goalbuddy 0.3.6 → 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
 
@@ -70,6 +70,7 @@ docs/goals/<your-goal>/
   goal.md
   state.yaml
   notes/
+  .goalbuddy-board/ # generated local board files
   subgoals/        # optional depth-1 child boards
 ```
 
@@ -84,16 +85,22 @@ 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 largest safe useful slice.
 
 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.
 
 ## Slice Sizing
 
@@ -101,7 +108,7 @@ 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.
 
-## Subgoals, Parallel Agents, and Dark Mode
+## Goalmaxxed
 
 GoalBuddy keeps the model small:
 
@@ -115,7 +122,7 @@ 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. 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.
 
@@ -131,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.
 
-See [GoalBuddy 0.3.5: Subgoals, Parallel Agents, and Dark Mode](RELEASE-0.3.5.md) for the release notes.
+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.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 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;
@@ -234,7 +242,7 @@ Use this skill for goals that are broad, multi-hour, ambiguous, high-risk, alrea
 
 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
 
@@ -274,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?

package/goalbuddy/scripts/check-goal-state.mjs

@@ -53,6 +53,38 @@ function nestedScalar(section, key) {
   return null;
 }
 
+function pathScalar(path, key) {
+  const lines = text.split(/\r?\n/);
+  let depth = 0;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const indent = line.match(/^ */)[0].length;
+    if (indent < depth * 2) depth = Math.floor(indent / 2);
+
+    if (depth < path.length && indent === depth * 2 && new RegExp(`^\\s{${indent}}${path[depth]}:\\s*$`).test(line)) {
+      depth += 1;
+      continue;
+    }
+
+    if (depth === path.length && indent === depth * 2) {
+      const match = line.match(new RegExp(`^\\s{${indent}}${key}:\\s*(.*?)\\s*$`));
+      if (match) return clean(match[1]);
+    }
+  }
+  return null;
+}
+
+function isWeakProof(value) {
+  if (value === null || value === undefined) return true;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === ""
+    || normalized === "unknown"
+    || normalized === "tbd"
+    || normalized === "todo"
+    || normalized === "none"
+    || /^<.*>$/.test(normalized);
+}
+
 function sectionText(section) {
   const lines = text.split(/\r?\n/);
   const start = lines.findIndex((line) => new RegExp(`^${section}:\\s*$`).test(line));
@@ -225,6 +257,11 @@ const allowedAgentStatuses = new Set(["installed", "bundled_not_installed", "mis
 const continuousUntilFullOutcome = nestedScalar("rules", "continuous_until_full_outcome") === true;
 const missingInputOrCredentialsDoNotStopGoal =
   nestedScalar("rules", "missing_input_or_credentials_do_not_stop_goal") === true;
+const goalPressureRequiresOracle = nestedScalar("rules", "goal_pressure_requires_oracle") !== false;
+const noCompletionOnWeakProof = nestedScalar("rules", "no_completion_on_weak_proof") !== false;
+const completionProof = pathScalar(["goal", "intake"], "completion_proof");
+const oracleSignal = pathScalar(["goal", "oracle"], "signal");
+const oracleFinalProof = pathScalar(["goal", "oracle"], "final_proof");
 const legacySignals = [
   /^gate:\s*$/m,
   /^artifact_policy:\s*$/m,
@@ -244,6 +281,19 @@ if (!["active", "blocked", "done"].includes(goalStatus)) {
   errors.push(`goal.status must be active, blocked, or done; got ${goalStatus || "<missing>"}`);
 }
 
+if (goalPressureRequiresOracle) {
+  if (isWeakProof(oracleSignal)) {
+    warnings.push("goal.oracle.signal is missing or placeholder-like; weak oracles make /goal finish too early.");
+  }
+  if (isWeakProof(oracleFinalProof)) {
+    warnings.push("goal.oracle.final_proof is missing or placeholder-like; final completion needs receipt-backed proof.");
+  }
+}
+
+if (isWeakProof(completionProof)) {
+  warnings.push("goal.intake.completion_proof is missing or placeholder-like; record the observable signal that proves the full original outcome.");
+}
+
 function agentStatusWarning(agent, status) {
   const agentLabel = agent[0].toUpperCase() + agent.slice(1);
   if (status === "bundled_not_installed") {
@@ -532,6 +582,9 @@ function escapeRegExp(value) {
 }
 
 if (goalStatus === "done") {
+  if (noCompletionOnWeakProof && (isWeakProof(completionProof) || isWeakProof(oracleSignal) || isWeakProof(oracleFinalProof))) {
+    errors.push("done goals require concrete completion proof, goal.oracle.signal, and goal.oracle.final_proof; weak proof cannot close a goal");
+  }
   const finalAudit = tasks.some((task) => {
     if (!["judge", "pm"].includes(task.type) || task.status !== "done") return false;
     if (!task.receipt.present || task.receipt.value === null) return false;

package/goalbuddy/scripts/render-task-prompt.mjs

@@ -2,7 +2,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseGoalStateText } from "../extend/local-goal-board/scripts/lib/goal-board.mjs";
+import { parseGoalStateText } from "../surfaces/local-goal-board/scripts/lib/goal-board.mjs";
 
 const ROLE_DEFAULTS = {
   scout: { agent: "goal_scout", reasoning: "low", sandbox: "read-only" },
@@ -45,6 +45,7 @@ export function renderTaskPrompt(options) {
         fork_context_allowed: role !== "worker",
         board_path: board.path,
         child_board_paths: childBoardPaths(board),
+        goal_oracle: board.goal.oracle || null,
         slice_policy: board.document.rules?.slice_policy || null,
         warnings,
       },
@@ -141,6 +142,12 @@ function promptWarnings(board, task) {
   const warnings = [];
   const role = normalizeRole(task.type);
   if (task.id !== board.activeTask) warnings.push(`Task ${task.id} is not the active task on this board.`);
+  if (isWeakProof(board.goal.oracle?.signal)) {
+    warnings.push("goal.oracle.signal is missing or placeholder-like; keep the goal pressured by a concrete completion oracle.");
+  }
+  if (isWeakProof(board.goal.oracle?.final_proof)) {
+    warnings.push("goal.oracle.final_proof is missing or placeholder-like; do not mark the goal complete without receipt-backed proof.");
+  }
   if (role === "worker") {
     if (stringList(task.allowed_files).length === 0) warnings.push(`Worker task ${task.id} has no allowed_files.`);
     if (stringList(task.verify).length === 0) warnings.push(`Worker task ${task.id} has no verify commands.`);
@@ -211,6 +218,17 @@ function isTrue(value) {
   return value === true || String(value).toLowerCase() === "true";
 }
 
+function isWeakProof(value) {
+  if (value === null || value === undefined) return true;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === ""
+    || normalized === "unknown"
+    || normalized === "tbd"
+    || normalized === "todo"
+    || normalized === "none"
+    || /^<.*>$/.test(normalized);
+}
+
 function stringList(value) {
   return Array.isArray(value) ? value.filter((item) => item !== null && item !== undefined).map(String) : [];
 }
@@ -261,6 +279,9 @@ function formatPrompt(payload) {
     lines.push("- child_board_paths:");
     for (const path of payload.metadata.child_board_paths) lines.push(`  - ${path}`);
   }
+  if (payload.metadata.goal_oracle) {
+    lines.push(`- goal_oracle: ${JSON.stringify(payload.metadata.goal_oracle)}`);
+  }
   if (payload.metadata.slice_policy) {
     lines.push(`- slice_policy: ${JSON.stringify(payload.metadata.slice_policy)}`);
   }

package/{plugins/goalbuddy/skills/goalbuddy/extend → goalbuddy/surfaces}/local-goal-board/README.md

@@ -2,7 +2,7 @@
 
 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`, `notes/`, or linked depth-1 sub-goal state changes without a manual reload.
