zhongwei/gh-udecode-dotai-claude-plugin-plugins-plan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:03:37 +08:00
commit 54c1d4009a
9 changed files with 538 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# plan
Planning and brainstorming workflows for software development - helps refine ideas into designs and create detailed implementation plans

10
commands/brainstorm.md Normal file
View File

@@ -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/<topic>-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.

5
commands/execute-plan.md Normal file
View File

@@ -0,0 +1,5 @@
---
description: Execute plan in batches with review checkpoints
---
Use the executing-plans skill exactly as written

5
commands/write-plan.md Normal file
View File

@@ -0,0 +1,5 @@
---
description: Create detailed implementation plan with bite-sized tasks
---
Use the writing-plans skill exactly as written

65
plugin.lock.json Normal file
View File

@@ -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": []
}
}

137
skills/brainstorming/SKILL.md Normal file
View File

@@ -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/<topic>-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/<topic>-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/<topic>-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

96
skills/executing-plans/SKILL.md Normal file
View File

@@ -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

203
skills/writing-plans/SKILL.md Normal file
View File

@@ -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/<feature-name>-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/<filename>.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