goalbuddy 0.3.5 → 0.3.7

package/README.md

@@ -16,9 +16,9 @@
   <a href="https://goalbuddy.dev"><img alt="goalbuddy.dev" src="https://img.shields.io/badge/site-goalbuddy.dev-684cff?style=flat-square"></a>
 </p>
 
-GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks, especially when the work branches into subgoals, parallel agents, and long-running verification.
+GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks by giving native `/goal` a finish line, a live work surface, and a proof loop.
 
-It gives `/goal` a small local workspace: a charter, a board, notes, receipts, and a clear next task. The work stays in your repo, so a run can pause, resume, verify, and keep going without re-inventing the plan every turn.
+It gives `/goal` a small local workspace: a charter, a goal oracle, a board, notes, receipts, and a clear next task. The work stays in your repo, so a run can pause, resume, verify, and keep going without re-inventing the plan every turn.
 
 ## Start Here
 
@@ -44,6 +44,25 @@ In Claude Code, use:
 
 Goal Prep creates the board and prints the exact `/goal` command to run next. That is the whole path.
 
+## Codex Install Model
+
+For Codex, the canonical install is the native plugin plus bundled agents:
+
+```text
+~/.codex/plugins/cache/goalbuddy/goalbuddy/<version>/
+~/.codex/agents/goal_judge.toml
+~/.codex/agents/goal_scout.toml
+~/.codex/agents/goal_worker.toml
+```
+
+The Codex plugin bundles `$goal-prep`; a clean Codex install should not need personal `~/.codex/skills/goalbuddy` or `~/.codex/skills/goal-maker` folders. Native Codex `/goal` is a separate OpenAI-gated feature. GoalBuddy prepares local boards and handoff prompts for it, but it does not enable or replace native `/goal`.
+
+To verify a Codex install:
+
+```bash
+npx goalbuddy doctor --target codex --goal-ready
+```
+
 ## What It Creates
 
 ```text
@@ -51,6 +70,7 @@ docs/goals/<your-goal>/
   goal.md
   state.yaml
   notes/
+  .goalbuddy-board/ # generated local board files
   subgoals/        # optional depth-1 child boards
 ```
 
@@ -65,18 +85,30 @@ docs/goals/<your-goal>/
 ## How It Thinks
 
 ```text
-rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verify
+Intent -> Oracle -> Surface -> Loop -> Proof
 ```
 
+The oracle is the observable signal that says whether the original owner outcome is actually true: a test suite, browser walkthrough, demo transcript, generated artifact, benchmark, source-backed answer, release check, or final human decision.
+
+No oracle, no serious goal.
+
+The local board is the default work surface. It is not an extension marketplace; it is the built-in view of the `state.yaml` truth.
+
 Scout maps the repo.
 
-Judge chooses the next bounded slice.
+Judge chooses the largest safe useful slice.
 
-Worker changes code and leaves a receipt.
+Worker completes the whole assigned slice and leaves a receipt.
 
-`/goal` keeps the loop honest until the original goal is actually done.
+`/goal` keeps the loop honest until a final Judge/PM audit maps receipts and verification back to the oracle and records the full outcome complete.
 
-## Subgoals, Parallel Agents, and Dark Mode
+## Slice Sizing
+
+Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
+
+GoalBuddy should not optimize for tiny safe tasks. It should optimize for the largest safe useful slice: a working screen, working API path, data pipeline step, backend vertical slice, real bug fix, or milestone review. The board warns when it sees safe-looking work that keeps adding helpers, contracts, proof files, or doc notes without moving the outcome.
+
+## Goalmaxxed
 
 GoalBuddy keeps the model small:
 
@@ -90,9 +122,9 @@ Use subgoals for bounded child work that belongs to a parent task. Use multiple
 
 ## Execution Quality
 
-GoalBuddy can prepare safe parallel work; it does not run a parallel org chart.
+GoalBuddy can prepare safe parallel work; it does not run a parallel org chart or install arbitrary extension packs.
 
