{"id":"anombyte93-handoff","name":"handoff","summary":"prd-taskmasterパイプラインのフェーズ3:スマートモード選択とユーザーハンドオフ。","body":"# Phase 3: Handoff\n\nDeclarative phase skill. Invoked by the prd-taskmaster orchestrator when\n`current_phase` is `HANDOFF`. Never called directly by a user.\n\nThe one rule: **detect what the user has, recommend ONE mode, give the user a\nstructured choice, dispatch the chosen mode. Mode D executes only on tier=premium; otherwise it is a locked teaser.**\n\n## Entry gate\n\n1. Call `mcp__plugin_prd_go__check_gate(phase=\"HANDOFF\", evidence={})` for diagnostics.\n\n   `check_gate` is an EXIT gate: it requires `user_mode_choice` and `plan_file_exists` —\n   both produced by HANDOFF itself, i.e. evidence to *advance*, not to *enter*. On first\n   entry neither exists yet, so a `gate_passed: false` here is EXPECTED — the state\n   machine's legal transitions already guarantee only legal entry.\n\n   - **First entry** (no evidence yet): note the result and continue with the Procedure.\n   - **Re-entry**: if the gate reports violations, report them and stop — it protects\n     against re-running a completed phase or skipping ahead from GENERATE.\n2. Read the GENERATE outputs — `.taskmaster/docs/prd.md`, `.taskmaster/tasks/tasks.json`,\n   `.taskmaster/reports/task-complexity-report.json`. If any are missing,\n   report and stop. The gate should have caught this, but belt-and-braces.\n\n## Handoff checklist\n\nCopy into your response before running the procedure:\n\n```\nHANDOFF CHECKLIST:\n- [ ] Capabilities detected (tier + per-capability flags)\n- [ ] Recommended mode: ___ (reason: ___)\n- [ ] Summary displayed (spec location, task count, capabilities)\n- [ ] CLAUDE.md task workflow appended (idempotent)\n- [ ] AskUserQuestion mode picker surfaced (or prose fallback if hook-blocked)\n- [ ] User choice dispatched (Mode A / B / C, or D when tier=premium)\n- [ ] Debrief scaffold emitted (optional, silently tolerated)\n- [ ] Handoff complete\n```\n\n## Step 1: Detect capabilities\n\n**MCP (preferred)**: `mcp__plugin_prd_go__detect_capabilities()`\n\n**CLI fallback**: `python3 script.py detect-capabilities`\n\nReturns a `tier` field (`\"free\"` or `\"premium\"`) plus per-capability flags.\nKey signals:\n\n| Capability | What It Enables |\n|------------|----------------|\n| superpowers plugin | Modes A, C (brainstorm, plans, subagents) |\n| task-master-ai (CLI or MCP) | Mode B (native auto-execute loop) |\n| ralph-loop plugin | Mode C (iterative execution loop) |\n| atlas-launcher MCP (licensed) | Mode D — Atlas Fleet (tier=premium) |\n| atlas-loop / atlas-cdd skills | legacy Mode-D seeds — superseded by atlas-launcher detection |\n| Research model (task-master or MCP) | Deep research per task |\n| Playwright MCP | Tier S browser verification |\n\n**Mode D (Atlas Fleet) unlocks on `tier: \"premium\"` only** — i.e. a licensed\n`atlas-launcher` MCP registration detected by `detect_atlas_launcher()`. Local\n`atlas-loop`/`atlas-cdd` skills do NOT unlock it. See Step 2 and the Mode D\nsection below.\n\n## Step 2: Recommend ONE mode\n\nDecision logic (first match wins):\n\n- `superpowers` + `ralph-loop` present → **Mode C** (recommended free)\n- `superpowers` only → **Mode A** (plan-only, manual drive)\n- `task-master-ai` only → **Mode B** (native auto-execute)\n- Fallback → **Mode A**\n\nExternal-tool modes (E–J: Cursor, RooCode, Codex, Gemini, CodeRabbit, Aider)\nare offered as alternatives via the `alternative_modes` field, not primary\nrecommendations. **Mode D is recommended iff `tier == \"premium\"` AND the task\ngraph parallelizes (>= 2 independent dependency chains — check `fleet-waves`\noutput: any wave with >= 2 chunks). Premium + serial graph: recommend the best\nfree mode and say why (\"your tasks form a single dependency chain — Verified\nLoop is the right tool here\"); Fleet stays selectable but not default. Free\ntier: Mode D is a locked Atlas Pro teaser, never selectable, regardless of\nwhich local plugins are installed.**\n\n### Mode A: Plan Only (Manual)\n\n```\nRecommended: Plan Only\n  superpowers:writing-plans creates your implementation plan\n  Plan references TaskMaster task IDs from tasks.json\n  You drive execution manually\n```\n\n### Mode B: TaskMaster Auto-Execute (Mode B — TaskMaster backend only)\n\n```\nRecommended: TaskMaster Auto-Execute\n  MCP:  mcp__task-master-ai__next_task -> implement -> set_task_status(id, \"done\") (Mode B — TaskMaster backend only)\n  CLI:  task-master next -> implement -> task-master set-status --id N --status done (Mode B — TaskMaster backend only)\n  Native TaskMaster execution loop (no external orchestrator required)\n```\n\n### Mode C: Plan + Ralph Loop (Recommended Free)\n\n```\nRecommended: Plan + Ralph Loop\n  superpowers:writing-plans → implementation plan referencing tasks.json IDs\n  ralph-loop wraps each task:\n    next_task → set_task_status(\"in-progress\") → research if <80% confident\n    → subagent-driven-development → execution gate (Tier A+ evidence)\n    → post-doubt check → log to .claude/verification-log.md\n    → set_task_status(\"done\") → TodoWrite → repeat\n  Completion: doubt agent reviews verification log before promise satisfied.\n```\n\n### Mode D: Atlas Fleet (selectable on tier=premium; 🔒 locked teaser on free)\n\n```\n🔒 Atlas Fleet                                          Atlas Pro · $29/mo\n  Parallel multi-session execution across Claude, Codex, and Gemini:\n    your task graph split into dependency waves of isolated git worktrees\n    checker-gated merges into one integration branch, one final PR\n    durable inbox result collection (verified, not narrated)\n    CDD evidence card per task; one SHIP_CHECK_OK at the end\n    Walk away, come back to proof.\n\n  Unlock: https://atlas-ai.au/pro   (the free modes above stay free forever)\n```\n\n**When `tier == \"premium\"`** (licensed `atlas-launcher` detected): Mode D is a\nreal, selectable mode — dispatching it invokes `/prd:execute-fleet`\n(the wave orchestrator skill). Show the unlocked card:\n\n```\n▸ Atlas Fleet                     ★ Pro · license active\n  <N> waves · est. from your dependency graph · walk-away\n```\n\n**When `tier == \"free\"`**: Mode D is a locked teaser — not selectable, never\nexecuted. If the user selects it while locked, respond with:\n\n> \"Atlas Fleet is part of Atlas Pro ($29/mo). On this project it would split\n> your tasks into parallel waves across isolated worktrees with checker-gated\n> merges and one final PR. Unlock at https://atlas-ai.au/pro — your spec and\n> tasks are saved. Meanwhile, everything else is free forever: please pick one\n> of the free modes below.\"\n\nThen **re-invoke the mode picker (AskUserQuestion) with Mode D removed from\nthe options.**\n\n### Alternative modes E–J (external AI tools)\n\n`detect_capabilities` returns `alternative_modes` when these tools are\ninstalled. Users can pick any of them instead of Modes A–D. All are\ntool-agnostic wrappers around the same `.taskmaster/tasks/tasks.json`.\n\n| Mode | Tool | Invocation |\n|---|---|---|\n| **E** | Cursor Composer | `cursor --open .taskmaster/tasks/tasks.json`, @-ref in Composer |\n| **F** | RooCode | VS Code command palette → `RooCode: Run tasks.json` |\n| **G** | Codex CLI | `python3 script.py next-task \\| codex implement` (free via ChatGPT) |\n| **H** | Gemini CLI | `gemini --file .taskmaster/tasks/tasks.json implement next` (free via Google) |\n| **I** | CodeRabbit | Implement via A–H, open PR, CodeRabbit reviews per task. Combines with other modes. |\n| **J** | Aider | `aider --read .taskmaster/tasks/tasks.json` — pair-programming style |\n\n## Step 3: Append task workflow to CLAUDE.md\n\nUse the deterministic subcommand — do **not** do raw Read+Edit. This path is\nidempotent, takes a timestamped backup when modifying an existing file, and\nuses HTML-comment sentinels so re-runs are no-ops.\n\n1. The workflow content is the same every run — write it to a tempfile:\n\n   ```markdown\n   ## Task Execution Workflow (prd-taskmaster)\n\n   When implementing tasks, prefer backend operations:\n   1. `python3 script.py next-task` — get next ready task\n   2. `python3 script.py set-status --id <id> --status in-progress` — note hyphen; underscore is rejected\n   3. Implement the task (follow the plan step linked to this task)\n   4. `python3 script.py set-status --id <id> --status done` — mark complete\n   5. Update TodoWrite with progress\n   6. Repeat from step 1\n\n   Valid statuses: `pending`, `in-progress`, `done`, `review`, `blocked`, `deferred`, `cancelled`.\n\n   ### Progress Tracking\n   - Update TodoWrite BEFORE and AFTER each task\n   - Cannot proceed to next task without updating TodoWrite\n   - TodoWrite = user visibility. TaskMaster = source of truth.\n   ```\n\n2. Run the append command. No Plan Mode preview — the subcommand itself is\n   idempotent (HTML-comment sentinels gate the write), so the information is\n   surfaced to the user via the Step-4 summary and the AskUserQuestion\n   options (Step 5) *before* dispatch, not via a plan dialog:\n\n   ```bash\n   python3 $SKILL_DIR/script.py append-workflow \\\n     --target ./CLAUDE.md \\\n     --content-file /tmp/pdtm-workflow-section.md\n   ```\n\n   The JSON response reports one of:\n   - `action: \"created\"` — no prior CLAUDE.md, fresh file with markers\n   - `action: \"skipped\"` (reason: `markers_present`) — already wired, no-op\n   - `action: \"appended\"` — existing CLAUDE.md untouched except for the\n     appended marker block; `backup_path` points at\n     `CLAUDE.md.prd-taskmaster-backup-<ts>`\n\n   If the user wants a preview before the write, surface the planned content\n   inside the AskUserQuestion options or as an informational paragraph in the\n   Step 4 summary — describe what would be written without invoking any\n   plan-dialog tool.\n\n## Step 4: Display summary\n\nRender the handoff panel and print it: MCP `render_status(phase=\"HANDOFF\")` →\nprint `rendered`; CLI `python3 script.py status --phase HANDOFF`. (Fallback —\nemit a compact block before the mode picker so the user has full context:)\n\n```\nSpec Generated: .taskmaster/docs/prd.md\nValidation: <GRADE> (<score>/<max>)\nTasks: <count> tasks parsed with dependencies (see .taskmaster/tasks/tasks.json)\nComplexity: analyzed via TaskMaster (.taskmaster/reports/task-complexity-report.json)\nResearch: <expanded|skipped>\n\nCapabilities:\n  [check] TaskMaster (MCP|CLI)\n  [check|circle] Playwright (browser verification)\n  [check|circle] Research provider\n  [check|circle] Ralph-loop plugin\n  [check|circle] Atlas Fleet (premium: selectable · free: locked)\n```\n\n## Step 5: Mandatory AskUserQuestion for mode selection\n\nHANDOFF is the moment of user agency. Prose recommendations are skippable;\ntool calls are not. You **MUST** invoke `AskUserQuestion` in this step. This\nis hard-enforced — prose-only fallback is a bug, not a shortcut.\n\nAskUserQuestion gives the user an explicit, structured, machine-readable\nchoice. That's the durable handoff record. The user's selection is logged\nprogrammatically and downstream steps dispatch on it directly — no parsing\nnatural-language affirmatives, no ambiguity.\n\n### Sequence\n\n1. **Emit a handoff summary** covering:\n   - PRD path + validation grade\n   - Task count + complexity breakdown\n   - Recommended mode (A/B/C) + one-line reason\n   - Alternative modes available (E–J when detected, collapsed under \"Use\n     another tool…\")\n   - Mode D 🔒 Atlas Fleet teaser with the Atlas Pro price and /pro URL\n   - A \"next step\" description scoped to the recommended mode (e.g. for Mode\n     B: \"run `task-master next`\" with the first ready task ID (Mode B — TaskMaster backend only))\n\n2. **Call `AskUserQuestion`** with a multi-option question listing each\n   available execution mode. Use the user-facing names (internal IDs in\n   parentheses are for this skill only — never shown to the user):\n   - **Plan & Drive** (Mode A) — get the plan, implement it yourself\n   - **Auto-Execute** (Mode B) — TaskMaster's native loop, lighter verification\n   - **Verified Loop** (Mode C) — evidence-gated single-session loop\n     (recommended when superpowers + a loop runner are present)\n   - **🔒 Atlas Fleet** (Mode D) — Atlas Pro $29/mo, parallel multi-session\n   - \"Use another tool…\" — expands the applicable alternatives from E–J\n   - \"Show me more detail before I decide\" — loops back to Step 4 summary\n\n   Mark the recommended mode as the default (Atlas Fleet may be the default\n   only when tier=premium AND the graph parallelizes). Selecting Atlas Fleet\n   while locked (free tier) returns the upgrade response (see the Mode D block\n   in Step 2) and re-prompts with only the free modes (plus any applicable\n   alternatives).\n\n3. **Dispatch the chosen mode:**\n   - **Mode A handoff**: invoke `superpowers:writing-plans` with spec path\n     `.taskmaster/docs/prd.md`\n   - **Mode B handoff (Mode B — TaskMaster backend only)**: show the `task-master next` command + the first\n     ready task ID surfaced from `.taskmaster/tasks/tasks.json`\n   - **Mode C handoff**: write `.claude/atlas-loop-prompt.md` describing the\n     task-execution contract, then invoke `/goal` with the condition:\n\n       `\"SHIP_CHECK_OK has been emitted by .atlas-ai/ship-check.py AND all tasks in .taskmaster/tasks/tasks.json show status=done AND /sync has been invoked this session\"`\n\n     The `/goal` session continues until the Haiku evaluator verifies the\n     condition. Each iteration runs the execute-task 13-step cycle and\n     checks the condition after step 13. `/sync` MUST be the last action\n     before SHIP_CHECK_OK is emitted (per execute-task Termination).\n     (Migrated from `/ralph-loop:ralph-loop` 2026-06-04 — Claude Code's\n     built-in `/goal` evaluator structurally solves the controller-wears-\n     different-hats triple-verify rot caught in the 2026-06-03 audit.)\n   - **Mode D handoff (tier=premium)**: invoke `/prd:execute-fleet` — it owns the wave loop, worker dispatch, verification, merges, and SHIP_CHECK_OK termination. (free tier: upgrade response only, re-prompt)\n\n### Hook-blocked fallback (graceful degradation)\n\nIf `PreToolUse:AskUserQuestion` is hook-blocked (automated / orchestrator /\nfleet session), fall back to a prose option table preserving the same\nsemantics — labels, descriptions, Mode D locked Atlas Pro teaser, recommended\nmode marked. **Surface the hook block as an `[AI]` insight block** so the\nparent orchestrator can detect the fallback:\n\n> `[AI] Hook blocked AskUserQuestion — a PreToolUse hook disables interactive\n> questions for this session (automated mode). Surfacing the mode picker in\n> prose instead. A parent orchestrator should either lift the hook for skills\n> with requires_user_agency:true or supply the mode selection as part of the\n> spawn directive.`\n\nThe prose fallback MUST NOT invoke any plan-mode dialog. AskUserQuestion is\nthe sole user-agency mechanism in this skill — when it is unavailable, the\nprose table is the documented fallback.\n\n### Hard-coded programmatic path (for tests and fleet orchestrators)\n\nThe skill's deterministic layer exposes\n`python3 script.py handoff-gate --recommended <A|B|C>` (when implemented).\nThis emits the full mode option set as structured JSON on stdout, enabling\ntests and external orchestrators to drive the handoff without the LLM layer.\nUse this when you need deterministic, LLM-skippable handoff enforcement.\n\n### Anti-pattern: prose-only prompt\n\n**DO NOT** say \"Ready to proceed with Mode X? (or type 'options')\" as your\nonly gate. That is a prose prompt the model can skip or satisfy with a fake\naffirmative. The v4 dogfood (LEARNING #16 → #20) surfaced this exact pattern\nas a user-agency hole. `AskUserQuestion` is the fix.\n\n## Step 6: Auto-scaffold dogfood debrief\n\nEvery successful HANDOFF calls the deterministic debrief scaffolder as its\nfinal act, so the run does not leave only artifacts (PRD, tasks.json,\ncomplexity report) with no record of what actually happened:\n\n```bash\nSLUG=\"$(basename \"$PWD\")\"\npython3 \"$SKILL_DIR/script.py\" debrief \\\n  --slug \"$SLUG\" \\\n  --grade \"$VALIDATION_GRADE\" \\\n  --output-dir docs/v4-release 2>/dev/null || true\n```\n\n- Uses the project's directory name as slug (stable, matches human convention).\n- Embeds the validation grade captured in Step 4's summary (`EXCELLENT 56/57`, etc.).\n- Defaults to `.taskmaster/{tasks/tasks.json, reports/task-complexity-report.json, docs/prd.md}`\n  — no path flags needed in the common case.\n- Silently tolerates failure (`|| true`) — a missing complexity report or\n  gitignored `docs/v4-release/` must never block a handoff that otherwise\n  succeeded.\n- Output path is returned as `output_path` in the JSON response; surface it\n  to the user as \"Debrief scaffolded at: <path>. Judgment sections (worked /\n  broke / meta) left as TODO — fill them in before the memory fades.\"\n\nIf `docs/v4-release/` doesn't exist in the target project (most projects\nwon't — this is a prd-taskmaster convention), skip the call or let it fail\nsilently. The scaffold is only useful for projects that retain it.\n\n## Evidence Gate\n\n**Gate: capabilities detected AND a mode recommended AND CLAUDE.md workflow\nappended AND AskUserQuestion surfaced (or prose fallback with `[AI]` insight\nif hook-blocked) AND the user's choice dispatched.**\n\nEmit a compact one-block status:\n\n```\nHandoff:\n  capabilities tier: <free|premium>\n  recommended mode: <A|B|C>\n  CLAUDE.md: <created|appended|skipped>\n  picker: <AskUserQuestion|prose-fallback>\n  user choice: <A|B|C|D-teased>\n  dispatched: <skill/command invoked, or \"waitlist re-prompt\">\n  debrief: <path or \"skipped\">\n```\n\n## Exit gate\n\nAfter the evidence gate passes:\n\n1. Call `mcp__plugin_prd_go__advance_phase(expected_current=\"HANDOFF\", target=\"EXECUTE\", evidence={\"user_mode_choice\": \"<A|B|C>\", \"plan_file_exists\": True, \"capabilities_tier\": \"<free|premium>\"})`.\n   The call atomically transitions `pipeline.json` from HANDOFF to EXECUTE.\n   The `expected_current` field is the compare-and-swap guard;\n   `evidence` is stored under `phase_evidence[EXECUTE]` for audit.\n2. Return control to the orchestrator (`prd-taskmaster` skill). Do NOT invoke\n   EXECUTE directly — the orchestrator re-reads `current_phase` and routes.\n\n## Red flags (stop and report, do not paper over)\n\n- \"The user typed 'yeah sure' so I'll treat that as Mode C approval\" → NO.\n  Use `AskUserQuestion`. A structured choice is the durable record; prose\n  affirmatives are skippable.\n- \"AskUserQuestion is hook-blocked so I'll just pick Mode C myself\" → NO.\n  Fall back to the prose option table + `[AI]` insight block. The user still\n  picks; you just surface the choice in a different shape.\n- \"Mode D (Atlas Fleet) is available locally because atlas-loop is installed,\n  so I'll execute it\" → NO. Mode D is always a teaser. Detection returns\n  `atlas_auto: false` until the feature ships.\n- \"The CLAUDE.md append had markers already, so I'll skip Step 3 entirely\"\n  → NO. `action: \"skipped\"` is the expected idempotent outcome; emit it and\n  proceed. Skipping the call means you don't know the state.\n- \"I can call advance_phase without the evidence gate passing\" → NO. Gate\n  first, always.\n- \"The debrief scaffolder failed so I'll abort the whole handoff\" → NO. The\n  scaffolder is silently tolerant (`|| true`) — a missing `docs/v4-release/`\n  is not a handoff failure.\n\n## Non-exits\n\nThis skill does not use explicit process termination. A hard block reports\nthe reason and returns control to the orchestrator; the orchestrator decides\nwhether to surface to the user.","author":"@anombyte93","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/anombyte93/prd-taskmaster/tree/main/skills/handoff","license":"MIT","category":"writing","lang":"en","tokens":4776,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":["plugin_prd_go","task-master-ai"],"tools":["Read","Skill","AskUserQuestion","ToolSearch","mcp__atlas-engine","mcp__plugin_prd_go","mcp__plugin_prd-taskmaster_go","mcp__plugin_atlas-go_go"]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["atlas-ai.au"]}}