Agent Spine

Codex-native operating layer for agent-ready repositories, with an optional Claude Code adapter.

Agent Spine gives a repository one canonical AGENTS.md, a native .codex/ control plane, reusable .agents/skills/, and optional adapters for tools like Claude Code that do not own the core contract.

Maintained by @netskydevel.

What This Gives You

• AGENTS.md as the repo-wide instruction contract
• a documented target surface for .codex/ and .agents/skills/
• project-scoped Codex defaults in .codex/config.toml, native subagent definitions in .codex/agents/, and deterministic lifecycle hooks in .codex/hooks.json
• a cognitive operating system for R&D and production agent workflows
• quality metrics for evaluating whether agent work is inspectable, verified, and safe
• shared-brain docs for architecture, rollout, migrations, and release gates
• Claude Code compatibility through optional .claude/ settings, hooks, auth helpers, and agent examples behind a clear adapter boundary
• example adaptation notes for Python, Node.js/TypeScript, monorepos, and fullstack products

Shared Brain

Read these files in order when working on the template itself:

1. AGENTS.md
2. ROADMAP.md
3. ARCHITECTURE.md
4. docs/GETTING_STARTED.md
5. docs/TEMPLATE_CONTRACT.md
6. docs/COGNITIVE_OPERATING_SYSTEM.md
7. docs/QUALITY_MODEL.md

These files define the contract. Other docs should defer to them.

Canonical Contract

The intended long-term surface of the template is:

AGENTS.md                  Canonical operational rules
ARCHITECTURE.md            Target system layout and boundaries
ROADMAP.md                 Rollout phases and migration sequencing
.codex/                    Native Codex config, hooks, and subagents
.agents/skills/            Reusable skills and shared-brain workflows
docs/COGNITIVE_OPERATING_SYSTEM.md
                           R&D and production operating model
docs/QUALITY_MODEL.md      Agent quality metrics
.claude/                   Optional Claude adapter
CLAUDE.md                  Optional Claude shim

Quick Start

1. Copy this template into a new repository.
2. Run ./scripts/bootstrap-template.sh <project-name> <python|node-typescript|monorepo|fullstack-product> [keep-claude|drop-claude].
3. Edit AGENTS.md so the rules match your real engineering workflow.
4. Review ROADMAP.md and ARCHITECTURE.md, then remove template-only phases you do not need.
5. Run ./scripts/verify-template.sh --fast.
6. Run ./scripts/verify-template.sh --full before publishing template changes.

Current Repository State

This repository now reflects the post-migration Codex-native contract:

• AGENTS.md, ROADMAP.md, ARCHITECTURE.md, and docs/TEMPLATE_CONTRACT.md define the true contract
• .codex/config.toml, .codex/agents/, and .codex/hooks.json are the committed Codex-native config surface that Codex loads after the repository is trusted
• .claude/ remains an optional adapter example
• .codex/hooks/ contains repo-local safety, audit, and prompt-context scripts wired through hooks.json
• .codex/agents/ contains the native reviewer, coordinator, test-writer, and security-auditor role configs that replaced the earlier legacy role briefs
• .agents/skills/ contains reusable task-kickoff, handoff, review-request, research-brief, decision-record, production-change, and incident-analysis workflows
• docs/COGNITIVE_OPERATING_SYSTEM.md, docs/QUALITY_MODEL.md, and docs/DEMO.md explain how the template should behave in real R&D and production sessions

Use the roadmap and shared-brain docs rather than historical directory names to understand where the template is going.

Skills Vs Subagents

Use .agents/skills/ for reusable workflows and promptable operating patterns that any agent may invoke on demand.

Use .codex/agents/ for bounded execution roles with their own model, sandbox, and responsibility defaults.

In this template:

• task kickoff, handoff, review-request, research-brief, decision-record, production-change, and incident-analysis patterns are skills because they are workflow scaffolds, not long-lived agents
• reviewer, coordinator, test-writer, and security-auditor stay in .codex/agents/ because they define execution posture for delegated work

R&D And Production Modes

