OpenParable
Skip to content
← Back to skills

Spec Writer

Productivity
spec-writer

Spec Writer is an Agent Skill for productivity published in the freekmurze/dotfiles repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create detailed software specifications through iterative Q&A brainstorming. Use when starting a new project, feature, or app. Produces spec.md, architecture docs, implementation plans with step-by-step prompts, and todo checklists. Triggers include "write a spec", "plan this project", "brainstorm this idea", "create implementation plan", or any new project/feature planning.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/freekmurze/dotfiles/blob/HEAD/config/claude/skills/spec-writer/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/spec-writer, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Spec Writer

Transform ideas into developer-ready specifications through structured brainstorming and planning.

The Process

Phase 1: Idea Honing (Brainstorm)

Ask ONE question at a time to develop a thorough spec. Each question builds on previous answers. Goal: detailed specification ready for implementation.

Start with:

I'll help you develop a detailed spec for this idea. I'll ask one question at a time.

Let's start: [First clarifying question about the core problem/goal]

Key areas to explore:

  • Core problem: What pain point does this solve?
  • Users: Who uses this? What are their workflows?
  • Features: What are the must-haves vs nice-to-haves?
  • Data: What entities exist? How do they relate?
  • Integrations: What external systems are involved?
  • Constraints: Performance, security, tech stack requirements?
  • Edge cases: What could go wrong? How to handle it?

When brainstorming concludes naturally, compile into SPEC.md.

Phase 2: Architecture

Create ARCHITECTURE.md covering:

  • System overview diagram (Mermaid)
  • Component breakdown
  • Data flow
  • Key technical decisions
  • File/folder structure

Phase 3: Implementation Plan

Break the spec into small, iterative chunks:

  1. First pass: Major phases/milestones
  2. Second pass: Break each phase into tasks
  3. Third pass: Ensure tasks are:
    • Small enough for safe implementation with tests
    • Big enough to move the project forward
    • Building on previous tasks (no orphaned code)
    • Ending with integration/wiring

Output: PROMPT_PLAN.md with ready-to-use prompts for each step.

Phase 4: Checklist

Generate TODO.md as a checkable list that tracks progress.

Output Structure

analysis/                    # or docs/, specs/, etc.
├── SPEC.md                  # Full specification
├── ARCHITECTURE.md          # System design
├── PROMPT_PLAN.md           # Step-by-step implementation prompts
├── TODO.md                  # Checklist version
└── phases/                  # Optional: detailed phase docs
    ├── 01-phase-name.md
    ├── 02-phase-name.md
    └── ...

SPEC.md Template

# [Project Name] Specification

## Overview
[One paragraph summary]

## Problem Statement
[What pain point this solves]

## Users & Personas
[Who uses this and how]

## Features

### Must Have (MVP)
- [ ] Feature 1: [description]
- [ ] Feature 2: [description]

### Should Have
- [ ] Feature 3: [description]

### Nice to Have
- [ ] Feature 4: [description]

## Data Model
[Entities, relationships, key fields]

## User Flows
[Step-by-step workflows for key actions]

## Technical Requirements
- Stack: [technologies]
- Integrations: [external services]
- Performance: [requirements]
- Security: [considerations]

## Edge Cases & Error Handling
[What could go wrong and how to handle it]

## Success Criteria
[How do we know it's done? What tests prove it works?]

## Open Questions
[Anything still TBD]

PROMPT_PLAN.md Format

Each prompt section should:

  1. Reference what exists (files, patterns to follow)
  2. State the specific task
  3. Include verification criteria (tests, expected output)
  4. Be tagged with markdown code blocks for easy copy/paste
## Phase 1: [Name]

### Step 1.1: [Task Name]

**Context**: [What exists, what patterns to follow]

**Prompt**:
\`\`\`
[Ready-to-use prompt for the AI agent]

Verification:
- [ ] Test X passes
- [ ] Feature Y works as expected
\`\`\`

### Step 1.2: [Next Task]
...

Best Practices

  1. One question at a time during brainstorming — don't overwhelm
  2. Be specific — vague specs produce vague implementations
  3. Include verification — every feature needs a "done" signal
  4. Reference patterns — point to existing code as examples
  5. Small steps — each prompt should be achievable in one session
  6. No orphans — every step ends with integration
  7. Test-first thinking — define expected behavior before implementation

When to Use Each Phase

SituationStart At
Vague idea, exploringPhase 1 (Brainstorm)
Clear requirements, need structurePhase 2 (Architecture)
Architecture known, need execution planPhase 3 (Plan)
Resuming existing projectPhase 4 (TODO review)