do

Do Workflow

Take a task and do it top-to-bottom: research, branch, implement, pass CI, open a PR, and ship. (Under --no-git, extend the working tree in place — no branch, commit, or PR.)

Mostly autonomous. Do NOT use AskUserQuestion at any point (except during the --review planning pause). Make sensible default choices and keep moving. If the user wants to skip specific steps, they can say so in the prompt — honor it.

Arguments

Parse the arguments string: [--review] [--no-git] [--minimal] [--from <step-id>] <task description or issue-url>

The workflow is forge-aware: it auto-detects whether the repo lives on GitHub or elsewhere during the sync step (see Forge Detection). Only GitHub has an active code path today — Bitbucket/other forges gracefully skip PR-related steps. Tracking: srid/agency#10.

• --review: Pause after research for user plan approval via EnterPlanMode/ExitPlanMode, then continue autonomously. (hickey/lowy now runs post-implement on a concrete diff, so there's no plan-approval moment attached to that step anymore — the review point is pre-implement, before any code is written.)
• --no-git: Extend the working tree in place — do not create a branch, commit, push, or touch any PR. Research, implement, check, docs, police, fmt, and test all run; git-mutating steps (branch, commit, create-pr) are skipped. Use this when you have uncommitted local work and want the agent to build on it without taking over git state. Feedback from a Bitbucket user in #26.
• --minimal: Skip the steps whose value is disproportionate on trivially-scoped diffs: docs, hickey+lowy, police, and evidence. The remaining flow runs in order: sync → research → branch → implement → check → fmt → commit → test → create-pr → ci → done. Use this when the change is obviously confined (one-line bug fix, typo, config tweak) and structural review / docs sync / quality gate / PR evidence are overkill — PR comments on small /do runs frequently note this. The four skipped steps each record status="skipped" with reason="--minimal".
• --from <step-id>: Start from a specific step (see entry points below)

Results Tracking

Every step is bookended by two scripts/do-results calls: step-start <name> before the work begins, and step-end <status> <verification> [reason] after verification. This is what keeps per-step timing accurate — collapsing both into a single end-of-step call produces zero-second durations and worthless timing tables. The script tracks workflow state and emits the final timing table during done.

Trust the script's stdout. Every mutation echoes a one-line confirmation. Treat that line as your confirmation that the write succeeded; the script is the only public surface, and whatever it persists internally is private.

Lifecycle the script tracks intrinsically:

• Step status — passed, failed, or skipped. A skipped step must include a reason (e.g. "non-github forge: bitbucket", "--no-git", "--minimal", "no check command configured").
• active — state enum (not a boolean). Set to working when the workflow starts (sync), waiting when the agent is idle waiting for an external process (e.g. background CI), back to working when that process returns, and false when done is reached. The stop hook uses this: working blocks exits; waiting and false allow them.
• Workflow status — completed when done finishes, failed if halted. Informational.

Workflow fields /do also stashes via set (the script doesn't interpret these — it just remembers them):

• forge — github, bitbucket, or unknown. Populated by scripts/steps/sync after forge detection.
• noGit — true or false. Reflects the --no-git flag. Git-mutating steps (branch, commit, create-pr) skip with reason="--no-git" when set.

Commands (invoke with the full path, e.g. .../skills/do/scripts/do-results ...):

• init — initialize the workflow's lifecycle skeleton. Echoes init: startedAt=<ts>.
• step-start <name> — call before step work. Echoes pending: <name>.
• step-end <status> "<verification>" ["<reason>"] — call after verification. Echoes recorded: <name> <status> (steps=<count>, pending=<none|name>).
• step <name> <status> "<verification>" <startedAt> <completedAt> ["<reason>"] — single-call form used by scripts/steps/sync where startedAt was captured in shell. Echoes recorded: <name> <status> (steps=<count>). Agent code should prefer step-start / step-end.
• set <field> <value> — set an arbitrary top-level field. Used both for lifecycle (set active waiting, set status completed) and for /do-specific values that sync stashes (set forge github, set noGit false). Echoes set: <field>=<value>.

Discipline:

• Bookend every step with step-start at the top and step-end at the bottom. Calling step-end without a prior step-start is an error; calling step with now for both timestamps collapses duration to 0 — neither pattern is allowed. Exceptions: sync is recorded by scripts/steps/sync itself, and skipped steps (duration always 0) may use back-to-back step-start / step-end skipped.
• Don't run date yourself or guess timestamps — do-results resolves UTC internally.

Progress tracking

Drive Claude Code's native todo UI via the TaskCreate tool so the user sees a live checklist of the workflow. At the start of sync (or the chosen --from entry point), seed a task list with the step names in order:

sync, research, branch, implement, check, docs, fmt, commit, hickey+lowy, police, test, create-pr, ci, evidence, done

Emit all TaskCreate calls as parallel tool_use blocks in a single assistant turn — one model round-trip, not one per task. The seeded steps have no addBlocks / addBlockedBy dependencies, so there is nothing to serialize on. Sequential seeding (15 round-trips before any real work) is a regression: it adds latency to every /do invocation and clutters the transcript with 15 wrapper turns of "Task #N created successfully" before sync even starts.

Under --minimal, omit the four steps the flag skips (docs, hickey+lowy, police, evidence) from the seeded list — the user explicitly opted out of them, so they shouldn't clutter the human-facing checklist. The seeded list becomes 11 items in --minimal runs. (Run-inherent skips like --no-git and forge skips stay in the list — see the Skipped steps rule below.)

The scripts/do-results lifecycle still records --minimal-skipped steps with status="skipped" and reason="--minimal" via back-to-back step-start / step-end calls — that's what keeps the final timing table and completed-status logic correct. The task UI is independent of that recording.

At each step boundary, update task state alongside the scripts/do-results script call — they are not redundant. The script's state drives the stop hook; the task list is the human-facing UI. Miss either and the workflow is inconsistent.

Rules:

• Flip to in_progress when a step starts, completed when it verifies. One step in_progress at a time.
• Retries stay in_progress. If check, test, or ci loop through their retry budget, do not bounce the task state back to pending or flicker it — leave it in_progress until the step finally verifies (or the retries exhaust and the workflow fails).
• --from <step> entry points: still seed the full list (minus any --minimal omissions). Mark steps earlier than the entry point as completed immediately after seeding, so the checklist shows a consistent view regardless of entry point.
• Skipped steps that stay in the list (e.g. branch/commit/create-pr under --no-git, or PR steps on non-GitHub forges) go straight to completed. Record the skip with a back-to-back scripts/do-results step-start <name> / scripts/do-results step-end skipped ... "<reason>"; the task list just shows the step as done. --minimal skips are not in this category — they're omitted from the seeded list entirely (see above), so there's no task entry to flip.
• Failure: if retries exhaust and the workflow halts, leave the failing step in_progress, mark done completed after the failure summary is written, and run scripts/do-results set status failed.

Steps

sync

Run the scripts/steps/sync script in this skill's directory, passing true or false for --no-git:

.../skills/do/scripts/steps/sync <noGit>

The script:

• Fetches origin and pins origin/HEAD

• If --no-git is not set and the branch is behind origin (ahead-count 0), fast-forwards with git pull --ff-only. Under --no-git, fetching happens but the working tree is not touched — uncommitted work is preserved.

• Prints the dirty-tree hint to stderr (no pause) when the tree is dirty and --no-git is not set:

  Dirty tree detected. Continuing will create a fresh branch on top of these changes. If you wanted the agent to extend your WIP in place without touching git, re-run with --no-git.

• Classifies the forge from git remote get-url origin — github.com → github, bitbucket. (covers bitbucket.org and self-hosted servers like bitbucket.juspay.net) → bitbucket, otherwise unknown.

• Calls scripts/do-results init <forge> <noGit> then scripts/do-results step sync passed ....

• Prints forge=<value>, branch=<value>, defaultBranch=<value> on stdout for downstream steps.

Only github has an active code path today. Both bitbucket and unknown cause forge-dependent steps (PR creation, PR comments, PR edits, CI status) to skip gracefully. Bitbucket support is planned — see srid/agency#10.

Verify: Script exited 0 and printed forge=, branch=, `defaul

Content truncated.