Add plan key support for concurrent work streams

[brian-lai]

Summary

This PR introduces plan keys to the PARA workflow, enabling multiple concurrent work streams in the same repository without collision.

Changes

1. Command Updates (commands/plan.md)

• Added plan key as a required parameter: /plan [plan-key] [task-description]
• Plan keys must not contain spaces (use - or _)
• Supported formats: PLAN-123, add_user_auth, fix-memory-leak
• Updated all examples to demonstrate plan key usage

2. File Naming Convention

• Old format: YYYY-MM-DD-descriptive-name.extension
• New format: YYYY-MM-DD-{plan-key}-descriptive-name.extension
• Examples:
  • 2025-11-11-AUTH-123-refactor.md
  • 2025-11-11-add_user_auth-api-payload.json

3. Context Structure (resources/CLAUDE.md)

• Changed active_context from array to object grouped by plan key:

Before:

{
  "active_context": [
    "context/plans/2025-11-08-payroll-api-mcp.md",
    "context/data/2025-11-08-payload-example.json"
  ]
}

After:

{
  "active_context": {
    "PLAN-123": [
      "context/plans/2025-11-08-PLAN-123-payroll-api-mcp.md",
      "context/data/2025-11-08-PLAN-123-payload-example.json"
    ],
    "add_user_authentication": [
      "context/plans/2025-11-08-add_user_authentication-jwt-auth.md"
    ]
  }
}

4. Human-Readable Summaries

• Added plan key sections to context/context.md:

# Current Work Summary

## PLAN-123
Enhancing payroll API with token-efficient MCP integration.

## add_user_authentication
Adding JWT-based authentication to all API endpoints.

5. Template Updates

• Added **Plan Key:** {PLAN_KEY} to plan template metadata

Benefits

✅ Support multiple concurrent work streams - Work on different features/fixes simultaneously
✅ No collision between work - Each plan key groups its own files
✅ Clear organization - Easy to find all files related to specific work
✅ Better context management - Human-readable summaries per plan
✅ Scalable workflow - Handles complex projects with parallel work

Example Usage

# Start two concurrent work streams
/plan FEAT-456 add-logging-middleware
/plan AUTH-123 implement-user-authentication

# Files created:
# - context/plans/2025-01-07-FEAT-456-add-logging-middleware.md
# - context/plans/2025-01-07-AUTH-123-implement-user-authentication.md

# Both can be worked on independently without collision

Test Plan

• Verify plan key validation (rejects spaces)
• Test creating plans with different plan key formats
• Confirm file naming includes plan key
• Validate context.md structure with multiple plan keys
• Test archiving behavior with multiple active plans

🤖 Generated with Claude Code