/start

name: start
description: "Master orchestrator skill that kicks off the full development pipeline. Routes tasks through the correct skill chain (brainstorm, debug, tdd, e2e, verify) based on task type. Guarantees testing.md exists, Playwright E2E tests are written, and nothing is claimed done without verification. Use when starting any new task, feature, bugfix, or refactor."

/start — Development Pipeline Orchestrator

> One command to rule them all. Routes your task through the right skills, guarantees test infrastructure, and won't let you claim done without proof.

Usage

/start <task description>

Pipeline

You MUST follow this sequence exactly. No shortcuts. No skipping steps.

---

Step 0: Test Infrastructure

**This step runs EVERY time, before anything else. Do NOT skip any sub-step.**

Check if `testing.md` exists at the project root.

**If it does NOT exist:**

1. Explore the project to discover:

• Package manager (npm, pnpm, yarn, bun)
• Test frameworks already installed (vitest, jest, playwright, etc.)
• Scripts in `package.json` (test, test:e2e, test:integration, etc.)
• Existing test files and their locations
• Required environment variables
• Database or service dependencies

2. Create `testing.md` using the template below, filled in with **real values from this project**:

# Testing Guide

## Environment Setup
- Package manager: [detected]
- Required env vars: [list with descriptions]
- Database: [commands to start/seed test DB, or "none"]
- Services: [docker-compose, external APIs, or "none"]

## Running Tests

### Unit Tests
Command: `[detected or recommend]`
Location: `tests/unit/`

### Integration Tests
Command: `[detected or recommend]`
Location: `tests/integration/`

### E2E Tests (Playwright)
Command: `npx playwright test`
Setup: `npx playwright install chromium`
Base URL: `[detected from config or recommend]`
Location: `tests/e2e/`

## Debugging Failed Tests
- Single test: `[framework-specific command]`
- Headed browser: `npx playwright test --headed`
- Traces: `npx playwright show-trace test-results/*/trace.zip`

3. **Install Playwright if not already installed.** This is NOT optional. Run:

   npm install -D @playwright/test && npx playwright install chromium

4. **Create `playwright.config.ts` if it doesn't exist.** Use the config template from `/e2e-playwright`. 5. **Create `tests/e2e/` directory** if it doesn't exist. 6. **Create CI so the suite runs without anyone remembering.** Rules written in prompts evaporate between sessions — CI is the enforcement. (This step exists because an audited project carried a red test for a month; nothing was running the suite.) Write `.github/workflows/tests.yml`, adjusting env vars per `testing.md`:

name: tests
on: [push, pull_request]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npm run test:run --if-present   # unit + integration
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
      - name: Fail on permanently-skipped tests
        run: |
          if grep -rnE "test\.skip\(true|it\.skip\(true|describe\.skip\(true" tests/ src/ 2>/dev/null; then
            echo "Permanently skipped tests found — skipped is failing"; exit 1
          fi

7. Commit: `git commit -m "chore: add test infrastructure (testing.md, playwright, CI)"`

**If it exists:** Read it. Then verify Playwright is installed (`npx playwright --version`) — if not, install it now. Then verify `.github/workflows/tests.yml` exists — if not, create it now (sub-step 6) before proceeding.

---

Step 1: Route the Task

Read CLAUDE.md. Classify the task as one of:

| Type | Route | Next step | |------|-------|-----------| | **feature** | New functionality or significant change | Step 2 (Design) | | **bugfix** | Something is broken | Step 3 (use `/debug` first) | | **refactor** | Restructure without behavior change | Step 4 (write tests for existing behavior first) | | **e2e-only** | Only adding/fixing E2E tests | Step 5 |

---

Step 2: Design (features only)

Run `/brainstorm-and-plan` with the task description.

• The plan MUST include Playwright E2E tests for every user-facing flow
• The plan MUST include integration tests for every API route
• Wait for user approval before writing any code

After approval, proceed to Step 4.

---

Step 3: Root Cause Analysis (bugfixes only)

Run `/debug` to investigate the bug.

• Do NOT guess at fixes
• Trace to root cause first
• Once root cause is identified, proceed to Step 4

---

Step 4: Implement with TDD

Run `/tdd` for every implementation step.

For each piece of work: 1. Write a failing test 2. Run it — confirm RED 3. Write minimal code to pass 4. Run it — confirm GREEN 5. Refactor if needed 6. Commit with conventional commit message

**Commit after every green cycle**, not at the end.

**Test Debt Handoff — before moving to Step 5:**

Review the `/tdd` Behavior Coverage Checklist. List every E2E test owed:

E2E debts from Step 4:
- [ ] [describe the user workflow that needs an E2E test]
- [ ] [describe the nav change that needs a navigation test]
- [ ] [describe the bug fix that needs a browser-level regression test]

Carry this list into Step 5. Every item MUST be covered before Step 6.

---

Step 5: E2E Coverage

╔══════════════════════════════════════════════════════════════════╗
║  THIS STEP IS MANDATORY. YOU MUST NOT SKIP IT.                  ║
║                                                                  ║
║  "Playwright is not installed" → INSTALL IT (Step 0 should      ║
║  have done this — if it didn't, install it now).                 ║
║                                                                  ║
║  "It would require significant setup" → THAT IS THE WORK.       ║
║  Do the setup. Tha