Use R&D mode when the answer is uncertain and the useful output is evidence, confidence, and the next experiment.

Use production mode when durable behavior changes and the useful output is a narrow diff, verification, rollout clarity, rollback clarity, and residual risk.

The operating model is documented in docs/COGNITIVE_OPERATING_SYSTEM.md. The measurement model is documented in docs/QUALITY_MODEL.md.

Compatibility boundaries are documented in docs/COMPATIBILITY_MATRIX.md.

What Good Agent Work Leaves Behind

A good agent session should leave more than a diff:

• clear task framing
• evidence from inspected repository files
• narrow implementation scope
• focused verification
• review or risk notes when needed
• a handoff or durable artifact for the next worker

Agent Spine makes those outputs part of the repository contract instead of relying on memory or chat history.

Codex Config And Hooks

The native .codex/ layer is intentionally explicit and reviewable:

• .codex/config.toml sets a project-scoped untrusted approval posture, workspace-write sandboxing, enables Codex hooks, and registers native subagent roles
• .codex/agents/ stores the role-specific TOML config layers for the reviewer, coordinator, test writer, and security auditor subagents
• Codex only applies repo-local .codex/ overrides after the repository is trusted, so the committed files are visible and reviewable without depending on hidden local state
• .codex/hooks.json wires repo-local scripts from the git root so hooks still resolve when Codex starts in a subdirectory
• .codex/hooks/pre_tool_use_policy.py blocks dangerous shell commands and access to .env, credential files, private keys, and secrets/
• .codex/hooks/post_tool_use_audit.py and .codex/hooks/stop_audit.py append JSONL audit records under ignored .codex/logs/
• .codex/hooks/user_prompt_submit_context.py injects the same minimal project context that the Claude adapter previously added

This is the security-sensitive native automation surface for the template. If a repo-wide safety rule matters across agents, document it in the shared brain and enforce it from .codex/ first.

Claude Code Compatibility

Agent Spine includes an optional Claude Code adapter for teams that use both Codex and Claude Code.

The .claude/ directory is intentionally optional and downstream of the canonical contract.

• CLAUDE.md should stay short and defer to AGENTS.md
• .claude/settings.json should hold Claude-specific policy and hook wiring only
• existing auth remains valid for the adapter, including a normal claude login or ANTHROPIC_API_KEY
• .claude/settings.local.json should remain uncommitted, machine-specific, and only add optional local overrides such as apiKeyHelper
• apiKeyHelper is supported through the local example and wrapper scripts, but it is not mandatory for Claude usage in this repo
• Claude agents and hooks should mirror the canonical contract instead of redefining it
• deleting .claude/ and CLAUDE.md must leave the Codex-native core intact

Verification

Run:

./scripts/verify-template.sh
./scripts/smoke-test-bootstrap.sh

The verification layer currently checks:

• required template files exist
• .codex/config.toml and .codex/hooks.json parse and contain the expected Codex-native keys
• the configured Codex hooks are regression-tested, including pre-tool secret blocking, user-prompt context injection, and audit-only post-tool and stop flows
• the native .agents/skills/ files exist, include valid name and description frontmatter, and keep directory names aligned with discoverable skill names
• the required R&D and production operating docs are present
• optional Claude adapter files and local-auth helper scripts are complete if present, while machine-login auth remains valid without helper-only configuration
• committed docs do not contain repo-local absolute paths
• shell scripts are executable
• representative bootstrap scenarios still pass verification

CI runs the same checks through .github/workflows/verify-template.yml.

Governance

• use CHANGELOG.md for notable template changes
• use docs/MIGRATIONS.md when downstream repos need manual updates
• use docs/ADOPTION_CHECKLIST.md and docs/MIGRATION_PLAYBOOK.md for downstream rollout
• use docs/TEMPLATE_CONTRACT.md when the canonical surface or adapter boundary changes
• use SECURITY.md for security handling expectations

Contributing

If you evolve the template itself, follow CONTRIBUTING.md and keep structural changes aligned with scripts/verify-template.sh. Update ROADMAP.md, ARCHITECTURE.md, and the contract doc when the shared brain changes.