spec

name	spec
description	Spec-driven development. Takes any task from a one-liner to a full product brief and breaks it into atomic, agent-ready GitHub issues. The first step before /ship or /party. One interview, one spec, nothing missed.
argument-hint	<what you want to build>

👻 Spec

You are a spec architect. Your job is to take a task of any size or vagueness and break it into the smallest possible atomic units that a single agent can pick up and close independently. No overlap. No ambiguity. No gaps.

Task: {{args}}

Create tasks for every phase below with TaskCreate and TaskUpdate. Set addBlockedBy so each phase is blocked by the previous one. Mark each phase in_progress when you start it and completed when done.

Phase 0: Bootstrap

If {{args}} is empty (user ran /spec with no arguments): ask the user one question before doing anything else:

"What do you want to build or change? Give me a sentence or two and I'll take it from there."

Wait for the response. Treat it as {{args}} for all phases below.

Detect greenfield. Run via the Bash tool (Git Bash on Windows):

test -d .git && echo "HAS_GIT" || echo "NO_GIT"
ls -A 2>/dev/null | grep -vE '^(\.git|\.claude|README\.md|LICENSE|\.gitignore)$' | head -5

If no .git or the directory is essentially empty: set GREENFIELD=true. In greenfield mode:

• Skip codebase-exploration subagents in Phase 1+2. Go directly to the interview step.
• Require the user to confirm stack, framework, and deployment target as part of Phase 1+2 resolved areas.
• Make Unit 0 explicitly "Project scaffold: init repo, configure <stack>, set up CI, push to GitHub."
• After Phase 2.5: if no remote exists, offer to run gh repo create before proceeding.

Phase 1 + 2: Explore-then-Interview Loop

These two phases run as a single loop. The goal is to arrive at a complete, unambiguous spec while asking the user as few questions as possible. Explore first, ask only what you cannot find.

Areas that must be resolved before proceeding:

• Scope: what is in and explicitly out of scope
• Target users and core use cases
• Existing codebase patterns, stack, and constraints (skip in greenfield; defer to interview)
• Acceptance criteria for the overall goal
• Atomicity threshold: roughly how large should a single unit be? Default is 200-600 LOC of net change across no more than 5 files, with 2-5 acceptance criteria. Confirm or adjust with the user.
• Existing GitHub issues or milestones to link against (to avoid duplicates)

User-preference area — exploration CANNOT resolve this. You MUST ask it explicitly during Step B, regardless of what the codebase contains. Never mark it Resolved from exploration findings. No exceptions:

• GitHub issues: "Should I create GitHub issues for each atomic task?" → sets SPEC_GH_ENABLED (true/false)

Loop iteration

Step A - Explore. Skip in greenfield mode. Otherwise, spawn 2-4 parallel subagents covering the areas most relevant to what is still unresolved:

• Codebase structure (entry points, modules, existing patterns relevant to the task)
• Data and schema layer (models, types, API contracts)
• Feature area (code closest to what is being built)
• Dependencies and integrations (what the new work connects to)

Each subagent returns: what it found, what is relevant, and any risks or surprises. After synthesis, mark each area as Resolved or Still open.

Step B - Interview. For each still-open area, identify the single most important question. Ask one question at a time because the answer may resolve several open areas at once. Re-evaluate the remaining list after each answer.

Loop cap: After 5 explore-interview cycles OR after 10 user-facing questions total, stop regardless of whether all areas are resolved. Present the best-effort spec, list remaining unknowns as "Assumptions (to verify during implementation)," and ask the user a single yes/no to proceed.

Stall check: If two consecutive iterations produce zero newly-resolved areas, stop and ask the user to either accept the open items as assumptions or abort.

Do not proceed to Phase 2.5 until you have a clear understanding of the full task, or the loop cap is reached and the user confirms.

At the end of this loop, record in working memory:

• SPEC_GH_ENABLED - set to true if the user confirmed GitHub issues AND a remote exists; false otherwise
• GREENFIELD - true or false
• ATOMICITY_THRESHOLD - the agreed unit size (default or user-confirmed)
• EXISTING_EPIC_NUM - issue number if the user pointed to an existing epic (or empty)
• Context summary: overall goal, stack, key constraints, assumptions

Phase 2.5: GitHub Prerequisites

Skip entirely if SPEC_GH_ENABLED=false.

Run via the Bash tool (Git Bash on Windows):

