Spec Creator

Spec Creator

Problem

Writing story specs from scratch is error-prone: incorrect file paths, wrong function signatures, missed existing infrastructure, over-engineered designs, and inconsistent formatting. Each project has its own spec conventions that must be discovered and followed.

Quick Check

# Discover project spec conventions
~/.claude/skills/spec-creator/scripts/discover-conventions.sh .           # Report
~/.claude/skills/spec-creator/scripts/discover-conventions.sh . --json    # JSON

Progress Tracking (MANDATORY)

Before starting, determine the workflow and create the task checklist:

~/.claude/skills/spec-creator/scripts/task-manifest.sh single-story    # Default
~/.claude/skills/spec-creator/scripts/task-manifest.sh vertical-split   # If splitting

Single-story workflow (default):

| # | subject | activeForm | |---|---------|------------| | 1 | Parse input and discover conventions | Discovering project conventions | | 2 | Research codebase | Researching codebase | | 3 | Brainstorm approaches with user | Brainstorming approaches | | 4 | Generate spec file | Generating spec file | | 5 | Post-creation review | Running post-creation review |

Vertical-split workflow (chosen in Phase 3 if splitting triggers fire):

| # | subject | activeForm | |---|---------|------------| | 1 | Parse input and discover conventions | Discovering project conventions | | 2 | Research codebase | Researching codebase | | 3 | Brainstorm approaches with user | Brainstorming approaches | | 4 | Generate spec files for all slices | Generating spec files | | 5 | Update tracking file | Updating tracking file | | 6 | Post-creation review | Running post-creation review |

Update rules:

• Create all tasks from single-story manifest at start (TaskCreate)
• Mark each task in_progress (TaskUpdate) immediately before starting it
• Mark each task completed immediately after it succeeds
• If user selects vertical split in Phase 3, delete task 4-5 and create tasks 4-6 from vertical-split manifest
• If user selects "Done" in Phase 5, mark the post-creation task completed immediately
• On error, keep current task as in_progress and report

Workflow (5 Phases)

Phase 1: Parse Input and Discover Conventions

→ TaskUpdate: task 1 in_progress

1.1 Detect input type from the user's arguments:

| Input Type | Detection | Action | |-----------|-----------|--------| | Prompt | Plain text describing the feature | Extract requirements directly | | File path | @path/to/file.md or file extension | Read file, extract requirements | | GitHub issue | #123 or GitHub URL | Fetch via gh issue view | | Claude plan | References a plan or plan output | Parse plan steps into requirements |

1.2 Discover project conventions by running the discovery script:

CONVENTIONS=$(~/.claude/skills/spec-creator/scripts/discover-conventions.sh "$(git rev-parse --show-toplevel)" --json)

This returns: spec directory, naming pattern, epic structure, next available story numbers, tracking files, and common sections across existing specs.

1.3 Read a recent spec from the project as a style reference. Use the sampleSpec path from the discovery output. This ensures the generated spec matches the project's actual voice and formatting — not just the template structure.

1.4 Determine epic and story number. If the user specified an epic, use it. Otherwise, infer from the requirement's domain or ask. Use the nextStory value from discovery.

→ TaskUpdate: task 1 completed

Phase 2: Research Codebase (Parallel Agents)

→ TaskUpdate: task 2 in_progress

Launch 3 agents in a SINGLE Task tool message:

Agent 1: Feature Scout (feature-dev:code-explorer) > Research the codebase to find: (1) existing code related to [requirement], > (2) services, utilities, and patterns that should be reused, (3) relevant file > paths with function signatures and line numbers, (4) existing tests that cover > related functionality. CRITICAL: Use ls and grep to verify every module > name, file path, and directory structure — do NOT guess names based on conventions. > List actual exports with grep -r "export" dir/ instead of assuming names like > apiService.ts or LanguageContext.tsx. > > For dependency upgrade stories, ALSO: (5) check the target package's module > system compatibility: npm view @ exports type --json — if the > project uses CJS (require()) and the target version has no require/node.require > entry in exports, the upgrade is infeasible without an ESM migration. > (6) Search for existing compatibility guard scripts: > grep -rl "verify.*compat\|ERR_REQUIRE_ESM\|require.*" scripts/ tests/. > (7) Check if Jest/Babel masks the breakage — require() calls that fail in > production Node.js can pass in Jest because Babel transpiles ESM→CJS at test time. > > Return a structured report of what EXISTS (with verified paths), what needs > MODIFICATION, and what needs CREATION. For dep upgrades, include a > "Module Compatibility" section with the exports field analysis.

Agent 2: Convention Scanner (general-purpose, model: haiku) > Read the sample spec file at [sampleSpec] and extract: (1) the exact markdown > formatting style (header levels, bold patterns, code block usage), (2) how > sub-tasks are numbered and structured, (3) how acceptance criteria are written, > (4) any project-specific sections not in the standard template. Return a concise > style guide.

