Add new methodology skills for enhanced development workflows

2026-07-14 02:55:18 +03:00 · 2025-11-29 18:27:51 +07:00
parent ef96f165ef
commit 353e55e2fe
24 changed files with 3979 additions and 4 deletions
@@ -0,0 +1,159 @@
+# /brainstorm - Interactive Design Session
+
+## Purpose
+
+Start an interactive brainstorming session using the one-question-at-a-time methodology. Refine rough ideas into fully-formed designs through collaborative dialogue.
+
+## Usage
+
+```
+/brainstorm [topic or feature to design]
+```
+
+## Arguments
+
+- `$ARGUMENTS`: The topic, feature, or problem to brainstorm about
+
+---
+
+Start interactive brainstorming session for: **$ARGUMENTS**
+
+## Methodology
+
+**Reference**: `.claude/skills/methodology/brainstorming/SKILL.md`
+
+This command uses the superpowers brainstorming methodology for optimal results.
+
+## Workflow
+
+### Phase 1: Understanding
+
+**Goal**: Clarify requirements through sequential questioning.
+
+**Rules**:
+1. Ask **ONE question per message**
+2. Wait for user response before next question
+3. Prefer **multiple-choice** over open-ended questions
+4. Break complex topics into multiple questions
+
+**Example interaction**:
+```
+Claude: "What type of authentication should we support?
+         a) Username/password only
+         b) OAuth providers (Google, GitHub)
+         c) Both options
+         d) Magic link (passwordless)"
+
+User: "b"
+
+Claude: "Which OAuth providers should we integrate?
+         a) Google only
+         b) GitHub only
+         c) Both Google and GitHub
+         d) Let me specify others..."
+```
+
+### Phase 2: Exploration
+
+**Goal**: Present alternatives with clear trade-offs.
+
+Present 2-3 approaches:
+- Lead with recommended option
+- Explain trade-offs for each
+- Let user choose direction
+
+```markdown
+## Approach 1: JWT-based (Recommended)
+- Stateless, scalable
+- Cons: Can't revoke instantly
+
+## Approach 2: Session-based
+- Easy revocation
+- Cons: Requires session store
+
+Which approach aligns better with your goals?
+```
+
+### Phase 3: Design Presentation
+
+**Goal**: Present validated design incrementally.
+
+**Rules**:
+- Break into **200-300 word sections**
+- Validate after each section
+- Cover: architecture, components, data flow, error handling, testing
+
+**Sections to present**:
+1. Architecture overview
+2. Component breakdown
+3. Data flow
+4. Error handling
+5. Testing considerations
+
+## Core Principles
+
+### YAGNI Ruthlessly
+
+Remove unnecessary features aggressively:
+- Question every "nice to have"
+- Start with minimal viable design
+- "We might need this later" = remove it
+
+### One Question at a Time
+
+Sequential questioning produces better results:
+- Gives user time to think deeply
+- Prevents overwhelming with choices
+- Creates natural conversation flow
+
+### Multiple-Choice Preference
+
+When possible, provide structured options:
+- Reduces cognitive load
+- Surfaces your understanding
+- Makes decisions concrete
+
+## Output
+
+After design is validated, create design document:
+
+```markdown
+# Design: [Feature Name]
+Date: [YYYY-MM-DD]
+
+## Summary
+[2-3 sentences]
+
+## Architecture
+[Architecture decisions]
+
+## Components
+[Component breakdown]
+
+## Data Flow
+[How data moves through system]
+
+## Error Handling
+[Error scenarios and handling]
+
+## Testing Strategy
+[Testing approach]
+
+## Open Questions
+[Any remaining unknowns]
+```
+
+## Next Steps After Brainstorming
+
+After design is complete:
+1. Commit design document to version control
+2. Use `/plan --detailed` for implementation planning
+3. Use `/execute-plan` for automated implementation
+
+## When NOT to Use
+
+- Clear "mechanical" processes with known implementation
+- Simple bug fixes with obvious solutions
+- Tasks with explicit requirements already defined
+
+Use direct implementation instead.
@@ -0,0 +1,221 @@
+# /execute-plan - Subagent-Driven Plan Execution
+
+## Purpose
+
+Execute a detailed implementation plan using fresh subagents per task with mandatory code review gates between tasks.
+
+## Usage
+
+```
+/execute-plan [plan-file-path]
+```
+
+## Arguments
+
+- `$ARGUMENTS`: Path to the plan file (created with `/plan --detailed`)
+
+---
+
+Execute plan from: **$ARGUMENTS**
+
+## Methodology
+
+**Reference**: `.claude/skills/methodology/executing-plans/SKILL.md`
+
+This command uses the superpowers execution methodology for quality-gated implementation.
+
+## Core Pattern
+
+**"Fresh subagent per task + review between tasks = high quality, fast iteration"**
+
+### Why Fresh Agents?
+
+- Prevents context pollution between tasks
+- Each task gets focused attention
+- Failures don't cascade
+- Easier to retry individual tasks
+
+### Why Code Review Between Tasks?
+
+- Catches issues early
+- Ensures code matches intent
+- Prevents technical debt accumulation
+- Creates natural checkpoints
+
+## Workflow
+
+### Step 1: Load Plan
+
+1. Read the plan file
+2. Verify plan is complete and approved
+3. Create TodoWrite with all tasks from plan
+4. Set first task to `in_progress`
+
+### Step 2: Execute Task (For Each Task)
+
+```markdown
+1. Dispatch fresh subagent with task details
+2. Subagent implements following TDD cycle:
+   - Write failing test
+   - Verify test fails
+   - Implement minimally
+   - Verify test passes
+   - Commit
+3. Subagent returns completion summary
+```
+
+### Step 3: Code Review
+
+After each task:
+
+```markdown
+1. Dispatch code-reviewer subagent
+2. Review scope: only changes from current task
+3. Reviewer returns findings:
+   - Critical: Must fix before proceeding
+   - Important: Should fix before proceeding
+   - Minor: Can fix later
+```
+
+### Step 4: Handle Review Findings
+
+```markdown
+IF Critical or Important issues found:
+  1. Dispatch fix subagent for each issue
+  2. Re-request code review
+  3. Repeat until no Critical/Important issues
+
+IF only Minor issues:
+  1. Note for later cleanup
+  2. Proceed to next task
+```
+
+### Step 5: Mark Complete
+
+1. Update TodoWrite - mark task completed
+2. Move to next task
+3. Repeat from Step 2
+
+### Step 6: Final Review
+
+After all tasks complete:
+
+1. Dispatch comprehensive code review
+2. Review entire implementation against plan
+3. Verify all success criteria met
+4. Run full test suite
+5. Use `finishing-development-branch` skill
+
+## Critical Rules
+
+### Never Skip Code Reviews
+
+Every task must be reviewed before proceeding. No exceptions.
+
+### Never Proceed with Critical Issues
+
+Critical issues must be fixed:
+```
+implement → review → fix critical → re-review → proceed
+```
+
+### Never Run Parallel Implementation
+
+Tasks run sequentially:
+```
+WRONG: Run Task 1, 2, 3 simultaneously
+RIGHT: Task 1 → Review → Task 2 → Review → Task 3 → Review
+```
+
+### Always Read Plan Before Implementing
+
+```
+WRONG: Start coding based on memory of plan
+RIGHT: Read plan file, extract task details, then implement
+```
+
+## Error Handling
+
+### Task Fails
+
+1. Capture error details
+2. Attempt fix (max 2 retries)
+3. If still failing, pause execution
+4. Report to user with:
+   - Which task failed
+   - Error details
+   - Suggested resolution
+5. Wait for user decision
+
+### Review Finds Major Issues
+
+1. List all Critical/Important issues
+2. Dispatch fix subagent for each
+3. Re-run code review
+4. If issues persist after 2 cycles:
+   - Pause execution
+   - Report to user
+   - May need plan revision
+
+## Output
+
+### Progress Updates
+
+```markdown
+## Execution Progress
+
+### Task 1: Create User model ✓
+- Files modified: src/models/user.ts
+- Tests added: 3
+- Review: Passed
+
+### Task 2: Add validation ✓
+- Files modified: src/models/user.ts
+- Tests added: 2
+- Review: Passed (1 minor deferred)
+
+### Task 3: Create endpoint [IN PROGRESS]
+- Status: Implementing...
+```
+
+### Completion Summary
+
+```markdown
+## Execution Complete
+
+### Summary
+- Tasks completed: 8/8
+- Tests added: 24
+- Coverage: 92%
+
+### Files Created
+- src/models/user.ts
+- src/services/user-service.ts
+- src/routes/user.ts
+
+### Files Modified
+- src/routes/index.ts
+- src/types/index.ts
+
+### Deferred Items
+- Minor: Variable rename in user-service.ts line 12
+
+### Next Steps
+- Run full test suite
+- Use /ship to create PR
+```
+
+## Prerequisites
+
+Before using this command:
+
+1. Plan file exists and is complete
+2. Plan was created with `/plan --detailed`
+3. Plan has been reviewed and approved
+4. Tests can be run (`npm test` or `pytest`)
+
+## Related Commands
+
+- `/plan --detailed` - Create detailed plan
+- `/brainstorm` - Design before planning
+- `/ship` - Create PR after execution
@@ -191,11 +191,76 @@ For code improvements
 ### Migration Plan
 For data or system migrations

