goalbuddy 0.2.12 → 0.2.14

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "goalbuddy",
+  "interface": {
+    "displayName": "GoalBuddy"
+  },
+  "plugins": [
+    {
+      "name": "goalbuddy",
+      "source": {
+        "source": "local",
+        "path": "./plugins/goalbuddy"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
+    }
+  ]
+}

package/README.md

@@ -1,81 +1,139 @@
 # GoalBuddy
 
-Turn open-ended Codex work into a living Scout/Judge/Worker board with receipts, verification, and optional extensions.
+<p align="center">
+  <a href="https://goalbuddy.dev">
+    <img src="internal/assets/goalbuddy-readme-hero.png" alt="GoalBuddy turns vague Codex goals into structured progress with Scout, Judge, Worker, receipts, and verification." width="100%">
+  </a>
+</p>
+
+<p align="center">
+  <strong>Turn open-ended Codex work into one reviewable goal board.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/goalbuddy"><img alt="npm" src="https://img.shields.io/npm/v/goalbuddy?style=flat-square&color=684cff"></a>
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-071236?style=flat-square"></a>
+  <a href="https://goalbuddy.dev"><img alt="goalbuddy.dev" src="https://img.shields.io/badge/site-goalbuddy.dev-684cff?style=flat-square"></a>
+</p>
+
+GoalBuddy is a local Codex companion for work that is too broad to trust to a single prompt. It turns a vague request into a `goal.md` charter, a machine-readable `state.yaml` board, role-tagged Scout/Judge/Worker tasks, compact receipts, and verification before completion.
 
 ```bash
 npx goalbuddy
 ```
 
-Then invoke the skill inside Codex:
+Then invoke the installed skill inside Codex:
 
 ```text
 $goalbuddy
 ```
 
-`$goalbuddy` creates a local goal charter and task board, then prints the `/goal` command to run next. It does not start `/goal` automatically.
+`$goalbuddy` prepares the board and prints the `/goal` command to run next. It does not start `/goal` automatically.
 
-Native Codex `/goal` is still an under-development Codex feature. Before relying on the printed command, confirm your local Codex runtime is logged in and has goals enabled:
+For native Codex plugin install instead of the skill-only installer:
 
 ```bash
-codex login status
-codex features enable goals
-npx goalbuddy doctor --goal-ready
+npx goalbuddy plugin install
 ```
 
-![A simple hand-drawn diagram showing a vague goal becoming a GoalBuddy board with Scout, Judge, Worker, and a receipt.](internal/assets/goal-maker-flow.png)
-
-## Why It Exists
+## Why GoalBuddy Exists
 
-Long Codex goals drift. A broad request like “improve this project” can turn into unbounded edits, stale verification, and premature completion claims.
+Long Codex goals drift. A request like "improve this project" can turn into unbounded edits, stale verification, and premature completion claims.
 
-GoalBuddy gives Codex an operating loop for that kind of work:
+GoalBuddy gives Codex a durable loop:
 
 ```text
-vague goal -> discovery -> task board -> one active task -> receipt -> board update -> repeat
+vague goal -> Scout -> Judge -> Worker -> receipt -> verify -> repeat
 ```
 
-The main Codex thread is the PM. It owns the board, chooses the active task, delegates when useful, records receipts, and only completes after a Judge or PM audit.
+The main `/goal` thread acts as PM. It owns the board, keeps exactly one active task, delegates when useful, records receipts, and only completes after a Judge or PM audit proves the original outcome is done.
 
-## Core Features
+## What You Get Locally
+
+```text
+docs/goals/<slug>/
+  goal.md
+  state.yaml
+  notes/
+```
 