Agent 3: Metrics Scout (general-purpose, model: sonnet) > Analyze the requirement and codebase to identify success metrics for this story. > > Research: > 1. What user-facing or system behavior does this story change? What would prove > it's working? (e.g., error rate drops, latency improves, feature adoption grows) > 2. Search for existing observability infrastructure: > grep -rn "metrics\.\|setAttribute\|Sentry\.\|captureMessage\|console\.log.*metric" src/ > 3. Identify which metrics already exist that this story should move, and which > new metrics need to be created > 4. For each metric, recommend the capture mechanism: > - Sentry span attributes (setAttribute()) — queryable in Explore > - Sentry custom metrics (metrics.count/gauge/distribution) — for dashboards > - Structured console logs — for Railway/CloudWatch > - Bruno API test assertions — for contract validation > - Existing feasibility codes — if story affects recommendation quality > > Return a structured report: > `` > ## Success Metrics > | Metric | Type | Current Value | Target | Capture Method | > | "Share link crash rate" | error_rate | ~22 events/week | 0 | Sentry error count | > | "Tips field present" | boolean | false after restart | always true | Bruno assertion | > > ## Existing Instrumentation to Reuse > - [list of existing metrics/spans relevant to this story] > > ## New Instrumentation Needed > - [list of new setAttribute/metrics calls to add] > ``

→ TaskUpdate: task 2 completed

Phase 3: Brainstorm Approaches (with Vertical Splitting)

→ TaskUpdate: task 3 in_progress

3.0 Clarify intent before designing — before proposing approaches, ask 1-3 clarifying questions (one at a time via AskUserQuestion) to fill gaps the codebase research couldn't answer:

• Purpose: What user-facing problem does this solve? What does success look like?
• Constraints: Performance targets? Backward compatibility? Timeline pressure?
• Scope boundaries: What's explicitly out of scope? What adjacent features should NOT change?
• Design preference: Minimal fix vs comprehensive solution? TDD methodology?

Skip clarifying questions if the input (spec file or detailed issue) already answers these. Prefer multiple-choice questions when possible. Never ask more than 3 questions total.

3.1 Assess scope from Phase 2 research. Count estimated sub-tasks, files affected, and layers touched. If any splitting trigger fires (see below), include a vertical split option alongside the single-story approaches.

3.2 Splitting triggers — recommend splitting when ANY of these apply:

| Trigger | Threshold | Why | |---------|-----------|-----| | Sub-task count | > 8 estimated | Too many moving parts for one PR | | Files affected | > 8 files | Review burden, merge conflict risk | | Layers touched | 3+ (MCP + Backend + Frontend) | Cross-layer stories hide integration bugs | | Independent user values | 2+ distinct outcomes | Each value deserves its own validation | | Testable hypotheses | 2+ assumptions to validate | Ship one, learn, then decide on next | | Estimate | > 6 hours | Diminishing returns on large stories |

3.3 Vertical slice rules — each slice must be:

• End-to-end: Touches all layers needed to deliver ONE user-visible behavior
• Independently deployable: Can merge to develop without waiting for sibling slices
• Independently testable: Has its own acceptance criteria and tests
• Valuable alone: Delivers customer value or validates a hypothesis even if

other slices are never built

Anti-pattern: Horizontal slicing (Story A = backend, Story B = frontend, Story C = tests). This creates integration risk and blocks deployment until all slices merge.

3.4 Present options via AskUserQuestion. Structure depends on scope assessment:

If splitting triggers fired — include a split option:

Option 1: Single Story (Minimal)
- Scope: [reduced scope that fits under thresholds]
- Complexity: S/M
- Files: N
- Tradeoff: Leaves out [X, Y]

Option 2: Single Story (Full Scope)
- Scope: [everything requested]
- Complexity: L
- Files: N (⚠️ exceeds 8)
- Tradeoff: Large PR, harder to review

Option 3: Vertical Split into N Stories (Recommended)
- Slice A: "[User-facing behavior 1]" — [layers], ~Xh
- Slice B: "[User-facing behavior 2]" — [layers], ~Xh
- Slice C: "[Hypothesis to validate]" — [layers], ~Xh
- Tradeoff: More specs to write, but each is focused and shippable

If no splitting triggers — standard options:

