docs(workflow): add standardized 'Resume Issue Workflow' template

[VirtueMe]

Problem

When a user says "continue on issue X" or "resume work on issue X", Claude Code instances don't have a standardized workflow to follow. This leads to:

• Inconsistent behavior across sessions
• Missing the MCP session coordinator sign-on step
• Not retrieving stored state from previous sessions
• Not checking GitHub issues when no state exists
• Confusion when issue numbers don't exist

Enhanced Solution (Credit: Cipher/DS-02)

Transform from static documentation to self-teaching MCP server integration that guides Claude Code through the Resume Issue workflow automatically.

Key Insight: Instead of writing documentation that Claude might skip, embed the workflow directly into the MCP server's prompts and resources so Claude sees it every time.

Implementation Strategy

Phase 1: MCP Server Integration

File: packages/mcp-server/src/claude_session_coordinator/prompts.py

Create startup and sign-off prompts that teach the workflow:

1. STARTUP_PROMPT - Shown when Claude connects to MCP server:

   • Document trigger phrases ("continue on issue #X", "resume issue #X", etc.)
   • Provide complete workflow steps (sign-on → retrieve state → present → work → sign-off)
   • Include decision tree for all scenarios (state exists vs. no state vs. issue doesn't exist)
   • List best practices and common pitfalls
   • Define standardized state storage keys

2. SIGNOFF_PROMPT - Shown before sign-off:

   • Checklist for state storage before signing off
   • Reminder to document next steps for handoff
   • Ensure proper session release

File: packages/mcp-server/src/claude_session_coordinator/resources.py

Enhance session://context resource with workflow guidance:

• Add workflow object with step-by-step instructions
• Include trigger phrases array
• Provide best practices for state storage
• Show quick start guide
• Give current recommendations (next available session, etc.)

Phase 2: Supporting Documentation

File: .claude/workflow.md

Create human-readable reference explaining:

• Self-teaching concept (MCP server teaches Claude automatically)
• Trigger phrases that activate the workflow
• What happens behind the scenes
• Troubleshooting guide
• How to customize for other projects

File: README.md

Add brief mention of Resume Issue Workflow:

• Link to workflow.md
• Quick example of usage
• Benefits of self-teaching approach

Phase 3: Testing & Validation

Test the complete workflow:

• Start work on an issue and store state
• Sign off and start new session
• Say "continue on issue #X"
• Verify Claude follows workflow automatically
• Test edge cases (non-existent issue, no state, multiple sessions)

Phase 4: Polish

• Add example conversations to startup prompt
• Improve error messages with recovery guidance
• Document in blog post (The Claude Code Chronicles)

Requirements

The implementation must:

1. Be self-teaching - Claude learns the workflow from MCP server prompts, not static docs
2. Be automatic - Workflow triggers on recognized phrases without manual explanation
3. Cover all scenarios:
   • State exists in MCP session coordinator → restore and continue
   • No state exists → check GitHub issue
   • No GitHub issue exists → ask user for clarification
4. Define trigger patterns - Recognize variations of "continue on issue X"
5. Integrate seamlessly - Work with existing sign-on/sign-off procedures
6. Be reusable - Template approach works for other repositories

Acceptance Criteria

Phase 1: MCP Server Integration

• prompts.py created with STARTUP_PROMPT

  • Trigger phrases documented
  • Complete workflow steps outlined
  • Decision tree for all scenarios
  • Best practices and common pitfalls
  • Standardized state storage keys defined

• prompts.py includes SIGNOFF_PROMPT

  • State storage checklist
  • Handoff documentation reminder
  • Sign-off guidance

• resources.py enhanced with workflow guidance in session://context

  • Workflow object with steps
  • Trigger phrases array
  • Best practices object
  • Quick start guide
  • Current recommendations

Phase 2: Supporting Documentation

• .claude/workflow.md created

  • Self-teaching concept explained
  • Trigger phrases documented
  • Behind-the-scenes workflow described
  • Troubleshooting guide included
  • Customization instructions provided

• README.md updated

  • Resume Issue Workflow mentioned
  • Link to workflow.md
  • Quick usage example

Phase 3: Testing

• End-to-end workflow test completed

  • Start work and store state
  • Sign off and start new session
  • "continue on issue #X" triggers workflow
  • State retrieved and presented automatically
  • Continuation works smoothly

• Edge cases tested

  • Non-existent issue number handled
  • No previous state handled
  • Multiple active sessions coordinated
  • Corrupted/missing state data handled

Phase 4: Polish

• Example conversations added to startup prompt
• Error messages improved with recovery guidance
• Blog post drafted (The Claude Code Chronicles)

Success Metrics

After implementation, this workflow should work:

✅ User says: "continue on issue #54"
✅ Claude responds: "Let me check the session coordinator..."
✅ Claude retrieves: Previous state from MCP server
✅ Claude presents: "Found previous work on batch 2. Continue?"
✅ Claude continues: From exactly where previous session stopped

Critical: This should work WITHOUT the user explaining the workflow - the MCP server teaches Claude automatically.

Why This Approach is Better

Original approach (static documentation):

Human writes workflow.md → Hopes Claude reads it → Often doesn't work

Enhanced approach (self-teaching MCP):

MCP server prompts Claude → Claude sees it every time → Always works

The difference:

• Static docs = Claude might skip them
• Dynamic prompts = Claude can't miss them
• Self-teaching = Consistent behavior across all sessions

Context

This issue was discovered when trying to resume work on issue #54. The current workflow documentation doesn't cover resuming work, only starting new work.

Related to the MCP session coordinator (Phase 3) which provides state storage and retrieval capabilities.

Enhanced by Cipher (DS-02) to use a self-teaching approach via MCP server integration rather than static documentation.

Implementation Timeline

Phase 1 (2-3 hours):

• Create prompts.py with startup and sign-off prompts
• Enhance resources.py with workflow guidance
• Create .claude/workflow.md
• Update README

Phase 2 (Testing & Blog):

• End-to-end testing with real scenarios
• Document results
• Write blog post with examples

Related Issues

• Phase 3: MCP server implementation (completed)
• Issue Fix markdown linting errors across entire monorepo #54: Context for discovery of this need
• Future: Workflow compliance analytics and validation

[VirtueMe]

Phase 1 Complete! ✅

All Phase 1 acceptance criteria have been completed and merged in PR #60.

Completed:

MCP Server Integration:

• ✅ prompts.py created with STARTUP_PROMPT

  • ✅ Trigger phrases documented
  • ✅ Complete workflow steps outlined
  • ✅ Decision tree for all scenarios
  • ✅ Best practices and common pitfalls
  • ✅ Standardized state storage keys defined

• ✅ prompts.py includes SIGNOFF_PROMPT

  • ✅ State storage checklist
  • ✅ Handoff documentation reminder
  • ✅ Sign-off guidance

• ✅ server.py enhanced (not resources.py as originally planned) with workflow guidance in session://context

  • ✅ Workflow object with steps
  • ✅ Trigger phrases array
  • ✅ Best practices object
  • ✅ Quick start guide
  • ✅ Current recommendations

Supporting Documentation:

• ✅ .claude/workflow-resume-issue.md created (gitignored human reference)

  • ✅ Self-teaching concept explained
  • ✅ Trigger phrases documented
  • ✅ Behind-the-scenes workflow described
  • ✅ Troubleshooting guide included
  • ✅ Customization instructions provided

• ✅ README.md updated

  • ✅ Resume Issue Workflow mentioned
  • ✅ Link to workflow-resume-issue.md
  • ✅ Quick usage example

Implementation Note:

Enhanced server.py directly instead of creating separate resources.py file, as the session://context resource already existed in the server. The prompts were also integrated directly into server.py functions (startup() and sign_off_prompt()), with prompts.py created as a module for future extensibility.

Next Steps (Phase 2):

• End-to-end workflow testing with real scenario
• Edge case testing
• Blog post ("The Claude Code Chronicles")

Ready for testing! 🎯