rota-work

Main-session-driven implementation with per-task verification and commits. Subagents are in-process Agent calls that write files; the main session commits.

Rounds are not this skill (standing workers, merge gate, relays: /rota-orchestrate and the rota round verbs). If work.dispatch is "tmux" or "herdr", this skill still dispatches subagents; say so once and continue, or point the user at /rota-orchestrate for a multi-issue round.

Configuration

Read .rota/config.json:

• models.orchestrator: main session model: planning and verification (default opus)
• models.worker: the standard tier: implementation subagents (default sonnet)
• work.isolation: "branch" (default) or "worktree"
• work.mergeStrategy: "direct" (default) or "pr"

Flow

Copy this checklist and track your progress:

- [ ] Step 1 — Guard
- [ ] Step 2 — Clarify Ambiguous Briefs (only when needed)
- [ ] Step 2.5 — Detect Knowledge-vs-Correction Contradictions
- [ ] Step 3 — Name the Branch
- [ ] Step 4 — Plan Tasks
- [ ] Step 4.5 — Umbrella Pre-Flight
- [ ] Step 5 — Create Branch or Worktree
- [ ] Step 6 — Dispatch Subagents
- [ ] Step 7 — Verify Each Completion
- [ ] Step 7.5 — Commit per Task (main session)
- [ ] Step 8 — Sequential Waves
- [ ] Step 8.5 — Sweep Tool-Generated Siblings
- [ ] Step 9 — Close the Items
- [ ] Step 10 — Merge or PR
- [ ] Step 11 — Update Status and Report
- [ ] Step 12 — After-Work QA
- [ ] Step 13 — After the Cycle

No-Argument Mode (reconcile, suggest, then work)

With no item, ID or brief, read `no-argument-mode.md` and follow it: it reconciles active streams, suggests one item and continues into Step 1.

Preview Mode (--preview <target>)

--preview <target> (flag anywhere in the args) prints a read-only approach peek and stops: no writes, no commits, no status. Procedure in `references/work-preview.md`; context per `references/context-load-protocol.md` and `references/knowledge-consult.md`.

Step 1 — Guard

rota git guard clean --context "/rota-work"

Exit 0: continue. Exit 3: not a repo, surface and stop. Exit 1 (dirty tree): when every dirty path is a tool-generated sibling, sweep them into a chore: commit and continue; any user change stops with the guard's message. Procedure and sibling list: `sibling-sweep.md`.

Step 2 — Clarify Ambiguous Briefs (only when needed)

Only when the brief is too thin to plan concrete tasks (scope hits 2+ incompatible areas, a requirement could yield opposite implementations, captured items imply different orderings), ask one AskUserQuestion of 1-3 questions before touching code. Otherwise proceed. Don't ask to confirm understanding, for preferences inferable from KNOWLEDGE.md or the codebase, or for style inside an agreed scope.

Each question gets a short header, options that map to concrete plans with the likeliest marked (Recommended), and multiSelect: true for conflicting items. On ambiguity, default to Recommended and state it in the dispatch brief.

Step 2.5 — Detect Knowledge-vs-Correction Contradictions

When Step 2 produced a non-Recommended answer that pushes back on a stated assumption, read `contradictions.md`. Skip silently otherwise.

Step 3 — Name the Branch

Pick a descriptive branch name (rota/quick-switch). Step 5 creates the branch and registers it once. When items carry Repos: (umbrella mode) or the backend is issues, read `umbrella-and-issue-mode.md` at each step it names.

Step 4 — Plan Tasks

Plan-as-artifact check (first, including resume). For every item or slice, read `plan-artifact.md` and resolve its supported backend key before decomposing. An issue plan needs no milestone. Use the stored tasks, constraints and verify steps when a plan exists; a plan that fails rota plan check stops the run before dispatch; the check is skipped on the file backend and for plans with no Serves: line (see that file).

Planning level. With no stored plan, apply `references/planning-dial.md` and state the level in one line to the user. Level 1 (pointers) decomposes ad hoc as below, unchanged. Level 2 or higher: stop and offer /rota-brainstorm, /rota-spike or /rota-plan first; proceed ad hoc only if the user says so. A round worker (branch <agent>/<issue>-<slug>) does not stop: the issue's acceptance criteria are its spec, so it states the level and proceeds, and escalates with ROTA-BLOCKED only for an open product question. A stored plan already carries its level; skip this.

