Set up a repository

This is the target layout for a repository that supports both Codex and Claude Code. Add only the files required by actual workflows; empty scaffolding creates maintenance without capability.

Reference tree

repo/
├── AGENTS.md
├── CLAUDE.md
├── docs/
│   ├── README.md
│   ├── architecture/
│   ├── design-docs/
│   ├── product-specs/
│   ├── generated/
│   ├── quality/
│   ├── standards/
│   ├── runbooks/
│   └── plans/
│       ├── active/
│       ├── completed/
│       └── tech-debt.md
├── scripts/
│   └── agent/
│       ├── verify
│       └── changed-scope
├── .agents/
│   ├── skills/
│   │   └── verify-change/
│   │       ├── SKILL.md
│   │       ├── agents/openai.yaml
│   │       ├── scripts/
│   │       ├── references/
│   │       └── assets/
│   └── plugins/
│       └── marketplace.json
├── .claude/
│   ├── settings.json
│   ├── rules/
│   └── skills/
│       └── verify-change/
├── .codex/
│   ├── config.toml
│   ├── hooks.json
│   ├── hooks/
│   └── rules/
│       └── default.rules
└── plugins/
    └── example-plugin/
        ├── .codex-plugin/plugin.json
        ├── .claude-plugin/plugin.json
        ├── skills/
        ├── hooks/hooks.json
        ├── .mcp.json
        ├── .app.json
        ├── agents/
        ├── .lsp.json
        ├── monitors/monitors.json
        ├── bin/
        ├── settings.json
        └── assets/

File-by-file responsibilities

`AGENTS.md`

Codex’s durable repository map. Include only repository purpose and shape, universal constraints, canonical environment and verification commands, mandatory if/then workflow triggers, and links to canonical docs. Codex builds an instruction chain from global through root and nested AGENTS.md files; closer files apply to their subtree.

Do not copy full standards, tutorials, or large examples into this file. When a review exposes a persistent incorrect assumption, correct the canonical doc and the smallest routing statement needed here.

`CLAUDE.md`

Claude Code’s repository map. When the shared content is identical and every required checkout, package, and operating system preserves symlinks, make CLAUDE.md a relative symlink to AGENTS.md. Otherwise keep CLAUDE.md as a small routing file that points to AGENTS.md and adds only Claude-specific launch-directory or settings behavior. Do not maintain two independent copies of shared policy. Nested CLAUDE.md files belong with subsystem owners. Anthropic recommends keeping root instructions below roughly 200 lines and moving specialised procedures into skills.

Do not rely on identical discovery semantics: Claude loads nested instructions when it reads into directories, while product settings have separate scope and inheritance behavior.

`docs/README.md`

The repository knowledge index. Link architecture, product behavior, standards, runbooks, plans, and generated references. Each execution-critical document should have an owner or owning area, an update trigger, and links from its parent index. Root instruction files should route here instead of duplicating the content.

OpenAI’s reported structure separates architecture, indexed design documents, product specifications, generated references, active and completed plans, technical debt, and discipline guides for design, frontend, product sense, quality, reliability, and security. Repositories can choose different names, but those responsibilities must remain discoverable rather than collapsing into an unowned docs/ pile.

`docs/architecture/`

System boundaries, dependency direction, data flow, and architectural decisions. Prefer mechanically checkable invariants and error messages that explain remediation. Keep diagrams and prose close to the code or schema that can verify them.

`docs/design-docs/` and `docs/product-specs/`

Design documents record important technical choices, verification status, and the core beliefs that guide future decisions. Product specifications define observable behaviour and acceptance boundaries. Each collection needs an index, status, owner, and supersession path.

`docs/generated/`

Machine-produced references such as database schemas. Every artifact declares its editable source, generation command, and freshness check. Agents inspect or regenerate these files but do not patch them as the source of truth.

`docs/quality/`

Quality state by product domain or architectural layer, including known gaps, reliability and security expectations, and the evidence used to update a grade. Keep aspirational principles separate from measured status.

`docs/standards/`

Adopted engineering policy, not research notes or candidate ideas. A standard should identify scope, owner, normative requirements, enforcement, exceptions, and review cadence. Candidate standards stay separate until approved.

`docs/runbooks/`

Operational procedures and incident/release knowledge. A skill may orchestrate a runbook, but the durable operational truth should remain readable and reviewable without invoking a model.

`docs/plans/active/<plan>.md`

Durable state for long, cross-package, or multi-session work. Record objective, scope, sequence, decisions, progress, changed artifacts, validation, blockers, and remaining work. Move completed plans rather than losing the decision trail.

Keep known technical debt beside active and completed plans or link it from the same index. This lets planning, cleanup, and current implementation decisions share one versioned context.

`scripts/agent/*`

Stable commands used by humans, skills, hooks, and CI. Each command should have documented inputs, focused stdout, diagnostic stderr, meaningful exit codes, idempotency expectations, and an artifact contract. Prefer affected-scope and failure-only modes to dumping logs into model context.

`.agents/skills/<name>/SKILL.md`

