feat(skills): phase protocol enforcement for orchestration skills

CLAUDE.md

@@ -167,6 +167,7 @@ Working memory files live in a dedicated `.memory/` directory:
 - Target: ~120-150 lines per SKILL.md with progressive disclosure to `references/`
 - Skills default to read-only (`allowed-tools: Read, Grep, Glob`); exceptions: git/review skills add `Bash`, interactive skills add `AskUserQuestion`, `quality-gates` adds `Write` for state persistence, and `router` omits `allowed-tools` entirely (unrestricted, as the main-session orchestrator)
 - All skills live in `shared/skills/` — add to plugin `plugin.json` `skills` array, then `npm run build`
+- Orchestration skills (`*:orch`) follow the Phase Protocol (defined in `router/SKILL.md`) — each phase needs `**Produces:**`/`**Requires:**` annotations and a `## Phase Completion Checklist`
 
 ### Agents
 

plugins/devflow-audit-claude/commands/audit-claude.md

@@ -19,6 +19,8 @@ Audit CLAUDE.md files against Anthropic's best practices. Finds oversized files,
 
 ### Phase 1: Discovery
 
+**Produces:** CLAUDE_FILES
+
 Find all CLAUDE.md files to audit:
 
 ```bash
@@ -36,6 +38,9 @@ If a specific path argument was provided, use only that file.
 
 ### Phase 2: Analysis
 
+**Produces:** AUDIT_RESULTS
+**Requires:** CLAUDE_FILES
+
 For each discovered file, spawn a `claude-md-auditor` agent:
 
 ```
@@ -53,6 +58,8 @@ Run agents in parallel when multiple files are found.
 
 ### Phase 3: Report
 
+**Requires:** AUDIT_RESULTS
+
 Combine all agent outputs into a single report:
 
 ```markdown

plugins/devflow-code-review/commands/code-review-teams.md

@@ -21,6 +21,8 @@ Run a comprehensive code review of the current branch by spawning a review team
 
 #### Step 0a: Discover Worktrees
 
+**Produces:** WORKTREES
+
 1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
    - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
    - See `~/.claude/skills/devflow:worktree-support/SKILL.md` for the full 7-step algorithm and canonical protected branch list
@@ -31,6 +33,9 @@ Run a comprehensive code review of the current branch by spawning a review team
 
 #### Step 0b: Per-Worktree Pre-Flight (Git Agent)
 
+**Produces:** BRANCH_INFO, PR_INFO
+**Requires:** WORKTREES
+
 For each reviewable worktree, spawn Git agent:
 
 ```
