Devspec

Development Specification Creation Workflow

This skill provides a structured, interactive workflow for creating Development Specifications. It walks each Dev Spec section collaboratively, manages the Deliverables Manifest, and runs a mechanical finalization checklist.

Pipeline Taxonomy (authoritative — locked 2026-04-26)

The wave-pattern pipeline is built from four primitives. This skill teaches them explicitly so every Pair walking a Dev Spec shares the same vocabulary (per docs/phase-epic-taxonomy-devspec.md R-02..R-04, R-12):

| Primitive | Platform shape | Role | |-----------|----------------|------| | Plan | GitHub/GitLab issue with type::plan label | The top-level container. One issue per Plan; its number is the plan_id. Its body holds frozen scope (Goal / Scope / DoD / Phases checklist); its comments hold the Decision Ledger and lifecycle events. /devspec create anchors its walk on the Plan issue. | | Phase | Internal to phases-waves.json — NO platform issue | A sequential ordering unit within a Plan. Phases partition the Dev Spec's §8 Implementation Plan. They exist only in phases-waves.json; they are not issues, not labels. | | Wave | Internal to phases-waves.json — NO platform issue | A concurrency unit within a Phase. Stories in the same Wave are parallelizable (by dependency); Waves within a Phase run in order. | | Story | GitHub/GitLab issue with type::feature / type::bug / type::chore / type::docs | The smallest execution unit. One issue per Story. Every Story declares its depends_on in phases-waves.json. |

Epic is NOT a pipeline primitive. Epic is an optional PM-layer label (type::epic on a parent tracker issue; epic::N label on child Stories) that a Pair may use to group Stories thematically for program-management rollups. The pipeline (/prepwaves, /nextwave, /wavemachine) does not read type::epic or epic::N; they read phases-waves.json. Treating "Epic" as a pipeline container is the old vocabulary and is explicitly retired.

The rest of this skill body uses Plan / Phase / Wave / Story throughout. When "Epic" appears, it is always qualified as the PM-layer label.

Platform Detection

Before proceeding, detect the platform:

1. Check .claude-project.md for cached platform config
2. If not cached, run git remote -v and inspect the origin URL
3. GitHub → gh CLI, GitLab → glab CLI

Commands

• /devspec create — Interactive Dev Spec generation (walk each section, build Deliverables Manifest, append Decision-Ledger comments to the Plan issue)
• /devspec finalize — Mechanical finalization checklist (verify Dev Spec completeness)
• /devspec approve — Approval gate (run finalization, present summary, record approval)
• /devspec upshift — Backlog population (create Story issues from approved Dev Spec, write phases-waves.json with plan_id + per-Story depends_on)

Usage

# Create a new Dev Spec interactively
/devspec create

# Run the finalization checklist on an existing Dev Spec
/devspec finalize

# Approve a finalized Dev Spec (human gate)
/devspec approve

# Create backlog issues from an approved Dev Spec
/devspec upshift

# Show help
/devspec

---

