@techwavedev/agi-agent-kit 1.2.7 → 1.2.8

package/templates/skills/knowledge/test-driven-development/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: test-driven-development
+description: RED-GREEN-REFACTOR enforcement. MANDATORY for new features, bug fixes, and behavior changes. Write the test first, watch it fail, then implement.
+version: 1.0.0
+---
+
+# Test-Driven Development (TDD)
+
+> Adapted from obra/superpowers — platform-agnostic commands.
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
+
+---
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Write code before the test? **Delete it.** Start over.
+
+**No exceptions:**
+
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+
+---
+
+## When to Use
+
+**Always:**
+
+- New features
+- Bug fixes
+- Refactoring
+- Behavior changes
+
+**Exceptions (ask the user):**
+
+- Throwaway prototypes
+- Generated code
+- Configuration-only changes
+
+Thinking "skip TDD just this once"? Stop. That's rationalization.
+
+---
+
+## Red-Green-Refactor Cycle
+
+### 🔴 RED — Write Failing Test
+
+Write one minimal test showing what **should** happen.
+
+**Requirements:**
+
+- One behavior per test
+- Clear, descriptive name
+- Real code (no mocks unless unavoidable)
+
+```
+✅ test('rejects empty email with error message')
+❌ test('test1')  /  test('validates email and domain and whitespace')
+```
+
+### 🔴 Verify RED — Watch It Fail
+
+**MANDATORY. Never skip.**
+
+Run the test. Confirm:
+
+- Test **fails** (not errors — compilation errors are different from test failures)
+- Failure message is expected (feature missing, not typos)
+
+**Test passes immediately?** You're testing existing behavior. Fix the test.
+
+### 🟢 GREEN — Minimal Code
+
+Write the **simplest** code to pass the test.
+
+- Don't add features beyond what the test requires
+- Don't refactor other code
+- Don't "improve" beyond the test
+- YAGNI ruthlessly
+
+### 🟢 Verify GREEN — Watch It Pass
+
+**MANDATORY.**
+
+Run the test. Confirm:
+
+- New test passes
+- All other tests still pass
+- Output pristine (no errors, warnings)
+
+**Test fails?** Fix the code, not the test.
+
+### 🔵 REFACTOR — Clean Up
+
+After green only:
+
+- Remove duplication
+- Improve names
+- Extract helpers
+
+**Keep tests green during refactoring.** Don't add behavior.
+
+### 🔁 Repeat
+
+Next failing test for next behavior.
+
+---
+
+## Good Tests vs Bad Tests
+
+| Quality          | Good                               | Bad                                                 |
+| ---------------- | ---------------------------------- | --------------------------------------------------- |
+| **Minimal**      | One thing. "and" in name? Split it | `test('validates email and domain and whitespace')` |
+| **Clear**        | Name describes behavior            | `test('test1')`                                     |
+| **Real**         | Tests actual code                  | Tests mock behavior                                 |
+| **Shows intent** | Demonstrates desired API           | Obscures what code should do                        |
+
+---
+
+## Why Order Matters
+
+| Rationalization                        | Reality                                                                 |
+| -------------------------------------- | ----------------------------------------------------------------------- |
+| "I'll write tests after to verify"     | Tests written after pass immediately — proves nothing                   |
+| "Already manually tested"              | Manual = ad-hoc, no record, can't re-run                                |
+| "Deleting X hours of work is wasteful" | Sunk cost fallacy. Unverified code is tech debt                         |
+| "TDD is dogmatic"                      | TDD IS pragmatic: finds bugs before commit                              |
+| "Tests after achieve same goals"       | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+
+---
+
+## Common Rationalizations
+
+| Excuse                                 | Reality                                                    |
+| -------------------------------------- | ---------------------------------------------------------- |
+| "Too simple to test"                   | Simple code breaks. Test takes 30 seconds                  |
+| "I'll test after"                      | Tests passing immediately prove nothing                    |
+| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete |
+| "Need to explore first"                | Fine. Throw away exploration, start with TDD               |
+| "Test hard = skip it"                  | Hard to test = hard to use. Simplify the design            |
+| "TDD will slow me down"                | TDD is faster than debugging. Always                       |
+| "Existing code has no tests"           | You're improving it. Add tests for what you touch          |
+
+---
+
+## Red Flags — STOP and Start Over
+
+- Code written before test
+- Test passes immediately (never saw it fail)
+- Can't explain why the test failed
+- Rationalizing "just this once"
+- "Keep as reference" or "adapt existing code"
+- "This is different because..."
+
+**All of these mean: Delete code. Start over with TDD.**
+
+---
+
+## Bug Fix Example
+
+**Bug:** Empty email accepted
+
+**🔴 RED:**
+
+```
+test('rejects empty email') → assert result.error == 'Email required'
+```
+
+**🔴 Verify RED:**
+
+```
+$ run tests → FAIL: expected 'Email required', got undefined ✓
+```
+
+**🟢 GREEN:**
+
+```
+if not data.email: return error('Email required')
+```
+
+**🟢 Verify GREEN:**
+
+```
+$ run tests → PASS ✓
+```
+
+---
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass
+- [ ] Output pristine (no errors, warnings)
+- [ ] Tests use real code (mocks only if unavoidable)
+- [ ] Edge cases and errors covered
+
+Can't check all boxes? You skipped TDD. Start over.
+
+---
+
+## When Stuck
+
+| Problem                | Solution                                                      |
+| ---------------------- | ------------------------------------------------------------- |
+| Don't know how to test | Write the wished-for API. Write assertion first. Ask the user |
+| Test too complicated   | Design too complicated. Simplify the interface                |
+| Must mock everything   | Code too coupled. Use dependency injection                    |
+| Test setup is huge     | Extract helpers. Still complex? Simplify the design           |
+
+---
+
+## Integration
+
+| Skill                            | Relationship                               |
+| -------------------------------- | ------------------------------------------ |
+| `executing-plans`                | TDD cycle used during task implementation  |
+| `systematic-debugging`           | Bug found → write failing test → TDD cycle |
+| `verification-before-completion` | Gate before claiming tests pass            |
+| `plan-writing`                   | Plans include TDD step structure           |

