haacked/dotfiles/go

/go

End-to-end orchestrator: plan → implement (one stage at a time when the plan is staged) → simplify → commit → open draft PR → request a ReviewHog round → run review-code --fix while ReviewHog works → address every review comment → run review-code over the fix commits → simplify the review fixes → mark the PR ready → watch CI to green → request a stamphog approval, unless a code owner has to review the PR → with --merge-pr, merge the approved PR → explain the open items that need the user's judgment.

The run ends with a PR that the user can merge when stamphog approves it, or keep working on when stamphog does not. When the base branch requires code-owner review and the PR touches a path that CODEOWNERS assigns to a team or person, the run reports the PR as waiting on that code owner instead. Without --merge-pr, /go never merges or enqueues the PR. With it, the Merge step merges or enqueues the PR, and only when the merge gate finds it approved at its current head with CI green.

The pipeline is idempotent. .notes/go-state.md tracks progress, so re-running /go reports where the pipeline stands and resumes from the first incomplete or stale step. On a branch /go never drove, it infers position from the session conversation, working tree, branch commits, and PR, then proceeds as if it had been running all along.

The review runs in a fresh CLI process using the same harness as this invocation. The parent keeps the pipeline state and resumes from the saved result. Other stages use the current harness's skills and agents.

Harness

Set HARNESS from the harness running this skill: claude in Claude Code, codex in Codex. Pass it explicitly to the review runner. Installed executables and inherited environment variables do not decide the harness. A missing CLI is an error, not a reason to switch providers. Each CLI uses its configured model and settings; the parent conversation is never passed to it.

Set GO_SKILL_DIR to the absolute directory containing this SKILL.md, using the path supplied by the invoking harness. Use it for runner commands while the working directory remains the implementation worktree.

The Skill(...) and Agent tool examples below describe operations. In Claude, use the Skill and Agent tools. In Codex, read the named installed skill and follow it, applying the repository's execution-tier routing, and use its native subagent tools for agent dispatches. Use a fresh agent without inherited conversation when a prompt below calls for the spec alone. The Review step always uses the CLI runner, even when the review skill has an execution tier. The CI step has a separate Codex route because ci-monitor is excluded from Codex.

Arguments

• <task description> — what to build/fix. Omit to resume: /go detects the branch's position and continues from there (see Determine position).
• --skip-planner — skip the implementation-planner sub-agent; implement directly from the description.
• --skip-reviewhog — don't request or wait on a ReviewHog round; review-code and the explain-open wrap-up still run. Applied automatically outside the PostHog org (ReviewHog is PostHog-internal) and when the @posthog review trigger comment can't be posted.
• --plan-file <path> — use an already-approved plan file directly (e.g. one written by Plan Mode) instead of looking up or generating one. Implies skipping the planner.
• --staged / --single-pass — override the plan's **Execution** line, which decides whether Implement runs its stage loop or its single pass.
• --unattended: nobody is watching the run. /go runs from its resume point through Report without asking, taking the defaults that Unattended runs lists, and stops only where that section says no safe default exists.
• --merge-pr: implies --unattended. After Request stamphog, the Merge step merges the PR, or adds it to the repository's merge queue, when the merge gate passes.
• --yolo: shorthand for --unattended --merge-pr.
• --attended: turn off --unattended and --merge-pr that an earlier run saved in the state file.

Run to the end

/go runs from its resume point to Report in one turn. The user reviews at Report and nowhere earlier. These rules keep the run moving:

• Never end a turn between steps. A message that carries no tool call ends the turn, so write progress notes (a stage landed, a step finished, a flagged call) only in a message that also makes the next tool call, or leave them for Report.
• When any skill or agent returns, its result is input to the next step, not the end of the run. Read the state file's next step and continue.
• Never end the turn to wait on a background command. Block on it with a Monitor until-loop, or poll its status, until it exits. The harness's completion notice is not a reliable wake-up for a long review, ReviewHog round, or CI run. A skill that sets an sb wait under Switchboard and ends the turn is the one exception, because sbd resumes the session when the wait resolves.
• Decide instead of asking, except for the questions Judgment calls says to stop on. Everything else gets the best judgment the plan, the codebase, and that rule support, recorded under ## Flagged calls as Judgment calls describes.
• Stop early only where a step says to stop or no safe choice exists, such as when there is nothing to resume and no task, the base ref can't be resolved, docket's config.toml is broken, every review account is over its limit, the PR is closed or merged, a command needs credentials or approval the harness denied, a Judgment calls question needs the user, or a step failed after two attempts and bug-root-cause-analyzer found no fix. Say what is blocked and what would unblock it.
• A reviewer, bot, or check that has not answered after its wait is not a blocker. Record it and continue to Report.
• Replies to human reviewers stay drafts for Report.

Unattended runs

When UNATTENDED is true, nobody answers a question. The places that would ask take a default instead: Plan, the dramatic-change rule in Judgment calls, Address reviews, and CI each say which. The stops in Run to the end still stop an unattended run, apart from a dramatic-change Judgment call, which takes its default.

