solo-handoff-protocol

Guides a five-stage file-based handoff protocol between Cowork and Claude Code agents.

Updated Apr 23, 2026
One-click install
npx skills add https://github.com/cjrain-12505614/solo-forge-marketplace --skill solo-handoff-protocol-cjrain-12505614
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: solo-handoff-protocol
Source: https://github.com/cjrain-12505614/solo-forge-marketplace/tree/main/solo-forge-v0.6.0/skills/solo-handoff-protocol
Command: npx skills add https://github.com/cjrain-12505614/solo-forge-marketplace --skill solo-handoff-protocol-cjrain-12505614

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Coordinating work between two AI agents (Cowork on Claude Desktop and Claude Code CLI) on a solo developer project is error-prone without a shared protocol. This Skill enforces a structured five-stage file-based handoff workflow (directive, plan, review, report, decision) so tasks are issued, executed, verified, and closed without miscommunication or state corruption. ## Core Features & Use Cases - Five-Stage Handoff Protocol: Manages the lifecycle of handoff folders (HO-, PLG-, DOC-) through 01_directive, 02_plan, 03_review, 04_report, and 05_decision files with a defined state machine (DRAFT through CLOSED-MERGE/CLOSED-REJECT). - Role Separation Enforcement: Defines clear responsibilities where Cowork handles strategy, review, and INDEX.md updates while Claude Code handles planning, execution, and reporting, with unidirectional write rules per file. - Guardrails and Decision Trees: Provides a decision tree for four read-only commands (list, pickup, execute, report), an APPROVED gate check before execution, and operational rules covering NFD path handling, Kaggle CLI usage, and commit approval. - Use Case: A solo developer running Kaggle experiments asks Claude Code to pick up an issued handoff; the Skill directs it to read INDEX.md, create 02_plan.md from the template, wait for Cowork approval, execute, and write 04_report.md before closure. ## Quick Start Ask the assistant to list pending handoffs and pick up the next issued one from the handoff folder following the solo handoff protocol.

Frequently Asked Questions about solo-handoff-protocol

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I coordinate tasks between Claude Desktop and Claude Code?▼

Use a file-based handoff protocol with five sequential markdown files: directive, plan, review, report, and decision. Cowork writes directives and reviews while Claude Code writes plans and reports, with all state tracked in a shared INDEX.md file.

How does the handoff state machine work?▼

Handoffs progress through states from DRAFT and ISSUED to PLANNING, IN_REVIEW, APPROVED, EXECUTING, REPORTING, and finally CLOSED-MERGE or CLOSED-REJECT. Only Cowork may update the INDEX.md status column; Claude Code has read-only access.

Can Claude Code start work before a plan is approved?▼

No. The protocol requires an APPROVED gate: Claude Code must verify that 03_review.md contains an APPROVE decision before entering EXECUTING state. Starting work on a REVISE or unwritten review violates the operating rules.

Why do Korean folder paths fail on iCloud Drive?▼

iCloud Drive stores Korean filenames in NFD (decomposed) Unicode form, so hardcoded NFC paths fail to match. Use os.listdir() combined with unicodedata.normalize('NFC', s) to locate folders safely.

What are the limitations of the handoff commands?▼

The four commands (list, pickup, execute, report) are strictly read-only regarding shared files. They never modify INDEX.md, templates, directives, or reviews; they only create the agent's own 02_plan.md or 04_report.md files.