goalbuddy 0.3.1 → 0.3.5

package/README.md

@@ -2,12 +2,12 @@
 
 <p align="center">
   <a href="https://goalbuddy.dev">
-    <img src="internal/assets/goalbuddy-readme-hero.png" alt="GoalBuddy: a /goal operating system for Codex and Claude Code with live boards, Scout, Judge, Worker, receipts, and verification." width="100%">
+    <img src="internal/assets/goalbuddy-v0.3.5-release.png" alt="GoalBuddy v0.3.5 release: Subgoals, parallel agents, and dark mode." width="100%">
   </a>
 </p>
 
 <p align="center">
-  <strong>A /goal operating system for Codex and Claude Code: intake, live boards, agents, receipts, and verification.</strong>
+  <strong>A simple operating loop for long <code>/goal</code> runs.</strong>
 </p>
 
 <p align="center">
@@ -16,243 +16,121 @@
   <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 is a local companion for **Codex** and **Claude Code** when the work is too broad to trust to a single prompt. It turns rough intent into a durable operating loop: a `goal.md` charter, a machine-readable `state.yaml` board, optional visual boards, Scout/Judge/Worker task flow, compact receipts, and verification before completion.
+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.
 
-```bash
-npx goalbuddy                  # installs for Codex and Claude Code
-npx goalbuddy --target codex   # installs for Codex only
-npx goalbuddy --target claude  # installs for Claude Code only
-```
+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.
 
-Or install it globally:
+## Start Here
+
+Run one command:
 
 ```bash
-npm i -g goalbuddy
+npx goalbuddy
 ```
 
-Then restart your AI coding agent and invoke the installed skill:
+Restart Codex or Claude Code.
+
+Then prepare a goal:
 
 ```text
-$goal-prep      # in Codex
-/goal-prep      # in Claude Code
+$goal-prep
 ```
 
-`goal-prep` prepares the GoalBuddy board and prints the `/goal` command to run next. It does not start `/goal` automatically.
-
-## Why GoalBuddy Exists
-
-Long-running goals in Codex and Claude Code drift. A request like "improve this project" can turn into unbounded edits, stale verification, and premature completion claims.
-
-GoalBuddy gives your AI coding agent a durable loop:
+In Claude Code, use:
 
 ```text
-vague goal -> Scout -> Judge -> Worker -> receipt -> verify -> repeat
+/goal-prep
 ```
 
-The main `/goal` thread acts as PM. It owns the board, keeps exactly one active task, delegates when useful, records receipts, and only completes after a Judge or PM audit proves the original outcome is done.
+Goal Prep creates the board and prints the exact `/goal` command to run next. That is the whole path.
 
-## What You Get Locally
+## What It Creates
 
 ```text
-docs/goals/<slug>/
+docs/goals/<your-goal>/
   goal.md
   state.yaml
   notes/
+  subgoals/        # optional depth-1 child boards
 ```
 
-- `goal.md` is the editable charter: objective, constraints, tranche, and stop rule.
-- `state.yaml` is the board truth: task status, active task, receipts, and verification.
-- `notes/` holds longer Scout, Judge, or PM findings when a task receipt would be too large.
+`goal.md` says what you want.
 
-## The Operating Model
+`state.yaml` tracks the board.
 
-GoalBuddy uses four primitives:
+`notes/` keeps longer findings out of the main thread.
 
-- **Charter**: states what this goal is trying to accomplish and what must stay true.
-- **Board**: tracks tasks, status, receipts, and verification freshness.
-- **Task**: exactly one active Scout, Judge, Worker, or PM task.
-- **Receipt**: compact proof for every completed, blocked, or escalated task.
+`subgoals/` holds optional child boards when one parent task needs a bounded branch of work.
 
-GoalBuddy bundles default agent templates. `goal-prep` records whether matching installed agent configs were actually found; if not, `/goal` can continue through PM fallback, or you can install dedicated agents with:
+## How It Thinks
 
