diff --git a/agent-skills/scode-build-goal/AGENTS.md b/agent-skills/scode-build-goal/AGENTS.md index 0d78724..d8b7c02 100644 --- a/agent-skills/scode-build-goal/AGENTS.md +++ b/agent-skills/scode-build-goal/AGENTS.md @@ -35,27 +35,30 @@ an outline of the goal file it would write, and judge the answer against the exp otherwise, the session is interactive in a Git checkout at `~/git/foo` with a GitHub remote, and no models were named. The first rows are regression checks: shepherd and overseer mode must not change what the other modes do. -| Situation | Expected answer | -| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `$scode-build-goal add a --verbose flag` | no-workhorse stated; menu with opus high as the default; goal file and log beside the checkout; neither mode file read; the goal file has the resume protocol and the watchdog (the shipped script, Monitor in Claude Code, wake-on-exit in Codex, no per-minute polling); started with `/goal` | -| `$scode-build-goal powerhorse add a --verbose flag` | powerhorse with its worker, width, and PR-sizing defaults; menu with opus high as the default; log and chunk table paths; `modes/shepherd.md` not read | -| `$scode-build-goal galaxy-brain add a --verbose flag` | galaxy brain stated; `modes/shepherd.md` not read; otherwise as before | -| `$scode-build-goal fix the scode-shepherd runner's lock` | the mention is the goal's subject, not a switch: no-workhorse, `modes/shepherd.md` not read | -| `$scode-build-goal shepherd the 2.0 migration through CI` | `shepherd` is the goal's verb: goal text, no-workhorse (or asks); `modes/shepherd.md` not read | -| `$scode-build-goal teach scode-shepherd to run Claude workers` | a goal about scode-shepherd: no-workhorse, `modes/shepherd.md` not read | -| `$scode-build-goal shepherd runner: add a --dry-run flag` | `shepherd` is a noun in the goal: goal text, no-workhorse (or asks) | -| `$scode-build-goal help` | the TLDR names all five modes, that a shepherd-mode goal file is started with `$scode-shepherd`, and that an overseer-mode `/goal` session launches and oversees an executor; nothing written | -| `$scode-build-goal shepherd add a --verbose flag` | reads `modes/shepherd.md`; batch states shepherd mode, worker `gpt-6.1-terra` high, how the run is started, the menu with opus unavailable and sol high the default, the run directory `~/git/foo-verbose-goal-shepherd`; no log | -| the same, goal file outline | opens with the shepherd-mode sentence; execution mode requires `$scode-shepherd`, names the run directory and worker, forbids the other orchestrators; no resume protocol, no watchdog; decision logging to the run's journal | -| the same, after writing | tells the user `$scode-shepherd ` and the `shepherd drive` command; the run directory is not created | -| `$scode-build-goal shepherd ...`, the user answers "review with opus" | says opus cannot run in shepherd mode and asks; does not map it to another model | -| `$scode-build-goal shepherd powerhorse add a --verbose flag` | two modes requested: asks which | -| `$scode-build-goal overseer add a --verbose flag` | reads `modes/overseer.md`, not `modes/shepherd.md`; batch states overseer mode, executor `haiku` high with a smaller auto-compact window, the unchanged menu with opus high the default, started with `/goal` in a fresh (or `/compact`ed) farhelm Claude Code session, the farhelm host permissions an unattended run needs, the log and the overseer log `~/git/foo-verbose-goal-overseer-log.md` | -| the same, goal file outline | opens with Roles decided by the marker sentence; executor sections as no-workhorse plus Oversight (binding overseer messages, introduction message first); overseer sections: its resume protocol with the live-overseer check, launching via farhelm with matching permission mode, the `CLAUDE_CODE_AUTO_COMPACT_WINDOW=125000` wrapper for haiku, and a `/goal` prompt, overseeing by judgment with examples, limits, done ending with a question about a whole-stack review | -| `$scode-build-goal overseer ...`, the user answers "executor on sonnet high" | the executor runs on sonnet high with Claude Code's default auto-compact window: no `CLAUDE_CODE_AUTO_COMPACT_WINDOW` wrapper, which is for `haiku` only | -| `$scode-build-goal overseer ...`, the user answers "executor on gpt-6.1-terra" | says the executor must be a Claude model in this mode and asks; does not map it to another model | -| `$scode-build-goal add an overseer role to the job scheduler` | `overseer` is part of the goal: no-workhorse (or asks); `modes/overseer.md` not read | -| `$scode-build-goal overseer shepherd add a --verbose flag` | two modes requested: asks which | +| Situation | Expected answer | +| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `$scode-build-goal add a --verbose flag` | no-workhorse stated; menu with opus high as the default; goal file and log beside the checkout; neither mode file read; the goal file has the resume protocol and the watchdog (the shipped script, Monitor in Claude Code, wake-on-exit in Codex, no per-minute polling); started with `/goal` | +| `$scode-build-goal add a --verbose flag`, goal file outline | names the project by its GitHub remote and never by a checkout path; first action is the checkout check, which stops without writing the log when the session is not in a checkout of the project; repository paths relative to the checkout root; the watchdog watches the running checkout's root, added at run time; no planning-time commit or bookmark recorded as a fact; log, status file, and watchdog script absolute | +| `$scode-build-goal in ./notes add a --verbose flag`, goal file outline | goal file, log, and watchdog status file in `~/git/foo/notes` with absolute paths, the batch saying that directory is inside the repository; project file paths still relative; the checkout still identified only by its GitHub repository | +| `$scode-build-goal add a --verbose flag` in a fork clone (`origin` is `alice/foo`, `upstream` is `acme/foo`), goal file outline | identifies the project as the repository the PRs target, asking which when unclear; the checkout check accepts any clone with a remote pointing there and uses the nearest checkout, never an enclosing one | +| `$scode-build-goal powerhorse add a --verbose flag` | powerhorse with its worker, width, and PR-sizing defaults; menu with opus high as the default; log and chunk table paths; `modes/shepherd.md` not read | +| `$scode-build-goal galaxy-brain add a --verbose flag` | galaxy brain stated; `modes/shepherd.md` not read; otherwise as before | +| `$scode-build-goal fix the scode-shepherd runner's lock` | the mention is the goal's subject, not a switch: no-workhorse, `modes/shepherd.md` not read | +| `$scode-build-goal shepherd the 2.0 migration through CI` | `shepherd` is the goal's verb: goal text, no-workhorse (or asks); `modes/shepherd.md` not read | +| `$scode-build-goal teach scode-shepherd to run Claude workers` | a goal about scode-shepherd: no-workhorse, `modes/shepherd.md` not read | +| `$scode-build-goal shepherd runner: add a --dry-run flag` | `shepherd` is a noun in the goal: goal text, no-workhorse (or asks) | +| `$scode-build-goal help` | the TLDR names all five modes, that a shepherd-mode goal file is started with `$scode-shepherd`, and that an overseer-mode `/goal` session launches and oversees an executor; nothing written | +| `$scode-build-goal shepherd add a --verbose flag` | reads `modes/shepherd.md`; batch states shepherd mode, worker `gpt-6.1-terra` high, how the run is started, the menu with opus unavailable and sol high the default, the run directory `~/git/foo-verbose-goal-shepherd`; no log | +| the same, goal file outline | opens with the shepherd-mode sentence; execution mode requires `$scode-shepherd`, names the run directory and worker, forbids the other orchestrators; no resume protocol, no watchdog; decision logging to the run's journal | +| the same, after writing | tells the user `$scode-shepherd ` and the `shepherd drive` command; the run directory is not created | +| `$scode-build-goal shepherd ...`, the user answers "review with opus" | says opus cannot run in shepherd mode and asks; does not map it to another model | +| `$scode-build-goal shepherd powerhorse add a --verbose flag` | two modes requested: asks which | +| `$scode-build-goal overseer add a --verbose flag` | reads `modes/overseer.md`, not `modes/shepherd.md`; batch states overseer mode, executor `haiku` high with a smaller auto-compact window, the unchanged menu with opus high the default, started with `/goal` in a fresh (or `/compact`ed) farhelm Claude Code session, the farhelm host permissions an unattended run needs, the log and the overseer log `~/git/foo-verbose-goal-overseer-log.md` | +| the same, goal file outline | opens with Roles decided by the marker sentence; executor sections as no-workhorse plus Oversight (binding overseer messages, introduction message first); overseer sections: its resume protocol with the live-overseer check, launching via farhelm with matching permission mode, the `CLAUDE_CODE_AUTO_COMPACT_WINDOW=125000` wrapper for haiku, and a `/goal` prompt, overseeing by judgment with examples, limits, done ending with a question about a whole-stack review | +| `$scode-build-goal overseer ...`, the user answers "executor on sonnet high" | the executor runs on sonnet high with Claude Code's default auto-compact window: no `CLAUDE_CODE_AUTO_COMPACT_WINDOW` wrapper, which is for `haiku` only | +| `$scode-build-goal overseer ...`, the user answers "executor on gpt-6.1-terra" | says the executor must be a Claude model in this mode and asks; does not map it to another model | +| `$scode-build-goal add an overseer role to the job scheduler` | `overseer` is part of the goal: no-workhorse (or asks); `modes/overseer.md` not read | +| `$scode-build-goal overseer shepherd add a --verbose flag` | two modes requested: asks which | For an end-to-end check of the shepherd mode, have one sub agent write a real goal file for a small goal into a scratch directory, then run scode-shepherd's own goal-file evals (in `../scode-shepherd/AGENTS.md`) against that file instead of diff --git a/agent-skills/scode-build-goal/SKILL.md b/agent-skills/scode-build-goal/SKILL.md index 9fcafcb..4f2c037 100644 --- a/agent-skills/scode-build-goal/SKILL.md +++ b/agent-skills/scode-build-goal/SKILL.md @@ -206,9 +206,28 @@ a statement, not a question: "Goal file at X, log at Y unless you want them else 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. -Every path the goal file mentions — the log file, the repo root, worktrees, scratch directories, anything the Q&A -settles — is written in absolute form. The goal file will be read by sessions with arbitrary working directories, so a -relative path inside it is a resumption bug waiting to happen. +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 ` +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 @@ -351,10 +370,18 @@ overseer mode, `modes/overseer.md` does. Include, at minimum: 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. -- **Resume protocol.** The first action is to 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. +- **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 @@ -386,8 +413,9 @@ overseer mode, `modes/overseer.md` does. Include, at minimum: 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 - commit range or bookmark to review, and the file the findings go to; the reviewer has no other context. + 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 @@ -395,18 +423,19 @@ overseer mode, `modes/overseer.md` does. Include, at minimum: 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, so the - executing agent writes no watchdog of its own: + 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, `-goal-watchdog.json` next to the working log, which this skill does not - create. The watched paths, each passed to `sample` as `--path`: the repository, 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. + 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 ` under the Monitor tool, and `watchdog sample --status --path ...` 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 diff --git a/agent-skills/scode-build-goal/SPEC.md b/agent-skills/scode-build-goal/SPEC.md index 28ae82f..1947c22 100644 --- a/agent-skills/scode-build-goal/SPEC.md +++ b/agent-skills/scode-build-goal/SPEC.md @@ -34,8 +34,21 @@ whoever is judging whether a change kept the user-facing behavior intact. user whether to replace them. Replacing moves both existing files aside under a dated suffix; it never deletes them and never leaves the old log in place. A leftover watchdog status file moves aside with them, since it carries the old attempt's alert state. -- Every path written into the goal file, not only the log path, is absolute. The goal file is read by sessions with - arbitrary working directories. +- The goal file assumes it runs inside a checkout of the project, and that checkout is whichever one contains the + running session's working directory. It never names a checkout by path: the user may have several clones of one + project, and a goal planned in one of them has to run correctly in any other. It names the project by something no + clone changes, writes project file paths relative to the checkout root, and does not record the planning checkout's + VCS state (current commit, bookmarks, where `main` was) as a fact the run relies on. +- The project's identity is the GitHub repository its PRs target, asked about when the remotes leave that unclear; a + checkout is one of the project when any of its remotes points there, which admits a fork's clone with an `upstream` + remote. A project without a GitHub remote is identified by its root commit id, which every clone shares. A judgment + that a checkout's contents look right is not an identity check: two unrelated projects can look alike. +- The checkout a run works in is the nearest Git worktree or jj workspace containing the working directory, never an + enclosing one tried after the nearest one fails. The outermost-checkout rule under Naming and placement is for file + placement only. +- The goal file's own run files (the goal file, the log, the watchdog script and status file, scratch directories, a + shepherd run directory) are written as absolute paths wherever they live, an `in ` inside the checkout included, + since they are the same files whichever checkout or working directory the goal runs from. ## Naming and placement @@ -188,10 +201,10 @@ whoever is judging whether a change kept the user-facing behavior intact. - The mode's specifics live in `modes/overseer.md`, read only when the mode is on, governing where it and `SKILL.md` differ. The other modes never read it, for the same reason as `modes/shepherd.md`. - The session the user hands the goal file to with `/goal` is the overseer, assumed to be Claude Code. It launches the - executor as a farhelm session on the same host, in the checkout, running Claude Code on the executor model and effort, - with an initial prompt that is `/goal` plus the executor's instructions, or the same instructions without `/goal` when - `/goal` is not accepted. The mode is hard-wired to farhelm and to Claude Code for both sessions; the executor's model - is not switched during the run. + executor as a farhelm session on the same host, in the overseer's own checkout, running Claude Code on the executor + model and effort, with an initial prompt that is `/goal` plus the executor's instructions, or the same instructions + without `/goal` when `/goal` is not accepted. The mode is hard-wired to farhelm and to Claude Code for both sessions; + the executor's model is not switched during the run. - The executor is told in its prompt and in the goal file that it works under the overseer's oversight and that the overseer's messages direct it, within the user's settled decisions. It does the goal as a no-workhorse run would, with its own working log, PR stack, resource watchdog, and the review gate the user chose, launched by the executor itself. @@ -286,7 +299,14 @@ In shepherd mode, Shepherd mode above replaces the resume protocol, the resource entries below, and moves decision logging to the run's journal. In overseer mode, the entries below are what the goal file requires of the executor, preceded by its introduction message, and Overseer mode above adds the overseer's own. -- Invoking `agent-resumeable` on the log file's absolute path as its first action, with the resume semantics spelled +- As its first action, confirming that the working directory is inside a checkout of the project the goal file names. + When it is not, the executing agent stops before writing anything, the log included, and tells the user; a log written + from the wrong place would make the next run in the right one resume from it. In shepherd mode the supervisor runs + this check, and in overseer mode both the overseer and the executor do. A headless shepherd drive records its `--repo` + before the supervisor runs, so there the check cannot prevent run state and the start instructions say what a wrong + `--repo` costs. A resumed overseer whose log shows the executor working in a different checkout from its own stops and + tells the user instead of reusing, restarting, or replacing that executor. +- Invoking `agent-resumeable` on the log file's absolute path right after that check, with the resume semantics spelled out: an existing log means resume after cross-checking it against reality, a missing log means a fresh start. - In the default no-workhorse mode, no orchestration skill, with the demands and allowances described under No-workhorse mode. In galaxy brain mode, `scode-galaxy-brain` for the entire run as described under Galaxy brain mode. In @@ -349,9 +369,10 @@ file requires of the executor, preceded by its introduction message, and Oversee - A linear stack of reviewable PRs via `jjstack`, each reviewed before it is finished by a fresh-context run, delegated through the active orchestration skill (in no-workhorse mode, launched by the executing agent itself), of the reviewer the user chose from the menu, stated in the goal file as an explicit demand for its model, effort, and skill or - charter. The prompt names the skill or carries the full charter, the repo root, the range to review, and the findings - file, with no launch command copied into the goal file. For every non-swarm reviewer the goal file spells out the - charter in full: general correctness, design, and idiomatic code, findings to a named file, no edits, no VCS changes. + charter. The prompt names the skill or carries the full charter, the repo root (of the checkout the run is in, filled + in at run time), the range to review, and the findings file, with no launch command copied into the goal file. For + every non-swarm reviewer the goal file spells out the charter in full: general correctness, design, and idiomatic + code, findings to a named file, no edits, no VCS changes. - The reviewed outline and requirement sources, including the user's relevant words and later decisions, survive into the goal. Before implementing substantial departures, or undertaking another repair round after repeated corrective reviews of a component, reassess necessity with a fresh-context review carrying the full planning charter, original diff --git a/agent-skills/scode-build-goal/modes/overseer.md b/agent-skills/scode-build-goal/modes/overseer.md index fa0d288..933c15e 100644 --- a/agent-skills/scode-build-goal/modes/overseer.md +++ b/agent-skills/scode-build-goal/modes/overseer.md @@ -57,17 +57,17 @@ In this mode the batch states, besides what `SKILL.md` lists: The executor keeps the working log, `-goal-log.md`, exactly as in no-workhorse mode. The overseer keeps its own, `-goal-overseer-log.md`, in the same directory, through `agent-resumeable`. It records the current overseer as a line `CURRENT OVERSEER: ` (the latest such line wins, and the executor reads it), the permission mode -the executor was launched in, the executor's farhelm session id, messaging name, Claude session id, and transcript path, -the transcript offset last read, and every nudge with its reason. Together with the working log it records every session -the run spends money in, so that a later look at the run's cost finds them all by searching both logs for `SESSION`. -Each overseer session, fresh or resumed, appends `SESSION overseer transcript ` right after -invoking `agent-resumeable` (its id from `printenv CLAUDE_CODE_SESSION_ID`). The overseer appends `SESSION executor - launch farhelm transcript ` for every executor session id it -has not recorded yet, whenever an introduction or the transcript lookup reveals one: after a launch, a replacement, a -restart, or a handoff between overseers. A launch that ends before it introduces itself still gets its line from the -transcript lookup, if it left a transcript. One line per session id, never rewritten. This skill creates neither log, -for the reason `SKILL.md` gives for the working log, and handles an existing overseer log the same way as an existing -working log, moving both aside together when replacing an earlier attempt. +the executor was launched in and the working directory it was launched in, the executor's farhelm session id, messaging +name, Claude session id, and transcript path, the transcript offset last read, and every nudge with its reason. Together +with the working log it records every session the run spends money in, so that a later look at the run's cost finds them +all by searching both logs for `SESSION`. Each overseer session, fresh or resumed, appends `SESSION overseer transcript ` right after invoking `agent-resumeable` (its id from `printenv CLAUDE_CODE_SESSION_ID`). +The overseer appends `SESSION executor launch farhelm transcript +` for every executor session id it has not recorded yet, whenever an introduction or the transcript lookup reveals +one: after a launch, a replacement, a restart, or a handoff between overseers. A launch that ends before it introduces +itself still gets its line from the transcript lookup, if it left a transcript. One line per session id, never +rewritten. This skill creates neither log, for the reason `SKILL.md` gives for the working log, and handles an existing +overseer log the same way as an existing working log, moving both aside together when replacing an earlier attempt. ## What the goal file contains @@ -100,56 +100,62 @@ differences: the user had given them, within the user's settled decisions: the overseer cannot authorize what the goal file's unattended fallback forbids. The executor acts on them at once, and answers every message that asks for a reply. When it disagrees, it says so in a reply and still follows the instruction unless the overseer changes it. Its first - action, before the resume protocol (whose wording the goal file adjusts to match), is a message to the overseer giving - its own Claude session id (`printenv CLAUDE_CODE_SESSION_ID`), its launch id, and its working log's path, so the - overseer can find its transcript; it sends the same introduction whenever the overseer asks for one. Its working log - records its Claude session id as the executor's, so a compacted or resumed executor that no longer sees its first - prompt keeps the role. After every compaction (frequent for a `haiku` executor), it rereads the goal file's Roles and - Oversight sections and the part covering the item it is on, along with the working log's latest entries, before its - next step. Otherwise it messages the overseer only to reply, to report a decision only the user can make, and when the - goal is done. + action, before the checkout check and the resume protocol (whose wording the goal file adjusts to match), is a message + to the overseer giving its own Claude session id (`printenv CLAUDE_CODE_SESSION_ID`), its launch id, and its working + log's path, so the overseer can find its transcript; it sends the same introduction whenever the overseer asks for + one. Its working log records its Claude session id as the executor's, so a compacted or resumed executor that no + longer sees its first prompt keeps the role. After every compaction (frequent for a `haiku` executor), it rereads the + goal file's Roles and Oversight sections and the part covering the item it is on, along with the working log's latest + entries, before its next step. Otherwise it messages the overseer only to reply, to report a decision only the user + can make, and when the goal is done. For the overseer, the goal file adds these sections: +- **The checkout.** The overseer runs the same checkout check as the executor (see "The checkout" in `SKILL.md`) before + its resume protocol, and stops the same way when it fails, since the executor it launches works in the overseer's own + checkout. - **Resume protocol.** When the overseer log exists, first read its latest `CURRENT OVERSEER` line and check with `ListAgents` whether that session, unless it is this one, is still live; if it is, another overseer is running this goal, so stop, write nothing, and tell the user. Only then invoke `agent-resumeable` on the overseer log. A fresh - overseer writes its `CURRENT OVERSEER` line before launching the executor. A resumed overseer whose own permission - mode differs from the one the log records for the executor replaces the executor in its own mode, since its messages - would otherwise wait for approval. Otherwise it appends its own `CURRENT OVERSEER` line and reconciles the recorded - executor with `farhelm agent sessions`. One that is running is sent a message asking for its introduction, which also - tells it the new overseer's name. One that stopped is restarted with `farhelm agent restart`, which resumes its - conversation without resending its first prompt, so the overseer then messages it to continue per the goal file and - introduce itself. A message reaches a busy executor only at its next tool call, so an executor whose transcript shows - a tool call still running or recent activity is waited on, not counted as silent; a tool call running far longer than - its kind plausibly needs is a judgment call between waiting, replacing the executor, and telling the user. A restarted - executor that stops at the end of every turn, because `/goal` did not survive the restart, is replaced instead. One - that is gone, or that shows no activity and no answer for about five minutes, is replaced by a new launch, which - resumes from the executor's working log. + overseer writes its `CURRENT OVERSEER` line before launching the executor. A resumed overseer first compares the + executor working directory its log records with its own checkout root. When they differ, the run so far happened in + another clone, whose unpushed work a new executor here would not see, so it stops before touching the executor and + tells the user which checkout the run is in. A resumed overseer whose own permission mode differs from the one the log + records for the executor replaces the executor in its own mode, since its messages would otherwise wait for approval. + Otherwise it appends its own `CURRENT OVERSEER` line and reconciles the recorded executor with `farhelm agent + sessions`. One that is running is sent a message asking for its introduction, which also tells it the new overseer's + name. One that stopped is restarted with `farhelm agent restart`, which resumes its conversation without resending its + first prompt, so the overseer then messages it to continue per the goal file and introduce itself. A message reaches a + busy executor only at its next tool call, so an executor whose transcript shows a tool call still running or recent + activity is waited on, not counted as silent; a tool call running far longer than its kind plausibly needs is a + judgment call between waiting, replacing the executor, and telling the user. A restarted executor that stops at the + end of every turn, because `/goal` did not survive the restart, is replaced instead. One that is gone, or that shows + no activity and no answer for about five minutes, is replaced by a new launch, which resumes from the executor's + working log. - **Launching the executor.** Run `farhelm agent instructions` and follow it. Create the session on this host with the - checkout as its working directory, agent `claude`, the executor's model and effort, a title derived from the slug - (`-executor`, numbered `-2`, `-3`, and so on for replacements), a fresh idempotency key for each launch (a - replacement reuses none, so it cannot be answered with the session it replaces), and the same permission mode as the - overseer's own session (YOLO when its permissions are bypassed); a message to a session in a different permission mode - waits for a human to approve it. When the executor model is `haiku`, and only then, add `--wrapper - 'CLAUDE_CODE_AUTO_COMPACT_WINDOW=125000'`. Claude Code compacts about 31K tokens short of that window, so the - executor's context is compacted at roughly 94K tokens instead of growing toward the model's 1M window, and every call - stays under the 100K-token prompt size above which Haiku bills five times its base rate. Other models have no such - price step and keep their default window. A restart reuses the stored launch, wrapper included. If farhelm refuses the - wrapper, launch without it and say in the overseer log and in the report to the user that the executor runs on the - default window. The initial prompt is `/goal`, followed by: the marker sentence, the goal file's absolute path, the - overseer's messaging name (from the header `ListAgents` prints), the launch id (this launch's idempotency key), and - that the executor must read the goal file's Roles and Oversight sections first. A replacement stops the old session - first and carries its own new launch id. When the executor's transcript shows that `/goal` was not accepted, replace - the session with one whose prompt is the same text without `/goal`. The introduction gives the executor's messaging - name (the message's sender) and its transcript, the file named after its Claude session id under - `~/.claude/projects/`. Answer it with a message the executor has to reply to: the introduction proves only that - messages reach the overseer, and every nudge travels the other way. When no introduction arrives within about five - minutes, check `farhelm agent sessions` first: a session that is not running (an approval card pending, a failed - start) is the thing to fix or tell the user about. Otherwise, to see what went wrong, the transcript is the top-level - file (not one under a session's `subagents` directory) in the checkout's project directory under `~/.claude/projects/` - whose first prompt contains this launch's id. Then replace the executor once; a second launch that does not introduce - itself goes to the user. + root of the overseer's own checkout as its working directory (the goal file names no checkout path), agent `claude`, + the executor's model and effort, a title derived from the slug (`-executor`, numbered `-2`, `-3`, and so on for + replacements), a fresh idempotency key for each launch (a replacement reuses none, so it cannot be answered with the + session it replaces), and the same permission mode as the overseer's own session (YOLO when its permissions are + bypassed); a message to a session in a different permission mode waits for a human to approve it. When the executor + model is `haiku`, and only then, add `--wrapper 'CLAUDE_CODE_AUTO_COMPACT_WINDOW=125000'`. Claude Code compacts about + 31K tokens short of that window, so the executor's context is compacted at roughly 94K tokens instead of growing + toward the model's 1M window, and every call stays under the 100K-token prompt size above which Haiku bills five times + its base rate. Other models have no such price step and keep their default window. A restart reuses the stored launch, + wrapper included. If farhelm refuses the wrapper, launch without it and say in the overseer log and in the report to + the user that the executor runs on the default window. The initial prompt is `/goal`, followed by: the marker + sentence, the goal file's absolute path, the overseer's messaging name (from the header `ListAgents` prints), the + launch id (this launch's idempotency key), and that the executor must read the goal file's Roles and Oversight + sections first. A replacement stops the old session first and carries its own new launch id. When the executor's + transcript shows that `/goal` was not accepted, replace the session with one whose prompt is the same text without + `/goal`. The introduction gives the executor's messaging name (the message's sender) and its transcript, the file + named after its Claude session id under `~/.claude/projects/`. Answer it with a message the executor has to reply to: + the introduction proves only that messages reach the overseer, and every nudge travels the other way. When no + introduction arrives within about five minutes, check `farhelm agent sessions` first: a session that is not running + (an approval card pending, a failed start) is the thing to fix or tell the user about. Otherwise, to see what went + wrong, the transcript is the top-level file (not one under a session's `subagents` directory) in the checkout's + project directory under `~/.claude/projects/` whose first prompt contains this launch's id. Then replace the executor + once; a second launch that does not introduce itself goes to the user. - **Overseeing.** The judgment brief from What the mode is, in the overseer's words, with its examples marked as examples. Read what is new since the last look (the transcript past the offset the overseer log records, the working log, the PR stack), not the whole history each time; investigations that need more go to a sub-agent so the overseer's diff --git a/agent-skills/scode-build-goal/modes/shepherd.md b/agent-skills/scode-build-goal/modes/shepherd.md index 72ed0dc..32ed7a6 100644 --- a/agent-skills/scode-build-goal/modes/shepherd.md +++ b/agent-skills/scode-build-goal/modes/shepherd.md @@ -58,7 +58,7 @@ There is no working log in this mode: scode-shepherd keeps the run's state and j takes the log's place. Name it `-goal-shepherd`, a directory in the same place as the goal file, so the two stay adjacent in a listing (`~/git/foo-verbose-goal.md` and `~/git/foo-verbose-goal-shepherd/`). The name differs from the `-shepherd-` directories a plain scode-shepherd run picks, so a goal's run directory does not collide -with one of those. Its path in the goal file is absolute, like every path. +with one of those. Its path in the goal file is absolute, like every path outside the checkout. The run directory never goes inside the checkout the goal is about, where the worker's version control would see it and scode-shepherd refuses it. When an `in ` clause puts the goal file inside that checkout, say so in the batch and @@ -90,6 +90,11 @@ Then the items of "What the goal file must contain" in `SKILL.md`, with these di for its model and effort when the user named one, or otherwise as the default worker, which the supervisor may change as scode-shepherd allows. Forbid invoking, loading, or following `scode-galaxy-brain`, `scode-powerhorse`, or `scode-model-routing` at any point. +- **The checkout.** Keep it: the supervisor confirms that the checkout scode-shepherd runs on is one of the project + before planning, and stops and tells the user when it is not. With no resume protocol, the check comes first. Started + headless, `shepherd drive` creates the run directory and records its `--repo` before any supervisor reads the goal + file, so there the check cannot keep the run state clean, and the start instructions below tell the user what a wrong + `--repo` costs. - **Resume protocol.** Leave it out. scode-shepherd's run directory, its journal, and the runner's state are the resume record, and starting the same goal file again resumes the run. Do not name an `agent-resumeable` log. - **Resource watchdog.** Leave it out. scode-shepherd's runner checks disk and memory before every worker session, check @@ -113,6 +118,9 @@ Tell the user how to start it, in place of the `/goal` command: file>`. - Headless: `~/.codex/skills/scode-shepherd/scripts/shepherd drive --repo --goal-file `, with every path absolute (`~` expanded too). The run directory has to be the one the goal file names. + `` is the root of the checkout to run in, which the user picks and has to be a checkout of the project: the + first drive records it in the run directory and later drives keep it, so a wrong one means moving the run directory + aside and starting over. Either way, the same command again resumes the run, as long as it is the same way the run was started (a run started headless resumes headless) and the run has not finished; edits to the goal file after the start do not reach a headless