{{#if (eq args "create")}} {{> devspec-create}} {{else if (eq args "finalize")}} {{> devspec-finalize}} {{else if (eq args "approve")}} {{> devspec-approve}} {{else if (eq args "upshift")}} {{> devspec-upshift}} {{else}} {{> devspec-help}} {{/if}}

/devspec Command Reference

You've invoked /devspec without a command. Use one of:

/devspec create — Interactive Dev Spec Generation

Walk each Dev Spec section collaboratively. I'll generate a draft for each section, present it for review, wait for your feedback, and — after each section the Pair approves — append a [ledger D-NNN] comment to the Plan tracking issue recording the decision. After Section 5 (Detailed Design), we'll walk the Deliverables Manifest defaults together.

Input sources: DDD domain model, external document, or verbal description.

Prerequisite: A Plan tracking issue (run /issue plan "" first if one doesn't exist).

/devspec finalize — Finalization Checklist

Run the Section 7.2 finalization checklist mechanically against an existing Dev Spec. Reports pass/fail per item with explanation.

/devspec approve — Approval Gate

Run the finalization checklist, present a Dev Spec summary (section count, Story count, Wave count, deliverable count), and hard-stop for human approval. On approval, records approval metadata in the Dev Spec and appends a [ledger D-NNN] comment to the Plan issue. On rejection, lists failing items with suggested fixes.

Prerequisite: A finalized Dev Spec that passes all checklist items.

/devspec upshift — Backlog Population

Create backlog issues from an approved Dev Spec's Section 8 (Phased Implementation Plan). Creates one Story issue per Story from §8, writes phases-waves.json with plan_id (the Plan issue number) and per-Story depends_on, and backfills Story issue numbers into the Dev Spec and the Plan issue's Phases checklist. Optionally creates a PM-layer Epic parent tracker (type::epic) if the Pair requests one.

Prerequisite: An approved Dev Spec (must have approval metadata from /devspec approve).

Which command would you like to run?

Interactive Dev Spec Generation

I'll guide you through creating a complete Dev Spec, section by section. For each section, I'll generate a draft, present it for review, wait for your feedback, and — once you approve — append a [ledger D-NNN] comment to the Plan tracking issue recording the decision. The Decision Ledger (per docs/phase-epic-taxonomy-devspec.md §5.1, §5.2) is the authoritative record of decided matters across the Plan's lifecycle.

Step 0: Resolve the Plan Issue

Before walking the Dev Spec, identify the Plan tracking issue this Dev Spec is anchored to:

1. Ask the user: "What is the Plan tracking issue number for this Dev Spec?" (e.g., #499)
2. If the user does not yet have a Plan issue, tell them: "Create one first with /issue plan \"\" — the returned issue number is your plan_id. Then re-run /devspec create."
3. Record the Plan issue number as plan_id for the rest of the walk. Every [ledger D-NNN] comment this session appends will target this issue.
4. Determine the starting Ledger ID: fetch the Plan issue's existing comments, find the highest [ledger D-NNN] prefix already posted (or zero if none), and continue monotonically from D-(max+1). See Step 3.5 below.

Step 1: Determine Input Source

How would you like to provide the concept for this Dev Spec?

Check the arguments and conversation context for input mode. The three input sources are equally first-class — /devspec create MUST work with any of them. Do NOT assume a DDD artifact exists on disk.

1. Verbal Description — If no document is provided, ask the user to describe the project concept verbally. This is a first-class input mode that works without any DDD or external artifacts on disk.
2. External Document — If the user provides a path to any non-DDD document (concept doc, brief, notes), read it and extract the concept.
3. DDD Domain Model — Only if the user provides a path to a domain model (e.g., docs/DOMAIN-MODEL.md), or explicitly says "from the domain model", read it and use the DDD → Dev Spec translation protocol (docs/DDD-to-devspec-protocol.md) as the mapping guide. This is opt-in, not a prerequisite.

If input is verbal:

• Capture the verbal description directly into the section walk
• Do NOT look for docs/DOMAIN-MODEL.md or docs/SKETCHBOOK.md
• Use the captured description as the foundation for drafting each section

If input is an external document:

• Read the document
• Use it as the foundation for drafting each section

If input is a DDD domain model:

• Read docs/DDD-to-devspec-protocol.md for the translation rules
• Apply the 8-step translation as the backbone, but still walk each section interactively
• The protocol provides structure; the user provides judgment

Load-bearing decoupling rule: /devspec create must never fail due to a missing docs/DOMAIN-MODEL.md or docs/SKETCHBOOK.md. Those files are only read in the DDD input mode. In verbal and external-document modes, the skill must not touch them.

Step 2: Ask for Project Name

What should the Dev Spec be named? (e.g., "my-project" → docs/my-project-devspec.md)

Read docs/devspec-template.md to load the template structure.

Step 3: Walk Each Section

For each Dev Spec section (1 through 9), follow this pattern:

1. Generate a draft for the section based on the input source
2. Present the draft to the user
3. Ask for feedback: "Does this look right? Any changes before we move on?"
4. Wait for the user to approve or request changes
5. Incorporate feedback — iterate until the user is satisfied
6. Append a [ledger D-NNN] comment to the Plan issue (see Step 3.5 below) capturing the decisions locked in this section
7. Record the final version and move to the next section

Step 3.5: Append Decision-Ledger Comment to the Plan Issue

This is the load-bearing step. After the Pair approves each section, the skill appends a [ledger D-NNN] comment to the Plan tracking issue. Per Dev Spec §5.2.1 the entry MUST conform to this schema:

[ledger D-NNN] /devspec §X.Y · 
**Decision:** 
**Rationale:** 

— ****  ()

If the entry corrects a prior entry (new evidence, factual fix), include **Supersedes:** D-MMM on the line after the header (per §5.2.4 Correction workflow). Never edit the original D-MMM comment — append a new one.

Mechanics:

1. Compute the next monotonic ID. Re-read the Plan issue's comments just before posting (to catch concurrent writes); find the max existing D-NNN; post as D-(max+1). The Tier 2 lint validator (cc-workflow#501) will flag collisions if two tools race.
2. Compose the body following the §5.2.1 schema above. Source is the canonical /devspec §X.Y form; if the decision pins a specific requirement, use /devspec §X.Y R-NN.
3. Resolve agent identity. Read /.claude/agent-identity.json for Dev-Name, Dev-Avatar, and the project's Dev-Team from CLAUDE.md (fallback: /tmp/claude-agent-.json). These populate the signature line.
4. Post the comment by invoking the pr_comment MCP tool (mcp__sdlc-server__pr_comment) with { number: , body: }. On GitHub and GitLab the tool targets the unified issue/PR comment stream, so it works for issue comments too.
5. When to write entries — per Dev Spec §5.2.2, write a [ledger D-NNN] comment for each of:

• Pair approves a §1.5 non-goal
• Pair approves a §2 constraint (Technical or Product)
• Pair approves a §3 requirement (EARS)
• Pair approves a §5 design choice
• /devspec approve completes (one summary entry)

Routine lifecycle events (Phase transitions, Wave completions, Story merges) do not get [ledger] comments — they use their own typed prefixes ([phase-start], [story-merge], etc. per §5.1.3).

1. If pr_comment fails (network, permissions, rate-limit): retry once; on second failure tell the Pair "Could not append ledger entry D-NNN to Plan issue # — . Paste this into the issue manually:" and render the entry for copy-paste. Do NOT abort the walk — the Dev Spec file is still the primary record; the Ledger is the append-only replay.

Example (taken from docs/phase-epic-taxonomy-devspec.md §5.2.4):

[ledger D-011] /devspec §5.1 revised · 2026-04-26T19:40Z
**Supersedes:** D-006
**Decision:** Plan issue runtime state lives in ISSUE COMMENTS, not in mutable body sections.
**Rationale:** BJ's insight during §5.1 walk. Comments are append-only at the PLATFORM level...

— **Takashi** 🦔 (cc-workflow)

Section Walk Order

Section 1: Problem Domain

• 1.1 Background
• 1.2 Problem Statement
• 1.3 Proposed Solution
• 1.4 Target Users (if DDD input: translate from Actors responsibility matrix)
• 1.5 Non-Goals → append ledger entry per Non-Goal

Section 2: Constraints → append ledger entry per Constraint

• 2.1 Technical Constraints
• 2.2 Product Constraints

Section 3: Requirements (EARS Format) → append ledger entry per Requirement

• If DDD input: translate policies to EARS requirements using the heuristic table
• Group requirements by theme
• Number sequentially: R-01, R-02, ...

Section 4: Concept of Operations

• 4.1 System Context
• 4.X Operational flows (if DDD input: derive from commands and serial chains)

Section 5: Detailed Design → append ledger entry per Design Choice

• 5.1+ Design topics (project-specific)
• 5.A Deliverables Manifest → see Step 4 below
• 5.B Installation & Deployment
• 5.N Open Questions

Section 6: Test Plan

• 6.1 Test Strategy
• 6.2 Integration Tests
• 6.3 End-to-End Tests
• 6.4 Manual Verification Procedures

Section 7: Definition of Done

• Global DoD checklist
• 7.2 Dev Spec Finalization Checklist (pre-populated from template)

Section 8: Phased Implementation Plan

• Phase structure, Stories grouped into Waves
• Each Story declares depends_on on other Story titles/IDs (may be empty [])
• After this section: verify manifest wave assignments (see Step 6)

Section 9: Appendices

• Appendix V: VRTM skeleton
• Additional appendices as needed

Step 4: Walk the Deliverables Manifest (After Section 5)

After completing the design topics in Section 5, walk the Tier 1 Deliverables Manifest defaults with the user.

For each Tier 1 row (DM-01 through DM-09):

1. Present the row: ID, deliverable, category, default file path
2. Ask: "Confirm this deliverable? If not applicable, provide a rationale (N/A — because [reason])."
3. Record the response: confirmed (with any file path adjustments) or N/A with rationale
4. If confirmed: ask which Wave/Phase will produce it (fill "Produced In" column)

Tier 1 defaults to walk:

| ID | Deliverable | Category | |----|-------------|----------| | DM-01 | README.md | Docs | | DM-02 | Unified build system (Makefile) | Code | | DM-03 | CI/CD pipeline | Code | | DM-04 | Automated test suite | Test | | DM-05 | Test results (JUnit XML) | Test | | DM-06 | Coverage report | Test | | DM-07 | CHANGELOG | Docs | | DM-08 | VRTM | Trace | | DM-09 | Audience-facing doc (ops runbook, user manual, API/CLI ref) | Docs |

Step 5: Scan for Tier 2 Triggers

After walking Tier 1, scan the Dev Spec content for Tier 2 trigger conditions:

| Trigger Condition | Deliverable to Add | |-------------------|--------------------| | MV-XX items exist in Section 6.4 | Manual test procedures document | | >2 interacting components in design | Architecture document | | Project deploys infrastructure | Deployment verification procedures | | Project has host/platform requirements | Environment prerequisites document |

For each trigger that fires:

1. Tell the user: "Tier 2 trigger fired: [condition]. Adding [deliverable] to the manifest."
2. Ask for file path and Wave assignment
3. Add the row to the Deliverables Manifest

Step 6: Verify Manifest Wave Assignments (After Section 8)

After completing Section 8 (Implementation Plan), verify that every Deliverables Manifest row has a "Produced In" Wave/Phase assignment.

For any row missing an assignment:

1. Flag it: "DM-XX ([deliverable]) has no Wave assignment yet."
2. Ask the user which Wave/Phase should produce it
3. Update the row

This is a hard gate — the Dev Spec cannot be finalized without complete Wave assignments.

Step 7: Write the Dev Spec

After all sections are walked and the manifest is complete:

1. Check for existing Dev Spec: Call devspec_locate to see if a Dev Spec already exists for this project. If one is found, confirm with the

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Wave-Engineering
• Source: Wave-Engineering/claudecode-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.