-```bash
-npx goalbuddy agents                  # Codex TOML agents
-npx goalbuddy agents --target claude  # Claude Code markdown subagents
+```text
+rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verify
 ```
 
-- **Scout** maps repo evidence, workflows, constraints, risks, and candidate next tasks.
-- **Judge** resolves ambiguity, scope, risk, task selection, and completion claims.
-- **Worker** performs one bounded implementation or recovery slice with explicit files and checks.
+Scout maps the repo.
 
-## Install Everywhere
-
-```bash
-npx goalbuddy
-```
+Judge chooses the next bounded slice.
 
-This installs and enables the native Codex plugin in `~/.codex/`, then installs the GoalBuddy skill, Scout/Judge/Worker subagents, and `/goal-prep` slash command into `~/.claude/`. Restart Codex and Claude Code, then use `$goal-prep` in Codex or `/goal-prep` in Claude Code. The Codex plugin bundles the local live board and GitHub Projects visual board backends so Goal Prep can offer a board immediately.
+Worker changes code and leaves a receipt.
 
-If you prefer a global executable:
+`/goal` keeps the loop honest until the original goal is actually done.
 
-```bash
-npm i -g goalbuddy
-goalbuddy
-```
+## Subgoals, Parallel Agents, and Dark Mode
 
-Native Codex `/goal` is still an under-development Codex feature. Before relying on the printed command, confirm your local Codex runtime is logged in and has goals enabled:
+GoalBuddy keeps the model small:
 
-```bash
-codex login status
-codex features enable goals
-npx goalbuddy doctor --goal-ready
-```
+- `state.yaml` is the source of truth.
+- A board is a view of one `state.yaml`.
+- The local hub is a switchboard for many boards.
+- A subgoal is one depth-1 `state.yaml` linked from a parent task.
+- Settings are viewer preferences, not workflow state.
 
-## Install One Target
+Use subgoals for bounded child work that belongs to a parent task. Use multiple local boards when parallel agents or separate goal runs are active at the same time. Keep the board open in light or dark mode while the work moves.
 
-Use `--target` when you only want to install or update one agent environment:
+## Execution Quality
 
-```bash
-npx goalbuddy --target codex
-npx goalbuddy --target claude
-```
+GoalBuddy can prepare safe parallel work; it does not run a parallel org chart.
 
-The Claude Code target installs the GoalBuddy skill, the three Scout/Judge/Worker subagents, and the `/goal-prep` slash command into `~/.claude/`. Restart Claude Code, then run:
+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.
 
-```text
-/goal-prep
-```
+## Update
 
-Check the local Claude Code install:
+When a new GoalBuddy version ships:
 
 ```bash