Before an unattended run stops, write a ## Blocked section at the end of the state file. It names the step, what is blocked, the question and its options when there is one, and what would unblock it. Then end the turn with a message that opens with Blocked: and repeats that section. A stopped run never reaches the Merge step, and the Merge step also refuses while ## Blocked has an entry. The next /go removes the section once the plan's ## Decisions holds the answer or the cause is gone.

State file

.notes/go-state.md records pipeline progress for the branch. Update the current entry when a step completes, and save the active stage and next action before starting it. Keep one current value per field. An interrupted run resumes from these records after reconciling them with Git and GitHub:

# /go state
branch: haacked/add-dark-mode-toggle
slug: add-dark-mode-toggle
plan: ~/dev/haacked/notes/Dev/repositories/haacked/dotfiles/plans/add-dark-mode-toggle.md
harness: codex
skip-planner: false
skip-reviewhog: false
unattended: true
merge-pr: true
execution: plan
active-stage: review-code
next-action: validate-review-fixes
review-state: .notes/go-review-state.json
review-run: 0b6e4c2a-5d1f-4e8b-9a3c-7f2d1e6b8a40
fix-review-tier: skip 9c1d2e3..f4a5b6c (14 lines)
reviews-addressed-at: 2026-11-04T17:05:00Z
 
-implement: done
-simplify-commit: a1b2c3d
-pr: 123
-reviewhog-requested: a1b2c3d

Step values are git rev-parse --short HEAD captured when the step finished (done for implement, the PR number for pr, the sha at request time or skipped for reviewhog-requested, the sha at the verdict, followed by codeowners when a code owner's review gates the PR, or skipped for stamphog, the sha followed by merged, enqueued, or refused for merge). If branch: doesn't match the current branch, ignore the file and re-infer as Determine position describes. Restore saved options when resuming without new options; reviewhog-requested: skipped also restores SKIP_REVIEWHOG=true for older state files. Update harness to the current invocation's harness. A resumed pipeline may change harness, but every new review must use its current parent harness.

Persist decisions and references as they arise: the original task or brief, user choices, the plan path, unresolved simplify findings, held replies, review artifact paths, and errors with their next action. Save background agent IDs with their assigned work before continuing. After a restart, check whether those agents are still available and whether their outputs exist before dispatching replacements. Record completed tests against the reviewed commit and working-tree fingerprint. Later edits invalidate those results.

scripts/run-review.py owns .notes/go-review-state.json and per-attempt files under .notes/go-reviews/. Do not edit those files to mark work complete. They record the harness, PR, branch, full input SHA, process status, review artifact, and output fingerprint. The runner saves running before launching and reviewed only after validating a successful completion and copying the review artifact. reviewed means fixes await parent validation, not that the Review step is finished. Keep these files until the pipeline finishes; they let a fresh parent recover without the child conversation.

Steps

The steps run in this order: Parse arguments, Determine position, Plan, Implement, Quality passes, Open the PR, Request ReviewHog, Review, Address reviews, Review fix commits, Final simplify, CI, Request stamphog, Merge, and Report. Steps refer to each other by these heading names.

Parse arguments

Extract from $ARGUMENTS:

• SKIP_PLANNER — boolean, true if --skip-planner is present.
• SKIP_REVIEWHOG — boolean, true if --skip-reviewhog is present.
• PLAN_FILE — the path following --plan-file, if present.
• EXECUTION — staged if --staged is present, single-pass if --single-pass is present, otherwise plan.
• MERGE_PR: boolean, true if --merge-pr or --yolo is present.
• UNATTENDED: boolean, true if --unattended, --merge-pr, or --yolo is present.
• --attended sets both MERGE_PR and UNATTENDED to false.
• TASK — everything else, joined with spaces.
• SLUG — short kebab-case identifier derived from TASK (e.g. "add dark mode toggle" → "add-dark-mode-toggle"). Used in commit messages and planner descriptions. If TASK is empty, SLUG comes from the state file, the plan file's first heading, or the branch name — resolved in Determine position.

When none of --unattended, --merge-pr, --yolo, and --attended is present and Determine position resumes, MERGE_PR and UNATTENDED come from the state file's merge-pr and unattended, whatever other options the invocation passes. A new cycle starts with both false, because the earlier task's opt-in to merging does not extend to the next task. Once Determine position has decided between a resume and a new cycle, write the resulting values back to the state file's header.

Determine position

Gather the facts in one round trip:

git check-ignore -q .notes/go-state.md 2>/dev/null || echo '.notes/' >> "$(git rev-parse --git-common-dir)/info/exclude"
git status --porcelain
git log @{u}..HEAD --oneline 2>/dev/null | head -20
git log "$(git merge-base HEAD origin/<default>)"..HEAD --oneline | head -20
git rev-parse --short HEAD
cat .notes/go-state.md 2>/dev/null
gh pr list --head "$(git branch --show-current)" --json number,state,isDraft,labels --jq '.[0] // empty'
~/.dotfiles/ai/skills/ran/scripts/ran-report.sh --json 2>/dev/null