Codex repository skill entry point. It requires name and description and contains the focused workflow. Codex scans .agents/skills from the current working directory toward the repository root, so place root-wide skills at the root and narrow skills beside the applicable subtree.

The skill entry file is loaded into conversation state when invoked, so progressive disclosure does not remove its recurring token cost. Keep it navigational, write durable state to files, and test resumption after compaction.

`.agents/skills/<name>/agents/openai.yaml`

Optional Codex metadata for display, default prompt, implicit-invocation policy, and MCP dependencies. Set policy.allow_implicit_invocation: false for side-effecting or deliberately manual workflows. Declare required MCP tools so installation and runtime dependencies are visible.

Skill `scripts/`, `references/`, and `assets/`

Put deterministic helpers in scripts/, large or optional knowledge in references/, and templates or static resources in assets/. The entry file must say exactly when each support file is needed. Do not load the entire folder for every invocation.

`.claude/skills/<name>/`

Claude Code’s project skill location. Use the same Agent Skills-compatible core workflow where behavior is genuinely portable, with client-specific metadata or wrappers where invocation and tool controls differ.

For a dual-client repository, choose one source of truth and use a reviewed generation or mirroring check. Do not maintain two silently divergent copies. If using symlinks, verify support in every required environment and packaging path before standardizing them.

`.codex/config.toml`

Trusted-project Codex settings such as MCP servers, hooks, sandbox or approval defaults, and custom agents. Codex loads project config layers from repo root to working directory; the closest value wins. Relative paths resolve from the containing .codex/ folder. Some credential, provider, profile, notification, and telemetry keys are intentionally user-only and ignored in project config.

Keep personal auth and machine-specific preferences in ~/.codex/config.toml. Never commit secrets.

`.codex/hooks.json`

Repository lifecycle configuration. Prefer this file over inline hooks when multiple hooks would make config.toml hard to review. Codex merges matching hooks from active layers rather than replacing them, and project hooks run only after the project and the exact hook definitions are trusted.

Store implementations under .codex/hooks/, invoke them with a git-root-based absolute resolution, parse JSON input, and return the event’s documented JSON or exit-code contract.

`.codex/rules/default.rules`

Codex command policy for actions requested outside the sandbox. Use tested prefix_rule() entries with allow, prompt, or forbidden, human-readable justification, and match/not_match examples. Codex applies the most restrictive matching decision. Rules are currently experimental, so keep a small test suite and review release changes.

`.claude/settings.json`

Claude Code project settings for permissions, hooks, exclusions, and related client behavior. A package-level settings file must be self-contained; it does not inherit from a parent like CLAUDE.md. Keep worktree and package launch behavior in mind when deciding where it belongs.

`.claude/rules/*.md`

Path-scoped Claude guidance for conventions that apply to defined file globs, especially when relevant files are spread across packages. Use nested CLAUDE.md for subsystem ownership and path rules for cross-cutting file classes. These are instructions, not command-security policy.

`.agents/plugins/marketplace.json`

Optional repository catalogue for installable Codex plugins. It describes where packages come from; it is not the package itself. Pin or version remote sources, review publisher metadata, and treat every update as executable supply chain input.

`plugins/<name>/.codex-plugin/plugin.json`

Required Codex plugin manifest. It identifies name, version, description, publisher and interface metadata, and relative paths to skills, MCP servers, apps, or hooks. Only this manifest belongs inside .codex-plugin/; components remain at the plugin root.

`plugins/<name>/.claude-plugin/plugin.json`

Claude Code plugin manifest for the same cohesive capability when dual-client distribution is required. Keep version and ownership aligned while allowing component declarations to reflect actual Claude support rather than pretending the manifests are interchangeable.

Claude’s manifest can be omitted when all components use default locations, but a distributed EOS plugin should normally keep one for stable identity, ownership, and versioning. Claude-specific components can include agents/, .lsp.json, monitors/monitors.json, bin/, and settings.json; at the time reviewed, plugin settings support only agent and subagentStatusLine.

Plugin `skills/`

The portable workflow layer. A plugin is an appropriate home only after local use has stabilized the routing, outputs, scripts, and safety expectations. Plugin skill names are part of the installed public interface; avoid unrelated workflows in one namespace.

Plugin `hooks/hooks.json`

Lifecycle automation shipped with the plugin. Both products can use this convention, but their supported handler types, events, output contracts, trust, and interception coverage differ. Share deterministic scripts where possible and keep client configuration explicit.

Plugin `.mcp.json` and `.app.json`

.mcp.json declares bundled MCP server configuration. OpenAI accepts a direct server map or a wrapped mcp_servers object. .app.json maps a Codex plugin to one or more ChatGPT apps/connectors. Review authentication and tool authority separately from the skill that calls them.

Plugin `assets/`

Icons, logos, screenshots, templates, and presentation resources. Keep runtime code out of this directory and validate asset paths from the manifest.

Minimum viable setup

For a repository starting from zero, create only:

short AGENTS.md and/or CLAUDE.md maps;
docs/README.md with the existing sources of truth;
one canonical verification command under the normal package scripts or scripts/agent/;
one local skill only when a repeated procedure cannot be expressed by that command and a short instruction;
native permissions and CI before adding automatic hooks.

