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