commit 54c1d4009a8039c8cef784950794a49d93fa5691 Author: Zhongwei Li Date: Sun Nov 30 09:03:37 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..06fe961 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "plan", + "description": "Planning and brainstorming workflows for software development - helps refine ideas into designs and create detailed implementation plans", + "version": "0.1.0", + "author": { + "name": "zbeyens" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..2ecadd5 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# plan + +Planning and brainstorming workflows for software development - helps refine ideas into designs and create detailed implementation plans diff --git a/commands/brainstorm.md b/commands/brainstorm.md new file mode 100644 index 0000000..acc63d8 --- /dev/null +++ b/commands/brainstorm.md @@ -0,0 +1,10 @@ +--- +description: Interactive design refinement using Socratic method with AskUserQuestion tool +--- + +Use and follow the brainstorm skill exactly as written + +**🚨 CRITICAL REQUIREMENTS**: + +1. **Write plan file FIRST**: Create `.claude/docs/plans/-design.md` BEFORE asking questions, then update it incrementally after EACH answer. Do NOT wait until the end. +2. **Use AskUserQuestion tool for ALL questions**: NEVER output questions as plain text - always use the tool to enable interactive selection. diff --git a/commands/execute-plan.md b/commands/execute-plan.md new file mode 100644 index 0000000..6b24b98 --- /dev/null +++ b/commands/execute-plan.md @@ -0,0 +1,5 @@ +--- +description: Execute plan in batches with review checkpoints +--- + +Use the executing-plans skill exactly as written diff --git a/commands/write-plan.md b/commands/write-plan.md new file mode 100644 index 0000000..6845e50 --- /dev/null +++ b/commands/write-plan.md @@ -0,0 +1,5 @@ +--- +description: Create detailed implementation plan with bite-sized tasks +--- + +Use the writing-plans skill exactly as written diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..f85641b --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,65 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:udecode/dotai:.claude-plugin/plugins/plan", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "17f9dab5ddf22882a9afbdd886553a7686f1ae68", + "treeHash": "c3ba9deca7f4baffd19e06de8e0063b8921b000b9489733442b0a433081de44f", + "generatedAt": "2025-11-28T10:28:49.072308Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "plan", + "description": "Planning and brainstorming workflows for software development - helps refine ideas into designs and create detailed implementation plans", + "version": "0.1.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "5340fb3e2c6e64722b4de65e3597cd1597b6f53446070e585a2b5afc675956b5" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "d3467a8319adb25b8240c4151884ea6d997d19852d207571600e7f36ae377119" + }, + { + "path": "commands/execute-plan.md", + "sha256": "2fe897057e1d41dff582ec33c66ff2e5be74cbb0d17be61cd1c357d3b6e51b08" + }, + { + "path": "commands/write-plan.md", + "sha256": "22e58a637a46420673646b64559b453265d6119e62b6081687bec61952d751c5" + }, + { + "path": "commands/brainstorm.md", + "sha256": "f99d0af649e23e3355ae49f2750af9ea4b47301070552fd384df18c7c68c64c1" + }, + { + "path": "skills/executing-plans/SKILL.md", + "sha256": "a914a28597ab78bfc30fab180d1131ee4b63ee0c9174f4c91b811da2c2cc2147" + }, + { + "path": "skills/brainstorming/SKILL.md", + "sha256": "aaa7cc4b2325d69a36000b83b078d5bb53c0bb9e8a5654c238ef18cdd4882c3d" + }, + { + "path": "skills/writing-plans/SKILL.md", + "sha256": "42461112699b3cd48ae5e9a3dffbc2b35e74b16c4a5abf30e6b0e215e11a24c1" + } + ], + "dirSha256": "c3ba9deca7f4baffd19e06de8e0063b8921b000b9489733442b0a433081de44f" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md new file mode 100644 index 0000000..e941323 --- /dev/null +++ b/skills/brainstorming/SKILL.md @@ -0,0 +1,137 @@ +--- +name: brainstorming +description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes +--- + +# Brainstorming Ideas Into Designs + +## Overview + +Help turn ideas into fully formed designs and specs through natural collaborative dialogue. + +**🚨 CRITICAL REQUIREMENT**: Create the plan file `.claude/docs/plans/-design.md` BEFORE asking questions, then update it incrementally after EACH answer. Do NOT wait until the end to write everything at once. + +Start by understanding the current project context, then ask multiple related questions together (up to 4 at once) to efficiently refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far. + +## The Process + +**CRITICAL FIRST STEP - Create Plan File Immediately:** + +- **Before asking ANY questions, create `.claude/docs/plans/-design.md` using Write tool** +- Write initial context: problem statement, initial understanding (even if incomplete) +- Structure: Use headings like "Goals", "Requirements", "Architecture", "Open Questions" +- This file is your working document - update it continuously throughout brainstorming +- **DO NOT wait until the end** - write first, refine continuously + +**Understanding the idea:** + +- Check out the current project state first (files, docs, recent commits) +- **After EACH round of answers, immediately update the plan file using Edit tool** +- Ask multiple related questions together using the AskUserQuestion tool (up to 4 per call) +- **CRITICAL**: Always use the AskUserQuestion tool for ALL questions - NEVER output questions as plain text +- Prefer multiple choice questions when possible (the tool supports multiSelect when needed) +- Group related questions together for efficiency (e.g., scope + timeline + constraints in one call) +- Focus on understanding: purpose, constraints, success criteria +- After each round of answers, ask follow-up questions to drill deeper into areas that need clarification +- **Pattern: Question → Answer → Update plan file → Next question** + +**Exploring approaches:** + +- Propose 2-3 different approaches with trade-offs +- Present options conversationally with your recommendation and reasoning +- Lead with your recommended option and explain why + +**Presenting the design:** + +- Once you believe you understand what you're building, present the design +- Break it into sections of 200-300 words +- Use AskUserQuestion tool after each section to confirm it looks right (e.g., "Does this architecture look right?") +- Cover: architecture, components, data flow, error handling, testing +- Be ready to go back and clarify if something doesn't make sense + +## Design vs Implementation Boundaries + +**THIS SKILL IS FOR DESIGN ONLY.** If you find yourself writing implementation details, STOP - you're crossing into writing-plans territory. + +**DESIGN (this skill) - High-level, conceptual:** +- Architecture decisions and trade-offs (e.g., "Use React Query for server state") +- Component responsibilities (conceptual) (e.g., "FilterSidebar handles job title filtering") +- Data flow approach (e.g., "Server actions → React Query → UI") +- Technology choices with reasoning (e.g., "shadcn/ui for component library") +- Open questions and assumptions + +**IMPLEMENTATION (writing-plans skill) - Detailed, executable:** +- Exact file paths (e.g., "src/app/(protected)/training-videos/page.tsx") +- Numbered implementation phases/steps (e.g., "Phase 1: Sidebar Setup") +- "Files to modify" and "Files to create" lists +- Complete code examples and snippets +- Git commit instructions +- Task breakdown with dependencies + +**Red Flags - STOP Immediately:** +- Writing "Phase 1: Setup", "Phase 2: Components" → That's writing-plans +- Listing "Files to modify: src/exact/path.tsx" → That's writing-plans +- Creating "File Change Summary" section → That's writing-plans +- Writing "Implementation Plan" header → That's writing-plans +- Providing exact directory structures with file paths → That's writing-plans + +**If you catch yourself doing any of the above, immediately:** +1. Delete the implementation content +2. Ask user if ready to transition to writing-plans skill +3. Use writing-plans skill to create proper implementation plan + +## After the Design + +**Documentation:** + +- The plan file `.claude/docs/plans/-design.md` should already exist and be complete +- **You should have been updating it throughout the entire brainstorming process** +- If you haven't been updating it incrementally, you made a mistake - fix it now +- Final pass: Review for clarity, completeness, and consistency +- Use elements-of-style:writing-clearly-and-concisely skill if available for polish + +**Incremental Writing Pattern (THE CORRECT WAY):** + +``` +WRONG ❌: +1. Ask all questions +2. Get all answers +3. Write entire plan at the end + +CORRECT ✅: +1. Write initial plan file with problem statement +2. Ask question batch 1 +3. Immediately update plan file with answers +4. Ask question batch 2 +5. Immediately update plan file with answers +6. Present design section by section +7. Update plan file with any refinements +8. Final review and polish +``` + +Example workflow: + +1. **Start**: Write `.claude/docs/plans/2025-11-05-pcc-sync-design.md` with initial understanding +2. **Question 1**: Ask about goals → User answers → Edit plan file "Goals" section +3. **Question 2**: Ask about technical constraints → User answers → Edit plan file "Requirements" section +4. **Question 3**: Ask about data types → User answers → Edit plan file "Data Types" section +5. **Design**: Present architecture → User approves → Edit plan file "Architecture" section +6. **Refinement**: User asks about error handling → Edit plan file to add "Error Handling" section +7. **Complete**: Plan file reflects entire conversation + +The plan file is your **working document**, not a final deliverable to write at the end + +**Implementation (if continuing):** + +- Use AskUserQuestion tool: "Ready to set up for implementation?" with options: ["Yes, create implementation plan", "No, refine design more", "No, just save the design"] +- **MANDATORY NEXT STEP if user chooses "Yes":** Use writing-plans skill to create detailed implementation plan + +## Key Principles + +- **Use AskUserQuestion tool** - ALWAYS use the tool for questions, never plain text +- **Ask multiple questions** - Group related questions together (up to 4) for efficiency +- **Multiple choice preferred** - The tool makes it easy for users to select from options +- **YAGNI ruthlessly** - Remove unnecessary features from all designs +- **Explore alternatives** - Always propose 2-3 approaches before settling +- **Incremental validation** - Present design in sections, validate each with AskUserQuestion +- **Be flexible** - Go back and clarify when something doesn't make sense diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md new file mode 100644 index 0000000..78d3571 --- /dev/null +++ b/skills/executing-plans/SKILL.md @@ -0,0 +1,96 @@ +--- +name: executing-plans +description: Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically, executes tasks in batches, reports for review between batches +--- + +# Executing Plans + +## Overview + +Load plan, review critically, execute tasks in batches, report for review between batches. + +**Core principle:** Batch execution with checkpoints for architect review. + +**Announce at start:** "I'm using the executing-plans skill to implement this plan." + +## The Process + +### Step 1: Load and Review Plan + +1. Read plan file +2. Review critically - identify any questions or concerns about the plan +3. If concerns: Raise them with your human partner before starting +4. If no concerns: Create TodoWrite and proceed + +### Step 2: Execute Batch + +**Default: First 3 tasks** + +For each task: + +1. Mark as in_progress +2. Follow each step exactly (plan has bite-sized steps) +3. Run verifications as specified (tests if included, typecheck/lint if not) +4. Mark as completed + +**Note on tests**: Only some tasks will have tests (complex logic only). Follow the plan's testing approach - don't add tests where the plan doesn't specify them. + +### Step 3: Report and Commit Check + +When batch complete: + +- Show what was implemented +- Show verification output +- **Check if commit should be suggested:** + - If you verified tests/typecheck/lint passed AND plan includes commit steps → Ask: "Batch complete. Create commit for these changes?" + - If tests are user's responsibility OR you couldn't verify → Skip commit suggestion, just report +- Say: "Ready for feedback." + +### Step 4: Continue + +Based on feedback: + +- Apply changes if needed +- Execute next batch +- Repeat until complete + +### Step 5: Complete Development + +After all tasks complete and verified: + +- Run final verification: `npm run typecheck && npm run lint` +- Report completion summary showing all implemented tasks +- **Final commit check using AskUserQuestion tool:** + - If no commits created during batches → Ask: "All tasks complete. Create a git commit?" + - If already committed during batches → Ask: "All tasks complete. Run additional verification or move on?" + +## When to Stop and Ask for Help + +**STOP executing immediately when:** + +- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear) +- Plan has critical gaps preventing starting +- You don't understand an instruction +- Verification fails repeatedly + +**Ask for clarification rather than guessing.** + +## When to Revisit Earlier Steps + +**Return to Review (Step 1) when:** + +- Partner updates the plan based on your feedback +- Fundamental approach needs rethinking + +**Don't force through blockers** - stop and ask. + +## Remember + +- Review plan critically first +- Follow plan steps exactly +- Don't skip verifications +- Reference skills when plan says to +- Between batches: report, check commit opportunity, wait for feedback +- **Never auto-commit** - Always ask user first, even if plan includes commit commands +- Leverage batch pauses for commit suggestions (don't create extra pauses) +- Stop when blocked, don't guess diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md new file mode 100644 index 0000000..ac50998 --- /dev/null +++ b/skills/writing-plans/SKILL.md @@ -0,0 +1,203 @@ +--- +name: writing-plans +description: Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming engineer has minimal domain knowledge +--- + +# Writing Plans + +## Overview + +Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. + +Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well. + +**Announce at start:** "I'm using the writing-plans skill to create the implementation plan." + +**Save plans to:** `.claude/docs/plans/-plan.md` + +**Testing Strategy:** Auto-decide whether unit tests are needed based on complexity: + +- **Include tests for**: Complex algorithms, business logic, data transformations where bugs are likely +- **Skip tests for**: Simple CRUD, UI components, straightforward mappings, anything you're 100% certain is bug-free +- **Test type**: Only deterministic unit tests - no integration tests, no complex mocking, no async complexity +- Tests should verify logic, not implementation details + +## Bite-Sized Task Granularity + +**Each step is one action (2-5 minutes):** + +**If tests are included (for complex behavior):** + +- "Write the failing test" - step +- "Run it to make sure it fails" - step +- "Implement the minimal code to make the test pass" - step +- "Run the tests and make sure they pass" - step +- "Commit" - step + +**If no tests (for simple changes):** + +- "Implement the code" - step +- "Verify with typecheck/lint" - step +- "Commit" - step + +## Plan Document Header + +**Every plan MUST start with this header:** + +```markdown +# [Feature Name] Implementation Plan + +**Goal:** [One sentence describing what this builds] + +**Architecture:** [2-3 sentences about approach] + +**Tech Stack:** [Key technologies/libraries] + +**Testing Approach:** [If tests included: "TDD with deterministic unit tests for complex logic (Tasks X, Y, Z)" | If no tests: "Code review and typecheck verification - logic is straightforward and bug-free"] + +--- +``` + +## Task Structure + +### With Tests (Complex Behavior) + +````markdown +### Task N: [Component Name] + +**Files:** + +- Create: `exact/path/to/file.ts` +- Modify: `exact/path/to/existing.ts:123-145` +- Test: `tests/exact/path/to/test.spec.ts` + +**Step 1: Write the failing test** + +```typescript +describe('specific behavior', () => { + it('should return expected result', () => { + const result = function(input); + expect(result).toBe(expected); + }); +}); +``` + +**Step 2: Run test to verify it fails** + +Run: `npm run test -- test.spec.ts` +Expected: FAIL with "function is not defined" + +**Step 3: Write minimal implementation** + +```typescript +export function function(input: InputType): ReturnType { + return expected; +} +``` + +**Step 4: Run test to verify it passes** + +Run: `npm run test -- test.spec.ts` +Expected: PASS + +**Step 5: Commit** + +```bash +git add tests/path/test.spec.ts src/path/file.ts +git commit -m "feat: add specific feature" +``` +```` + +### Without Tests (Simple Changes) + +````markdown +### Task N: [Component Name] + +**Files:** + +- Create: `exact/path/to/file.ts` +- Modify: `exact/path/to/existing.ts:123-145` + +**Step 1: Implement the code** + +```typescript +export function function(input: InputType): ReturnType { + return expected; +} +``` + +**Step 2: Verify with typecheck** + +Run: `npm run typecheck` +Expected: No errors + +**Step 3: Verify with lint** + +Run: `npm run lint` +Expected: No errors + +**Step 4: Commit** + +```bash +git add src/path/file.ts +git commit -m "feat: add specific feature" +``` +```` + +## Remember + +- Auto-decide on unit tests - only for complex logic where bugs are likely +- Only deterministic unit tests - no integration/async/complex mocking +- Exact file paths always +- Complete code in plan (not "add validation") +- Exact commands with expected output +- Reference relevant skills with @ syntax +- DRY, YAGNI, frequent commits +- TypeScript syntax for all examples + +## Git Commit Guidance + +**IMPORTANT: Plans include commit steps, but executing-plans will handle commit approval.** + +**During Execution (not plan writing):** + +- **NEVER auto-commit** - Even if plan includes commit commands, agent must ask user first +- **When to suggest commits:** + - After completing batch where agent verified tests pass + - Leverage existing pause points (batch completion, not extra pauses) + - Only when agent can verify the work (tests, typecheck, lint) +- **When NOT to suggest commits:** + - Tests are user's responsibility (agent can't verify) + - No natural pause point exists + - Manual verification required + +**In this skill (plan writing):** + +- Include commit steps in tasks as part of the plan +- Commit commands show what should be committed, not when +- executing-plans skill handles actual commit timing and user approval + +## Execution Handoff + +After saving the plan, offer execution choice: + +**"Plan complete and saved to `.claude/docs/plans/.md`. Two execution options:** + +**1. This Session (default)** - Execute tasks iteratively in this session, reviewing and adjusting between tasks + +**2. Parallel Session** - Open new session with executing-plans skill for batch execution with checkpoints + +**Which approach? (Press Enter for option 1)"** + +**If This Session (default):** + +- Use the superpowers executing-plans skill in this session +- Execute in batches (default: first 3 tasks) +- Review and iterate between batches +- Adjust plan if needed based on learnings + +**If Parallel Session chosen:** + +- Guide them to open new session +- **REQUIRED SUB-SKILL:** New session uses superpowers executing-plans +- Load the plan file and execute in batches