-- **Local board truth**: `goal.md` is the editable charter; `state.yaml` is the machine-readable board; `notes/` holds long receipts.
-- **Default role agents**: Scout discovers evidence, Judge resolves risk and completion claims, Worker performs one bounded implementation task.
-- **One active task**: keeps autonomous work sequenced and reviewable instead of turning a vague goal into a pile of parallel edits.
-- **Task receipts**: every completed, blocked, or escalated task records what changed, what was learned, and what verification ran.
-- **Board checker**: validates v2 goal folders and rejects old `gate`, `units`, `artifacts`, and `evidence.jsonl` layouts.
-- **Extensions**: optional add-ons are discovered from `extend/catalog.json` without requiring npm updates for every integration.
+- `goal.md` is the editable charter: objective, constraints, tranche, and stop rule.
+- `state.yaml` is the board truth: task status, active task, receipts, and verification.
+- `notes/` holds longer Scout, Judge, or PM findings when a task receipt would be too large.
 
-## The Model
+## The Operating Model
 
 GoalBuddy uses four primitives:
 
-- **Charter**: `goal.md` states the objective, constraints, current tranche, and stop rule.
-- **Board**: `state.yaml` is machine truth for tasks, status, receipts, and verification freshness.
-- **Task**: exactly one active task is worked at a time.
-- **Receipt**: every completed, blocked, or escalated task leaves compact proof of what happened.
+- **Charter**: states what this goal is trying to accomplish and what must stay true.
+- **Board**: tracks tasks, status, receipts, and verification freshness.
+- **Task**: exactly one active Scout, Judge, Worker, or PM task.
+- **Receipt**: compact proof for every completed, blocked, or escalated task.
 
-Scout, Judge, and Worker are installed by default:
+The default agents are installed with the skill:
 
-- **Scout** maps repo/source/spec evidence and candidate tasks.
-- **Judge** resolves ambiguity, scope, risk, and completion claims.
-- **Worker** performs one bounded implementation or recovery task.
+- **Scout** maps repo evidence, workflows, constraints, risks, and candidate next tasks.
+- **Judge** resolves ambiguity, scope, risk, task selection, and completion claims.
+- **Worker** performs one bounded implementation or recovery slice with explicit files and checks.
 
-The main `/goal` thread is the PM. Use medium thinking for specific bounded goals, high for open-ended/recovery/audit goals, and reserve xhigh for exceptional high-risk or multi-day final audits.
+## Install And Check Readiness
 
-## Goal Folder
+Install or refresh the Codex skill and bundled agents:
 
-For each goal, `$goalbuddy` prepares:
+```bash
+npx goalbuddy
+npx goalbuddy update
+```
+
+Install and enable the native Codex plugin:
+
+```bash
+npx goalbuddy plugin install
+```
+
+Native Codex `/goal` is still an under-development Codex feature. Before relying on the printed command, confirm your local Codex runtime is logged in and has goals enabled:
+
+```bash
+codex login status
+codex features enable goals
+npx goalbuddy doctor --goal-ready
+```
+
+Repair only the bundled agent definitions:
+
+```bash
+npx goalbuddy agents
+```
+
+Check the local install:
+
+```bash
+npx goalbuddy doctor
+```
+
+Use a non-default Codex home:
+
+```bash
+npx goalbuddy install --codex-home /path/to/.codex
+```
+
+`install`, `update`, and `doctor` also support `--json` when an agent or script needs structured output.
+
+## Run A Goal
+
+After `$goalbuddy` creates or repairs the board, start the run with the printed command:
 
 ```text
-docs/goals/<slug>/
-  goal.md
-  state.yaml
-  notes/
+/goal Follow docs/goals/<slug>/goal.md.
 ```
 
-Most task results live inline as receipts in `state.yaml`. Use `notes/<task-id>-<slug>.md` only when a Scout, Judge, or PM result is too large for the task card.
+Check board health at any time:
+
+```bash
+node ~/.codex/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
+```
 
-For a broad prompt like “Improve my project,” the first task should usually be Scout, not Worker:
+For a broad prompt like "Improve my project," the first active task should usually be Scout, not Worker:
 
 ```yaml
 tasks:
@@ -104,50 +162,9 @@ tasks:
     receipt: null
 ```
 
