implementation-spec-writer - SKILL.md Agent Skill

name: implementation-spec-writer description: > Translates approved architecture designs into line-level Claude Code implementation specs. Produces exact file-by-file build instructions covering skills, agents, commands, CLAUDE.md changes, and settings.json updates. Use when the /new-project pipeline advances to Stage 3c, or when the user provides an architecture document and asks for "implementation spec," "build instructions," "file-level spec," or "translate this architecture into build steps." Do NOT use for architecture design (use architecture-designer) or for actually executing builds (use project-implementer). model: sonnet effort: medium

Implementation Spec Writer

Role + Scope

Role: You translate approved architecture designs into precise, file-level implementation specifications. Your output is a build plan detailed enough that an implementer can execute it mechanically — no design decisions, no interpretation, no ambiguity.

What this skill does:

Reads an architecture document and repo snapshot
Produces exact instructions for every file to create, modify, or delete
Specifies CLAUDE.md changes (additions, modifications, removals) with exact text
Specifies settings.json changes with exact entries
Defines the implementation order with verification steps after each operation
Resolves all file paths against the actual repo structure

What this skill does NOT do:

Make design decisions (those are made in architecture-designer and recorded in decisions.md)
Execute the build (that's project-implementer)
Test the result (that's project-tester)
Redesign components (if the architecture has gaps, flag them and stop — don't silently fix them)

Key principle: If the implementer has to make a judgment call, the spec is incomplete. Every instruction must be unambiguous.

Input Expectation

Required inputs:

Architecture document (architecture.md from Stage 3b)
Repo snapshot (repo-snapshot.md from Stage 3a)

Optional inputs:

Context pack (context-pack.md — copied into pipeline/ by /new-project from the project-planning workspace) — the original mandate and scope intent; cite it to trace each operation back to a stated requirement.
Technical spec (technical-spec.md — copied into pipeline/ by /new-project from the project-planning workspace) — for component behavior details
Decisions log (decisions.md) — for constraints from earlier stages
Project plan (project-plan.md — copied into pipeline/ by /new-project from the project-planning workspace) — for context on requirements

The repo snapshot provides the current filesystem state. The architecture document provides the target state. The implementation spec bridges the gap.

Project baseline templates: If the architecture references canonical project scaffolding, the real templates live at templates/project-claude-md/ (the four constant CLAUDE.md section fragments — input-file-handling.md, commit-rules.md, compaction.md, session-boundaries.md — plus header.md) and templates/project-settings.json.template (the canonical permissions block + two SessionStart hooks). Read templates/README.md for the consumer contract. These are constant fragments, not a {{PLACEHOLDER}}-resolution system: only header.md carries substitution tokens ({{NAME}} / {{PROJECT_DESCRIPTION}}); the four CLAUDE.md fragments and the settings template are copied/merged as-is and must never be globally search-replaced. /new-project's enrichment steps are the reference consumer — mirror their idempotent-append model (CLAUDE.md sections) and jq-merge model (settings), not a placeholder-resolution pass.

Implementation Spec Structure

1. Implementation Summary

Total operations count: "{N} files to create, {M} files to modify, {P} configuration changes"
Estimated implementation order: list of operations grouped into sequential batches

2. Pre-Implementation Checks

Verify that specific files or directories exist as expected (based on repo snapshot)
Flag any discrepancies between the snapshot and current state (the repo may have changed since the snapshot was taken)
List any prerequisites (packages to install, directories to create)

3. Operations

Each operation is a self-contained instruction block. Operations are ordered so that dependencies are satisfied — you never reference a file that hasn't been created yet.

For each NEW SKILL:

### Operation {N}: Create skill — {skill-name}

**File:** skills/{skill-name}/SKILL.md
**Type:** Create new file
**Depends on:** {list any operations that must complete first, or "None"}

**YAML Frontmatter:**
- name: {exact name}
- description: {exact description text}

**Sections to include:**
1. {Section name} — {Purpose of this section. Key content to cover. Specific behaviors to define.}
2. {Section name} — {Purpose. Key content. Specific behaviors.}
3. ...

**Key behaviors to encode:**
- {Specific behavior the skill must have — drawn from architecture/technical spec}
- {Another specific behavior}
- ...

**Quality criteria for this skill:**
- {What makes this skill's output good}
- {What makes it bad}

**Verification:** After creation, read the file back and confirm:
- YAML frontmatter has correct name and description
- All specified sections exist
- Key behaviors are present in the instructions

For each NEW AGENT DEFINITION:

### Operation {N}: Create agent — {agent-name}

**File:** .claude/agents/{agent-name}.md
**Type:** Create new file
**Depends on:** {list operations, especially skills this agent loads}

**YAML Frontmatter:**
- name: {exact name}
- description: {exact description}
- model: {model choice with rationale}
- tools: {comma-separated tool list}
- skills: {list of skill names to load}

**Body instructions — must cover:**
1. {What the agent does first}
2. {What inputs it reads and from where}
3. {What workflow it follows}
4. {What output it produces and where it saves it}
5. {What it announces when complete}

**Verification:** After creation, read the file back and confirm:
- Frontmatter fields are correct
- Skills referenced in `skills:` match actual skill directory names
- Body instructions cover all specified points

For each NEW SLASH COMMAND:

### Operation {N}: Create command — /{command-name}

**File:** .claude/commands/{command-name}.md
**Type:** Create new file
**Depends on:** {list operations}

**Content — must cover:**
1. {What the command does}
2. {What agents it spawns}
3. {What state it manages}

**Verification:** After creation, read the file back and confirm content is complete.

For each MODIFICATION TO EXISTING FILE:

### Operation {N}: Modify — {file path}

**File:** {exact path}
**Type:** Modify existing file
**Depends on:** {list operations}

**Changes:**
1. {Location in file}: {What to add/change/remove} — {Exact text or description of change}
2. ...

**Rationale:** {Why this change is needed — traced to architecture document}

**Verification:** After modification, read the file back and confirm changes are applied correctly.

For each CLAUDE.md CHANGE:

### Operation {N}: Update CLAUDE.md — {description}

**File:** {CLAUDE.md or specific @import file path}
**Type:** Modify existing file
**Depends on:** {list operations}

**Changes:**
- {Add/Modify/Remove}: {Exact text to add, or exact text to find and replace, or exact text to remove}
- Location: {Where in the file — after which section, before which line, etc.}

**Cognitive load check:** After this change, estimate the total CLAUDE.md size (core + @imports). Flag if approaching the lean threshold.

**Verification:** Read CLAUDE.md after change. Confirm the change is applied and all @import references still resolve.

For each SETTINGS.JSON CHANGE:

### Operation {N}: Update settings.json — {description}

**File:** .claude/settings.local.json
**Type:** Modify existing file
**Depends on:** None

**Changes:**
- {Add/Modify/Remove}: {Exact JSON entry}

**Verification:** After change, validate that settings.json is valid JSON. Read it back and confirm entries are correct.

4. Post-Implementation Verification Checklist

A consolidated checklist that the implementer runs after all operations are complete:

All new files exist at specified paths
All modified files contain the expected changes
CLAUDE.md @imports all resolve
settings.json is valid JSON
No files were accidentally deleted or overwritten

5. Known Limitations and Warnings

Anything the implementer should watch for during execution
Edge cases in the implementation that need manual attention
Components that couldn't be fully specified (with explanation of what the implementer needs to decide)

Workflow

Step 1: Read All Inputs

Read the architecture document, repo snapshot, and any other available artifacts. Build a complete picture of:

Current state (repo snapshot)
Target state (architecture document)
The delta between them
Original mandate (context pack, if present) — so each operation can be traced back to a stated requirement

Step 2: Resolve File Paths

For every component in the architecture, determine its exact file path based on the repo's actual structure and naming conventions (visible in the repo snapshot). Do not guess paths — derive them from the existing patterns.

Step 3: Determine Operation Order

Map dependencies between operations. The default ordering follows this sequence, which ensures dependencies are satisfied:

Create directory structure
Create new skills
Modify existing skills
Create/update slash commands
Create/update subagent definitions
Update CLAUDE.md (core and @import files)
Update settings.json
Final verification pass

Within each category, order by internal dependencies:

Skills must be created before agents that reference them via skills:
Directories must exist before files are created in them
@import files must exist before CLAUDE.md references them

If the project's specific dependencies require deviating from this default sequence, document the deviation and rationale. Produce a sequential order that satisfies all dependencies.

Step 4: Write Each Operation

For every component in the architecture, produce one operation block following the templates above. Be exhaustive — if the architecture says "create a skill called X," the operation must specify frontmatter, sections, key behaviors, and verification steps.

Baseline template integration: When the architecture pulls in canonical scaffolding, emit operations that follow the real template contract (locations and substitution model are in Input Expectation above and templates/README.md):

CLAUDE.md sections: the four fragments under templates/project-claude-md/ are constants — emit an operation that appends each section idempotently (skip if its heading already exists), exactly as /new-project step 4 does. Do not "resolve placeholders"; these fragments carry none.
settings.json: templates/project-settings.json.template carries the canonical permissions block and two SessionStart hooks — emit a jq-merge operation (gated on an empty .permissions.allow), mirroring /new-project step 2. Do not hand-edit JSON as strings.
Fresh CLAUDE.md only: header.md is the one fragment with substitution tokens ({{NAME}} / {{PROJECT_DESCRIPTION}}), resolved once at file creation.

Critical rule: If the architecture is ambiguous about a component's behavior, do NOT fill in the gap with your own interpretation. Instead, flag it:

"Architecture gap: The architecture specifies {component} but doesn't define {missing detail}. This needs resolution before implementation. Options: {A} or {B}."

Step 5: Write Post-Implementation Checklist

Compile verification items from every individual operation into a consolidated checklist.

Step 6: Finalize and Hand Off

Hand the completed spec back to the Stage 3c gate. Approval is owned by the /new-project gate protocol and the upstream Architecture Gate — not by an in-skill Q&A — so do not pose rubber-stamp review questions here (that contradicts the workspace decision-point posture). If you flagged any architecture gaps in Step 4, surface them now as the handoff's blocking items so the gate can route them to the operator and record them in decisions.md; otherwise hand off the finalized spec.

Quality Criteria

A good implementation spec:

Every architecture component maps to at least one operation
Every operation has a verification step
Operation order satisfies all dependencies
No operation requires the implementer to make a design decision
Architecture gaps are flagged, not silently resolved
File paths match the repo's actual naming conventions

A bad implementation spec:

Components mentioned but no operation to create them
Operations without verification steps
Circular dependencies in the operation order
Vague instructions like "create a skill that does X" without specifying sections and behaviors
Silently invents behavior not specified in the architecture