From a675d22ff13d7a1d71f453148f93bffee79a1535 Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Wed, 21 Jan 2026 18:03:56 -0800 Subject: [PATCH] Standardize plan and brainstorm filename conventions (#105) - Move plans from `plans/` to `docs/plans/` for consistency with other artifacts - Add date prefix (YYYY-MM-DD) to both plans and brainstorms for chronological sorting - Add self-documenting suffixes: `-plan` and `-brainstorm` to identify artifact type - Update filename derivation to extract title from content, not filename - Clarify deepened plan naming: append `-deepened` after `-plan` suffix New conventions: - Brainstorms: `docs/brainstorms/YYYY-MM-DD--brainstorm.md` - Plans: `docs/plans/YYYY-MM-DD---plan.md` - Deepened: `docs/plans/YYYY-MM-DD---plan-deepened.md` --- .../commands/deepen-plan.md | 6 +- .../commands/workflows/brainstorm.md | 4 +- .../commands/workflows/plan.md | 62 +++++++++++++------ .../skills/brainstorming/SKILL.md | 2 +- 4 files changed, 50 insertions(+), 24 deletions(-) diff --git a/plugins/compound-engineering/commands/deepen-plan.md b/plugins/compound-engineering/commands/deepen-plan.md index 1e74a09..2a2ed4f 100644 --- a/plugins/compound-engineering/commands/deepen-plan.md +++ b/plugins/compound-engineering/commands/deepen-plan.md @@ -24,8 +24,8 @@ The result is a deeply grounded, production-ready plan with concrete implementat #$ARGUMENTS **If the plan path above is empty:** -1. Check for recent plans: `ls -la plans/` -2. Ask the user: "Which plan would you like to deepen? Please provide the path (e.g., `plans/my-feature.md`)." +1. Check for recent plans: `ls -la docs/plans/` +2. Ask the user: "Which plan would you like to deepen? Please provide the path (e.g., `docs/plans/2026-01-15-feat-my-feature-plan.md`)." Do not proceed until you have a valid plan file path. @@ -460,7 +460,7 @@ At the top of the plan, add a summary section: ## Output Format -Update the plan file in place (or create `plans/-deepened.md` if requested). +Update the plan file in place (or if user requests a separate file, append `-deepened` after `-plan`, e.g., `2026-01-15-feat-auth-plan-deepened.md`). ## Quality Checks diff --git a/plugins/compound-engineering/commands/workflows/brainstorm.md b/plugins/compound-engineering/commands/workflows/brainstorm.md index b2af445..3cb204d 100644 --- a/plugins/compound-engineering/commands/workflows/brainstorm.md +++ b/plugins/compound-engineering/commands/workflows/brainstorm.md @@ -72,7 +72,7 @@ Use **AskUserQuestion tool** to ask which approach the user prefers. ### Phase 3: Capture the Design -Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-.md`. +Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD--brainstorm.md`. **Document structure:** See the `brainstorming` skill for the template format. Key sections: What We're Building, Why This Approach, Key Decisions, Open Questions. @@ -96,7 +96,7 @@ When complete, display: ``` Brainstorm complete! -Document: docs/brainstorms/YYYY-MM-DD-.md +Document: docs/brainstorms/YYYY-MM-DD--brainstorm.md Key decisions: - [Decision 1] diff --git a/plugins/compound-engineering/commands/workflows/plan.md b/plugins/compound-engineering/commands/workflows/plan.md index 6709eea..07a1a69 100644 --- a/plugins/compound-engineering/commands/workflows/plan.md +++ b/plugins/compound-engineering/commands/workflows/plan.md @@ -124,8 +124,8 @@ Think like a product manager - what would make this issue clear and actionable? - [ ] Draft clear, searchable issue title using conventional format (e.g., `feat: Add user authentication`, `fix: Cart total calculation`) - [ ] Determine issue type: enhancement, bug, refactor -- [ ] Convert title to kebab-case filename: strip prefix colon, lowercase, hyphens for spaces - - Example: `feat: Add User Authentication` → `feat-add-user-authentication.md` +- [ ] Convert title to filename: add today's date prefix, strip prefix colon, kebab-case, add `-plan` suffix + - Example: `feat: Add User Authentication` → `2026-01-21-feat-add-user-authentication-plan.md` - Keep it descriptive (3-5 words after prefix) so plans are findable by context **Stakeholder Analysis:** @@ -169,6 +169,14 @@ Select how comprehensive you want the issue to be, simpler is mostly better. **Structure:** ````markdown +--- +title: [Issue Title] +type: [feat|fix|refactor] +date: YYYY-MM-DD +--- + +# [Issue Title] + [Brief problem/feature description] ## Acceptance Criteria @@ -213,6 +221,14 @@ end **Structure:** ```markdown +--- +title: [Issue Title] +type: [feat|fix|refactor] +date: YYYY-MM-DD +--- + +# [Issue Title] + ## Overview [Comprehensive description] @@ -269,6 +285,14 @@ end **Structure:** ```markdown +--- +title: [Issue Title] +type: [feat|fix|refactor] +date: YYYY-MM-DD +--- + +# [Issue Title] + ## Overview [Executive summary] @@ -444,25 +468,26 @@ end ## Output Format -**Filename:** Use the kebab-case filename from Step 2 Title & Categorization. +**Filename:** Use the date and kebab-case filename from Step 2 Title & Categorization. ``` -plans/-.md +docs/plans/YYYY-MM-DD---plan.md ``` Examples: -- ✅ `plans/feat-user-authentication-flow.md` -- ✅ `plans/fix-checkout-race-condition.md` -- ✅ `plans/refactor-api-client-extraction.md` -- ❌ `plans/plan-1.md` (not descriptive) -- ❌ `plans/new-feature.md` (too vague) -- ❌ `plans/feat: user auth.md` (invalid characters) +- ✅ `docs/plans/2026-01-15-feat-user-authentication-flow-plan.md` +- ✅ `docs/plans/2026-02-03-fix-checkout-race-condition-plan.md` +- ✅ `docs/plans/2026-03-10-refactor-api-client-extraction-plan.md` +- ❌ `docs/plans/2026-01-15-feat-thing-plan.md` (not descriptive - what "thing"?) +- ❌ `docs/plans/2026-01-15-feat-new-feature-plan.md` (too vague - what feature?) +- ❌ `docs/plans/2026-01-15-feat: user auth-plan.md` (invalid characters - colon and space) +- ❌ `docs/plans/feat-user-auth-plan.md` (missing date prefix) ## Post-Generation Options After writing the plan file, use the **AskUserQuestion tool** to present these options: -**Question:** "Plan ready at `plans/.md`. What would you like to do next?" +**Question:** "Plan ready at `docs/plans/YYYY-MM-DD---plan.md`. What would you like to do next?" **Options:** 1. **Open plan in editor** - Open the plan file for review @@ -474,11 +499,11 @@ After writing the plan file, use the **AskUserQuestion tool** to present these o 7. **Simplify** - Reduce detail level Based on selection: -- **Open plan in editor** → Run `open plans/.md` to open the file in the user's default editor +- **Open plan in editor** → Run `open docs/plans/.md` to open the file in the user's default editor - **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research - **`/plan_review`** → Call the /plan_review command with the plan file path - **`/workflows:work`** → Call the /workflows:work command with the plan file path -- **`/workflows:work` on remote** → Run `/workflows:work plans/.md &` to start work in background for Claude Code web +- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/.md &` to start work in background for Claude Code web - **Create Issue** → See "Issue Creation" section below - **Simplify** → Ask "What should I simplify?" then regenerate simpler version - **Other** (automatically provided) → Accept free text for rework or specific changes @@ -496,16 +521,17 @@ When user selects "Create Issue", detect their project tracker from CLAUDE.md: - Or look for mentions of "GitHub Issues" or "Linear" in their workflow section 2. **If GitHub:** + + Use the title and type from Step 2 (already in context - no need to re-read the file): + ```bash - # Extract title from plan filename (kebab-case to Title Case) - # Read plan content for body - gh issue create --title "feat: [Plan Title]" --body-file plans/.md + gh issue create --title ": " --body-file <plan_path> ``` 3. **If Linear:** + ```bash - # Use linear CLI if available, or provide instructions - # linear issue create --title "[Plan Title]" --description "$(cat plans/<issue_title>.md)" + linear issue create --title "<title>" --description "$(cat <plan_path>)" ``` 4. **If no tracker configured:** diff --git a/plugins/compound-engineering/skills/brainstorming/SKILL.md b/plugins/compound-engineering/skills/brainstorming/SKILL.md index f8115f6..0a994dd 100644 --- a/plugins/compound-engineering/skills/brainstorming/SKILL.md +++ b/plugins/compound-engineering/skills/brainstorming/SKILL.md @@ -134,7 +134,7 @@ topic: <kebab-case-topic> → `/workflows:plan` for implementation details ``` -**Output Location:** `docs/brainstorms/YYYY-MM-DD-<topic>.md` +**Output Location:** `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md` ### Phase 4: Handoff