Option 1: Minimal
- Scope: [fewest changes]
- Complexity: S
- Key tradeoff: [what's excluded]

Option 2: Recommended
- Scope: [balanced]
- Complexity: M
- Key tradeoff: [balance point]

Option 3: Ambitious (optional)
- Scope: [comprehensive]
- Complexity: L
- Key tradeoff: [effort vs completeness]

Team Mode (Optional): When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is enabled, Phase 2 research agents and Phase 3 brainstorming agents can be persistent teammates that iterate on user feedback via SendMessage rather than running as one-shot sub-agents. This allows the Feature Scout to refine its research based on real-time Convention Scanner findings.

Brainstorming rules:

• YAGNI ruthlessly — strip unnecessary features from all approaches before presenting.

If a feature isn't needed for the stated success criteria, don't include it.

• Design for isolation — break into units with clear boundaries. For each unit:

can someone understand it without reading internals? Can you change internals without breaking consumers? If not, the boundaries need work.

• Apply the simplification decision tree before presenting:
• Does this need a new file, or can existing code absorb it?
• Does this need a new abstraction, or can it be inline?
• Does this need backward compatibility, or can it replace directly?
• Does this touch 3+ layers — can it be contained in fewer?
• When presenting a split, name each slice by its customer value, not its

technical layer ("Show hours badge" not "Add businessHours field")

• Order slices by dependency: foundational slices first, enhancement slices later
• Lead with your recommendation — present the recommended option first with

reasoning, then alternatives. Don't force the user to evaluate all options equally.

→ TaskUpdate: task 3 completed

→ If user selected vertical split: delete tasks 4-5, create tasks 4-6 from vertical-split manifest

Phase 4: Generate Spec(s)

→ TaskUpdate: task 4 in_progress

After user selects an approach, generate the spec file(s).

Path A: Single Story (user chose a single-story option)

4.1 Build spec content using:

• The template structure from [references/spec-template.md](references/spec-template.md)
• The formatting style extracted by Convention Scanner (Phase 2)
• The codebase facts from Feature Scout (Phase 2)
• The scope/approach from user selection (Phase 3)

4.2 Populate each section:

| Section | Source | |---------|--------| | Title & Metadata | Discovery script (epic, story number) + user input | | User Story | Extracted from requirements | | Context | From requirements + codebase research | | Solution Overview | From selected approach | | Current Codebase State | From Feature Scout agent (verified paths + signatures) | | Acceptance Criteria | Derived from requirements, one per testable behavior | | Success Metrics | From Metrics Scout agent — what to measure, targets, capture method | | File Structure Map | Aggregated from codebase research — all files to create/modify | | Implementation Tasks | TDD steps with complete code, run commands, expected output | | Testing Checklist | Inferred from tasks (unit, Bruno, E2E as applicable) | | Definition of Done | Standard template + project-specific items |

4.3 Codebase State verification gate (MANDATORY):

Before writing the spec, verify every name in the "Current Codebase State" section against the actual codebase. This prevents the #1 spec quality issue: fabricated module names.

What to verify:

# Every file path listed under "What EXISTS" — must return a result
ls -la path/to/claimed/file.ts

# Every module/hook/context/service name — must exist as an export
grep -r "export.*ClaimedName" frontend/src/ backend/src/

# Every directory structure claim — must match reality
ls frontend/src/components/screens/    # Does this dir exist?

# Every type definition — must match actual values
grep -A5 "type ClaimedType" frontend/src/App.tsx

# Item counts — must be accurate
ls frontend/src/components/*.tsx | wc -l

Common fabrication patterns to catch (from Epic 15 post-mortems):

| Pattern | Example (fabricated → actual) | How to catch | |---------|-------------------------------|--------------| | Plausible module names | apiService.ts → api.ts, mcpClient.js → mcpEventsClient.js | ls + grep the actual directory | | Assumed directory structure | components/screens/ → screens are flat in components/ | ls the parent dir | | Wrong file extensions | locales/en.json → en.ts | ls the directory | | Guessed type values | 'long' → 'extended', 'first_time' → month abbreviations | grep -A5 "type TypeName" | | Inflated counts | "10+ screens" → 5 screens, "10+ MCP endpoints" → 0 | Count with ls | wc -l | | Assumed endpoints/routes | /api/mcp/* proxy routes → no such routes exist | grep -r "router\." src/routes/ |

Rule: If you cannot verify a claim with a command, do NOT include it in the spec. Write "TBD — verify during implementation" instead of guessing.

4.3b Dependency Upgrade Pre-Flight (MANDATORY for dependency upgrade stories):

When the story involves upgrading a package to a new major version, verify module system compatibility BEFORE writing the spec. This catches the #2 spec quality issue: assuming a major version bump is a drop-in replacement when it actually changes the module system (CJS→ESM).

# 1. Check project's module system
grep '"type"' package.json  # "module" = ESM, absent = CJS

# 2. Check how the package is imported
grep -rn "require.*\|from ['\"]" src/ --include="*.ts" --include="*.js"
# If require() is used → project NEEDS CJS support from the package

# 3. Check target version's exports field
npm view @ exports type --json
# Look for "require" or "node.require" entry — if missing, CJS is NOT support

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [abhattacherjee](https://github.com/abhattacherjee)
- **Source:** [abhattacherjee/claude-code-skills](https://github.com/abhattacherjee/claude-code-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.