@techwavedev/agi-agent-kit 1.2.7 → 1.2.8

package/templates/skills/knowledge/plan-writing/SKILL.md

@@ -9,27 +9,32 @@ allowed-tools: Read, Glob, Grep
 > Source: obra/superpowers
 
 ## Overview
+
 This skill provides a framework for breaking down work into clear, actionable tasks with verification criteria.
 
 ## Task Breakdown Principles
 
 ### 1. Small, Focused Tasks
+
 - Each task should take 2-5 minutes
 - One clear outcome per task
 - Independently verifiable
 
 ### 2. Clear Verification
+
 - How do you know it's done?
 - What can you check/test?
 - What's the expected output?
 
 ### 3. Logical Ordering
+
 - Dependencies identified
 - Parallel work where possible
 - Critical path highlighted
 - **Phase X: Verification is always LAST**
 
 ### 4. Dynamic Naming in Project Root
+
 - Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
 - Name derived from task (e.g., "add auth" → `auth-feature.md`)
 - **NEVER** inside `.claude/`, `docs/`, or temp folders
@@ -40,11 +45,11 @@ This skill provides a framework for breaking down work into clear, actionable ta
 
 ### Principle 1: Keep It SHORT
 
-| ❌ Wrong | ✅ Right |
-|----------|----------|
-| 50 tasks with sub-sub-tasks | 5-10 clear tasks max |
-| Every micro-step listed | Only actionable items |
-| Verbose descriptions | One-line per task |
+| ❌ Wrong                    | ✅ Right              |
+| --------------------------- | --------------------- |
+| 50 tasks with sub-sub-tasks | 5-10 clear tasks max  |
+| Every micro-step listed     | Only actionable items |
+| Verbose descriptions        | One-line per task     |
 
 > **Rule:** If plan is longer than 1 page, it's too long. Simplify.
 
@@ -52,11 +57,11 @@ This skill provides a framework for breaking down work into clear, actionable ta
 
 ### Principle 2: Be SPECIFIC, Not Generic
 
-| ❌ Wrong | ✅ Right |
-|----------|----------|
-| "Set up project" | "Run `npx create-next-app`" |
+| ❌ Wrong             | ✅ Right                                                 |
+| -------------------- | -------------------------------------------------------- |
+| "Set up project"     | "Run `npx create-next-app`"                              |
 | "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
-| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
+| "Style the UI"       | "Add Tailwind classes to `Header.tsx`"                   |
 
 > **Rule:** Each task should have a clear, verifiable outcome.
 
@@ -65,16 +70,19 @@ This skill provides a framework for breaking down work into clear, actionable ta
 ### Principle 3: Dynamic Content Based on Project Type
 
 **For NEW PROJECT:**
+
 - What tech stack? (decide first)
 - What's the MVP? (minimal features)
 - What's the file structure?
 
 **For FEATURE ADDITION:**
+
 - Which files are affected?
 - What dependencies needed?
 - How to verify it works?
 
 **For BUG FIX:**
+
 - What's the root cause?
 - What file/line to change?
 - How to test the fix?
@@ -85,13 +93,13 @@ This skill provides a framework for breaking down work into clear, actionable ta
 
 > 🔴 **DO NOT copy-paste script commands. Choose based on project type.**
 
-| Project Type | Relevant Scripts |
-|--------------|------------------|
+| Project Type   | Relevant Scripts                          |
+| -------------- | ----------------------------------------- |
 | Frontend/React | `ux_audit.py`, `accessibility_checker.py` |
-| Backend/API | `api_validator.py`, `security_scan.py` |
-| Mobile | `mobile_audit.py` |
-| Database | `schema_validator.py` |
-| Full-stack | Mix of above based on what you touched |
+| Backend/API    | `api_validator.py`, `security_scan.py`    |
+| Mobile         | `mobile_audit.py`                         |
+| Database       | `schema_validator.py`                     |
+| Full-stack     | Mix of above based on what you touched    |
 
 **Wrong:** Adding all scripts to every plan
 **Right:** Only scripts relevant to THIS task
@@ -100,11 +108,11 @@ This skill provides a framework for breaking down work into clear, actionable ta
 
 ### Principle 5: Verification is Simple
 