-Use `goalbuddy prompt docs/goals/<slug>` to render a compact prompt for the active task without dumping the whole state file. Use `goalbuddy parallel-plan docs/goals/<slug>` to inspect read-only or disjoint write-scope work that can be handed to native Codex or Claude Code agent flows. The command reports recommendations only; it does not mutate state or spawn agents.
+Use `goalbuddy prompt docs/goals/<slug>` to render a compact prompt for the active task without dumping the whole state file. The prompt includes a mandatory `required_spawn_agent_type`; Codex PMs should use that exact GoalBuddy agent (`goal_scout`, `goal_worker`, or `goal_judge`) instead of a generic role agent. Use `goalbuddy parallel-plan docs/goals/<slug>` to inspect read-only or disjoint write-scope work that can be handed to native Codex or Claude Code agent flows. The command reports recommendations only; it does not mutate state or spawn agents.
 
 ## Update
 
@@ -106,11 +138,13 @@ That updates both Codex and Claude Code.
 
 ## Live Boards
 
-GoalBuddy can open a local board while the work is running, so you can see the plan, active task, receipts, subgoals, and verification status without digging through the chat.
+GoalBuddy opens a local board while the work is running, so you can see the plan, active task, receipts, subgoals, and verification status without digging through the chat.
+
+Multiple local boards reuse one readable `goalbuddy.localhost` hub with an in-header board switcher. When sharing a board in chat or docs, use a real Markdown link such as `[Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/)` so the URL is clickable. The viewer also supports dark mode, compact mode, completed-task collapse, active-work motion, and reduced-motion handling.
 
-Multiple local boards reuse one readable `goalbuddy.localhost` hub with an in-header board switcher. The viewer also supports dark mode, compact mode, completed-task collapse, active-work motion, and reduced-motion handling.
+Custom external integrations should be built as ordinary repo work with a concrete implementation plan, not installed from a GoalBuddy catalog.
 
-See [GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode](RELEASE-0.3.5.md) for the release notes.
+See [GoalBuddy 0.3.7: Goalmaxxed](RELEASE-0.3.7.md) for the latest release notes.
 
 <p align="center">
   <img src="internal/assets/goalbuddy-live-board.jpg" alt="GoalBuddy local live board open next to Codex while Scout, Judge, and Worker tasks populate." width="100%">

package/RELEASE-0.3.5.md

@@ -256,8 +256,8 @@ The board renderer also fails closed on invalid child paths, so a malformed subg
 Run the bundled parent/child board:
 
 ```bash
-node goalbuddy/extend/local-goal-board/scripts/local-goal-board.mjs \
-  --goal goalbuddy/extend/local-goal-board/examples/subgoal-parent
+node goalbuddy/surfaces/local-goal-board/scripts/local-goal-board.mjs \
+  --goal goalbuddy/surfaces/local-goal-board/examples/subgoal-parent
 ```
 
 Then try:
@@ -265,8 +265,8 @@ Then try:
 - switch to dark mode from the gear menu
 - open task `T004` to see the embedded child board
 - launch another board and use the header selector
-- run `goalbuddy parallel-plan goalbuddy/extend/local-goal-board/examples/subgoal-parent`
-- run `goalbuddy prompt goalbuddy/extend/local-goal-board/examples/subgoal-parent`
+- run `goalbuddy parallel-plan goalbuddy/surfaces/local-goal-board/examples/subgoal-parent`
+- run `goalbuddy prompt goalbuddy/surfaces/local-goal-board/examples/subgoal-parent`
 
 ## Tests
 

package/RELEASE-0.3.7.md

