name: workflow-protocols
description: Orchestration protocols for /workflow pipeline. Load at /workflow startup (step 0.1), then load individual protocols on-demand per event triggers. Covers: handoff contracts (4 phase-to-phase contracts + narrative casting), checkpoint format (session recovery), re-routing (complexity mismatch), pipeline metrics (completion tracking).
disable-model-invocation: true
Workflow Protocols
Protocol Overview
| Protocol | When to Load | Purpose |
|---|
| Handoff | BEFORE forming handoff between phases | 4 pipeline contracts + 1 tool contract (code-researcher) + narrative casting |
| Checkpoint | AFTER completing each phase | Format (12 YAML fields), recovery (5 steps), state persistence |
| State Layer | On-demand (debugging state issues, Phase 5 cleanup) | File contracts, lifecycle rules, cleanup protocol for .claude/workflow-state/ |
| Re-routing | On complexity mismatch signal | Downgrade/upgrade route + tracking + learning |
| Pipeline Metrics | At completion phase only | Format (12 fields), storage (JSONL file), analysis, anomaly detection |
| Agent Memory | Agent startup + completion | Shared memory behavior for all memory: project agents |
| Parallel Dispatch | 2+ independent tasks identified (L/XL) | Multi-agent dispatch patterns (research + future debugging) |
Instructions
Step 1: Load at /workflow startup (step 0.1)
Read this SKILL.md for the protocol overview. Then load Core Deps files:
Autonomy, Orchestration Core.
Step 2: Use event-driven protocol loading
Do NOT load all protocols upfront. Load on-demand per the Event Triggers section below.
Step 3: Always form a handoff payload
CRITICAL: Every phase MUST produce a structured handoff payload (context + artifact + metadata) for the next phase.
Handoff load rule (the single source of truth — Event Triggers and Protocol References point here):
- Forming a handoff OUTSIDE Phase-2/4 delegation (e.g. designer→planner) → read Handoff Contracts (5 pipeline contracts, 5 KB, core contracts only).
- On the Phase-2/4 delegation path the contract shapes are already inlined in Delegation Templates — do NOT also load handoff-contracts.md or handoff-protocol.md there.
- Read Handoff Protocol ONLY when authoring a net-new IMP-02/03/04 envelope (verdict envelopes, ID normalization, diff-based replan).
Example
Handoff payload — complete vs missing
Good — full handoff payload (planner → plan-review):
artifact: ".claude/prompts/add-user-endpoint.md"
metadata:
task_type: "new_feature"
complexity: "L"
sequential_thinking_used: true
key_decisions:
- "Repository pattern over direct SQL — testability"
known_risks:
- "N+1 queries in list endpoint"
Bad — skipping handoff, jumping to code:
Why: Skipping phases leads to unvalidated code without architectural review. Every phase MUST produce a handoff payload for the next phase (see Handoff Protocol).
For more examples, see Examples & Troubleshooting.
Common Issues
Stuck in Phase 1 → Phase 2 loop
Cause: Requirements unclear or task too broad.
Fix: Ask user to clarify scope, break task into smaller pieces.
Session interrupted mid-workflow
Cause: Connection lost, timeout, or manual stop.
Fix: Check .claude/prompts/{feature}.md for saved plan, use --from-phase to resume.
Phase 2 keeps returning NEEDS_CHANGES
Cause: Plan missing critical sections (Scope, Architecture Decision, Tests).
Fix: Check plan against templates/plan-template.md, ensure all sections filled.
For all troubleshooting cases, see Examples & Troubleshooting.
Event Triggers
Core Deps (workflow-only, loaded at startup)
These files define fundamental workflow behavior and are loaded at pipeline startup (step 0.1):
- Autonomy — 3 modes (INTERACTIVE/AUTONOMOUS/RESUME), stop/continue conditions
- Orchestration Core — pipeline phases, loop rules (max 3), session recovery tables. Heavy recovery paths (IMP-06 UNKNOWN verdict, counter heuristics, loop-limit summary) are extracted to on-demand files (see Protocol References).
Protocol References
For detailed protocol specifications, read the supporting files in this skill directory:
- Handoff Contracts — 5 core contracts, lightweight (5 KB); use for common-path handoff formation
- Handoff Protocol — full protocol: 5 contracts + IMP-02/03/04 implementation details (22 KB)
- Diff Manifest — diff-based re-plan algorithm (STEP 0.5) + planner re-invocation template; load on iter 2+ only
- Delegation Templates — full delegation prompts + pre/post_delegation for plan-review and code-review (IMP-01/03/04); load ONLY before Phase 2 or Phase 4 delegation
- Incomplete Output Recovery — output_validation checks + step_0..step_5 INCOMPLETE verdict fallback chain; load ONLY on INCOMPLETE verdict
- Checkpoint Protocol — format, recovery, example
- State Layer — file contracts, lifecycle categories, cleanup protocol for .claude/workflow-state/
- Re-routing — 3 triggers + tracking fields + learning
- Pipeline Metrics — format, storage, analysis, anomaly detection
- Examples & Troubleshooting — execution examples, common mistakes, troubleshooting
- Agent Memory Protocol — shared memory behavior for all
memory: project agents
- Parallel Dispatch — decision flowchart, research multi-dispatch, failure isolation, conflict detection
- Unknown Verdict Recovery — IMP-06 UNKNOWN verdict resolution rules + IMP-02 filter predicates + anti-patterns + cost comparison; load ONLY on INCOMPLETE verdict
- Counter Recovery — counter_recovery heuristic (missing checkpoint) + iteration_summary_on_stop format (3/3 limit hit); load ONLY when the trigger fires
