agent-spec

agent-spec is an intent compiler（意图编译器） for AI agent coding: it compiles human intent — through structured requirements as the intermediate representation (IR) — into verifiable Task Contracts, then mechanically verifies the implementation against them. BDD/spec verification is the backend of that compiler.

The compilation pipeline:

• intent (PRDs, issues, conversations) is captured as structured requirements — the IR
• requirements lower into Task Contracts — the verifiable target
• agents implement against the contract; the machine verifies the code satisfies it
• liveness tracing keeps compiled knowledge honest after the fact

The core review loop stays simple: humans review the contract, agents implement against the contract, the machine verifies whether the code satisfies the contract.

Architecture: the Intent Compiler

Current pipeline below; the detailed contracts for Requirement Governance, Code Graph IR, Intent-Code Linker, Quality Planning, and Execution Bundles live in docs/intent-compiler/architecture.md.

flowchart TD
    subgraph SRC["源 · Human Intent"]
        A["PRD · Issues · 对话"]
    end

    subgraph FE["前端 · Intake"]
        B["agent-spec-intent-compiler skill<br/>AI drafts Candidate Requirement Blocks,<br/>a human reviews and accepts"]
        C["agent-spec requirements import<br/>deterministic — marked blocks or YAML dialect"]
        CG{"Requirement Governance Gate<br/>proposed → accepted / rejected"}
    end

    subgraph IR["中间表示 · Requirement IR"]
        D["accepted knowledge/requirements/*.md<br/>REQ-* clauses · MUST / SHOULD / MAY"]
        E["lint-knowledge --gate<br/>EARS · ISO-29148 · governance"]
        F["requirements graph --gate<br/>dependency DAG validation"]
    end

    subgraph PIR["程序中间表示 · Code Graph IR"]
        P["Language code-intelligence providers<br/>Rust Atlas · F1 adapter kit · future F2 providers"]
        PG["derived project graph<br/>symbols · impls · references · calls"]
        P --> PG
    end

    subgraph ME["中端 · Lowering & Planning"]
        G["requirements work-units<br/>executable or blocked units"]
        X["Code Grounding / Intent-Code Linker<br/>REQ × work-unit × code bindings"]
        K["Task Contracts (specs/*.spec.md)<br/>satisfies: REQ-* · Boundaries · Symbols"]
        H["requirements plan --gate<br/>REQ × work-unit × spec DAG<br/>typed code bindings"]
        I["requirements test-obligations<br/>spec-derived, code-independent"]
        J["requirements worktrees<br/>parallel scheduling manifest"]
        QP["Quality Planning<br/>toolchain + required skills"]
        EB["Execution Bundle<br/>Contract + bindings + tools + skills"]
    end

    subgraph BE["后端 · Verifiable Target"]
        L["agent implements within Boundaries"]
        M["lifecycle: lint → structural →<br/>boundaries → bound tests"]
        QT["Quality providers<br/>clippy · rustfmt · deny · miri · third-party"]
    end

    subgraph LK["链接 · Liveness"]
        N["trace REQ-* --gate<br/>honored · violated · unproven"]
        O["agent-spec mcp<br/>read-only knowledge serving"]
    end

    A --> B --> C --> CG
    CG -->|accepted| D
    CG -->|rejected| R["historical, non-executable"]
    D --> E --> F --> G --> X --> K --> H --> QP --> EB --> L
    PG --> X
    PG --> M
    H -.-> I
    H -.-> J
    QT --> M
    L --> M --> N
    N -. "liveness recomputed from verdicts,<br/>never stored" .-> D
    D -.-> O
    F -.-> Q["requirements questions<br/>deterministic clarification prompts"]
    Q -. "human resolves ambiguity" .-> D

Loading

AI participates only at the edges — drafting candidate requirements and implementing contracts. Every gate in between (lint-knowledge, graph, plan, lifecycle, trace) is deterministic and model-free, and human acceptance sits at both ends: requirement review on the way in, Contract Acceptance on the way out.

The two IR tracks keep different facts separate: Requirement IR records what the system must do; Code Graph IR records what the current program is. The code graph is derived and rebuildable, while accepted KLL requirements remain the governed source of truth. A provider-neutral Intent-Code Linker grounds accepted work units in code without turning derived code facts into KLL truth. Quality Planning then resolves deterministic tools and required agent skills into an Execution Bundle. Skills guide generation; tool results provide acceptance evidence. See Intent Compiler Architecture for the target-state contracts, state machines, provider roles, and failure semantics.

The primary planning surface is the Task Contract, rendered by agent-spec contract.

Stability: the 1.0 promise

1.0 turns the surfaces below into a compatibility promise — breaking changes only with a major version:

• CLI commands and flags: init, parse, lint, contract, lifecycle, verify, guard, explain, stamp, matrix, audit, promote, discover, check-structure, gen-integrations, trace, lint-knowledge, mcp, plan, wiki *, atlas *, and the requirements family (import|export|transition|supersede|status|graph|work-units|plan| test-obligations|worktrees|draft-specs|questions|replay|explain-failure| trace-graph|traceability|verify-run|compile|bind|bundle|affected| affected-bundle|affected-record).
• Machine formats: lifecycle/verify JSON top-level keys, the five verdicts (pass, fail, skip, uncertain, pending_review) and is_passing semantics, schema $id URIs under agent-spec/intent-compiler/, the YAML dialect v1.1, compilation provenance manifests (v1 and the replayable v2 run manifests), the requirement-traceability projection, the compile bundle layouts (agent-spec-v1, arc-v1), the code-bindings and execution-bundle schemas, typed trace code targets, and the atlas graph schema_version.
• Governance semantics: the requirement state machine, the execution ladder, and derived (never stored) liveness.

Deprecation policy: deprecated surfaces keep working for one minor release with a notice, then leave at the next major. brief (legacy alias of contract) was deprecated in 0.4.0 and is now removed; contract renders the identical output.

What agent-spec doesn't solve

We want you to know up-front. These are real limits, not roadmap stubs:

