---
title: "scode-build-goal"
description: "Use only when the user explicitly invokes `$scode-build-goal` or `/scode-build-goal`. Takes a natural-language goal, optionally prefixed with an `in <dir>` clause (also `into`, `under`); picks mnemonic paths for the goal file and its working log (by default beside the checkout, out of the repo; proposes a temporary location when no good place exists), interrogates the user up front to resolve the decisions unattended work will need, then writes a self-resumeable goal file meant to be passed to /goal. No-workhorse mode is the default: the executing session works at its own model, with same-model sub-agents allowed for speed. `galaxy-brain` mode uses scode-galaxy-brain to delegate suitable work to cheaper models; `powerhorse` mode uses scode-powerhorse to supervise large parallel chunks on strong delegates; `shepherd` mode writes it for scode-shepherd, a strong supervisor over a cheap worker; `overseer` mode has the /goal session launch a cheap Claude Code executor through farhelm and oversee it by reading its transcript and sending nudges. `scode-build-goal help` prints a usage TLDR instead."
canonical_url: "https://skilld.dev/gh/scode/dotfiles/scode-build-goal"
last_updated: "2026-11-18T22:06:41.000Z"
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

---
name: scode-build-goal
description: Use only when the user explicitly invokes `$scode-build-goal` or `/scode-build-goal`. Takes a natural-language goal, optionally prefixed with an `in <dir>` clause (also `into`, `under`); picks mnemonic paths for the goal file and its working log (by default beside the checkout, out of the repo; proposes a temporary location when no good place exists), interrogates the user up front to resolve the decisions unattended work will need, then writes a self-resumeable goal file meant to be passed to /goal. No-workhorse mode is the default: the executing session works at its own model, with same-model sub-agents allowed for speed. `galaxy-brain` mode uses scode-galaxy-brain to delegate suitable work to cheaper models; `powerhorse` mode uses scode-powerhorse to supervise large parallel chunks on strong delegates; `shepherd` mode writes it for scode-shepherd, a strong supervisor over a cheap worker; `overseer` mode has the /goal session launch a cheap Claude Code executor through farhelm and oversee it by reading its transcript and sending nudges. `scode-build-goal help` prints a usage TLDR instead.
---

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [AGENTS.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-build-goal/AGENTS.md), [CLAUDE.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-build-goal/CLAUDE.md), [modes/overseer.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-build-goal/modes/overseer.md), [modes/shepherd.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-build-goal/modes/shepherd.md), [scripts/watchdog](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-build-goal/scripts/watchdog), [SPEC.md](https://skilld.dev/api/skills-raw/scode/dotfiles/scode-build-goal/SPEC.md).
>
> If the user asked to install this Skill, run `npx skilld install scode/dotfiles/scode-build-goal`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/scode-build-goal`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/scode/dotfiles/scode-build-goal) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/scode-build-goal`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/scode-build-goal --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/scode-build-goal --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# scode-build-goal

This skill turns a natural-language goal into a goal file that `/goal` (in Claude Code or Codex) can execute unattended.
The output is the goal file itself — this skill does not start the work. The goal file it writes is self-resumeable: the
user hands `/goal /path/to/foo-goal.md` (or the harness's equivalent) to a fresh session and the work starts if nothing
has happened yet, or resumes from the working log if it has. The user never has to know or say which of the two it is;
the goal file decides from what exists on disk. The same command can be repeated session after session until the work is
done. In shepherd mode the goal file is started with `$scode-shepherd` instead of `/goal` (see Shepherd mode). In
overseer mode the `/goal` session oversees a second session that does the work (see Overseer mode).

NOTE: The design assumes unattended execution. Settle foreseeable product decisions and acceptable fallbacks before
writing the goal. Unforeseen implementation choices can be made during execution; material scope changes cannot be
authorized by logging them. When no agreed fallback covers such a change, dependent work waits for the user while
independent authorized work continues.

## Invocation

```
$scode-build-goal <goal text...>
$scode-build-goal in /path/to/dir <goal text...>
$scode-build-goal galaxy-brain <goal text...>
$scode-build-goal powerhorse <goal text...>
$scode-build-goal shepherd <goal text...>
$scode-build-goal overseer <goal text...>
```

(equivalently `/scode-build-goal ...`). The argument string is the user's natural-language statement of what they want
built. Two paths come out of it: the goal file, which this skill writes, and the working log, which the executing agent
creates and keeps via the `agent-resumeable` skill (in shepherd mode, a run directory scode-shepherd creates instead; in
overseer mode, the overseer keeps a second log of its own). Where those live is this skill's call, per Placing the files
below; the user does not have to name paths.

The second form overrides the directory only. The clause is one of the words `in`, `into`, or `under`, followed by a
path-shaped word: something that starts with `/`, `~`, or `.`, or contains a `/`, and ends at the next whitespace (a
directory with a space in its name cannot be given this way). It has to be the first thing after the skill name. When
those conditions hold, both files go in that directory, with their names still derived the way Placing the files
describes, and the override is honored even when the directory is inside a repository; the user asked. The clause says
where the files go and nothing else: it does not choose which repository the goal is about, which is always the checkout
containing the working directory, so `in ~/git/foo` from a checkout of `bar` files a goal about `bar` inside `foo`. When
the conditions do not hold — `$scode-build-goal into the weeds: untangle the config loader` — there is no clause, and
the whole argument string is goal text. Nothing inside the goal text is ever a placement instruction, however much it
sounds like one: "write the results to /srv/reports" or "keep notes in docs/" are part of the executing agent's brief,
and this skill does not mine the brief for where to put its own files. Resolve `<dir>` to an absolute path (relative to
the working directory, `~` expanded), and if it does not exist or is not a writable directory, say so and ask rather
than creating it or falling back to the defaults.

If the entire argument string is `help`, answer in chat with a TLDR — the invocation shapes including the default
no-workhorse mode, galaxy brain mode, powerhorse mode, shepherd mode (whose goal file is started with
`$scode-shepherd`), and overseer mode (whose `/goal` session launches and oversees a farhelm executor), what the two
files are for, where they get put by default, and that the output is a file to pass to `/goal` — and stop. Do not create
or modify anything.

If the goal text is missing, ask rather than guessing.

## No-workhorse mode

By default, no unit of the executing agent's own decomposition goes to a weaker model or a lower effort than its own,
and galaxy-brain plays no part in the run. The reviews the goal file itself calls for are not units of that
decomposition: the review gate keeps the model and effort the goal file demands, and scope reassessment runs at the
executing agent's own model and effort. The goal file forbids invoking, loading, or following `scode-galaxy-brain` or
`scode-model-routing`. If galaxy-brain is already active when the run starts, an explicit no-workhorse choice in the
invocation or up-front answers is the user's instruction to stop it. If this mode was only the default, the executing
agent asks how to resolve the conflict before doing dependent work.

Sub-agents at the executing agent's own model and effort are fine, and worth considering whenever they are likely to
finish the work sooner without costing quality: independent investigations run in parallel, or implementation split
across agents. Whether to use them is the executing agent's judgment call; the goal file encourages thinking about it
but does not require parallelism. If concurrent agents might otherwise conflict, it is fine to run them in separate
worktrees or jj workspaces and merge the results back. The executing agent still owns the `jjstack` stack and every PR.
A native sub-agent is the normal way to launch one, with model and effort set explicitly where the mechanism allows;
when the needed model is not available as a native sub-agent type, `scode-harness-shellout` supplies the launch
mechanics. If the user's request itself rules out sub-agents altogether, that is a settled decision and overrides this
allowance. Do not copy galaxy-brain's concurrency rules (serialized writers, isolation requirements, serial integration)
into the goal file; how to avoid conflicts beyond the worktree allowance is the executing agent's judgment.

The review gate and the scope reassessment review work the same way as in galaxy brain mode: they are not a cheaper
model standing in for the executing agent, they exist to be independent of the author, and that matters no less when the
author wrote every line. The executing agent launches them like any other sub-agent, natively or through
`scode-harness-shellout`. The review gate keeps the model, effort, and skill or charter the goal file demands. The scope
reassessment review, for which the goal file names no model, runs at the executing agent's own model and effort.

The mode applies unless the user requests galaxy brain mode, powerhorse mode, shepherd mode, or overseer mode. The
existing `no-workhorse` switch and plain-language requests that the executing agent work at its own model also select it
explicitly. Remove only a switch consumed as a mode choice; a quoted, negated, path-embedded, or subject-of-the-goal
mention stays in the goal text. An unclear request about delegation belongs in the up-front batch rather than being
guessed. The `in <dir>` clause still has to come first, and `help` still requires the entire argument string.

## Galaxy brain mode

The `galaxy-brain` switch, or a plain-language request to delegate suitable work to cheaper models, selects galaxy brain
mode. A quoted, negated, path-embedded, or subject-of-the-goal mention does not select it. Remove only a switch consumed
as the mode choice. The goal file requires the executing agent to use `scode-galaxy-brain` for the entire run: it hands
suitable units of its own work (implementation, mechanical edits, searches, fixups) to cheaper or faster models while
keeping planning, gating, and version control for itself. The review gate and scope reassessment review run through that
skill. The review gate keeps the model and effort the goal file demands; scope reassessment has no named model in the
goal file.

## Powerhorse mode

Powerhorse mode requires `scode-powerhorse` for the whole run, and the executing agent supervises large, independent
chunks of the work running in parallel on strong delegates (by default at its own model), aiming to finish sooner at
equal quality. Galaxy-brain plays no part in such a run. The goal file forbids invoking or loading it, and if it is
somehow already active when the run starts, the goal file is the user's express instruction to stop it. Only one of the
two orchestrators is ever loaded.

Everything else the goal file requires stays the same: the resume protocol, the planning outline and scope reassessment,
PR discipline, decision logging, the unattended fallback, the done criterion, and the review gate the user picks from
the menu. The review gate and the scope reassessment review are launched through powerhorse instead of galaxy-brain. The
review gate keeps the model, effort, and skill the goal file demands.

Three choices exist only in this mode, and the up-front batch states a default for each so the user can override it with
one line:

- The worker model: the model and effort of the session that first runs the goal, unless the user names another. A model
  named for the workers, in the invocation or in an answer ("use gpt-6.2 sol high for the powerhorses", "chunks on
  fable"), sets it, at the effort named or the executing session's own effort when none is. A model named for the
  reviewer sets the review gate, per Review gate options. When it is unclear which role a named model is for, ask. When
  the named worker model needs a CLI this machine lacks (`codex` for GPT, for example), say so in the batch; either way
  the goal file records what happens if the model is unreachable at run time, which by default is that the executing
  agent pauses the chunks that need it and asks.
- The width: at most two writer chunks in flight at once unless the user picks another number. More is not automatically
  faster, since every chunk waits on the executing agent at its checkpoints, gate, and integration.
- PR sizing: in this mode a PR defaults to one chunk (one coherent change with its tests). The user may instead keep the
  default bite-sized PRs, in which case a chunk spanning several PRs has its spec name the boundaries (file sets, or
  ordered stages each of which passes the checks) so the executing agent can split the result.

The mode is on when the argument string asks for it: the word `powerhorse` used as a switch, or a plain-language request
that the executing agent supervise large parallel chunks on strong models rather than delegating to cheaper ones. The
same rules as for `galaxy-brain` decide what is a switch and what is a mention, and an unclear request is asked about. A
request that asks for more than one mode is asked about, never resolved by guessing.

## Shepherd mode

The `shepherd` switch, or a plain-language request to run the goal under scode-shepherd, selects shepherd mode. The same
rules as for `galaxy-brain` decide what is a switch and what is a mention, and a request for more than one mode is asked
about. A goal that is about scode-shepherd (`$scode-build-goal teach scode-shepherd to run Claude workers`) is a
mention, not a request. `shepherd` is also an ordinary word: when it is part of the goal's own wording, as a verb
(`$scode-build-goal shepherd the 2.0 migration through CI`) or a noun (`$scode-build-goal shepherd runner: add a
--dry-run flag`), it is goal text, not a switch, and when it could be either, ask. When the mode is on, read
`modes/shepherd.md` next to this file in full before the up-front questions: it changes the review gate menu, the
placement, the goal file's contents, and how the user starts the run, and it governs wherever it and this file differ.
In every other mode, do not read it.

## Overseer mode

The `overseer` switch, or a plain-language request that the goal session oversee a separate executor session (launched
through farhelm, by transcript and nudges) rather than do the work itself, selects overseer mode. The same rules as for
`galaxy-brain` decide what is a switch and what is a mention, and a request for more than one mode is asked about. A
goal that is about overseeing or about an overseer (`$scode-build-goal overseer: show the last nudge in the status
line`, `$scode-build-goal add an overseer role to the job scheduler`) is goal text, and when it could be either, ask.
When the mode is on, read `modes/overseer.md` next to this file in full before the up-front questions: it changes the
batch, the placement, the goal file's contents, and how the user starts the run, and it governs wherever it and this
file differ. In every other mode, do not read it.

## Placing the files

The point of picking the paths here is that the user should never have to invent two filenames to get an unattended run
started, and should never be handed an anonymous id as a filename either. Both files get a mnemonic name, and by default
they live outside the repository but next to it, so that the run cannot commit them by accident and a later session (or
the user, scanning a directory listing weeks later) can find them again without remembering anything.

Naming first. Derive a short kebab-case slug from the goal, the kind of thing a person would type from memory:
`build-bar-and-baz`, `farhelm-dist`, `patreon-buddy`. Lead with the project name (`farhelm-dist`, not `dist`) unless the
directory that will hold the files is dedicated to that one project; the default directory never is, since it holds the
checkout's siblings. The project name is the basename of the checkout directory (the outermost one, when checkouts are
nested), not a package name or a remote name, so two agents given the same goal in the same checkout produce the same
slug. Never a UUID, a timestamp, a session id, or anything else the user could not reproduce from the goal itself. The
goal file is `<slug>-goal.md` and the log is `<slug>-goal-log.md`; the shared prefix keeps the pair adjacent in a
listing and makes the log's role obvious.

In shepherd mode a run directory takes the log's place; `modes/shepherd.md` says how it is named. In overseer mode a
second log sits next to the first; `modes/overseer.md` says how it is named.

Where they go. An `in <dir>` clause on the invocation (see Invocation) settles this outright: both files go in that
directory and the list below is skipped. Otherwise, in order of preference:

1. **The parent directory of the repository checkout.** The checkout is the one containing the working directory, and
   the repository the goal text talks about does not change this. Find it by taking `$PWD` as the shell reports it and
   walking up to the nearest directory containing `.git` or `.jj`; do not use `git rev-parse --show-toplevel` or `jj
   root` for this step, since both resolve symlinks and a checkout at `~/git/foo -> /data/repos/foo` should get its
   files in `~/git`, not `/data/repos`. When that checkout is itself nested inside another (a worktree at
   `~/git/foo/.worktrees/bar`, a vendored repo), keep walking up and use the outermost checkout's parent. A working tree
   rooted at the home directory (a dotfiles arrangement) is never counted as a checkout in this section: it neither
   makes `~/git/foo` a nested checkout nor makes `~/git` count as inside a repository, or every invocation on such a
   machine would fall through. So for a goal "add a --verbose flag" in a checkout at `~/git/foo`, the files are
   `~/git/foo-verbose-goal.md` and `~/git/foo-verbose-goal-log.md`, and for a checkout at `~/dotfiles` they are
   `~/dotfiles-verbose-goal.md` and `~/dotfiles-verbose-goal-log.md`; the home directory is a fine parent. This is the
   default whenever the work is in a repository, and it is what to do in the common case. The parent has to be writable,
   and as a sanity check `git rev-parse --show-toplevel` and `jj root` run from it must both fail or report the home
   directory. When any of that fails, fall through.
2. **A proposed temporary location, confirmed by the user.** When there is no repository, or the parent directory is
   unsuitable, propose a path for a fresh directory under the harness's per-session scratch space or the system temp
   directory, name both files there under the same mnemonic names, and present the paths to the user as a proposal.
   Create the directory only once the user accepts. Say plainly that the location is temporary and may not survive a
   reboot or a scratch cleanup; the user is the one who knows a durable place, and the proposal exists so they can name
   it with one line. Do not write anything until they answer.

Whichever case applies, including the `in <dir>` case, the chosen paths go into the up-front questions batch below, so
the user sees them before anything is written and can override with a word. In the default and `in <dir>` cases that is
a statement, not a question: "Goal file at X, log at Y unless you want them elsewhere", adding that the directory is
inside a repository when it is. In the temporary-location case it is a blocking question. There is no case where the
paths are silently decided and only discoverable by reading the goal file.

The goal file never names the checkout by path. It assumes the session that runs it was started inside a checkout of the
project, and that checkout is whichever one the session finds itself in: the user may have several clones, and the one
the goal was planned in is not necessarily the one it runs in. So the goal file names the project by something no clone
changes, writes the paths of project files it refers to relative to the checkout root, and does not record the planning
checkout's state (its current commit, bookmarks, or where `main` was) as a fact the run can rely on; the executing agent
reads that state when it starts. Worktrees and workspaces the run creates are the executing agent's to place at run
time.

The project's identity is the GitHub repository its PRs go to, as `owner/repo`. The planning checkout here is the
nearest checkout containing the working directory, the same one the run's checkout check examines, not the outermost one
used above to place files. When its remotes name more than one GitHub repository (a fork with an `upstream`, say), the
identity is the one the PRs target, and when that is unclear, ask in the up-front batch. A checkout counts as the
project when any of its remotes points at that repository, compared as host, owner, and name (an SSH and an HTTPS URL
for the same repository match, with or without `.git`), so a fork's clone with an `upstream` remote passes and a fork's
clone without one does not. A project with no GitHub remote is identified by its root commit id instead (`git rev-list
--max-parents=0 HEAD`, the oldest commit when there are several), which every clone of it shares.

The goal file's own run files — the goal file, the log, the watchdog script and status file, scratch directories, and
anything else the Q&A settles outside the project's source — are written in absolute form, even when an `in <dir>`
clause put them inside the checkout. They are the same files whichever checkout or working directory the goal runs from,
so a relative one would be a resumption bug waiting to happen, and an absolute one inside a checkout says where the file
is, not which checkout the run works in.

NOTE: This skill writes the goal file only. Never create the log file, not even an empty one or one with a heading: the
goal file's resume protocol treats the log's existence as the signal that a previous session already started, so a log
created here would make the first `/goal` run "resume" from nothing. If a goal or log file with the chosen name already
exists, never overwrite or remove it without asking. Either refine the slug with another word from the goal (not a
counter or a date) so the new pair is distinct, or, when the existing files really are an earlier attempt at the same
goal, ask the user whether to replace them. Replacing means moving both existing files aside under a dated suffix
(`<name>.archive-YYYY-MM-DD.md`), never deleting them, and never leaving the old log in place: a leftover log would make
the new goal's first run resume from the old attempt. A leftover watchdog status file (`<slug>-goal-watchdog.json`, see
Resource watchdog) moves aside with them, as `<slug>-goal-watchdog.archive-YYYY-MM-DD.json` (after stopping any sampler
still writing it), since it carries the old attempt's alert state.

## Up-front questions

Before writing the goal file, close the gaps that would otherwise stall or derail an unattended run. First do enough
reading (the repo, existing docs, prior art) to answer what is answerable without the user — do not ask questions the
codebase already answers. Then ask the user about what remains, batched rather than dribbled:

- Scope boundaries: what is explicitly in, what is explicitly out, and what "done" looks like beyond the mechanical
  PR-stack criterion below.
- Design forks: places where the goal could reasonably be built more than one way — technology choices, API shape, data
  model, user-visible behavior. Ask about the forks you can foresee; for the ones you cannot, the goal file's unattended
  fallback rules bound what the executor can decide.
- Constraints and tradeoffs: performance vs simplicity, compatibility requirements, anything the user would veto if they
  saw it in review.
- PR shaping: any preference about how the work should be sliced, beyond the default bite-sized-stack rules (in
  powerhorse mode, beyond the PR-sizing default that Powerhorse mode lists).
- Review gate: which reviewer checks each PR before it is finished, chosen from the menu in Review gate options below.
  Present the menu every time, numbered as it appears there, with the first option marked as the default taken if the
  user does not care.
- Delegation mode: no-workhorse (the default), galaxy brain, powerhorse, shepherd, or overseer, per the mode sections
  above, stated rather than asked unless the request was ambiguous, so a misread costs the user one line to fix. In
  powerhorse mode, also state the defaults for the worker model, the width, and PR sizing that Powerhorse mode lists. In
  shepherd mode, state what `modes/shepherd.md` lists, and in overseer mode what `modes/overseer.md` lists.
- If no-workhorse applies only by default, state the fallback for an executing session that already has galaxy-brain
  active: the executor asks how to resolve that conflict before dependent work. The user can instead explicitly choose
  no-workhorse now, which authorizes stopping galaxy-brain, or choose galaxy brain mode.
- File placement: the goal and log paths chosen per Placing the files, stated so the user can override them, or put as a
  question when only a temporary location was available.

Resolve consequential choices and fallbacks, not every hypothetical edge case. Show their aggregate implementation cost
using the outline below; piecemeal approval of user-facing behavior does not approve every mechanism attached to it.
Record the actual answers as settled decisions, keeping planner proposals distinct.

## Implementation outline and scope review

Before finalizing the goal, show a short, repository-grounded outline: the existing path to extend, the existing
mechanisms the work reuses or generalizes, the smallest design that satisfies the request, substantial new persistent
state or subsystems, and promises that drive the cost. Compare with the nearest existing implementation when useful.
Explain the size and uncertainty in terms of mechanisms and validation needed; do not invent precise line counts or turn
estimates into targets. A routine change may need only a paragraph. The outline exposes consequential choices, not a
detailed prescription for every defensive helper.

Keep three sources of requirements distinct in the goal: the user's request and later decisions (retain their relevant
words), binding repository constraints (cite the source), and planner-proposed implementation choices with reasons.
Trace substantial mechanisms to the requirement they serve. Start with existing facilities and ordinary libraries; extra
machinery needs a concrete contract or demonstrated failure the smaller design cannot handle. An unsupported case can be
refused only when that still meets the agreed behavior. Neither novelty nor an unfamiliar technology alone proves
overengineering.