+## Detailed Mode (Superpowers Methodology)
+
+Use `--detailed` flag for superpowers-style plans with 2-5 minute tasks:
+
+```
+/plan --detailed [task description]
+```
+
+### Detailed Mode Features
+
+**Reference**: `.claude/skills/methodology/writing-plans/SKILL.md`
+
+When `--detailed` is specified:
+- **Bite-sized tasks**: 2-5 minutes each (vs standard 15-60 min)
+- **Exact file paths**: Always include full paths
+- **Complete code samples**: Actual code, not descriptions
+- **TDD steps per task**: Write test → verify fail → implement → verify pass → commit
+- **Expected command outputs**: Specify what success looks like
+
+### Detailed Task Template
+
+```markdown
+## Task [N]: [Task Name]
+
+**Files**:
+- Create: `path/to/new-file.ts`
+- Modify: `path/to/existing-file.ts`
+- Test: `path/to/test-file.test.ts`
+
+**Steps**:
+
+1. Write failing test
+   ```typescript
+   // Exact test code
+   ```
+
+2. Verify test fails
+   ```bash
+   npm test -- --grep "test name"
+   # Expected: 1 failing
+   ```
+
+3. Implement minimally
+   ```typescript
+   // Exact implementation code
+   ```
+
+4. Verify test passes
+   ```bash
+   npm test -- --grep "test name"
+   # Expected: 1 passing
+   ```
+
+5. Commit
+   ```bash
+   git commit -m "feat: add [feature]"
+   ```
+```
+
+### Execution After Planning
+
+Use `/execute-plan [plan-file]` for subagent-driven execution with code review gates.
+
+**Reference**: `.claude/skills/methodology/executing-plans/SKILL.md`
+
 <!-- CUSTOMIZATION POINT -->
 ## Variations

 Modify behavior via CLAUDE.md:
