Decompose

Convert a SPEC.md into a structured spec.json — an ordered list of right-sized user stories with verifiable acceptance criteria and dependency ordering. The output is consumed by /implement and the OpenBolts engine.

This skill is the dedicated planner in a plan-then-execute architecture. It analyzes the spec and codebase to produce a decomposition plan. It does NOT implement, run tests, or modify application code.

Operating assumptions

Assumption	Type	If violated
bun is available to run validate-spec.ts	Hard requirement	Error with message: "bun required for spec.json validation"
SPEC.md follows /spec's output format	Adaptable	Graceful degradation — warn and proceed with reduced quality (see Phase 1 triage)
Codebase is accessible via Read/Glob/Grep	Adaptable	Skip codebase analysis; warn "dependencies inferred from spec only"
/implement's spec.json schema (validate-spec.ts) is stable	Hard requirement	scripts/validate-spec.ts is a symlink to /implement's copy — no manual sync needed

Ship working directory

Output is written to a configurable directory. Resolution: env var CLAUDE_SHIP_DIR (default: tmp/ship). Throughout this skill, tmp/ship/ refers to the resolved directory.

---

Create workflow tasks (first action)

Before starting any work, create a task for each phase using TaskCreate with addBlockedBy to enforce ordering. Derive descriptions and completion criteria from each phase's own workflow text.

1. Decompose: Intake — read SPEC.md, assess complexity, detect mode
2. Decompose: Analyze codebase — verify dependencies, discover patterns (skipped for simple specs)
3. Decompose: Extract stories — decompose requirements into user stories
4. Decompose: Validate and output — run checks, validate-spec.ts, write files

Mark each task in_progress when starting and completed when its phase's exit criteria are met. On re-entry, check TaskList first and resume from the first non-completed task.

---

Inputs

Input	Required	Description
Path to SPEC.md	Yes	Source spec to decompose
--story US-NNN	No	Re-decomposition: which story to sub-decompose
--reason "..."	No	Re-decomposition: why the story blocked
--human-readable / --no-human-readable	No	Override DECOMPOSITION.md production
--no-browser	No	Omit browser verification criteria from UI stories
Model tier	No (default: standard)	frontier / standard / lightweight — calibrates story sizing

Re-decomposition mode

When --story is provided, load references/re-decomposition-protocol.md and follow it instead of the normal workflow.

---

Detect starting point

Condition	Action
SPEC.md path provided, no --story flag	Normal workflow (Phases 1-4)
--story US-NNN flag provided	Re-decomposition mode (load reference)
SPEC.md path does not exist	Error: "SPEC.md not found at [path]"

---

Phase 1: Intake

Read the SPEC.md at the provided path and assess what you're working with.

1.1 Triage SPEC.md sections

Identify which structured sections are present:

Required (cannot proceed without):

• A title and description of what to build
• Requirements or acceptance criteria (the source material for stories)

Expected (enriches decomposition if present; proceed without):

• User journeys including failure paths → failure path conversion
• Non-functional requirements → cross-cutting criteria
• Current state / architecture → implementationContext
• Decision log → constraints for stories
• System design → architecture context
• Interaction state matrix → enriches acceptance criteria and story coverage
• Data flow / shadow paths → failure path acceptance criteria

If SPEC.md is free-form markdown without structured sections:

1. Extract requirements from whatever structure exists (headers, bullet lists, prose)
2. Warn: "SPEC.md doesn't follow /spec output format — decomposition quality may be reduced. Missing: [sections]."
3. Proceed with available content

1.2 Assess complexity

Complexity	Criteria	Depth	Expected stories
Simple	≤5 requirements, single module, no cross-cutting concerns	1 (flat)	1-5
Moderate	5-12 requirements, 2-3 modules, some cross-cutting	1 (flat, mark complex stories)	5-12
Complex	>12 requirements, >3 modules, significant cross-cutting	1 initially, depth 2 on demand	7-15 at level 1

Never produce depth 2 upfront. Start flat. Mark stories as "may need sub-decomposition" in notes. Re-decompose on failure (via --story flag).

1.3 Detect composition mode

Detect this NOW (before Phase 4 creates the directory) and remember the result for Phase 4.4:

if tmp/ship/ directory already exists OR CLAUDE_SHIP_DIR is set:
  → composed mode → skip DECOMPOSITION.md (unless --human-readable)