@@ -49,6 +54,9 @@ In multi-worktree mode, spawn all pre-flight agents **in a single message** (par
 
 #### Step 0c: Incremental Detection & Timestamp Setup
 
+**Produces:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP
+**Requires:** BRANCH_INFO
+
 For each worktree:
 
 1. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`).
@@ -64,6 +72,9 @@ For each worktree:
 
 ### Phase 1: Analyze Changed Files
 
+**Produces:** REVIEWER_LIST
+**Requires:** DIFF_RANGE
+
 Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditional reviews:
 
 | Condition | Adds Perspective |
@@ -84,6 +95,8 @@ Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditio
 
 ### Phase 1b: Load Knowledge Index
 
+**Produces:** KNOWLEDGE_CONTEXT
+
 Load the knowledge index for the current worktree before spawning the review team:
 
 ```bash
@@ -94,6 +107,9 @@ This produces a compact index of active ADR/PF entries. Pass `KNOWLEDGE_CONTEXT`
 
 ### Phase 2: Spawn Review Team
 
+**Produces:** REVIEWER_OUTPUTS
+**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, KNOWLEDGE_CONTEXT, REVIEWER_LIST
+
 **Per worktree**, create an agent team for adversarial review. Always include 4 core perspectives; conditionally add more based on Phase 1 analysis.
 
 **Note**: In multi-worktree mode, process worktrees sequentially for Agent Teams (one team per session constraint). Each worktree gets its own team lifecycle: create → debate → synthesize → cleanup.
@@ -166,6 +182,8 @@ Spawn review teammates. For each teammate, compose a self-contained prompt using
 
 ### Phase 2b: Debate Round
 
+**Requires:** REVIEWER_OUTPUTS
+
 After all reviewers complete initial analysis, lead initiates adversarial debate:
 
 Lead initiates debate via broadcast:
@@ -196,6 +214,9 @@ Reviewers message each other directly using SendMessage:
 
 ### Phase 3: Synthesis and PR Comments
 
+**Produces:** REVIEW_SUMMARY
+**Requires:** REVIEWER_OUTPUTS, REVIEW_DIR, PR_INFO
+
 **WAIT** for debate to complete, then lead produces outputs.
 
 Spawn 2 agents **in a single message**:
@@ -240,6 +261,8 @@ Check for existing inline comments at same file:line before creating new ones."
 
 ### Phase 4: Write Review Head Marker
 
+**Requires:** BRANCH_INFO, REVIEW_DIR
+
 Per worktree, after successful completion:
 1. Write current HEAD SHA to `{worktree_path}/.docs/reviews/{branch-slug}/.last-review-head`
 
@@ -248,6 +271,8 @@ Per worktree, after successful completion:
 
 ### Phase 5: Cleanup and Report
 
+**Requires:** REVIEW_SUMMARY
+
 Shut down all review teammates explicitly:
 
 ```

plugins/devflow-code-review/commands/code-review.md

@@ -28,6 +28,8 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 
 #### Step 0a: Discover Worktrees
 
+**Produces:** WORKTREES
+
 1. **Discover reviewable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
    - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
    - See `~/.claude/skills/devflow:worktree-support/SKILL.md` for the full 7-step algorithm and canonical protected branch list
@@ -38,6 +40,9 @@ Run a comprehensive code review of the current branch by spawning parallel revie
 
 #### Step 0b: Per-Worktree Pre-Flight (Git Agent)
 
+**Produces:** BRANCH_INFO, PR_INFO
+**Requires:** WORKTREES
+
 For each reviewable worktree, spawn Git agent:
 
 ```
@@ -56,6 +61,9 @@ In multi-worktree mode, spawn all pre-flight agents **in a single message** (par
 
 #### Step 0c: Incremental Detection & Timestamp Setup
 
+**Produces:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP
+**Requires:** BRANCH_INFO
+
 For each worktree:
 
 1. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`).
@@ -71,6 +79,9 @@ For each worktree:
 
 ### Phase 1: Analyze Changed Files
 
+**Produces:** REVIEWER_LIST
+**Requires:** DIFF_RANGE
+
 Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditional reviews:
 
 | Condition | Adds Review |
@@ -91,6 +102,8 @@ Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditio
 
 ### Phase 1b: Load Knowledge Index
 
+**Produces:** KNOWLEDGE_CONTEXT
+
 While file analysis runs (or just before spawning reviewers), load the knowledge index for the current worktree:
 
 ```bash
@@ -101,6 +114,9 @@ This produces a compact index of active ADR/PF entries. Pass `KNOWLEDGE_CONTEXT`
 
 ### Phase 2: Run Reviews (Parallel)
 
+**Produces:** REVIEWER_OUTPUTS
+**Requires:** DIFF_RANGE, REVIEW_DIR, TIMESTAMP, KNOWLEDGE_CONTEXT, REVIEWER_LIST
+
 Spawn Reviewer agents **in a single message**. Always run 7 core reviews; conditionally add more based on changed file types:
 
 | Focus | Always | Pattern Skill |
@@ -141,6 +157,9 @@ In multi-worktree mode, process worktrees **sequentially** (one worktree at a ti
 
 ### Phase 3: Synthesis (Parallel)
 
+**Produces:** REVIEW_SUMMARY
+**Requires:** REVIEWER_OUTPUTS, REVIEW_DIR, PR_INFO
+
 **WAIT** for Phase 2, then spawn agents per worktree **in a single message**:
 
 **Git Agent (PR Comments)** per worktree:
@@ -169,6 +188,8 @@ Output: {worktree_path}/.docs/reviews/{branch-slug}/{timestamp}/review-summary.m
 
 ### Phase 4: Write Review Head Marker & Report
 
+**Requires:** BRANCH_INFO, REVIEW_DIR
+
 Per worktree, after successful completion:
 1. Write current HEAD SHA to `{worktree_path}/.docs/reviews/{branch-slug}/.last-review-head`
 2. Display results from all agents:

plugins/devflow-debug/commands/debug-teams.md

@@ -25,6 +25,8 @@ Investigate bugs by spawning a team of agents, each pursuing a different hypothe
 
 ### Phase 1: Load Knowledge Index (Orchestrator-Local)
 
+**Produces:** KNOWLEDGE_CONTEXT
+
 Before hypothesizing, load the knowledge index:
 
 ```bash
@@ -35,6 +37,9 @@ The orchestrator uses `KNOWLEDGE_CONTEXT` locally when generating hypotheses (Ph
 
 ### Phase 2: Context Gathering
 
+**Produces:** HYPOTHESES, BUG_CONTEXT
+**Requires:** KNOWLEDGE_CONTEXT
+
 If `$ARGUMENTS` starts with `#`, fetch the GitHub issue:
 
 ```
@@ -51,6 +56,8 @@ Analyze the bug description (from arguments or issue) and identify 3-5 plausible
 
 ### Phase 3: Spawn Investigation Team
 
+**Requires:** HYPOTHESES, BUG_CONTEXT
+
 Create an agent team with one investigator per hypothesis:
 
 ```
@@ -111,6 +118,9 @@ Spawn investigator teammates with self-contained prompts:
 
 ### Phase 4: Investigation
 
+**Produces:** INVESTIGATION_RESULTS
+**Requires:** HYPOTHESES
+
 Teammates investigate in parallel:
 - Read relevant source files
 - Trace execution paths
@@ -120,6 +130,8 @@ Teammates investigate in parallel:
 
 ### Phase 5: Adversarial Debate
 
+**Requires:** INVESTIGATION_RESULTS
+
 Lead initiates debate via broadcast:
 
 ```
@@ -147,6 +159,9 @@ Teammates challenge each other directly using SendMessage:
 
 ### Phase 6: Convergence
 
+**Produces:** CONVERGENCE_RESULTS
+**Requires:** INVESTIGATION_RESULTS
+
 After debate (max 2 rounds), lead collects results:
 
 ```
@@ -159,6 +174,8 @@ Lead broadcast:
 
 ### Phase 7: Cleanup
 
+**Requires:** CONVERGENCE_RESULTS
+
 Shut down all investigator teammates explicitly:
 
 ```
@@ -172,6 +189,8 @@ Verify TeamDelete succeeded. If failed, retry once after 5s. If retry fails, HAL
 
 ### Phase 8: Report
 
+**Requires:** CONVERGENCE_RESULTS
+
 Lead produces final report:
 
 ```markdown

plugins/devflow-debug/commands/debug.md

@@ -33,6 +33,8 @@ Investigate bugs by spawning parallel agents, each pursuing a different hypothes
 
 ### Phase 1: Load Knowledge Index (Orchestrator-Local)
 
+**Produces:** KNOWLEDGE_CONTEXT
+
 Before hypothesizing, load the knowledge index:
 
 ```bash
@@ -43,6 +45,9 @@ The orchestrator uses `KNOWLEDGE_CONTEXT` locally when generating hypotheses (Ph
 
 ### Phase 2: Context Gathering
 
+**Produces:** HYPOTHESES, BUG_CONTEXT
+**Requires:** KNOWLEDGE_CONTEXT
+
 If `$ARGUMENTS` starts with `#`, fetch the GitHub issue:
 
 ```
@@ -59,6 +64,9 @@ Analyze the bug description (from arguments or issue) and identify 3-5 plausible
 
 ### Phase 3: Investigate (Parallel)
 
+**Produces:** INVESTIGATION_RESULTS
+**Requires:** HYPOTHESES
+
 Spawn one Explore agent per hypothesis in a **single message** (parallel execution):
 
 ```
@@ -102,6 +110,9 @@ Focus area: {specific code area, mechanism, or condition}
 
 ### Phase 4: Synthesize
 
+**Produces:** ROOT_CAUSE_SYNTHESIS
+**Requires:** INVESTIGATION_RESULTS
+
 Once all investigators return, spawn a Synthesizer agent to aggregate findings:
 
 ```
@@ -120,6 +131,8 @@ Instructions:
 
 ### Phase 5: Report
 
+**Requires:** ROOT_CAUSE_SYNTHESIS
+
 Produce the final report:
 
 ```markdown