| name | agent-spec-tool-first |
| description | CRITICAL: Use for agent-spec CLI tool workflow. Triggers on:
agent-spec, contract, lifecycle, guard, verify, explain, stamp, checkpoint, plan,
requirements, work-units, knowledge requirements, KLL, docs vs knowledge,
spec verification, task contract, spec quality, lint spec, run log,
"how to verify", "how to use agent-spec", "spec failed", "guard failed",
contract review, contract acceptance, PR review, code review workflow,
plan context, codebase scan, task sketch, implementation plan,
合约, 验证, 生命周期, 守卫, 规格检查, 质量门禁, 合约审查, 计划,
"验证失败", "怎么用 agent-spec", "spec 不通过", "工作流"
|
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:
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:
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.
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
