The intent compiler（意图编译器）for AI coding: intent compiles into
requirement IR, Rust source compiles into a queryable code graph, and every
contract in between is verified by machines.
Humans define intent. Agents implement. Nothing ships unverified.
Traditional code review asks humans to judge 500 lines of code diff. agent-spec moves the review point: humans define 50 lines of contract, and machines verify the code against it.
Issue → Branch → Code → PR → Read Diff (80%) → Approve
Contract (60%) → Agent Codes → Explain → Approve
Human time shifts from "reading code" to "defining intent" — a higher-value activity. Quality assurance shifts from "human judgment" to "machine verification".
Two independent IRs: human intent compiles into the Requirement IR (human-owned KLL truth) while Rust source compiles into the Code Graph IR (derived, stale-aware, via Rust Atlas). The Intent-Code Linker joins them into a verifiable plan DAG — derived code facts never rewrite accepted requirements, and liveness feeds verdicts back to the knowledge that produced them. AI works only at the edges; every gate is deterministic.
0.6.0: every box above is shipped — dual IRs, governance / status / liveness gates, the orchestrator machine surface, and the Intent-Code Linker (contract symbols · typed trace targets · execution bundles) (architecture)
Agents stop grepping and start querying. rust-atlas (a standalone crate,
embedded as agent-spec atlas) compiles Rust source into the Code Graph IR:
modules, types, traits, impls, calls — extracted with syn on stable,
stored as per-file shards with blake3 hashes, optionally sharpened by a SCIP index.
Every edge carries provenance; every read can demand freshness.
Deterministic module outlines and symbol adjacency from syn —
no nightly, no rustc plugin. Shards rebuild only when their
file hash changes, so re-indexing a large repo costs one file, not the world.
Every shard records the blake3 of the source it came from.
atlas check fails CI when the graph lags the code, and
--frozen makes reads refuse silently-stale answers.
agent-spec mcp exposes atlas_tree, atlas_query,
atlas_refs, atlas_impls, atlas_status —
any MCP client asks "who calls this?" and gets provenance-stamped edges, not grep hits.
agent-spec ships project-local Skills that teach AI agents the contract-driven workflow. One install command — works with Claude Code, Codex, Cursor, Aider, and any agent that reads workspace conventions.
The default integration path. Teaches the Agent the seven-step workflow: read the Contract, implement within Boundaries, run lifecycle for verification, retry on failure, generate explain for review. CLI commands are the primary interface.
The spec writing path. Teaches the Agent how to draft and revise Task Contracts in the DSL — four elements structure, bilingual keywords, test selectors, step tables, and the "exception paths ≥ happy paths" principle.
The estimation path. Maps Task Contract elements — scenarios, decisions, boundaries — to round-based effort estimates with risk coefficients. Produces breakdown tables, wallclock projections, and confidence levels.
The intake path. Turns unstructured PRDs and issues into human-reviewed Candidate Requirement Blocks — with source excerpts, confidence, scenarios, and open questions — that the deterministic Intent Compiler then imports.
The working-memory path. Maintains the repo-local code live wiki: stale-article detection, source-traced module and concept pages, architecture inventories, and cross-project maps.
A Contract is not a vague Issue. It's a precise specification with four parts that constrain the Agent's behavior and define deterministic acceptance criteria.
A focused statement of purpose. Not a feature list — a clear direction that gives the Agent context.
Already-decided choices that remove the Agent's decision space. The Agent follows these without questioning.
Path globs are mechanically enforced by the BoundariesVerifier. Natural language prohibitions are checked by lint.
BDD scenarios with explicit test bindings. Key rule: exception paths ≥ happy paths.
Human writes intent. Agent implements code. Machine verifies correctness. Each step has a clear owner and a specific agent-spec command.
Deterministic layers run first — zero token cost, no false negatives. AI layers handle the residual — probabilistic, with structured evidence.
Key rule: skip ≠ pass
— all four verdicts are semantically distinct.
Mechanical verifiers handle deterministic checks. For the rest, agent-spec supports two modes: the calling Agent does the review, or an injected backend does it.
The calling Agent (Claude Code, Codex…) performs AI verification itself. agent-spec emits structured requests; the Agent returns structured decisions.
AiRequest[]AiDecision[]uncertain findingsAn independent AI backend is injected via the Rust API. Ideal for orchestrator systems (Symphony-like) using a different model for verification.
AiBackendbackend.analyze()AiDecision
Both modes share the same data structures: AiRequest and
AiDecision.
agent-spec stays provider-agnostic.
Constraints and decisions inherit downward. Organization rules flow through project conventions into every task contract. Write once, enforce everywhere.
Contracts verify tasks. KLL makes the knowledge around them durable:
decisions and requirements live under knowledge/, specs link back with
satisfies:, and 0.4.0 adds real governance — explicit human transitions,
a three-axis status query, a YAML projection that round-trips, and provenance manifests
for every compilation. Liveness stays recomputed — never stored, never stale.
Status is a real state machine: proposed → accepted | rejected,
accepted → deprecated, supersession atomic across both documents.
Missing status fails plan --gate. Transitions are explicit
human commands with line-precise rewrites — compilation never mutates governance.
One query, three independent axes: governance (persisted), execution ladder
(unplanned → … → verified → archived), and liveness recomputed from
current verdicts — honored, violated, or unproven.
agent-spec requirements status REQ-001 answers all three.
A side entrance in, a projection out. requirements import --from reads a
YAML requirement tree; export --out writes one back, with
--check as a drift gate. Round-trip is a fixpoint — and the hand-written
Markdown under knowledge/requirements/ stays the only source of truth.
Every import/export can emit a manifest: blake3 digests of inputs and outputs plus tool identity. Re-run the compilation, compare manifests, and drift has nowhere to hide — requirement compilation becomes reproducible, auditable work.
A tracked, source-traced wiki under .agent-spec/wiki: module and concept
pages, staleness detection, architecture inventory, cross-project maps —
agent working memory that lint keeps honest.
agent-spec mcp serves knowledge, liveness, contracts, guidance, and the
Rust Atlas graph over JSON-RPC — deterministic tools, no RAG, so any MCP client
queries project truth live instead of re-reading files.
The contract loop verifies one task. The intent compiler loop governs the requirements above it. Both are plain CLI — no server, no lock-in.