A persistent, repo-local operating contract that guides AI coding agents — Codex, Claude Code, and more — across the whole software lifecycle: design → planning → governed execution → verification → review → outcome evidence → handoff.
AgentSpec turns your design docs into a governed, file-based operating contract for AI coding agents. The contract lives in your repo — accepted requirements, scoped tasks, allowed file paths, iteration limits, verification commands, and review evidence — all version-controlled. No external service or database is required for the AgentSpec core. Optional adapters can submit facts from browsers, CI, observability, deployment, and release systems without giving those systems authority to declare an outcome ready.
AgentSpec actively governs every lifecycle boundary: it supplies the task, allowed paths, verification expectations, review requirements, and durable finish evidence while Codex or Claude Code executes in its native workflow. For hosts without that capability, AgentSpec can package each instruction and validate structured results through its generic runner fallback. You can stop a project mid-flight, come back days later, and continue from the repo — not from chat history.
Design doc → Accepted spec → Scoped task pack ──┐
│
┌───────────────────────┘
▼
Provider-native workflow (AgentSpec task + policy + evidence boundary)
│
▼
Verify → Review → Finish → Outcome readiness
(policy and evidence written back to the repo)
AI coding agents are powerful, but the day-to-day pain is familiar:
- Context evaporates — every session you re-paste the design, the conventions, the "don't touch that folder" rules.
- Scope creep — the agent helpfully refactors a file you didn't ask it to.
- No paper trail — you can't tell whether tests actually ran, what was reviewed, or what the next person should pick up.
- Drift — the design doc says one thing, the code does another, and nobody notices until production.
- False finishes — a task is marked complete even though the browser journey, API contract, deployment, or service objective is still broken.
AgentSpec fixes this by keeping the operating contract — what is canonical, what is in scope, what counts as verified, how many iterations remain — in the repository itself, and re-asserting it on every step. A new agent (or a new teammate) can resume work without reading chat history.
Stable release (recommended):
pip install "git+https://github.com/yimwoo/agent-spec.git@v0.1.43"Latest from main (dev):
pip install "git+https://github.com/yimwoo/agent-spec.git@main"Requires Python 3.11+. Installs aspec and agentspec as console scripts.
Verify:
aspec --helpThe plugin teaches Codex or Claude Code how to call AgentSpec safely. The
aspec CLI is still the source of truth — the plugin is a thin adapter that
turns natural-language requests into aspec invocations.
Codex
# Stable installer. The script defaults to the release-pinned plugin v0.1.43.
curl -fsSL https://raw.githubusercontent.com/yimwoo/agent-spec/main/install.sh | bashThe installer defaults to the release-pinned plugin v0.1.43, verifies it
against an installed AgentSpec CLI, and stops with repair guidance if the
versions differ. To test the development plugin intentionally, pass
--ref main; use --allow-version-mismatch only for explicit compatibility
testing.
curl -fsSL https://raw.githubusercontent.com/yimwoo/agent-spec/main/install.sh \
| bash -s -- --ref mainThen enable the plugin:
codex
/plugins
Choose the local marketplace, open aspec, select Install plugin. In the
Codex desktop app, restart and enable aspec under Plugins > Local Plugins.
Claude Code
/plugin marketplace add yimwoo/agent-spec
/plugin install aspec@agentspec
Open your repository, then prompt your agent.
Bootstrap a new project:
Use AgentSpec to initialize this repository. The design source is at
docs/source/design.md. Set up Codex and Claude agent guidance, compile the requirements, report readiness and open questions, and propose the first task context packs.
Continue an existing project:
Use AgentSpec to continue this repository. Read
AGENTS.md, run project status, pick the next ready task pack, execute it in the host's native workflow, record review evidence, finish the task, and refresh roadmap + handoff.
Behind the scenes, the agent runs a CLI sequence like:
aspec init → aspec ingest → aspec compile → aspec task create
→ aspec plan → session preflight ──► (Codex/Claude executes natively)
→ run the task pack's verification commands
→ aspec review code → aspec finish
The agent reports back: requirement IDs touched, task pack path, allowed paths, iteration count, verification commands and results, review ID, and updated handoff/roadmap state.
When a repository keeps agent/ runtime state private, AgentSpec mirrors both
completed tasks and explicitly recorded non-terminal states into the tracked
docs/release/evidence.yml projection. Use aspec task state T-123 --status blocked --reason "..." (or in_progress, paused, or halted) so status,
task listing, and roadmap generation do not mistake blocked work for an idle
project; completing the task replaces that state with final verification and
review evidence.
AgentSpec is more than a wrapper around before and after. During a task,
it supplies the governance contract while Codex Goal/workflow or Claude
/loop/dynamic workflows own provider-native execution. The native agent must
still honor the task pack, session lease, allowed paths, verification, review,
and finish write-back.
Enforcement is layered deliberately:
- Trusted provider hooks can evaluate session state, policy, scope expansion, stop verification, and finish evidence before or after native tool events. Hooks must be supported, enabled, and trusted in the host.
- AgentSpec lifecycle commands enforce session, verification, review, and finish requirements regardless of which agent performed the implementation.
- The generic runner fallback validates structured package/result boundaries when provider-native execution is unavailable.
- The host sandbox and permissions remain the hard process boundary; AgentSpec never auto-approves a tool call or replaces OS isolation.
When the host cannot provide that workflow, AgentSpec exposes a portable generic fallback:
- A runner package (
aspec run package) containing the next executor prompt, the active context pack, the iteration counter (e.g. 3 of 5), allowed and forbidden paths, and the expected result schema. The agent reads this — not free-form chat — to know what to do next. - The agent executes one step, then submits structured results back via
aspec run result. - AgentSpec validates the result against policy: touched paths against
the allowlist, iteration count against
max_iterations, destructive git operations, credential leakage, missing tests. - AgentSpec decides whether to continue (next runner package), halt (budget exhausted, policy violation), or hand off for review.
aspec run package and aspec run result are the stable provider-neutral
bridge. aspec run loop and aspec run exec remain compatible fallback
commands; they are no longer the preferred execution path.
What the agent receives in a task context pack is itself a contract:
- Goal — the requirement the task implements.
- Requirements — linked
R-###IDs with priority and confidence. - Source sections — the design snippets that justify scope.
- Allowed paths — whitelist of files the task may edit, each marked
confirmedorinferred. - Forbidden paths — explicit boundaries.
- Tests to add or update — verification targets.
- Acceptance criteria — definition of done.
The result: trusted hooks can reject an out-of-scope action before execution, while the generic fallback catches violations at its next result boundary. Iteration limits prevent runaway loops. Verification and review are required before finish. The contract survives session boundaries because it lives in the repo, not in the model's context window.
flowchart LR
A["Design intake<br/>(docs/source)"] --> B["Compile spec<br/>(requirements.yml)"]
B --> C["Create task pack<br/>(bounded scope)"]
C --> D["Plan workflow"]
D --> E["Provider-native execution<br/>(generic runner fallback)"]
E --> F["Verify<br/>(tests + checks)"]
F --> G["Review<br/>(evidence recorded)"]
G --> H["Finish<br/>(ledger + handoff + roadmap)"]
H --> I["Outcome readiness<br/>(browser + SLO + API + deploy + release)"]
I -.->|next task| C
AgentSpec defines 10 native lifecycle stages: brainstorm, design, plan,
branch start, execute, delegate, verify, review, branch finish, and
handoff recovery. Every stage writes evidence back to the repo. Interrupted?
The next session reads agent/handoff.yml and agent/runs/ and continues
from the right step.
For the full control-plane and execution architecture — adapter → CLI → source/spec → planning → governed execution → governance — see docs/GETTING_STARTED.md#how-the-pieces-fit.
Plugin install does not touch your project. Files appear only after
aspec init + aspec emit, which create AGENTS.md, CLAUDE.md,
.agentspec/, agent/ (context-pack and workflow templates, roles,
session/run directories, outcome definitions, and maturity defaults), docs/
(source, spec, traceability, ADR, DCR, and discovery scaffolding), and
reports/. Planning and execution later add task packs, reviews, the task
ledger, handoff, and docs/ROADMAP.md; hooks, outcome adapters, and controlled
evaluations add agent/hook-evidence/, agent/outcome-evidence/,
agent/evals/, and reports/eval/. See the full tree in
docs/GETTING_STARTED.md#files-added-to-target-repositories.
The core task terms — source snapshot, requirement, DCR, task context pack, workflow, execution strategy, runner fallback, handoff, and review evidence — are defined in the mental model. Outcome gates, observations, verdicts, and controlled evaluations are introduced below and specified in their linked guide sections.
Task completion proves that bounded implementation work passed its declared
checks and review. It does not prove that a user journey works or a deployment
is healthy. AgentSpec models those claims separately in agent/outcomes.yml
with typed command, browser_ui, slo, api_compatibility, deployment,
and release checks.
External adapters submit timestamped observations with provenance; they cannot
submit passed, status, or verdict. AgentSpec evaluates the policy and
writes the current verdict projection:
aspec outcome observe --input-file ./browser-observation.json --json
aspec outcome verify --json
aspec outcome --jsonDefinitions, observations, and verdicts remain separate so a model self-report or completed task cannot silently become production-readiness evidence. See Outcome Verification for the evidence contract and examples.
AgentSpec can compare the same fixed tasks with and without its governance across Codex and Claude. Versioned experiment manifests pin the task, oracle, model, environment, limits, and replicate. Immutable run evidence records completion, regressions, retries, human interventions, tokens, cost, duration, review findings, and escaped defects.
aspec eval validate agent/evals/EXP-lifecycle-001/manifest.yml --json
aspec eval record agent/evals/EXP-lifecycle-001/manifest.yml \
--input-file ./run-evidence.json --json
aspec eval report agent/evals/EXP-lifecycle-001/manifest.yml --jsonAgentSpec does not launch the providers for these experiments. Each cell runs through the provider's normal workflow and security controls; AgentSpec records and compares only compatible evidence. Missing data is reported as limited, not converted into a favorable result. See Controlled Agent Evaluations.
AgentSpec is a contract and a harness, not a guarantee. Out of scope:
- It does not replace code review. It records review evidence and gates finish on it; humans (or other agents) still judge correctness.
- It does not guarantee correctness. Verification gates run the tests you define — they don't know what you forgot to test.
- It does not sandbox the agent at the OS level. Trusted native hooks can deny an out-of-scope request before a matching tool executes, and the fallback runner validates result boundaries, but AgentSpec does not control arbitrary agent processes. Pair it with host or OS sandboxing for hard isolation.
- It does not host project data. All state lives in your repo's files. No external service, account, or database is required or used.
AgentSpec stores all state in repo-local files. Treat imported design docs,
candidate snapshots, and task packs as untrusted content (the pack
template explicitly marks design excerpts UNTRUSTED SOURCE CONTENT). Agents
should operate within AGENTS.md, allowed paths, and review gates. Review
DCRs and external imports before promoting them to accepted source.
- docs/GETTING_STARTED.md — full human guide: exact CLI sequences, control-plane and execution architecture, importing changing sources, provider-native workflows, fallback runners, native hooks, outcome verification, controlled evaluations, and recovery commands.
- docs/release/README.md — public completion, verification, review evidence, private-state cleanup, and release checks.
- agentspec/ — CLI source:
run.pyandrunner.py(generic fallback),policy.pyandhooks.py(lifecycle enforcement),outcome.py(typed product evidence),eval.py(controlled comparisons),task.py(context packs), andlifecycle.py(10 native stages). - agentspec-codex-plugin/ — Codex adapter.
- agentspec-claude-plugin/ — Claude Code adapter.
git clone https://github.com/yimwoo/agent-spec.git
cd agent-spec
pip install -e .
python -m pip install "build>=1.2,<2" "mypy>=1.10,<2" \
"pylint>=3,<4" "pytest>=8,<9" "twine>=6,<7"
python -m pytest -q
python -m compileall -q agentspec tests
python -m mypy
python -m pylint agentspec
python -m build
python -m twine check dist/*Or run the CLI without installing console scripts:
python -m agentspec.cli --helpAgentSpec is released under the MIT License. See LICENSE for the full license text.
Keywords: AI coding agent · spec-driven development · agent operating contract · agent execution harness · Codex plugin · Claude Code plugin · agent governance · repo-local memory · lifecycle hooks · outcome verification · agent evaluation · supervised AI agent · iteration-bounded agent · LLM development workflow · AI pair programming · agent control plane