else:
  → standalone mode → produce DECOMPOSITION.md alongside spec.json (unless --no-human-readable)

Store the result — Phase 4.2 will create tmp/ship/ before Phase 4.4 runs, so Phase 4.4 must use the mode detected here, not re-check the directory.

1.4 Archive previous runs

Before writing a new spec.json, check if there is an existing one from a different feature:

1. Read the current tmp/ship/spec.json if it exists
2. Check if branchName differs from the new feature's branch name
3. If different AND tmp/ship/progress.txt has content beyond the header:
   • Create archive: tmp/ship/archive/YYYY-MM-DD-feature-name/
   • Copy current spec.json and progress.txt to archive
   • Reset progress.txt with fresh header

Phase 1 gate: SPEC.md is readable and has at minimum a title + description + requirements.

---

Phase 2: Analyze Codebase (skip for simple specs)

Read-only codebase analysis enriches the decomposition. Load: references/codebase-analysis-patterns.md

What to check	How	What it informs
File existence	Glob for paths mentioned in SPEC.md	Verify spec's code traces are current
Existing patterns	Grep for similar implementations	Story ordering (match existing patterns)
Integration points	Read files at module boundaries	Dependency identification between stories
Test coverage	Glob for test files, Grep for test patterns	Which stories need "Tests pass" criterion

Constraint: Read, Glob, Grep only. Do not create files, modify code, or execute commands during this phase. The only files this skill writes are its output artifacts (spec.json, DECOMPOSITION.md) in Phase 4.

Phase 2 gate: None (analysis enriches but does not block). Mark task completed and continue.

---

Phase 3: Extract Stories

This is the core decomposition phase. Apply all conversion rules below to transform the SPEC.md into structured user stories.

spec.json output format

{
  "project": "[Project Name]",
  "branchName": "implement/[feature-name-kebab-case]",
  "description": "[Feature description from SPEC.md title/intro]",
  "implementationContext": "[Concise prose — see extraction rules below]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": ["Criterion 1", "Criterion 2", "Typecheck passes"],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ],
  "qaScenarios": [
    {
      "id": "QA-001",
      "priority": "P0",
      "category": "ux-flow",
      "name": "Scenario name",
      "given": "Precondition",
      "when": "Action",
      "then": "Expected outcome",
      "tracesTo": ["US-001"],
      "derivedFrom": "spec",
      "oracleType": "specified",
      "route": "/path (optional)"
    }
  ]
}

Story size: the number one rule

Each story must be completable in ONE iteration (one context window).

Each iteration receives the same prompt with no memory of previous work — only files and git history persist. If a story is too big, the LLM runs out of context before finishing and produces broken code.

Right-sized stories:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too big (split these):

• "Build the entire dashboard" → Split into: schema, queries, UI components, filters
• "Add authentication" → Split into: schema, middleware, login UI, session handling
• "Refactor the API" → Split into one story per endpoint or pattern

Rule of thumb: If you cannot describe the change in 2-3 sentences, it is too big.

When model tier is specified, calibrate sizing. Load: references/model-tier-calibration.md

Story ordering: dependencies first

Stories execute in priority order. Earlier stories must not depend on later ones.

Correct order:

1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Dashboard/summary views that aggregate data

When codebase analysis is available (Phase 2), use actual file dependencies to inform ordering — not just the generic schema→backend→UI heuristic.

Acceptance criteria: must be verifiable

Load: references/ears-format.md for EARS acceptance criteria format.

Each criterion must be something the iteration agent can CHECK, not something vague.

Good criteria (EARS format for event-driven items):

• WHEN user clicks status toggle THE SYSTEM SHALL update status and reflect in UI without refresh
• WHEN API receives invalid status value THE SYSTEM SHALL return 400 with descriptive error

Good criteria (behavioral for non-event items):

• "Task with changed status is retrievable with the new status"
• "Task list displays only tasks matching the selected filter"
• "Invalid status value returns 400 with descriptive error message"

Bad criteria (vague):

• "Works correctly"
• "User can do X easily"
• "Good UX"
• "Handles edge cases"

Bad criteria (implementation-coupled / fragile):

• "handleStatusChange calls db.update with the correct enum"
• "Component renders by calling useTaskList hook"

Implementation-coupled criteria produce tests that break on refactor even when behavior is unchanged. Behavioral criteria survive internal restructuring.

