Workflow Development

---
name: workflow-development
description: "Development workflow — full lifecycle from Branch → Implement → Verify → Review → Deliver. Activated by /swe-workbench:implement, /swe-workbench:design, /swe-workbench:refactor, /swe-workbench:debug, /swe-workbench:test, /swe-workbench:architect, /swe-workbench:migrate, and /swe-workbench:document when the plan being authored modifies the codebase (Mode A) or when driving an implementation (Mode B). Entry point to execute a written implementation plan end to end — delegates to superpowers:executing-plans and superpowers:subagent-driven-development with the full 5-phase lifecycle. Skip for pure design / analysis output. Can also be invoked directly to author a Workflow section, or orchestrate parallel agents (Mode C)."
orchestrator: true
---

# Development Workflow

Single source of truth for how development work flows. Three modes:

- **Mode A (Plan Writing):** Embed a `## Workflow` section into plans using `templates/plan-workflow-section.md`
- **Mode B (Implementation):** Guide step-by-step execution through all 5 phases
- **Mode C (Orchestration):** Coordinate multiple parallel agents across dependency rounds — see `orchestration.md`

**Announce at start:** "I'm using the development skill to [write the workflow section / guide this implementation]."

## When This Skill Activates

- **Mode A:** Writing or finalizing an implementation plan (before `ExitPlanMode`)
- **Mode B:** User says "implement this", "build this", "execute this plan", "run the implementation plan end to end" — any branch → code → deliver flow. For focused bug diagnosis prefer `/swe-workbench:debug` (invokes the `debugger` subagent, which composes `superpowers:systematic-debugging`); escalate here when the fix needs the full 5-phase lifecycle. <!-- validate: prose-ref -->
  - **Prefer entering here rather than calling `superpowers:executing-plans` directly** — Phase 2 already delegates to it while adding the surrounding Branch → Verify → Review → Deliver lifecycle.
- **Mode C:** User says "orchestrate these issues", "run in parallel", multi-issue campaigns with >3 issues

## Sub-Skill Integration Map

```
Mode B — Single Implementation:

  Phase 1 (Branch)    → enter existing worktree if one matches, else rimba add <task> (rimba) OR superpowers:using-git-worktrees (fallback)
  Phase 2 (Implement) → superpowers:executing-plans OR superpowers:subagent-driven-development
                          └─ swe-workbench:principle-tdd (per unit)
                          └─ swe-workbench:workflow-delegated-implementation (scope/complexity warrants isolation)
  Phase 3 (Verify)    → superpowers:verification-before-completion
  Phase 4 (Review)    → BOTH in parallel (neither optional):
                          ├─ superpowers:requesting-code-review (Skill — plan-alignment)
                          └─ swe-workbench:reviewer (subagent — diff correctness/security/design)
  Phase 5 (Deliver)   → swe-workbench:workflow-commit-and-pr

Mode C — Orchestration: see orchestration.md
```

**Deduplication rule:** If a Phase 2 sub-skill already ran verification or review with evidence, mark that phase "completed by sub-skill" and proceed.

## Project Detection

Run during activation to populate workflow with project-specific values.

```bash
git branch -a && git log --oneline -20   # branch convention + commit style
grep -E '^[a-zA-Z_-]+:' Makefile 2>/dev/null   # available make targets
```

Also check CLAUDE.md for project-specific conventions.

**Detection markers** used by `templates/plan-workflow-section.md` — substitute every `[[detect:KEY]]` before saving the plan:

- `branch-convention` — from `git branch -a`
- `commit-style` — from `git log --oneline -20`
- `imports-command` — from Makefile `imports` target or language-marker fallback below
- `format-command` — from Makefile `format` target or language-marker fallback below
- `lint-command` — from Makefile `lint` target or language-marker fallback below
- `test-command` — from Makefile `test` target or language-marker fallback below
- `quality-command` — from Makefile `quality` target, project-script, or language-marker fallback below. Optional — if absent and no config is detected, skip the Quality stage with a note.
- `pr-template-path` — absolute path of the detected PR template, or `"none — use default format"`

**Language marker fallback (if no Makefile):**