1. Consult knowledge and decisions with the canonical K+D pattern (references/knowledge-consult.md), topics inferred from the planned work. Run rota glossary read <terms in the item>… too; call out drift from a canonical term. Carry matches into Step 6 briefs as **Known gotchas:** (relevant bullets only) and **Hard boundaries:** (full entries: rule, Why, Forbids, Permits). If a planned task would violate a decision, stop and surface it before dispatching. Run rota map stats --cap (one-line nudge; never blocks).

   REQUIRED — Register hits on consumed bullets. After writing the briefs, apply Hit-register after consumption in references/knowledge-consult.md: one rota knowledge hit --topic "<T>" --title "<first-line-of-bullet>" per bullet that landed in a brief's **Known gotchas:**, all in one parallel batch. Bullets pruned before the briefs earn no credit.

2. Identify tasks from the loaded plan, preserving its key and task numbers; only decompose ad hoc when no plan exists. Include files, what changes and acceptance criteria.

3. Resuming (a branch with commits past the base): apply the resume rule in `references/task-ledger.md` to those tasks, skip committed task IDs and plan only the unfinished tasks. Do not silently re-decompose or renumber a saved plan.

4. Absorb file collisions before grouping: any two tasks whose modified-file sets intersect, and shared-symbol changes that disjoint file sets hide. Rules and the rename check in `references/work-wave-planning.md`.

5. Group into dependency waves: wave 1 is independent files (parallel); wave 2+ depends on earlier output.

Step 4.5 — Umbrella Pre-Flight

Skip when rota repo umbrella exits 1 (single-repo). When it exits 0, read `umbrella-and-issue-mode.md`, Step 4.5, and carry the resolved repo set into Steps 5 and 10.

Step 5 — Create Branch or Worktree

Use the Step 3 name; references/isolation-patterns.md has the pattern per work.isolation. Single-repo, branch isolation:

git checkout -b <branch>
rota status add <branch> --items <ID>[,<ID>...]

The only rota status add of the cycle: create the branch or worktree first, then register once (--worktree <path> for a worktree). Idempotent on (branch, repo).

When umbrella, read Step 5 in umbrella-and-issue-mode.md (registration, branches). When backlog.backend is "issues", read the same section for the claim flow before planning tasks.

The main session stays at the repo root; subagents cd into their assigned directory first and use absolute paths.

Step 6 — Dispatch Subagents

Dispatch one standard-tier subagent per independent task, all in one message; don't announce. Subagents write files and never stage or commit (no .git/index races). Fill the brief from `dispatch-brief.md`. Umbrella: read Step 6 in umbrella-and-issue-mode.md.

Step 7 — Verify Each Completion

Verify silently. Trust the diff, not the subagent's narrative.

1. git status --porcelain, then git diff for the files the subagent reported.
2. Read the modified files: do they match the brief?
3. Structural checks: grep for expected patterns, no regressions.
4. Rename validation. Re-run git grep -l "<old-name>" -- <scope>; files outside the subagent's set get a fix-up dispatch before staging.
5. Claim-weight check on gap-fills, and treat a subagent's dispute of its brief as a FAIL on the plan (see references/work-wave-planning.md, Verifying a completion).
6. When test.fast is set, run rota test run fast; a FAIL is a FAIL. Use it as the PASS proof --check.

PASS → move on. FAIL → dispatch a fix agent and re-verify; repeat until PASS, and surface only persistent failures. Commit (Step 7.5) only on PASS.

Record proof (facts about what ran, not acceptance). Per task:

• PASS: one row per item the task resolves, run through the verb so the row is measured: rota proof record <ID> -- <verify command or grep> (exit 0 writes PASS, non-zero writes FAIL and exits 1). Never type a PASS you did not run.
• Persistent FAIL: rota proof record already wrote the FAIL row.
• Behavior task (skip the RED half when rota config show work.tdd is false; PASS rows stay): run the new test through rota proof record <ID> -- <test command> before the change (the FAIL row is the RED; the verb exits 1, expected), then again after for the PASS row. A subagent that reports no RED gets a fix dispatch (a FAIL above). So does one whose RED evidence is a build, compile or setup failure (undefined:, cannot find, no such file, command not found, import or syntax error): the test must fail on an assertion, so the fix agent repairs the test until it does.
• Docs or skill-only task: no RED, and no command to run. Use rota proof add with no test seam: docs/skill change in the row's --check.
• Acceptance: rota item complete (Step 9) writes it and exits 4 when an item has no proof. Never pass --no-proof on your own; an unproven item stays open and is surfaced.

Issue mode keeps the rows in the item's proof note.

Step 7.5 — Commit per Task (main session)

One commit per task, sequential, in dispatch order, staging only that task's files:

git add <task-N-files>
git commit -m "<suggested-message-from-task-N-brief>" -m "Task: <key>/<N>"

