/agent-spec-authoring

name: agent-spec-authoring
description: |
  CRITICAL: Use for writing and editing agent-spec .spec/.spec.md files. Triggers on:
  write spec, create spec, edit spec, new spec, spec authoring, task contract,
  .spec file, .spec.md file, BDD scenario, acceptance criteria, completion criteria,
  test selector, boundary, constraint, intent, decision, out of scope,
  "how to write a spec", "spec format", "spec syntax", "contract quality",
  写 spec, 创建规格, 编辑合约, 任务合约, 验收标准, 完成条件,
  BDD 场景, 测试选择器, 约束, 意图, 决策, 边界, 排除范围,
  "怎么写 spec", "spec 格式", "spec 语法", "合约质量"

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

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:

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 combin