| Marker | Imports | Format | Lint | Test |
|--------|---------|--------|------|------|
| `go.mod` | `goimports -w .` | `gofmt -w .` | `golangci-lint run` | `go test ./...` |
| `package.json` | `npx organize-imports-cli` (always works); or `eslint --fix` if `eslint-plugin-import` / `@typescript-eslint/consistent-type-imports` configured | check `scripts.format`/`prettier` | check `scripts.lint`/`eslint` | check `scripts.test` |
| `Cargo.toml` | `cargo fix --allow-dirty` (removes unused imports — review output before staging); configure `imports_granularity` in `rustfmt.toml` then `cargo fmt` | `cargo fmt` | `cargo clippy` | `cargo test` |
| `pyproject.toml` | `ruff check --select I --fix` (legacy: `isort .` + `autoflake -r --remove-all-unused-imports .`) | `ruff format` or `black .` | `ruff check` | `pytest` |
| `pom.xml` | `mvn spotless:apply` (requires import-ordering rules in Spotless config; for unused-import removal add `impsort-maven-plugin`) | `mvn spotless:apply` | `mvn checkstyle:check` (requires plugin) | `mvn test` |
| `build.gradle` / `build.gradle.kts` | `./gradlew spotlessApply` (Spotless: importOrder + removeUnusedImports) | `./gradlew spotlessApply` (or ktlint / google-java-format) | `./gradlew check` (Kotlin: `detekt`; Java: `checkstyleMain`) | `./gradlew test` |

