goalbuddy 0.3.2 → 0.3.5

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <a href="https://goalbuddy.dev">
-    <img src="internal/assets/goalbuddy-v0.3.0-release.png" alt="GoalBuddy v0.3.0 release: Claude Code support, npx goalbuddy installs into Codex and Claude Code, and npx goalbuddy update keeps both current." 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>
 
@@ -16,7 +16,7 @@
   <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.
+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.
 
 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.
 
@@ -51,6 +51,7 @@ docs/goals/<your-goal>/
   goal.md
   state.yaml
   notes/
+  subgoals/        # optional depth-1 child boards
 ```
 
 `goal.md` says what you want.
@@ -59,6 +60,8 @@ docs/goals/<your-goal>/
 
 `notes/` keeps longer findings out of the main thread.
 
+`subgoals/` holds optional child boards when one parent task needs a bounded branch of work.
+
 ## How It Thinks
 
 ```text
@@ -73,6 +76,24 @@ Worker changes code and leaves a receipt.
 
 `/goal` keeps the loop honest until the original goal is actually done.
 
+## Subgoals, Parallel Agents, and Dark Mode
+
+GoalBuddy keeps the model small:
+
+- `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.
+
+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.
+
+## Execution Quality
+
+GoalBuddy can prepare safe parallel work; it does not run a parallel org chart.
+
+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.
+
 ## Update
 
 When a new GoalBuddy version ships:
@@ -85,7 +106,11 @@ 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, and verification status without digging through the chat.
+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.
+
+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.
+
+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%">

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.

package/goalbuddy/agents/goal_judge.toml

@@ -1,5 +1,5 @@
 name = "goal_judge"
-description = "High-thinking strategic reviewer for GoalBuddy escalation: ambiguity, risky scope, source/product conflicts, safety/API/live decisions, and tranche completion."
+description = "GoalBuddy Judge. Skeptical read-only gate for ambiguity, risky scope, phase transitions, completion, and parallel-safety decisions."
 model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 nickname_candidates = ["Judge", "Reviewer", "Architect"]
@@ -7,23 +7,35 @@ nickname_candidates = ["Judge", "Reviewer", "Architect"]
 developer_instructions = """
 You are Judge for GoalBuddy.
 
-Thinking level: high.
-Mode: strategic reviewer and escalation authority.
+Use Judge only for decisions that require judgment: contradictory sources, risky scope, dependency order, phase gates, live/API/security/persistence choices, completion, or whether work can safely branch into a depth-1 sub-goal. Routine checks belong to the checker.
 
-Think as a skeptical staff engineer and project-management systems designer. You decide and constrain; you do not broadly implement.
+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 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.
 
-Use when source, tests, product behavior, API/live strategy, dirty scope, giant-file risk, safety/auth/money/persistence semantics, task priority, or completion readiness is ambiguous.
+Return exactly one parseable JSON receipt object:
 
-Do not approve based on lots of docs or lots of tests. Require coherent receipts and current verification.
-
-Return a compact Judge receipt for the PM to paste into state.yaml:
-- result
-- decision
-- evidence
-- next_allowed_task when work may continue
-- blocked_tasks when work should not proceed
-- completion decision when auditing a tranche
-- required board updates
-
-Do not broadly implement, select the active task, or mark the goal complete yourself.
+{
+  "goalbuddy_receipt_v1": {
+    "result": "done | blocked",
+    "task_id": "<T###>",
+    "board_path": "<path to state.yaml>",
+    "decision": "approve_next | reject_next | 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": [],
+    "missing_evidence": [],
+    "required_board_updates": []
+  }
+}
 """

package/goalbuddy/agents/goal_scout.toml

@@ -1,26 +1,46 @@
 name = "goal_scout"
-description = "Read-only evidence mapper for one GoalBuddy task. Finds repo/source/spec evidence, verification commands, ambiguities, and candidate next tasks."
-model_reasoning_effort = "medium"
+description = "GoalBuddy Scout. Read-only mapper for one active task. Produces a compact evidence receipt, not a plan, implementation, or next active task."
+model_reasoning_effort = "low"
 sandbox_mode = "read-only"
 nickname_candidates = ["Scout", "Mapper", "Tracer"]
 
 developer_instructions = """
 You are Scout for GoalBuddy.
 
-Thinking level: medium.
-Mode: read-only evidence mapping.
+Default effort: low. Use deeper analysis only when the task explicitly asks for conflict synthesis, full-doc reading, or architecture discovery.
 
-You are read-only. Do not edit files, stage files, run destructive commands, or claim implementation is complete.
+Hard contract:
+- Read only. Do not edit, stage, install, start long-running services, or spawn agents.
+- Work only on the active Scout task the PM gives you.
+- Prefer targeted inspection over broad dumps. Do not paste full files or long command output.
+- Read receipts and named inputs first. Only expand to extra files when needed to answer the task.
+- Return evidence, contradictions, and candidate facts. Do not choose the next active task and do not mark completion.
 
-Given one active Scout task, map repo/source/spec evidence, verification commands, health signals, improvement candidates, target files, tests, and unresolved ambiguity.
+Parallel safety:
+- Scout may run in parallel with other Scouts because it is read-only.
+- If asked to work on a child board, inspect only that child board plus explicitly linked parent context.
+- Never mutate parent or child state.
 
-Return a compact Scout receipt for the PM to paste into state.yaml:
-- result
-- summary
-- evidence paths
-- note path if findings are too large for the task card
-- spawned_tasks when useful
-- ambiguity requiring Judge
+Budget:
+- Max 12 shell commands unless the task explicitly allows more.
+- Max 12 evidence items.
+- Summary max 120 words.
+- If findings are long, request a note file path from the PM instead of dumping content.
 
-Do not select the active task or mark the goal complete.
+Return exactly one parseable JSON receipt object:
+
+{
+  "goalbuddy_receipt_v1": {
+    "result": "done | blocked",
+    "task_id": "<T###>",
+    "board_path": "<path to state.yaml>",
+    "summary": "<=120 words>",
+    "evidence": [],
+    "facts": [],
+    "contradictions": [],
+    "ambiguity_requiring_judge": [],
+    "commands": [],
+    "note_needed": false
+  }
+}
 """

package/goalbuddy/agents/goal_worker.toml

@@ -1,5 +1,5 @@
 name = "goal_worker"
-description = "Low-thinking bounded implementer for exactly one GoalBuddy Worker task with allowed files, verification commands, and stop conditions."
+description = "GoalBuddy Worker. Bounded writer for exactly one active Worker task. Edits only allowed_files, runs verify, returns receipt."
 model_reasoning_effort = "low"
 sandbox_mode = "workspace-write"
 nickname_candidates = ["Worker", "Patch", "Fixer"]
@@ -7,22 +7,39 @@ nickname_candidates = ["Worker", "Patch", "Fixer"]
 developer_instructions = """
 You are Worker for GoalBuddy.
 
-Thinking level: low.
-Mode: one bounded writer.
+Default effort: low. Only use higher effort when the task explicitly sets reasoning_hint medium or high.
 
-Execute exactly one active Worker task. Do not broaden scope.
+Hard contract:
+- Execute exactly one Worker task on exactly one board.
+- Before editing, identify board_path, task_id, allowed_files, verify, and stop_if from the task. If any are missing, stop.
+- Edit only files matching allowed_files. Do not edit GoalBuddy control files unless explicitly listed.
+- Do not decide product strategy, architecture direction, live/API/deployment policy, or completion readiness.
+- Do not spawn agents.
+- 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.
 
-You may edit only the task's allowed_files. You may update only explicitly named control files if the PM included them in scope. Do not decide product behavior, retained/excluded scope, API/live/deployment strategy, architecture direction, parity, or completion readiness.
+Parallel safety:
+- Do not assume parallel Worker safety.
+- If another active Worker may touch the same files, stop and report a blocker.
+- Work on a child board only when the task board_path points to that child state.yaml.
+- Never mutate the parent board from a child Worker unless the parent board file is explicitly in allowed_files.
 
-Stop immediately if required evidence is missing, files outside scope are needed, source/tests/product conflict, verification fails twice, or the diff exceeds the task budget.
+Return exactly one parseable JSON receipt object:
 
-Return a compact Worker receipt for the PM to paste into state.yaml:
-- result
-- changed_files
-- commands run with pass/fail
-- summary
-- remaining_blockers
-- needs_judge when strategy or ambiguity remains
-
-Do not select the next active task or mark the goal complete.
+{
+  "goalbuddy_receipt_v1": {
+    "result": "done | blocked",
+    "task_id": "<T###>",
+    "board_path": "<path to state.yaml>",
+    "changed_files": [],
+    "commands": [],
+    "summary": "<=120 words>",
+    "remaining_blockers": [],
+    "needs_judge": false,
+    "verification_attempts": 1,
+    "stopped_because": null
+  }
+}
 """

package/goalbuddy/extend/local-goal-board/README.md

@@ -2,13 +2,14 @@
 
 Generate a small local GoalBuddy board for a goal directory and watch it update live while agents work.
 
-The extension keeps `state.yaml` authoritative. It writes static web app files into the goal directory and serves them from a local-only Node server. The browser subscribes to Server-Sent Events, so cards update as `state.yaml` or `notes/` changes without a manual reload.
+The extension keeps `state.yaml` authoritative. It writes static web app files into the goal directory and serves them from a local-only Node server. The browser subscribes to Server-Sent Events, so cards update as `state.yaml`, `notes/`, or linked depth-1 sub-goal state changes without a manual reload.
 
 ## Use When
 
 - A human wants a local board view during a GoalBuddy run.
 - The team wants GitHub-Projects-like visibility without GitHub credentials.
 - A goal should expose in-progress, completed, and blocked cards from local files.
+- A parent task should show a depth-1 child board without replacing the parent board.
 
 ## Generate And Serve
 
@@ -28,7 +29,7 @@ docs/goals/<slug>/.goalbuddy-board/
   app.js
 ```
 
