@complexthings/superpowers-agent 8.1.0

package/skills/testing/testing-anti-patterns/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: testing-anti-patterns
+description: Identifies and corrects dangerous testing anti-patterns including testing mock behavior instead of real behavior, adding test-only methods to production classes, mocking without understanding dependencies, writing brittle implementation-coupled tests, and sharing mutable state across tests. Use when writing or changing tests, adding mocks, designing test fixtures, debugging flaky tests, or tempted to add test-only methods to production code.
+metadata:
+  version: 1.2.0
+---
+
+# Testing Anti-Patterns
+
+## Overview
+
+Tests must verify real behavior, not mock behavior. Mocks isolate; they are not the thing being tested.
+
+**Core principle:** Test what the code *does*, not how it *does it* or what the mocks *do*.
+
+**Following strict TDD prevents most of these anti-patterns.**
+
+## The Iron Laws
+
+1. NEVER test mock behavior
+2. NEVER add test-only methods to production classes
+3. NEVER mock without understanding dependencies
+4. NEVER couple tests to implementation details — test contracts, not internals
+
+## Anti-Pattern 1: Testing Mock Behavior
+
+**The violation:**
+```typescript
+// ❌ BAD: Testing that the mock exists, not real behavior
+test('renders sidebar', () => {
+  render(<Page />);
+  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+});
+```
+
+**Why this is wrong:**
+- Verifies the mock is present, not that the component works
+- Passes when mock exists, fails when mock changes — irrelevant to behavior
+- `getByTestId` is an implementation artifact; prefer semantic queries
+
+**The fix:**
+```typescript
+// ✅ GOOD: Test real behavior; query by role, not by test ID
+test('renders sidebar', () => {
+  render(<Page />);  // Don't mock sidebar if avoidable
+  expect(screen.getByRole('navigation')).toBeInTheDocument();
+});
+
+// If sidebar must be mocked for isolation:
+// Assert Page's behavior, not the mock's presence
+```
+
+**When you see an assertion on a `*-mock` testId:** Ask "Am I testing real component behavior or just mock existence?" If the latter, delete the assertion.
+
+## Anti-Pattern 2: Test-Only Methods in Production
+
+**The violation:**
+```typescript
+// ❌ BAD: destroy() only called from tests
+class Session {
+  async destroy() {  // Looks like a production API!
+    await this._workspaceManager?.destroyWorkspace(this.id);
+  }
+}
+afterEach(() => session.destroy());
+```
+
+**Why this is wrong:**
+- Pollutes production API with test concerns
+- Dangerous if called accidentally in production
+- Violates YAGNI and separation of concerns
+
+**The fix:**
+```typescript
+// ✅ GOOD: Cleanup lives in test utilities
+// Session has no destroy() in production
+
+// In test-utils/session-helpers.ts
+export async function cleanupSession(session: Session) {
+  const workspace = session.getWorkspaceInfo();
+  if (workspace) {
+    await workspaceManager.destroyWorkspace(workspace.id);
+  }
+}
+afterEach(() => cleanupSession(session));
+```
+
+**Before adding any method to a production class:** Ask "Is this only used by tests?" If yes, put it in test utilities.
+
+## Anti-Pattern 3: Mocking Without Understanding
+
+**The violation:**
+```typescript
+// ❌ BAD: Mock kills the side effect this test actually depends on
+test('detects duplicate server', () => {
+  vi.mock('ToolCatalog', () => ({
+    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+  }));
+  await addServer(config);
+  await addServer(config);  // Should throw — but won't, mock prevented config write
+});
+```
+
+**Why this is wrong:**
+- Mocked method had a side effect the test depended on
+- Over-mocking "to be safe" hides the real behavior
+- Test passes for the wrong reason or fails mysteriously
+
+**The fix:**
+```typescript
+// ✅ GOOD: Mock at the correct level — the slow/external part only
+test('detects duplicate server', () => {
+  vi.mock('MCPServerManager'); // Mock slow startup, not config logic
+  await addServer(config);    // Config written ✓
+  await addServer(config);    // Duplicate detected ✓
+});
+```
+
+**Before mocking any method:**
+1. Ask "What side effects does the real method have?"
+2. Ask "Does this test depend on any of those side effects?"
+3. Run the test with the real implementation first; observe what it needs
+4. THEN add minimal mocking at the lowest appropriate level
+
+**Red flags:** "I'll mock this to be safe" · "This might be slow, better mock it" · Mocking a high-level method without reading its source
+
+## Anti-Pattern 4: Incomplete Mocks
+
+**The violation:**
+```typescript
+// ❌ BAD: Only mock the fields you think you need
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' }
+  // Missing: metadata.requestId that downstream code reads
+};
+// Breaks silently when code accesses response.metadata.requestId
+```
+
+**Why this is wrong:**
+- Partial mocks hide structural assumptions
+- Silent failures when downstream code accesses unmocked fields
+- Tests pass in isolation; integration fails against the real API
+
+**The fix:**
+```typescript
+// ✅ GOOD: Mirror the complete real API structure
+const mockResponse = {
+  status: 'success',
+  data: { userId: '123', name: 'Alice' },
+  metadata: { requestId: 'req-789', timestamp: 1234567890 }
+  // All fields the real API returns
+};
+```
+
+**Before creating a mock response:** Examine the actual API docs or real response. Include ALL fields downstream code might access. If uncertain, include all documented fields.
+
+## Anti-Pattern 5: Brittle Implementation-Coupled Tests
+
+**The violation:**
+```typescript
+// ❌ BAD: Tests internal method call order, not the outcome
+test('calculates total', () => {
+  const spy = vi.spyOn(calculator, '_applyDiscount');
+  calculator.total(items);
+  expect(spy).toHaveBeenCalledWith(items, 0.1);  // Tests HOW, not WHAT
+});
+```
+
+**Why this is wrong:**
+- Tests lock in implementation details, not behavioral contracts
+- A valid refactor (same output, different internals) breaks the test
+- *"Coupling to the implementation also interferes with refactoring"* — Fowler
+- Discourages clean code evolution
+
+**The fix:**
+```typescript
+// ✅ GOOD: Test the observable outcome/state
+test('applies 10% discount to qualifying items', () => {
+  const result = calculator.total(qualifyingItems);
+  expect(result).toBe(expectedDiscountedTotal);
+  // Don't care HOW the discount was applied
+});
+```
+
+**Rule of thumb:** A test should survive any refactor that preserves the public contract. If renaming a private method breaks a test, the test is wrong.
+
+## Anti-Pattern 6: Shared Mutable State Between Tests
+
+**The violation:**
+```typescript
+// ❌ BAD: State leaks between tests; order-dependent results
+let store: AppStore;
+beforeAll(() => {
+  store = createStore();  // Shared across all tests
+});
+
+test('adds item', () => {
+  store.add({ id: 1 });
+  expect(store.count()).toBe(1);
+});
+
+test('removes item', () => {
+  store.remove(1);  // Assumes 'adds item' ran first — flaky!
+  expect(store.count()).toBe(0);
+});
+```
+
+**Why this is wrong:**
+- Tests become order-dependent — pass in one order, fail in another
+- Debugging requires running the full suite to reproduce
+- Violates test isolation; each test should be a self-contained unit
+
+**The fix:**
+```typescript
+// ✅ GOOD: Fresh state for each test
+let store: AppStore;
+beforeEach(() => {
+  store = createStore();  // Reset before each test
+});
+
+test('adds item', () => {
+  store.add({ id: 1 });
+  expect(store.count()).toBe(1);
+});
+
+test('removes item', () => {
+  store.add({ id: 1 });   // Set up own preconditions
+  store.remove(1);
+  expect(store.count()).toBe(0);
+});
+```
+
+**Red flags:** `beforeAll` modifying state that tests mutate · Tests that only pass when run in a specific order · Cleanup logic in `afterAll` that tests depend on
+
+## Anti-Pattern 7: Tests as Afterthought
+
+**The violation:**
+```
+✅ Implementation complete
+❌ No tests written
+"Ready for testing"
+```
+
+Testing is part of implementation, not optional follow-up. Claiming "complete" without tests is incomplete.
+
+**The fix:** TDD cycle — write failing test → implement to pass → refactor → then claim complete.
+
+## When Mocks Become Too Complex
+
+**Warning signs:**
+- Mock setup is longer than test logic
+- Mocking everything just to make the test compile
+- Mocks missing methods that real components have
+- Test breaks when mock internals change, not when behavior changes
+
+**Consider:** Integration tests with real components are often simpler than maintaining complex mocks.
+
+## TDD Prevents These Anti-Patterns
+
+1. **Write test first** → Forces clarity on what you're actually testing
+2. **Watch it fail** → Confirms the test verifies real behavior, not mock presence
+3. **Minimal implementation** → No test-only methods added speculatively
+4. **Real dependencies visible** → You see what the test needs before mocking anything
+
+**If you're testing mock behavior, you violated TDD** — mocks were added without watching the test fail against real code first.
+
+## Quick Reference
+
+| Anti-Pattern | Harm | Fix |
+|---|---|---|
+| Assert on mock elements | Tests mock, not behavior | Test real component or unmock it |
+| Test-only methods in production | Pollutes production API | Move to test utilities |
+| Mock without understanding | Hides bugs, wrong behavior | Understand first, mock minimally |
+| Incomplete mocks | Silent failures downstream | Mirror full real API structure |
+| Implementation-coupled tests | Break on valid refactors | Test contracts, not internals |
+| Shared mutable state | Flaky, order-dependent | Fresh state per test (`beforeEach`) |
+| Tests as afterthought | False completeness | TDD — tests first |
+
+## Red Flags Checklist
+
+- [ ] Assertion checks for `*-mock` testIds
+- [ ] Methods only called in test files exist on production classes
+- [ ] Mock setup is >50% of the test
+- [ ] Test fails when you remove the mock (but not the real behavior)
+- [ ] Can't explain why a mock is needed
+- [ ] Mocking "just to be safe"
+- [ ] Test breaks when implementation changes but output is the same
+- [ ] Tests only pass when run in a specific order
+- [ ] `beforeAll` modifies state that individual tests mutate
+
+## The Bottom Line
+
+**Mocks isolate; they are not the thing being tested.**
+
+Test the *contract* (observable outputs and state), not the *mechanism* (how it's implemented internally).
+
+If TDD reveals you're testing mock behavior or internal details, you've gone wrong. Fix: test real behavior or question whether you need the mock at all.

package/skills/testing/testing-anti-patterns/skill.json

@@ -0,0 +1,9 @@
+{
+    "version": "1.2.0",
+    "name": "superpowers:testing/testing-anti-patterns",
+    "title": "Testing Anti-Patterns",
+    "aliases": [
+        "testing-anti-patterns",
+        "testing/testing-anti-patterns"
+    ]
+}

package/skills/testing/verification-before-completion/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+metadata:
+  version: 2.0.0
+  when_to_use: before any completion claim, commit, PR, or task handoff
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without running verification is not efficiency — it is dishonesty.
+
+**Core principle:** Evidence before claims, always.
+
+The rule applies to the spirit, not just the letter. Any phrasing that implies success without verification evidence violates it.
+
+## 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
+
+```mermaid
+flowchart LR
+    CLAIM[About to claim success?] --> ID[1. Identify: what command proves this?]
+    ID --> RUN[2. Run: execute the FULL command, fresh]
+    RUN --> READ[3. Read: full output, check exit code]
+    READ --> MATCH{4. Output confirms claim?}
+    MATCH -->|No| STATE[State actual status with evidence]
+    MATCH -->|Yes| MAKE[5. Make claim WITH evidence]
+```
+
+**Step-by-step:**
+
+1. **IDENTIFY**: What exact command proves this claim? (see table below)
+2. **RUN**: Execute the full command fresh — not a cached result, not a partial run
+3. **READ**: Read the complete output and check the exit code
+4. **VERIFY**: Does the output confirm the claim?
+   - If NO → State actual status with evidence
+   - If YES → State claim WITH that evidence
+5. **ONLY THEN**: Make the claim
+
+Skip any step = asserting without evidence.
+
+## What to Run for Each Claim
+
+| Claim | Required command output | Not sufficient |
+|-------|------------------------|----------------|
+| Tests pass | Test runner: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter: 0 errors/warnings | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs "look OK" |
+| Bug fixed | Original symptom: test passes | Code changed, assumed fixed |
+| Regression test works | Full red→green cycle verified | Test passes once |
+| Agent task completed | VCS diff shows expected changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist verified | Tests passing |
+| Types valid | Type checker: 0 errors | Code compiles |
+| No regressions | Full test suite: 0 new failures | Feature tests pass |
+
+## Finding the Right Verification Command
+
+Not sure what command to run? Start here:
+
+```bash
+# Common test runners
+npm test                    # Node.js (Jest, Vitest, Mocha)
+python -m pytest            # Python
+cargo test                  # Rust
+go test ./...               # Go
+bundle exec rspec           # Ruby
+
+# Common linters/type checkers
+npm run lint                # JS/TS (ESLint)
+npx tsc --noEmit            # TypeScript types
+mypy .                      # Python types
+cargo clippy                # Rust
+golangci-lint run           # Go
+
+# Common build commands
+npm run build               # JS/TS
+cargo build                 # Rust
+go build ./...              # Go
+
+# Check package.json/Makefile for project-specific commands
+grep -A20 '"scripts"' package.json
+grep "^[a-z]" Makefile
+```
+
+When uncertain, check the project README, `Makefile`, or `package.json` `scripts` section.
+
+## Before a Commit or PR
+
+Run all of these, in order, before committing or opening a PR:
+
+```
+1. [ ] Tests pass (full suite, not just changed files)
+2. [ ] No lint errors
+3. [ ] No type errors
+4. [ ] Build succeeds
+5. [ ] Original bug/requirement is demonstrably addressed
+6. [ ] No unintended side effects in related tests
+```
+
+Every box must be checked with actual command output, not assumption.
+
+## Key Patterns
+
+**Tests:**
+
+<Good>
+```bash
+$ npm test
+PASS: 34 tests, 0 failures
+
+# Now you can say: "All 34 tests pass"
+```
+</Good>
+
+<Bad>
+```
+"Should pass now" / "Looks correct" / "I'm confident it works"
+```
+</Bad>
+
+---
+
+**TDD Regression Test (Red-Green Verification):**
+
+<Good>
+```bash
+# 1. Write test, confirm it passes with fix in place
+$ npm test feature.test.ts
+PASS
+
+# 2. Temporarily revert the fix
+# 3. Confirm test now FAILS (proves test catches the bug)
+$ npm test feature.test.ts
+FAIL: expected X, got Y
+
+# 4. Restore fix, confirm passes again
+$ npm test feature.test.ts
+PASS
+```
+</Good>
+
+<Bad>
+```
+"I've written a regression test" (without verifying the red state)
+```
+</Bad>
+
+---
+
+**Requirements checklist:**
+
+<Good>
+```
+1. Re-read the plan/requirements document
+2. For each requirement item:
+   - Write down how you'll verify it
+   - Run that verification
+   - Check it off, or flag it as a gap
+3. Report: "X of Y requirements verified, Z gaps found"
+```
+</Good>
+
+<Bad>
+```
+"Tests pass, so the phase is complete"
+```
+</Bad>
+
+---
+
+**Agent delegation:**
+
+<Good>
+```bash
+# Agent reports "done"
+$ git diff HEAD~1   # What actually changed?
+$ npm test          # Does it still pass?
+```
+</Good>
+
+<Bad>
+```
+Trust the agent's success report without independent verification
+```
+</Bad>
+
+## When Verification Is Slow
+
+If the full test suite takes a long time:
+
+1. **Run the specific test file first** — fast feedback loop, catches most issues
+2. **Run the full suite before commit** — required, not optional
+3. **Never skip the full suite before a PR** — no exceptions
+
+Partial verification is acceptable for iteration. It is never acceptable as the final gate before claiming completion.
+
+## Red Flags — Stop
+
+Encountering any of these means you haven't verified yet:
+
+- Using "should", "probably", "seems to", "looks like"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without having run all checks
+- Trusting agent success reports without independent verification
+- Using a previous run's output as proof
+- **ANY wording that implies success without evidence from this session**
+
+## 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 for final gate |
+| "Different words, rule doesn't apply" | Spirit over letter |
+| "I already checked mentally" | Mental simulation ≠ execution |
+| "The CI will catch it" | Your job is to catch it before CI |
+
+## Why This Matters
+
+Every shortcut here has a known failure mode:
+
+- Undefined functions ship → crashes in production
+- Missing requirements ship → incomplete features reach users  
+- False completion claims break trust between collaborators
+- Time wasted on redirects and rework after false "done" reports
+
+The verification step costs seconds. The rework from skipping it costs hours.
+
+## The Bottom Line
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/skills/testing/verification-before-completion/skill.json

@@ -0,0 +1,10 @@
+{
+  "version": "1.0.0",
+  "name": "testing/verification-before-completion",
+  "title": "verification-before-completion",
+  "helpers": [],
+  "aliases": [
+    "testing/verification-before-completion",
+    "verification-before-completion"
+  ]
+}

package/skills/using-a-skill/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: using-a-skill
+description: Use when you need to load and apply a specific skill from system, personal, or project locations - automatically handles priority resolution
+---
+
+# Using a Skill
+
+## Overview
+
+Load and apply a specific skill by name. The system automatically finds the skill across all locations and applies the highest-priority version.
+
+## When to Use
+
+Use this skill when you:
+- Need to apply a specific skill to your current task
+- Want to reference a skill's detailed guidance
+- Need to load supporting files or examples from a skill
+- Are following another skill that references a sub-skill
+
+## How to Use
+
+**Basic usage:**
+```bash
+superpowers-agent use-skill <skill-name>
+```
+
+**Examples:**
+```bash
+# Load a system skill
+superpowers-agent use-skill superpowers:brainstorming
+
+# Load a Claude skill
+superpowers-agent use-skill claude:persistent-planning
+
+# Load a project or personal skill (no prefix)
+superpowers-agent use-skill my-custom-skill
+```
+
+## Skill Naming and Prefixes
+
+**Prefixes indicate source:**
+- `superpowers:skill-name` - System skill from `~/.agents/superpowers/skills/`
+- `claude:skill-name` - Claude skill from `.claude/skills/`
+- `skill-name` (no prefix) - Project or personal skill
+
+**Priority resolution (when no prefix specified):**
+1. Project skills (`.agents/skills/`) - highest priority
+2. Claude skills (`.claude/skills/`)
+3. Personal skills (`~/.agents/skills/`)
+4. System skills (`~/.agents/superpowers/skills/`) - lowest priority
+
+## What You Get
+
+When you load a skill, you receive:
+- The skill's main content (SKILL.md)
+- Reference to supporting files directory
+- Frontmatter metadata (name, description, when to use)
+
+## Skill References
+
+Skills often reference other skills using patterns like:
+- `**REQUIRED SUB-SKILL:** Use superpowers:skill-name`
+- `**REQUIRED BACKGROUND:** You MUST understand superpowers:skill-name`
+
+When you see these, load the referenced skill before proceeding.
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `use-skill superpowers:<name>` | Load system skill |
+| `use-skill claude:<name>` | Load Claude skill |
+| `use-skill <name>` | Load with auto-priority |
+| `find-skills` | See all available skills |
+
+## Supporting Files
+
+Skills may include supporting files in their directory:
+- Example code (`.ts`, `.js`, `.py`, etc.)
+- Reference documentation (`.md` files)
+- Reusable tools (scripts, templates)
+
+The skill header shows the directory path where these files are located.
+
+## Common Mistakes
+
+**Don't:**
+- Force-load skills with `@` syntax (wastes context)
+- Skip loading referenced skills (breaks workflows)
+- Assume you remember skill content (skills evolve, reload them)
+
+**Do:**
+- Load skills on-demand when needed
+- Follow cross-references to sub-skills
+- Check `find-skills` if you can't find a skill
+
+## Related Skills
+
+- **finding-skills** - Discover available skills
+- **using-superpowers** - Introduction to the skills system
+- **writing-skills** - Create new skills

package/skills/using-a-skill/skill.json

@@ -0,0 +1,8 @@
+{
+    "version": "1.0.0",
+    "name": "superpowers:using-a-skill",
+    "title": "using-a-skill",
+    "aliases": [
+        "using-a-skill"
+    ]
+}