@@ -0,0 +1,127 @@
+# GoalBuddy 0.3.7: Goalmaxxed
+
+Release date: 2026-05-19
+
+Goalmaxxed is the release where GoalBuddy stops trying to become a workflow catalog and commits to one sharper job:
+
+```text
+Give /goal enough pressure that it keeps working until the original outcome is actually true.
+```
+
+This release is heavily inspired by the Codex maxxing playbook: keep the goal visible, preserve context in local files, use subagents deliberately, demand evidence, and resist the temptation to declare victory because a plausible slice finished.
+
+Update with:
+
+```bash
+npx goalbuddy update
+```
+
+## The Headline
+
+GoalBuddy now centers the native `/goal` loop around five small ideas:
+
+- **Intent**: capture what the owner actually wants.
+- **Oracle**: define the observable signal that proves the outcome is real.
+- **Surface**: keep one local board visible while the run moves.
+- **Loop**: Scout maps facts, Judge chooses the largest safe useful slice, Worker completes the whole slice.
+- **Proof**: final completion requires receipts mapped back to the oracle.
+
+That is the product. Everything else got judged against that loop.
+
+## Goal Pressure
+
+GoalBuddy now treats the goal oracle as first-class state. A serious goal needs an observable signal before the board can pretend it knows what done means:
+
+- a passing test suite
+- a browser walkthrough
+- a demo transcript
+- a generated artifact
+- a benchmark
+- a source-backed answer
+- a release check
+- a final human decision
+
+No oracle, no serious goal.
+
+The checker also rejects weak final completion. A goal should not be marked done just because the active task ended. Done means a final Judge or PM audit records that the receipts and verification satisfy the oracle.
+
+## Larger Useful Slices
+
+This release sharpens the slice policy:
+
+```text
+Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
+```
+
+GoalBuddy now pushes Judge and Worker toward the largest safe useful slice: a working screen, working API path, backend vertical slice, real bug fix, data pipeline step, or milestone review.
+
+The board warns when it sees micro-slicing: helper files, contracts, proof notes, or tiny prep tasks that are safe but do not move the owner outcome.
+
+## Built-In Local Board
+
+The local board is now a core surface, not an extension.
+
+The bundled surface lives at:
+
+```text
+goalbuddy/surfaces/local-goal-board/
+```
+
+It remains the default way to watch a GoalBuddy run: active task, blocked state, receipts, verification status, subgoals, and board switching all point back to the same `state.yaml` truth.
+
+## No Extension Catalog
+
+GoalBuddy no longer ships a public extension catalog.
+
+The old catalog made the product look bigger while making the core loop blurrier. Goalmaxxed chooses the smaller invariant:
+
+```text
+GoalBuddy prepares and pressures /goal runs. Custom integrations are ordinary repo work.
+```
+
+If a team wants a GitHub, Linear, Slack, or release integration, they should prepare a concrete implementation plan in their repo and build it as normal software. GoalBuddy should not install arbitrary workflow packs as a side channel.
+
+## Simpler Public Surface
+
+The public copy now says what GoalBuddy actually does:
+
+- prepares `/goal`
+- writes `goal.md` and `state.yaml`
+- creates a goal oracle
+- opens a local board
+- keeps Scout/Judge/Worker handoffs receipt-shaped
+- prevents early completion
+- leaves custom integrations outside the core
+
+The Codex and Claude Code plugin manifests are aligned with the package description, and the test suite now checks that the Claude manifest stays in sync.
+
+## Release Boundaries
+
+This release intentionally does not add:
+
+- an extension marketplace
+- automatic parallel-agent spawning
+- hosted board state
+- automatic receipt application
+- UI controls that mutate board state
+- a replacement for native `/goal`
+
+GoalBuddy stays local, file-backed, and boring in the parts that should be boring.
+
+## Package Notes
+
+This release updates:
+
+- npm package version: `0.3.7`
+- Codex plugin version: `0.3.7`
+- Claude Code plugin version: `0.3.7`
+- package contents to include `goalbuddy/surfaces/`
+- mirrored GoalBuddy skill files under `plugins/goalbuddy/skills/goalbuddy/`
+
+Before publishing, verify:
+
+```bash
+npm run check
+npm run pack:dry-run
+node internal/cli/check-publish-version.mjs
+```

package/goalbuddy/SKILL.md

@@ -12,9 +12,17 @@ GoalBuddy is for autonomous, long-running Codex or Claude Code work where the PM
 The loop is:
 
 ```text
-raw user intent -> intake compiler -> discovery/plan validation/execution board -> one active task -> receipt -> board update -> repeat
+raw user intent -> intake compiler -> goal oracle -> local work surface -> one active task -> receipt -> proof loop -> repeat
 ```
 
