spec-authoring

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.