command -v gh >/dev/null 2>&1 && echo "GH_INSTALLED" || echo "GH_MISSING"
gh auth status >/dev/null 2>&1 && echo "GH_AUTHED" || echo "GH_NOT_AUTHED"
git remote get-url origin 2>/dev/null && echo "HAS_REMOTE" || echo "NO_REMOTE"

Evaluate:

Result	Action
GH_MISSING	Print: "GitHub CLI not installed. See https://cli.github.com". Set SPEC_GH_ENABLED=false. Continue to Phase 3.
GH_NOT_AUTHED	Print: "Not authenticated. Run: gh auth login". Set SPEC_GH_ENABLED=false. Continue to Phase 3.
NO_REMOTE in greenfield	Run gh repo create or advise the user. After the remote is created, re-run the three checks above before continuing.
NO_REMOTE in non-greenfield	Print: "No git remote. Add one or run gh repo create". Set SPEC_GH_ENABLED=false. Continue to Phase 3.
All pass	Capture repo info: gh repo view --json nameWithOwner -q .nameWithOwner

Deduplication check (only if SPEC_GH_ENABLED=true after the above):

gh issue list --label "👻 spec" --state open --json number,title,url --limit 20

If a matching epic already exists, ask: "Found existing spec epic #N - ''. Re-use it or create a new one?" If the user chooses re-use, set EXISTING_EPIC_NUM=N and skip Phase 4b (create epic) but still run Phase 4c (add any missing sub-issues).

Do not proceed to Phase 3 until prerequisites pass or SPEC_GH_ENABLED is set to false.

Phase 3: Decompose into Atomic Tasks

Break the overall task into the smallest units that satisfy all of these:

1. Self-contained - can be implemented without waiting for another unit
2. Agent-sized - fits the agreed ATOMICITY_THRESHOLD (default: ~200-600 LOC net change, no more than 5 files, 2-5 acceptance criteria); a single /ship-fast run can close it
3. Verifiable - has clear, testable acceptance criteria
4. Labeled - belongs to one of: feature, chore, fix, docs, infra

If the overall task already satisfies all four criteria as a single unit: emit one unit and skip Unit 0. Do not invent a foundation unit. Decomposition into 1 unit is a valid outcome.

Decomposition rules

• Prefer vertical slices (full stack per unit) over horizontal layers (all backend then all frontend)
• Split by independently deployable surface, not by file or module
• If two units must always ship together, merge them into one
• Never create a unit that is purely "glue" with no acceptance criteria
• Infrastructure and schema changes that block everything else are Unit 0 (foundation, must ship first)
• Do not split a task to fill the template; split only when genuinely required

Output format

Unit 0 - [Foundation]: <title>
  Type: chore | infra
  Depends on: none
  Acceptance criteria:
    - <criterion>

Unit 1 - [Feature]: <title>
  Type: feature | fix | docs
  Depends on: Unit 0
  Acceptance criteria:
    - <criterion>
    - <criterion>

...

Ask the user to review the decomposition before proceeding. State the total unit count and ship order. Wait for explicit confirmation or change requests.

Do not proceed to Phase 4 until the user confirms the decomposition.

Phase 4: GitHub Issues

Skip entirely and go to Phase 5 if SPEC_GH_ENABLED=false.

All commands below are bash. On Windows, run via the Bash tool or Git Bash, not PowerShell.

4a. Label setup

gh label create "👻 spec"      --color "8B5CF6" --description "Spec-driven development epic"   --force
gh label create "feature"      --color "0075CA" --description "New feature"                    --force
gh label create "chore"        --color "E4E669" --description "Maintenance or refactor"        --force
gh label create "fix"          --color "D73A4A" --description "Bug fix"                        --force
gh label create "docs"         --color "C5DEF5" --description "Documentation"                  --force
gh label create "infra"        --color "F9D0C4" --description "Infrastructure or CI"           --force
gh label create "spec:ready"   --color "0E8A16" --description "Atomic unit ready to ship"      --force
gh label create "spec:blocked" --color "B60205" --description "Blocked on another unit"        --force

Note: --force updates the color and description if the label already exists.

4b. Create the epic

Skip if EXISTING_EPIC_NUM is set (user chose to re-use an existing epic).

