continuous-improvement 3.1.0 → 3.9.1

package/skills/superpowers.md

@@ -0,0 +1,219 @@
+---
+name: superpowers
+tier: companion
+description: "Law activator for the 7 Laws of AI Agent Discipline. Unified four-source dispatcher — routes tasks to the correct Law-aligned specialist across the CI plugin (tdd-workflow, verification-loop, gateguard, ralph, deploy-receipt) and four registered upstream companions (Obra superpowers, addy agent-skills, ruflo-swarm, oh-my-claudecode) so the right discipline fires automatically instead of the agent skipping a step. Product-management coverage comes from phuryn/pm-skills via an out-of-band marketplace install (see docs/THIRD_PARTY.md). Not a peer skill — a dispatcher for the others."
+origin: https://github.com/obra/superpowers
+---
+
+# Superpowers — Mandatory Agent Workflows (Five-Source Dispatcher)
+
+Superpowers enforces a structured development workflow. Skills activate automatically when their trigger conditions are met. This is not optional guidance — it is mandatory workflow.
+
+## Philosophy
+
+AI agents skip steps, guess, and declare "done" without verifying. Superpowers blocks this by making workflow stages explicit and enforced.
+
+## What changed in v3.8.0
+
+The dispatcher now routes across **four registered marketplaces** instead of relying on Obra installed separately. All four are installable from one marketplace entry:
+
+```
+/plugin install superpowers@continuous-improvement       # Obra's 14 workflow skills
+/plugin install agent-skills@continuous-improvement      # Addy's 21 SDLC skills
+/plugin install ruflo-swarm@continuous-improvement       # Agent swarm + Monitor stream
+/plugin install oh-my-claudecode@continuous-improvement  # 39 skills + 19 agents
+```
+
+The CI plugin (this dispatcher + `tdd-workflow`, `verification-loop`, `gateguard`, `ralph`, `deploy-receipt`, etc.) installs by default. The four companions are opt-in — install only what you need.
+
+Product-management coverage (PRD, OKRs, personas, GTM, etc.) is provided by `phuryn/pm-skills` via an out-of-band Claude Code marketplace install:
+
+```
+claude plugin marketplace add phuryn/pm-skills
+claude plugin install pm-toolkit@pm-skills
+claude plugin install pm-product-strategy@pm-skills
+claude plugin install pm-product-discovery@pm-skills
+claude plugin install pm-market-research@pm-skills
+claude plugin install pm-data-analytics@pm-skills
+claude plugin install pm-marketing-growth@pm-skills
+claude plugin install pm-go-to-market@pm-skills
+claude plugin install pm-execution@pm-skills
+```
+
+See `docs/THIRD_PARTY.md` for plugin-by-plugin scope.
+
+## The Basic Workflow
+
+| Order | Skill | When It Activates |
+|-------|-------|-------------------|
+| 1 | **brainstorming** | Before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. |
+| 2 | **using-git-worktrees** | After design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline. |
+| 3 | **writing-plans** | With approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps. |
+| 4 | **subagent-driven-development** or **executing-plans** | With plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints. |
+| 5 | **test-driven-development** | During implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests. |
+| 6 | **requesting-code-review** | Between tasks. Reviews against plan, reports issues by severity. Critical issues block progress. |
+| 7 | **finishing-a-development-branch** | When tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree. |
+| 8 | **deploy-receipt** | When the deploy branch auto-deploys (Railway / Cloudflare Workers / Vercel / Netlify / Fly.io / etc.). Verifies deployed SHA matches merge SHA and healthcheck returns 200. Until the receipt is COMPLETE the merge is not reported as done. |
+
+The agent checks for relevant skills before any task. These are mandatory workflows, not suggestions.
+
+## Four-Source Routing Table
+
+When a task trigger fires, the dispatcher resolves to the first available skill in the preference chain. Order = preference order. Items prefixed with `ci:` are bundled in this plugin; others are namespaced by their installed plugin name.
+
+| Trigger | Law | Preferred → Fallback chain |
+|---|---|---|
+| Write a failing test before code | 3+4 | `ci:tdd-workflow` → `superpowers:test-driven-development` → `agent-skills:test-driven-development` |
+| Verify before declaring done | 4 | `ci:verification-loop` → `superpowers:verification-before-completion` |
+| Block edit until investigation present | 1 | `ci:gateguard` (no equivalents) |
+| Diagnose root cause across layers | 6 | `superpowers:systematic-debugging` → `agent-skills:debugging-and-error-recovery` |
+| Refine vague request into design | 2 | `superpowers:brainstorming` → `agent-skills:idea-refine` |
+| Decompose plan into atomic tasks | 2 | `superpowers:writing-plans` → `agent-skills:planning-and-task-breakdown` → `ci:planning-with-files` |
+| Execute plan with checkpoints | 3+6 | `superpowers:executing-plans` → `agent-skills:incremental-implementation` |
+| Spawn fresh subagent per task | 3 | `superpowers:subagent-driven-development` → `superpowers:dispatching-parallel-agents` |
+| Fan out N parallel agents on isolated worktrees | 3 | `superpowers:dispatching-parallel-agents` → `ruflo-swarm:swarm-init` |
+| Stream live observation of long agent runs | 4 | `ruflo-swarm:monitor-stream` (only source) |
+| Isolate work on a new branch | 3 | `superpowers:using-git-worktrees` (only source) |
+| Decide merge / PR / discard at branch end | 3+4 | `superpowers:finishing-a-development-branch` → `agent-skills:shipping-and-launch` |
+| Pre-review checklist before requesting review | 4 | `superpowers:requesting-code-review` → `agent-skills:code-review-and-quality` |
+| Respond to reviewer feedback | 4 | `superpowers:receiving-code-review` |
+| Verify deployed SHA matches merge SHA | 4 | `ci:deploy-receipt` (only source) |
+| Audit repo / MCP / env at session start | 1 | `ci:workspace-surface-audit` (only source) |
+| Run autonomous PRD loop | 6 | `ci:ralph` → `oh-my-claudecode:ralph` (heavy overlap; prefer CI) |
+| Audit-then-execute production fix sweep | all | `ci:proceed-with-the-recommendation` (only source) |
+| Spec-first contract before implementation | 2 | `agent-skills:spec-driven-development` (only source) |
+| Source-first reading before writing | 1 | `agent-skills:source-driven-development` (only source) |
+| Curate the right context window | 1 | `agent-skills:context-engineering` → `ci:context-budget` |
+| Simplify code, remove duplication | 6 | `agent-skills:code-simplification` → `simplify` |
+| Security review for auth/input/secrets | 4 | `agent-skills:security-and-hardening` → `security-review` |
+| Browser-level visual regression | 4 | `oh-my-claudecode:visual-verdict` (only source) |
+| Reflect after session, extract patterns | 5+7 | `ci:learn-eval` → `oh-my-claudecode:retrospective` |
+| Long autonomous run with quality gates | 6 | `oh-my-claudecode:ultrawork` → `ci:ralph` |
+| Coordinator role for staged hand-off | 3 | `ruflo-swarm:agents/coordinator` (when ruflo installed) |
+| Product-management work (PRD, OKRs, personas, GTM, growth, market research, analytics) | 1+2+5 | Install `phuryn/pm-skills` via Claude Code marketplace — see docs/THIRD_PARTY.md. Eight installable plugins (`pm-toolkit`, `pm-product-strategy`, `pm-product-discovery`, `pm-market-research`, `pm-data-analytics`, `pm-marketing-growth`, `pm-go-to-market`, `pm-execution`) cover the full lifecycle. Out of band — not a `/plugin install <name>@continuous-improvement` target. |
+
+When no installed plugin in the chain resolves, the dispatcher falls back to the inline protocols below (Test-Driven Development, Brainstorming, Plan Format, etc.) so the workflow still works on a clean install.
+
+## Stacked-PR Plan Precondition (≥3 files)
+
+Any change touching three or more files — across `skills/`, `src/`, `bin/`, `commands/`, or any combination — must produce a stacked-PR plan as a precondition to the first edit landing. The 28-day usage report shows a clean correlation: sessions that opened with a stacked-PR plan landed at `fully_achieved`; sessions that began as a single big-bang multi-file edit landed at `partially_achieved` (landing-page dark theme, market-data-hub wiring, RAG misrouting). Single-concern PRs are the lever that closes that gap.
+
+The required plan output has four components, in this order:
+
+1. **Per-PR table** — title, scope (files), test strategy, merge order. One row per PR.
+2. **Dependency graph** — which PRs depend on which (or "independent" if none).
+3. **Worktree per PR** — branch name + base commit. Sequential by default; parallel only when items share no state.
+4. **Out-of-scope list** — anything explicitly NOT in the train. Drive-by temptations get logged here, not implemented.
+
+The plan ships as the FIRST commit of the train's first PR (under `docs/plans/YYYY-MM-DD-<slug>.md`) and is cited by every subsequent commit it produces.
+
+### When this rule does NOT fire
+
+The threshold targets multi-concern feature work, not high-volume mechanical changes. The rule does NOT fire on:
+
+- **Markdown-only commits** — README, CHANGELOG, docs/ updates that touch many files but ship one concern.
+- **Lockfile-only commits** — `package-lock.json`, `pnpm-lock.yaml`, `Cargo.lock`, etc. updated in isolation by a dependency bump.
+- **Generated-only commits** — output of `npm run build`, `tsc`, codemod sweeps, or any tool whose input is one source file and whose output is many derived files. The source change is what counts toward the threshold; the regenerated artifacts ride free.
+- **Vendor-snapshot refreshes** — `third-party/<name>/` updated by a documented `bin/refresh-third-party.mjs` driver. The single source of change is the upstream SHA bump.
+- **Skill-mirror sync commits** — `skills/<name>.md` + `plugins/continuous-improvement/skills/<name>/SKILL.md` count as one file pair, not two, since the CONTRIBUTING.md skill mirror rule treats them as the same concern.
+
+If you are unsure whether the rule applies, the fall-through default is to write the plan. A 30-line plan doc is cheap; a stranded big-bang edit is expensive.
+
+## Skill Library
+
+### Testing
+- **test-driven-development** — RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)
+
+### Debugging
+- **systematic-debugging** — 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
+- **verification-before-completion** — Ensure it's actually fixed
+
+### Collaboration
+- **brainstorming** — Socratic design refinement
+- **writing-plans** — Detailed implementation plans
+- **executing-plans** — Batch execution with checkpoints
+- **dispatching-parallel-agents** — Concurrent subagent workflows
+- **requesting-code-review** — Pre-review checklist
+- **receiving-code-review** — Responding to feedback
+- **using-git-worktrees** — Parallel development branches
+- **finishing-a-development-branch** — Merge/PR decision workflow
+- **subagent-driven-development** — Fast iteration with two-stage review (spec compliance, then code quality)
+
+### Deployment Verification
+- **deploy-receipt** — Closes the merge-to-production gap on auto-deploy targets (CI-side companion to `finishing-a-development-branch`)
+
+### Meta
+- **writing-skills** — Create new skills following best practices (includes testing methodology)
+- **using-superpowers** — Introduction to the skills system
+
+## Test-Driven Development (Mandatory)
+
+```
+RED: Write failing test → Watch it fail
+GREEN: Write minimal code → Watch it pass
+REFACTOR: Improve while staying green → Commit
+```
+
+Code written before tests is deleted. No exceptions.
+
+## Brainstorming Protocol
+
+When given a vague request:
+
+1. Ask clarifying questions
+2. Explore 2-3 alternative approaches
+3. Present design in sections
+4. Wait for explicit approval before proceeding
+
+## Plan Format
+
+Every task in a plan must include:
+
+```yaml
+- task: "Specific action"
+  file: "exact/path/to/file.ext"
+  code: "Complete implementation"
+  verify: "How to confirm it works"
+  estimate: "2-5 minutes"
+```
+
+## Code Review Severity
+
+| Level | Action |
+|-------|--------|
+| Critical | Blocks progress. Must fix before continuing. |
+| Warning | Should fix. Note and continue. |
+| Info | Noted for later. No action required. |
+
+## Subagent Development
+
+Two-stage review for every task:
+
+1. **Spec compliance** — Does it match the plan?
+2. **Code quality** — Is it clean, tested, and maintainable?
+
+Both must pass. Fresh subagent per task prevents context pollution.
+
+## Git Worktrees
+
+Each feature gets an isolated workspace:
+
+```bash
+git worktree add -b feature-name ../feature-name
+```
+
+Clean separation, parallel development, easy cleanup.
+
+## Using Superpowers
+
+Superpowers skills activate when their trigger conditions are detected. The dispatcher resolves each trigger through the five-source routing table above:
+
+- "Create a feature" → `superpowers:brainstorming` → `superpowers:writing-plans` → `superpowers:executing-plans`
+- "Fix this bug" → `superpowers:systematic-debugging` → `superpowers:verification-before-completion`
+- "Review this PR" → `superpowers:requesting-code-review`
+- "Draft a PRD" / "Write OKRs" / "Build a persona" → install `phuryn/pm-skills` (out of band — see docs/THIRD_PARTY.md)
+- "Run this PRD autonomously" → `ci:ralph`
+- "Fan out parallel provider migration" → `superpowers:dispatching-parallel-agents` or `/swarm` (PR D)
+- "Visual regression check the landing page" → `oh-my-claudecode:visual-verdict`
+
+No manual skill selection. The framework detects the trigger, resolves the chain, and enforces.

