agent-spec

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

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.

Walking the pipeline forward

Governance flows in one direction, and each layer has exactly one exit:

knowledge/proposals/    LEP-NNN   should we do this, and why
    │  ## Produces: ADR-NNN
knowledge/decisions/    ADR-NNN   the ruling, with alternatives
    │  a governed requirement
knowledge/requirements/ REQ-*     MUST clauses + scenarios
    │  satisfies: [REQ-*]
specs/                  task-*    executable, verifiable contract

knowledge/standards/operational/id-registry.md is the authority for which prefix lives where; scaffold each artifact with agent-spec knowledge new <kind> <id> so the enum values, filename, and exit pointer are right the first time. lint-knowledge --gate enforces the walk: a task contract with no satisfies: raises orphan-spec at Warning severity, an ADR-* id under a requirement's ## Dependencies raises dependency-kind-mismatch, and an accepted proposal whose produced decision does not link back raises produces-link-integrity. The 1.3.0 migration used a shrink-only baseline for existing contracts. That baseline is now retired and empty; any non-empty .agent-spec/orphan-baseline.json is an Error rather than an exemption.

Decision points

Three places stop for a human, and all three emit the same machine-readable envelope so any agent harness can render it as a choice instead of improvising the question:

Candidates are drafted by the agent from source text and validated by the CLI (at most four, each with a label and a one-sentence description); the CLI never authors one. An empty candidate list is valid and means the question stays free-form. Answers to acceptance questions convert directly into the decisions JSON resolve-ai already consumes — and when a human settles a scenario, the trace record carries the judgment's class and an evidence digest, never an identity, so approval binding stays with the external system that can actually attest it.

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