/coding Workflow Orchestrator

This skill orchestrates a structured TDD development workflow across 9 phases (Phase 0–8). Phase 8 (PR Review Comments) is optional and user-initiated.

Orchestration Principle

The main agent is strictly an orchestrator — it delegates all substantive work to sub-agents and only manages phase transitions and state.

MUST DO

• Use Task tool to launch sub-agents for all exploration, planning, test design, implementation, and review work
• Use Skill tool to invoke other skills (e.g., run-quality-checks)
• Use Read only for workspace files: STATE.json, PLAN.md, QC_SUMMARY.md, QC_<CATEGORY>.raw, QC_<CATEGORY>.exitcode, QC_AUTOFIX.md, TASK_LIST.txt
• Use Write only for STATE.json
• Use Bash only for git operations and workspace directory management
• Use TaskCreate/TaskUpdate/TaskList to track Implementation Units and fix items (NOT for phase tracking)

MUST NOT

• Read, search, or explore source code files directly — delegate to sub-agents
• Write or edit source code files directly — delegate to sub-agents
• Analyze code structure, dependencies, or architecture directly — delegate to sub-agents
• Generate implementation code, test code, or review content — delegate to sub-agents
• Run git push or any remote push command — push is a user-initiated action only
• Run gh pr create or create pull requests in any form — PR creation is a user-initiated action only

Workflow Progress Checklist

Copy this checklist and track progress:

Workflow Progress:
- [ ] Phase 0: Pre-checks
- [ ] Phase 1: Exploration
- [ ] Phase 2: Planning (includes Test Plan)
- [ ] Phase 3: Approval Gate
- [ ] Phase 4: TDD Implementation
- [ ] Phase 5: Quality Checks
- [ ] Phase 6: User Review
- [ ] Phase 7: Final Report
- [ ] Phase 8: PR Review Comments (optional)

Resume Detection

Before starting Phase 0, check for an existing workspace:

1. Run ls -d .ai-workspace/*_$(git branch --show-current | tr '/' '_') 2>/dev/null
2. If workspace found, read its STATE.json.
3. If currentPhase exists in STATE.json:
   • Read currentPhaseId if present (e.g., "quality-checks").
   • Use AskUserQuestion:
     • 前回の続きから再開する — Resume from Phase N (<currentPhaseId>)
     • 最初からやり直す — Start fresh from Phase 0
   • Resume: set <work-dir> to existing workspace.
     • If currentPhaseId is present: find the matching entry in the Phases list below by its ID. If its file number differs from currentPhase (skill was renumbered), use the ID to identify the correct file. Then skip to that phase.
     • If currentPhaseId is absent (legacy STATE.json): fall back to currentPhase number.
   • Fresh: proceed to Phase 0 normally.
4. If no workspace or no currentPhase → proceed to Phase 0.

Phases

Read each phase document only when you are ready to execute that phase. Do not read ahead.

1. Pre-checks — Clarify task, create branch, verify tools, initialize workspace
2. Exploration (exploration) — Load past learnings, check profile, explore codebase
3. Planning (planning) — Create work plan and test plan based on exploration results
4. Approval Gate (approval-gate) — Present plan (including test plan) to user for approval
5. Implementation (implementation) — Implement code following TDD methodology
6. Quality Checks (quality-checks) — Run tests, lint, formatting (max 3 retries)
7. User Review (user-review) — Present changes to user for approval
8. Final Report (final-report) — Summarize results and present to user
9. PR Review Comments (pr-review) — Address PR review comments (optional, user-initiated)

Loop Control

• Phase 2 plan review cycle: task-planner (sonnet) drafts, test-plan-reviewer/general-plan-reviewer (opus, launched in parallel) review autonomously, task-planner revises — max 3 rounds. On exceed, outstanding concerns are appended to PLAN.md's Unresolved Questions instead of looping further; the user decides in Phase 3.
• Phase 5 retry limit: 3 (report to user on exceed)
• Phase 6 user review: If user requests fixes → fix → return to Phase 5
• Phase 6→5 return: Reset Phase 5 retry counter, does NOT increase any cycle counter; set currentPhaseId to "quality-checks"
• Phase 8 PR review: If fixes needed → fix → return to Phase 5 (no push until quality checks pass)
• Phase 8→5 return: Reset Phase 5 retry counter, does NOT increase any cycle counter; set currentPhaseId to "quality-checks"
• State file: <work-dir>/STATE.json (initialize in Phase 0)

CRITICAL: Phase File Re-read on Loop Return

When returning to Phase 5 from Phase 6 or 8, you MUST re-read the phase documents before executing them. This is because earlier phase instructions may have drifted out of your active attention due to intervening conversation.

Rule: Before executing Phase 5, re-read phases/5-quality-checks.md. Before executing Phase 6, re-read phases/6-user-review.md.

This applies every time you enter these phases, not just the first time. Treat each phase entry as if you are reading the instructions for the first time.

Tasks Usage

Use Claude Code's TaskCreate/TaskUpdate/TaskList tools for work-item-level progress tracking, NOT phase-level tracking (that is STATE.json's role).

Principles

• Do NOT use Tasks for phase tracking — STATE.json handles phase transitions
• Create Tasks after Phase 3 approval — from Implementation Units in PLAN.md
• Create Tasks for fix items — in Phase 6 (User Feedback) and Phase 8 (PR Review)
• Only the orchestrator manages Tasks — sub-agents must NOT call TaskCreate/TaskUpdate/TaskList

Naming Convention

Type	Subject Format	Example
Implementation Unit	Implement Unit N: <name>	Implement Unit 1: UserService CRUD
User Feedback Fix	Fix UF-<round>-<M>: <title>	Fix UF-1-1: Error message in Japanese
PR Review Fix	Fix PR-<round>-<M>: <title>	Fix PR-1-1: Missing validation