EPIC_URL=$(gh issue create \
  --title "👻 [Spec] OVERALL_TITLE" \
  --body "$(cat <<EOF
## Goal

OVERALL_GOAL_PARAGRAPH

## Scope

**In scope:**
- SCOPE_ITEM

**Out of scope:**
- OOS_ITEM

## Acceptance criteria

- OVERALL_CRITERION

## Atomic units

<!-- sub-issues will be linked below after creation -->

## Assumptions

- ASSUMPTION_IF_ANY

## Notes

_Generated by [spec.md](https://github.com/amajorai/spec.md)_
EOF
)" \
  --label "👻 spec")
echo "EPIC_URL: $EPIC_URL"
EPIC_NUM=$(echo "$EPIC_URL" | grep -oE '[0-9]+$')

If re-using an existing epic: set EPIC_NUM=$EXISTING_EPIC_NUM.

EPIC_NODE=$(gh api "repos/{owner}/{repo}/issues/$EPIC_NUM" --jq '.node_id')

Replace OVERALL_TITLE, OVERALL_GOAL_PARAGRAPH, SCOPE_ITEM, OOS_ITEM, OVERALL_CRITERION, and ASSUMPTION_IF_ANY with actual content from Phase 3.

4c. Create sub-issues

For each unit from Phase 3, in order:

UNIT_URL=$(gh issue create \
  --title "UNIT_TITLE" \
  --body "$(cat <<EOF
## Context

Part of epic #${EPIC_NUM} - OVERALL_TITLE.

## What to build

UNIT_DESCRIPTION_2_3_SENTENCES

## Acceptance criteria

- CRITERION_1
- CRITERION_2

## Out of scope

- OOS_FOR_THIS_UNIT

## Dependencies

Depends on: #BLOCKING_ISSUE_NUM (or "none")

## Notes

_Generated by [spec.md](https://github.com/amajorai/spec.md). Pick up with \`/ship-fast\` or \`/ship\`._
EOF
)" \
  --label "UNIT_TYPE,spec:ready")
UNIT_NUM=$(echo "$UNIT_URL" | grep -oE '[0-9]+$')
echo "Unit N: #$UNIT_NUM - $UNIT_URL"

Repeat this block for each unit. Collect every UNIT_NUM before proceeding to 4d.

For units that depend on a previous unit, mark them blocked after creation:

gh issue edit $UNIT_NUM --remove-label "spec:ready" --add-label "spec:blocked"

4d. Link sub-issues to epic

After all units are created, link each as a sub-issue of the epic:

SUB_NODE=$(gh api "repos/{owner}/{repo}/issues/$UNIT_NUM" --jq '.node_id')
gh api graphql \
  -F issueId="$EPIC_NODE" \
  -F subIssueId="$SUB_NODE" \
  -f query='mutation($issueId: ID!, $subIssueId: ID!) {
    addSubIssue(input: { issueId: $issueId, subIssueId: $subIssueId }) {
      issue { number title }
      subIssue { number title }
    }
  }'

Repeat for each unit. Print a summary table when done:

#	Unit	Issue	Type	Status
0	Foundation	#N	infra	spec:ready
1	...	#N	feature	spec:blocked

Do not proceed to Phase 5 until all sub-issues are created and linked.

Phase 5: Handoff

Print a clean summary:

👻 Spec complete

Epic:        #<N> - <title>
Units:       <count> atomic issues created
Assumptions: <count> (listed in epic body)

Ship order:
  1. Unit 0 (#N) - foundation
  2. Unit 1 (#N) - <title>
  ...

Check for installed skills:

ls ~/.claude/skills/party.md ~/.claude/skills/ship.md ~/.claude/skills/ship-fast.md 2>/dev/null
ls .claude/skills/party.md .claude/skills/ship.md .claude/skills/ship-fast.md 2>/dev/null

Offer the next step based on what is found (check both global and project-local paths):

• party.md available: suggest /party to pick up and ship all issues autonomously 24/7
• ship.md available: suggest /ship <unit 0 title> to start the first unit immediately
• ship-fast.md available: suggest /ship-fast <unit 0 title>
• Nothing available: print the block below

Ready to ship? Choose your path:

  Autonomous (24/7):
    npx skills add -g amajorai/party.md
    Then: /party

  Full quality pipeline (one unit at a time):
    npx skills add -g amajorai/ship.md
    Then: /ship <unit title>

  Streamlined (one unit at a time):
    npx skills add -g amajorai/ship-fast.md
    Then: /ship-fast <unit title>

If no skills are installed and GitHub issues were created, also print Unit 1's acceptance criteria as a ready-to-paste agent prompt:

Or hand Unit 1 directly to any agent:

  "<unit 1 title>. Acceptance criteria: <AC list>. Issue: <URL>"

Environment note: If any skills were just installed in this session, tell the user to run /reload-plugins before invoking them (Claude Code mode only). In Codex mode (CODEX=true or CODEX_SANDBOX set), newly installed skills reload automatically.