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.)

Fully autonomous. Do NOT use AskUserQuestion at any point (unless --review is active during the planning pause). Make sensible default choices and keep moving.

Arguments

Parse the arguments string: [--review] [--no-git] [--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 hickey/lowy for user plan approval via EnterPlanMode/ExitPlanMode, then continue autonomously
• --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.
• --from <step-id>: Start from a specific step (see entry points below)

Results Tracking

After each step's verification, record results via the do-results script. The script manages a JSON file with this schema:

{
  "workflow": "do",
  "startedAt": "<ISO timestamp>",
  "active": "working",
  "status": "running",
  "forge": "github",
  "noGit": false,
  "steps": [
    {
      "name": "sync",
      "status": "passed",
      "verification": "...",
      "startedAt": "...",
      "completedAt": "..."
    }
  ]
}

• forge is set during sync (see Forge Detection below). One of github, bitbucket, unknown.

• noGit is true if the user passed --no-git. When set, git-mutating steps (branch, commit, create-pr) record status skipped with reason "--no-git".

• Step status is one of passed, failed, or skipped. A skipped step must include a reason field explaining why (e.g., "non-github forge: bitbucket", "--no-git", "no check command configured").

• active is a state enum, not a boolean. Set it 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 the external process returns, and false when the workflow ends (done). The stop hook uses this field: "working" blocks exits, "waiting" allows them (with a resume hint), false allows them.

• Set status to "completed" when done is reached, or "failed" if halted. This field is informational only.

• Always use the do-results script (in this skill's directory) — never write the JSON file directly. Commands:

  • Initialize: do-results init <forge> <noGit> — creates the skeleton with a timestamp
  • Record a step: do-results step <name> <status> "<verification>" <startedAt> <completedAt> ["<reason>"] — pass now for either timestamp to auto-generate the current UTC time
  • Update top-level field: do-results set <field> <value> (e.g., set active waiting, set status completed)
  • Patch last step: do-results patch-last <field> <value> (e.g., patch-last completedAt "2026-...")

• Pass now as a timestamp argument to do-results step — the script resolves it to UTC internally. Do not run date yourself or guess timestamps.

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 all 14 step names in order:

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

At each step boundary, update task state alongside the do-results script call — they are not redundant. The JSON file is machine state for 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 all 14 steps. Mark steps earlier than the entry point as completed immediately after seeding, so the checklist shows a consistent 14-item view regardless of entry point.
• Skipped steps (e.g. branch/commit/create-pr under --no-git, or PR steps on non-GitHub forges) go straight to completed. The skip reason is recorded via do-results step <name> skipped ... "<reason>"; the task list just shows the step as done.
• 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 do-results set status failed.

Steps

sync

Run: git fetch origin && git remote set-head origin --auto

If --no-git is NOT set: if current branch is behind origin, fast-forward with git pull --ff-only.

If --no-git is set: do not pull. Fetching the remote is harmless and useful context, but modifying the working tree could conflict with the user's uncommitted work. Leave the branch where it is.

Dirty-tree hint: run git status --porcelain. If it is non-empty and --no-git was NOT passed, print a one-line hint to the terminal:

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.

Do not pause or ask — just print and continue. The user's default-mode invocation is respected.

Forge detection: Inspect git remote get-url origin and classify:

• URL contains github.com → github
• URL contains bitbucket. (covers bitbucket.org and self-hosted Bitbucket Server, e.g. bitbucket.juspay.net) → bitbucket
• Otherwise → unknown

Record the result via do-results set forge <value>. Subsequent steps branch on this value. 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: git fetch ran without error, forge is recorded, and noGit is recorded.

research

Research the task thoroughly before writing code.

• If given a GitHub issue URL and forge == github, fetch with gh issue view. On non-GitHub forges, treat any issue-like URL as opaque context — use the prompt text as-is and do not attempt to fetch. (Bitbucket issue/Jira fetching is tracked in #10.)
• Use Explore subagents, Grep, Glob, Read — whatever it takes to understand the problem
• Never assume how something works. Read the code. Check the config.
• If the prompt involves external tools/libraries, use WebSearch/WebFetch

Verify: Can articulate what needs to change, where, and why.

hickey + lowy

Invoke /hickey and /lowy via the Skill tool. They are completely independent — do NOT wait for one to finish before invoking the other.

<use_parallel_tool_calls> For this step, invoke both Skill("hickey") and Skill("lowy") simultaneously in a single response. Do not include any other tool calls or text — just the two parallel Skill invocations. </use_parallel_tool_calls>

After both complete, revise the approach to eliminate accidental complexity before proceeding.

If --review: Use EnterPlanMode to present the revised approach for user approval:

• Clarify ambiguities first — ask via AskUserQuestion if anything is unclear. Don't guess.
• High-level plan: what to do and why, not implementation details. Include an Architecture section (affected modules, new abstractions, ripple effects).
• Split non-trivial plans into phases — MVP first, each phase functionally self-sufficient.
• Include a Simplicity assessment noting what hickey/lowy found and any trade-offs accepted.

Use ExitPlanMode to present the plan. Once approved, continue autonomously from branch.

Verify: Every finding has an action (fix or defer with issue link). No unactioned findings.

branch

If --no-git: Skip this step entirely with status skipped and reason "--no-git". Stay on the current branch — do not create, commit, or push anything. Move to implement.

Detect the default branch: git symbolic-ref refs/remotes/origin/HEAD

1. Create a descriptive feature branch from origin/<default>

That's it — just the local branch. No commit, no push, no PR. The branch is pushed later in commit, and the PR is created in create-pr after all changes are done.

Verify: On a feature branch (not master/main).

implement

If the task is a bug fix: write a failing test first (e2e or unit, whichever is appropriate), then fix the bug.

Otherwise: implement the planned changes. Prefer simplicity. Do the boring obvious thing.

E2E coverage: When the change introduces multiple user-facing paths (e.g., a dialog that appears under different conditions), write e2e scenarios for each distinct path. Enumerate the user-visible paths, then check that every one has a corresponding test.

Verify: Code changes match the planned approach. All distinct user-facing paths have test coverage.

check

Read the project's instructions to find the check command — a fast static-correctness gate (e.g. tsc --noEmit, cargo check, cabal build, mypy, dune build @check). Run it.

This is the cheapest gate in the pipeline, so it runs first — fail fast on broken code before any downstream step does work over it. If no check command is documented, skip this step with a note.

Verify: Check ran without errors, or no command configured. If failed (max 3 attempts): Fix the errors and re-run check. Do not fall back to implement — the agent is already in fix mode and the failure is local to just-written code.

docs

Read the project's instructions to find which documentation files to keep in sync (e.g., README.md). Compare those files against changes in this PR.

If no documentation files are documented, skip this step with a note.

Verify: Docs match current code. If outdated (max 3 attempts): Fix the outdated sections and re-verify.

police

Use git diff origin/HEAD...HEAD --name-only to check if the PR contains code changes. If all changed files are documentation-only (e.g., .md, .txt, README, docs/) — skip this step with a note.

Otherwise, invoke the /code-police skill via the Skill tool. It runs three passes: rule checklist, fact-check, and elegance.

When /code-police asks about scope: changes in the current branch/PR only.

Cross-reference hickey/lowy actions: After code-police completes, check every hickey and lowy finding marked "Fix in this PR". For each one, verify the diff addresses it. An unaddressed "Fix in this PR" action is a police failure — fix it before proceeding, same as any other police violation. This closes the loop between hickey/lowy (which find structural issues before implementation) and police (which verifies the implementation after).

For followup entry points: Run hickey and lowy on the full cumulative diff (origin/HEAD...HEAD) as part of police. Followups skip the normal hickey/lowy steps (jumping straight to implement), so this is the only structural review the cumulative PR changes get. It catches complexity that accumulates silently across multiple small followups — e.g., a component gaining 12 new props across 5 followups without any structural review catching the prop-drilling pattern. Any findings with "Fix in this PR" actions are police violations — fix them before proceeding.

Verify: All 3 passes clean ("All clear") AND all hickey/lowy "Fix in this PR" actions addressed in the diff. If violations found (max 3 attempts): Fix the violations and re-invoke /code-police.

fmt

Read the project's instructions to find the format command (typically documented in a workflow instruction). Run it.

If no format command is documented, skip this step with a note.

Verify: Format command ran without error, or no command configured.

commit

If --no-git: Skip with status skipped and reason "--no-git". Move to test. The working-tree changes stay uncommitted — that is the point.

Create a NEW commit (never amend) with a conventional commit message. Push to the feature branch with git push -u origin <branch> (sets upstream on first push).

Verify: git log -1 shows a new commit on the feature branch, and it's pushed to remote.

test

Read the project's instructions to find the test command and strategy. Run only the tests relevant to the code paths changed in this PR.

Use git diff origin/HEAD...HEAD --name-only to identify changed files and determine which tests are relevant.

If changes are purely internal with no user-facing impact, unit tests may suffice — skip e2e if no relevant scenarios exist. If no test command is documented, skip with a note.

Verify: Tests pass (exit code 0), or no relevant tests to run. If failed (max 4 attempts): Analyze the failure. If flaky, re-run. If real: fix → go to fmt, then retry.