diff --git a/agent-skills/scode-build-goal/AGENTS.md b/agent-skills/scode-build-goal/AGENTS.md index d8b7c02..ec08919 100644 --- a/agent-skills/scode-build-goal/AGENTS.md +++ b/agent-skills/scode-build-goal/AGENTS.md @@ -35,30 +35,32 @@ 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 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 | +| 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 retries to the S3 uploader`; `src/http/retry.rs` has a backoff helper taking only `reqwest::Error`, called from six places under `src/http/` whose tests pin its retry budget, goal file outline | the outline names the existing helper and whether the plan reuses it, generalizes it, or keeps a separate S3 retry, and why; the batch puts that choice to the user as a judgment call, with costs; the planning charter, carried in full for scope reassessment, covers duplication and premature generalization | +| `$scode-build-goal add a --verbose flag`; the CLI already parses flags with `clap` derive | reuses `clap` without asking about it; no duplication or generalization question in the batch | +| `$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 e755c63..5a4fa4d 100644 --- a/agent-skills/scode-build-goal/SKILL.md +++ b/agent-skills/scode-build-goal/SKILL.md @@ -274,11 +274,12 @@ Record the actual answers as settled decisions, keeping planner proposals distin ## Implementation outline and scope review -Before finalizing the goal, show a short, repository-grounded outline: the existing path to extend, 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. +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. @@ -287,22 +288,44 @@ machinery needs a concrete contract or demonstrated failure the smaller design c 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. For each substantial new mechanism, explain which requirement -> makes it necessary and whether an existing facility or narrower supported behavior would suffice. Propose the smallest -> coherent design. Challenge planner-authored requirements; identify any simplification that would change an explicit -> user requirement or repository constraint. Report concrete findings and alternatives, or say no unnecessary complexity -> was found. Do not manufacture objections or add safeguards to justify an unnecessary subsystem. Write findings to the -> supplied private file; change no product files or VCS state. +> 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. 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. +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 @@ -357,19 +380,23 @@ overseer mode, `modes/overseer.md` does. Include, at minimum: 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. + 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; these are examples, not - a blacklist. 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. + 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 diff --git a/agent-skills/scode-build-goal/SPEC.md b/agent-skills/scode-build-goal/SPEC.md index 2f888b8..197c798 100644 --- a/agent-skills/scode-build-goal/SPEC.md +++ b/agent-skills/scode-build-goal/SPEC.md @@ -279,17 +279,30 @@ whoever is judging whether a change kept the user-facing behavior intact. ## Proportionate planning -- Before finalizing, show a short repository-grounded implementation outline: existing paths to reuse, the smallest - sufficient design, substantial new state or subsystems, expensive promises, and uncertainty. Explain aggregate cost; - do not prescribe every defensive detail or use invented precise estimates as targets. +- Before finalizing, show a short repository-grounded implementation outline: existing paths to reuse, existing + mechanisms reused or generalized, the smallest sufficient design, substantial new state or subsystems, expensive + promises, and uncertainty. Explain aggregate cost; do not prescribe every defensive detail or use invented precise + estimates as targets. +- Keeping the plan small and avoiding duplication are weighed against each other; neither overrides the other. A + mechanism that does substantially the same job as an existing one reuses it when it fits. Otherwise the plan weighs + generalizing it only as far as the callers actually in hand need against a separate implementation, which is right + when sharing would blur two different contracts, and the outline says which and why. Clear-cut cases are the planner's + to settle. Close calls (generalizing that reaches into code the goal otherwise leaves alone, changes behavior other + callers rely on, or rests on an unclear shared shape) go to the user during planning and are recorded as settled + decisions, so the foreseeable ones are not left to the unattended run. One planning did not foresee is a routine fork + during execution when every option stays within the agreed scope: decided after scope reassessment and logged as + DECISION. The user asked for this on 2026-11-17: the planning review until then guarded only against doing more than + needed, which leaves a plan free to stay small by duplicating. - Keep the original request and later user decisions, sourced repository constraints, and planner-proposed mechanisms distinct. Substantial mechanisms need a concrete contract or demonstrated failure that the smaller design cannot handle. Refusal of unsupported cases must still satisfy the agreed behavior. - Run one fresh-context planning review, using a native sub-agent at the planner's model unless the user specifies otherwise. It receives the request and decisions as well as the proposed goal, outline, and repository context. Its charter explicitly challenges unnecessary planner-authored obligations and asks for concrete smaller alternatives, - distinguishing changes that need a user decision. No findings is valid. Findings go to a named private file; no - product or VCS edits. This does not activate execution skills or change the per-PR reviewer selection. + challenges duplication of existing mechanisms without proposing generalization beyond the plan's actual uses, and + distinguishes changes and close reuse-versus-duplication calls that need a user decision. No findings is valid. + Findings go to a named private file; no product or VCS edits. This does not activate execution skills or change the + per-PR reviewer selection. - Resolve findings before finalizing. Reassess affected conclusions after material design changes, not wording changes. Disclose unavailable independent review; self-review must not be represented as independent.