Agentic engineering setup guide

This guide turns OpenAI and Anthropic’s published guidance into a practical repository setup. It explains which customization surface to use, how the surfaces compose, where every file belongs, and what must be tested before a workflow is shared.

The main guides contain the usable recommendations. The sources/ directory is supporting evidence, not the place a team should have to reconstruct the setup.

Recommended reading order

1. Choose the right surface to decide whether a need belongs in instructions, documentation, a skill, script, hook, rule, plugin, MCP server, subagent, or runtime integration.
2. Set up a repository for the target file tree and the responsibility of every file.
3. Use the component guides when implementing:
   • Skills
   • Plugins
   • Hooks, rules, and permissions
   • MCP, tools, and subagents
4. Use Context, scope, and cost and Harnesses and long-running agents when operating at monorepo or runtime scale.
5. Review candidate standards before converting this guidance into adopted EOS policy.
6. Use the adoption checklist when implementing or promoting a workflow.

Setup sequence

0. Baseline: current quality, cost, and failure modes are measurable from usage data, CI history, and review feedback.
1. Map: every agent can orient itself without loading a manual by using AGENTS.md, CLAUDE.md, and docs/README.md.
2. Make commands executable: build and verification mechanics have stable interfaces through scripts/agent/*, package scripts, and CI.
3. Add workflows: repeated judgement and procedures load on demand from .agents/skills/* and .claude/skills/*.
4. Add automatic controls: lifecycle checks and command policy run deterministically through .codex/hooks.json, .codex/rules/*, and .claude/settings.json.
5. Connect systems: external data and actions have explicit tool boundaries in .codex/config.toml, plugin .mcp.json, and skill dependency metadata.
6. Package: stable capabilities can be installed and versioned through plugins/*/.codex-plugin/plugin.json and marketplace catalogues.
7. Evaluate: routing, outcomes, safety, cost, and drift are measured through skill evaluations, hook fixtures, CI, and ownership metadata.
8. Maintain: documentation and code drift are removed continuously through freshness checks, quality grades, and focused cleanup tasks.

Do not begin with a plugin or a large root instruction file. Begin with the smallest local mechanism that proves the workflow, then promote it when its scope and release boundary are understood.

The expected result is not “more agent files.” It is a repository where an agent can discover the right knowledge, run the right checks, observe the result, preserve evidence, and stop or escalate at a defined boundary.

Shared operating model

The reviewed material converges on these layers:

1. A small map is always available. Root instructions identify the repository, universal constraints, canonical commands, and deeper sources.
2. Detailed knowledge loads on demand. Focused docs, path-scoped guidance, and skills keep unrelated material out of context.
3. Mechanics are executable. Scripts, hooks, rules, linters, tests, and CI perform deterministic work; the model supplies contextual judgement.
4. Capabilities have separate trust boundaries. Shell, filesystem, MCP, connectors, network, secrets, and approvals are reviewed independently.
5. Long work has durable state. Plans, artifacts, events, and resumable threads survive compaction and client disconnection.
6. Quality is measured and maintained. Routing, outcomes, cost, duration, failures, review feedback, documentation drift, and unused automation feed back into the repository.

Evidence and status

The source associations and article dossiers distinguish:

• Documented mechanism: what a product supports and how it behaves.
• Explicit recommendation: what the vendor tells users to do.
• Observed practice: what a vendor team reports doing in a particular context.

The implementation guidance combines those categories but calls out product-specific and experimental behavior. Candidate standards remain proposals until approved through the project’s decision process. Product interfaces change; the vendor-specific details were checked on 2026-07-13.