-## Commands
-
-Install or update the Codex skill and bundled agents:
-
-```bash
-npx goalbuddy
-npx goalbuddy update
-```
-
-`install` and `update` print a compact summary of the skill, agent files, preserved installed extensions, and extension catalog recommendations. Use `--json` when an agent or script needs structured output.
-
-### Compatibility Window
-
-GoalBuddy was previously published as `goal-maker`. During the migration window, `npx goal-maker` remains available as a compatibility alias and prints the new command:
-
-```bash
-npx goalbuddy
-```
-
-Machine-readable commands such as `npx goal-maker install --json` keep JSON output clean so existing automation can migrate safely.
-
-Release automation for future npm publishes is documented in [RELEASE.md](RELEASE.md).
-
-Repair only the agent definitions:
-
-```bash
-npx goalbuddy agents
-```
-
-Check what is installed:
-
-```bash
-npx goalbuddy doctor
-```
-
-Strictly check whether the native Codex `/goal` runtime is ready too:
-
-```bash
-npx goalbuddy doctor --goal-ready
-```
-
-`doctor` reports missing or stale bundled agents, Codex login status, and whether the `goals` feature is enabled. `update` refreshes the installed skill and bundled agents.
+## Extensions
 
-Discover optional extensions from the GitHub-hosted catalog:
+The npm package is the stable core. Optional extensions live under `extend/` and are discovered from the GitHub-hosted `extend/catalog.json`, so users do not need a new npm release for every integration.
 
 ```bash
 npx goalbuddy extend
@@ -156,51 +173,44 @@ npx goalbuddy extend install github-pr-workflow --dry-run
 npx goalbuddy extend install --all --dry-run
 ```
 
-Use a non-default Codex home:
-
-```bash
-npx goalbuddy install --codex-home /path/to/.codex
-```
-
-## Extensions
-
-The npm package is the stable core. Extensions live under `extend/` and move through the GitHub-hosted `extend/catalog.json`, so users do not need a new npm release for every optional integration.
+`goalbuddy extend` shows available extensions plus local install state, activation state, credential requirements, safe-by-default status, and missing environment variables.
 
-`goalbuddy extend` reads the catalog and shows available extensions plus operational state such as activation, install/configuration status, approval requirements, safe-by-default status, and missing environment variables. `goalbuddy extend <id>` shows what an extension reads, writes, requires, supports, and a local-use prompt. `goalbuddy extend install <id>` copies a pinned, checksum-verified extension into the local GoalBuddy install. `goalbuddy extend install --all` installs every cataloged extension.
+Current catalog examples include:
 
-Extensions are not board truth. They may publish, report, intake, or add role guidance, but `state.yaml` remains authoritative.
+- `github-pr-workflow`: prepares receipt-aligned commit and PR handoff text.
+- `github-projects`: mirrors GoalBuddy boards into GitHub Projects.
+- `ai-diff-risk-review`: summarizes risk in the current diff.
+- `ci-failure-triage`: maps failing CI back to likely causes and next tasks.
+- `docs-drift-audit`: checks whether docs still match implementation.
+- `codebase-onboarding-map`: creates a concise repo map from files and conventions.
+- `release-readiness`: checks whether a goal is ready to publish.
 
-The first cataloged extension, `github-pr-workflow`, prepares receipt-aligned commit boundaries and GitHub PR handoff text from goal receipts without requiring GitHub credentials or making GitHub authoritative. The catalog also includes GitHub Projects sync plus local-first review, recovery, planning, documentation, audit, and credential-gated handoff extensions such as `github-projects`, `ai-diff-risk-review`, `ci-failure-triage`, `docs-drift-audit`, `test-gap-planner`, `release-readiness`, `dependency-upgrade-planner`, `security-review-brief`, `codebase-onboarding-map`, `slack-standup-digest`, and `linear-ticket-handoff`.
+Extensions can publish, report, intake, or add role guidance. They are not board truth. `state.yaml` remains authoritative.
 
-## Running A Goal
+## Compatibility Window
 
