goalbuddy 0.2.20 → 0.2.22

package/internal/cli/goal-maker.mjs

@@ -33,11 +33,15 @@ const requiredAgentFiles = [
   "goal_scout.toml",
   "goal_worker.toml",
 ];
+const bundledCoreExtensionIds = new Set(["github-projects", "local-goal-board"]);
 const optionsWithValues = new Set([
   "--catalog",
   "--catalog-url",
   "--codex-home",
+  "--goal",
+  "--host",
   "--kind",
+  "--port",
   "--source",
 ]);
 
@@ -70,12 +74,19 @@ async function main() {
     case "doctor":
       doctor();
       break;
+    case "check-update":
+    case "update-check":
+      checkUpdate();
+      break;
     case "plugin":
       plugin();
       break;
     case "extend":
       await extend();
       break;
+    case "board":
+      await board();
+      break;
     case "help":
     case "--help":
     case "-h":
@@ -144,11 +155,13 @@ Usage:
   ${canonicalCliName} update [--codex-home <path>] [--json]
   ${canonicalCliName} agents [--codex-home <path>] [--force]
   ${canonicalCliName} doctor [--codex-home <path>] [--goal-ready]
+  ${canonicalCliName} check-update [--json]
   ${canonicalCliName} extend [--catalog-url <url-or-path>] [--kind <kind>] [--json]
   ${canonicalCliName} extend <id> [--catalog-url <url-or-path>] [--json]
   ${canonicalCliName} extend install <id> [--catalog-url <url-or-path>] [--dry-run] [--force] [--json]
   ${canonicalCliName} extend install --all [--catalog-url <url-or-path>] [--dry-run] [--force] [--json]
   ${canonicalCliName} extend doctor [<id>] [--codex-home <path>] [--json]
+  ${canonicalCliName} board <docs/goals/slug> [--catalog-url <url-or-path>] [--host <host>] [--port <port>] [--once] [--json]
 
 Default:
   ${canonicalCliName}  Installs and enables the native Codex plugin.
@@ -335,6 +348,46 @@ function doctor() {
   process.exit(installOk && goalReadyOk ? 0 : 1);
 }
 
+function checkUpdate() {
+  const report = updateReport();
+
+  if (hasFlag("--json")) {
+    printJson(report);
+    return;
+  }
+
+  if (report.check_status !== "ok") {
+    console.log(`GoalBuddy update check unavailable: ${report.error}`);
+  } else if (report.update_available) {
+    console.log(`GoalBuddy ${report.latest_version} is available; installed version is ${report.current_version}.`);
+    console.log(`Update with: ${report.update_command}`);
+  } else {
+    console.log(`GoalBuddy is up to date (${report.current_version}).`);
+  }
+}
+
+function updateReport() {
+  const report = {
+    package: packageInfo.name,
+    current_version: normalizeVersion(packageInfo.version),
+    latest_version: null,
+    update_available: false,
+    check_status: "unknown",
+    update_command: `npx ${canonicalCliName}`,
+  };
+
+  try {
+    report.latest_version = latestPublishedVersion();
+    report.update_available = compareVersions(report.current_version, report.latest_version) < 0;
+    report.check_status = "ok";
+  } catch (error) {
+    report.check_status = "unavailable";
+    report.error = error.message;
+  }
+
+  return report;
+}
+
 function plugin() {
   const subcommand = positional(1) || "";
   switch (subcommand) {
@@ -407,9 +460,9 @@ function installPlugin() {
   console.log("Restart Codex, then use:");
   console.log(`  $${canonicalSkillName}`);
   console.log("");
-  console.log("Optional extensions:");
-  console.log(`  npx ${canonicalCliName} extend`);
-  console.log(`  npx ${canonicalCliName} extend install --all`);
+  console.log("Bundled visual boards:");
+  console.log(`  npx ${canonicalCliName} board docs/goals/<slug>`);
+  console.log(`  npx ${canonicalCliName} extend github-projects`);
 }
 
 function pluginCacheRoot(version) {
@@ -475,9 +528,12 @@ function codexGoalRuntimeStatus() {
 }
 
 function runCodex(args) {
-  const result = spawnSync("codex", args, {
+  const env = { ...process.env, CODEX_HOME: codexHome() };
+  const command = codexSpawnCommand(args, env);
+  const result = spawnSync(command.file, command.args, {
     encoding: "utf8",
-    env: { ...process.env, CODEX_HOME: codexHome() },
+    env,
+    shell: command.shell || false,
   });
   return {
     ok: result.status === 0,
@@ -487,6 +543,38 @@ function runCodex(args) {
   };
 }
 
+function codexSpawnCommand(args, env) {
+  if (process.platform !== "win32") return { file: "codex", args };
+
+  const command = resolveWindowsCommand("codex", env);
+  if (!command) return { file: "codex", args };
+  if (/\.(?:cmd|bat)$/i.test(command)) {
+    const commandLine = [quoteWindowsCommandArg(command), ...args.map(quoteWindowsCommandArg)].join(" ");
+    return {
+      file: commandLine,
+      args: [],
+      shell: true,
+    };
+  }
+  return { file: command, args };
+}
+
+function resolveWindowsCommand(name, env) {
+  const systemWhere = env.SystemRoot ? join(env.SystemRoot, "System32", "where.exe") : "";
+  const whereCommand = systemWhere && existsSync(systemWhere) ? systemWhere : "where.exe";
+  const where = spawnSync(whereCommand, [name], { encoding: "utf8", env });
+  if (where.status !== 0) return "";
+  const candidates = where.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return candidates.find((candidate) => /\.(?:exe|cmd|bat)$/i.test(candidate)) || "";
+}
+
+function quoteWindowsCommandArg(value) {
+  return `"${String(value).replace(/(["^&|<>()%])/g, "^$1")}"`;
+}
+
 function parseGoalFeature(output) {
   const line = output.split(/\r?\n/).find((candidate) => candidate.trim().startsWith("goals"));
   if (!line) return { enabled: false, stage: "" };
@@ -528,6 +616,56 @@ async function extend() {
   }
 }
 
+async function board() {
+  const goal = optionValue("--goal") || positional(1);
+  if (!goal) {
+    console.error(`Missing goal directory. Usage: ${canonicalCliName} board docs/goals/<slug>`);
+    process.exit(2);
+  }
+
+  const script = await ensureLocalBoardExtension();
+  const scriptArgs = [script, "--goal", goal];
+  for (const option of ["--host", "--port"]) {
+    const value = optionValue(option);
+    if (value) scriptArgs.push(option, value);
+  }
+  if (hasFlag("--once")) scriptArgs.push("--once");
+  if (hasFlag("--json")) scriptArgs.push("--json");
+
+  const capture = hasFlag("--once") || hasFlag("--json");
+  const result = spawnSync(process.execPath, scriptArgs, {
+    cwd: packageRoot,
+    encoding: "utf8",
+    env: process.env,
+    stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+  });
+
+  if (capture) {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  }
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+async function ensureLocalBoardExtension() {
+  const id = "local-goal-board";
+  const script = join(extensionTarget(id), "scripts", "local-goal-board.mjs");
+  if (existsSync(script)) return script;
+
+  const catalog = await loadCatalog();
+  const extension = catalog.extensions.find((candidate) => candidate.id === id);
+  if (!extension) {
+    throw new Error(`Extension ${id} is not available in ${catalog.url}.`);
+  }
+
+  await installCatalogExtension(catalog, extension);
+  if (!existsSync(script)) {
+    throw new Error(`Extension ${id} installed, but script is missing: ${script}`);
+  }
+  return script;
+}
+
 function extendUsage() {
   console.log(`${canonicalProductName} Extend
 
@@ -686,6 +824,11 @@ async function extendInstall() {
 async function extendInstallAll(catalog) {
   const results = [];
   for (const extension of catalog.extensions) {
+    if (existsSync(extensionTarget(extension.id)) && !hasFlag("--force")) {
+      validateCatalogExtension(extension);
+      results.push({ extension, target: extensionTarget(extension.id), plan: installPlan(catalog, extension, extensionTarget(extension.id)), skipped: true });
+      continue;
+    }
     results.push(await installCatalogExtension(catalog, extension));
   }
 
@@ -713,11 +856,13 @@ async function extendInstallAll(catalog) {
     printJson({
       installed: true,
       count: results.length,
-      extensions: results.map(({ extension, target }) => ({ id: extension.id, target })),
+      extensions: results.map(({ extension, target, skipped }) => ({ id: extension.id, target, skipped: Boolean(skipped) })),
     });
   } else {
-    console.log(`Installed ${results.length} extensions`);
-    for (const { extension, target } of results) console.log(`  ${extension.id} -> ${target}`);
+    const installedCount = results.filter((result) => !result.skipped).length;
+    const skippedCount = results.length - installedCount;
+    console.log(`Installed ${installedCount} extensions${skippedCount ? `, skipped ${skippedCount} already installed` : ""}`);
+    for (const { extension, target, skipped } of results) console.log(`  ${extension.id} -> ${target}${skipped ? " (already installed)" : ""}`);
   }
 }
 
@@ -965,6 +1110,7 @@ function preserveInstalledExtensions(targets) {
     if (!existsSync(source)) continue;
     mkdirSync(tempPath, { recursive: true });
     for (const entry of readdirSync(source, { withFileTypes: true })) {
+      if (bundledCoreExtensionIds.has(entry.name)) continue;
       const from = join(source, entry.name);
       const to = join(tempPath, entry.name);
       cpSync(from, to, { recursive: true, force: true });
@@ -978,9 +1124,11 @@ function preserveInstalledExtensions(targets) {
 
 function restoreInstalledExtensions(target, tempPath) {
   if (!tempPath) return;
-  rmSync(join(target, "extend"), { recursive: true, force: true });
-  mkdirSync(target, { recursive: true });
-  cpSync(tempPath, join(target, "extend"), { recursive: true });
+  const destinationRoot = join(target, "extend");
+  mkdirSync(destinationRoot, { recursive: true });
+  for (const entry of readdirSync(tempPath, { withFileTypes: true })) {
+    cpSync(join(tempPath, entry.name), join(destinationRoot, entry.name), { recursive: true, force: true });
+  }
 }
 
 function cleanupPreservedExtensions(paths) {
@@ -1129,9 +1277,39 @@ function assertSkillInstalledForExtensionInstall() {
   }
 }
 
+function latestPublishedVersion() {
+  if (process.env.GOALBUDDY_TEST_NPM_LATEST_VERSION) {
+    return normalizeVersion(process.env.GOALBUDDY_TEST_NPM_LATEST_VERSION);
+  }
+
+  const result = spawnSync("npm", ["view", packageInfo.name, "version"], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    timeout: 5000,
+    env: {
+      ...process.env,
+      npm_config_update_notifier: "false",
+    },
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const output = `${result.stderr || ""}${result.stdout || ""}`.trim();
+    throw new Error(output || `npm view exited with status ${result.status}`);
+  }
+
+  return normalizeVersion(result.stdout);
+}
+
+function normalizeVersion(value) {
+  const match = String(value).trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) throw new Error(`Unsupported version: ${value}`);
+  return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
+}
+
 function compareVersions(left, right) {
-  const leftParts = left.split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const rightParts = right.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const leftParts = normalizeVersion(left).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const rightParts = normalizeVersion(right).split(".").map((part) => Number.parseInt(part, 10) || 0);
   const length = Math.max(leftParts.length, rightParts.length);
   for (let index = 0; index < length; index += 1) {
     const diff = (leftParts[index] || 0) - (rightParts[index] || 0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "goalbuddy",
-  "version": "0.2.20",
-  "description": "Turn open-ended Codex goals into a GoalBuddy Scout/Judge/Worker board with receipts, verification, and optional extensions.",
+  "version": "0.2.22",
+  "description": "Turn open-ended Codex goals into GoalBuddy Scout/Judge/Worker boards with visual board surfaces, receipts, and verification.",
   "type": "module",
   "bin": {
     "goalbuddy": "internal/cli/goal-maker.mjs",
@@ -18,6 +18,7 @@
     "goalbuddy/SKILL.md",
     "goalbuddy/agents",
     "goalbuddy/scripts",
+    "goalbuddy/extend",
     "goalbuddy/templates"
   ],
   "scripts": {

package/plugins/goalbuddy/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "goalbuddy",
-  "version": "0.2.20",
-  "description": "Turn broad Codex work into verified GoalBuddy boards with Scout, Judge, Worker, receipts, and optional extensions.",
+  "version": "0.2.22",
+  "description": "Turn broad Codex work into verified GoalBuddy boards with Scout, Judge, Worker, visual boards, and receipts.",
   "author": {
     "name": "tolibear",
     "email": "support@tolibear.com",
@@ -24,7 +24,7 @@
   "interface": {
     "displayName": "GoalBuddy",
     "shortDescription": "Turn broad Codex work into verified Scout/Judge/Worker boards",
-    "longDescription": "GoalBuddy packages a structured Codex goal workflow for broad, long-running, or ambiguous engineering work. It creates durable goal charters, task boards, receipts, verification gates, extension handoffs, and compatibility guidance for teams moving from goal-maker.",
+    "longDescription": "GoalBuddy packages a structured Codex goal workflow for broad, long-running, or ambiguous engineering work. It creates durable goal charters, task boards, visual board surfaces, receipts, verification gates, extension handoffs, and compatibility guidance for teams moving from goal-maker.",
     "developerName": "tolibear",
     "category": "Coding",
     "capabilities": [

package/plugins/goalbuddy/README.md

@@ -15,6 +15,7 @@ From the repo root:
 ```bash
 npm run check
 npx goalbuddy doctor
+npx goalbuddy check-update
 ```
 
 ## Native Codex Install
@@ -25,11 +26,7 @@ Install and enable GoalBuddy:
 npx goalbuddy
 ```
 
-Restart Codex, then use `$goal-prep`. Optional extensions can be installed with:
-
-```bash
-npx goalbuddy extend install --all
-```
+Restart Codex, then use `$goal-prep`. The plugin bundles the local live board and GitHub Projects visual board backends so Goal Prep can offer a board immediately.
 
 Or install the npm package globally:
 

package/plugins/goalbuddy/skills/goalbuddy/SKILL.md

@@ -24,19 +24,37 @@ There are two different modes:
 
 This boundary is strict. `$goal-prep` is not a lightweight `/goal`; it is a board compiler.
 
-During a `$goal-prep` turn, do not perform the user's requested work, even if the work looks read-only, preparatory, or obviously useful. Do not refresh or load named skills, inspect implementation files, browse reference repos, research design inspiration, generate design plans, generate images/assets, run app-specific checks, start servers, or edit product files. Put those actions into Scout, Judge, Worker, or PM tasks for the later `/goal` run.
+During a `$goal-prep` turn, do not perform the user's requested work, even if the work looks read-only, preparatory, or obviously useful. Do not refresh or load named skills, inspect implementation files, browse reference repos, research design inspiration, generate design plans, generate images/assets, run app-specific checks, or edit product files. Put those actions into Scout, Judge, Worker, or PM tasks for the later `/goal` run.
 
 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`, and `docs/goals/<slug>/notes/`;
+- 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;
 - optionally run the GoalBuddy board checker against that `state.yaml`;
-- verify that the GoalBuddy agents are installed, if this can be done without touching implementation work;
+- 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.`;
 - ask whether to start `/goal`, refine the board, or stop.
 
 If the prompt names another skill or tool, such as "use the taste skill", "refresh the taste skill", "look at this repo", "use browser", or "generate assets", record that requirement in the charter and seed tasks. Do not load that skill, browse that repo, or generate those assets during `$goal-prep`.
 
+## Update Check
+
+At the start of a `$goal-prep` turn, check whether GoalBuddy itself is stale. Run the bundled checker from the installed skill directory when available:
+
+```bash
+node <skill-path>/scripts/check-update.mjs --json
+```
+
+If the checker reports `update_available: true`, tell the user once before continuing:
+
+```text
+GoalBuddy <latest_version> is available. After this turn, update with: npx goalbuddy
+```
+
+Do not block intake or board creation on update checking. If the checker is missing, cannot find npm, or network access fails, continue silently unless the user asked about updates.
+
 ## Intake Compiler
 
 Before creating, repairing, or running a board, privately translate the user's input into a Goal Intake. The input may be vague, specific, or detailed with an existing plan. Do not dump the intake to the user unless they ask for it.
@@ -55,6 +73,22 @@ Extract:
 - 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:
+
+```text
+Do you want to set up a visual board for this?
+```
+
+Recommended options:
+
+1. Local live board in Codex (Recommended) - starts immediately, requires no credentials, and lets the user watch tasks populate.
+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 Codex in-app 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 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.
+
 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.
 
 For vague or strategic goals, one answer is rarely enough. After each answer, reflect what it implies, name one likely blind spot, and ask the next material question. The goal is to help the user discover what they mean, not merely collect a form value.
@@ -100,10 +134,11 @@ 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. Intent target: what kind of improvement or outcome matters most?
-2. Success proof: what evidence would convince the user this worked?
-3. Scope and non-goals: what should remain untouched or explicitly out of scope?
-4. Board handling: reuse an existing board, create a fresh board, or inspect first?
+1. Visual board: ask "Do you want to set up a visual board for this?"
+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?
+5. Board handling: reuse an existing board, create a fresh board, or inspect first?
 
 Ask these one at a time. Skip a step only when the user's words already answer it clearly. After the user answers one step, do not assume the remaining steps; ask the next unresolved material question.
 
@@ -131,15 +166,17 @@ When invoked directly, run intake first. For vague, strategic, improvement-orien
 
 Do:
 
+- check for a newer GoalBuddy version once at the start and mention it without blocking;
 - clarify or infer the goal title and slug;
 - run the Intake Compiler;
 - ask diagnostic intake questions when clarity would materially improve the board;
 - 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 Codex in-app Browser before filling the task list;
 - seed a role-tagged task board that matches the input shape;
 - make the first active task safe;
-- verify Scout, Worker, and Judge agents are installed or explain what is missing;
+- verify Scout, Worker, and Judge agent availability or record an explicit truthful state;
 - print the exact command `/goal Follow docs/goals/<slug>/goal.md.`;
 - ask whether to start now, refine `goal.md`, or stop.
 
@@ -203,7 +240,7 @@ docs/goals/<slug>/
   notes/
 ```
 
-The goal root may contain only `goal.md`, `state.yaml`, and `notes/`.
+The goal root may contain only `goal.md`, `state.yaml`, `notes/`, and generated `.goalbuddy-board/` files when the local visual board is enabled.
 
 Most results live inline as task receipts in `state.yaml`. Only create `notes/<task-id>-<slug>.md` when Scout, Judge, or PM output is too large to fit on the task card.
 
@@ -409,6 +446,25 @@ Blocked tasks do not necessarily block the goal. The PM should keep doing safe l
 
 Avoid setting `goal.status: blocked` for missing input, credentials, production access, destructive-operation permission, or policy decisions. Block the specific task instead, record the missing requirement, and continue with every safe local workaround or adjacent slice.
 
+## Operator Escalation
+
+When Scout, Judge, Worker, or PM discovers a problem, improvement opportunity, product suggestion, follow-up repair, or tool limitation that should not be fixed inside the current active task, do not let it disappear in chat.
+
+The PM may create a board task to prepare a repo-native follow-up. If the user has already approved publishing and the repo/auth state supports it, the PM may create an issue or PR directly and record the link in the receipt. Otherwise, ask the operator one concise question before creating the external artifact:
+
+```markdown
+I found [problem or suggestion].
+
+Should I:
+1. Create an issue in this repo for it? (Recommended) - [why]
+2. Prepare a PR for the fix/suggestion - [when this is better]
+3. Keep it only in the GoalBuddy board for now - [tradeoff]
+```
+
+Use an issue for follow-up work, unclear scope, missing approval, or suggestions that need discussion. Use a PR when the fix is already implemented or safely implementable within the current approved scope. If neither is appropriate, propose a different path and record the decision in `state.yaml`.
+
+External issues and PRs are supporting artifacts, not board truth. `state.yaml` remains authoritative, and every issue/PR creation or decision must be reflected in a PM, Worker, or Judge receipt.
+
 ## Continuation Rule
 
 After a task completes, immediately write its receipt and select the next active task unless:
@@ -435,7 +491,18 @@ If the checker and your judgment disagree, choose the more conservative state.
 
 ## Agents
 
-Scout, Worker, and Judge are default-installed roles.
+Scout, Worker, and Judge templates are bundled with GoalBuddy. They may also be installed as user or project agent configs, but a board must not claim `installed` unless the preparer verified the matching agent files.
+
+Use these `state.yaml` values:
+
+| State | Meaning | Next action |
+|---|---|---|
+| `installed` | Matching Scout/Worker/Judge agent configs were found in the expected user or project agent location. | Continue. |
+| `bundled_not_installed` | The bundled `goal_*.toml` template exists with the skill, but no matching installed agent config was verified. | `/goal` can proceed through PM fallback. If dedicated agents are required before `/goal`, run `npx goalbuddy agents`. |
+| `missing` | Neither an installed config nor the bundled template was verified. | `/goal` can proceed through PM fallback. If dedicated agents are required before `/goal`, run `npx goalbuddy install`. |
+| `unknown` | Agent availability could not be checked. | `/goal` can proceed through PM fallback. To check before `/goal`, run `npx goalbuddy doctor`. |
+
+Non-`installed` states are warnings, not false failures, because the main `/goal` PM can perform Scout/Judge/Worker-shaped tasks directly when dedicated agents are unavailable.
 
 | Agent | Thinking level | Write access | Use for |
 |---|---:|---:|---|

package/plugins/goalbuddy/skills/goalbuddy/extend/github-projects/README.md

@@ -0,0 +1,105 @@
+# GitHub Projects
+
+Mirror a GoalBuddy `state.yaml` board into GitHub Projects without making GitHub the source of truth.
+
+This extension ports the GitHub Projects work from PR #1 into the catalog-based extension system. It keeps the package core dependency-free and optional, while giving teams a practical way to publish a GoalBuddy board into a familiar project surface.
+
+## Use When
+
+- A long-running GoalBuddy board needs stakeholder visibility in GitHub Projects.
+- A team wants one-way sync from `state.yaml` into ProjectV2 draft issues.
+- The PM needs a dry-run plan before using GitHub credentials.
+- Existing GoalBuddy receipts, verification commands, allowed files, owners, and dependencies should be visible in a board layout.
+
+## What It Creates
+
+The live sync ensures a GitHub Project has:
+
+- Draft issues keyed by `Task ID`, so reruns update existing cards instead of duplicating them.
+- Status mapping: `queued -> Todo`, `active -> In Progress`, `blocked -> Blocked`, `done -> Done`.
+- Single-select fields for `Status`, `Priority`, `Work Type`, and `Agent Lane`.
+- Text fields for `Task ID`, `Owner`, `Goal Role`, `Agent Responsible`, `Credential Gate`, `Parent ID`, `Depends On`, `Receipt Summary`, `Verify`, `Allowed Files`, and `Goal Updated`.
+- A `Goal Board` board-layout view for PM flow.
+
+The extension must use the bundled sync script for live writes. Do not use Computer Use, browser automation, or the GitHub web UI to create or repair the board view. Do not replace the script with `gh project` commands; `gh project` does not expose the complete ProjectV2 view creation path this extension needs. The script uses GitHub GraphQL for projects, fields, items, and draft issues, plus the GitHub REST Project views endpoint for the `Goal Board` view.
+
+The sync only creates or reuses `Goal Board`. It does not create a default Table view, an `Agent Workboard`, or extra role-specific views. GitHub may still show views that already existed on the Project.
+
+The extension does not promise custom board grouping or sort order. GitHub's public Project views REST API currently accepts `name`, `layout`, `filter`, and `visible_fields` when creating a view, and GraphQL exposes grouping/sort fields for reading but not a public mutation for saving them. Because that display state cannot be written reliably through the public API, the sync only creates supported fields, cards, and the single `Goal Board` view.
+
+## Inputs
+
+- `docs/goals/<slug>/state.yaml`
+- Optional `GITHUB_PROJECT_ID`
+- Optional `GITHUB_PROJECT_OWNER` and `GITHUB_PROJECT_NUMBER`
+- `GITHUB_TOKEN` or `GH_TOKEN` for live sync
+
+## Dry Run
+
+Dry-run mode does not call GitHub:
+
+```bash
+node extend/github-projects/scripts/sync-github-project.mjs \
+  --state docs/goals/<slug>/state.yaml \
+  --dry-run
+```
+
+For structured output:
+
+```bash
+node extend/github-projects/scripts/sync-github-project.mjs \
+  --state docs/goals/<slug>/state.yaml \
+  --dry-run \
+  --json
+```
+
+## Live Sync
+
+Always run the bundled script for live sync. It creates or reuses the `Goal Board` view as part of the same run that syncs fields and draft issues.
+
+Use a ProjectV2 node ID:
+
+```bash
+GITHUB_TOKEN=... node extend/github-projects/scripts/sync-github-project.mjs \
+  --state docs/goals/<slug>/state.yaml \
+  --project-id <project-node-id>
+```
+
+Or use an owner and project number:
+
+```bash
+GITHUB_TOKEN=... node extend/github-projects/scripts/sync-github-project.mjs \
+  --state docs/goals/<slug>/state.yaml \
+  --owner <user-or-org> \
+  --project-number <number>
+```
+
+Environment alternatives:
+
+- `GITHUB_PROJECT_ID`
+- `GITHUB_PROJECT_OWNER`
+- `GITHUB_PROJECT_NUMBER`
+- `GITHUB_TOKEN` or `GH_TOKEN`
+
+## Verification
+
+```bash
+node --test extend/github-projects/test/*.test.mjs
+node extend/github-projects/scripts/sync-github-project.mjs \
+  --state extend/github-projects/examples/goal-board-sync/state.yaml \
+  --dry-run
+node extend/github-projects/scripts/sync-github-project.mjs \
+  --state extend/github-projects/examples/goal-board-sync/state.yaml \
+  --dry-run \
+  --json
+```
+
+## Boundaries
+
+- `state.yaml` remains authoritative.
+- The sync is one-way from GoalBuddy to GitHub Projects.
+- Missing GitHub credentials block only live sync, not local dry-run validation.
+- Live sync creates or updates GitHub Project draft issues, fields, and the `Goal Board` view through the bundled script.
+- Agents must not fall back to Computer Use, browser automation, or the GitHub web UI for Project setup.
+- Agents must not claim ProjectV2 board views are UI-only; GitHub's REST Project views API supports creating board-layout views.
+- Native GitHub issue hierarchy and dependencies are represented as fields because ProjectV2 draft issues do not provide full issue relationship semantics.