• Cold-start product judgment. agent-spec verifies whether code satisfies a contract; it does not tell you whether the contract describes the right product. You still need product sense to write good Rules and Scenarios. A planned agent-spec discover --from-codebase (Phase 9) will help bootstrap a spec library from existing code + tests, but not from a blank page.
• Architectural taste at the line where it matters. Lint catches what's expressible in the DSL — boundaries, vague verbs, missing test bindings, dangling selectors. Naming clarity, abstraction choice, the line between "appropriate" and "inappropriate" coupling — these need human review or inferential AI review (Phase 5+).
• NFR ceiling. Functional behavior bound to cargo test is fully verifiable today. Performance, reliability, scalability — these need specialized runners (criterion, k6, external probes; planned Phase 7) and even then the honest verdict is often uncertain or pending_review, not pass.
• Test selector maintenance. The mechanical coverage matrix is the moat, but it comes with a cost: renaming a test function breaks the contract until you update the spec. Tooling can detect dangling selectors, it cannot rename them for you.
• False sense of security. A passing lifecycle means the contract was satisfied. It does not mean the contract was comprehensive. We recommend coupling agent-spec lifecycle with periodic human + AI architectural reviews (Phase 8 agent-spec audit will automate part of this).
• Approval identity and workflow. agent-spec provides deterministic compilation artifacts, stable machine formats, digests, and replay. Any orchestrator can insert human approval between compiler commands — but approval identity, authority, and workflow never enter the compiler core (ADR-001): a CLI cannot attest who approved, so it reports facts and digests for external systems to bind approvals to.

docs/comparison-openspec-speckit.md §9.4 expands these in context; docs/bdd-spine-end-state.md shows where each is addressed across Phases 1–9.

Task Contract

A task contract is a structured spec with four core parts:

• Intent: what to do, and why
• Decisions: technical choices that are already fixed
• Boundaries: what may change, and what must not change
• Completion Criteria: BDD scenarios that define deterministic pass/fail behavior

The DSL supports English and Chinese headings and step keywords.

Example

spec: task
name: "User Registration API"
tags: [api, contract]
---

## Intent

Implement a deterministic user registration API contract that an agent can code against
and a verifier can check with explicit test selectors.

## Decisions

- Use `POST /api/v1/users/register` as the only public entrypoint
- Persist a new user only after password hashing succeeds

## Boundaries