• Every task commit ends with the Task: <key>/<N> trailer (`references/task-ledger.md`); a resumed session skips finished tasks by it.
• Stage exactly the files named in the task's brief. Never git add -A or git add ..
• Use the brief's suggested message verbatim, unless a FAIL→re-dispatch loop changed what landed.
• Same-file carve-out. Two parallel subagents editing different ranges of one file get ONE commit naming both task IDs; granularity lives in the message.
• Worktree isolation: commit against the worktree's index (git -C <worktree-path>). Umbrella: Step 7.5 in umbrella-and-issue-mode.md.

Step 8 — Sequential Waves

Wait for wave 1 to complete, verify and commit (Step 7.5), then dispatch wave 2 with updated context.

Step 8.5 — Sweep Tool-Generated Siblings

When the toolchain left untracked siblings after the task commits, sweep them per `sibling-sweep.md`, Step 8.5. Otherwise skip.

Step 9 — Close the Items

Issue backend: skip; the issue closes when its PR merges (umbrella-and-issue-mode.md, Step 9).

File backend: follow `file-backend-close.md` per resolved item: it tombstones the item's plan, runs rota item complete <ID> --commit <commit-hash> (the only write to the backlog), then commits .rota/BACKLOG.md and the removed plan by name.

Step 10 — Merge or PR

work.mergeStrategy picks rota ship merge (direct, the default and when unset) or rota ship pr. Don't ask. Invocations (umbrella --repo, exit-4 verdict, merge-approval handling) are in rota-ship Steps 6a/6b. Opening a PR is a manual gate. The issue backend forces the PR path: read Step 10 in umbrella-and-issue-mode.md and references/issue-mode.md.

Step 11 — Update Status and Report

rota status rm <branch>                  # umbrella: add --repo <repo>

Umbrella: see Step 11 in umbrella-and-issue-mode.md. Then one compact summary, no plan recap or verification list: Done — merged <branch> into main., one - #<n> <title> — <what changed> line per item, Commit: <sha>.

Step 12 — After-Work QA

When rota config show qa.afterWork is true, read `after-work-qa.md`. false (default) → skip silently.

Step 13 — After the Cycle

One line, only when references/post-cycle-trigger-gate.md fires: "Run /rota-learn to save what this cycle taught; /rota-decide, /rota-ship --docs and /rota-refactor are there when you want them." Never auto-invoke any of them. If the cycle touched files in a .rota/map/<name>.md entry's Key files / dirs, bump its touched: and run rota map index.

Gates: Thought → Reality

Thought	Reality
"The subagent said it passed."	Step 7 trusts the diff: git status, git diff and the read files, never the subagent's narrative.
"The check is obvious, skip the proof row."	rota item complete exits 4 without one. An unproven item stays open and is surfaced.
"The new test passes, that's enough."	A test that never failed may not test the change. A behavior task needs a RED run first, recorded as a FAIL row, then the PASS row.
"Pass --no-proof, the code is fine."	Never on your own. The row records what ran; the flag records that nothing did.
"A subagent disputing its brief is noise."	A dispute is a FAIL on the plan. Fix the plan, then re-dispatch.
"Open the PR now, the user wants it shipped."	Opening a PR is a manual gate whatever autonomy.level says (Step 10, /rota-ship Step 6a).
"Run the full smoke after each task."	Per-task checks stay structural. The full suite runs in /rota-ship and /rota-review.

Key Principles

• No noise. Report results, not process.
• The main session owns .rota/ state (status.json, backlog via rota item verbs).
• Never work directly on main.

References

• `references/knowledge-consult.md`: canonical K+D query pattern and hit-register rule.
• `references/context-load-protocol.md`: shared parallel context load (Preview Mode).
• `references/work-preview.md`: --preview procedure.
• `references/task-ledger.md`: Task: trailer and resume rule.
• `references/work-wave-planning.md`: file collisions, brief-writing rules, verifying a completion.
• `references/isolation-patterns.md`: branch, worktree and umbrella layouts.
• `references/issue-mode.md`: issue backend: claim, proof note, PR path.
• `references/umbrella-mode.md`: umbrella registry and Repos: semantics.
• `references/post-cycle-trigger-gate.md`: when the Step 13 learn nudge fires.
• `references/worker-contract.md`: round-worker rules and review-feedback handling.
• `plan-artifact.md`: Step 4 backend keys, saved tasks and resume identity for item and slice plans.
• `no-argument-mode.md`: reconcile, suggest, then work.
• `sibling-sweep.md`: Step 1 / 8.5 tool-generated sibling sweep.
• `contradictions.md`: Step 2.5 contradiction logging.
• `umbrella-and-issue-mode.md`: umbrella and issue-backend branches of Steps 3–11.
• `dispatch-brief.md`: Step 6 brief template.
• `file-backend-close.md`: Step 9 on the file backend.
• `after-work-qa.md`: Step 12.