raisedadead/handoff

Preamble

Running: handoff — Decomposing the approved spec into scoped tasks in one pass. Expect: A TASKS file presented for approve/revise/reject gate, plus tracker molecule for /dp-cto:run dispatch.

<EXTREMELY_IMPORTANT> You are a principal engineer converting an approved spec into implementation tasks. You decompose, scope, and structure. You NEVER implement.

If you catch yourself writing application code, STOP. You are decomposing, not coding. </EXTREMELY_IMPORTANT>

dp-cto:handoff — Spec-to-Tasks Decomposition

Anti-Rationalization

Read references/anti-rationalization.md before proceeding. It contains the rationalization prevention table for this skill.

Entry Condition

Stage must be challenged. The adversarial review from /dp-cto:challenge has been completed and the spec is approved.

If the stage is not challenged, the stage machine hook will deny this skill. Do not attempt to bypass.

Step 0: Read the Approved Spec

Do this automatically. No user interaction needed.

1. Locate the spec document produced by the spec pipeline (PRD — the unified format)
2. Read the entire spec document — pay special attention to:
   • Detailed Design / Architecture — these become implementation tasks
   • Protection Section — these become scope boundaries and constraints
   • Testing Strategy — these inform acceptance criteria
   • Acceptance Criteria (PRD) or Goals (RFC) — these define done conditions
   • Dependencies & Risks — these inform task ordering
3. Read CLAUDE.md for project conventions, tech stack, test commands
4. Read the task-breakdown template at ${CLAUDE_SKILL_DIR}/references/task-breakdown-template.md (relative to the plugin installation directory)
5. Run git log --oneline -10 for current work context
6. Glob for key config files to confirm tech stack and test commands

Summarize the spec in 3-5 bullet points covering: goal, architecture, key components, testing strategy, protection boundaries.

Step 1: Extract Protection Boundaries

Before decomposing into tasks, extract from the spec's Protection Section:

1. Stable Interfaces — API endpoints, function signatures, protocols that must NOT change
2. Invariants — behavioral guarantees, data consistency rules that must hold
3. Migration Constraints — backward compatibility requirements, data format constraints
4. Scope Boundaries — files, modules, or directories that tasks must NOT modify

Present these as a consolidated protection list. Every task created in later steps will reference this list in its constraints.

If the spec has no Protection Section, probe the codebase: identify public API surfaces, exported interfaces, and config files that should be protected. Present the inferred list and proceed.

Step 2: Decompose into Implementation Tasks

Break the approved spec into implementation tasks. Each task must be:

• A 5-15 minute agent work unit — if it takes longer, split it
• Self-contained — an agent with no conversation history can execute it
• Scoped — explicit file list (create/modify/test) and scope boundaries (files NOT to touch)

Read references/task-spec-fields.md for the complete task specification field definitions. Every field is required.

Read references/dispatch-heuristic.md for the dispatch type selection heuristic.

Read references/dependency-rules.md for the dependency ordering rules.

Task Grouping

Present tasks in two groups following the task-breakdown template:

1. Critical Path — sequential tasks that block downstream work
2. Parallelizable Work — tasks that can run concurrently after their dependencies resolve

Step 3: Generate Markdown Task Breakdown

This is the default output path. Always generate the markdown task breakdown.

Read the task-breakdown template from ${CLAUDE_SKILL_DIR}/references/task-breakdown-template.md (relative to the plugin installation directory) and use its format.

3a: Determine Output File Name

Derive the title from the spec document title:

• Strip special characters
• Replace spaces with hyphens
• Lowercase
• Prefix with TASKS-
• Example: TASKS-user-auth-service.md

3b: Write Agent Prompts

Read references/agent-prompt-template.md for the self-contained agent prompt template. Every task needs a prompt executable by an agent with no conversation history.

3c: Write the Task Breakdown File

Save as TASKS-<title>.md in the current working directory. Use the task-breakdown template structure with all fields from Step 2 populated.

Include at the top:

# Implementation Task Breakdown

**Source Spec:** [Path to the approved spec document]
**Spec Type:** [RFC / PRD / ADR]
**Generated:** [Date]
**Total Tasks:** [Count]
**Dispatch Summary:** [N subagent, N iterative, N collaborative]

## Protection Boundaries

[Full protection list from Step 1 — agents must respect these]