package/templates/skills/knowledge/verification-before-completion/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: verification-before-completion
+description: Universal verification gate. MANDATORY before any completion claim, success assertion, commit, or PR. Evidence before claims, always.
+version: 1.0.0
+---
+
+# Verification Before Completion
+
+> Adapted from obra/superpowers — integrated with agi verification scripts.
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+---
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+---
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = unverified, not verified
+```
+
+---
+
+## Evidence Requirements
+
+| Claim                 | Requires                        | Not Sufficient                 |
+| --------------------- | ------------------------------- | ------------------------------ |
+| Tests pass            | Test command output: 0 failures | Previous run, "should pass"    |
+| Linter clean          | Linter output: 0 errors         | Partial check, extrapolation   |
+| Build succeeds        | Build command: exit 0           | Linter passing, logs look good |
+| Bug fixed             | Test original symptom: passes   | Code changed, assumed fixed    |
+| Regression test works | Red-green cycle verified        | Test passes once               |
+| Agent completed       | VCS diff shows changes          | Agent reports "success"        |
+| Requirements met      | Line-by-line checklist          | Tests passing                  |
+
+---
+
+## Integration with Agi Scripts
+
+When available, use the project's verification scripts:
+
+| Verification  | Script             | Command                                                               |
+| ------------- | ------------------ | --------------------------------------------------------------------- |
+| Full audit    | `checklist.py`     | `python .agent/scripts/checklist.py .`                                |
+| Security scan | `security_scan.py` | `python .agent/skills/vulnerability-scanner/scripts/security_scan.py` |
+| Lint check    | `lint_runner.py`   | `python .agent/skills/lint-and-validate/scripts/lint_runner.py`       |
+| Tests         | `test_runner.py`   | `python .agent/skills/testing-patterns/scripts/test_runner.py`        |
+| UX audit      | `ux_audit.py`      | `python .agent/skills/frontend-design/scripts/ux_audit.py`            |
+
+> If no project scripts exist, use the project's native test/build commands.
+
+---
+
+## Red Flags — STOP
+
+If you catch yourself thinking:
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without verification
+- Trusting agent success reports without checking
+- Relying on partial verification
+- Thinking "just this once"
+- **ANY wording implying success without having run verification**
+
+---
+
+## Rationalization Prevention
+
+| Excuse                                  | Reality                   |
+| --------------------------------------- | ------------------------- |
+| "Should work now"                       | RUN the verification      |
+| "I'm confident"                         | Confidence ≠ evidence     |
+| "Just this once"                        | No exceptions             |
+| "Linter passed"                         | Linter ≠ compiler ≠ tests |
+| "Agent said success"                    | Verify independently      |
+| "Partial check is enough"               | Partial proves nothing    |
+| "Different words so rule doesn't apply" | Spirit over letter        |
+
+---
+
+## Verification Patterns
+
+**Tests:**
+
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Build:**
+
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+---
+
+## When to Apply
+
+**ALWAYS before:**
+
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+---
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.