-npx goalbuddy doctor --target claude
+npx goalbuddy update
 ```
 
-Use non-default homes:
+That updates both Codex and Claude Code.
 
-```bash
-npx goalbuddy --codex-home /path/to/.codex --claude-home /path/to/.claude
-npx goalbuddy --target codex --codex-home /path/to/.codex
-npx goalbuddy --target claude --claude-home /path/to/.claude
-```
+## Live Boards
 
-`install` and `update` prepare both targets by default. `install`, `update`, `doctor`, and `agents` all accept `--target claude|codex`, and `--json` for structured output.
+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.
 
-## Run A Goal
+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.
 
-After `goal-prep` creates or repairs the board, start the run with the printed command:
-
-```text
-/goal Follow docs/goals/<slug>/goal.md.
-```
-
-Check board health at any time:
-
-```bash
-# Codex
-node ~/.codex/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
-# Claude Code
-node ~/.claude/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
-```
-
-For a broad prompt like "Improve my project," the first active task should usually be Scout, not Worker:
-
-```yaml
-tasks:
-  - id: T001
-    type: scout
-    assignee: Scout
-    status: active
-    objective: "Map repo health and identify improvement candidates."
-    receipt: null
-  - id: T002
-    type: judge
-    assignee: Judge
-    status: queued
-    objective: "Choose the next safe implementation task."
-    receipt: null
-  - id: T003
-    type: worker
-    assignee: Worker
-    status: queued
-    objective: "Execute the safe implementation task selected by Judge."
-    allowed_files: []
-    verify: []
-    stop_if:
-      - "Need files outside allowed_files."
-      - "Verification fails twice."
-    receipt: null
-```
-
-## Visual Boards
-
-GoalBuddy can show progress as the goal runs. `goal-prep` can open a local live board inside your AI coding agent before the task list is finished, or prepare a GitHub Projects sync when stakeholders need an external board.
+See [GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode](RELEASE-0.3.5.md) for the 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%">
 </p>
 
-## Extensions
-
-The npm package is the stable core. Local Board and GitHub Projects are bundled into the installed GoalBuddy skill so `goal-prep` can offer a visual board immediately. Other optional extensions live under `extend/` and are discovered from the GitHub-hosted `extend/catalog.json`, so users do not need a new npm release for every integration.
-
-```bash
-npx goalbuddy board docs/goals/<slug>
-npx goalbuddy extend github-projects
-npx goalbuddy extend
-npx goalbuddy extend github-pr-workflow
-npx goalbuddy extend install github-pr-workflow --dry-run
-```
-
-`goalbuddy extend` shows available extensions and detail commands. `goalbuddy extend <id>` shows local install state, activation state, credential requirements, safe-by-default status, and missing environment variables.
-
-Current catalog examples include:
-
-- `github-pr-workflow`: prepares receipt-aligned commit and PR handoff text.
-- `github-projects`: mirrors GoalBuddy boards into GitHub Projects.
-- `local-goal-board`: serves a local live board that updates from `state.yaml` and `notes/`.
-- `ai-diff-risk-review`: summarizes risk in the current diff.
-- `ci-failure-triage`: maps failing CI back to likely causes and next tasks.
-- `docs-drift-audit`: checks whether docs still match implementation.
-- `codebase-onboarding-map`: creates a concise repo map from files and conventions.
-- `release-readiness`: checks whether a goal is ready to publish.
-
-Extensions can publish, report, intake, or add role guidance. They are not board truth. `state.yaml` remains authoritative.
-
-## Compatibility Window
-
-GoalBuddy was previously published as `goal-maker`. During the migration window, `npx goal-maker` remains available as a compatibility alias and prints the new command:
-
-```bash
-npx goalbuddy
-```
-
-Machine-readable commands such as `npx goal-maker install --json` keep JSON output clean so existing automation can migrate safely.
-
-Release automation for future npm publishes is documented in [RELEASE.md](RELEASE.md).
-
-## Examples
-
-- `examples/improve-goal-maker/`: a small completed reliability run.
-- `examples/extend-catalog-workflow/`: a larger run from product framing through implementation and cleanup.
-- `examples/github-pr-workflow-extension/pr-handoff.md`: an extension-generated PR handoff artifact.
+## Good For
 
-## Repo Map
+- broad project improvements
+- release prep
+- bug hunts that need evidence
+- refactors with verification steps
+- anything too large for one prompt
 
-- `goalbuddy/SKILL.md`: canonical skill definition (shared by Codex and Claude Code)
-- `goalbuddy/agents/`: Scout, Judge, and Worker agent definitions (Codex TOML; Claude Code markdown lives under `plugins/goalbuddy/agents/`)
-- `goalbuddy/templates/`: `goal.md`, `state.yaml`, and `note.md`
-- `goalbuddy/scripts/check-goal-state.mjs`: v2 board checker
-- `internal/cli/goal-maker.mjs`: npm installer CLI for Codex and Claude Code
-- `plugins/goalbuddy/`: Codex plugin (`.codex-plugin/`) and Claude Code plugin (`.claude-plugin/`) scaffolds
-- `extend/` and `extend/catalog.json`: GitHub-hosted extension surface
-- `examples/`: completed sample runs
+## For This Repo
 
-## Status
+GoalBuddy is MIT licensed and published on npm.
 
-`0.3.x` adds first-class Claude Code support alongside the existing Codex target. The v2 board and receipt model intentionally rejects old v1 `gate`, `units`, `artifacts`, and `evidence.jsonl` goal folders instead of auto-migrating them.
+The implementation lives in this repo, but the happy path is intentionally tiny: install it, run Goal Prep, then let `/goal` work from the generated files.
 
-Use GoalBuddy to structure autonomous coding-agent work. Keep relying on repo-specific `AGENTS.md`/`CLAUDE.md`, tests, and CI for repo facts.
+For release process details, see [RELEASE.md](RELEASE.md).
 
 ## Star History
 

package/RELEASE-0.3.5.md

@@ -0,0 +1,324 @@
+# GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode
+
+Release date: 2026-05-12
+
+![GoalBuddy v0.3.5 release: Subgoals, parallel agents, and dark mode.](https://raw.githubusercontent.com/tolibear/goalbuddy/v0.3.5/internal/assets/goalbuddy-v0.3.5-release.png)
+
+This is the release where GoalBuddy starts feeling less like a single board and more like a calm local workspace for serious agent work.
+
+0.3.5 adds three big things:
+
+- **Subgoals**: depth-1 child boards for branching work.
+- **Parallel agents**: safe, explicit surfaces for parallel Scout, Judge, and bounded Worker handoffs.
+- **Dark mode**: a cleaner local board that can stay open all day without punishing your eyes.
+
+Under the hood, this release also hardens GoalBuddy's execution model: stricter agent contracts, deterministic task prompts, conservative parallel planning, stronger checker rules, and safer child-board rendering.
+
+Update with:
+
+```bash
+npx goalbuddy update
+```
+
+## The Headline
+
+GoalBuddy still has one simple job: keep long `/goal` runs oriented until the real outcome is done.
+
+0.3.5 makes that loop much easier to run when the work branches, when more than one agent is helping, or when you want a live board open beside Codex or Claude Code.
+
+The model stays intentionally small:
+
+- `goal.md` is the charter.
+- `state.yaml` is the ledger.
+- A board is a view of one `state.yaml`.
+- A subgoal is one depth-1 child `state.yaml` linked from a parent task.
+- The local hub is navigation, not workflow truth.
+- Viewer settings are preferences, not state.
+
+## Subgoals
+
+Subgoals give GoalBuddy a clean way to branch without turning into project-management software.
+
+A parent task can now link to a child board under `subgoals/`:
+
+```yaml
+subgoal:
+  status: active
+  path: subgoals/T004-board-view/state.yaml
+  owner: Worker
+  created_from: T004
+  depth: 1
+  rollup_receipt: null
+```
+
+The local board renders that child board inside the parent task detail, so you can open one task and see the focused child workflow underneath it.
+
+What this is good for:
+
+- a parent task that needs a focused implementation branch
+- a verification slice that deserves its own mini-board
+- a Scout/Judge/Worker path that should stay bounded
+- parallel work that needs a visible surface without losing the parent context
+
+What it is not:
+
+- recursive planning
+- nested subgoals
+- a separate project hierarchy
+- a new source of truth
+
+One parent task can have one depth-1 child board. That is the whole trick.
+
+## Parallel Agents
+
+GoalBuddy 0.3.5 is parallel-agent-ready, but deliberately not an automatic scheduler.
+
+That distinction matters.
+
+GoalBuddy now helps you prepare safe parallel work surfaces:
+
+- Scouts are read-only and safe to run in parallel by default.
+- Judges are read-only and safe on separate board decisions.
+- Workers are only safe when they are on separate boards or have provably disjoint `allowed_files`.
+- Ambiguous Worker write scopes fail closed.
+
+Use the new planner:
+
+```bash
+goalbuddy parallel-plan docs/goals/<slug>
+```
+
+It reports active tasks across the parent board and linked child boards:
+
+- board path
+- task id
+- role
+- recommended agent
+- reasoning hint
+- whether it is safe to parallelize
+- why
+- the exact prompt-render command
+
+It does not mutate state. It does not spawn agents. It does not pretend overlap is safe.
+
+That keeps GoalBuddy in the sweet spot: it makes parallel execution easier to see and safer to hand off, while native Codex or Claude Code agent flows still do the actual dispatch.
+
+## Dark Mode
+
+The local board now has real dark mode.
+
+Not "the background changed and half the text disappeared" dark mode. The board, task cards, modals, settings, detail sections, receipt text, and embedded child boards all get readable dark styling.
+
+The board also adds global viewer settings:
+
+- Theme: system, light, dark
+- Density: comfortable, compact
+- Completed column: show, collapse
+- Open boards: last viewed, newest
+- Motion: system, reduce, allow
+
+Settings are local viewer preferences and live at:
+
+```text
+~/.goalbuddy/local-board-settings.json
+```
+
+Tests can override that path with:
+
+```bash
+GOALBUDDY_LOCAL_BOARD_SETTINGS_PATH=/tmp/goalbuddy-settings.json
+```
+
+## The Local Board Got Sharper
+
+The board header now matches the GoalBuddy site style more closely:
+
+- GoalBuddy mark and wordmark
+- green live blip beside the wordmark
+- board selector only when multiple boards are running
+- GitHub stars link that opens in a new window
+- cleaner settings gear
+
+Multiple boards now share one readable local hub:
+
+```text
+http://goalbuddy.localhost:41737/
+```
+
+Each board gets its own path:
+
+```text
+http://goalbuddy.localhost:41737/subgoal-parent-board/
+http://goalbuddy.localhost:41737/local-kanban-board-extension/
+```
+
+Launch another board while the hub is already running and GoalBuddy registers it with the existing local server instead of replacing the first board.
+
+If port `41737` is occupied by something that is not GoalBuddy, the CLI says so clearly.
+
+## Active Work Is Easier To See
+
+Active cards now have a visible in-progress treatment: a subtle moving border that makes the current task obvious at a glance.
+
+The motion respects:
+
+- `prefers-reduced-motion`
+- the board Motion setting
+
+So the board can feel alive without becoming noisy.
+
+## Better Agent Contracts
+
+Scout, Judge, and Worker now have sharper contracts.
+
+Scout:
+
+- read-only
+- compact evidence
+- no edits
+- no task selection
+- receipt-shaped output
+
+Judge:
+
+- read-only
+- phase gates and risky decisions only
+- completion skepticism
+- parallel-safety decisions
+- subgoal approval boundaries
+
+Worker:
+
+- edits only `allowed_files`
+- runs listed verification
+- stops when scope expands
+- returns changed files and verification results
+- treats parallel Worker safety conservatively
+
+This is the durable GoalBuddy model:
+
+```text
+Scout maps. Judge gates. Worker patches. Receipts prove. state.yaml decides.
+```
+
+## Deterministic Prompt Rendering
+
+New command:
+
+```bash
+goalbuddy prompt docs/goals/<slug>
+goalbuddy prompt docs/goals/<slug> --task T004
+goalbuddy prompt --board docs/goals/<slug>/state.yaml --task T004
+```
+
+The renderer emits compact task-specific prompts with:
+
+- board path
+- task id
+- task type
+- objective
+- inputs
+- constraints
+- allowed files
+- verify commands
+- stop conditions
+- reasoning hint
+- recommended agent
+- expected receipt shape
+
+It avoids the bad handoff pattern where a subagent gets the entire state file, chat history assumptions, and too much inherited context.
+
+## Checker And Durability
+
+The checker now understands 0.3.5 branching.
+
+It accepts:
+
+- depth-1 subgoals under the parent goal root
+- child boards with `goal.md`, `state.yaml`, and `notes/`
+- parent tasks linked to valid child boards
+- Worker changed files that match simple `allowed_files` globs
+
+It rejects:
+
+- child paths outside the parent root
+- child paths that do not point to `state.yaml`
+- missing child state files
+- nested child subgoals
+- invalid child board state
+- done Workers with changed files outside scope
+- final completion without the expected verification and audit evidence
+
+The board renderer also fails closed on invalid child paths, so a malformed subgoal cannot make the local board read a `state.yaml` outside the parent goal root.
+
+## Demo
+
+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
+```
+
+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`
+
+## Tests
+
+0.3.5 adds or expands coverage for:
+
+- parent task subgoal payloads
+- embedded child boards
+- missing child state files
+- outside-root child paths
+- live child-state updates over SSE
+- multi-board hub registration
+- settings persistence and normalization
+- dark-mode readability surfaces
+- prompt rendering
+- read-only parallel planning
+- overlapping Worker write scopes
+- overlapping Worker glob patterns
+- checker rejection for outside-root, missing, and nested subgoals
+- plugin/source mirror consistency
+
+Verified locally with:
+
+```bash
+npm run check
+git diff --check
+npm run publish:check
+```
+
+## Release Boundaries
+
+This release intentionally does not add:
+
+- automatic parallel-agent spawning
+- a parallel Worker scheduler
+- automatic receipt application
+- UI controls for creating or editing subgoals
+- recursive/nested subgoals
+- cloud-hosted board state
+
+The principle is Karpathy-level simple:
+
+```text
+One board owns one state file. A subgoal is one child state file. Parallel work is allowed only when the write boundaries are clear.
+```
+
+That gives GoalBuddy a stronger execution loop without making it heavy.
+
+## Package Notes
+
+This release updates:
+
+- npm package version: `0.3.5`
+- Codex plugin version: `0.3.5`
+- Claude Code plugin version: `0.3.5`
+- mirrored GoalBuddy skill files under `plugins/goalbuddy/skills/goalbuddy/`

package/goalbuddy/SKILL.md

@@ -85,7 +85,7 @@ Recommended options:
 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.
 
-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). 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. Keep the printed URL in the final prep response as a 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 the operator fallback, but do not make the URL the primary experience.
 
 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.
 
@@ -506,7 +506,7 @@ Non-`installed` states are warnings, not false failures, because the main `/goal
 
 | Agent | Thinking level | Write access | Use for |
 |---|---:|---:|---|
-| Scout | medium | no | source/spec/repo evidence mapping |
+| 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 |
 
@@ -538,6 +538,12 @@ reasoning_hint: default # default | low | medium | high | xhigh
 
 Treat `reasoning_hint` as PM guidance. It does not override task scope, write permissions, stop conditions, or the one-active-task rule.
 
+## 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 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.
+
 ## Completion
 
 Never complete because work looks substantial.