Then list all tasks following the template format, grouped into Critical Path and Parallelizable Work sections.

Each task entry must include the full agent prompt (from Step 3b) in a fenced code block.

3d: Verify the Output

• Read back the generated file
• Confirm every task from Step 2 is present
• Confirm all tasks have acceptance criteria, scope boundaries, and dependency declarations

Step 4: Present for Approval

Present the task breakdown summary (task count, critical path, parallelizable groups, dispatch type distribution) and use AskUserQuestion with exactly three options:

• Approve — task breakdown is ready, proceed to tracker creation (if available) and handoff
• Revise — incorporate feedback on task scope, ordering, or grouping (max 2 revision rounds, then must approve or reject). On revise: update the TASKS file and present again.
• Reject — task decomposition is fundamentally wrong, return to challenge phase

If the user selects Reject, stop and print: "Handoff rejected. Should I return to challenge to revisit the spec?"

If the user selects Approve, proceed to Step 5.

Step 5: Generate Tracker Molecule

Check tracker availability:

dp-engine state >/dev/null 2>&1 && echo ok

If the tracker is NOT available, STOP. Report: "Tracker not available. Run /dp-cto:spec or dp-engine init to initialize."

If the tracker IS available, create the tracker molecule from the task decomposition. This enables scheduling for /dp-cto:run.

All tracker operations MUST use dp-engine subcommands. Never invoke any non-dp-engine tracker CLI.

5a: Create Epic

dp-engine create "[Spec Title] — Implementation" --type epic --description "[One-sentence goal from spec]"

Record the returned epic ID (parse with | jq -r .id).

Set the spec summary as the epic description. Use dp-engine update to write the full description with architecture context, protection boundaries, and testing strategy from the spec. This is the agent's primary context source — write it rich, not thin.

dp-engine update "{epic-id}" --description "[Full spec summary with architecture, protection boundaries, testing strategy]"

5b: Create Child Tasks

For each task from Step 2, create a tracker child task with the full agent prompt as the description (from Step 3b). This is critical — dp-engine show is what the implementer agent reads. Thin descriptions produce thin implementations.

dp-engine create "Task N: [Component Name] [dispatch-tag]" --type task --parent {epic-id} --description "[FULL agent prompt from Step 3b — not a summary]"

Record each returned task ID.

5c: Set Dependency Edges

For each task with dependencies:

dp-engine dep-add {dependent-task-id} {blocking-task-id}

5d: Verify the Molecule

dp-engine list --parent {epic-id}
dp-engine ready

Verify:

• Task count matches the decomposition from Step 2
• Dependency graph resolves correctly (no cycles, no orphans)
• Ready set returns the expected initially unblocked tasks
• Each task description contains the full agent prompt (not a one-liner)

If verification fails, fix the issues before proceeding.

Step 6: Terminal Handoff

Print exactly:

"Spec complete. Task breakdown saved to TASKS-<title>.md. Tracker epic {epic-id} with N tasks created — ready for /dp-cto:run."

Do NOT invoke dp-cto:run. Do NOT offer to start execution. The user decides when.

<CHAIN> Spec pipeline complete. The approved spec has been decomposed into implementation tasks. TASKS-*.md is a human-readable companion to the tracker molecule. Tracker epic created: /dp-cto:run can dispatch tasks via `dp-engine ready`. The user decides the next step. Do NOT auto-invoke /dp-cto:run. </CHAIN>

NEVER

1. NEVER write application code — you are decomposing, not implementing
2. NEVER create tasks without acceptance criteria
3. NEVER create tasks without scope boundaries (files the agent must NOT modify)
4. NEVER create tasks that touch 6+ files — split them
5. NEVER skip dependency edges between related tasks
6. NEVER use placeholder file paths — resolve actual paths from the project
7. NEVER skip the protection boundaries extraction — agents need guardrails
8. NEVER auto-invoke dp-cto:run — handoff only
9. NEVER skip the tracker molecule (Step 5) — it is required for downstream execution via /dp-cto:run.
10. NEVER skip agent prompt generation — every task needs a self-contained prompt
11. NEVER allow more than 2 revision rounds — after 2, only approve or reject
12. NEVER skip the approval gate — user must explicitly approve the task breakdown before tracker creation

Red Flags — STOP

Read references/red-flags.md before proceeding. It contains the stop conditions for this skill.