Index of every page on this site: llms.txt
All skills
scode avatar

/scode-build-goal

@03a9f7f
Run it yourself

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.

  • 7 files
  • 165.7 KB
  • Updated 3 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/scode/dotfiles/scode-build-goal

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈281 tokens for metadata: the name and description. ≈12k when used: this file. ≈22k more on demand in 5 files.

An Agent shortens this description

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • Codex shortens descriptions longer than 1,024 characters. Put when-to-use details first.
  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈1126 characters, or 14.1%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 03a9f7f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago

README badge

README badge for scode/dotfiles/scode-build-goal