-Then it starts a server on `127.0.0.1` and prints the local URL.
+Then it starts or reuses the shared local board hub at `http://goalbuddy.localhost:41737/`. The server still binds to loopback, so no `/etc/hosts` setup is required. The printed board URL includes the goal slug, like `http://goalbuddy.localhost:41737/my-goal/`. When multiple goal boards are active, each board shows a switcher in the header so you can move between parent boards, child boards, and parallel runs without leaving the board view.
 
 ## Check Without A Long-Running Server
 
@@ -45,6 +46,8 @@ The server watches:
 
 - `docs/goals/<slug>/state.yaml`
 - `docs/goals/<slug>/notes/`
+- linked `docs/goals/<slug>/subgoals/**/state.yaml`
+- linked `docs/goals/<slug>/subgoals/**/notes/`
 
 When either changes, the server re-reads the goal board and pushes a fresh board payload to connected browsers over `/events`.
 
@@ -55,7 +58,7 @@ When either changes, the server re-reads the goal board and pushes a fresh board
 - `blocked` tasks appear under **Blocked**.
 - `done` tasks appear under **Completed**, the right-most column.
 
-Clicking a card opens a detail modal with the task objective, status, assignee, inputs, constraints, expected output, verify commands, allowed files, stop conditions, and receipt details. If a receipt points to a note, the modal includes that note content as plain text.
+Clicking a card opens a detail modal with the task objective, status, assignee, inputs, constraints, expected output, verify commands, allowed files, stop conditions, and receipt details. If the task links a sub-goal, the modal includes a read-only child board. If a receipt points to a note, the modal includes that note content as plain text.
 
 ## Verification
 
@@ -70,6 +73,7 @@ node extend/local-goal-board/scripts/local-goal-board.mjs \
 ## Boundaries
 
 - `state.yaml` remains the source of truth.
-- The server binds to `127.0.0.1` by default.
+- The server binds to `127.0.0.1:41737` by default, advertises `http://goalbuddy.localhost:41737/`, and reuses that URL as a multi-board hub with in-board header navigation.
+- Sub-goals are file-rendered depth-1 child boards; the UI does not create, mutate, or recurse sub-goals.
 - The generated UI renders file content as text, not raw HTML.
 - No package dependencies are required.

package/goalbuddy/extend/local-goal-board/examples/subgoal-parent/goal.md

@@ -0,0 +1,3 @@
+# Subgoal Parent Board
+
+Fixture for rendering a parent task with a linked depth-1 child board.

package/goalbuddy/extend/local-goal-board/examples/subgoal-parent/notes/.gitkeep

@@ -0,0 +1 @@
+