dev

What this skill does

# /dev — Full Autonomous Development Pipeline

One skill to go from goal to merged PR. The human intervenes at two gates:
1. **Plan approval** — before implementation begins
2. **Merge** — the human clicks merge when ready

Everything else runs autonomously: test writing, implementation, validation, PR creation, CI monitoring, addressing review comments.

## Commit Discipline

**Commit early and often. Push after every commit.**

- Commit after every meaningful unit of progress (a test written, a function implemented, a bug fixed)
- Always push immediately after committing — don't accumulate local commits
- When dev_checks or formatting fixes something, commit and push those fixes immediately as their own commit (e.g., `style: fix lint/formatting`)
- After cleanup, commit and push before moving on
- After addressing review comments, commit and push each logical fix separately
- Small, frequent commits are always better than large, infrequent ones

## What NOT to Include in PRs

- **Design docs / spec files** — these are working artifacts for the brainstorming/planning phase, not deliverables. Do not commit them to the repo or include them in PRs.

## Input

- **A goal string**: `/dev implement rate limiting for the admin API`
- **A Trello card**: `/dev https://trello.com/c/abc123`

If no argument, ask: "What should I build? (goal or Trello card URL)"

---

## Stage 1: Setup

### 1.1 Verify Worktree

Run `pwd`. Must contain `.claude/worktrees/`.

If not: STOP. "Not in a worktree. Run `claude --worktree` first, then `/dev` again."

### 1.2 Set Up .env

If `.env` doesn't exist:
- Try `cp ../../.env .env`
- Fallback: `cp .env.example .env`
- Warn if copied from example

### 1.3 Resolve Goal

**Trello card** (URL contains `trello.com/c/`):
- Fetch card: `~/bin/trello card <ID>`
- Extract title + description as goal
- Move to In Progress: `~/bin/trello move <ID> <LIST_ID>` (look up via `~/bin/trello lists <BOARD_ID>`)
- Save card ID for later

**Plain text**: use as-is.

---

## Stage 2: Plan (HUMAN GATE)

The plan goes through two gates: structural validation by the `PreToolUse` hook on `ExitPlanMode` (mechanical), then user content review (judgment). The hook will deny any plan missing the required sections and tell you which sections to add.

### 2.1 Research

- Read ARCHITECTURE.md if it exists
- Search codebase for relevant modules
- Read existing tests in the area
- Check `dev/context/` for learnings, decisions, gotchas

### 2.2 Draft Plan

Draft a plan containing **all four required sections** (see `~/.claude/CLAUDE.md` → "Plan Mode" for the full spec):

1. **A fenced code block with the literal hot-path sequence** — actual events with indices, DDL, request/response, or call sequence. No prose paraphrases. If you can't show the concrete shape, you don't understand the change yet.
2. **A specific named test that would fail if the shape is wrong** — `def test_block_indices_are_monotonic` or `tests/.../test_x.py::test_y`. Not "we'll add tests" — the name commits the plan to a concrete failure mode.
3. **`## External Contracts` (or `## Invariants`)** — each external API/protocol this change touches and the invariant it must preserve. Write `- None` if genuinely none.
4. **`## Assumptions`** — one falsifiable bullet per load-bearing assumption. Write `- None` if genuinely none.

Plus the tracking content you'll persist downstream: goal, approach, test strategy, acceptance criteria, branch/PR/Trello.

### 2.3 Submit via ExitPlanMode

Call `ExitPlanMode` with the plan as the `plan` argument. The `PreToolUse` hook (`~/.claude/hooks/check_plan_quality.sh`) validates the four required sections before the user ever sees the plan. If any section is missing, the hook denies with a reason naming what to add — revise and resubmit.

Once the hook passes, the user reviews the plan content via the native plan-mode approval flow. **STOP and wait for approval.** Adjust the plan if they have feedback.

### 2.4 Persist Plan to dev/OBJECTIVE.md

