agent-spec-tool-first

# Agent Spec Tool-First Workflow > **Version:** 3.7.0 | **Last Updated:** 2026-07-22 | **Tracks agent-spec:** 1.2.0 (stability promise) You are an expert at using `agent-spec` as a CLI tool for contract-driven AI coding. Help users by: - **Planning**: Render task contracts with `contract`, generate plan context with `plan` - **Implementing**: Follow contract Intent, Decisions, Boundaries - **Verifying**: Run `lifecycle` / `guard` to check code against specs - **Reviewing**: Use `explain` for human-readable summaries, `stamp` for git trailers - **Debugging**: Interpret verification failures and fix code accordingly ## IMPORTANT: CLI Prerequisite Check **Before running any `agent-spec` command, Claude MUST check:** ```bash command -v agent-spec || cargo install agent-spec ``` If `agent-spec` is not installed, inform the user: > `agent-spec` CLI not found. Install with: `cargo install agent-spec` ## Core Mental Model **The key shift**: Review point displacement. Human attention moves from "reading code diffs" to "writing contracts". ``` Traditional: Write Issue (10%) → Agent codes (0%) → Read diff (80%) → Approve (10%) agent-spec: Write Contract (60%) → Agent codes (0%) → Read explain (30%) → Approve (10%) ``` Humans define "what is correct" (Contract). Machines verify "is the code correct" (lifecycle). Humans do final "Contract Acceptance" — not Code Review. ## Quick Reference | Command | Purpose | When to Use | |---------|---------|-------------| | `agent-spec init` | Scaffold new spec | Starting a new task | | `agent-spec contract <spec>` | Render Task Contract | Before coding - read the execution plan | | `agent-spec lint <files>` | Spec quality check | After writing spec, before giving to Agent | | `agent-spec plan <spec> --code .` | Generate plan context | Before coding - codebase scan + task sketch | | `agent-spec lifecycle <spec> --code .` | Full lint + verify pipeline | After edits - main quality gate | | `agent-spec guard --spec-dir specs --code .` | Repo-wide check | Pre-commit / CI - all specs at once | | `agent-spec explain <spec> --format markdown` | PR-ready review summary | Contract Acceptance - paste into PR | | `agent-spec explain <spec> --history` | Execution history | See how many retries the Agent needed | | `agent-spec stamp <spec> --dry-run` | Preview git trailers | Before committing - traceability | | `agent-spec graph --spec-dir specs` | Dependency graph (DOT) | After writing specs - visualize deps & critical path | | `agent-spec requirements graph --gate` | Validate KLL requirements and dependency graph | After importing PRD/issue requirements | | `agent-spec wiki status` | Check stale code live wiki articles | Session start / before broad source reading | | `agent-spec wiki query <text>` | Search tracked live wiki articles | Before opening many source files | | `agent-spec wiki check` | Live wiki lint + worktree status gate | Pre-commit / CI for tracked wiki | | `agent-spec atlas build/tree/query/search/explore/context/flow/impact/affected/refs/impls/status/check/scip-gen` | Rust graph with scored retrieval, bounded context projection, explainable paths, reverse impact, identity, and independent syn/SCIP/MIR freshness; `scip-gen` invokes rust-analyzer for the optional SCIP overlay | Build before querying; use `--frozen` for review, and never infer tests from affected filenames | | `agent-spec atlas benchmark validate/plan/summarize/score` | Validate offline evaluation inputs and gate query-quality observations | Evaluate correctness before performance; default tests do not invoke a model or network | | `agent-spec atlas benchmark agent-plan/agent-gate` | Compile and gate matched Read/Grep, Atlas primitive, and context arms | Real execution is opt-in; a checked-in plan is not adoption evidence | | `agent-spec atlas benchmark serving-plan/serving-gate` | Compile and gate direct/worker burst trials | Keep worker serving opt-in until real evidence is accepted | | `agent-spec atlas provider validate/conformance` | Validate external Code Graph providers and run the F1 conformance matrix | Conformance proves adapter behavior, not language quality | | `agent-spec verify <spec> --code .` | Raw verification only | When you want verify without lint gate | | `agent-spec checkpoint status` | VCS-aware status | Check uncommitted state | ## BDD-spine Commands (0.3.0) agent-spec 0.3.0 absorbs living-spec-library + scaffolding/governance under the BDD-spine model (Discovery → Formulation → Automation). These six commands are additive — **verdict semantics and `is_passing` are unchanged**; every new check is a sensor (lint / report / audit), never a silent change to pass/fail. | Command | Purpose | When to Use | |---------|---------|-------------| | `agent-spec matrix <spec> --code .` | Render the coverage matrix: Rule × Scenario × Test × Verdict × Provenance (`--format text\|json\|markdown`) | See which Rules/Examples are proven by which tests, and whether evidence is Computational vs Inferential | | `agent-spec promote <spec> --rule <id> --to <cap> --code .` | Promote a passing task Rule into `specs/capabilities/<cap>.spec.md` (living-spec library) | When a task Rule has matured and should be reused across tasks. Gate: the Rule's Examples must pass (≥1 example required); the stable `id` never changes | | `agent-spec audit --spec-dir specs` | Aggregate spec-library health: counts, unproven rules, ungrouped scenarios, open questions, malformed rules (`--format text\|json`) | Periodic library health snapshot. **Observability only — never gates** | | `agent-spec discover --from-codebase --code <dir> --name <n> [--out <file>]` | Reverse-engineer a draft task spec from existing test functions (one bound scenario per test + a `## Questions` seed) | Cold-start: a codebase has tests but no spec. The draft is a parseable starting point, NOT a finished contract — refine the seeded Questions | | `agent-spec check-structure --code <dir> --forbid <substr> --in <glob>` | Mechanical layering guard: forbid a reference within a file glob; non-zero exit on violation | Enforce architecture invariants (e.g. `--forbid crate::services --in clients/**`) in CI | | `agent-spec gen-integrations [--target agents\|cursor\|claude\|all] [--out <dir>] [--check]` | Generate per-tool integration files from one source; `--check` exits non-zero on drift | Keep agents/cursor/claude integration files in sync from a single source; use `--check` as a CI drift gate | Notes: - `matrix` shares `verify`'s change-set flags (`--change`, `--change-scope`, `--ai-mode`) and default semantics. - `promote` writes to `specs/capabilities/<name>.spec.md`; the capability name is path-traversal-checked. - `audit` and `check-structure` are mechanical and read-only (no code execution beyond scanning). ## Knowledge & Liveness Layer (0.4.0 KLL) KLL adds a typed **knowledge layer** beside specs: durable `decision` / `requirement` / `guidance` / `proposal` artifacts under `knowledge/`, a `satisfies:` edge from specs back to decisions or requirements, and a **derived liveness** answer to "is this decision/requirement still guarded by the code?" — recomputed from current spec verdicts, never stored. A read-only MCP server serves it all to agents with no RAG. Knowledge lives in `knowledge/`; specs still live in `specs/`. | Command | Purpose | When to Use | |---------|---------|-------------| | `agent-spec init --workspace` | Scaffold the canonical `knowledge/` tree (decisions/requirements/proposals/guidance/context + canon + `.agent-spec/config.yaml`). Idempotent | Once, to lay down the knowledge workspace beside `specs/` | | `agent-spec trace <id> [--gate]` | Trace a decision or requirement id to the specs that `satisfy:` it and report **liveness** (honored / violated / unproven / n/a). `--gate` exits 2 on violated, warns on unproven | Check whether a recorded knowledge artifact is still enforced by passing specs; use `--gate` in CI | | `agent-spec lint-knowledge [--format text\|json\|sarif] [--gate]` | Lint the knowledge corpus: per-doc rules + governance (id-conflict, supersession integrity, stale refs). `--gate` exits 2 on any Error | Governance gate for the knowledge base; `--format sarif` feeds GitHub Code Scanning | | `agent-spec requirements transition <ID> --to <status>` / `requirements supersede <ID> --by <NEW>` | Explicit human governance transitions (proposed→accepted/rejected, accepted→deprecated, atomic supersession); missing status fails `graph --gate`; `--format json` emits digest-bearing machine output (facts only — no actor/authority fields; external systems bind approvals to digests) | Accept requirements before lowering; compilation never mutates status | | `agent-spec requirements status <ID>` | Three-axis report: governance / execution / liveness with spec evidence | "Where is REQ-X?" in one command | | `agent-spec requirements traceability <ID> [--format json\|text] [--out <file>]` | Deterministic projection of one requirement's evidence chain: clauses → satisfying specs → scenarios → bound tests → latest recorded verdicts → derived liveness; a pure read over stored trace records | Feed dashboards/orchestrators one byte-stable JSON document instead of re-deriving the join | | `agent-spec requirements <graph\|plan\|work-units\|test-obligations\|traceability> --out <f> --provenance <m>.json` | Emit a compilation-run manifest (v2): compiler build commit + effective config + blake3 input/output digests | Record any artifact-emitting compilation as reproducible, auditable work | | `agent-spec requirements verify-run --manifest <m>.json` | Replay the recorded compilation in memory and byte-compare against recorded digests; non-zero exit names every drifted output | Prove a recorded compilation still reproduces — determinism as an executable check | | `agent-spec requirements compile --out <dir> [--id REQ-*] [--layout agent-spec-v1\|arc-v1] [--force]` | Per-requirement bundles (requirement doc + draft spec + traceability + compilation manifest with bundle digest); atomic writes, overwrite refusal without `--force`; `arc-v1` projects reference-compatible file names over the same content | Hand orchestrators/consumers a pinned, replayable bundle; covers accepted requirements whose work unit is ready (cold-start compile path) | | `agent-spec requirements bind [--code .] [--graph .agent-spec/graph] [--out .agent-spec/code-bindings.json]` | Bind ready work units' declared `### Symbols` to code targets resolved in the provider graph (rust-atlas first); stale graph fails naming lagging files; bindings are derived working data, never KLL truth | Ground work units in real symbols before contract finalization (boundary 2 of the target architecture) | | Contract `### Symbols` (`- rust-atlas: <path>`) | Lifecycle validates every declared symbol against a fresh graph: `atlas-symbol-missing` / `atlas-stale` (stale wins, no false positives); valid = silent; no symbols = no graph needed. Passing runs persist typed code targets (provider/node/kind/file/provenance/fingerprint) into trace evidence | Pin a contract to real code symbols; the Linker turns "the symbol no longer exists" into a mechanical diagnostic | | `agent-spec requirements bundle --unit WU-REQ-X --out bundle.json` | One complete execution context: work unit + embedded contracts (digested) + code bindings + quality profile (argv arrays, normalized outcomes — required-unavailable never passes) + skill receipts (provenance, not acceptance) + fast checks + acceptance gates | Hand an agent everything it needs for one work unit in a single pinnable artifact (boundary 4) | | `agent-spec requirements export --out requirements.yaml` | YAML projection of confirmed requirements (round-trip fixpoint, `--check` drift gate) | Interop with YAML-world tooling; derived, never source of truth | | `agent-spec requirements import/graph/work-units/draft-specs` | Convert marked PRD/issue requirement blocks into KLL artifacts, validate the graph, generate executable work units, and draft Task Contracts with `satisfies: [REQ-*]` | Use when raw product requirements need to become verifiable agent-spec work | | `agent-spec mcp` | Serve the knowledge layer over MCP (JSON-RPC 2.0 over stdio, read-only, deterministic) | Wire into an MCP client so agents query knowledge live | | `agent-spec gen-integrations --with-guidance <knowledge>` | Project `guidance/` artifacts into the generated CLAUDE.md/AGENTS.md/.cursorrules | Push stack/path-scoped guidance into agent tool config | Requirements intake flow: ```bash agent-spec requirements import --from docs/prd.md --out knowledge/requirements agent-spec requirements import --from requirements.yaml --out knowledge/requirements 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 ``` `requirements import` reads explicit `<!-- agent-spec:requirement ... -->` Markdown blocks, or the constrained YAML dialect for `.yaml`/`.yml` sources (`docs/intent-compiler/yaml-frontend-v1.md`); it never interprets raw prose. Marked blocks need blocks with `id` and `title`. Generated Task Contract drafts are review artifacts: they carry `satisfies: [REQ-*]` and placeholder `pending_...` test selectors, so `lifecycle` is expected to fail until a human binds real tests. ### `docs/` vs `knowledge/` Use `docs/` for human-facing explanatory material: PRDs, issue writeups, design notes, plans, retrospectives, tutorials, and background context. `docs/` files do not need stable IDs or KLL frontmatter, and `trace`, `lint-knowledge`, and `requirements graph` do not treat them as governed truth. Use `knowledge/` for machine-consumable project truth: durable decisions, requirements, guidance, and proposals with typed frontmatter (`kind`, `id`, `title` when required, `liveness`) and lintable sections. Specs connect to these artifacts with `satisfies: [ADR-*|REQ-*]`; `trace` can then answer whether code still guards them. Pipeline rule: raw PRD/issue material may start in `docs/`, but executable work must be derived from imported `knowledge/requirements/*.md`, not directly from raw prose. Exception: `knowledge/context/` is a free-form KLL escape hatch served by MCP, but it is untyped, unlinted, and not trace-gated. The six MCP tools (deterministic, no RAG): `knowledge.find`, `knowledge.governing` (decisions guarding a path via satisfying-spec boundaries + live liveness), `liveness.status`, `spec.contract`, `guidance.for`, `context.read`. Liveness ladder (precedence, total): declared `n/a` → `na`; any satisfying spec `Fail` → `violated`; none or any not-`Pass` → `unproven`; all `Pass` → `honored`. Liveness is **never stored** — always recomputed. ## Code Live Wiki Use the wiki commands to maintain a repo-local code live wiki from raw source, KLL artifacts, Task Contracts, docs, archive summaries, and lifecycle trace evidence. The default path is `.agent-spec/wiki`. ```bash 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 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 wiki meta update --code . --wiki .agent-spec/wiki ``` Wiki pages are tracked agent working memory under `.agent-spec/wiki/**`, not KLL truth and not published docs. Every maintained article must declare