name: spec-writing-standard description: Write or upgrade an AI-facing specification or scoped execution artifact using a reusable spec writing standard. Use when a repo needs a precise, implementation-ready contract with explicit goals, current evidence, boundaries, commands, validation gates, and approval rules. Do not use for lightweight briefs, changelogs, or loose brainstorm notes.

Spec Writing Standard

Purpose

Produce a specification that is safe and specific enough for autonomous coding work. This skill combines contract-style spec structure with AI execution rules.

Workflow

1. Read references/AI_FACING_SPEC_WRITING_STANDARD.md.
2. If the target repo already owns a normalized packet format, use the repo-owned packet first. When working within the AxiomMd workflow, the authoritative normalized input is templates/input.packet.yaml.
3. If the target repo does not already own a normalized packet format and the intake is weak or scattered, normalize it with assets/spec-input-packet-template.md.
4. Use section 16 of the reference standard to decide whether the output should be a full 18-section spec or a smaller scoped artifact.
5. For a full implementation spec, start from assets/spec-writing-standard-template.md.
6. For a scoped artifact, start from assets/scoped-artifact-template.md.
7. Ground the draft in current repository evidence before making design decisions.
8. If a critical input is unknown, ask a targeted question or record an OPEN item. Do not silently guess.
9. If the output is a full 18-section spec, run python3 <skill-root>/scripts/check_spec_standard.py <path/to/spec.md> before finishing.
10. If the output is a scoped artifact, run python3 <skill-root>/scripts/check_scoped_artifact.py <path/to/artifact.md> before finishing.

Input Ownership

• This skill is generic and does not replace a target repo's owned workflow packet.
• When the target repo already ships input.packet.yaml or equivalent, that repo-owned format wins.
• assets/spec-input-packet-template.md is a fallback normalization worksheet for repos that do not already own a packet format.
• This skill should not fetch owner-repo GitHub documents at runtime.

Input Contract

• when the target repo already owns a normalized packet, read that repo-owned packet first
• otherwise use assets/spec-input-packet-template.md as the minimum intake worksheet
• minimum decision-ready intake still needs problem, boundary, current evidence, target delta, definition of done, and approval boundary

Read Paths

• provided repo-owned input packet such as input.packet.yaml, when one exists
• relevant source-of-truth files, commands, logs, and failures from the target repository
• references/AI_FACING_SPEC_WRITING_STANDARD.md
• local templates and validators inside this skill folder

Write Paths

• the user-selected output artifact path for one full spec or one scoped artifact
• optional adjacent notes only when the target repo already expects them

Output Target

• one implementation-ready full spec
• or one scoped artifact with explicit coverage categories

Stop Conditions

• the intake does not provide, and repository evidence cannot recover, the minimum decision-ready facts
• the requested output is neither a full 18-section spec nor a valid scoped artifact
• the relevant validator still fails and the remaining failure cannot be resolved from repository evidence
• the target repo already owns multi-file package truth and the user is actually asking for package authoring rather than a spec artifact

References

• Full standard: references/AI_FACING_SPEC_WRITING_STANDARD.md
• Fallback input worksheet: assets/spec-input-packet-template.md
• Full-spec template: assets/spec-writing-standard-template.md
• Scoped-artifact template: assets/scoped-artifact-template.md

When To Use

• Converting loose notes or PRDs into a working implementation spec.
• Upgrading an existing spec so it can guide AI coding agents safely.
• Writing a bounded scoped artifact that still needs explicit evidence, boundaries, failures, and validation.
• Defining repository execution, validation, and handoff rules.

When Not To Use

• One-off idea capture.
• Product marketing copy.
• Roadmaps or changelogs.
• Tiny fixes that only need a short task note.
• Multi-file package truth that is already split across repository-owned method/** and specs/**.

Commands

Full-spec validator

python3 <skill-root>/scripts/check_spec_standard.py <path/to/spec.md>

Scoped-artifact validator

python3 <skill-root>/scripts/check_scoped_artifact.py <path/to/artifact.md>

<skill-root> = this skill's installation directory (the directory containing this SKILL.md).