package/skills/tdd-workflow.md

@@ -0,0 +1,411 @@
+---
+name: tdd-workflow
+tier: "1"
+description: Enforces Law 3 (One Thing at a Time) and Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests.
+origin: continuous-improvement
+---
+
+# Test-Driven Development Workflow
+
+This skill ensures all code development follows TDD principles with comprehensive test coverage.
+
+## When to Activate
+
+- Writing new features or functionality
+- Fixing bugs or issues
+- Refactoring existing code
+- Adding API endpoints
+- Creating new components
+
+## Core Principles
+
+### 1. Tests BEFORE Code
+ALWAYS write tests first, then implement code to make tests pass.
+
+### 2. Coverage Requirements
+- Minimum 80% coverage (unit + integration + E2E)
+- All edge cases covered
+- Error scenarios tested
+- Boundary conditions verified
+
+### 3. Test Types
+
+#### Unit Tests
+- Individual functions and utilities
+- Component logic
+- Pure functions
+- Helpers and utilities
+
+#### Integration Tests
+- API endpoints
+- Database operations
+- Service interactions
+- External API calls
+
+#### E2E Tests (Playwright)
+- Critical user flows
+- Complete workflows
+- Browser automation
+- UI interactions
+
+## TDD Workflow Steps
+
+### Step 1: Write User Journeys
+```
+As a [role], I want to [action], so that [benefit]
+
+Example:
+As a user, I want to search for markets semantically,
+so that I can find relevant markets even without exact keywords.
+```
+
+### Step 2: Generate Test Cases
+For each user journey, create comprehensive test cases:
+
+```typescript
+describe('Semantic Search', () => {
+  it('returns relevant markets for query', async () => {
+    // Test implementation
+  })
+
+  it('handles empty query gracefully', async () => {
+    // Test edge case
+  })
+
+  it('falls back to substring search when Redis unavailable', async () => {
+    // Test fallback behavior
+  })
+
+  it('sorts results by similarity score', async () => {
+    // Test sorting logic
+  })
+})
+```
+
+### Step 3: Run Tests (They Should Fail)
+```bash
+npm test
+# Tests should fail - we haven't implemented yet
+```
+
+### Step 4: Implement Code
+Write minimal code to make tests pass:
+
+```typescript
+// Implementation guided by tests
+export async function searchMarkets(query: string) {
+  // Implementation here
+}
+```
+
+### Step 5: Run Tests Again
+```bash
+npm test
+# Tests should now pass
+```
+
+### Step 6: Refactor
+Improve code quality while keeping tests green:
+- Remove duplication
+- Improve naming
+- Optimize performance
+- Enhance readability
+
+### Step 7: Verify Coverage
+```bash
+npm run test:coverage
+# Verify 80%+ coverage achieved
+```
+
+## Testing Patterns
+
+### Unit Test Pattern (Jest/Vitest)
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react'
+import { Button } from './Button'
+
+describe('Button Component', () => {
+  it('renders with correct text', () => {
+    render(<Button>Click me</Button>)
+    expect(screen.getByText('Click me')).toBeInTheDocument()
+  })
+
+  it('calls onClick when clicked', () => {
+    const handleClick = jest.fn()
+    render(<Button onClick={handleClick}>Click</Button>)
+
+    fireEvent.click(screen.getByRole('button'))
+
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('is disabled when disabled prop is true', () => {
+    render(<Button disabled>Click</Button>)
+    expect(screen.getByRole('button')).toBeDisabled()
+  })
+})
+```
+
+### API Integration Test Pattern
+```typescript
+import { NextRequest } from 'next/server'
+import { GET } from './route'
+
+describe('GET /api/markets', () => {
+  it('returns markets successfully', async () => {
+    const request = new NextRequest('http://localhost/api/markets')
+    const response = await GET(request)
+    const data = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(data.success).toBe(true)
+    expect(Array.isArray(data.data)).toBe(true)
+  })
+
+  it('validates query parameters', async () => {
+    const request = new NextRequest('http://localhost/api/markets?limit=invalid')
+    const response = await GET(request)
+
+    expect(response.status).toBe(400)
+  })
+
+  it('handles database errors gracefully', async () => {
+    // Mock database failure
+    const request = new NextRequest('http://localhost/api/markets')
+    // Test error handling
+  })
+})
+```
+
+### E2E Test Pattern (Playwright)
+```typescript
+import { test, expect } from '@playwright/test'
+
+test('user can search and filter markets', async ({ page }) => {
+  // Navigate to markets page
+  await page.goto('/')
+  await page.click('a[href="/markets"]')
+
+  // Verify page loaded
+  await expect(page.locator('h1')).toContainText('Markets')
+
+  // Search for markets
+  await page.fill('input[placeholder="Search markets"]', 'election')
+
+  // Wait for debounce and results
+  await page.waitForTimeout(600)
+
+  // Verify search results displayed
+  const results = page.locator('[data-testid="market-card"]')
+  await expect(results).toHaveCount(5, { timeout: 5000 })
+
+  // Verify results contain search term
+  const firstResult = results.first()
+  await expect(firstResult).toContainText('election', { ignoreCase: true })
+
+  // Filter by status
+  await page.click('button:has-text("Active")')
+
+  // Verify filtered results
+  await expect(results).toHaveCount(3)
+})
+
+test('user can create a new market', async ({ page }) => {
+  // Login first
+  await page.goto('/creator-dashboard')
+
+  // Fill market creation form
+  await page.fill('input[name="name"]', 'Test Market')
+  await page.fill('textarea[name="description"]', 'Test description')
+  await page.fill('input[name="endDate"]', '2025-12-31')
+
+  // Submit form
+  await page.click('button[type="submit"]')
+
+  // Verify success message
+  await expect(page.locator('text=Market created successfully')).toBeVisible()
+
+  // Verify redirect to market page
+  await expect(page).toHaveURL(/\/markets\/test-market/)
+})
+```
+
+## Test File Organization
+
+```
+src/
+├── components/
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.test.tsx          # Unit tests
+│   │   └── Button.stories.tsx       # Storybook
+│   └── MarketCard/
+│       ├── MarketCard.tsx
+│       └── MarketCard.test.tsx
+├── app/
+│   └── api/
+│       └── markets/
+│           ├── route.ts
+│           └── route.test.ts         # Integration tests
+└── e2e/
+    ├── markets.spec.ts               # E2E tests
+    ├── trading.spec.ts
+    └── auth.spec.ts
+```
+
+## Mocking External Services
+
+### Supabase Mock
+```typescript
+jest.mock('@/lib/supabase', () => ({
+  supabase: {
+    from: jest.fn(() => ({
+      select: jest.fn(() => ({
+        eq: jest.fn(() => Promise.resolve({
+          data: [{ id: 1, name: 'Test Market' }],
+          error: null
+        }))
+      }))
+    }))
+  }
+}))
+```
+
+### Redis Mock
+```typescript
+jest.mock('@/lib/redis', () => ({
+  searchMarketsByVector: jest.fn(() => Promise.resolve([
+    { slug: 'test-market', similarity_score: 0.95 }
+  ])),
+  checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
+}))
+```
+
+### OpenAI Mock
+```typescript
+jest.mock('@/lib/openai', () => ({
+  generateEmbedding: jest.fn(() => Promise.resolve(
+    new Array(1536).fill(0.1) // Mock 1536-dim embedding
+  ))
+}))
+```
+
+## Test Coverage Verification
+
+### Run Coverage Report
+```bash
+npm run test:coverage
+```
+
+### Coverage Thresholds
+```json
+{
+  "jest": {
+    "coverageThresholds": {
+      "global": {
+        "branches": 80,
+        "functions": 80,
+        "lines": 80,
+        "statements": 80
+      }
+    }
+  }
+}
+```
+
+## Common Testing Mistakes to Avoid
+
+### FAIL: WRONG: Testing Implementation Details
+```typescript
+// Don't test internal state
+expect(component.state.count).toBe(5)
+```
+
+### PASS: CORRECT: Test User-Visible Behavior
+```typescript
+// Test what users see
+expect(screen.getByText('Count: 5')).toBeInTheDocument()
+```
+
+### FAIL: WRONG: Brittle Selectors
+```typescript
+// Breaks easily
+await page.click('.css-class-xyz')
+```
+
+### PASS: CORRECT: Semantic Selectors
+```typescript
+// Resilient to changes
+await page.click('button:has-text("Submit")')
+await page.click('[data-testid="submit-button"]')
+```
+
+### FAIL: WRONG: No Test Isolation
+```typescript
+// Tests depend on each other
+test('creates user', () => { /* ... */ })
+test('updates same user', () => { /* depends on previous test */ })
+```
+
+### PASS: CORRECT: Independent Tests
+```typescript
+// Each test sets up its own data
+test('creates user', () => {
+  const user = createTestUser()
+  // Test logic
+})
+
+test('updates user', () => {
+  const user = createTestUser()
+  // Update logic
+})
+```
+
+## Continuous Testing
+
+### Watch Mode During Development
+```bash
+npm test -- --watch
+# Tests run automatically on file changes
+```
+
+### Pre-Commit Hook
+```bash
+# Runs before every commit
+npm test && npm run lint
+```
+
+### CI/CD Integration
+```yaml
+# GitHub Actions
+- name: Run Tests
+  run: npm test -- --coverage
+- name: Upload Coverage
+  uses: codecov/codecov-action@v3
+```
+
+## Best Practices
+
+1. **Write Tests First** - Always TDD
+2. **One Assert Per Test** - Focus on single behavior
+3. **Descriptive Test Names** - Explain what's tested
+4. **Arrange-Act-Assert** - Clear test structure
+5. **Mock External Dependencies** - Isolate unit tests
+6. **Test Edge Cases** - Null, undefined, empty, large
+7. **Test Error Paths** - Not just happy paths
+8. **Keep Tests Fast** - Unit tests < 50ms each
+9. **Clean Up After Tests** - No side effects
+10. **Review Coverage Reports** - Identify gaps
+
+## Success Metrics
+
+- 80%+ code coverage achieved
+- All tests passing (green)
+- No skipped or disabled tests
+- Fast test execution (< 30s for unit tests)
+- E2E tests cover critical user flows
+- Tests catch bugs before production
+
+---
+
+**Remember**: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.