Initial commit

2025-11-30 09:03:37 +08:00
commit 54c1d4009a
9 changed files with 538 additions and 0 deletions
--- a/skills/brainstorming/SKILL.md
+++ 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/<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
--- a/skills/executing-plans/SKILL.md
+++ 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
--- a/skills/writing-plans/SKILL.md
+++ 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/<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