Implementation Spec Writer

Transform validated design specs into actionable, phased implementation plans.

Usage

planspec:impl-spec planspec/designs/[topic].md

Input Requirements

The design spec must contain (as produced by planspec:brainstorm):

• Problem statement
• Success criteria (must have, quality attributes, anti-goals)
• Approach with alternatives considered
• Design (architecture, data model, interfaces, behavior, testing requirements)
• Risks and mitigations
• Dependencies

Output

Creates planspec/implementations/[topic].md with:

• Phased task breakdown
• Review checkpoints
• Security review gates (where applicable)

The spec is reviewed against code reviewer criteria before finalization to catch issues that would be flagged during implementation.

Process

Step 1: Validate Input

1. Read the design spec file

2. Verify all required sections exist:

   • Problem
   • Success Criteria
   • Approach
   • Design (with sub-sections)
   • Risks
   • Dependencies

3. If sections missing, abort with specific feedback:

   "Cannot generate implementation spec. Design spec missing:
   - [missing section 1]
   - [missing section 2]
   
   Run planspec:brainstorm to complete the design spec first."
   

Step 2: Analyze Codebase

1. Read existing codebase structure:

   • File organization patterns
   • Naming conventions
   • Existing similar implementations (for consistency)
   • Test file locations and patterns

2. Map design components to concrete file paths:

   • Where should new files go?
   • What existing files need modification?
   • Where do tests live?

3. Identify project conventions:

   • Import style
   • Error handling patterns
   • Logging patterns
   • Test framework and patterns

Step 3: Determine Review Requirements

From the design spec, extract:

1. Security review needed if design spec mentions:

   • Authentication/authorization
   • User input handling
   • Database queries
   • API keys/secrets
   • File system access
   • External service calls with credentials
   • Any item in Risks related to security

2. Mark phases for security review based on which tasks touch these areas

Step 4: Generate Task Breakdown

Task Granularity Rules

Each task should be:

• Atomic: One logical unit of work
• Verifiable: Clear acceptance criteria
• Contextual: Includes why, not just what
• Bounded: Completable in one focused session

Task Structure

### Task [Phase].[Number]: [Action verb] [what]

**Context:** [Why this task exists - link to design decision]

**Files:**
- Create: `path/to/new/file.ts`
- Modify: `path/to/existing/file.ts` - [what changes]

**Requirements:**
- [Specific requirement from design spec]
- [Another requirement]

**Acceptance Criteria:**
- [ ] [Verifiable condition - can be checked]
- [ ] [Another verifiable condition]

**Dependencies:** None | Task X.Y, Task X.Z

Phase Structure

Group tasks into logical phases:

## Phase 1: [Foundation/Core/Setup]

[Tasks that must come first - shared infrastructure, types, utilities]

### Task 1.1: ...
### Task 1.2: ...

---

## Phase 2: [Core Implementation]

[Main feature implementation]

### Task 2.1: ...
### Task 2.2: ...
### Task 2.3: Write tests for Phase 2

**Tests should cover:**
- [Critical path from design spec]
- [Edge cases from design spec's Behavior section]
- [Error cases from design spec]

### CHECKPOINT

Gate: Tests pass, issues resolved before Phase 3.

---

## Phase 3: [Integration/Security-Sensitive]

### Task 3.1: ...
### Task 3.2: Write tests for Phase 3

### CHECKPOINT

Security: Auth flow, user input handling, database queries

Gate: Tests pass, issues resolved before completion.

Step 5: Map Design to Tasks

Step 6: Write Implementation Spec

Create file at planspec/implementations/[topic].md:

---
date: YYYY-MM-DD
design-spec: ../designs/[topic].md
status: ready
executor: planspec:impl-spec-executor
---

# Implementation: [Title]

> **Execute with:** `planspec:impl-spec-executor planspec/implementations/[topic].md`

## Overview

[1-2 sentence summary of what we're implementing]

**Design spec:** [link to design spec]
**Security reviews:** Phases X, Y (or "None")

## Prerequisites

- [ ] [Dependency from design spec]
- [ ] [Another dependency]

## Phase 1: [Name]

### Task 1.1: [Title]
...

---

## Phase 2: [Name]

### Task 2.1: [Title]
...

### Task 2.N: Tests for Phase 2

**Test file:** `path/to/tests/feature.test.ts`

**Cover:**
- [ ] [Happy path scenario]
- [ ] [Edge case 1]
- [ ] [Edge case 2]
- [ ] [Error case 1]

### CHECKPOINT

Gate: Tests pass, issues resolved before Phase 3.

---

## Completion Checklist

- [ ] All tasks completed
- [ ] All tests passing
- [ ] All review checkpoints passed
- [ ] Design spec success criteria met:
  - [ ] [Criterion 1]
  - [ ] [Criterion 2]

Step 7: Review Loop

Before finalizing, review the spec to catch issues that would be flagged during code review.

1. Spawn spec reviewer subagent:

   Read ./spec-reviewer-prompt.md, substitute variables:

   • {IMPL_SPEC_PATH} - path to the implementation spec just written
   • {DESIGN_SPEC_PATH} - path to the design spec
   • {CODE_REVIEWER_PATH} - ../impl-spec-executor/code-reviewer-prompt.md
   • {IMPL_SPEC_FILENAME} - filename of the implementation spec

   Task(
     subagent_type: "general-purpose",
     description: "Review impl-spec before finalization",
     prompt: [constructed from template]
   )
   

2. Handle review result:

   IF verdict == "PASS":
     proceed to Step 8
   
   IF verdict == "PASS WITH FIXES" or "FAIL":
     # Patch the impl-spec based on findings
     For each blocking/should-fix issue:
       - Update the specific task description
       - Add missing tasks if needed
       - Clarify vague requirements
   
     # Re-run review
     Go back to step 7.1
   

3. Patch strategy:

   • Edit specific tasks rather than regenerating entire spec
   • For "Task X.Y needs error handling specified" → add error handling to that task's requirements
   • For "Missing task for edge case X" → add new task to appropriate phase
   • For "O(n²) approach described" → update task to specify efficient approach

4. Loop limit:

   • Maximum 3 iterations
   • If still failing after 3, output spec with remaining issues noted
   • User can decide to proceed or manually refine

Step 8: Output Summary

After review passes:

Implementation spec created: planspec/implementations/[topic].md

Review: PASSED (N iterations)

Summary:
- Phases: [N]
- Tasks: [M]
- Checkpoints: [X]
- Security reviews: Phases [list] (or "None")

Prerequisites to verify:
- [Any blocking dependencies]

Ready to execute with: planspec:impl-spec-executor planspec/implementations/[topic].md

Principles

• Traceability: Every task links back to design decisions
• No gaps: Design spec coverage should be 100%
• No invention: Don't add tasks not justified by design spec
• Concrete paths: Use real file paths from codebase analysis
• Meaningful tests: Only where they verify correctness, not for coverage theater
• Review gates: Prevent forward progress with broken/insecure code
• Shift left: Catch code review issues at spec stage, not during implementation

Quick Reference

Prompt Templates

Subagent prompts in this directory:

• ./spec-reviewer-prompt.md - Reviews impl-spec against code reviewer criteria before finalization