+GoalBuddy's core invariant is:
+
+```text
+Intent -> Oracle -> Surface -> Loop -> Proof
+```
+
+No oracle, no serious goal. A goal oracle is the observable signal that tells the PM whether the original owner outcome is actually true yet. It may be a test suite, browser walkthrough, demo transcript, generated artifact, benchmark, source-backed answer, release check, or final human decision. Weak proof creates weak goals, so record the oracle before shaping tasks and keep testing against it until final completion.
+
 ## Invocation Boundary
 
 There are two different modes:
@@ -31,7 +39,7 @@ Allowed `$goal-prep` actions:
 - run the bundled GoalBuddy update checker and mention a newer version if one is available;
 - ask diagnostic intake questions and wait when required;
 - create or repair only `docs/goals/<slug>/goal.md`, `docs/goals/<slug>/state.yaml`, `docs/goals/<slug>/notes/`, and the generated `.goalbuddy-board/` visual board artifact;
-- create and open the selected visual board surface for the goal;
+- create and open the built-in local GoalBuddy board surface for the goal unless the user opts out;
 - optionally run the GoalBuddy board checker against that `state.yaml`;
 - verify GoalBuddy agent availability, if this can be done without touching implementation work, and record `installed`, `bundled_not_installed`, `missing`, or `unknown` truthfully;
 - print exactly `/goal Follow docs/goals/<slug>/goal.md.`;
@@ -69,25 +77,25 @@ Extract:
 - authority: `requested | approved | inferred | needs_approval | blocked`;
 - proof type: `test | demo | artifact | metric | review | source_backed_answer | decision`;
 - completion proof: the observable signal for full outcome completion;
+- goal oracle: the live check, walkthrough, artifact, metric, or decision that will keep pressure on the goal and prevent early completion;
 - likely misfire: how `/goal` could succeed at the wrong thing;
 - blind spots: important risks, choices, or success dimensions the user may not have named yet;
 - existing plan facts: user-provided steps, files, constraints, or sequencing that must be preserved but still validated.
 
-Ask the visual-board question early, before detailed task shaping:
+Use the local GoalBuddy board as the default work surface for broad GoalBuddy runs. Ask only when the user has not already implied they want the default local surface, the goal is unusually quick/private, or board setup would materially distract from the requested prep:
 
 ```text
-Do you want to set up a visual board for this?
+Do you want the local GoalBuddy board for this goal?
 ```
 
 Recommended options:
 
 1. Local live board (Recommended) - starts immediately, requires no credentials, and lets the user watch tasks populate inside Codex or Claude Code.
-2. GitHub Projects - best when stakeholders need a shared external board and the user can approve GitHub credentials/project details.
-3. No visual board - best for quick or private goals where the file board is enough.
+2. No visual board - best for quick or private goals where the file board is enough.
 
-If the user chooses the local live board, create the goal directory, `notes/`, and an initial minimal `state.yaml` as soon as the slug is known, then run `npx goalbuddy board docs/goals/<slug>` and open the printed local URL in the AI coding agent's in-app browser (the Codex in-app Browser, the Claude Code preview, or the user's regular browser). The default local hub is `http://goalbuddy.localhost:41737/`, and board URLs normally look like `http://goalbuddy.localhost:41737/<slug>/`. In short: start the local board before filling the task list so the board pops up right away and cards populate live as `state.yaml` changes. Include the printed board URL in the final prep response as the operator fallback, but do not make the URL the primary experience.
+If the user chooses the local live board, create the goal directory, `notes/`, and an initial minimal `state.yaml` as soon as the slug is known, then run `npx goalbuddy board docs/goals/<slug>` and open the printed local URL in the AI coding agent's in-app browser (the Codex in-app Browser, the Claude Code preview, or the user's regular browser). The default local hub is `http://goalbuddy.localhost:41737/`, and board URLs normally look like `http://goalbuddy.localhost:41737/<slug>/`. In short: start the local board before filling the task list so the board pops up right away and cards populate live as `state.yaml` changes. Include the printed board URL in the final prep response as an actual clickable Markdown link, for example `[Open GoalBuddy board](http://goalbuddy.localhost:41737/<slug>/)`. Do not put the board URL only in a code block, quote, HTML comment, or prose that the UI cannot click.
 