-After `$goalbuddy` creates or repairs the board, start `/goal` with the printed command:
+GoalBuddy was previously published as `goal-maker`. During the migration window, `npx goal-maker` remains available as a compatibility alias and prints the new command:
 
-```text
-/goal Follow docs/goals/<slug>/goal.md.
+```bash
+npx goalbuddy
 ```
 
-The detailed run instructions live in that goal's `goal.md`, so the kickoff prompt can stay short while the board carries the full stop rule, intake, and PM loop.
-
-By default, GoalBuddy treats broad goals as requests for continuous work, not plan-only or one-slice exercises. Missing credentials or owner input are blockers for specific tasks, not reasons to stop the goal. A queued or active Worker task blocks `goal.status: done`; finish it, block it with a receipt, or replace it with a smaller safe Worker task before final audit. For continuous execution boards, a final audit must prove the full original outcome is complete, not merely that the latest slice passed.
-
-Check board health:
+Machine-readable commands such as `npx goal-maker install --json` keep JSON output clean so existing automation can migrate safely.
 
-```bash
-node ~/.codex/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
-```
+Release automation for future npm publishes is documented in [RELEASE.md](RELEASE.md).
 
-## Example
+## Examples
 
-See `examples/improve-goal-maker/` for a small completed reliability run, `examples/extend-catalog-workflow/` for a larger run that moves from product framing through implementation and repo cleanup, and `examples/github-pr-workflow-extension/pr-handoff.md` for an extension-generated PR handoff artifact.
+- `examples/improve-goal-maker/`: a small completed reliability run.
+- `examples/extend-catalog-workflow/`: a larger run from product framing through implementation and cleanup.
+- `examples/github-pr-workflow-extension/pr-handoff.md`: an extension-generated PR handoff artifact.
 
-## Repo Contents
+## Repo Map
 
-- `goalbuddy/SKILL.md`: the canonical Codex skill
+- `goalbuddy/SKILL.md`: canonical Codex skill
 - `goalbuddy/agents/`: Scout, Judge, and Worker definitions
 - `goalbuddy/templates/`: `goal.md`, `state.yaml`, and `note.md`
 - `goalbuddy/scripts/check-goal-state.mjs`: v2 board checker
-- `$goal-maker` compatibility: generated by the installer for existing users
 - `internal/cli/goal-maker.mjs`: npm installer CLI
 - `plugins/goalbuddy/`: repo-local Codex plugin package scaffold
 - `extend/` and `extend/catalog.json`: GitHub-hosted extension surface
@@ -208,9 +218,9 @@ See `examples/improve-goal-maker/` for a small completed reliability run, `examp
 
 ## Status
 
-`0.2.x` is the v2 board/receipt model. It intentionally rejects old v1 `gate`, `units`, `artifacts`, and `evidence.jsonl` goal folders instead of auto-migrating them.
+`0.2.x` is the v2 board and receipt model. It intentionally rejects old v1 `gate`, `units`, `artifacts`, and `evidence.jsonl` goal folders instead of auto-migrating them.
 
-Use this to structure autonomous Codex work. Keep relying on repo-specific `AGENTS.md`, tests, and CI for repo facts.
+Use GoalBuddy to structure autonomous Codex work. Keep relying on repo-specific `AGENTS.md`, tests, and CI for repo facts.
 
 ## License
 

