Dev Flow
Standard flow for code changes. Two paths sharing one spine: verify premise → plan → isolate → build → verify → ship autonomous. Human attention concentrates at two points: premise validation (start) and merge decision (end).
Steps reference other skills — invoke them via the Skill tool, don't reimplement their content.
Requires
This skill orchestrates other skills. Installing it alone leaves dangling references — the flow degrades gracefully (each step can be done by hand) but you lose the enforcement. Install alongside:
| Skill / agent |
Ships in |
brainstorming, writing-plans, executing-plans, using-git-worktrees, subagent-driven-development, test-driven-development, systematic-debugging, verification-before-completion |
superpowers (claude-plugins-official) |
code-simplifier (the /simplify agent) |
code-simplifier (claude-plugins-official) |
code-review, security-review |
code-review (claude-plugins-official) |
architecture |
knowledge-work-plugins |
cavecrew-reviewer, cavecrew-investigator (optional) |
cavecrew plugin (third-party, not in this marketplace); when absent, use code-review for review and the Explore agent for investigation |
grill-me, ticket-swarm, handoff |
personal / project skills — optional, referenced only on named branches of the flow |
falsify, ship and babysit-pr ship in this plugin.
Path selection
- New capability, enhancement, integration, refactor → Feature path
- Broken existing behaviour, regression, failing test, error report → Bugfix path
- One-line mechanical change (typo, config value) → skip flow; edit, verify, commit
Feature path
1. Validate the premise (interactive — user in the loop)
- Ambiguous scope or design freedom →
brainstorming skill; user wants stress-test → grill-me
- Touches external API/system behaviour (Google APIs, Coda, BigQuery, CloudFront, AWS, OAuth, query planner) →
falsify skill is mandatory before any design commitment. No implementation until load-bearing assumptions are CONFIRMED
- Significant design decision →
architecture skill for an ADR; open the ADR/requirements as its own PR for team discussion before implementation
2. Plan
- Multi-step work →
writing-plans skill from the ADR/requirements
- Plan should identify independent tasks (enables parallel build below)
3. Isolate
using-git-worktrees skill — worktree off latest origin/main, one per ticket
- Resuming an existing PR instead → freshness preflight first (
babysit-pr Step 1b)
4. Build (pick by shape)
| Shape |
Mechanism |
| Small/medium, sequential |
executing-plans + test-driven-development inline |
| Plan with independent tasks |
subagent-driven-development |
| Batch of related GitHub issues |
ticket-swarm |
| Very wide/audit-grade, user opted into token cost |
Workflow tool (multi-agent orchestration) |
TDD applies in all cases: failing test before implementation code.
5. Verify
verification-before-completion — run the actual commands, evidence before claims. This certifies local evidence only (tests, lint, build, diff); step 4 certifies the running system. Both must pass
/simplify — launch the code-simplifier plugin agent on the ticket diff before review, so reviewers see the cleaned tree
code-review skill on the post-simplify diff; security-relevant changes (auth, RLS, secrets, input handling) → security-review as well
- Probe the fix in the system that will run it —
falsify skill, Mode 2. Mandatory when the diff touches IaC/provider config (infra/, Pulumi/Terraform, WAF, IAM), a deployed env var, or rendered layout. A green typecheck proves the shape compiles, not that the provider accepts it or the page renders
6. Ship
ship skill — creates PR, drives to green via babysit loop, classifies flaky CI, stops at merge-readiness report. Never merges; the user decides
- End with the Run Output Contract sections (defined in
ship Step 4)
Bugfix path
1. Diagnose — no fix until root cause proven
systematic-debugging skill. Reproduce first — the reproduction is the live probe; a fix without one is an unverified assumption
- Unknown location / cross-cutting →
cavecrew-investigator if installed, otherwise the Explore agent, to locate, keep findings not file dumps in context
2. Isolate
- Worktree if the fix is non-trivial or the main checkout is busy; skip for one-liners
3. Fix, test-first
- Write the failing test that captures the bug BEFORE the fix (
test-driven-development). The test is the permanent regression probe
- Fix minimally; resist adjacent refactors (separate ticket)
4. Verify + ship
verification-before-completion (local evidence), then falsify Mode 2 when the diff touches infra, deployed config or rendered layout (running-system evidence), then /simplify (code-simplifier plugin) on the fix diff only, then ship
- Tiny diffs:
cavecrew-reviewer if installed, otherwise code-review, on the post-simplify diff
Delegation (context hygiene + independence)
Default rule: delegate to a subagent when raw tool output vastly exceeds the conclusions needed; stay inline when accumulated conversation context is the asset. Subagents give two things: main context stays clean (cavecrew agents also compress output), and independent judgment (a reviewer who didn't write the code has no confirmation bias).
| Step |
Where it runs |
Why |
| Brainstorm / grill / plan |
Inline |
User dialogue + accumulated understanding is the value; a subagent starts blind |
| Falsify probes |
Parallel subagents |
Raw probe output pollutes; only the verdict table matters |
| Code location / diagnosis sweeps |
cavecrew-investigator (else Explore) |
Want a file:line table, not 40 file reads in context |
| Build — independent tasks |
Subagents (subagent-driven-development) |
Tasks are self-contained by design. State each agent's done explicitly: branch pushed, CI green, review findings addressed, and every call site of the thing it changed checked — never "PR opened" |
| Build — small sequential + TDD |
Inline |
Handoff cost exceeds pollution; TDD needs tight edit-test iteration |
/simplify |
code-simplifier plugin agent on the ticket/fix diff |
Independence: author doesn't grade own cleanup |
| Review / verify pass |
cavecrew-reviewer (else code-review) on the post-simplify diff |
Independence: fresh eyes, author never reviews own work |
| Ship loop |
Background job |
Long CI polling shouldn't occupy the interactive session |
Never delegate a decision the user must see reasoning for (design trade-offs, scope calls) — subagent reports summarize, and the user loses the why.
Context budget (avoid the 50% degradation zone)
Long flows degrade when context grows. The fix is structural, not compaction: every phase writes its output to a file, and phase transitions are session boundaries.
Phase artifacts (mandatory — the artifact IS the phase's deliverable):
| Phase |
Artifact on disk |
| Premise validation |
ADR / requirements doc + falsify verdict table |
| Plan |
Plan file (per writing-plans) |
| Build |
Commits + updated plan checkboxes |
| Verify |
code-simplifier result + review findings appended to plan or PR comments |
| Ship |
PR + audit log |
At each phase boundary, when context is above ~40%:
- Confirm the phase artifact is written and self-contained (a fresh reader needs NO conversation history to continue)
- Tell the user: "Phase done, artifact at
<path>. Recommend /clear; resume with dev-flow + that path." A fresh session reading a 2-page plan outperforms a 60%-full session that remembers writing it
- The plan → build boundary is the highest-value break:
executing-plans is explicitly designed to run in a separate session from planning
Mid-phase (no clean artifact yet) and context already heavy → invoke the handoff skill: it writes a handoff doc capturing decisions-not-yet-in-artifacts, then the user clears and resumes from the doc.
Do not rely on auto-compact — it triggers after the degradation zone and does not choose what survives.
Rules
- Skipping a step is allowed but must be stated explicitly with the reason ("skipping worktree: one-line fix")
- Never skip: falsify-on-external-API (feature), falsify-the-fix on infra/IaC/deployed-config/layout diffs (both paths), reproduce-first (bugfix), verification-before-completion (both)
- Closing a PR without merging? Harvest its review findings first — copy unresolved bot and human findings onto the successor branch or issue. Otherwise they re-surface verbatim in the rewrite weeks later
- Skip
/simplify only for one-line mechanical edits (state the reason). Invoke the code-simplifier plugin; do not reimplement it
- Long-running ship loops can run as background jobs; recurring runs via
/loop or /schedule
1---2name: dev-flow3description: This skill should be used when the user asks to "start work on a feature", "fix this bug", "implement this ticket", or "work on this regression". Standard development flow for any code change — feature path (design interrogation, falsify, plan, worktree, build, verify, ship) or bugfix path (reproduce, root-cause, TDD fix, ship).4---56# Dev Flow78Standard flow for code changes. Two paths sharing one spine: **verify premise → plan → isolate → build → verify → ship autonomous**. Human attention concentrates at two points: premise validation (start) and merge decision (end).910Steps reference other skills — invoke them via the Skill tool, don't reimplement their content.1112## Requires1314This skill orchestrates other skills. Installing it alone leaves dangling references — the flow degrades gracefully (each step can be done by hand) but you lose the enforcement. Install alongside:1516| Skill / agent | Ships in |17|---|---|18| `brainstorming`, `writing-plans`, `executing-plans`, `using-git-worktrees`, `subagent-driven-development`, `test-driven-development`, `systematic-debugging`, `verification-before-completion` | `superpowers` (claude-plugins-official) |19| `code-simplifier` (the `/simplify` agent) | `code-simplifier` (claude-plugins-official) |20| `code-review`, `security-review` | `code-review` (claude-plugins-official) |21| `architecture` | `knowledge-work-plugins` |22| `cavecrew-reviewer`, `cavecrew-investigator` (optional) | `cavecrew` plugin (third-party, not in this marketplace); when absent, use `code-review` for review and the `Explore` agent for investigation |23| `grill-me`, `ticket-swarm`, `handoff` | personal / project skills — optional, referenced only on named branches of the flow |2425`falsify`, `ship` and `babysit-pr` ship in this plugin.2627## Path selection2829- New capability, enhancement, integration, refactor → **Feature path**30- Broken existing behaviour, regression, failing test, error report → **Bugfix path**31- One-line mechanical change (typo, config value) → skip flow; edit, verify, commit3233## Feature path3435### 1. Validate the premise (interactive — user in the loop)3637- Ambiguous scope or design freedom → `brainstorming` skill; user wants stress-test → `grill-me`38- Touches external API/system behaviour (Google APIs, Coda, BigQuery, CloudFront, AWS, OAuth, query planner) → **`falsify` skill is mandatory before any design commitment**. No implementation until load-bearing assumptions are CONFIRMED39- Significant design decision → `architecture` skill for an ADR; open the ADR/requirements as its own PR for team discussion before implementation4041### 2. Plan4243- Multi-step work → `writing-plans` skill from the ADR/requirements44- Plan should identify independent tasks (enables parallel build below)4546### 3. Isolate4748- `using-git-worktrees` skill — worktree off latest origin/main, one per ticket49- Resuming an existing PR instead → freshness preflight first (`babysit-pr` Step 1b)5051### 4. Build (pick by shape)5253| Shape | Mechanism |54|---|---|55| Small/medium, sequential | `executing-plans` + `test-driven-development` inline |56| Plan with independent tasks | `subagent-driven-development` |57| Batch of related GitHub issues | `ticket-swarm` |58| Very wide/audit-grade, user opted into token cost | Workflow tool (multi-agent orchestration) |5960TDD applies in all cases: failing test before implementation code.6162### 5. Verify63641. `verification-before-completion` — run the actual commands, evidence before claims. This certifies **local** evidence only (tests, lint, build, diff); step 4 certifies the running system. Both must pass652. `/simplify` — launch the `code-simplifier` plugin agent on the ticket diff **before** review, so reviewers see the cleaned tree663. `code-review` skill on the post-simplify diff; security-relevant changes (auth, RLS, secrets, input handling) → `security-review` as well674. **Probe the fix in the system that will run it** — `falsify` skill, Mode 2. Mandatory when the diff touches IaC/provider config (`infra/`, Pulumi/Terraform, WAF, IAM), a deployed env var, or rendered layout. A green typecheck proves the shape compiles, not that the provider accepts it or the page renders6869### 6. Ship7071- `ship` skill — creates PR, drives to green via babysit loop, classifies flaky CI, stops at merge-readiness report. Never merges; the user decides72- End with the Run Output Contract sections (defined in `ship` Step 4)7374## Bugfix path7576### 1. Diagnose — no fix until root cause proven7778- `systematic-debugging` skill. **Reproduce first** — the reproduction is the live probe; a fix without one is an unverified assumption79- Unknown location / cross-cutting → `cavecrew-investigator` if installed, otherwise the Explore agent, to locate, keep findings not file dumps in context8081### 2. Isolate8283- Worktree if the fix is non-trivial or the main checkout is busy; skip for one-liners8485### 3. Fix, test-first8687- Write the failing test that captures the bug BEFORE the fix (`test-driven-development`). The test is the permanent regression probe88- Fix minimally; resist adjacent refactors (separate ticket)8990### 4. Verify + ship9192- `verification-before-completion` (local evidence), then **`falsify` Mode 2 when the diff touches infra, deployed config or rendered layout** (running-system evidence), then `/simplify` (`code-simplifier` plugin) on the fix diff only, then `ship`93- Tiny diffs: `cavecrew-reviewer` if installed, otherwise `code-review`, on the post-simplify diff9495## Delegation (context hygiene + independence)9697Default rule: **delegate to a subagent when raw tool output vastly exceeds the conclusions needed; stay inline when accumulated conversation context is the asset.** Subagents give two things: main context stays clean (cavecrew agents also compress output), and independent judgment (a reviewer who didn't write the code has no confirmation bias).9899| Step | Where it runs | Why |100|---|---|---|101| Brainstorm / grill / plan | Inline | User dialogue + accumulated understanding is the value; a subagent starts blind |102| Falsify probes | Parallel subagents | Raw probe output pollutes; only the verdict table matters |103| Code location / diagnosis sweeps | `cavecrew-investigator` (else Explore) | Want a file:line table, not 40 file reads in context |104| Build — independent tasks | Subagents (`subagent-driven-development`) | Tasks are self-contained by design. **State each agent's done explicitly: branch pushed, CI green, review findings addressed, and every call site of the thing it changed checked — never "PR opened"** |105| Build — small sequential + TDD | Inline | Handoff cost exceeds pollution; TDD needs tight edit-test iteration |106| `/simplify` | `code-simplifier` plugin agent on the ticket/fix diff | Independence: author doesn't grade own cleanup |107| Review / verify pass | `cavecrew-reviewer` (else `code-review`) on the **post-simplify** diff | Independence: fresh eyes, author never reviews own work |108| Ship loop | Background job | Long CI polling shouldn't occupy the interactive session |109110Never delegate a decision the user must see reasoning for (design trade-offs, scope calls) — subagent reports summarize, and the user loses the why.111112## Context budget (avoid the 50% degradation zone)113114Long flows degrade when context grows. The fix is structural, not compaction: **every phase writes its output to a file, and phase transitions are session boundaries.**115116Phase artifacts (mandatory — the artifact IS the phase's deliverable):117118| Phase | Artifact on disk |119|---|---|120| Premise validation | ADR / requirements doc + falsify verdict table |121| Plan | Plan file (per `writing-plans`) |122| Build | Commits + updated plan checkboxes |123| Verify | `code-simplifier` result + review findings appended to plan or PR comments |124| Ship | PR + audit log |125126At each phase boundary, when context is above ~40%:1271281. Confirm the phase artifact is written and self-contained (a fresh reader needs NO conversation history to continue)1292. Tell the user: "Phase done, artifact at `<path>`. Recommend `/clear`; resume with `dev-flow` + that path." A fresh session reading a 2-page plan outperforms a 60%-full session that remembers writing it1303. The plan → build boundary is the highest-value break: `executing-plans` is explicitly designed to run in a separate session from planning131132Mid-phase (no clean artifact yet) and context already heavy → invoke the `handoff` skill: it writes a handoff doc capturing decisions-not-yet-in-artifacts, then the user clears and resumes from the doc.133134Do not rely on auto-compact — it triggers after the degradation zone and does not choose what survives.135136## Rules137138- Skipping a step is allowed but must be stated explicitly with the reason ("skipping worktree: one-line fix")139- Never skip: falsify-on-external-API (feature), **falsify-the-fix on infra/IaC/deployed-config/layout diffs (both paths)**, reproduce-first (bugfix), verification-before-completion (both)140- **Closing a PR without merging? Harvest its review findings first** — copy unresolved bot and human findings onto the successor branch or issue. Otherwise they re-surface verbatim in the rewrite weeks later141- Skip `/simplify` only for one-line mechanical edits (state the reason). Invoke the `code-simplifier` plugin; do not reimplement it142- Long-running ship loops can run as background jobs; recurring runs via `/loop` or `/schedule`