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, run the 5-phase implementation flow, 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.
  • 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.

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.

Worktree provider detection:

# Prefer rimba MCP server when active in the session (no shell needed).
# Otherwise resolve the binary: PATH first, then common install locations.
# NOTE: use `rimba version` (subcommand) to print the version; `rimba --version`
#       is not a recognised flag and exits non-zero.
RIMBA=$(command -v rimba 2>/dev/null \
  || { [ -x "$HOME/.local/bin/rimba" ] && echo "$HOME/.local/bin/rimba"; } \
  || { [ -x "$HOME/go/bin/rimba" ]     && echo "$HOME/go/bin/rimba"; } \
  || true)
[ -n "$RIMBA" ] && "$RIMBA" version 2>/dev/null || true   # confirm binary; never `--version`

• Detect an existing worktree first (idempotent resume; rimba absent → see that bullet below): rimba MCP active → call list; rimba CLI → run $RIMBA list --json (entries carry task, type, branch, path, is_current, status.dirty). Match an entry whose task equals the target task (PR invocations: target key is pr:<num>) or whose branch equals the derived <prefix>/<task>. On a match: resolve the absolute path via git worktree list --porcelain, keyed on the matched entry's own branch value — not a re-derived <prefix>/<task> guess, which can miss after a rimba rename or a task-only match. Print exactly one notice line: Resuming existing worktree: <branch> at <abs-path> (append (uncommitted changes present) if the entry's status.dirty is true — already fetched above, no extra call needed). If deps/install status is unknown (the worktree's own rimba add ran in a prior, possibly-dead session, so there is no process to wait on), confirm by checking the stack's install marker (node_modules, .venv, vendored deps) — no dedicated install-command detection marker exists in this skill, so lean on the marker check rather than guessing a command; don't run tests until confirmed. Follow "Enter the worktree" below, then skip the create call entirely — this pre-check runs before any add is launched, so a match is always a prior worktree. No match → create, using the bullets below.
• rimba MCP server active: invoke the add tool on it (rimba mcp) — no shell process needed. Use add pr:<num> when implementing from a PR number. Same non-zero-exit error-routing applies as the $RIMBA binary path below (an error reporting the worktree/branch already exists routes to enter; any other error is reported verbatim with a retry/fallback prompt) — the in-flight streaming behavior itself is CLI-specific and doesn't apply to an MCP tool call.
• $RIMBA non-empty (binary found): run $RIMBA add [<service>/]<task> [--flag] (or $RIMBA add pr:<num> --task "<label>" for a PR). Rimba handles branch-prefix conventions (feature/, bugfix/, hotfix/, docs/, test/, chore/), .env/.tool-versions/.vscode copying, post_create hooks, and lockfile sharing. In-flight ≠ duplicate: Path: <abs-path> prints before post_create hooks/deps finish (see "Post-create timing" and "Reclaim install time" below) — a path appearing while this rimba add is still running is the normal early print, never a duplicate; never kill or interrupt it. Only a genuine non-zero exit reporting the worktree/branch already exists — a real duplicate from another session — routes to enter: resolve the path via git worktree list --porcelain, print the same notice as above (dirty flag via git -C <path> status --porcelain, since no list call ran in this path), and EnterWorktree it instead of surfacing a failure. For any other non-zero exit, report the error verbatim and ask the user whether to retry or fall back to superpowers:using-git-worktrees — do not silently swallow it.
• Promote work already started — if you began editing on the current branch in the main checkout (not the default branch), $RIMBA add branch:<current-branch> moves that work into its own worktree, transferring dirty changes via git stash. --source is not valid in this mode. Distinct from the resume case above: that re-enters a worktree left over from a prior run; this promotes uncommitted work on the current branch in the main checkout into a new worktree.
• rimba absent: before invoking superpowers:using-git-worktrees, run git worktree list --porcelain and match the target branch the same way as the pre-check above; if a match exists, EnterWorktree it (same one-line notice + dirty flag via git -C <path> status --porcelain) instead of creating. Otherwise invoke superpowers:using-git-worktrees exactly as today.

Picking the branch-prefix flag — derive from the commit-tag the change will carry (see workflow-commit-and-pr for the full taxonomy):

Work type	rimba flag	Branch prefix	Commit-tag
New feature (default)	(none)	feature/<task>	[feat]
Bug fix	--bugfix (alias --fix)	bugfix/<task>	[fix]
Hotfix	--hotfix	hotfix/<task>	[hotfix]
Documentation	--docs	docs/<task>	[docs]
Tests	--test	test/<task>	[test]
Chore / tooling	--chore	chore/<task>	[chore]

Examples: $RIMBA add auth-redirect --bugfix → bugfix/auth-redirect; $RIMBA add ci-matrix --chore → chore/ci-matrix.

Monorepo scope — in a monorepo, prefix the task with the service or package name using <service>/<task>. The type flag still controls the branch prefix:

• $RIMBA add backend-api/auth-redirect --bugfix → bugfix/backend-api/auth-redirect
• $RIMBA add frontend/dark-mode → feature/frontend/dark-mode

Use the service scope whenever the work is clearly contained within one module — it groups branches and makes worktree paths self-descriptive. For cross-cutting changes, inspect the planned file edits and pick the service where the majority of changes land. If two services tie, prefer the service that owns the primary interface changed (e.g. the API layer for a contract change, the UI layer for a rendering change); only omit the scope entirely if no service file is touched at all (e.g. a root-only CI config change).

Post-create timing — rimba add runs dependency install and post_create hooks after creating the worktree. Path: <abs-path> is printed before deps install begins (after the create + copy steps). Coding may start as soon as Path: appears; running the test suite requires installed packages, so wait for rimba add to fully complete before running tests. This is the same early print the "In-flight ≠ duplicate" rule above guards against misreading as a duplicate worktree.

• Deps required (most stacks): omit --skip-deps/--skip-hooks and wait for rimba add to complete before running the test suite. This applies regardless of whether the plan is TDD-first — if tests need installed packages, rimba must finish first.
• No deps needed: pass --skip-deps and --skip-hooks only when the test suite requires no installation step (e.g. pure shell scripts, documentation assertion tests). Never skip deps and then reinstall them manually — rimba's pipeline already handles it correctly.

Reclaim install time (large/monorepo deps) — Path: is available before deps finish, so on a long install you can implement during the wait. A path becoming visible mid-run is never grounds to kill the in-flight rimba add (see "In-flight ≠ duplicate" above):

1. Run rimba add; if install will take a while, let it continue in the background (the Bash tool backgrounds long-running commands) so the session is free to code.
2. As soon as Path: <abs-path> appears, enter the worktree and implement the planned changes.
3. Do not run the test suite until rimba add has fully completed — RED/GREEN need installed deps.
4. Once rimba finishes, reconcile with TDD: git stash the implementation you wrote in step 2 → write the failing test → run (RED — fails with implementation stashed, confirming the test exercises the new behaviour) → git stash pop → run again (GREEN).

Skip this optimisation when install is fast, --skip-deps/--skip-hooks already apply (no wait), or post_create hooks rewrite the files you'd edit (let hooks finish first).

Enter the worktree: After Path: <abs-path> appears, try EnterWorktree(path=<abs-path>). From the main session this works for any git-registered worktree (including rimba's ../<repo>-worktrees/ layout). If rejected because the session is already inside a different worktree (target path outside .claude/worktrees/), the primary remedy is ExitWorktree(action=keep) → return to main → retry EnterWorktree(path=<abs-path>) (re-anchors session caches). Fall back to cd <abs-path> via Bash only as a last resort for non-rimba checkouts with no .claude/worktrees infrastructure; cd only anchors the Bash persistent cwd and does not re-anchor session-level caches the way EnterWorktree does. On any resumed or continued session, try EnterWorktree(path=<worktree-path>) first; if rejected because the session is already inside a different worktree, call ExitWorktree(action=keep) → retry; otherwise re-cd <worktree-path> as a last resort for non-rimba checkouts only (Bash cwd does not persist across session resume, so cd must be re-issued each time — unlike EnterWorktree, which restores it automatically).

Verify baseline tests pass before writing any code.

---

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.

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 code-impl sub-agent; consume the summary (not the diff) to stay lean

If a delegated 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. 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 senior-engineer consult: it reads the surfaced fork, invokes 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.

Skip condition: If Phase 2 sub-skill already ran full verification (imports + format + quality + lint + test) 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 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 workflow-extend)
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.