package/internal/assets/goalbuddy-logo.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 190" role="img" aria-labelledby="title desc">
+  <title id="title">GoalBuddy logo</title>
+  <desc id="desc">GoalBuddy wordmark with lavender cloud mark.</desc>
+  <defs>
+    <radialGradient id="logoMarkGrad" cx="34%" cy="18%" r="92%">
+      <stop offset="0" stop-color="#f8f2ff"/>
+      <stop offset="0.46" stop-color="#b6a9ff"/>
+      <stop offset="1" stop-color="#5361ff"/>
+    </radialGradient>
+    <filter id="logoShadow" x="-20%" y="-25%" width="140%" height="160%">
+      <feDropShadow dx="0" dy="12" stdDeviation="10" flood-color="#4d48b8" flood-opacity=".24"/>
+    </filter>
+  </defs>
+  <g filter="url(#logoShadow)">
+    <path d="M72 141c-30 0-54-24-54-54 0-26 18-48 43-53C65 15 82 0 103 0c18 0 34 10 42 24 12-8 27-13 43-13 36 0 66 26 72 61 22 11 37 33 37 59 0 36-30 66-66 66H93c-8 0-15-2-21-6z" transform="translate(0 4) scale(.82)" fill="url(#logoMarkGrad)"/>
+    <ellipse cx="82" cy="81" rx="8" ry="12" fill="#061238"/>
+    <ellipse cx="132" cy="81" rx="8" ry="12" fill="#061238"/>
+    <path d="M99 101c8 9 18 9 27 0" fill="none" stroke="#061238" stroke-width="7" stroke-linecap="round"/>
+  </g>
+  <text x="230" y="116" fill="#071236" font-family="Geist, Avenir Next, Arial, sans-serif" font-size="82" font-weight="800" letter-spacing="-1">GoalBuddy</text>
+</svg>

package/internal/cli/goal-maker.mjs

@@ -36,6 +36,7 @@ const optionsWithValues = new Set([
   "--catalog-url",
   "--codex-home",
   "--kind",
+  "--source",
 ]);
 
 const args = process.argv.slice(2);