> **Authoritative per-language tool list:** this table covers manifest-detected projects (Go, JS/TS, Rust, Python, Java, Kotlin). For the full, canonical command set for any language — including languages without a manifest row (C#, Ruby, Swift, SQL, Bash) — consult the matching `swe-workbench:language-<lang>` skill (e.g. `swe-workbench:language-csharp`).

> **`quality-command` fallback** is in the table below — intentionally separate because Quality is multi-tool by nature and a single cell would be unreadably wide.

**Quality stage fallback (multi-tool — wire whichever subset the project enforces):**

| Marker | Tool examples (complexity • duplication • length / maintainability) |
|--------|---------------------------------------------------------------------|
| `go.mod` | `gocyclo -over 15 .` • `dupl -t 50 ./...` • `gocognit -over 15 .` |
| `package.json` | `eslint` with `eslint-plugin-sonarjs` • `jscpd` • `es6-plato` (maintainability index; maintained fork of plato, Node 18+ compatible) |
| `Cargo.toml` | `cargo clippy -- -W clippy::cognitive_complexity` • (duplication: no OSS first-party tool; `jscpd` covers cross-language including Rust; `simian` is cross-language but commercial) • `cargo clippy -- -W clippy::too_many_lines` (per-function length; no file-level enforcer in first-party Rust) |
| `pyproject.toml` | `radon cc -n B -s` (grade ≥ B = complexity ≥ 6) and `lizard -CCN 15 -L 50` • `pylint --disable=all --enable=duplicate-code` • `radon mi -n B` |
| `pom.xml` | `mvn pmd:check` • `mvn pmd:cpd-check` • `checkstyle` (FileLengthCheck, MethodLengthCheck) |
| `build.gradle` / `build.gradle.kts` | `./gradlew detekt` (Kotlin) or `./gradlew pmdMain` (Java) • `./gradlew cpdCheck` (de.aaschmid.cpd; or `jscpd`) • `./gradlew checkstyleMain` (Method/FileLength) |

**PR template:** check `cat .github/pull_request_template.md 2>/dev/null` (and common variants: `.github/PULL_REQUEST_TEMPLATE.md`, `docs/pull_request_template.md`). If found, record the **absolute path** — pass it to `gh pr create --body-file <path>` in Phase 5. Before invoking, replace the literal `Closes #` placeholder with the resolved issue (`Closes #123`) or remove it and write a standalone `Issue: N/A — <one-line reason>` line. Never leave `Closes #` empty.

## The 5 Phases

---

### Phase 1: Branch

**Goal:** Isolated workspace with clean baseline. Detect an existing worktree (rimba MCP/CLI, or plain git) and resume it, or create a new one with the correct branch-prefix and monorepo scope, waiting on dependency install before running tests — full detection, creation, and recovery mechanics live in `reference/branch-resolution.md`.

---

### Phase 2: Implement

**Goal:** Write code following the plan, committing incrementally.

- New comments stay within `swe-workbench:principle-clean-code`'s per-language comment caps (Comment discipline) — assess at write-time so comments are lean on the first pass, rather than relying on the Phase 4 review backstop.
- **Symbol navigation.** Use `Grep`/`Glob` to locate an anchor, then expand from it with either the harness-native `LSP` tool (`goToDefinition`, `findReferences`, `prepareCallHierarchy`/`incomingCalls`/`outgoingCalls`) when it's reachable from the main loop, or `bin/swe-workbench-lsp` (via `Bash`; `def`/`refs`/`callers`/`callees`) — same capability, reachable regardless of tool-registry scoping. Attempt one call — on no servers or error (exit 3 from the script), state `LSP unavailable — falling back to Grep` once, use Grep for the rest of the run, and do not retry.

Choose execution strategy:
- **Sequential or separate session** → invoke `superpowers:executing-plans`
- **Independent tasks, same session** → invoke `superpowers:subagent-driven-development`
- **No plan / ad-hoc** → implement directly with `swe-workbench:principle-tdd` per unit
- **Scope/complexity warrants isolation** → invoke `swe-workbench:workflow-delegated-implementation` to group changes and dispatch each cohesive group to a focused `swe-workbench:code-impl` sub-agent; consume the summary (not the diff) to stay lean

If a delegated `swe-workbench:code-impl` run returns with verification evidence, mark Phase 3 "completed by sub-skill" per the deduplication rule above.

Commit logically grouped changes as you go. Never bundle unrelated changes.

| Commit type | Contains |
|---|---|
| Infrastructure | Config, dependencies, build changes |
| Core logic | Main feature/fix implementation |
| Tests | Test files and test utilities |
| Wiring | Integration, routing, CLI registration |

**Design-fork consult contract.** Worker subagents hold no `Agent` tool (verified: 0 of 21) — none can consult a peer subagent itself, regardless of what an individual agent's prompt text says. `swe-workbench:debugger` follows this contract: it surfaces a design fork in its output rather than attempting the consult. (Other worker prompts may still self-instruct to consult a subagent directly — that is a pre-existing instance of the same bug class, not a license to violate the tool grant; fix on sight.) The orchestrator (the top-level context activating this skill, which holds `Agent`) owns the `swe-workbench:senior-engineer` consult: it reads the surfaced fork, invokes `swe-workbench:senior-engineer` for the boundary/trade-off read, validates the resulting direction, and folds it back into the plan before continuing.

---

### Phase 3: Verify

**Goal:** Confirm imports, format, quality, lint, and test all pass with evidence.

Run in order — **Imports → Format → Quality → Lint → Test**. Imports come first because organizers (`goimports`, `ruff check --select I --fix`, `organize-imports-cli`, `spotless`) reshape lines that the formatter then normalises; reversing the order causes spurious rewrites on the next pass. Quality runs after Format so metrics evaluate normalised code, and before Lint so threshold violations surface as a distinct signal rather than mixed into lint noise. **Quality is optional** — if no `quality-command` is detected and the project has no complexity/duplication/length config, skip the stage with a note in the evidence block.

Invoke `superpowers:verification-before-completion`.

**Comment scan (advisory-with-accounting, not a hard gate)** — run per `shared/agents/comment-scan.md`
against the branch diff. It never fails verify on its own, but Phase 3 isn't "passed" until evidence
carries one `KEEP <id> <reason>` or `FIXED <id>` line per must-triage finding, `FIXED` re-confirmed
by a re-run.

**Skip condition:** If Phase 2 sub-skill already ran full verification (imports + format + quality + lint + test + comment scan with verdicts) with evidence, mark as "completed by sub-skill" and proceed.

---

### Phase 4: Review

**Goal:** Catch design and quality issues before delivery.

Dispatch **BOTH** reviewers **IN PARALLEL** — in a single batch (same turn), as two distinct required invocations, **neither optional**. They are different unit types:
- `superpowers:requesting-code-review` (a **Skill**) — plan-alignment: does this match the plan and meet standards?
- `swe-workbench:reviewer` (a **subagent**) — diff review: correctness, security, design, test gaps, comment quality in `Severity | File:Line | Issue | Why it matters | Suggested fix` format

Running the Skill inline and skipping the subagent (or vice-versa) does **not** satisfy this phase.

Act on feedback:
- **Critical/Important:** fix → re-verify (Phase 3) → re-review
- **Minor:** note or fix inline, proceed

**Skip condition:** Only skip with explicit named evidence that **both** stages already ran — a plan-alignment verdict from `superpowers:requesting-code-review` AND a `Severity | File:Line | …` diff review from `swe-workbench:reviewer`. Cite both when marking "completed by sub-skill". A single combined or one-sided review does not qualify.

---

### Phase 5: Deliver

**Goal:** Push branch and create PR.

Invoke `swe-workbench:workflow-commit-and-pr`.

**PR template rule:** if a template was detected in Project Detection, use `gh pr create --body-file [[detect:pr-template-path]]` — fill every section and substitute the `Closes #` placeholder before invoking. Do **not** fall through to a heredoc body when a template exists. Only use the heredoc fallback if no template was found.

---

## Optional deeper passes

Two existing skills provide deeper verification when warranted — invoke ad hoc outside the 5-phase core loop:

- `swe-workbench:workflow-codebase-audit` — multi-axis structural audit. Run pre-release or when onboarding a new codebase.
- `swe-workbench:security-review` — depth-first OWASP / secret-leak review. Run pre-merge for diffs touching auth, input parsing, secrets, or network surfaces.

---

## Plan-Time Behavior (Mode A)

**Gate:** Before rendering the Workflow section, confirm the plan introduces file edits (fix / make / implement). If the plan is a pure design recommendation or analysis with no codebase changes, return without modifying the plan.

When writing or finalizing a plan, add a `## Workflow` section using the template at `templates/plan-workflow-section.md`. Substitute every `[[detect:KEY]]` marker with concrete values from Project Detection. **Before saving, grep your rendered draft for `[[detect:` — if any match remains, you skipped Project Detection; redo it.**

Reproduce the template's `## Workflow` body **in full and verbatim** — copy every phase and line. The **only** permitted edit is substituting `[[detect:KEY]]` markers with concrete values; do **not** summarize, paraphrase, abridge, or collapse steps.

## Implementation-Time Behavior (Mode B)

1. **Announce transitions**: `Phase N complete — <summary>. Moving to Phase N+1: <name>.`
2. **Checkpoint**: after each phase transition, write the workflow state file so the session can survive auto-compaction (see `shared/docs/workflow-state.md` for the schema and path). Populate `context.worktree_root` with `git rev-parse --show-toplevel` at the Phase 1 checkpoint (omit when working in the main checkout). At Phase 5 success, delete the state file.
3. **Delegate to sub-skills**: don't re-implement what a sub-skill already does.
4. **Track phase state** — sub-skill completed Phases 3 or 4 with evidence → mark them "completed by sub-skill".
5. **Handle failures and no phase skipping** combined:

| Phase | Failure | Skip condition |
|-------|---------|----------------|
| 1 | Tests fail on baseline → report, ask to proceed | When caller passes `skip-phase-1: <rationale>` — branch already exists (e.g. invoked by `swe-workbench:workflow-extend` or `swe-workbench:workflow-redesign`) |
| 2 | Implementation blocked → stop, ask for clarification | Never |
| 3 | Verification fails → fix, re-run from imports | Sub-skill verified with evidence |
| 4 | Critical review issues → fix, re-verify, re-review | Sub-skill reviewed with evidence |
| 5 | Push/PR fails → diagnose, report | Never |

## Guardrails

### Common Mistakes

| Mistake | Fix |
|---------|-----|
| Skip verification, go straight to review | Always verify first (Phase 3 before 4) |
| Run only tests (skip imports/format/quality/lint) | Run all five, in order |
| Single giant commit | Group by logical change |
| Guess at branch/commit conventions | Detect from `git branch -a` and `git log` first |
| Plan that introduces file edits without Workflow section | Always add the Workflow section (Mode A) — skip only for pure design / analysis output |
| Jump straight to coding | Always start at Phase 1 |
| Ignore PR template, use generic format | Check for PR template first; fill every section |
| Render a summarized / short Workflow section | Copy the template body verbatim — substitute only `[[detect:]]` markers (Mode A) |

### Red Flags — Never

- Implement directly on main/master without explicit user consent
- Skip verification for any reason
- Proceed with unresolved critical/important review issues
- Force-push without explicit user request
- Commit files that may contain secrets (`.env`, credentials)

### If You Catch Yourself Thinking…

| Thought | Action |
|---------|--------|
| "Tests passed, good enough" | Run imports, format, quality, and lint too |
| "Review is overkill for this" | Small changes have bugs too. Review. |
| "I'll just commit everything together" | Split into logical commits |
| "Phase 2 sub-skill did everything" | Verify it provided evidence for Phases 3-4 |
| "This is a small fix, no need for the full lifecycle" | Small fixes still need verify + review |
| "The plan doesn't need a Workflow section" | If the plan introduces file edits, it does. Add one (Mode A). Skip only for pure design / analysis output. |
| "The plan only needs the gist of the Workflow steps" | Reproduce the template in full — a summary drops the exact guidance that prevents mistakes. |