-If the user chooses GitHub Projects, ask for approval and the required project target before any live write. Create or sync the GitHub Project at the same early point as the local board: after the goal root and skeleton `state.yaml` exist, before the detailed task list is finished, then sync again as tasks populate. Run a dry-run sync first when possible. Missing GitHub credentials or project details should not block local board creation or goal prep; record the missing requirement in `visual_board.github_projects` and seed a PM setup task.
+If the user wants an external board, GitHub sync, Slack digest, Linear handoff, or any other custom integration, do not install a GoalBuddy catalog item. Treat it as normal implementation work: create a concrete task that designs and verifies that integration inside the target repo or asks the operator for the required credentials and scope.
 
 Ask before board creation when the request is vague, strategic, improvement-oriented, or open-ended and the user has not explicitly said to use defaults. Ask one guided question at a time with 2-3 options and a recommended default, then wait. Continue the diagnostic intake until the user's answers are sufficient to choose the board shape. Do not create or repair `docs/goals/<slug>/` until the diagnostic intake is complete or the user explicitly accepts defaults.
 
@@ -134,7 +142,7 @@ Stop after each question. Do not create files, repair an existing board, run che
 
 Minimum diagnostic ladder for vague, strategic, or improvement-oriented goals:
 
-1. Visual board: ask "Do you want to set up a visual board for this?"
+1. Goal surface: use the local live board by default, or ask "Do you want the local GoalBuddy board for this goal?" when board handling is unresolved.
 2. Intent target: what kind of improvement or outcome matters most?
 3. Success proof: what evidence would convince the user this worked?
 4. Scope and non-goals: what should remain untouched or explicitly out of scope?
@@ -173,7 +181,7 @@ Do:
 - classify the goal as `specific`, `open_ended`, `existing_plan`, `recovery`, or `audit`;
 - create or repair `docs/goals/<slug>/`;
 - create `goal.md`, `state.yaml`, and `notes/`;
-- if requested, start the local visual board immediately and open it in the AI coding agent's in-app browser (Codex in-app Browser, Claude Code preview, or the user's regular browser) before filling the task list;
+- start the local board immediately and open it in the AI coding agent's in-app browser (Codex in-app Browser, Claude Code preview, or the user's regular browser) before filling the task list, unless the user opts out;
 - seed a role-tagged task board that matches the input shape;
 - make the first active task safe;
 - verify Scout, Worker, and Judge agent availability or record an explicit truthful state;
@@ -203,22 +211,38 @@ Planning, Scout findings, Judge decisions, and a queued Worker task are not term
 For execution goals, the default run is continuous:
 
 ```text
-Discover enough evidence, choose a safe implementation slice, implement it, verify it, audit it, then immediately choose and execute the next safe slice until the full original outcome is complete.
+Discover enough evidence, choose the largest reversible local work package, implement it, verify it, review only at risk or phase boundaries, then immediately choose and execute the next work package until the full original outcome is complete.
 ```
 
 If the first `/goal` run reaches a Judge decision that names a safe Worker task with `allowed_files`, `verify`, and `stop_if`, the PM should activate that Worker and continue in the same run unless a stop condition applies.
 
-After a verified Worker slice and audit, do not mark the thread goal complete merely because that slice passed. A slice audit is a checkpoint. For broad automation or product goals, continue by reopening or advancing the board to the next safe Worker task until the full owner outcome is complete.
+After a verified Worker package, do not mark the thread goal complete merely because that package passed. For broad automation or product goals, continue by reopening or advancing the board to the next safe Worker package until the full owner outcome is complete.
 
 Missing owner input, credentials, production access, destructive-operation permission, or policy decisions are blockers for specific tasks, not stopping conditions for the whole goal. When a slice hits one of those blockers, mark that exact task blocked with a receipt, create a safe follow-up or workaround task, and keep doing local, non-destructive work that advances the full outcome.
 