+The surface 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
 
@@ -14,11 +14,10 @@ The extension keeps `state.yaml` authoritative. It writes static web app files i
 ## Generate And Serve
 
 ```bash
-node extend/local-goal-board/scripts/local-goal-board.mjs \
-  --goal docs/goals/<slug>
+npx goalbuddy board docs/goals/<slug>
 ```
 
-The generated app includes the bundled `assets/goalbuddy-mark.png`, so the board keeps the GoalBuddy mark after the extension is installed or copied elsewhere.
+The generated app includes the bundled `assets/goalbuddy-mark.png`, so the board keeps the GoalBuddy mark anywhere the package is installed.
 
 The command writes:
 
@@ -34,8 +33,7 @@ Then it starts or reuses the shared local board hub at `http://goalbuddy.localho
 ## Check Without A Long-Running Server
 
 ```bash
-node extend/local-goal-board/scripts/local-goal-board.mjs \
-  --goal docs/goals/<slug> \
+npx goalbuddy board docs/goals/<slug> \
   --once \
   --json
 ```
@@ -63,9 +61,9 @@ Clicking a card opens a detail modal with the task objective, status, assignee,
 ## Verification
 
 ```bash
-node --test extend/local-goal-board/test/*.test.mjs
-node extend/local-goal-board/scripts/local-goal-board.mjs \
-  --goal extend/local-goal-board/examples/sample-goal \
+node --test goalbuddy/surfaces/local-goal-board/test/*.test.mjs
+node goalbuddy/surfaces/local-goal-board/scripts/local-goal-board.mjs \
+  --goal goalbuddy/surfaces/local-goal-board/examples/sample-goal \
   --once \
   --json
 ```

package/{plugins/goalbuddy/skills/goalbuddy/extend → goalbuddy/surfaces}/local-goal-board/examples/sample-goal/state.yaml

@@ -1,8 +1,8 @@
 version: 2
 
 goal:
-  title: "Local Kanban Board Extension"
-  slug: "local-kanban-board-extension"
+  title: "Local Goal Board Surface"
+  slug: "local-goal-board-surface"
   kind: specific
   tranche: "Demonstrate local GoalBuddy board rendering."
   status: active
@@ -30,7 +30,7 @@ tasks:
     type: worker
     assignee: Worker
     status: blocked
-    objective: "Catalog and document the local board extension."
+    objective: "Catalog and document the local board surface."
     receipt:
       result: blocked
       summary: "T003 is blocked during the progressive board motion demo."
@@ -78,7 +78,7 @@ tasks:
     type: scout
     assignee: Scout
     status: done
-    objective: "List the extension launch paths."
+    objective: "List the board launch paths."
     receipt:
       result: done
       summary: "T009 completed during the progressive board motion demo."
@@ -118,7 +118,7 @@ tasks:
     type: worker
     assignee: Worker
     status: done
-    objective: "Prepare final extension packaging check."
+    objective: "Prepare final board packaging check."
     receipt:
       result: done
       summary: "T014 completed during the progressive board motion demo."

package/{plugins/goalbuddy/skills/goalbuddy/extend → goalbuddy/surfaces}/local-goal-board/examples/subgoal-parent/state.yaml

@@ -31,10 +31,10 @@ tasks:
     status: active
     objective: "Build the sub-goal board view."
     allowed_files:
-      - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
-      - goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+      - goalbuddy/surfaces/local-goal-board/scripts/lib/goal-board.mjs
+      - goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
     verify:
-      - node --test goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+      - node --test goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
     stop_if:
       - "Need files outside allowed_files."
     subgoal:

package/goalbuddy/{extend → surfaces}/local-goal-board/examples/subgoal-parent/subgoals/T004-board-view/state.yaml

@@ -24,16 +24,16 @@ tasks:
       result: done
       summary: "Child board payload needs normal columns and task details."
       evidence:
-        - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
+        - goalbuddy/surfaces/local-goal-board/scripts/lib/goal-board.mjs
   - id: T002
     type: worker
     assignee: Worker
     status: active
     objective: "Render the read-only embedded child board."
     allowed_files:
-      - goalbuddy/extend/local-goal-board/scripts/lib/goal-board.mjs
+      - goalbuddy/surfaces/local-goal-board/scripts/lib/goal-board.mjs
     verify:
-      - node --test goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs
+      - node --test goalbuddy/surfaces/local-goal-board/test/local-goal-board.test.mjs
     stop_if:
       - "Need files outside allowed_files."
     receipt: null

package/goalbuddy/{extend → surfaces}/local-goal-board/scripts/lib/goal-board.mjs

@@ -6,8 +6,8 @@ import { fileURLToPath } from "node:url";
 const VALID_STATUSES = new Set(["queued", "active", "blocked", "done"]);
 const COLUMN_ORDER = ["todo", "in-progress", "blocked", "completed"];
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const extensionRoot = resolve(__dirname, "../..");
-const logoAssetPath = join(extensionRoot, "assets", "goalbuddy-mark.png");
+const surfaceRoot = resolve(__dirname, "../..");
+const logoAssetPath = join(surfaceRoot, "assets", "goalbuddy-mark.png");
 
 export class GoalBoardError extends Error {
   constructor(message) {

package/goalbuddy/{extend → surfaces}/local-goal-board/scripts/local-goal-board.mjs

@@ -527,9 +527,9 @@ function serveStatic(appDir, pathname, response) {
     return;
   }
 
-  const extension = cleanPath.match(/\.[^.]+$/)?.[0] || "";
+  const fileExtension = cleanPath.match(/\.[^.]+$/)?.[0] || "";
   response.writeHead(200, {
-    "Content-Type": textTypes[extension] || "application/octet-stream",
+    "Content-Type": textTypes[fileExtension] || "application/octet-stream",
     "Cache-Control": "no-store",
   });
   response.end(readFileSync(file));
@@ -580,8 +580,8 @@ function usage() {
   console.log(`GoalBuddy Local Goal Board
 
 Usage:
-  node extend/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<slug>
-  node extend/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<slug> --once --json
+  npx goalbuddy board docs/goals/<slug>
+  npx goalbuddy board docs/goals/<slug> --once --json
 
 Options:
   --goal <path>   Goal directory containing state.yaml.