Always include as final criterion: "Typecheck passes"

For stories with testable logic, also include: "Tests pass". When codebase analysis is available (Phase 2), use the test coverage findings to determine which stories need this — stories modifying code that already has tests must include it.

For stories that change UI — if browser available (no --no-browser): "Verify in browser using browser skill"

If --no-browser: substitute with Bash-verifiable criteria covering UI behavior through API responses or rendered output.

Conversion rules

1. Each user story becomes one JSON entry
2. IDs: Sequential (US-001, US-002, etc.) — must match ^US-\d{3}$
3. Priority: Based on dependency order, then document order — sequential from 1
4. All stories: passes: false. Use notes for: inter-story dependencies ("Depends on US-001 for result column"), spec AC traceability ("Covers AC1, AC2, AC4"), and uncertainty flags ("May need sub-decomposition")
5. branchName: Derive from feature name, kebab-case, prefixed with implement/
6. Always add: "Typecheck passes" to every story's acceptanceCriteria

Extracting implementationContext

The implementationContext field captures spec-level knowledge that applies across all stories.

Extract from these SPEC.md sections:

SPEC.md section	What to extract	Why it matters
§9 System design	Architecture overview, data model, API shape, auth model	Without this, the implementer guesses the architecture
§6 Non-functional requirements	Performance, security, reliability, operability	Constrain how every story is implemented
§10 Decision log	Settled decisions (especially 1-way doors) with rationale	Prevents revisiting spec decisions
§8 Current state	How the system works today, integration points, gaps	Implementer needs to know what exists

When codebase analysis is available, enrich with verified file paths, confirmed patterns, and integration point observations.

Calibrate depth:

Spec available during implementation?	Depth
Yes (spec path forwarded — default in /ship)	3-5 sentences — architecture + key constraints only
No (spec.json is the sole artifact)	5-10 sentences — include architecture, non-goals, integration points, key decisions

When in doubt, write the longer form.

Converting failure paths into acceptance criteria

For each failure scenario in SPEC.md (user journeys, failure paths):

1. Identify which story it belongs to
2. Convert to a verifiable acceptance criterion on that story

If a failure scenario spans multiple stories, attach the criterion to the story where the user-facing behavior lives.

Applying non-functional requirements

For each non-functional requirement:

1. Universal constraints → add as criterion to every applicable story
2. Story-specific constraints → add to the relevant story only

Do NOT create separate "non-functional" stories. Weave constraints into the stories that implement the relevant functionality.

Deriving qaScenarios (implementation context)

After converting user stories, derive a qaScenarios[] array. These scenarios provide QA context for iteration agents during implementation — they help the implementer understand what will be verified and write code accordingly. They do not constrain or scope /qa-plan — qa-plan derives its own scenarios directly from SPEC.md source material.

Mapping table:

SPEC.md section	Scenario category	Derivation rule
§6 Acceptance criteria	ux-flow, error-state	Each criterion → one happy-path; each failure → one error variant
§5 Interaction state matrix	visual, edge-case	Each non-empty cell → one state verification
§9 Data flow — shadow paths	edge-case, failure-mode	Each shadow path → one edge-case scenario
§9 Failure modes table	failure-mode	Each row → one failure-mode scenario testing recovery/safety behavior
§9 Affected routes/pages	visual, ux-flow	Each row → one visual verification
§5 User journeys	ux-flow, cross-system	Each step → one e2e scenario
§13 Risks (severity ≥ MEDIUM)	failure-mode	Each MEDIUM+ risk with a mitigation → one scenario verifying the mitigation works
§13 Deployment considerations	integration	Each row → one deployment verification

oracleType assignment:

oracleType	When to use	Example
specified	Deterministic pass/fail	"API returns 400 with error message"
derived	Compare to baseline	"Page renders identically to mockup"
human	Subjective judgment	"Error message is helpful and actionable"

Splitting large specs

Original: "Add user notification system"

Split into:

1. US-001: Add notifications table to database
2. US-002: Create notification service for sending notifications
3. US-003: Add notification bell icon to header
4. US-004: Create notification dropdown panel
5. US-005: Add mark-as-read functionality
6. US-006: Add notification preferences page

Each is one focused change that can be completed and verified independently.

---

Phase 4: Validate and Output