- Task size definitions
+- Task size definitions (standard: 15-60 min, detailed: 2-5 min)
 - Required plan sections
 - Estimation approach
 - Risk assessment criteria
@@ -69,6 +69,53 @@ Add more test cases and repeat the cycle.
 - Keep the red-green-refactor cycle short
 - Commit after each green phase

+## Superpowers TDD Methodology
+
+**Reference**: `.claude/skills/methodology/test-driven-development/SKILL.md`
+
+### Non-Negotiable Rule
+
+**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+This is not a guideline - it's a rule.
+
+### If You Already Wrote Code
+
+Delete it. Completely. Don't keep it as reference.
+
+```
+WRONG: "I'll keep this code as reference while writing tests"
+RIGHT: Delete the code, write test, rewrite implementation
+```
+
+### Verification Before Completion
+
+**Reference**: `.claude/skills/methodology/verification-before-completion/SKILL.md`
+
+Before claiming tests pass:
+1. **Identify** the command that proves assertion
+2. **Execute** it fully and freshly
+3. **Read** complete output
+4. **Verify** output matches claim
+5. **Only then** make the claim
+
+### Forbidden Language
+
+Never use without verification:
+- "should work"
+- "probably fixed"
+- "seems to pass"
+
+### Testing Anti-Patterns to Avoid
+
+**Reference**: `.claude/skills/methodology/testing-anti-patterns/SKILL.md`
+
+1. Testing mock behavior instead of real code
+2. Polluting production with test-only methods
+3. Mocking without understanding dependencies
+4. Creating incomplete mocks
+5. Writing tests as afterthoughts
+
 ## Output

 ```markdown