👻 spec.md

Spec-driven development for Claude Code. Takes any task — a one-liner, a vague idea, or a full product brief — and breaks it into the smallest possible atomic units that a single agent can pick up and ship independently. The first step before /ship or /party.

Note

These skills have been built and tested with Claude Code. Codex support is untested. If you try them on Codex, we'd love your help. Open an issue to share what works and what doesn't.

Quickstart

npx skills add -g amajorai/spec.md

Then in Claude Code:

/spec build a multiplayer chess game with spectator mode

or with a vague brief:

/spec I want to add payments to my app

Update

# Update this skill
npx skills update spec

# Update all installed skills (interactive scope prompt)
npx skills update

# Update only global or project skills
npx skills update -g
npx skills update -p

# Non-interactive (auto-detects scope)
npx skills update -y

Claude Code plugin

/plugin marketplace add amajorai/spec.md
/plugin install specmd@amajorai

Invoke as /specmd:spec <task>.

What it does

spec.md explores your codebase, interviews you until nothing is ambiguous, then produces a numbered list of atomic units — each one small enough for a single /ship-fast run, with clear acceptance criteria and explicit dependencies. Optionally, it creates a GitHub epic with linked sub-issues so /party can pick them up immediately.

flowchart TD
    A["👻 /spec <task>"] --> B["🔍 Explore\n2–4 parallel subagents map the codebase"]
    B --> C{"Still open\nareas?"}
    C -->|"Yes"| D["🎤 Interview\nAsk 1 question at a time"]
    D --> B
    C -->|"No"| E["📋 Decompose\nAtomic units: self-contained, agent-sized, verifiable"]
    E --> F["👤 Review\nUser confirms the spec"]
    F --> G{GitHub issues?}
    G -->|"Yes"| H["🐙 Create Epic + Sub-issues\nLinked via GitHub sub-issue API"]
    G -->|"No"| I["📄 Print spec\nNumbered list with ship order"]
    H --> I
    I --> J{Skills installed?}
    J -->|"/party"| K["🎉 /party\n24/7 autonomous build agent\npicks up all issues"]
    J -->|"/ship"| L["📦 /ship\nFull pipeline, one unit at a time"]
    J -->|"neither"| M["📥 Install prompt\nnpx skills add amajorai/party.md"]

Loading

What makes a unit atomic?

A unit is atomic when all of these are true:

Rule	What it means
Self-contained	Can be implemented without waiting for another unit to finish
Agent-sized	A single /ship-fast or /ship run can close it in one session
Verifiable	Has clear, testable acceptance criteria
Labeled	feature, chore, fix, docs, or infra

Units that must always ship together get merged. Pure "glue" units with no acceptance criteria are eliminated. Infrastructure and schema changes that block everything else become Unit 0 — the foundation.

GitHub integration

When GitHub issues are enabled, spec.md creates:

• One epic issue (👻 spec label) with the overall goal, scope, and acceptance criteria
• One sub-issue per unit with context, acceptance criteria, dependencies, and an explicit out-of-scope section
• Labels auto-created on your repo (spec:ready, spec:blocked, feature, chore, fix, docs, infra)
• Sub-issue links via GitHub's sub-issue API — the hierarchy shows up in GitHub Projects automatically

Each sub-issue is written so a single agent can pick it up cold and close it without needing to read the epic.

Works great with

• 🎉 party.md — the natural next step after /spec. Drop the created issues into a GitHub Projects board and party.md ships them autonomously 24/7.
• 📦 ship.md — pick up individual spec units one at a time with a full quality-gated pipeline.
• 🪅 vibe.md — provision your production server and deploy pipeline before you start shipping units.
• 🔎 fix.md — when a shipped unit breaks something, fix it surgically without re-speccing the whole project.
• 🎬 replay.md — record video proof of each shipped unit working and attach it to the closed issue.
• ⚡ amajorai/skills — edge cases, E2E, auth, payments, SEO, CI, and 20+ more skills that individual units will need.

Skills

Skill	What it does
/spec	Explore-first interview loop, atomic decomposition, optional GitHub epic + sub-issues, handoff to /party or /ship

Star History