Speccer

Transform rough ideas into a structured project specification with actionable issues.

Overview

This skill orchestrates a multi-phase process to distill unstructured input into a single spec document (docs/spec.md) containing:

1. Project overview and tech stack
2. Feature/domain analysis sections
3. Open questions for the user
4. Actionable issues with acceptance criteria

Everything goes in one file. Do not create multiple files or a directory of spec documents.

Output

The entire spec is written to docs/spec.md. This is the only file speccer creates or modifies.

Workflow

Phase 0: Project Foundation

Before analyzing features, establish the project's technical foundation.

1. Identify the tech stack by asking the user:

   • What language/framework will this project use? (e.g., Rust, Rails, Node.js, Python)
   • Is this a new project or adding to an existing codebase?

2. For new projects, determine prerequisites and scaffolding:

   Stack	Prerequisites	Scaffolding Command
   Rust	rustup, cargo	cargo new or cargo init
   Rails	Ruby, bundler, rails gem	rails new + database choice
   Node.js	Node, npm/pnpm/yarn	npm init or framework CLI
   Python	Python, pip/uv, venv	uv init or framework setup
   Go	Go toolchain	go mod init
   Elixir	Erlang, Elixir, mix	mix new or mix phx.new

3. Ask clarifying questions about project setup:

   • Database requirements? (PostgreSQL, SQLite, MySQL, none)
   • Package manager preferences? (npm vs pnpm, pip vs uv)
   • Any specific framework version requirements?
   • CI/CD requirements? (GitHub Actions, etc.)
   • Deployment target? (affects scaffolding choices)

Phase 1: Decomposition

When invoked with rough input:

1. Read the input and identify distinct feature/domain areas
2. Create the initial docs/spec.md with the project overview, tech stack, and list of identified feature areas
3. Output a brief summary of identified features before proceeding

Phase 2: Deep Analysis

For each identified feature/domain area, analyze:

1. What's well-defined vs ambiguous
2. Implementation concerns (without designing solutions)
3. Questions that need user clarification
4. Draft acceptance criteria for potential issues

Write each feature's analysis as a section within docs/spec.md. Use sub-agents (Task tool with subagent_type="general-purpose") to analyze features in parallel if needed, but have them return their analysis as text — do not have sub-agents write separate files. Incorporate their output into the single spec document yourself.

Phase 3: User Clarification

Present questions to the user using AskUserQuestion tool:

• Group related questions where possible
• Provide context for each question
• Offer reasonable default options when applicable
• Update docs/spec.md with answers as they come in

For complex clarifications, ask in batches of 3-4 questions max per interaction.

Phase 4: Refinement

After receiving user answers:

1. Update relevant sections of docs/spec.md with clarifications
2. Mark answered questions as resolved
3. If new questions arise from answers, repeat Phase 3

Phase 5: Issue Generation

When all clarifications are complete:

1. Compile issues starting with setup, then feature issues

2. Add an Issues section to docs/spec.md with:

   • Setup issues first: toolchain installation, project scaffolding, initial configuration
   • Feature issues grouped by area
   • Each issue has: title, description, acceptance criteria
   • Issues are ordered by dependency (setup → foundation → features)

3. If user wants beads integration, for each issue:

   Use beads:create skill to create the issue with:
   - Title from spec
   - Description including acceptance criteria
   - Labels for feature area
   

4. Update the Status section: "Specification complete"

Invocation

The skill can be invoked:

• /speccer - Start fresh with new input
• /speccer refine - Continue refining existing spec (re-run Phase 3-5)
• /speccer issues - Skip to issue generation from existing spec
• /speccer issues --beads - Generate issues and create beads

Maintaining Context

When resuming work:

1. Always read docs/spec.md first
2. Check the Status section to determine which phase to continue
3. Look for the Open Questions section to see pending clarifications

Tips

• Prefer more granular features over fewer large ones
• Questions should be concrete and actionable, not abstract
• Acceptance criteria should be testable/verifiable
• When uncertain about scope, err toward asking the user