-| ❌ Wrong | ✅ Right |
-|----------|----------|
-| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast" |
-| "Test the API" | "curl localhost:3000/api/users returns 200" |
-| "Check styles" | "Open browser, verify dark mode toggle works" |
+| ❌ Wrong                               | ✅ Right                                      |
+| -------------------------------------- | --------------------------------------------- |
+| "Verify the component works correctly" | "Run `npm run dev`, click button, see toast"  |
+| "Test the API"                         | "curl localhost:3000/api/users returns 200"   |
+| "Check styles"                         | "Open browser, verify dark mode toggle works" |
 
 ---
 
@@ -129,8 +137,62 @@ One sentence: What are we building/fixing?
 > Keep it minimal. Add complexity only when required.
 
 ## Notes
+
 [Any important considerations]
-```
+
+````
+
+---
+
+## Bite-Sized Task Granularity (TDD Steps)
+
+> Adapted from obra/superpowers — each step is one action (2-5 minutes).
+
+When the project has testable code, structure each task with TDD steps:
+
+```markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.ext`
+- Modify: `exact/path/to/existing.ext`
+- Test: `tests/exact/path/to/test.ext`
+
+**Step 1: Write the failing test**
+[Complete test code]
+
+**Step 2: Run test to verify it fails**
+Run: [exact command]
+Expected: FAIL with "[reason]"
+
+**Step 3: Write minimal implementation**
+[Complete implementation code]
+
+**Step 4: Run test to verify it passes**
+Run: [exact command]
+Expected: PASS
+
+**Step 5: Commit**
+git add [files] && git commit -m "feat: [description]"
+````
+
+> 🔴 **Not every task needs TDD steps.** Config changes, setup tasks, and non-code tasks can use simpler step structure.
+
+---
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete. Two execution options:**
+
+**1. Subagent-Driven** — Fresh agent per task, two-stage review (spec compliance + code quality), fast iteration
+
+**2. Batch Execution** — Execute 3 tasks at a time, report for human review between batches
+
+**Which approach?"**
+
+Both options use the `executing-plans` skill for structured execution.
 
 ---
 
@@ -141,6 +203,8 @@ One sentence: What are we building/fixing?
 3. **Each task verifiable** - Clear "done" criteria
 4. **Project-specific** - No copy-paste templates
 5. **Update as you go** - Mark `[x]` when complete
+6. **TDD when testable** - Use red-green-refactor step structure
+7. **Complete code in plan** - Not "add validation" but the actual code
 
 ---
 
@@ -150,3 +214,14 @@ One sentence: What are we building/fixing?
 - Adding a feature
 - Fixing a bug (if complex)
 - Refactoring multiple files
+
+---
+
+## Integration
+
+| Skill                            | Relationship                         |
+| -------------------------------- | ------------------------------------ |
+| `brainstorming`                  | Design phase before plan creation    |
+| `executing-plans`                | Executes the plan this skill creates |
+| `test-driven-development`        | TDD cycle referenced in task steps   |
+| `verification-before-completion` | Gate before marking plan complete    |

package/templates/skills/knowledge/systematic-debugging/SKILL.md

@@ -1,109 +1,214 @@
 ---
 name: systematic-debugging
-description: 4-phase systematic debugging methodology with root cause analysis and evidence-based verification. Use when debugging complex issues.
-allowed-tools: Read, Glob, Grep
+description: 4-phase root cause debugging process. Use for ANY technical issue — test failures, bugs, unexpected behavior, performance problems. ALWAYS find root cause before attempting fixes.
+version: 1.0.0
 ---
 
 # Systematic Debugging
 
-> Source: obra/superpowers
+> Adapted from obra/superpowers — integrated with agi `debugger` agent.
 
 ## Overview
-This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
 
-## 4-Phase Debugging Process
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
 
-### Phase 1: Reproduce
-Before fixing, reliably reproduce the issue.
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
 
-```markdown
-## Reproduction Steps
-1. [Exact step to reproduce]
-2. [Next step]
-3. [Expected vs actual result]
+---
+
+## The Iron Law
 