Add .codex/, .claude/, marketplaces, and plugins only for demonstrated needs. Every added layer increases discovery, trust, compatibility, and maintenance cost.

Minimal starter contents

These examples show the intended division of responsibility. Replace commands and links with repository facts; do not copy placeholders into production.

Root `AGENTS.md`

# Repository instructions

## Map

- Start at `docs/README.md`.
- Architecture lives under `docs/architecture/`.
- Adopted policy lives under `docs/standards/`.
- Save long-running plans under `docs/plans/active/`.

## Environment

- Install: `<canonical install command>`
- Verify changed scope: `scripts/agent/verify`

## Required workflows

- If runtime behavior, tests, examples, or build output changes, invoke the
  `verify-change` skill and do not report completion until applicable checks
  pass.

## Safety

- Do not commit secrets or edit generated output directly.
- Ask before destructive or externally visible actions.

Root `CLAUDE.md`

Prefer the zero-drift form when the supported environments preserve it:

ln -s AGENTS.md CLAUDE.md

Otherwise use a small routing file with only necessary client-specific facts:

# Repository instructions

Follow `docs/README.md` as the knowledge index.

## Claude Code specifics

- Start at the repo root for cross-package changes and at the package for
  package-only work.
- Package `.claude/settings.json` files are self-contained.
- Use package-local `CLAUDE.md` for subsystem-only conventions.

Starter `docs/README.md`

# Documentation map

| Need               | Source          | Owner       | Update          |
| ------------------ | --------------- | ----------- | --------------- |
| Boundaries         | `architecture/` | Platform    | Boundary change |
| Engineering policy | `standards/`    | Engineering | Standard change |
| Operations         | `runbooks/`     | Services    | Ops change      |
| Active work        | `plans/active/` | Plan author | Every session   |

Starter `.codex/config.toml`

Begin empty unless a trusted-project setting is required. A project MCP server might look like:

[mcp_servers.project_docs]
command = "scripts/agent/docs-mcp"
args = ["--stdio"]
cwd = "."

Keep authentication, providers, profiles, personal notification commands, and telemetry in user or managed configuration. Verify relative-path behavior from the containing .codex/ directory before relying on it.

Starter `.codex/hooks.json`

Start with no hooks. When an event-driven requirement is proven, add one narrow handler and place its implementation under .codex/hooks/. See the hook contract and example.

Starter `.codex/rules/default.rules`

Start with the platform sandbox and approval defaults. Add only reviewed command prefixes, with inline match and not_match tests, when a repeated approval or denial has a stable boundary. See Codex command rules.

Starter `.claude/settings.json`

Start with the smallest valid object and add only proven project settings:

{}

Add permissions, exclusions, and hook configuration deliberately. Test the effective file from every supported package and worktree launch location.

Repo skill `SKILL.md`

---
name: verify-change
description:
  Verify runtime, test, example, or build-output changes. Do not use for
  prose-only documentation changes.
---

1. Determine the changed packages and change class.
2. Read `references/verification-matrix.md` for the applicable checks.
3. Run `scripts/run-verification` with the affected scope.
4. Diagnose failures; do not hide or bypass them.
5. Report commands, results, skipped checks with reasons, and remaining risk.

Use the same contract under .agents/skills and .claude/skills through the repository’s declared source/mirroring strategy.

Setup verification

Launch each supported client from the repo root and a representative subdirectory; record which instructions, skills, settings, and hooks load.
Verify the CLAUDE.md symlink or routing file in every supported checkout, archive, plugin packaging path, and operating system.
Check documentation indexes, internal links, ownership, generated-reference freshness, and active-plan status in CI or scheduled maintenance.
Invoke every required skill explicitly and test representative implicit positive, negative, and ambiguous prompts.
Test hook scripts directly with fixture JSON, then through the client event.
Run codex execpolicy check for every Codex rule example.
Verify project config is ignored in an untrusted checkout and enabled only after trust is granted.
Run the same verification scripts locally and in CI.
Inspect a packaged plugin in a clean environment and confirm every manifest path, dependency, hook trust prompt, and uninstall path.
For libraries and CLIs, install the produced package into a consumer-realistic environment rather than relying only on in-repository tests.

Set up a repository

Reference tree

File-by-file responsibilities

AGENTS.md

CLAUDE.md

docs/README.md

docs/architecture/

docs/design-docs/ and docs/product-specs/

docs/generated/

docs/quality/

docs/standards/

docs/runbooks/

docs/plans/active/<plan>.md

scripts/agent/*

.agents/skills/<name>/SKILL.md

.agents/skills/<name>/agents/openai.yaml

Skill scripts/, references/, and assets/

.claude/skills/<name>/

.codex/config.toml

.codex/hooks.json

.codex/rules/default.rules

.claude/settings.json

.claude/rules/*.md

.agents/plugins/marketplace.json

plugins/<name>/.codex-plugin/plugin.json

plugins/<name>/.claude-plugin/plugin.json

Plugin skills/

Plugin hooks/hooks.json

Plugin .mcp.json and .app.json

Plugin assets/