Small is not the only test. Keeping a plan small and avoiding duplication pull against each other, and neither wins by
default. A plan that stays small by building a second copy of something the repository already has (another retry loop,
config loader, or path helper beside the existing one) is not simpler; it moves the cost to whoever later has to keep
the two in step. A plan that generalizes an existing mechanism for uses nobody has asked for is the overengineering this
section exists to prevent. So when the work needs something that does substantially the same job as an existing
mechanism, reuse that mechanism as it stands when it fits. When it does not quite fit, weigh generalizing it just far
enough to serve the callers actually in hand against keeping a separate implementation, which is the better answer when
sharing would blur two different contracts (reusing whatever smaller piece does fit, such as a backoff calculation). Say
in the outline which one the plan does and why. A clear-cut case is the planner's to settle. A close one is a judgment
call for the user, raised during planning with the options and what each costs, and recorded as a settled decision: for
example when generalizing would reach into code the goal otherwise leaves alone, change behavior other callers rely on,
or the overlap is partial enough that the shared shape is unclear. Do not ask about every helper; this is for mechanisms
whose duplication or generalization a reviewer of the finished stack would question.

Run one fresh-context planning review before writing the final goal. Use a native sub-agent at the planning session's
model unless the user specifies otherwise; this is a focused review, separate from the per-PR menu, not a swarm or a
reason to activate the execution workflow. Supply the original request, later user decisions, proposed goal and outline,
relevant repository constraints and existing implementation paths. Give it this charter:

