Version: 3.1.0 | Last Updated: 2026-03-08

agent-spec

• Planning: Render task contracts before coding with

  contract

• 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

• ./references/commands.md

  - Complete CLI command reference with all flags

1. Read

   ./references/commands.md

   for exact command syntax
2. If file read fails: Inform user "references/commands.md is missing, answering from SKILL.md patterns"
3. Still answer based on SKILL.md patterns + built-in knowledge

agent-spec contract specs/user-registration.spec

• Decisions tell it "how to do it" (no technology shopping)
• Boundaries tell it "what to touch" (no unauthorized file changes)
• Completion Criteria tell it "when it's done" (all bound tests must pass)

agent-spec lifecycle specs/user-registration.spec \
  --code . --change-scope worktree --format json --run-log-dir .agent-spec/runs

1. lint — re-check Contract quality (prevent spec tampering)
2. StructuralVerifier — pattern match Must NOT constraints against code
3. BoundariesVerifier — check changed files are within Allowed Changes
4. TestVerifier — execute tests bound to each scenario

Agent retry loop (no human needed):
  Code → lifecycle → FAIL (2/5) → read failure_summary → fix → lifecycle → FAIL (4/5) → fix → lifecycle → PASS (5/5) ✓

1. Run:

   agent-spec lifecycle <spec> --code . --format json

2. Parse JSON output, find each scenario's

   verdict

   and

   evidence

3. For

   fail

   : the bound test ran and failed — read evidence to understand why, fix code
4. For

   skip

   : the bound test was not found — check

   Test:

   selector matches a real test name
5. For

   uncertain

   : AI verification pending — review manually or enable AI backend
6. Fix code based on evidence. Do NOT modify the spec file — changing the Contract to make verification pass is sycophancy, not a fix
7. Re-run lifecycle
8. After 3 consecutive failures on the same scenario, stop and escalate to the human

agent-spec explain specs/user-registration.spec --code . --format markdown

1. Is the Contract definition correct? (Intent, Decisions, Boundaries make sense?)
2. Did all verifications pass? (4/4 pass including error paths?)

agent-spec explain specs/user-registration.spec --code . --history

1. Run

   agent-spec explain <spec> --code . --format markdown

   and present the output
2. If human asks about retry history: run with

   --history

   flag
3. If human asks about specific failures: run

   agent-spec lifecycle <spec> --code . --format json

   and extract the relevant scenario results
4. If human approves: run

   agent-spec stamp <spec> --code . --dry-run

   and present the trailers

--ai-mode caller

agent-spec lifecycle specs/task.spec --code . --ai-mode caller --format json

• "ai_pending": true

• "ai_requests_file": ".agent-spec/pending-ai-requests.json"

AiRequest

[
  {
    "scenario_name": "场景名称",
    "model": "claude-agent",
    "confidence": 0.92,
    "verdict": "pass",
    "reasoning": "All steps verified by code analysis"
  }
]

agent-spec resolve-ai specs/task.spec --code . --decisions decisions.json

• When the calling Agent (Claude, Codex, etc.) can read and reason about code
• For scenarios that can't be verified by tests alone (design intent, code quality)
• When you want the Agent to be both implementor and verifier

• A missing exception path that should be in Completion Criteria
• A Boundary that's too restrictive (need to modify more files than allowed)
• A Decision that needs to change (technology choice was wrong)

agent-spec-authoring

agent-spec lint

• Embedding

  agent-spec

  into another Rust agent runtime
• Testing

  spec-gateway

  internals
• Injecting a host

  AiBackend

  via

  verify_with_backend(Arc<dyn AiBackend>)