agent-spec-authoring

# Agent Spec Authoring > **Version:** 3.6.0 | **Last Updated:** 2026-08-14 | **Tracks:** agent-spec 1.4.0 ## Routing: What You Hold, Where It Goes Before writing anything, route the artifact. This table copies `knowledge/standards/operational/id-registry.md` — the registry is the authority, this copy is checked against it in CI. | You hold | Directory | Id prefix | Scaffold | |---|---|---|---| | A debate: should we do this, and why | `knowledge/proposals/` | `LEP-` | `agent-spec knowledge new proposal LEP-NNN` | | A settled architectural ruling | `knowledge/decisions/` | `ADR-` | `agent-spec knowledge new decision ADR-NNN` | | An obligation the system must satisfy | `knowledge/requirements/` | `REQ-` | `agent-spec knowledge new requirement REQ-NNN` | | An executable, verifiable task contract | `specs/` | `task-` | `agent-spec init --level task` | HARD GATE: when the workspace has a `knowledge/requirements/` corpus, do NOT write a task contract without `satisfies: [REQ-*]` — the orphan-spec lint diagnoses the jump. "This is just a small task" and "I'll link it later" are the rationalizations that produced orphan contracts before; route first, then write. You are an expert at writing agent-spec Task Contracts. Help users by: - **Creating specs**: Scaffold new `.spec.md` files with correct structure (`.spec` also supported) - **Editing specs**: Improve intent, constraints, boundaries, scenarios - **Writing scenarios**: BDD-style with proper test selectors and step tables - **Debugging specs**: Fix lint warnings, improve quality scores - **Self-hosting**: Maintain specs for the agent-spec project itself ## 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 Philosophy A Contract is **not a vague Issue** — it's a precise specification that shifts the review point: ``` Traditional: Human reviews 500 lines of code diff (slow, error-prone) agent-spec: Human writes 50-80 lines of Contract (fast, high-value) Machine verifies code against Contract (deterministic) ``` Writing a Contract is the **highest-value human activity** in the agent-spec workflow. You're defining "what is correct" — the machine handles "is the code correct". ## Quick Reference | Section | Chinese Header | English Header | Purpose | |---------|---------------|----------------|---------| | Intent | `## 意图` | `## Intent` | What to do and why | | Constraints | `## 约束` | `## Constraints` | Must / Must NOT rules | | Decisions | `## 已定决策` / `## 决策` | `## Decisions` | Fixed technical choices | | Boundaries | `## 边界` | `## Boundaries` | Allowed / Forbidden / Out-of-scope | | Acceptance Criteria | `## 验收标准` / `## 完成条件` | `## Acceptance Criteria` / `## Completion Criteria` | BDD scenarios | | Out of Scope | `## 排除范围` | `## Out of Scope` | Explicitly excluded items | | Questions (Discovery) | `## 问题` / `## 待澄清` | `## Questions` | Unresolved items to clarify (Phase 4; non-blocking) | ## Hard Syntax Rules - Use exactly one supported section header per line. Good: `## Intent` or `## 意图`. Bad: `## Intent / 意图`. - Write scenarios as bare DSL lines under the acceptance section. Good: `Scenario:` / `场景:`. The parser accepts Markdown-heading forms like `### Scenario:` for compatibility, but authoring should avoid emitting them by default. - Do not invent extra top-level sections such as `## Architecture`, `## Milestones`, or `## Quality` inside a task spec. Put that information into `Intent`, `Decisions`, `Boundaries`, or an external document. - After drafting or editing a spec, always run `agent-spec parse <spec>` and then `agent-spec lint <spec> --min-score 0.7`. ## Documentation Refer to the local files for authoring patterns and examples: - `./references/patterns.md` - Complete authoring patterns with examples ## IMPORTANT: Documentation Completeness Check **Before answering questions, Claude MUST:** 1. Read `./references/patterns.md` for authoring patterns 2. If file read fails: Inform user "references/patterns.md is missing, answering from SKILL.md patterns" 3. Still answer based on SKILL.md patterns + built-in knowledge ## Required Self-Check After writing or editing a spec: ```bash agent-spec parse specs/task.spec.md agent-spec lint specs/task.spec.md --min-score 0.7 ``` Do not hand a spec to an agent if: - `agent-spec parse` shows `Acceptance Criteria: 0 scenarios` - lint reports missing explicit test selectors - lint score is below threshold ## Behavior Surface Checklist When authoring a contract for CLI tools, MCP servers, protocols, or parity rewrites, do not stop at the main happy path. Check these observable surfaces explicitly: ### Observable Behavior - stdout vs stderr behavior - `--json` or machine-readable output - `-o/--output` and file side effects - local vs remote behavior - warm cache vs cold start - fallback / precedence order - partial failure vs hard failure - on-disk state changes and persisted files ### Flag Combinations (lint: `flag-combination-coverage`) - Multi-value parameters (multi-ID, batch) combined with output flags - Single vs multiple entry behavior for `-o`, `--full`, `--json` - If your command has 2+ output-affecting flags, add at least one scenario that tests a combination ### Platform-Specific Decisions (lint: `platform-decision-tag`) - When copying decisions from a reference implementation, tag platform-specific terms - Use markers like `[JS-only]`, `[platform-specific]`, or `不适用` to flag phantom requirements - The linter flags untagged references to npm, pip, cargo install, dist/, bundled dist, etc. ### Architectural Invariants - If the reference implementation uses a specific processing pattern (e.g., "collect all results then output once"), state this as a decision — per-item vs batch output are architecturally different - These invariants are invisible to per-feature tests but break on combinations If the task is a rewrite, migration, or parity effort, treat this as mandatory. The matrix is not required for ordinary incremental tasks — do not flag a plain feature contract as missing parity coverage. Do not hand the contract to an agent until these observable behaviors are either: - covered by scenarios, or - explicitly declared out of scope For these tasks, prefer starting from the parity-aware scaffold instead of the generic task template: ```bash agent-spec init --level task --template rewrite-parity --lang en --name "CLI Parity Contract" ``` ## Before Writing a Contract Not every task needs a Contract. Ask yourself: | Question | If No | |----------|-------| | Can I define what "done" looks like? | Vibe code first, write Contract later | | Can I write at least one deterministic test? | Not Contract-ready yet | | Is the scope bounded enough to list Allowed Changes? | Split into smaller tasks | | Do I know the key technical decisions? | Do a spike/prototype first | If all "yes" — proceed with authoring. If not, doing exploratory work first is the right call. ## The Four Elements of a Contract ### 1. Intent — What and Why One focused paragraph. Not a feature list — a clear statement of purpose. ```spec ## Intent 为现有的认证模块添加用户注册 endpoint。新用户通过邮箱+密码注册， 注册成功后发送验证邮件。这是用户体系的第一步，后续会在此基础上 添加登录和密码重置。 ``` **Rules:** - Focus on "what to do and why" - Mention context (what already exists, where this fits) - Keep it to 2-4 sentences - Do not combine bilingual section labels on the same header line ### 2. Decisions — Fixed Technical Choices Already-decided choices. Not aspirational. Not options to explore. ```spec ## Decisions - 路由: POST /api/v1/auth/register - 密码哈希: bcrypt, cost factor = 12 - 验证 Token: crypto.randomUUID(), 存数据库, 24h 过期 - 邮件: 使用现有 EmailService，不新建 ``` **Rules:** - Only choices that are **already fixed** — not "we should consider..." - Include specific technologies, versions, parameters - Agent follows these without questioning — they're not open for debate - **Every decision should be covered by at least one scenario** — lint warns if a decision has no matching scenario (checked by `decision-coverage` linter via backtick identifiers and keywords) - **Avoid universal claims without proportional coverage** — if a decision says "all entry points" or "every binary", lint (`universal-claim`) requires 2+ scenarios to verify each instance ### 3. Boundaries — What to Touch, What Not to Touch Triple constraint: Allowed, Forbidden, Out-of-scope. ```spec ## Boundaries ### Allowed Changes - crates/api/src/auth/** - crates/api/tests/auth/** - migrations/ ### Forbidden - 不要添加新的 npm/cargo 依赖 - 不要修改现有的登录 endpoint - 不要在注册流程中创建 session ## Out of Scope - 登录功能 - 密码重置 - OAuth 第三方登录 ``` **Rules:** - Path globs (`crates/auth/**`) are **mechanically enforced** by BoundariesVerifier - Natural language prohibitions are checked by lint but not file-path enforced - Out of Scope prevents scope creep — Agent knows what NOT to attempt - **If Boundaries list 2+ entry points** (e.g. `bin/cli.rs`, `bin/server.rs`), lint (`boundary-entry-point`) warns if scenarios don't reference each one — shared logic across entry points needs separate verification ### 4. Completion Criteria — Deterministic Pass/Fail BDD scenarios with explicit test bindings. **Critical principle: Exception scenarios >= happy path scenarios.** Lint enforces this — the `error-path` linter warns if all scenarios are happy paths with no error/failure path. ```spec ## Completion Criteria 场景: 注册成功 ← 1 happy path 测试: test_register_returns_201 假设 不存在邮箱为 "alice@example.com" 的用户 当 客户端提交注册请求: | 字段 | 值 | | email | alice@example.com | | password | Str0ng!Pass#2026 | 那么 响应状态码为 201 并且 响应体包含 "user_id" 场景: 重复邮箱被拒绝 ← exception path 1 测试: test_register_rejects_duplicate_email 假设 已存在邮箱为 "alice@example.com" 的用户 当 客户端提交相同邮箱的注册请求 那么 响应状态码为 409 场景: 弱密码被拒绝 ← exception path 2 测试: test_register_rejects_weak_password 假设 不存在邮箱为 "bob@example.com" 的用户 当 客户端提交密码为 "123" 的注册请求 那么 响应状态码为 400 场景: 缺少必填字段 ← exception path 3 测试: test_register_rejects_missing_fields 当 客户端提交缺少 email 字段的注册请求 那么 响应状态码为 400 ``` This forces you to think through edge cases **before coding begins**. The Agent can't skip error handling because each exception path has a bound test. ## Rewrite / Parity Contracts For rewrite, migration, and parity tasks, write a behavior matrix before writing scenarios. At minimum, ask whether the contract covers: - command x output mode - local x remote - warm cache x cold start - success x partial failure x hard failure - CLI x MCP entry points, if both are user-visible If these dimensions matter to the task, they should appear in scenarios, not only in Decisions. ## BDD-spine Authoring (0.3.0) agent-spec 0.3.0 organizes authoring around Discovery → Formulation → Automation. These constructs are additive — they never change verdict semantics. `Example` is a synonym for `Scenario` (Cucumber alignment). ### Rule → Example grouping Group related scenarios under a `Rule:` / `规则:` — a promise the system keeps, proven by one or more Examples. A Rule has a **stable kebab-case id** (used for references and promotion) and a mutable display name: ```spec ## Completion Criteria ### Rule: reject-invalid-input — 拒绝非法输入 场景: 空邮箱被拒绝 测试: test_rejects_empty_email 当 提交空邮箱 那么 返回 400 场景: 弱密码被拒绝 测试: test_rejects_weak_password 当 提交密码 "123" 那么 返回 400 ``` - The id is the leading kebab-case token (`reject-invalid-input`); it is separated from the display name by an **em dash `—`** or **two-or-more spaces** (the parser recognizes only these two separators — a plain `--` is NOT a separator and would be swallowed into the id, tripping `bdd-rule-id`). **Never encode identity in the display name** — rename freely, the id is the anchor. - `bdd-rule-id` lints malformed (non-kebab-case) ids; `bdd-rule-grouping` nudges ungrouped scenarios. A scenario binds to a Rule via `规则:` / by sitting under the Rule header. - A Rule with no proving Example is "unproven" (surfaces in `audit`). ### Discovery: `## Questions` Before a contract is fully formed, capture unresolved items in a `## Questions` (`## 问题` / `## 待澄清`) section — bullet list. These are **non-blocking** (`open-question` lint is Info/Warning, never an Error; they do NOT affect `is_passing`). Mark resolved items with `[x]` / `[已解决]` / `RESOLVED`. ```spec ## Questions - 折扣能否叠加? - [x] 退款按折后价(已确认) ``` `agent-spec discover --from-codebase` seeds this section when reverse-engineering a spec from tests — a cold-start draft is honestly "known-incomplete". ### lint-ack: acknowledging a warning with a reason When a lint Warning/Info is a deliberate, justified exception, acknowledge it inline **with a mandatory reason** instead of distorting the spec: ```spec <!-- lint-ack: error-path — 本任务是只读查询,无失败路径 --> ``` - Format: `<!-- lint-ack: <code> — <reason> -->`. After `lint-ack:`, the code and reason **must** be separated by an em dash `—` or a colon `:` — without one, the whole string is parsed as the code and nothing is acknowledged. - Acknowledged lints are filtered from the report but **counted** (visible in `audit`) — the waiver is on the record, not silenced. - **Errors can never be acknowledged** — only Warning/Info. A mechanical hard failure is not negotiable. ### capability specs and promotion A matured, reusable Rule can be promoted out of a task spec into a capability spec (`spec: capability`, the living-spec library) via `agent-spec promote <task> --rule <id> --to <cap> --code .`. The promote gate requires the Rule's Examples to pass (≥1 example). Authoring notes: - Capability specs use header `spec: capability`; a task can declare which capability it contributes to with a `capability:` frontmatter field. - Promotion preserves the Rule's `id` — task references stay valid. - In a capability spec, an empty Rule (no Example yet) is allowed but flagged unproven by `audit`. ### Provenance (read when reviewing the matrix) `agent-spec matrix` stamps each result's evidence provenance: `Computational` (mechanical — tests, structural, boundary) vs `Inferential` (AI). When authoring, prefer scenarios provable by Computational evidence; reserve AI-only scenarios for genuinely non-mechanical intent, and never let Inferential evidence default to pass. ## KLL Requirement Authoring (0.4.0) Task Contracts now sit beside a typed knowledge layer. When authoring: - Link a contract to its requirement with frontmatter `satisfies: [REQ-*]`. - Requirement documents live in `knowledge/requirements/req-*.md` with `kind: requirement`, a stable `id`, a governance `status` (`proposed | accepted | superseded | deprecated | rejected` — missing status fails the governance gate), `## Problem`, `## Requirements` with `[REQ-<DOC>-<SUFFIX>] ... MUST ...` single-obligation clauses, optional `## Scenarios` (needed for work units to become ready), `## Dependencies`, and a concrete `## Source Trace`. - Humans change governance status with `agent-spec requirements transition <ID> --to <status>` — not by hand-editing