From 36e1475285b100370a19748518c6d240d2f03470 Mon Sep 17 00:00:00 2001 From: Brian Lai Date: Wed, 7 Jan 2026 16:15:44 -0500 Subject: [PATCH] feat: Add plan key support for concurrent work streams MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add plan key parameter to /plan command to uniquely identify work - Update file naming convention to include plan key prefix (YYYY-MM-DD-{plan-key}-description) - Change active_context structure from array to object grouped by plan key - Add human-readable summaries organized by plan key in context.md - Support multiple concurrent work streams without collision - Update plan template to include plan key metadata - Update all examples and documentation to reflect plan key usage This allows multiple pieces of work to coexist in the same repository by grouping related files under unique plan keys (e.g., PLAN-123, add_user_auth, fix-memory-leak). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- commands/plan.md | 140 +++++++++++++++++++++++++------------ resources/CLAUDE.md | 118 ++++++++++++++++++++++--------- templates/plan-template.md | 1 + 3 files changed, 181 insertions(+), 78 deletions(-) diff --git a/commands/plan.md b/commands/plan.md index 03654c4..80c9cc1 100644 --- a/commands/plan.md +++ b/commands/plan.md @@ -18,18 +18,33 @@ This command helps you create a structured plan before executing work: ## Usage ``` -/plan [task-description] +/plan [plan-key] [task-description] ``` +### Plan Key Format + +The **plan key** is a unique identifier for grouping related work. It: +- Must NOT contain spaces (use hyphens `-` or underscores `_`) +- Should be concise and descriptive +- Can use formats like: + - `PLAN-123` (ticket-style) + - `add_user_auth` (snake_case) + - `fix-memory-leak` (kebab-case) + +The plan key is used to: +- Group related files in `active_context` +- Support concurrent work streams in the same repository +- Organize work summaries by plan + ### Examples ``` -/plan add-user-authentication -/plan fix-memory-leak -/plan refactor-api-layer +/plan PLAN-123 add-user-authentication +/plan fix_memory_leak investigate and fix memory leak in websocket handler +/plan api-refactor refactor-api-layer ``` -If no task description is provided, Claude will ask for it. +If no plan key or task description is provided, Claude will ask for them. ## When to Use Phased Plans @@ -151,58 +166,74 @@ When `/plan` is invoked, Claude should: ### Simple Plan Creation -1. Get current date in `YYYY-MM-DD` format -2. Sanitize task description for filename (lowercase, hyphens) -3. Create plan file: `context/plans/YYYY-MM-DD-{task-name}.md` -4. Populate with template from `templates/plan-template.md` -5. Update `context/context.md`: - - Add plan to `active_context` array +1. Prompt for **plan key** if not provided (validate no spaces) +2. Get current date in `YYYY-MM-DD` format +3. Sanitize task description for filename (lowercase, hyphens) +4. Create plan file: `context/plans/YYYY-MM-DD-{plan-key}-{task-name}.md` +5. Populate with template from `templates/plan-template.md` + - Include plan key in metadata section +6. Update `context/context.md`: + - Add plan to `active_context` object under the plan key + - Add human-readable summary under the plan key section - Update `last_updated` timestamp -6. Display plan location and request review +7. Display plan location and request review ### Phased Plan Creation -1. Get current date in `YYYY-MM-DD` format -2. Sanitize task description for filename (lowercase, hyphens) -3. Create master plan: `context/plans/YYYY-MM-DD-{task-name}.md` +1. Prompt for **plan key** if not provided (validate no spaces) +2. Get current date in `YYYY-MM-DD` format +3. Sanitize task description for filename (lowercase, hyphens) +4. Create master plan: `context/plans/YYYY-MM-DD-{plan-key}-{task-name}.md` - Populate with template from `templates/phased-plan-master-template.md` -4. Create sub-plans for each phase: - - `context/plans/YYYY-MM-DD-{task-name}-phase-1.md` - - `context/plans/YYYY-MM-DD-{task-name}-phase-2.md` + - Include plan key in metadata section +5. Create sub-plans for each phase: + - `context/plans/YYYY-MM-DD-{plan-key}-{task-name}-phase-1.md` + - `context/plans/YYYY-MM-DD-{plan-key}-{task-name}-phase-2.md` - etc. - Populate with template from `templates/phased-plan-sub-template.md` -5. Update `context/context.md`: - - Add master plan to `active_context` array - - Add all sub-plans to `active_context` array - - Add `phased_execution` metadata: + - Include plan key in metadata section +6. Update `context/context.md`: + - Add master plan to `active_context` object under the plan key + - Add all sub-plans to `active_context` object under the plan key + - Add human-readable summary under the plan key section + - Add `phased_execution` metadata under the plan key: ```json { + "active_context": { + "PLAN-123": [ + "context/plans/YYYY-MM-DD-PLAN-123-{task-name}.md", + "context/plans/YYYY-MM-DD-PLAN-123-{task-name}-phase-1.md", + "context/plans/YYYY-MM-DD-PLAN-123-{task-name}-phase-2.md" + ] + }, "phased_execution": { - "master_plan": "context/plans/YYYY-MM-DD-{task-name}.md", - "phases": [ - { - "phase": 1, - "plan": "context/plans/YYYY-MM-DD-{task-name}-phase-1.md", - "status": "pending" - }, - { - "phase": 2, - "plan": "context/plans/YYYY-MM-DD-{task-name}-phase-2.md", - "status": "pending" - } - ], - "current_phase": null + "PLAN-123": { + "master_plan": "context/plans/YYYY-MM-DD-PLAN-123-{task-name}.md", + "phases": [ + { + "phase": 1, + "plan": "context/plans/YYYY-MM-DD-PLAN-123-{task-name}-phase-1.md", + "status": "pending" + }, + { + "phase": 2, + "plan": "context/plans/YYYY-MM-DD-PLAN-123-{task-name}-phase-2.md", + "status": "pending" + } + ], + "current_phase": null + } } } ``` -6. Display all plan locations and request review +7. Display all plan locations and request review ## Examples ### Example: Simple Plan ``` -User: /plan add-logging-middleware +User: /plan FEAT-456 add-logging-middleware Claude analyzes: - Will touch 2-3 files @@ -210,13 +241,22 @@ Claude analyzes: - No dependencies - Straightforward implementation -Creates: context/plans/2025-12-18-add-logging-middleware.md +Creates: context/plans/2025-12-18-FEAT-456-add-logging-middleware.md + +Updates context/context.md with: +{ + "active_context": { + "FEAT-456": [ + "context/plans/2025-12-18-FEAT-456-add-logging-middleware.md" + ] + } +} ``` ### Example: Phased Plan ``` -User: /plan implement-user-authentication +User: /plan AUTH-123 implement-user-authentication Claude analyzes: - Will touch 10+ files across multiple layers @@ -230,10 +270,22 @@ with 3 phases for easier review and incremental merging?" User: Yes Creates: -- context/plans/2025-12-18-implement-user-authentication.md (master) -- context/plans/2025-12-18-implement-user-authentication-phase-1.md (DB migration) -- context/plans/2025-12-18-implement-user-authentication-phase-2.md (API layer) -- context/plans/2025-12-18-implement-user-authentication-phase-3.md (Frontend) +- context/plans/2025-12-18-AUTH-123-implement-user-authentication.md (master) +- context/plans/2025-12-18-AUTH-123-implement-user-authentication-phase-1.md (DB migration) +- context/plans/2025-12-18-AUTH-123-implement-user-authentication-phase-2.md (API layer) +- context/plans/2025-12-18-AUTH-123-implement-user-authentication-phase-3.md (Frontend) + +Updates context/context.md with: +{ + "active_context": { + "AUTH-123": [ + "context/plans/2025-12-18-AUTH-123-implement-user-authentication.md", + "context/plans/2025-12-18-AUTH-123-implement-user-authentication-phase-1.md", + "context/plans/2025-12-18-AUTH-123-implement-user-authentication-phase-2.md", + "context/plans/2025-12-18-AUTH-123-implement-user-authentication-phase-3.md" + ] + } +} ``` ## Phasing Strategy Examples diff --git a/resources/CLAUDE.md b/resources/CLAUDE.md index 6a88466..92e3139 100644 --- a/resources/CLAUDE.md +++ b/resources/CLAUDE.md @@ -94,22 +94,29 @@ project-root/ ## 📅 File Naming Convention -**All context files must use date prefixes for chronological ordering:** +**All context files must use date and plan key prefixes for chronological ordering and grouping:** -- **Format:** `YYYY-MM-DD-descriptive-name.extension` +- **Format:** `YYYY-MM-DD-{plan-key}-descriptive-name.extension` - **Examples:** - - Plans: `2025-11-11-auth-refactor.md` - - Data: `2025-11-11-api-payload.json` - - Summaries: `2025-11-11-auth-refactor-summary.md` + - Plans: `2025-11-11-AUTH-123-refactor.md` + - Data: `2025-11-11-AUTH-123-api-payload.json` + - Summaries: `2025-11-11-AUTH-123-refactor-summary.md` - Archives: `2025-11-11-context.md` -**Why date prefixes?** +**Plan Key Format:** +- Must NOT contain spaces (use `-` or `_`) +- Should be concise and descriptive +- Examples: `PLAN-123`, `add_user_auth`, `fix-memory-leak` + +**Why date + plan key prefixes?** - Files naturally sort chronologically in directories -- Easy to find recent work +- Easy to find recent work for a specific plan +- Clear grouping of related artifacts by plan key +- Support for concurrent work streams - Clear audit trail of when work was performed - No need to check file metadata for timestamps -**Exception:** Files in `context/servers/` do NOT require date prefixes, as they are persistent MCP tool implementations, not session-specific artifacts. +**Exception:** Files in `context/servers/` do NOT require date or plan key prefixes, as they are persistent MCP tool implementations, not session-specific artifacts. --- @@ -129,36 +136,64 @@ project-root/ This file tracks active work. It contains: -1. **Human-readable summary** of current focus. -2. **JSON block** tracking active plans, data files, and tool wrappers. +1. **Human-readable summaries** organized by plan key. +2. **JSON block** tracking active plans, data files, and tool wrappers grouped by plan key. + +### Plan Keys -Example: +Each piece of work must have a **plan key** - a unique identifier that: +- Must NOT contain spaces (use hyphens `-` or underscores `_`) +- Groups related files and context together +- Supports concurrent work streams in the same repository +- Examples: `PLAN-123`, `add_user_auth`, `fix-memory-leak` + +### Example with Multiple Concurrent Work Streams: ````markdown # Current Work Summary + +## PLAN-123 Enhancing payroll API with token-efficient MCP integration. +## add_user_authentication +Adding JWT-based authentication to all API endpoints. + --- ```json { - "active_context": [ - "context/plans/2025-11-08-payroll-api-mcp.md", - "context/data/2025-11-08-payload-example.json", - "context/servers/github/fetchRepo.ts" - ], + "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", + "context/servers/github/fetchRepo.ts" + ], + "add_user_authentication": [ + "context/plans/2025-11-08-add_user_authentication-jwt-auth.md", + "context/data/2025-11-08-add_user_authentication-jwt-config.json" + ] + }, "completed_summaries": [ - "context/summaries/2025-11-08-payroll-mcp-summary.md" + "context/summaries/2025-11-08-PLAN-123-payroll-mcp-summary.md" ], "last_updated": "2025-11-08T15:20:00Z" } +``` ```` -```` +### Workflow: -After completion: +**Starting new work:** +1. Create plan with unique plan key: `/plan PLAN-123 task-description` +2. Files created use format: `YYYY-MM-DD-{plan-key}-{description}.md` +3. Context grouped under plan key in `active_context` + +**After completing a plan key:** ```bash +# Archive only the completed plan key's context +# Keep other active plan keys in context/context.md +# Only archive when ALL plan keys are complete mv context/context.md context/archives/$(date +%F)-context.md -```` +``` --- @@ -256,15 +291,16 @@ Claude: OAuth is an authorization framework while JWT is a token format... ```bash mkdir -p context/{data,plans,summaries,archives,servers} ``` -* Claude drafts a plan in `context/plans/` with filename format: `YYYY-MM-DD-task-name.md` -* Include objective, scope, risks, data sources, and MCP tool usage. +* **Prompt for plan key:** If not provided, ask user for a unique plan key (no spaces allowed) +* Claude drafts a plan in `context/plans/` with filename format: `YYYY-MM-DD-{plan-key}-task-name.md` +* Include plan key in plan metadata, along with objective, scope, risks, data sources, and MCP tool usage. * Reference the **Plan Authoring Guide (Confluence)** for templates. #### 2. Review Claude pauses and requests human validation: -> "Please review `context/plans/YYYY-MM-DD-task-name.md`. Does it align with your intent and the MCP tools specified?" +> "Please review `context/plans/YYYY-MM-DD-{plan-key}-task-name.md`. Does it align with your intent and the MCP tools specified?" #### 3. Execute @@ -331,19 +367,24 @@ git commit -m "Apply middleware to API routes" #### 4. Summarize -* Claude writes a report to `context/summaries/` with filename format: `YYYY-MM-DD-task-name-summary.md` +* Claude writes a report to `context/summaries/` with filename format: `YYYY-MM-DD-{plan-key}-task-name-summary.md` * The summary should describe: * What changed * Why * Which MCP wrappers or data sources were used * Key learnings +* Add the summary to `completed_summaries` array in `context/context.md` +* Remove the completed plan key from `active_context` in `context/context.md` #### 5. Archive -* Move `context/context.md` → `context/archives/YYYY-MM-DD-context.md` -* Start a new `context/context.md` seeded with ongoing data if needed. -* Use the current date in YYYY-MM-DD format for the archived filename. +* **Only archive when ALL plan keys are complete** +* If other plan keys are still active, keep `context/context.md` with remaining active work +* When all work is complete: + * Move `context/context.md` → `context/archives/YYYY-MM-DD-context.md` + * Start a new `context/context.md` for new work + * Use the current date in YYYY-MM-DD format for the archived filename --- @@ -419,26 +460,35 @@ mkdir -p context/{data,plans,summaries,archives,servers} ````markdown # Current Work Summary + +## SETUP-001 Bootstrapping MCP-aware project. --- ```json { - "active_context": [ - "context/plans/2025-11-11-hello-mcp.md" - ], + "active_context": { + "SETUP-001": [ + "context/plans/2025-11-11-SETUP-001-hello-mcp.md" + ] + }, "completed_summaries": [], "last_updated": "YYYY-MM-DDTHH:MM:SSZ" } +``` ```` ```` ### 3) Create your first plan (referencing MCP) -`context/plans/2025-11-11-hello-mcp.md` +`context/plans/2025-11-11-SETUP-001-hello-mcp.md` ```markdown # Plan: Hello MCP Tooling +**Plan Key:** SETUP-001 +**Date:** 2025-11-11 +**Status:** In Review + ## Objective Test an MCP wrapper that lists repo files and returns a short summary. @@ -454,7 +504,7 @@ Test an MCP wrapper that lists repo files and returns a short summary. ## Review Checklist - [ ] Wrapper created - [ ] Output <= 1–2k tokens -- [ ] Summary captured in `context/summaries/2025-11-11-hello-mcp-summary.md` +- [ ] Summary captured in `context/summaries/2025-11-11-SETUP-001-hello-mcp-summary.md` ```` ### 4) Add a minimal MCP wrapper @@ -482,9 +532,9 @@ export async function listFiles(prefix: string) { ### 5) Run the workflow -1. **Plan**: Open `2025-11-11-hello-mcp.md`, approve steps. +1. **Plan**: Open `2025-11-11-SETUP-001-hello-mcp.md`, approve steps. 2. **Execute**: Call `listFiles()` from your MCP client / agent runtime. -3. **Summarize**: Save a short write‑up → `context/summaries/2025-11-11-hello-mcp-summary.md`. +3. **Summarize**: Save a short write‑up → `context/summaries/2025-11-11-SETUP-001-hello-mcp-summary.md`. 4. **Archive**: Move `context/context.md` to `context/archives/2025-11-11-context.md` when done. ### 6) Keep it lean diff --git a/templates/plan-template.md b/templates/plan-template.md index b6ba0c4..d5f0dea 100644 --- a/templates/plan-template.md +++ b/templates/plan-template.md @@ -1,5 +1,6 @@ # Plan: {TASK_NAME} +**Plan Key:** {PLAN_KEY} **Date:** {DATE} **Status:** In Review