> Identify where this plan does more than the user needs, and where it duplicates a mechanism the repository already
> has. For each substantial new mechanism, explain which requirement makes it necessary and whether an existing facility
> or narrower supported behavior would suffice. Where the plan builds something that does substantially the same job as
> an existing mechanism, say whether that mechanism could be reused as it stands or generalized to serve both uses, or
> whether keeping them separate is better because sharing would blur two different contracts, and what generalizing
> would cost; never propose generalizing beyond the uses the plan actually has. Weigh the two against each other: a plan
> is not simpler for copying a mechanism, and not better for generalizing one nobody else needs. Propose the smallest
> coherent design that avoids needless duplication. Challenge planner-authored requirements; identify any simplification
> that would change an explicit user requirement or repository constraint, and mark any reuse-versus-duplication choice
> that is a close judgment call rather than clear-cut. Report concrete findings and alternatives, or say no unnecessary
> complexity or duplication was found. Do not manufacture objections, add safeguards to justify an unnecessary
> subsystem, or add abstraction to justify a generalization. Write findings to the supplied private file; change no
> product files or VCS state.

Name that private findings file in the prompt. Assess the findings, remove unjustified planner obligations, and ask only
about unresolved product tradeoffs and the close reuse-versus-duplication calls. A reviewer cannot authorize weaker
behavior. Recheck affected conclusions if the resolution materially changes the outline; do not repeat the whole review
for wording fixes. If fresh-context review is unavailable, report the limitation before finalizing rather than calling a
self-review independent.