4.1 Self-regulation checklist

Before writing spec.json, verify:

• Previous run archived (if existing spec.json has different branchName)
• Each story is completable in one iteration (small enough — 2-3 sentence description test)
• Stories ordered by dependency (schema → backend → UI)
• Every story has "Typecheck passes" as criterion
• UI stories have browser verification criterion (or Bash substitute if --no-browser)
• Acceptance criteria are verifiable and behavioral (not vague, not implementation-coupled)
• No story depends on a later story (acyclic dependency ordering)
• implementationContext extracted from SPEC.md — concise prose, not copy-paste
• Failure/recovery paths converted into acceptance criteria on relevant stories
• Non-functional requirements applied as cross-cutting criteria
• qaScenarios derived with id (QA-NNN), given/when/then, tracesTo, and oracleType — these provide implementation context, not QA plan scope
• Every spec requirement traces to ≥1 story. When spec uses numbered ACs: (a) each story's notes lists which ACs it covers, AND (b) enumerate all spec ACs and verify each appears in at least one story's notes — log any gaps
• Total stories typically 5-12 at level 1 (reassess granularity if approaching 15+)

Load: references/stopping-criteria.md for the 7 atomic-story stopping criteria.

4.2 Write spec.json

Create tmp/ship/ if needed (mkdir -p tmp/ship). Write spec.json to tmp/ship/spec.json.

4.3 Run validate-spec.ts

bun <skill-path>/scripts/validate-spec.ts tmp/ship/spec.json

If validation fails: read the errors, fix the spec.json, re-validate. Repeat until zero errors.

4.4 Write DECOMPOSITION.md (standalone mode only)

If standalone mode was detected in Phase 1.3 or --human-readable flag:

# Decomposition: [Feature Name]

## Overview
[1-2 sentences: what this decomposition covers, key constraints]

## Complexity Assessment
- Assessed complexity: [simple/moderate/complex]
- Story count: [N]
- Model tier: [frontier/standard/not specified]

## Task Plan
- [ ] US-001: [title] (Priority: 1, Complexity: S)
- [ ] US-002: [title] (Priority: 2, Complexity: M, Blocked by: US-001)
- ...

## Task Details
### US-001: [title]
**Objective:** [what this achieves]
**Acceptance criteria:**
- WHEN [trigger] THE SYSTEM SHALL [behavior]
- ...
**Dependencies:** [none / US-NNN because...]
**Key files:** [codebase paths discovered during analysis]
**Implementation notes:** [patterns, gotchas from codebase]

