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

1. 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

1. Map design components to concrete file paths:

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

1. 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

1. 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: - {IMPLSPECPATH} - path to the implementation spec just written - {DESIGNSPECPATH} - path to the design spec - {CODEREVIEWERPATH} - ../impl-spec-executor/code-reviewer-prompt.md - {IMPLSPECFILENAME} - filename of the implementation spec

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

1. 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 ```

1. 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

1. 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