@@ -64,6 +65,9 @@ async function main() {
     case "doctor":
       doctor();
       break;
+    case "plugin":
+      plugin();
+      break;
     case "extend":
       await extend();
       break;
@@ -133,6 +137,7 @@ Usage:
   ${canonicalCliName} update [--codex-home <path>] [--json]
   ${canonicalCliName} agents [--codex-home <path>] [--force]
   ${canonicalCliName} doctor [--codex-home <path>] [--goal-ready]
+  ${canonicalCliName} plugin install [--source <marketplace-source>] [--codex-home <path>] [--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]
@@ -321,6 +326,123 @@ function doctor() {
   process.exit(installOk && goalReadyOk ? 0 : 1);
 }
 
+function plugin() {
+  const subcommand = positional(1) || "";
+  switch (subcommand) {
+    case "install":
+      installPlugin();
+      break;
+    case "help":
+    case "--help":
+    case "-h":
+      pluginUsage();
+      break;
+    default:
+      console.error(`Unknown plugin command: ${subcommand || "<missing>"}`);
+      pluginUsage();
+      process.exit(2);
+  }
+}
+
+function pluginUsage() {
+  console.log(`${canonicalProductName} Plugin
+
+Usage:
+  ${canonicalCliName} plugin install [--source <marketplace-source>] [--codex-home <path>] [--json]
+
+Default source:
+  tolibear/goalbuddy
+`);
+}
+
+function installPlugin() {
+  const source = optionValue("--source") || "tolibear/goalbuddy";
+  const pluginSource = join(packageRoot, "plugins", canonicalSkillName);
+  const pluginManifestPath = join(pluginSource, ".codex-plugin", "plugin.json");
+  if (!existsSync(pluginManifestPath)) {
+    throw new Error(`Plugin manifest not found: ${pluginManifestPath}`);
+  }
+
+  const pluginManifest = JSON.parse(readFileSync(pluginManifestPath, "utf8"));
+  const pluginCachePath = pluginCacheRoot(pluginManifest.version);
+  const marketplace = runCodex(["plugin", "marketplace", "add", source]);
+  if (!marketplace.ok) {
+    throw new Error(`Failed to add Codex plugin marketplace: ${firstLine(marketplace.stderr || marketplace.stdout)}`);
+  }
+
+  mkdirSync(dirname(pluginCachePath), { recursive: true });
+  rmSync(pluginCachePath, { recursive: true, force: true });
+  cpSync(pluginSource, pluginCachePath, { recursive: true });
+  const configPath = enablePluginConfig();
+
+  const report = {
+    installed: true,
+    plugin: `${canonicalSkillName}@${canonicalSkillName}`,
+    version: pluginManifest.version,
+    codex_home: codexHome(),
+    marketplace_source: source,
+    cache_path: pluginCachePath,
+    config_path: configPath,
+  };
+
+  if (hasFlag("--json")) {
+    printJson(report);
+    return;
+  }
+
+  console.log(`Installed ${canonicalProductName} Codex plugin ${pluginManifest.version}`);
+  console.log(`Marketplace: ${source}`);
+  console.log(`Cache: ${pluginCachePath}`);
+  console.log(`Config: ${configPath}`);
+  console.log("");
+  console.log("Restart Codex, then use:");
+  console.log(`  $${canonicalSkillName}`);
+}
+
+function pluginCacheRoot(version) {
+  return join(codexHome(), "plugins", "cache", canonicalSkillName, canonicalSkillName, version);
+}
+
+function enablePluginConfig() {
+  const configPath = join(codexHome(), "config.toml");
+  mkdirSync(dirname(configPath), { recursive: true });
+  const header = `[plugins."${canonicalSkillName}@${canonicalSkillName}"]`;
+  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  const updated = upsertTomlEnabled(existing, header);
+  writeFileSync(configPath, updated);
+  return configPath;
+}
+
+function upsertTomlEnabled(text, header) {
+  const normalized = text.endsWith("\n") || text.length === 0 ? text : `${text}\n`;
+  const lines = normalized.split("\n");
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start === -1) {
+    const prefix = normalized.trim() ? `${normalized}\n` : "";
+    return `${prefix}${header}\nenabled = true\n`;
+  }
+
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^\s*\[/.test(lines[index])) {
+      end = index;
+      break;
+    }
+  }
+
+  let sawEnabled = false;
+  for (let index = start + 1; index < end; index += 1) {
+    if (/^\s*enabled\s*=/.test(lines[index])) {
+      lines[index] = "enabled = true";
+      sawEnabled = true;
+      break;
+    }
+  }
+  if (!sawEnabled) lines.splice(start + 1, 0, "enabled = true");
+
+  return lines.join("\n").replace(/\n*$/, "\n");
+}
+
 function codexGoalRuntimeStatus() {
   const version = runCodex(["--version"]);
   const login = version.ok ? runCodex(["login", "status"]) : { ok: false, stdout: "", stderr: "codex CLI unavailable" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Turn open-ended Codex goals into a GoalBuddy Scout/Judge/Worker board with receipts, verification, and optional extensions.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
     "goal-maker": "internal/cli/goal-maker.mjs"
   },
   "files": [
+    ".agents/plugins/marketplace.json",
     "README.md",
     "CONTRIBUTING.md",
     "examples",

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

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.2.10",
+  "version": "0.2.14",
   "description": "Turn broad Codex work into verified GoalBuddy boards with Scout, Judge, Worker, receipts, and optional extensions.",
   "author": {
     "name": "tolibear",

package/plugins/goalbuddy/README.md

@@ -17,6 +17,16 @@ npm run check
 npx goalbuddy doctor
 ```
 
+## Native Codex Install
+
+Install and enable the plugin with the GoalBuddy CLI:
+
+```bash
+npx goalbuddy plugin install
+```
+
+This adds the `tolibear/goalbuddy` marketplace, caches the packaged plugin, and enables `goalbuddy@goalbuddy` for Codex. The npm CLI remains useful for `doctor`, project-local agent setup, and optional GoalBuddy extension management.
+
 For local CLI testing before npm publish:
 
 ```bash
@@ -26,4 +36,4 @@ node internal/cli/goal-maker.mjs doctor
 
 ## Release Notes
 
-The plugin is prepared for the `tolibear/goalbuddy` repo and `goalbuddy` npm package. Do not publish this plugin until the owner completes the GitHub and npm handoff steps in `docs/goals/goalbuddy-rebrand-plugin/state.yaml`.
+The plugin is prepared for the `tolibear/goalbuddy` repo and `goalbuddy` npm package. Keep `.codex-plugin/plugin.json` aligned with `package.json` before publishing a new package release.