+## Slice Sizing Policy
+
+A good task is the largest safe useful slice.
+
+Small is not the goal. Useful is the goal.
+
+Safe does not mean small. Safe means bounded, explicit, verified, and reversible.
+
+A good Worker task usually produces a working screen, a working API path, a working data pipeline step, a working backend vertical slice, a real bug fix, or a milestone review. A bad Worker task is one more tiny helper, projection function, contract file, read-only proof, or doc note unless that tiny task is truly blocking progress.
+
+Judge picks the largest safe useful next slice. Worker completes the whole assigned slice. Judge reviews the whole slice.
+
+After two tiny tasks in a row, PM or Judge should reorient the board. If a demo milestone is complete, the next task should move toward the next real milestone.
+
+Tiny tasks are allowed when the failure is isolated, the risk is high, the scope is unknown, or the tiny task unlocks a larger slice. Tiny tasks are bad when they keep happening, do not change behavior, only add wrappers/contracts/proof files, or avoid the real milestone.
+
 ## When To Use
 
 Use this skill for goals that are broad, multi-hour, ambiguous, high-risk, already planned, already stale, already red, or likely to need Scout/Judge/Worker delegation.
 
 For a one-change task, do not create a GoalBuddy board.
 
-Scout and Judge tasks may identify optional extension, plugin, publishing, reporting, or channel opportunities as improvement candidates. Treat those as normal board tasks. Extensions are supporting surfaces; `state.yaml` remains board truth.
+Scout and Judge tasks may identify optional publishing, reporting, integration, plugin, or channel opportunities as improvement candidates. Treat those as normal board tasks with concrete implementation plans. `state.yaml` remains board truth.
 
 ## The Four Primitives
 
@@ -258,6 +282,7 @@ The charter answers:
 What did the user originally ask for?
 What are we trying to improve?
 What input shape did the intake identify?
+What is the goal oracle?
 What constraints are non-negotiable?
 Is this goal specific, open-ended, existing-plan, recovery, or audit?
 What likely misfire must the PM avoid?
@@ -267,7 +292,7 @@ What counts as enough for the current tranche?
 Avoid forever goals. A broad goal should define an execution tranche, for example:
 
 ```text
-Discover the highest-leverage local improvements, complete successive safe verified implementation slices, audit each slice against the original user outcome, and keep advancing until the full outcome is complete.
+Discover the highest-leverage local improvements, complete successive safe verified work packages, review only at risk or phase boundaries, and keep advancing until the full outcome is complete.
 ```
 
 ## Board
@@ -390,8 +415,9 @@ Judge receipt:
 ```yaml
 receipt:
   result: done
-  decision: "Do router coverage first; defer auth flake because it is not reproducible locally."
-  next_allowed_task: T004
+  decision: "approved"
+  full_outcome_complete: false
+  rationale: "Router coverage is verified; continue with the next PM-selected work package."
   blocked_tasks:
     - T005
 ```
@@ -440,7 +466,7 @@ Blocked tasks do not necessarily block the goal. The PM should keep doing safe l
 
 - create a Scout task to improve evidence;
 - create a Judge task to resolve ambiguity;
-- create a Worker task for a smaller safe slice;
+- create a Worker task for the largest reversible local work package that can proceed;
 - write or update a note for handoff;
 - update receipts and verification freshness.
 
@@ -471,9 +497,11 @@ After a task completes, immediately write its receipt and select the next active
 
 - a final audit proves the full original owner outcome is complete.
 
-Do not stop at "ready for implementation" when a safe Worker task exists. Activate the Worker, execute it, verify it, and then run the audit task.
+Do not stop at "ready for implementation" when a safe Worker task exists. Activate the Worker, execute it, verify it, and keep going.
+
+Do not stop after one verified work package when the broader owner outcome still has safe local follow-up work. Advance the board to the next work package unless a risk boundary or final audit is due.
 
-Do not stop after one verified implementation slice when the broader owner outcome still has safe local follow-up slices. Treat a slice audit as permission to advance the board, not as permission to finish, unless the audit explicitly proves the full original outcome is complete.
+Do not create a Judge task after every Worker by default. Use Judge only for phase boundaries, high-risk changes, unclear scope, rejected verification, or final completion. Repeated same-shape work belongs in one Worker package.
 
 Do not stop because the current slice needs owner input, credentials, production access, destructive operations, or policy decisions. Mark that slice blocked, spawn or activate the smallest safe local task that can proceed around the blocker, and continue.
 
