{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "foundations-codex-primitives-field-guide",
  "slug": "codex-primitives-field-guide",
  "title": "Codex Primitive Field Guide",
  "summary": "AGENTS.md, skills, plugins, hooks, MCP, and Goal mode without mixing the layers.",
  "category": "Tools",
  "tags": [
    "field guide",
    "codex primitives"
  ],
  "sources": [
    {
      "label": "Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-07.html"
    },
    {
      "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
    }
  ],
  "sourceUnits": [
    "field-guides/guides.mjs#codex-primitives/overview",
    "field-guides/guides.mjs#codex-primitives/quote",
    "field-guides/guides.mjs#codex-primitives/decision",
    "field-guides/guides.mjs#codex-primitives/agentPrompt",
    "field-guides/guides.mjs#codex-primitives/stories",
    "field-guides/guides.mjs#codex-primitives/tips",
    "field-guides/guides.mjs#codex-primitives/refs"
  ],
  "collection": "foundations",
  "categoryId": "tools",
  "wordCount": 567,
  "url": "/topics/foundations-codex-primitives-field-guide/",
  "markdownUrl": "/markdown/foundations-codex-primitives-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/foundations-codex-primitives-field-guide.json",
  "headings": [
    {
      "id": "choose-the-right-mechanism",
      "text": "Choose the right mechanism",
      "level": 2
    },
    {
      "id": "agent-ready-prompt",
      "text": "Agent-ready prompt",
      "level": 2
    },
    {
      "id": "applied-stories",
      "text": "Applied stories",
      "level": 2
    },
    {
      "id": "next-js-monorepo-guardrails",
      "text": "Next.js monorepo guardrails",
      "level": 3
    },
    {
      "id": "browser-proof-skill",
      "text": "Browser proof skill",
      "level": 3
    },
    {
      "id": "checkout-stop-hook-gate",
      "text": "Checkout Stop-hook gate",
      "level": 3
    },
    {
      "id": "tips-and-gotchas",
      "text": "Tips and gotchas",
      "level": 2
    },
    {
      "id": "references",
      "text": "References",
      "level": 2
    },
    {
      "id": "related-principles",
      "text": "Related principles",
      "level": 2
    }
  ],
  "markdown": "# Codex Primitive Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nAGENTS.md, skills, plugins, hooks, MCP, and Goal mode without mixing the layers.\n\nUse this when a workflow keeps failing because instructions, tools, and enforcement are all living in the same prompt.\n\n> Skills use progressive disclosure to manage context efficiently.\n\n[OpenAI Codex Skills docs](https://developers.openai.com/codex/skills)\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| AGENTS.md | Stable repo or directory rules | Setup, commands, conventions, done criteria | Short instruction file near the code |\n| Skill | Reusable workflow with judgment | Browser proof, release notes, Oracle handoff | .agents/skills/<name>/SKILL.md |\n| Plugin | Shareable installable bundle | Team workflow with skills, MCP, apps, hooks | .codex-plugin/plugin.json plus bundled folders |\n| Hook | Lifecycle enforcement | Prompt injection, tool policy, Stop receipt gate | hooks/hooks.json plus small scripts |\n| MCP | External systems and context | Browser, Figma, docs, DB, SaaS tools | .mcp.json plus tool policy |\n| Goal mode | Long-running objective | Research, plan, implement, verify loop | .goals/<task>.md plus receipts |\n\n## Agent-ready prompt\n\n```text\nCreate a Codex primitive map for this repo.\nRead AGENTS.md, package scripts, existing skills/plugins/hooks, and MCP config first.\nFor each repeated workflow, decide whether it belongs in AGENTS.md, a skill, a plugin, a hook, MCP, or a goal file.\nWrite .notes/codex-primitives/decision.md with the decision, files to create, verification command, and rollback path.\n```\n\n## Applied stories\n\n### Next.js monorepo guardrails\n\n**Role:** Platform lead\n\nAgents keep running the wrong tests and claiming UI work is done without proof.\n\n**Agent brief:** Ask Codex to create a root AGENTS.md under 120 lines, copy commands from package scripts or CI, and add browser-proof expectations for UI work.\n\n**Done when:**\n\n- AGENTS.md exists\n- Commands match real scripts\n- Codex can summarize loaded instructions\n- No one-off task details\n\n### Browser proof skill\n\n**Role:** SaaS frontend engineer\n\nEvery UI fix needs the same route, viewport, action, console, screenshot, and command receipt.\n\n**Agent brief:** Ask Codex to create .agents/skills/browser-proof-saas/SKILL.md with clear trigger and non-trigger language.\n\n**Done when:**\n\n- SKILL.md has name/description\n- Proof schema is included\n- Smoke prompt exists\n- Skill says when not to use it\n\n### Checkout Stop-hook gate\n\n**Role:** Checkout owner\n\nAgents stop after one validation fix instead of proving cart to confirmation.\n\n**Agent brief:** Ask Codex to scaffold a local plugin with a Stop hook that continues until checkout test and browser receipts exist.\n\n**Done when:**\n\n- Manifest validates\n- Hook simulator covers missing/success/cap\n- Receipts are named\n- No global install before simulation\n\n## Tips and gotchas\n\n- Keep AGENTS.md short. Put workflow machinery in skills/plugins/hooks.\n- Treat a skill as guidance, not enforcement. Move deterministic checks to hooks.\n- Use current Codex Stop-hook behavior: return decision: \"block\" with a reason to continue the turn.\n- Installing a plugin does not automatically make plugin hooks trusted. Teach users to review and trust hook definitions.\n- Use MCP for external stateful systems; use local package scripts for repo-local tests and builds.\n\n## References\n\n- [OpenAI Codex Skills](https://developers.openai.com/codex/skills)\n- [OpenAI Codex Plugins](https://developers.openai.com/codex/plugins)\n- [OpenAI Codex Hooks](https://developers.openai.com/codex/hooks)\n- [OpenAI AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)\n- [AGENTS.md standard](https://agents.md/)\n- [Better Plugins examples](https://github.com/johnlindquist/better-plugins/tree/main/plugins)\n\n## Related principles\n\n- [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/)\n- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)"
}
