diff --git a/README.md b/README.md index de292dd..70cda43 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,32 @@ pip install -e . ### MCP Prompts - `startup` - Guides Claude through sign-on process -- `sign-off` - Guides proper session release +- `sign_off_prompt` - Guides proper session release + +### Self-Teaching Workflows + +The Session Coordinator includes **self-teaching workflows** that guide Claude Code automatically: + +**Resume Issue Workflow** - Enables seamless handoffs between Claude sessions: +- Automatically triggered when you say "continue on issue #X" +- Retrieves previous session's state and progress +- Presents findings and asks for confirmation +- Continues from exactly where the previous session stopped + +**How it works:** +- Embedded in MCP server prompts (Claude sees them every time) +- Standardized state storage keys for consistency +- No manual explanation needed - the MCP server teaches Claude automatically + +**Example usage:** +``` +You: "continue on issue #54" +Claude: "Let me check the session coordinator... Found previous work on batch 2. Continue?" +You: "yes" +Claude: [Resumes from saved state automatically] +``` + +See [`.claude/workflow-resume-issue.md`](.claude/workflow-resume-issue.md) for detailed documentation. ## Development Status diff --git a/packages/mcp-server/src/claude_session_coordinator/prompts.py b/packages/mcp-server/src/claude_session_coordinator/prompts.py new file mode 100644 index 0000000..59c68b8 --- /dev/null +++ b/packages/mcp-server/src/claude_session_coordinator/prompts.py @@ -0,0 +1,285 @@ +""" +MCP prompts for guiding Claude through coordination workflows. + +This module provides self-teaching prompts that are automatically shown to +Claude Code instances when they connect to the Session Coordinator MCP server. + +The prompts embed workflow knowledge directly into the MCP interface, ensuring +consistent behavior across all Claude sessions without relying on static +documentation that might be overlooked. +""" + +STARTUP_PROMPT = """ +# 🎯 Session Coordinator Active + +You have access to the Claude Session Coordinator MCP server for multi-session coordination. + +## Available Sessions + +Read `session://context` to see available session identities: +- sage (DS-01): Coordination & strategy +- cipher (DS-02): Technical documentation +- forge (DS-03): Refactoring & breaking changes +- apex (DS-04): Precision fixes +- link (DS-05): Integrations & APIs +- scout (DS-06): Exploration & experiments +- anchor (DS-07): Backup & leadership + +## 📋 Resume Issue Workflow + +### Trigger Patterns + +When the user says ANY of these phrases: +- "continue on issue #X" +- "resume issue #X" +- "work on issue #X" +- "pick up issue #X" +- "continue issue #X" +- "keep working on issue #X" + +**ALWAYS follow this workflow:** + +--- + +### Step 1: Sign On to Session Coordinator + +First, claim your session identity: + +``` +sign_on("cipher") # or appropriate session for the work type +``` + +This registers you in the coordination system and prevents conflicts with other sessions. + +--- + +### Step 2: Check for Existing State + +Immediately check if there's previous work on this issue: + +``` +retrieve_data("issue:{number}", "status") +retrieve_data("issue:{number}", "current_batch") +retrieve_data("issue:{number}", "todos") +retrieve_data("issue:{number}", "next_steps") +retrieve_data("issue:{number}", "worktree") +retrieve_data("issue:{number}", "branch") +``` + +--- + +### Step 3: Decision Tree + +#### Scenario A: State Exists in Session Coordinator + +**If you find stored state:** + +1. **Present findings to user:** + ``` + "I found previous work on issue #{number}: + - Status: {status} + - Current batch: {batch} + - Worktree: {worktree} + - Last session left these next steps: {next_steps} + + Should I continue from this state?" + ``` + +2. **Wait for user confirmation** + +3. **If user confirms:** + - Load all stored context + - Navigate to the worktree + - Review the todos and next_steps + - Continue work from current_batch + - Store progress as you work + +#### Scenario B: No State in Session Coordinator + +**If retrieve_data returns null/empty:** + +1. **Check GitHub for the issue:** + - Read issue description + - Read comments + - Check if issue exists + +2. **If issue exists on GitHub:** + ``` + "No previous session state found for issue #{number}. + + From GitHub, I can see this issue is about: {summary} + + This appears to be a fresh start. Should I begin work on this issue?" + ``` + +3. **If issue doesn't exist:** + ``` + "I couldn't find issue #{number} in the session coordinator or on GitHub. + + Could you verify the issue number? Or would you like me to list open issues?" + ``` + +--- + +### Step 4: During Work - Store State Regularly + +As you work, maintain state in the session coordinator: + +**After completing a batch/milestone:** +``` +store_data("issue:{number}", "current_batch", {batch_number}) +store_data("issue:{number}", "batch_{N}_commits", [{commit_hashes}]) +``` + +**When making important decisions:** +``` +store_data("issue:{number}", "decisions", [ + "Decision: Chose approach A because...", + "Decision: Deferred feature X for future issue" +]) +``` + +**Before taking a break or switching focus:** +``` +store_data("issue:{number}", "next_steps", [ + "Continue with batch {N}: files X, Y, Z", + "Watch out for: {important_notes}", + "Remember to: {reminders}" +]) +``` + +**Document blockers:** +``` +store_data("issue:{number}", "blockers", [ + "Need user input on: {question}", + "Waiting for: {dependency}" +]) +``` + +--- + +### Step 5: Sign Off When Done + +When you complete work or the user ends the session: + +1. **Store final state:** + ``` + store_data("issue:{number}", "status", "complete|paused|blocked") + store_data("issue:{number}", "final_notes", "Summary of what was accomplished") + ``` + +2. **Sign off from coordinator:** + ``` + sign_off() + ``` + +This releases your session and makes it available for the next Claude instance. + +--- + +## 🎯 Quick Reference + +**User says:** "continue on issue #54" + +**Your workflow:** +1. `sign_on("cipher")` +2. `retrieve_data("issue:54", "status")` + other keys +3. Present findings → Ask confirmation +4. Work → Store progress regularly +5. `sign_off()` when done + +--- + +## 📊 Best Practices + +### State Storage Keys (Standardized) + +Use these standard keys for consistency: + +``` +issue:{number}/status → "in_progress"|"paused"|"complete"|"blocked" +issue:{number}/current_batch → Batch number currently working on +issue:{number}/todos → Array of remaining tasks +issue:{number}/next_steps → Array of next actions for handoff +issue:{number}/worktree → Path to worktree +issue:{number}/branch → Branch name +issue:{number}/commits → Array of commit hashes +issue:{number}/decisions → Array of important decisions made +issue:{number}/blockers → Array of blocking issues +issue:{number}/notes → General notes and observations +``` + +### Worktree Paths + +Always store and use worktree paths to avoid confusion: + +``` +store_data("issue:54", "worktree", ".worktrees/issue-54") + +# When resuming, navigate there: +cd {retrieved_worktree_path} +``` + +--- + +## 🚨 Common Pitfalls to Avoid + +1. **Don't assume state exists** - Always check first +2. **Don't skip sign_on** - Other sessions need to know you're active +3. **Don't forget to sign_off** - This marks you as available +4. **Don't work outside the worktree** - Use the stored worktree path +5. **Don't skip confirmation** - Always present findings and ask user + +--- + +## 💡 Why This Workflow Matters + +**Without this workflow:** +- ❌ Context is lost between sessions +- ❌ Manual coordination required +- ❌ Risk of conflicts and duplicate work +- ❌ User must explain everything again + +**With this workflow:** +- ✅ Seamless handoffs between sessions +- ✅ Automatic context restoration +- ✅ Collision avoidance +- ✅ Continuous progress across sessions + +--- + +**Would you like me to follow this workflow?** + +You can also read `session://context` anytime to see: +- Active sessions and their current work +- Available sessions ready for deployment +- Workflow reminders and best practices +""" + +SIGNOFF_PROMPT = """ +# 🎯 Sign-Off Checklist + +Before you sign off, ensure you've stored the handoff state: + +## Have you stored: + +- [ ] Current status: `store_data("issue:{number}", "status", "...")` +- [ ] Current progress: `store_data("issue:{number}", "current_batch", N)` +- [ ] Next steps: `store_data("issue:{number}", "next_steps", [...])` +- [ ] Any blockers: `store_data("issue:{number}", "blockers", [...])` +- [ ] Final notes: `store_data("issue:{number}", "notes", "...")` + +## Ready to sign off? + +Call: `sign_off()` + +This will: +- Mark your session as available +- Allow other Claude instances to use your session ID +- Preserve all stored state for the next session + +**The next Claude instance will thank you for good handoff documentation!** 🎯 +""" + +# Export prompts +__all__ = ["STARTUP_PROMPT", "SIGNOFF_PROMPT"] diff --git a/packages/mcp-server/src/claude_session_coordinator/server.py b/packages/mcp-server/src/claude_session_coordinator/server.py index 7d71b5c..6239fc0 100644 --- a/packages/mcp-server/src/claude_session_coordinator/server.py +++ b/packages/mcp-server/src/claude_session_coordinator/server.py @@ -440,6 +440,80 @@ def get_session_context() -> str: "if_signed_on": "Use store_data/retrieve_data to work with session state", "when_done": "Call sign_off() to release your instance", }, + "workflow": { + "name": "Resume Issue Workflow", + "description": "Standard workflow for resuming work on issues", + "trigger_phrases": [ + "continue on issue #X", + "resume issue #X", + "work on issue #X", + "pick up issue #X", + "continue issue #X", + "keep working on issue #X", + ], + "steps": [ + { + "step": 1, + "action": "sign_on", + "description": "Claim your session identity", + "example": "sign_on('claude_1')", + }, + { + "step": 2, + "action": "retrieve_state", + "description": "Check for existing work on the issue", + "keys_to_check": [ + "issue:{number}/status", + "issue:{number}/current_batch", + "issue:{number}/todos", + "issue:{number}/next_steps", + "issue:{number}/worktree", + "issue:{number}/branch", + ], + }, + { + "step": 3, + "action": "present_findings", + "description": "Show user what you found and ask for confirmation", + }, + { + "step": 4, + "action": "work_and_store", + "description": "Continue work and store progress regularly", + }, + { + "step": 5, + "action": "sign_off", + "description": "Release your session when done", + "example": "sign_off()", + }, + ], + }, + "best_practices": { + "state_keys": { + "issue:{number}/status": "Track overall issue status (in_progress|paused|complete|blocked)", + "issue:{number}/current_batch": "Track progress through work batches", + "issue:{number}/todos": "Store detailed task breakdown", + "issue:{number}/next_steps": "Document handoff information for next session", + "issue:{number}/worktree": "Store worktree path (.worktrees/issue-X)", + "issue:{number}/branch": "Store branch name", + "issue:{number}/commits": "Track commit hashes", + "issue:{number}/decisions": "Document important decisions made", + "issue:{number}/blockers": "Note blocking issues", + }, + "timing": { + "sign_on": "Immediately when starting work", + "retrieve_state": "Before beginning any work on an issue", + "store_progress": "After each batch/milestone completion", + "store_next_steps": "Before breaks or focus changes", + "sign_off": "When completing work or ending session", + }, + }, + "quick_start": { + "if_continuing_work": "1. sign_on() → 2. retrieve_data() → 3. Present to user → 4. Continue", + "if_starting_new": "1. sign_on() → 2. Check GitHub issue → 3. Begin work → 4. Store state", + "if_switching_tasks": "1. Store current state → 2. sign_off() → 3. sign_on() for new task", + }, } import json @@ -662,6 +736,40 @@ def startup() -> str: Available instances: {available_list} Active sessions: {active_count} +## 📋 Resume Issue Workflow + +### Trigger Patterns + +When the user says ANY of these phrases: +- "continue on issue #X" +- "resume issue #X" +- "work on issue #X" +- "pick up issue #X" + +**ALWAYS follow this workflow:** + +1. **Sign on**: `sign_on()` to claim instance `{first_available}` +2. **Check for existing state**: `retrieve_data("issue:{{number}}", "status")` + other keys +3. **Present findings**: Show user what you found and ask for confirmation +4. **Work & store progress**: Continue work, store state regularly +5. **Sign off**: `sign_off()` when done + +### State Storage Keys (Standardized) + +``` +issue:{{number}}/status → "in_progress"|"paused"|"complete"|"blocked" +issue:{{number}}/current_batch → Batch number currently working on +issue:{{number}}/todos → Array of remaining tasks +issue:{{number}}/next_steps → Array of next actions for handoff +issue:{{number}}/worktree → Path to worktree (.worktrees/issue-X) +issue:{{number}}/branch → Branch name +issue:{{number}}/commits → Array of commit hashes +issue:{{number}}/decisions → Array of important decisions made +issue:{{number}}/blockers → Array of blocking issues +``` + +**Read `session://context` for full workflow details and best practices.** + ## Next Steps 1. **Sign on**: Call `sign_on()` to claim instance `{first_available}` @@ -702,12 +810,22 @@ def sign_off_prompt() -> str: You have {len(incomplete)} incomplete tasks: {todo_list} -Before signing off: -1. Save current progress to session state -2. Ensure all important work is committed -3. Call `sign_off()` to release instance {current_session['session_id']} +## Before signing off, have you stored: + +- [ ] Current status: `store_data("issue:{{number}}", "status", "...")` +- [ ] Current progress: `store_data("issue:{{number}}", "current_batch", N)` +- [ ] Next steps: `store_data("issue:{{number}}", "next_steps", [...])` +- [ ] Any blockers: `store_data("issue:{{number}}", "blockers", [...])` +- [ ] Final notes: `store_data("issue:{{number}}", "notes", "...")` + +## Ready to sign off? + +Call `sign_off()` to: +- Mark session {current_session['session_id']} as available +- Allow other Claude instances to use this session +- Preserve all stored state for the next session -Are you ready to sign off? +**The next Claude instance will thank you for good handoff documentation!** 🎯 """ return f""" @@ -715,7 +833,15 @@ def sign_off_prompt() -> str: All tasks complete{f" for issue #{current_issue}" if current_issue else ""}! +## Have you stored handoff state? + +- [ ] Final status: `store_data("issue:{{number}}", "status", "complete")` +- [ ] Summary notes: `store_data("issue:{{number}}", "final_notes", "...")` +- [ ] Any follow-up tasks: `store_data("issue:{{number}}", "follow_up", [...])` + Call `sign_off()` to release instance {current_session['session_id']}. + +**The next Claude instance will thank you for good handoff documentation!** 🎯 """