After user approval, write the plan to `dev/OBJECTIVE.md` as the on-disk artifact for downstream stages. Use this template (which includes the required sections so the persisted file matches what the user approved):

```markdown
# Objective

<One-sentence goal>

## Description

<Context informed by codebase research>

## Approach

- <Step 1: what to change and why>
- <Step 2: ...>
- <Step 3: ...>

## Hot-path sequence

<fenced code block with literal events / DDL / request-response / call sequence>

## External Contracts

- <contract>: <invariant that must be preserved>

## Assumptions

- <falsifiable assumption>

## Test Strategy

- Failing test: `<tests/.../test_x.py::test_y>` — one sentence on what it proves
- Additional unit tests: <what to test, which files>
- E2E tests: <whether needed, which scenarios>

## Acceptance Criteria

- [ ] Failing unit test (above) written
- [ ] Implementation makes all tests pass
- [ ] dev_checks passes
- [ ] <domain-specific criteria>

## Tracking

- Trello: <card URL or "none">
- Branch: <branch>
- PR: <filled later>
```

---

## Stage 3: Draft PR + Test-First

### 3.1 Create Draft PR Early

Commit the objective and push immediately — get the draft PR up before writing any code:

```bash
git add dev/OBJECTIVE.md
git commit -m "chore: set objective to <short-handle>"
git push -u origin $(git rev-parse --abbrev-ref HEAD)
gh pr create --draft --title "<type>: <title>" --body "$(cat <<'EOF'
## Objective

<objective statement>

## Approach

<approach from OBJECTIVE.md>

## Acceptance Criteria

<criteria>
EOF
)"
```

Update `dev/OBJECTIVE.md` Tracking section with the PR URL. If Trello card is linked, comment the PR URL on the card.

### 3.2 Write Failing Tests

Write unit tests that define the expected behavior:
- Follow existing test patterns in the project
- Cover happy path, edge cases, error conditions
- Place in the right directory mirroring source structure

### 3.3 Verify Tests Fail Correctly

Run: `uv run pytest <test_files> -v`

Confirm tests fail because the feature doesn't exist, not due to import errors or test bugs. Fix test infrastructure issues until they fail cleanly.

### 3.4 Commit and Push Tests

```bash
git add <test_files>
git commit -m "test: add failing tests for <feature>"
git push
```

---

## Stage 4: Implement

### 4.1 Build It

Implement the feature/fix according to the plan.

**Use tests as the feedback loop**: after each significant change, run the relevant tests to check progress. Don't wait until "done" to test — test continuously.

```bash
uv run pytest <test_files> -v
```

**Commit at each milestone**: when a test starts passing, when a module is complete, when a logical chunk of work is done. Push every commit.

### 4.2 All Tests Pass

Keep iterating until all new tests pass AND existing tests still pass:

```bash
uv run pytest tests/unit_tests/ -v
```

Commit and push when all tests are green.

---

## Stage 5: Validate

### 5.1 Run Cleanup

Invoke `/cleanup` on the changed files to scan for dead code, complexity, duplication, and other quality issues. Fix safe issues, report the rest.

**Commit and push any fixes immediately** (e.g., `style: cleanup pass`).

### 5.2 Code Review

Invoke the `superpowers:requesting-code-review` skill to self-review the implementation against the plan and acceptance criteria. Address any issues found before proceeding.

### 5.3 Run Dev Checks

Execute the project's QC suite — `"$(git rev-parse --show-toplevel)/scripts/dev_checks.sh"` or equivalent (formatting, linting, type checking, tests, coverage). Check the project's CLAUDE.md or build docs for the right command if `dev_checks.sh` doesn't exist.

The script auto-stages formatting fixes. After it passes:
- If there are staged changes: **commit and push** (`style: fix lint/formatting`)
- Test failures: investigate, fix, **commit and push**, re-run

### 5.4 Smoke Test

**Always do a basic smoke test** of the actual user workflow, even when the test strategy says no formal e2e te