@complexthings/superpowers-agent 9.2.1 → 10.0.0

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

@@ -1,298 +0,0 @@
----
-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

@@ -1,9 +0,0 @@
-{
-    "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

@@ -1,246 +0,0 @@
----
-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

@@ -1,10 +0,0 @@
-{
-  "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

@@ -1,101 +0,0 @@
----
-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

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