## Review gate options

Every PR in the stack gets reviewed before the executing agent finishes it, and the reviewer is chosen up front rather
than fixed here, because the right one depends on the goal, on which subscriptions have headroom that week, and on how
much the user trusts the model doing the writing. The menu, in the order and numbering to present it:

1. A single fresh-context agent with the general charter below on opus high. The default.
2. A single fresh-context agent with the general charter below on gpt-6.2-sol high.
3. A single fresh-context agent with the general charter below on gpt-6.2-astra high.
4. Other: a plain-text answer naming any other reviewer, such as another model or effort for the single agent, or a
   `pre-pr-review-swarm` run.

In shepherd mode, `modes/shepherd.md` changes the default and what can be chosen.

Every option runs on the model it names, shelled out to the other harness when the executing one cannot reach that model
natively. An Other answer that names a model without an effort runs at high.

A swarm is only ever the reviewer when the user asks for one: by saying "swarm" or naming `pre-pr-review-swarm`, in the
invocation or in an Other answer. The menu offers no swarm option and no default ever is one. A reviewer request that
names only a model and effort ("gpt 6.2 sol high reviewer", "review with fable") is a single charter agent on that
model, never the swarm on it. A swarm fans out many reviewers per PR, which costs far more than one agent, so it is not
something to infer from a model name. When the request already names a reviewer, the batch still shows the menu but
states which option that request maps to, so a misread costs the user one line to fix. A request for a swarm that names
no model is asked about, not guessed.

