Workflow reference

Numbering

Steps are numbered 0–24 in execution order — 25 numbered step commands in all, and the checklist reads top-to-bottom. Some are optional and off by default: 1 research and 3 spike opt in per issue via the ## Workflow flags block, and 19 mergetoall opts in per project by configuring all_prs_branch. A normal issue runs the 22 mandatory steps and its checklist shows the optional rows pre-marked [-] (skipped). Reduced checklist tiers show a monotonic subset with larger gaps.

Run steps one at a time with /devagent:next (which advances to the next unmarked step), chain them with /devagent:next --auto, or invoke any step command directly.

An --auto chain stops with a PHASE BREAK before implement, quality and updatewbs: run /clear, then the printed Resume command. Each phase then starts in a fresh session instead of re-reading the whole issue's history on every call (config phase_breaks; --no-breaks skips it for one chain).

Step 20, /devagent:mergemr, merges the PR only when the project sets permissions.merge_mr = true, and only at the head the last passing preship verified (verified_head); otherwise it marks its row [?] until the PR is merged elsewhere. /devagent:next re-checks a [?] mergemr row on every run; while the PR is still open it prints WAITING at step 20 (mergemr): the PR is not merged yet; … and stops with exit 0. Nothing polls: run /devagent:next again later. mergetoall (19) holds on pending CI before mergemr runs, so an --auto chain reaches mergemr only with mergetoall [-] or CI green. Cleanup waits for the mergemr row; /devagent:park or marking the row [-] are the escapes for a PR that stays open (see commands/mergemr.md).

Step table

Rows in execution order.

# Command Phase Purpose
0 pull Plan Fetch the issue and scaffold its workflow directory
1 research Plan (optional, off by default) Measure code/docs/upstream before drafting; record cited findings and open unknowns
2 draft Plan Draft the implementation plan
3 spike Plan (optional, off by default) Run the plan's load-bearing bets in a throwaway worktree; record verdicts
4 scope Plan Structured scope evaluation appended to the plan
5 improve Plan Fresh-context check for latent bugs, side effects, and ambiguities
6 prune Plan Move non-load-bearing items to the future-enhancements file
7 tighten Plan Final pre-implementation review: lock ordering, paths, and test plan
8 branch Implement Create the issue branch from the configured baseline
9 implement Implement Execute the plan task-by-task
10 quality Implement Review and tighten code quality on the branch
11 document Implement Record what was actually built versus planned
12 commit Implement Commit with DCO sign-off using the commit template
13 analyze Implement Run the project's analyzer family against the changed lines
14 draftmr Ship Draft the merge-request body
15 review Ship Run code review on the branch
16 redmr Ship Red-team adversarial review of the MR before shipping
17 preship Ship Fresh-context verification that the committed branch satisfies the acceptance criteria
18 ship Ship Push the branch and open the MR
19 mergetoall Integrate & close (optional, off by default; on when the project configures all_prs_branch) Squash-merge the branch into the local all-PRs branch; requires green CI on the MR
20 mergemr Integrate & close Merge the PR at the preship-verified head when merge_mr = true; otherwise wait [?] until it is merged
21 updatewbs Integrate & close Update the work-breakdown structure
22 impact Integrate & close Measure and record the real-world impact of the merged change
23 lessonslearned Integrate & close Extract reusable lessons from the completed issue
24 cleanup Integrate & close Restore the tree, commit the devdoc, clear the active issue

Checklist glyphs

Every issue's checklist.md tracks step state with this key:

State key: [ ] pending  [x] done  [-] skipped  [!] stuck  [~] in-progress  [?] blocked-external  [P] parked

The revision loop

  • Run /devagent:comments first to fetch reviewer feedback, then /devagent:revise opens a new revision pass that re-runs the workflow from the draft step — the revision's first pending step. revise does not fetch comments itself and stops with a pointer to comments if they are missing.
  • /devagent:stuck marks the current step stuck with a reason; /devagent:unstuck clears it and resumes.
  • /devagent:where and /devagent:catchup rehydrate an issue's state at any point — the current step, the artifacts so far, and what comes next.

← devAgent onboarding