Workflow protocols
Skill hex0xdeadbeef/claude-kit/.claude/skills/workflow-protocols
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).From its SKILL.md
npx -y skills add hex0xdeadbeef/claude-kit --skill workflow-protocolsAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
SKILL.md
7.5 KB, as published. Nobody here has run it
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:
# No plan created, no review requested
# → jump directly to /coder
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
- Phase completed → write checkpoint (see Checkpoint Protocol)
- Forming handoff OUTSIDE Phase-2/4 delegation (e.g. designer→planner) → read Handoff Contracts (5 KB, core contracts only) — full rule + Phase-2/4 caveat in Step 3 above.
- plan-review or coder signals mismatch → re-route (see Re-routing)
- All phases done → collect metrics (see Pipeline Metrics)
- Phase 5 cleanup → read cleanup protocol (see State Layer)
- Multiple independent tasks identified (L/XL planner research, or independent failures) → read Parallel Dispatch
- Problem encountered → see Examples & Troubleshooting
- Entering Phase 2 or Phase 4 delegation → read Delegation Templates (IMP-01/03/04 protocol details)
- INCOMPLETE verdict detected → read Incomplete Output Recovery (output_validation fallback chain + IMP-06 UNKNOWN resolution rules + IMP-02 filter predicates)
- Checkpoint missing (heuristic session recovery) OR loop limit reached (3/3) → read Counter Recovery (counter_recovery heuristic + iteration_summary_on_stop format)
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 + IMP-06 UNKNOWN verdict resolution rules (phase_2_recovery / phase_4_recovery) + IMP-02 filter predicates + anti-patterns; 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: projectagents - Parallel Dispatch — decision flowchart, research multi-dispatch, failure isolation, conflict detection
- Counter Recovery — counter_recovery heuristic (missing checkpoint) + iteration_summary_on_stop format (3/3 limit hit); load ONLY when the trigger fires