### Allowed Changes
- crates/api/**
- tests/integration/register_api.rs

### Forbidden
- Do not change the existing login endpoint contract
- Do not create a session during registration

## Completion Criteria

Scenario: Successful registration
  Test: test_register_api_returns_201_for_new_user
  Given no user with email "alice@example.com" exists
  When client submits the registration request:
    | field    | value             |
    | email    | alice@example.com |
    | password | Str0ng!Pass#2026  |
  Then response status should be 201
  And response body should contain "user_id"

Chinese authoring is also supported:

## 意图
## 已定决策
## 边界
## 完成条件

场景: 全额退款保持现有返回结构
  测试: test_refund_service_keeps_existing_success_payload
  假设 存在一笔金额为 "100.00" 元的已完成交易 "TXN-001"
  当 用户对 "TXN-001" 发起全额退款
  那么 响应状态码为 202

Workflow

1. Author a task contract

Start from a template:

cargo run -q --bin agent-spec -- init --level task --lang en --name "User Registration API"

For rewrite/parity tasks, start from the parity-aware task template:

cargo run -q --bin agent-spec -- init --level task --template rewrite-parity --lang en --name "CLI Parity Contract"

Or study the examples in examples/.

AI Agent Skills

This repo ships five agent skills under skills/:

• agent-spec-tool-first: the default integration path — tells the agent to use agent-spec as a CLI tool and drive tasks through contract, lifecycle, and guard.
• agent-spec-authoring: the authoring path — helps write or revise Task Contracts in the DSL.
• agent-spec-estimate: the estimation path — maps Task Contract elements (scenarios, decisions, boundaries) to round-based effort estimates.
• agent-spec-intent-compiler: the intake path — drafts human-reviewed Candidate Requirement Blocks from unstructured PRDs/issues for the deterministic intent-compiler pipeline to import.
• agent-spec-wiki: the working-memory path — maintains the repo-local code live wiki (stale detection, source-traced articles, architecture inventories).

For rewrite/parity work, the authoring path should explicitly bind observable behavior before coding:

• command x output mode
• local x remote
• warm cache x cold start
• success x partial failure x hard failure

See examples/rewrite-parity-contract.spec for a concrete parity-oriented contract.

One-line install (CLI + skills)

./install-skills.sh

This installs the agent-spec CLI via cargo install (if not already present) and copies all five skills to ~/.claude/skills/.

Manual install for Claude Code

# Copy to your global skills directory
cp -r skills/agent-spec-tool-first ~/.claude/skills/
cp -r skills/agent-spec-authoring ~/.claude/skills/
cp -r skills/agent-spec-estimate ~/.claude/skills/
cp -r skills/agent-spec-intent-compiler ~/.claude/skills/
cp -r skills/agent-spec-wiki ~/.claude/skills/

Or symlink for auto-updates:

ln -s "$(pwd)/skills/agent-spec-tool-first" ~/.claude/skills/
ln -s "$(pwd)/skills/agent-spec-authoring" ~/.claude/skills/
ln -s "$(pwd)/skills/agent-spec-estimate" ~/.claude/skills/
ln -s "$(pwd)/skills/agent-spec-intent-compiler" ~/.claude/skills/
ln -s "$(pwd)/skills/agent-spec-wiki" ~/.claude/skills/

Install for Codex

The equivalent guidance for Codex lives in AGENTS.md. Copy it to your project root:

cp AGENTS.md /path/to/your/project/

Install for Cursor

Copy .cursorrules to your project root.

Workflow

1. Use agent-spec-tool-first to inspect the target spec and render agent-spec contract.
2. Run agent-spec plan <spec> --code . --format prompt to generate a self-contained implementation prompt with codebase context.
3. Implement code against the Contract + Plan.
4. Run agent-spec lifecycle for the task-level gate.
5. Run agent-spec guard for repo-level validation when needed.

Before step 2, if the task is a rewrite, migration, or parity effort, use the tool-first workflow to review which observable behaviors are still unbound. If stdout/stderr, --json, -o/--output, local/remote, cache state, or fallback order are only described in prose, go back to authoring mode and add scenarios first.

This keeps the main integration mode tool-first. Library embedding remains available for advanced Rust-host integration, but it is not the default path.

2. Render the contract for agent execution

cargo run -q --bin agent-spec -- contract specs/my-task.spec

Use --format json if another tool or agent runtime needs structured output.

2b. Generate plan context (Contract + Codebase + Task Sketch)

cargo run -q --bin agent-spec -- plan specs/my-task.spec --code .

plan outputs three blocks:

• Contract — the full task contract with inherited constraints
• Codebase Context — files in Allowed Changes paths with summaries, pub API signatures, and existing test functions
• Task Sketch — scenarios grouped by dependency order (topological sort) for implementation sequencing

Use --format prompt for a self-contained AI prompt (includes mandatory verification gate and execution protocol). Use --format json for machine-parseable output. Use --depth full to include pub API signatures in the codebase scan.

3. Run the full quality gate

cargo run -q --bin agent-spec -- lifecycle specs/my-task.spec --code . --format json

lifecycle runs:

• lint
• verification
• reporting

The run fails if:

• lint emits an error
• any scenario fails
• any scenario is still skip or uncertain
• the quality score is below --min-score

4. Use the repo-level guard

cargo run -q --bin agent-spec -- guard --spec-dir specs --code .

guard is intended for pre-commit / CI use. It lints all specs in specs/ and verifies them against the current change set.

5. Contract Acceptance (replaces Code Review)

cargo run -q --bin agent-spec -- explain specs/my-task.spec --code . --format markdown

explain renders a reviewer-friendly summary of the Contract + verification results. Use --format markdown for direct PR description paste. Use --history to include retry trajectory from run logs.

The reviewer judges two questions: (1) Is the Contract definition correct? (2) Did all verifications pass?

6. Stamp for traceability

cargo run -q --bin agent-spec -- stamp specs/my-task.spec --code . --dry-run

Outputs git trailers (Spec-Name, Spec-Passing, Spec-Summary) for the commit message. Currently only --dry-run is supported.

Explicit Test Binding

Task-level scenarios should declare an explicit Test: / 测试: selector.

Scenario: Duplicate email is rejected
  Test: test_register_api_rejects_duplicate_email

If package scoping matters, use the structured selector block:

Scenario: Duplicate email is rejected
  Test:
    Package: user-service
    Filter: test_register_api_rejects_duplicate_email

场景: 超限退款返回稳定错误码
  测试:
    包: refund-service
    过滤: test_refund_service_rejects_refund_exceeding_original_amount

This is the default quality rule for self-hosting and new task specs. The older // @spec: source annotation is still accepted as a compatibility fallback, but it should not be the primary authoring path.

Boundaries And Change Sets

Boundaries can contain both natural-language constraints and path constraints. Path-like entries are mechanically enforced against a change set.

Examples:

## Boundaries

### Allowed Changes
- crates/spec-parser/**
- crates/spec-gateway/src/lifecycle.rs

### Forbidden
- tests/golden/**
- docs/archive/**

The relevant commands accept repeatable --change flags:

cargo run -q --bin agent-spec -- verify specs/my-task.spec --code . --change crates/spec-parser/src/parser.rs
cargo run -q --bin agent-spec -- lifecycle specs/my-task.spec --code . --change crates/spec-parser/src/parser.rs

Single-task commands also support optional VCS-backed change discovery:

cargo run -q --bin agent-spec -- verify specs/my-task.spec --code . --change-scope staged
cargo run -q --bin agent-spec -- lifecycle specs/my-task.spec --code . --change-scope worktree
cargo run -q --bin agent-spec -- lifecycle specs/my-task.spec --code . --change-scope jj

Available scopes: none (default for verify/lifecycle), staged, worktree, jj.

When a .jj/ directory is detected (even colocated with .git/), use --change-scope jj to discover changes via jj diff --name-only. The stamp command also outputs a Spec-Change: trailer with the jj change ID, and explain --history shows file-level diffs between adjacent runs via jj operation IDs.

AI Verifier Skeleton

agent-spec now includes a minimal AI verifier surface intended to make uncertain results explicit and inspectable before a real model backend is wired in.

The relevant commands accept:

cargo run -q --bin agent-spec -- verify specs/my-task.spec --code . --ai-mode stub
cargo run -q --bin agent-spec -- lifecycle specs/my-task.spec --code . --ai-mode stub

Available modes:

• off: default, preserves the current mechanical-verifier-only behavior
• stub: turns otherwise-uncovered scenarios into uncertain results with AiAnalysis evidence
• caller: the calling Agent acts as the AI verifier (two-step protocol)

caller mode enables the Agent running agent-spec to also serve as the AI verifier. When lifecycle --ai-mode caller finds skipped scenarios, it writes AiRequest objects to .agent-spec/pending-ai-requests.json. The Agent reads the requests, analyzes each scenario, writes ScenarioAiDecision JSON, then calls resolve-ai --decisions <file> to merge decisions back into the report.

stub mode does not claim success. It is only a scaffold for:

• explicit uncertain semantics
• structured AI evidence in reports
• future integration of a real model-backed verifier

Internally, the AI layer now uses a pluggable backend shape:

• AiRequest: structured verifier input
• AiDecision: structured verifier output
• AiBackend: provider abstraction used by AiVerifier
• StubAiBackend: built-in backend for deterministic local behavior

No real model provider is wired in yet. The current value is that the contract/reporting surface is now stable enough to add a real backend later without redesigning the verification pipeline.

Provider selection and configuration are intentionally out of scope for agent-spec itself. The intended embedding model is:

• the host agent owns provider/model/auth/timeout policy
• the host agent injects an AiBackend into spec-gateway
• agent-spec stays focused on contracts, evidence, and verification semantics

guard resolves change paths in this order:

1. explicit --change arguments
2. auto-detected git changes according to --change-scope, if the current workspace is inside a git repo
3. an empty change set, if no git repo is available

guard defaults to --change-scope staged, which keeps pre-commit behavior stable.

If you want stronger boundary checks against the full current workspace, use:

cargo run -q --bin agent-spec -- guard --spec-dir specs --code . --change-scope worktree

worktree includes:

• staged files
• unstaged tracked changes
• untracked files

This makes guard practical for both pre-commit usage and broader local worktree validation without forcing users to enumerate changed files manually.

For consistency, verify and lifecycle use the same precedence when --change-scope is provided. The practical default is:

• verify: none
• lifecycle: none
• guard: staged

Commands

Command	Purpose
parse	Parse .spec/.spec.md files and show the AST
lint	Analyze spec quality (vague verbs, missing test selectors, coverage gaps)
verify	Verify code against a single spec
matrix	Render the Rule→Example coverage matrix (text/json/markdown)
promote	Promote a task-scoped Rule to a capability spec (id-stable)
gen-integrations	Generate per-tool integration files from a single source
check-structure	Mechanical structural check: forbid a reference within a file glob
audit	Audit a spec library's health (unproven rules, open questions)
discover	Reverse-engineer a draft task spec from a codebase's tests (--from-codebase)
init --workspace	Scaffold the canonical knowledge/ tree for KLL artifacts
requirements	Import PRD/issue requirement blocks, validate a requirement graph, generate work units, and draft specs
wiki	Generate, check, and export a local-first source trace wiki from code, KLL artifacts, specs, traces, and docs
atlas	Build and query a freshness-gated Rust code graph, analyze flow/impact, run live serving, and validate external providers
trace	Trace a decision/requirement id to satisfying specs and report derived liveness
lint-knowledge	Lint the knowledge corpus and gate malformed or inconsistent artifacts
mcp	Serve specs, knowledge, guidance, context, and live liveness over read-only MCP
contract	Render the Task Contract view
plan	Generate plan context: Contract + Codebase scan + Task Sketch
lifecycle	Run lint + verify + report (the main quality gate)
guard	Lint all specs and verify against the current change set
explain	Generate a human-readable contract review summary (Contract Acceptance)
stamp	Preview git trailers for a verified contract (--dry-run)
resolve-ai	Merge external AI decisions into a verification report (caller mode)
checkpoint	Preview VCS-aware checkpoint status
graph	Generate spec dependency graph (--format dot or svg)
install-hooks	Install git hooks for automatic checking
measure-determinism	[experimental] Measure contract verification variance

Rust Atlas

The independently versioned rust-atlas crate builds a derived Rust code graph. Build it before querying, then use status to inspect graph identity and independent syn, SCIP, and MIR freshness. The graph, query index, and code bindings are rebuildable working data; knowledge/ remains the KLL source of truth.

agent-spec atlas build --code . --graph .agent-spec/graph
agent-spec atlas search <query> --code . --graph .agent-spec/graph --limit 20
agent-spec atlas explore <query> --profile compact --code . --graph .agent-spec/graph --frozen
agent-spec atlas context <query> --profile symbol --code . --graph .agent-spec/graph --frozen
agent-spec atlas flow --from <symbol> --to <symbol> --code . --graph .agent-spec/graph --frozen
agent-spec atlas flow --through <symbol> --code . --graph .agent-spec/graph --frozen
agent-spec atlas impact <symbol> --depth 3 --code . --graph .agent-spec/graph --frozen
agent-spec atlas affected --worktree --code . --graph .agent-spec/graph --frozen
agent-spec atlas status --code . --graph .agent-spec/graph --format json
agent-spec atlas check --code . --graph .agent-spec/graph
agent-spec atlas daemon start --code . --graph .agent-spec/graph
agent-spec atlas daemon status --code . --graph .agent-spec/graph
agent-spec atlas daemon service-status --code . --graph .agent-spec/graph
agent-spec atlas daemon sync --code . --graph .agent-spec/graph
agent-spec atlas daemon stop --code . --graph .agent-spec/graph

Builds publish one immutable committed generation containing metadata, shards, the query index, input plan, and semantic capability state. Queries pin and report one generation. A healthy zero-change build performs no resolution, validation, staging, or authority rewrite; changed declarations re-resolve a bounded reverse-dependent frontier, with an explicit complete fallback on overflow. Failed or cancelled work remains recoverable through an orphan queue without changing the active generation.

Use --features, --target, and repeatable --cfg values for the content-addressed Cargo input plan. --frontier-limit, --batch-size, and --working-byte-limit set deterministic resource boundaries. These D2 build primitives preserve committed Cargo inputs during automatic refresh, use an explicit full frontier for capability changes, and keep post-commit orphan maintenance failures recoverable. D3 optionally wraps them with a bounded watcher and daemon. It persists a pending watermark, reports degraded explicitly, and keeps separate writer-lock and ordinary retry budgets. Queries hold a reader lease while using an immutable generation; ambiguous leases block reclamation. Static MCP discovery and no-daemon queries remain available. Live state never replaces graph freshness, KLL, or lifecycle authority. See Rust Atlas Incremental Builds and Rust Atlas Live Runtime.

D4 adds an opt-in fixed query pool without changing those defaults. Start the daemon with --query-workers 2, then use atlas context --execution worker or inspect atlas daemon service-status. Queue, deadline, memory, cancellation, panic retry, circuit state, and fallback remain typed in receipts. Direct mode and the default MCP tool list stay unchanged pending E1 real Agent A/B. See Rust Atlas Concurrent Query Serving.

Bounded Rust trait-dispatch candidates are opt-in and require a SCIP call anchor. The original exact declaration edge remains; the enricher adds a separate unresolved candidate edge with a hard fan-out cap:

agent-spec atlas build --code . --scip target/index.scip --dynamic-dispatch

See Rust Atlas Dynamic Dispatch.

MIR activation is an opt-in Cargo feature and consumes a versioned external producer artifact. The stable JSON consumer carries no compiler dependency; the default build neither compiles nor invokes a MIR producer:

cargo run --features mir -- atlas build --code . --mir target/rust-atlas/mir-overlay.json
cargo run --features mir -- atlas build --code . --mir-driver /absolute/path/to/rust-atlas-mir-driver

The two MIR modes are mutually exclusive. Extraction or validation failure returns a mir-extraction-failed build warning, clears previous MIR facts, and keeps the syn plus optional SCIP graph usable. MIR shards commit as one staged generation, and status exposes extractor plus artifact/source fingerprints. The repository currently ships the protocol, consumer, and driver adapter, not an official rustc_public producer binary. See Rust Atlas MIR Overlay.

search accepts a query and supports --limit from 1 through 200 (default 20); add --frozen to read without automatic syn refresh. check is the compatibility freshness gate for syn stale files and exits non-zero when any remain. status reports the recorded and current graph identities plus separate layer states, so a fresh syn layer never implies a fresh SCIP or MIR layer.

explore composes ranked graph context under fixed hard budgets. Compact uses 8 seeds, 32 nodes, 48 edges, 8 paths, 4 excerpts of at most 20 lines, and 16,000 serialized bytes; deep uses 16, 96, 160, 20, 12, 40, and 24,000 bytes. Only source files whose current hash matches the graph metadata may appear as excerpts. In flow, found carries a path, no-path means a complete capable search found none, capability-unavailable means the graph cannot decide, truncated means a traversal limit stopped the search, and unknown-endpoint or ambiguous-endpoint reports endpoint resolution before traversal. For a fresh disconnected flow, Atlas may also report bounded query-time hints for async tasks, channels, callback registries, reflection, and framework routes. These runtime_boundaries explain where static flow stopped; they do not create graph edges or participate in impact, binding, lifecycle, or archive evidence. See Rust Atlas Runtime Boundary Hints. affected accepts exactly one of explicit paths, --stdin, --staged, --worktree, or --commit <range> and reports code nodes and evidence paths; it never infers test selectors or coverage from filenames.

context is the B5 two-stage context compiler. It parses explicit identifiers, paths, relations, and one symbol | flow | architecture | impact profile; retrieval returns scored candidates before projection applies relevance and byte limits. Results contain an omission manifest, stable fingerprint-bound continuation argv, separate retrieval/projection receipts, verified source spans, and a D4 load profile. Required evidence fails explicitly instead of being pruned. This additive CLI does not replace explore and is not exposed over default MCP. See Rust Atlas Query Context Compiler.

Rebuild with agent-spec atlas build after an atlas-schema-mismatch or any atlas-query-index-missing, atlas-query-index-schema, atlas-query-index-stale, or atlas-query-index-corrupt diagnostic. A graph from another worktree, or stale available semantic authority, cannot produce a definitive provider result, code binding, lifecycle symbol verdict, or typed trace target.

The MCP server is read-only and uses frozen Atlas reads. It lists atlas_search only when started with AGENT_SPEC_MCP_ATLAS_SEARCH=1. atlas_explore is unavailable to discovery and dispatch unless the server is started with AGENT_SPEC_MCP_ATLAS_EXPLORE=1; its default profile is compact. atlas_context is also hidden by default. Set AGENT_SPEC_MCP_ATLAS_CONTEXT=1 to expose its frozen direct path. Add AGENT_SPEC_MCP_ATLAS_QUERY_MODE=worker only after starting a daemon with non-zero query workers; initialize, discovery, and ping remain on the transport lane. The default MCP tool list remains unchanged while real Agent A/B is pending.

External Code Graph Providers

F1 provides a standalone Rust adapter SDK and conformance gate for future language or semantic providers. It does not add a non-Rust parser and does not change the Rust Atlas path. Providers remain disabled until a project supplies an explicit registration.

agent-spec atlas provider validate --manifest path/to/manifest.json --registration path/to/registration.json
agent-spec atlas provider conformance --manifest fixtures/code-graph-provider/basic/manifest.json --registration fixtures/code-graph-provider/basic/registration.json --fixture fixtures/code-graph-provider/basic/conformance.json --code . --scratch .agent-spec/provider-conformance --out .agent-spec/provider-conformance/receipt.json

The kit separates extractor nodes/basic references from additive semantic enrichment, validates worktree and freshness evidence, enforces timeout and stdout/stderr limits, supports cancellation, and publishes only validated artifacts atomically. See External Code Graph Provider Kit.

Code Live Wiki

agent-spec can maintain a repo-local code live wiki from code, KLL artifacts, Task Contracts, docs, archive summaries, and lifecycle trace evidence. The default location is .agent-spec/wiki.

agent-spec wiki init --code . --wiki .agent-spec/wiki
agent-spec wiki seed --code . --wiki .agent-spec/wiki
agent-spec wiki seed --code . --wiki .agent-spec/wiki --check
agent-spec wiki status --code . --wiki .agent-spec/wiki
agent-spec wiki query "intent compiler" --wiki .agent-spec/wiki
agent-spec wiki inspect src/spec_wiki/live.rs --code . --wiki .agent-spec/wiki
agent-spec wiki inventory --code . --format json
agent-spec wiki inventory --code . --format mermaid
agent-spec wiki project-map --code . --wiki .agent-spec/wiki --format json --out .agent-spec/wiki/architecture/project-map.json
agent-spec wiki project-map --code . --wiki .agent-spec/wiki --format mermaid --out .agent-spec/wiki/architecture/project-map.mmd
agent-spec wiki inspect-project brain-rs --code . --wiki .agent-spec/wiki --format text
agent-spec wiki index --wiki .agent-spec/wiki
agent-spec wiki lint --code . --wiki .agent-spec/wiki
agent-spec wiki check --code . --wiki .agent-spec/wiki
agent-spec atlas build --code .          # Rust project graph: build/refresh
agent-spec atlas query <symbol> --code . # query structure instead of grepping
agent-spec atlas search <query> --code . # deterministic indexed symbol search
agent-spec atlas status --code .          # graph identity and layered freshness
agent-spec atlas check --code .          # staleness gate (non-zero when stale)
agent-spec atlas scip-gen --code .       # optional: rust-analyzer SCIP index for the semantic overlay (Calls/UsesType)
agent-spec wiki meta update --code . --wiki .agent-spec/wiki

Atlas Evaluation

Atlas includes an offline, correctness-first evaluation baseline plus a deterministic query-quality regression gate. It does not invoke models or the network unless an external runner is explicitly configured. See Atlas Evaluation And Query Regression for the corpus, run-plan, score receipt, summary, and opt-in runner contracts.

E1 adds strict real-Agent A/B/C and direct/worker adoption gates. The harness is delivered, but no real receipt or passing conclusion is checked in; default MCP, B5, and worker behavior remain unchanged. See Atlas Real Agent A/B Gate.

D4 adds benchmarks/atlas/concurrent-query-receipt-v1.json: a strict 20-run direct/worker matrix covering four load profiles, seven typed outcomes, snapshot/lease invariants, and worktree isolation. Its latency, heartbeat, CPU, RSS, and response-size values are measurements, not pass thresholds or a performance claim.

cargo run -- atlas benchmark validate --corpus benchmarks/atlas/corpus.json
cargo run -- atlas benchmark plan --corpus benchmarks/atlas/corpus.json --out plan.json
cargo run -- atlas benchmark summarize --receipts receipts.ndjson --out summary.json
cargo run -- atlas benchmark score --corpus benchmarks/atlas/query-corpus.json --results benchmarks/atlas/query-results.json --out query-regression.json
cargo run -- atlas benchmark agent-plan --corpus benchmarks/atlas/corpus.json --experiment benchmarks/atlas/agent-ab-experiment-v1.json --out benchmarks/atlas/agent-ab-plan-v1.json
cargo run -- atlas benchmark agent-gate --plan benchmarks/atlas/agent-ab-plan-v1.json --receipts .agent-spec/evaluation/agent-receipts.json --out .agent-spec/evaluation/agent-gate.json
cargo run -- atlas benchmark serving-plan --experiment path/to/real-serving-experiment.json --out .agent-spec/evaluation/serving-plan.json
cargo run -- atlas benchmark serving-gate --plan .agent-spec/evaluation/serving-plan.json --receipts .agent-spec/evaluation/serving-receipts.json --out .agent-spec/evaluation/serving-gate.json

The score command gates ranked symbols, paths, evidence, forbidden hits, query costs, context retrieval/projection receipts, and stale/capability diagnostics. Pinned-repository cases identify immutable revisions but are not fetched or executed by scoring or default tests. Failed cases are written into the receipt before score exits non-zero.

Wiki pages are maintained agent working memory, not KLL truth and not published human docs. Track .agent-spec/wiki/** in git, but keep .agent-spec/runs, .agent-spec/trace, temporary files, and other runtime state ignored. Each article declares source_files; wiki status reports stale pages when those files change, including dirty, staged, and untracked worktree changes. Use wiki query before broad source reading and wiki inspect <path> to find the wiki pages, KLL requirements, and task specs tied to a source or knowledge path.

wiki seed creates focused draft module, concept, and decision pages without overwriting maintained articles. wiki inventory emits Rust architecture inventory, package/module data, and Mermaid graphs from Cargo metadata when available; non-Rust projects still get generic source inventory, status, index, lint, and metadata support. wiki check combines index freshness, lint, and current worktree stale status; in CI clean checkouts it acts as the tracked wiki structure gate.

Cross-Project Wiki

Use project articles when the main repository depends on another important project. Project articles live under .agent-spec/wiki/projects/*.md and use stable project_id values. Use flow articles under .agent-spec/wiki/flows/*.md to document working mechanisms and data flow between projects. Project and flow articles must be regular Markdown files; symlinks are rejected so discovery, copying, and stale checks use one deterministic file boundary. Every field shown in the examples is required and non-empty. Invalid frontmatter lines, duplicate keys, and incomplete articles fail project-map validation instead of producing partial architecture records.

source_files stay repo-local and participate in stale article checks. external_sources record outside project paths, URLs, or repo identifiers as evidence labels; agent-spec performs no external repository scan by default.

Project article example:

---
title: "brain-rs"
type: external-project
project_id: brain-rs
repo: rust-agents/brain-rs
role: "Context provider"
interfaces: [cli, json]
protocols: [stdio]
status: active
source_files:
  - src/integration/brain.rs
external_sources:
  - https://example.invalid/rust-agents/brain-rs
---
# brain-rs

Flow article example:

---
title: "agent-spec to brain-rs context flow"
type: project-flow
flow_id: agent-spec-to-brain
projects:
  - agent-spec
  - brain-rs
kind: calls
protocols: [stdio, json]
requirements:
  - REQ-CROSS-PROJECT-WIKI
specs:
  - specs/task-cross-project-wiki.spec.md
source_files:
  - src/integration/brain.rs
external_sources:
  - https://example.invalid/rust-agents/brain-rs/src/lib.rs
---
# agent-spec to brain-rs context flow

The projects list is ordered; each adjacent pair becomes a directed edge. requirements and specs resolve inside the current repository. Put paths, URLs, and repository identifiers from outside the current repository in external_sources only.

The wiki project-map command builds project-map JSON or Mermaid output under .agent-spec/wiki/architecture/. The maintained truth remains the project articles and flow articles; project-map.json and project-map.mmd are derived artifacts. Use wiki inspect-project <project-id> to list the project article, related flows, protocols, requirements, specs, and external source labels. wiki lint and wiki check also require both derived artifacts to match the maintained articles exactly.

Archive old wiki material instead of deleting it abruptly. Move obsolete article content into a learnings/ or archive/ summary page that preserves source links and the reason it is no longer active. Non-goals: no built-in LLM long-form generation, no web UI, and no replacement for knowledge/ as the durable requirements/decision layer.

Requirements Intake And Work Units

Use the requirements workflow when the source material starts as a PRD or issue, but the implementation should be governed by long-lived KLL requirements and Task Contracts.

If the PRD or issue is unstructured prose, use the agent-spec-intent-compiler skill first. The skill drafts human-reviewed Candidate Requirement Block entries with source excerpts, confidence, scenarios, and open questions; the CLI only imports those accepted blocks and never silently interprets raw prose.

agent-spec requirements import --from docs/prd.md --out knowledge/requirements
agent-spec requirements import --from requirements.yaml --out knowledge/requirements   # v1.1 and ARC-native shapes auto-detected
agent-spec requirements transition REQ-101 --to accepted   # human governance action
agent-spec requirements export --out requirements.yaml     # derived YAML projection (--check gates drift)
agent-spec requirements export --out requirements.yaml --dialect arc-native   # reference-compiler-loadable single-root tree
agent-spec lint-knowledge --knowledge knowledge --gate
agent-spec requirements graph --knowledge knowledge --format json --gate
agent-spec requirements work-units --knowledge knowledge --out .agent-spec/work_units.json
agent-spec requirements draft-specs --knowledge knowledge --out specs/generated
# Draft specs contain pending Test selectors; this lifecycle command is expected to fail until a human replaces them with real tests.
agent-spec lifecycle specs/generated/task-req-101-user-login.spec.md --code .
agent-spec trace REQ-101 --knowledge knowledge --specs specs --code .

Generated drafts are review artifacts. Their Test: selectors start with pending_...; agent-spec lifecycle reports those nonexistent selectors as fail. Replace each pending selector with a real test name before treating the draft as executable or using trace as acceptance evidence.

PRD/issue import is explicit. Raw prose is not silently reinterpreted; wrap stable requirements in an agent-spec:requirement block:

<!-- agent-spec:requirement id=REQ-101 title="User Login" tags=auth,web source=issue:#123 -->
## Problem

Users with existing accounts need to authenticate.

## Requirements

[REQ-101] The authentication service MUST create a login session when valid credentials are submitted.

## Scenarios

Scenario: Valid login
  Given the visitor has a valid persisted account
  When the visitor submits valid credentials
  Then the system establishes a login session

## Open Questions

None.
<!-- /agent-spec:requirement -->

Examples

See examples/:

• examples/user-registration-contract.spec
• examples/refactor-payment-service.spec
• examples/refund.spec
• examples/no-unwrap.spec

Current Status

The current system is strongest when the contract can be checked by:

• explicit tests selected from Completion Criteria
• structural checks
• boundary checks against an explicit or staged change set

More advanced verifier layers can still be added, but the current model is already sufficient for self-hosting agent-spec with task contracts.

Contributing

agent-spec is self-bootstrapping: the project uses itself to govern its own development. When you contribute, you follow the same Contract-driven workflow that agent-spec teaches.

The contribution flow

Every change starts with a Task Contract. Before writing code, create a .spec.md file in specs/ that defines what you're building — the intent, the technical decisions that are already fixed, the files you'll touch, and the BDD scenarios that define "done." Then implement against the Contract and verify with lifecycle. (Legacy .spec files are also supported.)

# 1. Create a task contract for your change
agent-spec init --level task --lang en --name "my-feature"
# Edit the generated spec: fill in Intent, Decisions, Boundaries, Completion Criteria

# 2. Check that the contract itself is well-written
agent-spec lint specs/my-feature.spec.md --min-score 0.7

# 3. Implement your change

# 4. Verify against the contract
agent-spec lifecycle specs/my-feature.spec.md --code . --change-scope worktree --format json

# 5. Run the repo-wide guard before committing
agent-spec guard --spec-dir specs --code .

# 6. Generate the PR description
agent-spec explain specs/my-feature.spec.md --code . --format markdown

The guard pre-commit hook is installed via agent-spec install-hooks. It checks all specs in specs/ against your staged changes — your commit will be blocked if any contract fails.

Project-level rules

The file specs/project.spec defines constraints that every task spec inherits. Read it before writing your first Contract — it tells you what the project enforces globally (e.g. "all public CLI behavior must have regression tests," "verification results must distinguish pass/fail/skip/uncertain").

Roadmap specs

Future work lives in specs/roadmap/. These are real Task Contracts but they are not checked by the default guard run. When a roadmap spec is ready for implementation, promote it to the top-level specs/ directory. See specs/roadmap/README.md for the promotion rule.

Using AI agents to contribute

If you use Claude Code, Codex, Cursor, or another AI coding agent, install the skills from the skills/ directory (see AI Agent Skills above).

The agent-spec-tool-first skill tells the agent to read the Contract first, implement within its Boundaries, run lifecycle to verify, and retry on failure without modifying the spec. The agent-spec-authoring skill helps the agent draft or revise Task Contracts in the DSL. The agent-spec-estimate skill maps Contract elements to round-based effort estimates for sprint planning.

For agents without skill support, the project includes AGENTS.md (Codex), .cursorrules (Cursor), and .aider.conf.yml (Aider) with the essential command reference.

Release maintainers should follow the multi-crate order and package gates in Release Process.

What we review

Pull requests are evaluated through Contract Acceptance, not line-by-line code review. The reviewer checks two things: is the Contract definition correct (does it capture the right intent and edge cases), and did all verifications pass (lifecycle reports all-green). If both are yes, the PR is approved.

This means the quality of your Contract matters as much as the quality of your code. A well-written Contract with thorough exception-path scenarios is a stronger contribution than clever code with a thin spec.

Intent Compiler Workflow

Terminology: Intent Compiler（意图编译器） is what agent-spec as a whole does; this workflow is its pipeline. Requirements are the compiler's intermediate representation (IR) — intent compiles into structured requirements, and requirements lower into Task Contracts. That is why the artifact layer keeps the requirement noun (agent-spec requirements, knowledge/requirements/, REQ-* ids): they name the IR, not the compiler. Historical contract/requirement file stems predating the rename are also unchanged.

Acknowledgement: the intent compiler's borrowed validation invariants (requirement tree, dependency DAG, scenario grounding, test-first obligations, traceability) draw on the ARC (Agentic Requirement Compiler) reference project; this note is the repository's only reference to that name, and docs/intent-compiler/reference-validation-matrix.md records the invariant mapping.

The requirements workflow is a compiler pipeline. requirements graph validates the KLL requirement graph, requirements work-units lowers graph nodes into executable or blocked work, requirements plan joins requirement, work-unit, and spec nodes into one DAG with explicit satisfies and spec_depends edges, requirements test-obligations emits spec-derived test obligations independently of implementation code, and requirements worktrees maps ready work units to git worktree execution entries for parallel agents. After code grounding, requirements affected joins provider-neutral impact to requirements, scenarios, explicit selectors, obligations, worktrees, and VCS; missing links remain typed gaps. requirements affected-bundle applies the risk A/B/C policy and preserves selected provider executable, argv, cwd, timeout, and output-limit configuration. requirements affected-record stores the completed chain. requirements trace/requirements replay/requirements explain-failure/requirements trace-graph expose stored lifecycle and affected evidence, while requirements questions emits deterministic clarification prompts. The CLI does not call an AI model; AI-assisted PRD translation and reverse interviewing live in skills that write reviewed KLL artifacts back to disk.

Compiler inputs are strict trust boundaries. Requirement ids must be safe stable identifiers, frontmatter must begin on the first line and contain no malformed or duplicate keys, declared kind must match the knowledge/ subdirectory, required roots must exist, and recursive compilation rejects symlinks. Missing or malformed inputs are diagnostics, never an empty successful graph.

DORA-inspired gates: specs may declare risk: A, risk: B, or risk: C. This is the QA class gate. Class A work requires lifecycle, trace, targeted tests, and adversarial review evidence; Class B requires lifecycle and trace; Class C requires lifecycle. Requirements with protocol or lifecycle behavior should use a ## State Machine section so state-machine lint can check transition coverage.

Requirement replay is evidence replay, not deterministic LLM replay. Trace ledger v2 can store the complete intent-impact report, its digest, an affected execution bundle, normalized quality outcomes, paths and source spans, worktree, and observed VCS reference beside lifecycle records for the same run_id. Replay, failure explanation, and trace graph read only stored evidence; they never rerun Atlas, Git diff, tests, quality tools, skills, or a model. Re-recording the same run preserves omitted bundle or quality evidence and rejects conflicting immutable evidence. V1 ledgers remain readable and return an explicit affected-trace-missing gap instead of guessing affected paths. A single-requirement spec owns all its scenarios; multi-requirement specs use KLL scenario names for disambiguation.

agent-spec development dogfoods this workflow on its own repository. The self-hosting gate uses knowledge/requirements/req-requirements-compiler-plan-dag.md and specs/task-requirements-compiler-plan-dag.spec.md as the primary proof that requirements remain guarded by code. Example fixtures demonstrate the workflow for other projects; they do not replace the self-hosting dogfood gate.

Completed specs should eventually leave the active specs scan set. Use agent-spec archive --spec-dir specs --archive-dir .agent-spec/archive/specs --summary knowledge/context/spec-archives.md --run-log-dir . --dry-run to preview which completed contracts can be archived and what compressed summary will be written. The archive command requires specs to be tagged done or completed and to have latest passing lifecycle evidence bound to the current canonical spec path and content fingerprint; missing, failing, or stale evidence blocks archival and appears as an archive diagnostic. Application preflights all sources and targets before moving any spec. Archived specs are historical evidence and are ignored by default active specs scans.

Use requirements questions as the deterministic input to the reverse interview workflow. The reverse interview happens in skills or human workflow, not inside CLI code.

agent-spec requirements plan --knowledge knowledge --specs specs --format json --gate
agent-spec requirements test-obligations --knowledge knowledge --specs specs --format json --out .agent-spec/test_obligations.json
agent-spec requirements worktrees --knowledge knowledge --specs specs --base main --path-prefix ../agent-spec-worktrees --out .agent-spec/worktrees.json
agent-spec requirements affected --path src/lib.rs --knowledge knowledge --specs specs --out .agent-spec/intent-impact.json
agent-spec requirements affected-bundle --impact .agent-spec/intent-impact.json --knowledge knowledge --out .agent-spec/affected-bundle.json
agent-spec requirements affected-record --impact .agent-spec/intent-impact.json --bundle .agent-spec/affected-bundle.json --quality-outcomes .agent-spec/quality-outcomes.json --run-id "$RUN_ID" --timestamp "$TIMESTAMP"
agent-spec requirements replay REQ-123 --format text
agent-spec requirements explain-failure REQ-123 --format json
agent-spec requirements trace-graph REQ-123 --format mermaid
agent-spec requirements questions --knowledge knowledge --specs specs --format json
agent-spec archive --spec-dir specs --archive-dir .agent-spec/archive/specs --summary knowledge/context/spec-archives.md --run-log-dir . --dry-run

affected-record is a recorder, not an executor. Its optional --quality-outcomes file is a JSON array such as [{"provider_id":"cargo-clippy","outcome":{"outcome":"pass"},"summary":"workspace clippy passed"}]. Use the same run_id as lifecycle so both evidence classes merge without overwriting one another. Repeating the command with an omitted optional artifact preserves previously recorded evidence; conflicting values for the same run fail.

Documentation Engineering

agent-spec adopts Lore-style documentation engineering for human-facing docs: doc types, canon, operational checklists, and docs lint tooling. Use docs/ for reader-facing prose and knowledge/ for machine-consumable truth. Run bash scripts/docs-lint.sh before publishing substantial documentation changes. KLL gates and docs gates are complementary: docs gates check readability, structure, English prose style, Chinese project style, and links with Harper, agent-spec's built-in Chinese docs lint, markdownlint, and lychee; KLL/spec gates check traceability and behavior. Treat these checks as pre-publish review for substantial documentation changes. CI uses DOCS_LINT_REQUIRE_EXTERNAL=all so Harper, markdownlint, and lychee must all run.