-## Reproduction Rate
-- [ ] Always (100%)
-- [ ] Often (50-90%)
-- [ ] Sometimes (10-50%)
-- [ ] Rare (<10%)
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 ```
 
-### Phase 2: Isolate
-Narrow down the source.
+If you haven't completed Phase 1, you cannot propose fixes.
 
-```markdown
-## Isolation Questions
-- When did this start happening?
-- What changed recently?
-- Does it happen in all environments?
-- Can we reproduce with minimal code?
-- What's the smallest change that triggers it?
-```
+---
 
-### Phase 3: Understand
-Find the root cause, not just symptoms.
-
-```markdown
-## Root Cause Analysis
-### The 5 Whys
-1. Why: [First observation]
-2. Why: [Deeper reason]
-3. Why: [Still deeper]
-4. Why: [Getting closer]
-5. Why: [Root cause]
-```
+## When to Use
 
-### Phase 4: Fix & Verify
-Fix and verify it's truly fixed.
+Use for **ANY** technical issue:
 
-```markdown
-## Fix Verification
-- [ ] Bug no longer reproduces
-- [ ] Related functionality still works
-- [ ] No new issues introduced
-- [ ] Test added to prevent regression
-```
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
 
-## Debugging Checklist
-
-```markdown
-## Before Starting
-- [ ] Can reproduce consistently
-- [ ] Have minimal reproduction case
-- [ ] Understand expected behavior
-
-## During Investigation
-- [ ] Check recent changes (git log)
-- [ ] Check logs for errors
-- [ ] Add logging if needed
-- [ ] Use debugger/breakpoints
-
-## After Fix
-- [ ] Root cause documented
-- [ ] Fix verified
-- [ ] Regression test added
-- [ ] Similar code checked
-```
+**Use ESPECIALLY when:**
 
-## Common Debugging Commands
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
 
-```bash
-# Recent changes
-git log --oneline -20
-git diff HEAD~5
+**Don't skip when:**
 
-# Search for pattern
-grep -r "errorPattern" --include="*.ts"
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (systematic is faster than thrashing)
 
-# Check logs
-pm2 logs app-name --err --lines 100
-```
+---
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - `git diff`, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   When system has multiple components:
+
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once → analyze evidence → identify failing component
+   ```
+
+5. **Trace Data Flow**
+   - Where does the bad value originate?
+   - What called this with the bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+1. **Find Working Examples**
+   - Locate similar working code in the same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - Read reference implementation COMPLETELY (don't skim)
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+
+### Phase 3: Hypothesis and Testing
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+### Phase 4: Implementation
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Use `test-driven-development` skill
+   - MUST exist before fixing
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new coupling in different place
+   - Fixes require "massive refactoring"
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and discuss with the user before more fix attempts.**
+
+---
+
+## Quick Reference
+
+| Phase                 | Key Activities                                         | Success Criteria            |
+| --------------------- | ------------------------------------------------------ | --------------------------- |
+| **1. Root Cause**     | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY     |
+| **2. Pattern**        | Find working examples, compare                         | Identify differences        |
+| **3. Hypothesis**     | Form theory, test minimally                            | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify                               | Bug resolved, tests pass    |
+
+---
+
+## Red Flags — STOP and Return to Phase 1
+
+If you catch yourself thinking:
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- Proposing solutions before tracing data flow
+- "One more fix attempt" (when already tried 2+)
+
+---
+
+## Common Rationalizations
+
+| Excuse                                       | Reality                                                             |
+| -------------------------------------------- | ------------------------------------------------------------------- |
+| "Issue is simple, don't need process"        | Simple issues have root causes too. Process is fast for simple bugs |
+| "Emergency, no time for process"             | Systematic debugging is FASTER than guess-and-check thrashing       |
+| "Just try this first, then investigate"      | First fix sets the pattern. Do it right from the start              |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it                    |
+| "Multiple fixes at once saves time"          | Can't isolate what worked. Causes new bugs                          |
+| "I see the problem, let me fix it"           | Seeing symptoms ≠ understanding root cause                          |
+
+---
+
+## Real-World Impact
+
+| Approach     | Time to Fix | First-Time Fix Rate | New Bugs  |
+| ------------ | ----------- | ------------------- | --------- |
+| Systematic   | 15-30 min   | ~95%                | Near zero |
+| Random fixes | 2-3 hours   | ~40%                | Common    |
+
+---
 
-## Anti-Patterns
+## Integration
 
-❌ **Random changes** - "Maybe if I change this..."
-❌ **Ignoring evidence** - "That can't be the cause"
-❌ **Assuming** - "It must be X" without proof
-❌ **Not reproducing first** - Fixing blindly
-❌ **Stopping at symptoms** - Not finding root cause
+| Skill/Agent                      | Relationship                                                      |
+| -------------------------------- | ----------------------------------------------------------------- |
+| `debugger` agent                 | Domain expertise for investigation; use this skill as its process |
+| `test-driven-development`        | Phase 4: creating failing test case                               |
+| `verification-before-completion` | Verify fix before claiming it works                               |
+| `executing-plans`                | When debugging blocks plan execution                              |