agent-spec-tool-first

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.1 | Last Updated: 2026-08-14 | Tracks: agent-spec 1.4.0

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 the E0 corpus, compile paired Atlas/baseline plans, summarize fully graded receipts, or score strict E3 query observations	Evaluate correctness before performance. Default tests probe current fixtures without network access. See docs/atlas-evaluation.md
agent-spec atlas benchmark agent-plan/agent-gate	Compile matched Read/Grep, Atlas primitive, and B5 context arms; gate strict complete receipts	Keep all failures and query metrics. B/A and C/B are independent. Real execution is opt-in and external. See docs/atlas-agent-ab-gate.md
agent-spec atlas benchmark serving-plan/serving-gate	Compile and gate four-profile direct/worker burst trials	Require a pinned non-fixture repository. The disabled template and D4 fixture matrix are not promotion evidence. See docs/atlas-agent-ab-gate.md
agent-spec atlas provider validate/conformance	Validate an external Code Graph manifest/registration or run the F1 conformance matrix	Keep providers project-configured and opt-in. Conformance proves adapter behavior, not language quality. See docs/code-graph-provider-kit.md
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

Atlas Workflow

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 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

For E1, never infer a passing result from a checked-in plan. Run the explicit external driver, retain every run and raw-session hash, then gate the complete receipt. Treat machine passed as a candidate for human acceptance, not as an instruction to change MCP discovery, B5 profiles, or worker defaults.

atlas build publishes one complete committed generation; all read surfaces pin and report that generation. Content-addressed Cargo input plans accept --features, --target, and repeatable --cfg. Incremental source edits use a bounded reverse-dependent frontier; configure --frontier-limit, --batch-size, and --working-byte-limit. A healthy zero-change build does no resolution, validation, staging, or authority rewrite. Cancellation and build failure preserve the old generation and orphan work for a later recovery build. Automatic refresh reuses committed Cargo inputs; capability changes use an explicit full-frontier fallback. The optional D3 watcher/daemon wraps these D2 build primitives, persists a pending watermark and exposes typed degraded state. Writer-lock and ordinary failures have separate bounded retries. Queries hold a reader lease until their immutable generation read ends; ambiguous leases prevent reclamation. MCP discovery and no-daemon queries remain deterministic. Live state never replaces graph freshness, KLL, or lifecycle authority. See docs/atlas-incremental-builds.md and docs/atlas-live-runtime.md.

D4 query workers are an opt-in prototype. Start the daemon with --query-workers 2, inspect daemon service-status, and invoke atlas context --execution worker. Keep direct mode for default, CI, and single-Agent use. Preserve typed queue, deadline, memory, cancellation, panic, circuit, fallback, generation, and lease receipts; worker mode cannot make a stale graph fresh. See docs/atlas-concurrent-query-serving.md.

status reports recorded/current graph identity and the three layer states; syn fresh is not authority for a stale SCIP or MIR layer. Rebuild after atlas-schema-mismatch or an atlas-query-index-* diagnostic. A borrowed worktree graph or stale available semantic layer cannot produce definitive provider, binding, lifecycle-symbol, or typed trace evidence. Atlas graph shards, the query index, and bindings are derived working data, not KLL truth.

Compact/deep explore budgets are fixed at 8/32/48/8/4/20/16,000 and 16/96/160/20/12/40/24,000 for seeds, nodes, edges, paths, excerpts, excerpt lines, and bytes. Excerpts require current source hashes. Treat flow states (found, no-path, capability-unavailable, truncated, unknown-endpoint, ambiguous-endpoint) as distinct. A fresh disconnected flow may include bounded runtime_boundaries; they explain async, channel, callback, reflection, or route boundaries as heuristic query hints and never become graph, impact, binding, lifecycle, or archive evidence. See docs/atlas-runtime-boundaries.md. affected requires one explicit, stdin, staged, worktree, or commit-range input and reports graph evidence, not inferred tests.

Use atlas context when the Agent needs a bounded, receipt-bearing projection rather than the legacy compact/deep explore shape. Pick one explicit symbol | flow | architecture | impact profile. Inspect both receipt.retrieval and receipt.projection; an omission is not a retrieval miss. Follow omissions[].continuation.argv literally with its graph fingerprint. Never hide required-evidence overflow, stale source, or cursor errors. Context output is derived working data and is not a default MCP tool; see docs/atlas-query-context.md.

MCP uses frozen, read-only Atlas reads. The default tool list omits atlas_search; start agent-spec mcp with AGENT_SPEC_MCP_ATLAS_SEARCH=1 to list it. atlas_explore is unavailable unless AGENT_SPEC_MCP_ATLAS_EXPLORE=1; keep the default surface until a real Agent A/B gate passes. atlas_context requires AGENT_SPEC_MCP_ATLAS_CONTEXT=1; its concurrent route additionally requires AGENT_SPEC_MCP_ATLAS_QUERY_MODE=worker. Keep both opt-in until that gate.

For external Code Graph providers, run atlas provider validate before any execution and atlas provider conformance before integration. Keep extractor and semantic-enricher artifacts separate. Reject stale/partial promotion, wrong-worktree responses, unsafe paths, unscoped ids, missing evidence, unknown schemas, output overflow, timeout, and cancellation. A fixture pass is not F2 language support or permission to auto-enable the provider.

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)