## Traceability
| Spec Requirement | Stories | Coverage |
|---|---|---|
| [Requirement] | US-001, US-003 | Full |
| [Requirement] | US-002 | Partial — [what's missing] |

## Decomposition Decisions
- [Decision + rationale]

Write to tmp/ship/DECOMPOSITION.md (or alongside spec.json in the current directory if no ship directory).

---

Examples

Incorrect: Story too large

US-001: "Build the entire dashboard with filters, sorting, and pagination"

Correct: Split into focused stories

US-001: "Add status column to tasks table" (schema)
US-002: "Create status filter dropdown" (UI)
US-003: "Add server-side filter query" (backend)
US-004: "Add pagination to task list" (UI + backend)

Incorrect: Vague acceptance criteria

"acceptanceCriteria": ["Works correctly", "Good UX", "Handles edge cases"]

Correct: EARS / behavioral criteria

"acceptanceCriteria": [
  "WHEN user clicks status toggle THE SYSTEM SHALL update status and reflect in UI without refresh",
  "WHEN API receives invalid status value THE SYSTEM SHALL return 400 with descriptive error",
  "Typecheck passes"
]

Incorrect: Wrong dependency ordering

US-001: "Add status badge UI component" (priority 1)
US-002: "Add status column to database" (priority 2)

UI depends on schema that doesn't exist yet.

Correct: Dependencies first

US-001: "Add status column to database" (priority 1)
US-002: "Add status toggle server action" (priority 2)
US-003: "Add status badge UI component" (priority 3)

Incorrect: Implementation-coupled criteria

"acceptanceCriteria": [
  "handleStatusChange calls db.update with the correct enum",
  "Component renders by calling useTaskList hook"
]

Correct: Behavioral criteria

"acceptanceCriteria": [
  "Task with changed status is retrievable with the new status",
  "Task list displays only tasks matching the selected filter"
]

Incorrect: Preemptive deep decomposition

US-001: "Authentication framework"
  US-001a: "Session table migration"
  US-001b: "JWT token service"

Depth 2 upfront before knowing if US-001 is actually too complex.

Correct: Flat with emergent hierarchy

US-001: "Add session table and migration" (simple, atomic)
US-002: "Add login endpoint with JWT" (notes: "may need sub-decomposition")
US-003: "Add auth middleware" (simple, atomic)

Flat list. Re-decompose US-002 only if it blocks during execution.

---

Full worked example

Input SPEC.md (abbreviated):

# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements
- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

## Non-functional requirements
- Status changes must be tenant-scoped

## User journeys — Failure paths
- Invalid status value via API → return 400 with descriptive error

## Current state
- Tasks stored in tasks table, accessed via getTasksByProject()
- API uses RESTful patterns under /api/tasks/
- UI uses TaskCard component in components/tasks/

Output spec.json:

{
  "project": "TaskApp",
  "branchName": "implement/task-status",
  "description": "Task Status Feature - Track task progress with status indicators",
  "implementationContext": "Tasks are stored in a tasks table accessed via getTasksByProject() in the data-access layer. The API follows RESTful patterns under /api/tasks/. Auth uses existing tenant-scoped middleware. The status field should be an enum column with a database-level constraint. UI components use the existing TaskCard component in components/tasks/.",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add status field to tasks table",
      "description": "As a developer, I need to store task status in the database.",
      "acceptanceCriteria": [
        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Display status badge on task cards",
      "description": "As a user, I want to see task status at a glance.",
      "acceptanceCriteria": [
        "Each task card shows colored status badge",
        "Badge colors: gray=pending, blue=in_progress, green=done",
        "Typecheck passes",
        "Verify in browser using browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-003",
      "title": "Add status toggle to task list rows",
      "description": "As a user, I want to change task status directly from the list.",
      "acceptanceCriteria": [
        "WHEN user changes status via dropdown THE SYSTEM SHALL save immediately and update UI without page refresh",
        "WHEN API receives invalid status value THE SYSTEM SHALL return 400 with descriptive error",
        "Status update is tenant-scoped (uses existing tenant middleware)",
        "Typecheck passes",
        "Verify in browser using browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-004",
      "title": "Filter tasks by status",
      "description": "As a user, I want to filter the list to see only certain statuses.",
      "acceptanceCriteria": [
        "Filter dropdown: All | Pending | In Progress | Done",
        "Filter persists in URL params",
        "Typecheck passes",
        "Verify in browser using browser skill"
      ],
      "priority": 4,
      "passes": false,
      "notes": ""
    }
  ],
  "qaScenarios": [
    {
      "id": "QA-001",
      "priority": "P0",
      "category": "ux-flow",
      "name": "User can toggle task status from list",
      "given": "A task exists with status 'pending' on the task list",
      "when": "User changes status to 'in_progress' via the dropdown",
      "then": "Status updates immediately, UI reflects the change without page refresh",
      "tracesTo": ["US-003"],
      "derivedFrom": "spec",
      "oracleType": "specified",
      "route": "/tasks"
    },
    {
      "id": "QA-002",
      "priority": "P0",
      "category": "error-state",
      "name": "Invalid status value returns descriptive error",
      "given": "A task exists in the system",
      "when": "API receives an invalid status value via PUT /api/tasks/:id",
      "then": "API returns 400 with message indicating allowed values",
      "tracesTo": ["US-003"],
      "derivedFrom": "spec",
      "oracleType": "specified"
    },
    {
      "id": "QA-003",
      "priority": "P1",
      "category": "visual",
      "name": "Status badge colors match spec for all states",
      "given": "Tasks exist with each status value",
      "when": "User views the task list",
      "then": "Badges show correct colors: gray=pending, blue=in_progress, green=done",
      "tracesTo": ["US-002"],
      "derivedFrom": "spec",
      "oracleType": "derived",
      "route": "/tasks"
    }
  ]
}

---

No interactive gates

This skill has no interactive gates. It runs identically whether invoked by a user, /implement, /ship, or the OpenBolts engine. No prompts, no approval steps, no decision points requiring human input. Complexity assessment, codebase analysis, decomposition, and validation all run autonomously.

---