Speccer

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:

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

Spec Document Template

Template for the single spec document (docs/spec.md) created by speccer.

# Project: [Name]

## Overview

[2-3 sentence summary of the entire project scope]

## Tech Stack

| Component | Choice | Notes |
|-----------|--------|-------|
| Language | [e.g., Rust, Ruby, TypeScript] | [Version if specific] |
| Framework | [e.g., Axum, Rails 8, Next.js] | |
| Database | [e.g., PostgreSQL, SQLite, none] | |
| Package Manager | [e.g., cargo, bundler, pnpm] | |

## Status

**Current Phase**: [Foundation | Decomposition | Analysis | Clarification | Refinement | Complete]
**Progress**: [Brief note on what's done/pending]

## Project Setup

### Prerequisites

| Tool | Version | Installation |
|------|---------|--------------|
| [Tool name] | [Version or "latest"] | [Install command or link] |

### Scaffolding

Step 1: [Description]

[command]

### Configuration Choices

| Choice | Decision | Rationale |
|--------|----------|-----------|
| Database | [e.g., PostgreSQL] | [Why this choice] |

---

## Features

### [Feature A]

#### Summary

[2-3 sentences describing what this feature area covers and its core purpose]

#### Key Requirements

- [Requirement 1]: [Brief description]
- [Requirement 2]: [Brief description]

#### Ambiguities & Questions

1. **[Question summary]**
   - Context: [Why this matters for implementation]

#### Decisions

- Q1: [Answer received, or "Pending"]

#### Suggested Issues

- **[Issue title]**: [Brief description]. Acceptance criteria: [testable criteria].

---

### [Feature B]

[Same structure as Feature A]

---

## Open Questions

Questions awaiting user clarification:

### [Feature Area]

1. **[Question]** — [Context for why this matters]. Status: Pending
2. **[Question]** — [Context]. Status: Answered — [answer]

---

## Issues

Total issues: X

### Implementation Order

**Setup issues come first**, then features ordered by dependency.

### Setup

#### [Issue Title]

**Description**: [What this accomplishes]

**Acceptance Criteria**:
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]

**Labels**: setup

---

### [Feature A]

#### [Issue Title]

**Description**: [What this accomplishes]

**Acceptance Criteria**:
- [ ] [Testable criterion 1]
- [ ] [Testable criterion 2]

**Labels**: [feature-area]
**Depends on**: [Other issues, if any]

---

## Original Input

<details>
<summary>Click to expand original rough notes</summary>

[Paste or summarize original input here for reference]

</details>

## Notes

[Any project-wide constraints, preferences, or context]