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