| name | spec-authoring |
| description | Standard for authoring engineering behavior-contract specs in docs/specs/: scope subsystems, assign stable IDs, structure docs, manage lifecycle. |
| version | 1.0.0 |
| category | documentation |
| agent_types | ["engineer","documentation"] |
| tags | ["specification","spec","authoring","engineering","standards"] |
| effort | medium |
| user-invocable | true |
| progressive_disclosure | {"entry_point":{"summary":"Author engineering specs in docs/specs/ using the SPEC-{SUBSYSTEM}-{NN}~{rev} grammar, a behavior-contract template, and a defined lifecycle. Specs are engineering-owned and implement PRD requirements.","when_to_use":"When creating a new docs/specs/{subsystem}.md file, adding spec sections, deciding granularity, establishing a new subsystem, or running pre-spec technical research.","quick_start":"1. Read docs/specs/README.md for ID grammar 2. Pick/create the subsystem file 3. Apply the spec template 4. Cite the PRD requirement realized 5. Link implementing modules 6. Run the CI traceability check"},"references":["spec-template.md","category-taxonomy.md","granularity-guide.md","research-conventions.md","authoring-workflow.md"]} |
Spec Authoring
Overview
This skill is the agent-facing entry point to the Engineering Spec Authoring Standard:
how to write engineering specifications in docs/specs/. A spec is a behavior contract
(testable WHAT + WHY, linked to implementing modules), owned by Engineering / Architecture.
It has two distinct companions — keep the roles separate:
spec-authoring (this skill) = authoring engineering specs. Scope a subsystem into a
file, assign stable IDs, structure a behavior-contract document, decide granularity, run
pre-spec technical research, and move a spec through its lifecycle.spec-linked-docs (SLD) = traceability. Keep source code in sync with the spec via
docstring References and a CI checker.prd-authoring = product PRDs (a separate, product-owned standard — docs/prd/).
SPEC ≠ PRD. A SPEC is an engineering contract (SPEC-{SUBSYSTEM}-{NN}~{rev}, in
docs/specs/, owned by Engineering). A PRD is a product requirements doc
(PRD-{AREA}-{NN}, in docs/prd/, owned by Product). A spec implements a PRD
requirement and cites it; product framing (problem, users, acceptance criteria, metrics)
stays in the PRD. Do not put PRD content in a spec.
Full standard: docs/specs/AUTHORING.md.
This skill orients and links; AUTHORING.md is the authoritative, portable standard.
The ID grammar itself lives in docs/specs/README.md
— defer to it; never re-derive it.
Use this skill, do not duplicate it. SKILL.md is a concise router. The detailed rules
live in AUTHORING.md and the five reference files below. Read the reference you need.
When to Use
- Creating a new
docs/specs/{subsystem}.md file for a subsystem.
- Adding a governed
SPEC-{SUBSYSTEM}-{NN}~{rev} section to an existing spec.
- Deciding whether a behavior is one ID, several, or none.
- Deciding whether to add a new subsystem (file) or a section to an existing one.
- Running pre-spec technical research and recording it in
docs/specs/research/.
- Moving a spec through its lifecycle (Draft → Review → Active → Superseded).
If your task is instead linking code to an existing spec, use spec-linked-docs.
If you are authoring product requirements, use prd-authoring.
Core Model (at a glance)
A claude-mpm spec is a behavior contract: one bounded subsystem = one file
(docs/specs/{subsystem}.md). Each governed section has a stable
{#SPEC-{SUBSYSTEM}-{NN}~{rev}} ID and contains:
- Behavior Contract (WHAT) — Inputs / Outputs / Preconditions / Postconditions / Error conditions.
- Rationale (WHY) — design decisions and constraints (mandatory; never HOW). Cite the
PRD-{AREA}-{NN} requirement realized, if any.
- Implementing Modules — the HOW-link table (SLD verifies these).
Around the governed sections sit a header block (Status, Version, Subsystem, Owner=eng,
Last-updated, Related), Purpose & Scope, a Table of Contents (ID → section →
modules), Open Questions / Future Work, and References.
There is no Acceptance Criteria or Success Metrics section — those are PRD concerns.
The copy-pasteable template is in references/spec-template.md.
Quick Start
- Read the grammar.
docs/specs/README.md §4
defines SPEC-{SUBSYSTEM}-{NN}~{rev} and the declaration rule. Do not invent IDs.
- Pick or create the subsystem file. One bounded subsystem = one file. See
references/category-taxonomy.md for the existing
seven subsystems and the add-subsystem-vs-section rules.
- Apply the spec template. Copy
references/spec-template.md;
fill the header block, Purpose & Scope, ToC, and each governed section.
- Get granularity right. One ID per independently-verifiable behavior. Use the litmus
test and split/merge heuristics in
references/granularity-guide.md.
- Cite the PRD requirement realized (if any) and your research. Non-obvious decisions
link to
docs/specs/research/NN-topic-slug.md. See
references/research-conventions.md.
- Link implementing modules in each section's table; engineers then add SLD
References blocks (handoff to spec-linked-docs).
- Run the CI check.
uv run pytest tests/test_spec_traceability.py verifies the
traceability graph. Draft sections are exempt from UNCOVERED (see README §9b).
Reference Files
Relationship to SLD and PRDs
spec-authoring is upstream of the contract; spec-linked-docs is downstream of it. You
author a section here; SLD then keeps source code in sync with it via docstring References
and the four-status CI checker. A ~rev bump you make on a contract change is what SLD's
OUTDATED status detects.
A spec implements product requirements. The prd-authoring skill (docs/prd/) is the
product-owned companion: PRDs state the problem and requirements; specs state the engineering
contract that realizes them and cite the PRD-{AREA}-{NN}. Read both skills when a feature
spans product intent and engineering contract.