A swarm runs a skill, and the reviewer's charter is that skill's. Every other reviewer runs no skill; the goal file
carries the charter itself, and it has to be complete because the reviewer has nothing else: review the PR's changes for
general correctness (bugs, unhandled cases, broken invariants, wrong behavior against the goal's acceptance criteria),
design (whether the shape of the change fits the codebase and the goal, and whether a simpler shape would), and
idiomatic code for the languages involved; report findings to a named file, most severe first, with the file, the quoted
code, what is wrong, and the smallest fix; edit nothing and touch no VCS state. "Fresh context" means a sub agent or
shelled-out session that starts with none of the executing session's conversation, which is what makes the review
independent of the author.

Whichever option is chosen, the goal file records it as an explicit demand for that model, effort, and (for a swarm)
skill, so that whatever launches the review honors it as a demand rather than treating the review as a unit to choose a
model for on its own. In galaxy brain mode that is `scode-galaxy-brain`, whose routing honors the demand; in powerhorse
mode it is `scode-powerhorse`, which runs a spawn the goal file defines at exactly the demanded model. In those two
modes the orchestration skill is what makes the launch mechanics, the shell-out when one is needed, and the result gate
someone else's problem. In no-workhorse mode there is no orchestration skill: the executing agent launches the reviewer
itself at the demanded model, as a native sub-agent or through `scode-harness-shellout`.

## What the goal file must contain

Write the goal file as instructions addressed to the executing agent. It must be self-contained: the executing session
has none of this conversation's context. In shepherd mode, `modes/shepherd.md` says which of these items change; in
overseer mode, `modes/overseer.md` does. Include, at minimum:

- **The goal.** The user's intent, sharpened by the Q&A. State the acceptance criteria.
- **Decisions already made.** The Q&A answers, phrased as settled decisions with their reasoning. The executing agent
  must not silently reverse these.
- **Implementation outline and requirement sources.** Carry the reviewed outline, the distinct requirement sources, and
  agreed fallbacks above into the goal. Preserve the original request and later decisions so a reviewer can challenge
  the planner's interpretation rather than merely checking compliance with it. Name the existing mechanisms the outline
  reuses or generalizes, so the executing agent builds on them instead of beside them.
- **Scope reassessment.** Before implementing a substantial departure from the outline, use a fresh-context review with
  the planning charter above, included in full in the goal. Supply the request, decisions, outline, current diff, and
  proposed departure: what changed, why it is necessary, and which simpler alternative was ruled out. A new parser,
  installation registry, recovery protocol, or compatibility layer can signal such a departure, and so can a new
  mechanism that does the job of an existing one or a generalization the outline did not plan; these are examples, not a
  blacklist. A close reuse-versus-duplication call that planning did not foresee is a routine fork under that boundary
  when every option stays within the agreed scope: decide it after the reassessment and log it as DECISION. Repeated
  corrective reviews of the same component also require reassessing its necessity before another repair round. Reuse an
  existing review or delegation checkpoint that can answer this question, rather than scheduling periodic swarms or
  reviewing every helper. Apply the same decision boundary as Unattended fallback below. Give delegates bounded units
  within the outline; unapproved new mechanisms are outside their task. If discovered mid-unit, leave that part
  unimplemented and report the dependency at the existing checkpoint, with checks and incomplete work stated honestly;
  do not require the delegate to build it merely to satisfy the completion checkpoint. In no-workhorse mode these
  sentences apply to whatever same-model sub-agents the executing agent chooses to run, and the checkpoint is simply the
  sub-agent's report back.
- **The checkout.** State that the goal runs inside a checkout of the project, identified as in Placing the files (by
  its GitHub repository or root commit, never by path), and that the checkout is the nearest Git worktree or jj
  workspace containing the session's working directory (a `.git` file counts as well as a `.git` directory). That is the
  innermost one, not the outermost one Placing the files uses for file placement, and an enclosing checkout is never
  tried after the nearest one fails. The executing agent's first action is to confirm that the nearest checkout is one
  of the project. When it is not, it stops before the resume protocol, writes nothing (the log included, since a log
  created from the wrong place would make the next run resume), and tells the user to start the goal from a checkout of
  the project. Every project file path in the goal file is relative to that checkout's root.
- **Resume protocol.** Right after the checkout check, invoke the `agent-resumeable` skill with the log file's absolute
  path. Spell out the semantics even though that skill also enforces them: if the log file already exists, read it and
  resume where the previous session left off — cross-checking the log against reality (VCS state, open PRs) — rather
  than starting over. If it does not exist, this is a fresh start. This is what makes the goal file self-resumeable.
- **Execution mode.** In the default no-workhorse mode, state what No-workhorse mode lists: this goal forbids sending
  any unit of the executing agent's own decomposition to a weaker model or a lower effort than its own (the review gate
  keeps the model and effort the goal file demands, while scope reassessment runs at the executing agent's own model and
  effort), and forbids invoking, loading, or following `scode-galaxy-brain` or `scode-model-routing` at any point (if
  galaxy-brain is already active, an explicit no-workhorse choice tells the executor to stop it; if no-workhorse was
  only the default, the executor asks how to resolve the conflict before dependent work); sub-agents at the executing
  agent's own model and effort are fine and worth considering when they are likely to finish the work sooner without
  costing quality, at the agent's judgment; concurrent agents that might otherwise conflict can run in separate
  worktrees or jj workspaces whose results the agent merges back; the scope reassessment review runs at the executing
  agent's own model and effort; and a sub-agent whose model is not available as a native sub-agent type, the reviewers
  included, is launched through `$scode-harness-shellout`. In galaxy brain mode, state explicitly that the user requires
  the executing agent to use `$scode-galaxy-brain` for the entire goal. Invoke it immediately after the resume protocol
  and keep it active through every delegation; merely reading it for mechanics does not satisfy this requirement. In
  powerhorse mode, require `$scode-powerhorse` instead for the entire run, invoked immediately after the resume protocol
  and kept active throughout. Forbid invoking, loading, or following `scode-galaxy-brain` or `scode-model-routing` at
  any point; if galaxy-brain is already active, this goal file is the user's express instruction to stop it. Carry the
  settled worker model, width, and PR-sizing choice from Powerhorse mode as explicit demands. Give powerhorse's chunk
  table its own absolute path next to the working log, `<slug>-goal-chunks.md`, which this skill does not create; the
  chunk table is edited in place, which the append-only log cannot be. Say that the per-PR review gate runs while other
  chunks continue, and that waiting for it holds back only that PR being marked finished and anything stacked on a
  rewrite of it.
