Specification Authoring
Establish scope
- Read
../../../.github/specs/specfile.spec.md when present.
- Identify the problem, intended audience, owner, current state, desired state, constraints, and decision status.
- Inspect related specifications, architecture, ADRs, source, tests, automation, and external standards.
- Decide whether one cohesive spec is sufficient. Propose a dependency-ordered split only when multiple independently governed contracts are necessary.
Write the contract
Use a kebab-case filename ending in .spec.md. Follow the repository's canonical structure. At minimum make these concerns explicit:
- purpose and context
- goals and non-goals
- functional and non-functional requirements
- system boundaries and ownership
- components, interfaces, data flow, state, and dependencies
- migration and compatibility behavior when applicable
- phased implementation guidance
- validation plan and observable acceptance criteria
- risks, assumptions, and open questions
Use must, should, and may consistently. Keep observed current state distinct from desired requirements. Give requirements stable identifiers when traceability across a large spec materially helps.
Preserve layer boundaries
- Put task or system requirements in the spec.
- Put reusable procedures in skills.
- Put always-on repository conventions in instructions.
- Put role, tools, and orchestration behavior in agents.
- Put the immediate unit of work in an issue or prompt.
Do not turn the spec into a tutorial, implementation dump, or duplicate of another canonical contract.
Validate
Check filename and metadata, internal consistency, requirement testability, architecture coverage, phase ordering, acceptance-criteria traceability, defined terminology, link integrity, and unresolved decisions. Avoid production code except small, clearly non-normative examples. Return or write the complete spec and identify blockers to approval or implementation.
1---2name: spec-authoring3description: Create, revise, split, or validate implementation-ready `.spec.md` files from ideas, requirements, architecture, research, or existing systems. Use when defining a durable scope contract with goals, non-goals, requirements, boundaries, interfaces, implementation phases, validation, acceptance criteria, and open questions.4---56# Specification Authoring78## Establish scope9101. Read `../../../.github/specs/specfile.spec.md` when present.111. Identify the problem, intended audience, owner, current state, desired state, constraints, and decision status.121. Inspect related specifications, architecture, ADRs, source, tests, automation, and external standards.131. Decide whether one cohesive spec is sufficient. Propose a dependency-ordered split only when multiple independently governed contracts are necessary.1415## Write the contract1617Use a kebab-case filename ending in `.spec.md`. Follow the repository's canonical structure. At minimum make these concerns explicit:1819- purpose and context20- goals and non-goals21- functional and non-functional requirements22- system boundaries and ownership23- components, interfaces, data flow, state, and dependencies24- migration and compatibility behavior when applicable25- phased implementation guidance26- validation plan and observable acceptance criteria27- risks, assumptions, and open questions2829Use **must**, **should**, and **may** consistently. Keep observed current state distinct from desired requirements. Give requirements stable identifiers when traceability across a large spec materially helps.3031## Preserve layer boundaries3233- Put task or system requirements in the spec.34- Put reusable procedures in skills.35- Put always-on repository conventions in instructions.36- Put role, tools, and orchestration behavior in agents.37- Put the immediate unit of work in an issue or prompt.3839Do not turn the spec into a tutorial, implementation dump, or duplicate of another canonical contract.4041## Validate4243Check filename and metadata, internal consistency, requirement testability, architecture coverage, phase ordering, acceptance-criteria traceability, defined terminology, link integrity, and unresolved decisions. Avoid production code except small, clearly non-normative examples. Return or write the complete spec and identify blockers to approval or implementation.
egohygiene