@@ -507,8 +535,8 @@ Non-`installed` states are warnings, not false failures, because the main `/goal
 | Agent | Thinking level | Write access | Use for |
 |---|---:|---:|---|
 | Scout | low | no | targeted source/spec/repo evidence mapping |
-| Worker | low | yes, bounded | one exact implementation or recovery task |
-| Judge | high | no | strategic review, ambiguity, scope, completion skepticism |
+| Worker | medium | yes, bounded | one coherent bounded useful slice |
+| Judge | high | no | phase/risk/final review, ambiguity, scope, completion skepticism |
 
 A task's `assignee` determines the agent. The task card is the order. The receipt is the return format.
 
@@ -540,7 +568,9 @@ Treat `reasoning_hint` as PM guidance. It does not override task scope, write pe
 
 ## Execution Quality Commands
 
-Use `goalbuddy prompt docs/goals/<slug>` to render a compact prompt for the active task. The prompt includes only task-specific material, safe agent metadata, and the expected receipt shape. It should not include broad chat history or dump the whole state file.
+Use `goalbuddy prompt docs/goals/<slug>` to render a compact prompt for the active task. The prompt includes only task-specific material, safe agent metadata, continuation warnings, and the expected receipt shape. It should not include broad chat history or dump the whole state file.
+
+When dispatching Codex subagents from a GoalBuddy prompt, the `required_spawn_agent_type` is mandatory. Use that exact `spawn_agent` `agent_type` (`goal_scout`, `goal_worker`, or `goal_judge`). Do not substitute generic `scout`, `worker`, or `judge` agents; if the required GoalBuddy agent is unavailable, stop spawning and continue as PM fallback or run `npx goalbuddy agents`/`npx goalbuddy install`. After one `wait_agent` timeout with no visible allowed-file changes, stop waiting, record the timeout, and recover deterministically instead of waiting forever.
 
 Use `goalbuddy parallel-plan docs/goals/<slug>` when the user explicitly asks for parallel agent work. It is read-only: it recommends safe Scout/Judge handoffs and Worker handoffs only when write scopes are known and disjoint. It does not mutate `state.yaml`, create sub-goals, apply receipts, or spawn agents.
 
@@ -552,7 +582,7 @@ Completion is a Judge or PM audit task. The goal is done only when a final done
 
 For execution goals, completion also requires implementation evidence. A final audit cannot call the goal done if the only completed work is planning, discovery, or task selection.
 
-For continuous execution goals, the final audit receipt must include `full_outcome_complete: true`. If the receipt only proves that the current slice or tranche is complete, keep the goal active and queue or activate the next safe Worker/Judge/PM task.
+For continuous execution goals, the final audit receipt must include `full_outcome_complete: true`. If the receipt only proves that the current work package or tranche is complete, keep the goal active and queue or activate the next safe Worker/PM task. Add a Judge only when the next decision is a phase, risk, ambiguity, rejected verification, or final completion review.
 
 Queued or active Worker tasks block `goal.status: done`. If a Worker is no longer required, mark it blocked with a receipt explaining why, remove it during PM board maintenance, or replace it with the actual required Worker task before completion.
 

package/goalbuddy/agents/README.md

@@ -13,7 +13,7 @@ This directory contains skill metadata and bundled agent definitions for Codex a
 | Agent | Codex file | Claude Code file | Reasoning effort | Write scope |
 |---|---|---|---:|---|
 | Scout | `goal_scout.toml` | `goal-scout.md` | medium | read-only |
-| Worker | `goal_worker.toml` | `goal-worker.md` | low | workspace-write |
+| Worker | `goal_worker.toml` | `goal-worker.md` | medium | workspace-write |
 | Judge | `goal_judge.toml` | `goal-judge.md` | high | read-only |
 
 ## Recommended Codex Config

package/goalbuddy/agents/goal_judge.toml

@@ -13,11 +13,16 @@ Hard contract:
 - Read only. Do not edit, stage, install, or implement.
 - Read state receipts before raw files. Then read only the inputs named in the Judge task.
 - Be skeptical of progress. Lots of files, docs, or tests are not completion.
-- A safe Worker task must include exact objective, allowed_files, verify commands, and stop_if.
+- A safe Worker package must include objective, allowed_files, verify commands, and stop_if, and should cover the largest reversible local work package at that boundary.
+- Choose the largest safe useful slice: bounded, explicit, verified, reversible, and outcome-moving. Safety does not mean tiny.
+- Judge a whole useful slice, not one helper at a time.
+- Detect micro-slice loops. Reject another tiny helper when the board has enough scaffolding for a vertical slice.
+- Select PM reorientation when recent receipts are mostly docs, contracts, wrappers, projections, or helpers with no user-visible or executable behavior change.
+- Prefer milestone reviews over helper reviews.
 - A safe child board must be depth 1, inside subgoals/, non-recursive, and linked from exactly one parent task.
 - Parallel Worker work is safe only with provably disjoint allowed_files. Separate boards alone are not proof.
 - Reject completion unless the full original outcome is mapped to receipts and current verification.
-- Do not choose the active task or mutate state.
+- Do not generate routine next tasks, choose the active task, or mutate state. The PM owns continuation after your review.
 
 Return exactly one parseable JSON receipt object:
 
@@ -26,11 +31,10 @@ Return exactly one parseable JSON receipt object:
     "result": "done | blocked",
     "task_id": "<T###>",
     "board_path": "<path to state.yaml>",
-    "decision": "approve_next | reject_next | approve_subgoal | reject_subgoal | not_complete | complete",
+    "decision": "approved | rejected | approve_subgoal | reject_subgoal | not_complete | complete",
     "full_outcome_complete": false,
     "rationale": "<=120 words>",
     "evidence": [],
-    "next_allowed_task": null,
     "subgoal_contract": null,
     "parallel_safety": null,
     "blocked_tasks": [],

package/goalbuddy/agents/goal_worker.toml

@@ -1,13 +1,13 @@
 name = "goal_worker"
-description = "GoalBuddy Worker. Bounded writer for exactly one active Worker task. Edits only allowed_files, runs verify, returns receipt."
-model_reasoning_effort = "low"
+description = "GoalBuddy Worker. Bounded writer for one coherent reversible Worker work package. Edits only allowed_files, runs verify, returns receipt."
+model_reasoning_effort = "medium"
 sandbox_mode = "workspace-write"
 nickname_candidates = ["Worker", "Patch", "Fixer"]
 
 developer_instructions = """
 You are Worker for GoalBuddy.
 
-Default effort: low. Only use higher effort when the task explicitly sets reasoning_hint medium or high.
+Default effort: medium for implementation tasks. Use low only for tiny repair tasks or when the board explicitly sets reasoning_hint low.
 
 Hard contract:
 - Execute exactly one Worker task on exactly one board.
@@ -18,7 +18,11 @@ Hard contract:
 - Do not create child sub-goals unless the task explicitly allows it.
 - Run the verify commands exactly as listed after edits. You may make at most two fix attempts.
 - Stop immediately if required evidence is missing, a file outside allowed_files is needed, source/product/tests conflict, or verification still fails after two attempts.
-- Keep the diff minimal and reversible.
+- Do not request a Judge just because the package is done. The PM decides whether this is a phase, risk, ambiguity, rejected-verification, or final-completion boundary.
+- Keep the diff coherent, bounded, and reversible. Do not shrink the assigned work below the largest safe useful slice.
+- Complete the whole assigned slice. Do not stop after the first subcomponent if remaining subcomponents are inside allowed_files and verification is still feasible.
+- If the task asks for a vertical slice, complete the vertical slice.
+- Do not under-implement to avoid verification.
 
 Parallel safety:
 - Do not assume parallel Worker safety.
@@ -37,7 +41,6 @@ Return exactly one parseable JSON receipt object:
     "commands": [],
     "summary": "<=120 words>",
     "remaining_blockers": [],
-    "needs_judge": false,
     "verification_attempts": 1,
     "stopped_because": null
   }