- **PR discipline.** Split the work into a linear stack of reviewable PRs using the `jjstack` skill. Err on the side of
  bite-sized PRs (in powerhorse mode, size PRs per the settled PR-sizing choice instead), but do not create churn — code
  added in one PR and deleted in a later PR of the same stack means the stack should have been shaped differently.
  Restructure the stack instead of stacking a correction on top.
- **Review gate.** Before finishing any PR, delegate a review of its changes to the reviewer chosen from Review gate
  options. In no-workhorse mode, the executing agent launches the reviewer natively or through `scode-harness-shellout`.
  In galaxy brain or powerhorse mode, it uses the active orchestration skill. Name the reviewer in the goal file as an
  explicit demand for its model, effort, and skill or charter, and address what it finds before moving on (in powerhorse
  mode, with the concurrency described under Execution mode). Do not write a launch command into the goal file; the
  `scode-harness-shellout` skill's harness files own the launch mechanics, and a copy pasted into a goal file drifts
  away from the guards they carry. The review prompt must name the skill (or carry the full charter), the repo root (the
  root of the checkout the executing agent runs in, which it fills in at run time), the commit range or bookmark to
  review, and the file the findings go to; the reviewer has no other context.
- **Resource watchdog.** Right after the resume protocol in no-workhorse mode, or after activating the orchestration
  skill in galaxy brain or powerhorse mode, and before the first delegation, the executing agent must start this skill's
  watchdog to watch memory and disk for the rest of the run, and act when either is heading for exhaustion. This is
  mandatory, not a suggestion: unattended runs fan out delegates and worktrees, a Rust worktree costs on the order of
  1.5 GB of build output, tests leave temp directories behind, and a full disk or an OOM kill ends a run
  mid-implementation with no signal to the orchestrator beyond a dead delegate. The watchdog is the Deno script
  `scripts/watchdog` next to this `SKILL.md`; its module docs describe each subcommand's output. When this machine has
  no `deno`, say so in the up-front batch. The goal file spells out everything below, with absolute paths for everything
  outside the checkout, so the executing agent writes no watchdog of its own:
  - **What it watches.** The script's path with symlinks resolved (`realpath`), so it is the same file whichever harness
    runs the goal. The status file, `<slug>-goal-watchdog.json` next to the working log, which this skill does not
    create. The watched paths, each passed to `sample` as `--path`: the root of the checkout the executing session runs
    in (which the session adds when it starts the sampler; the goal file does not name it), the home directory, `/tmp`,
    the directory holding the status file, the executing session's own scratch directory (which it adds when it starts
    the sampler), and any worktree or build directory the run later creates on another filesystem (restart the sampler
    with it added; a path that no longer exists is measured at its nearest existing parent). The interval, 60 seconds.
    The script's default alert levels, unless the user asked for others: a filesystem under 5 GiB free (or under a
    quarter of its size, for one smaller than 20 GiB), or under 10% free while also under 20 GiB; memory, including any
    cgroup limit, under 10% available while also under 4 GiB. It reports a shortage once, again each time it loses
    another quarter, and once when it recovers.
  - **Claude Code.** Run `watchdog observe --status <file>` under the Monitor tool, and `watchdog sample --status <file>
    --path <dir>...` under a second Monitor, both at the maximum timeout (30 minutes). Every line either prints is a
    notification, and a quiet sample prints nothing. The observer reports `STALE` once the status file is two sample
    intervals old, which catches a sampler that hangs without exiting. Keep the two in step: whenever either is re-armed
    or restarted, stop the other and arm both again, observer first, then run `check`. An expiry notice is routine, not
    an exit; a monitor exit is a monitoring failure.
  - **Codex.** Arm the observer, `watchdog observe --status <file> --exit-on-event`, and then the sampler, with the same
    arguments as in Claude Code, as two separate runs through the `skillette-codex-wake-on-exit` mechanism (load the
    `skillette` skill and follow that entry), then run `check` and keep working on the goal. The observer goes first
    because it relays only events recorded after it started. The sampler keeps sampling and never exits on purpose, so
    its run wakes the session only if it dies. The observer exits with status 10, printing the event, on the first event
    the sampler records after the observer started or on a heartbeat going stale (one already stale when it starts does
    not count). On that callback, acknowledge it and arm a fresh observer; after a `STALE`, also stop the hung sampler
    with `wake-on-exit stop` (which queues no wake-up), act on any alert in that run's `stdout.log` (it may have been
    unable to write the status file), and arm a new one; then run `check` and act. Stop this session's own runs only
    through their handles. The wake-up arrives when the current turn ends, and only an interactive session with a
    connected client receives it; a `codex exec` session uses the fallback below.
  - **Acting on it.** A shortage (an `ALERT` or `WORSE` line, or `check` reporting a resource short) is an instruction
    to act, not to note: stop launching new delegates, remove gated worktrees and build caches the run owns, wait for or
    kill the delegate most likely responsible, and resume launches only once `check` passes again. When nothing the run
    owns can free enough, record the shortage in the log as a blocker; launches stay paused. A monitoring failure (a
    `STALE` or `ERROR` line, a monitor exit, or `check` failing on heartbeat age or an unreadable source) pauses new
    launches until monitoring is restored and `check` passes: restart a dead or hung sampler, after stopping a hung one
    (its Monitor, its wake-on-exit run, or the `pid` in the status file) so two never write the same status file. A
    sampler that dies again before writing a sample, or a source that stays unreadable after a restart, is logged as a
    blocker and not retried before the next natural boundary; launches stay paused. A `RECOVERED` or `FRESH` line needs
    nothing beyond that `check`. Run `watchdog check --status <file>` before every new workload launch, batched with
    other required observations, and at natural boundaries (a delegate returning, a PR finished, a handoff).
  - **Verification.** In each session, before starting the real monitors, prove the mechanism on new throwaway status
    files in the scratch directory with `--interval 5`, run the same way as the real ones: a sampler run with
    `--synthetic-alert` delivers an `ALERT`; a sampler killed through the `pid` in its status file is reported as an
    exit; and a sampler run with `--stall-after 2`, watched by its own observer armed first, produces `STALE` within two
    sample intervals of the sample it missed. In Codex these callbacks, like the real ones, arrive at turn ends. Stop
    the throwaway runs afterwards.
  - **Fallback.** When the harness has neither mechanism, or the mechanism fails verification, say so in the log, run
    the sampler as a plain background process, and rely on `check` before launches and at boundaries. Do not poll the
    status file on a timer, do not lengthen the sampling interval to save model turns, and do not count a process-exit
    notification as delivering intermediate alerts from a sampler that is still running. Without `deno` there is no
    watchdog at all, which is a dead monitor: launches pause until it is installed.
  - **Lifecycle.** Record the monitor handles (Monitor task ids, or wake-on-exit run ids and directories), the status
    and watched paths, and the delivery mechanism in the log, and carry the watchdog's running state in every handoff
    note so a resumed session reconciles the existing monitors or restarts them. When the status file's heartbeat is
    still fresh at the start of a session, an earlier session's monitors are still running: stop them through the
    handles the log records where that works (a resumed Codex thread can still use its own), and otherwise kill the
    `pid` the status file names, before starting this session's own. Ignore callbacks from runs this session did not
    arm. A resumed session runs `check` before its first launch, because the sampler does not repeat an alert it already
    delivered. Stop the owned monitors (`TaskStop`, or `wake-on-exit stop`) when the goal is done.
- **Decision logging.** Log major design decisions in the working log as they happen, with a scannable DECISION label —
  especially decisions that could reasonably have gone another way. The user will later ask for the major decisions in
  order to revisit them, so an unlogged decision is effectively a hidden one.
- **Unattended fallback.** Resolve routine implementation forks within the agreed scope and log consequential choices as
  DECISION with the alternatives considered. Remove unnecessary planner-invented machinery when the requested behavior
  and repository constraints still hold. A material scope expansion, weakened guarantee, or omitted required behavior
  needs an already agreed fallback or a user decision. If neither is available, record the concrete tradeoff and pause
  only dependent work pending that decision; continue independent authorized work without claiming completion. A review
  finding or a decision log is not authorization. When the user reduces scope, rewrite the active obligations and remove
  excluded code and validation gates rather than preserving them as latent completion requirements.
- **Done criterion.** The goal is achieved when a linear stack of open PRs — open, not merged — collectively achieves
  the goal. Merging is the user's job.
