goalbuddy 0.3.0 → 0.3.2

package/README.md

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

package/internal/cli/goal-maker.mjs

@@ -195,8 +195,8 @@ Usage:
 Targets: by default, install/update prepares both Codex (~/.codex) and Claude Code (~/.claude). Use --target codex or --target claude to limit the command.
 
 Default:
-  ${canonicalCliName}                  Installs and enables Codex, then installs Claude Code skill + agents + /goal-prep command.
-  ${canonicalCliName} --target claude  Installs ${canonicalProductName} for Claude Code (skill + agents + /goal-prep command).
+  ${canonicalCliName}                  Installs and enables Codex, then installs Claude Code skill + agents (skill surfaces /goal-prep).
+  ${canonicalCliName} --target claude  Installs ${canonicalProductName} for Claude Code (skill + agents; skill surfaces /goal-prep).
   ${canonicalCliName} --target codex   Installs and enables the native Codex plugin.
 
 Compatibility:
@@ -246,8 +246,8 @@ function claudeAgentsRoot() {
   return join(claudeHome(), "agents");
 }
 
-function claudeCommandsRoot() {
-  return join(claudeHome(), "commands");
+function legacyClaudeCommandPath() {
+  return join(claudeHome(), "commands", "goal-prep.md");
 }
 
 function installClaudeSkill({ quiet = false } = {}) {
@@ -311,30 +311,12 @@ function installClaudeAgents({ quiet = false } = {}) {
   return results;
 }
 
-function installClaudeCommands({ quiet = false } = {}) {
-  const source = join(claudePluginSource, "commands");
-  const target = claudeCommandsRoot();
-  const force = hasFlag("--force") || command === "update" || command === "install" || command === "default";
-  mkdirSync(target, { recursive: true });
-
-  const results = [];
-  if (!existsSync(source)) return results;
-  for (const file of readdirSync(source)) {
-    if (!file.endsWith(".md")) continue;
-    const dest = join(target, file);
-    if (existsSync(dest) && !force) {
-      if (!quiet) console.log(`skip existing ${dest} (use --force to overwrite)`);
-      results.push({ file, status: "skipped", path: dest });
-      continue;
-    }
-    const sourceHash = sha256(readFileSync(join(source, file)));
-    const previousHash = existsSync(dest) ? sha256(readFileSync(dest)) : "";
-    cpSync(join(source, file), dest);
-    const status = previousHash ? previousHash === sourceHash ? "unchanged" : "updated" : "installed";
-    if (!quiet) console.log(`installed ${dest}`);
-    results.push({ file, status, path: dest });
-  }
-  return results;
+function cleanupLegacyClaudeCommands({ quiet = false } = {}) {
+  const legacyPath = legacyClaudeCommandPath();
+  if (!existsSync(legacyPath)) return { removed: false, path: legacyPath };
+  rmSync(legacyPath, { force: true });
+  if (!quiet) console.log(`removed legacy ${legacyPath} (skill now surfaces /goal-prep)`);
+  return { removed: true, path: legacyPath };
 }
 
 async function buildClaudeInstallReport() {
@@ -349,7 +331,7 @@ async function buildClaudeInstallReport() {
     claude_home: claudeHome(),
     skill: installClaudeSkill({ quiet }),
     agents: installClaudeAgents({ quiet }),
-    commands: installClaudeCommands({ quiet }),
+    legacy_commands_cleanup: cleanupLegacyClaudeCommands({ quiet }),
     extensions: await extensionDiscoverySummary(),
     warnings: [],
   };
@@ -408,7 +390,6 @@ async function installEverywhere() {
 function doctorClaude() {
   const skillPath = join(claudeSkillRoot(), "SKILL.md");
   const agentsPath = claudeAgentsRoot();
-  const commandsPath = claudeCommandsRoot();
   const installed = existsSync(skillPath);
   const agents = existsSync(agentsPath)
     ? readdirSync(agentsPath).filter((file) => file.startsWith("goal-") && file.endsWith(".md"))
@@ -420,9 +401,8 @@ function doctorClaude() {
     if (!existsSync(installedAgent) || !existsSync(bundledAgent)) return false;
     return sha256(readFileSync(installedAgent)) !== sha256(readFileSync(bundledAgent));
   });
-  const commands = existsSync(commandsPath)
-    ? readdirSync(commandsPath).filter((file) => file === "goal-prep.md")
-    : [];
+  const legacyCommandPath = legacyClaudeCommandPath();
+  const legacyCommandPresent = existsSync(legacyCommandPath);
 
   console.log(JSON.stringify({
     target: "claude",
@@ -432,10 +412,11 @@ function doctorClaude() {
     installed_agents: agents,
     missing_agents: missingAgents,
     stale_agents: staleAgents,
-    installed_commands: commands,
+    legacy_command_present: legacyCommandPresent,
+    legacy_command_path: legacyCommandPath,
   }, null, 2));
 
-  const installOk = installed && missingAgents.length === 0 && staleAgents.length === 0;
+  const installOk = installed && missingAgents.length === 0 && staleAgents.length === 0 && !legacyCommandPresent;
   process.exit(installOk ? 0 : 1);
 }
 
@@ -449,7 +430,9 @@ function printClaudeInstallReport(report) {
   console.log("");
   console.log(`Skill: ${report.skill.status} at ${report.skill.path}`);
   console.log(`Agents: ${summarizeStatuses(report.agents)}`);
-  console.log(`Commands: ${summarizeStatuses(report.commands)}`);
+  if (report.legacy_commands_cleanup?.removed) {
+    console.log(`Removed legacy command: ${report.legacy_commands_cleanup.path}`);
+  }
   if (report.skill.preserved_extensions.length) {
     console.log(`Preserved extensions: ${report.skill.preserved_extensions.join(", ")}`);
   }
@@ -1257,6 +1240,7 @@ function installedPluginSkillRoot() {
   const versions = readdirSync(root, { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
     .map((entry) => entry.name)
+    .filter(isSupportedVersion)
     .sort(compareVersions)
     .reverse();
   for (const version of versions) {
@@ -1420,9 +1404,9 @@ function preserveInstalledExtensions(targets, { tempRoot = "" } = {}) {
     if (!target) continue;
     const source = join(target, "extend");
     if (!existsSync(source)) continue;
-    mkdirSync(tempPath, { recursive: true });
     for (const entry of readdirSync(source, { withFileTypes: true })) {
       if (bundledCoreExtensionIds.has(entry.name)) continue;
+      mkdirSync(tempPath, { recursive: true });
       const from = join(source, entry.name);
       const to = join(tempPath, entry.name);
       cpSync(from, to, { recursive: true, force: true });
@@ -1593,7 +1577,9 @@ function printEverywhereInstallReport(report) {
   } else if (report.claude) {
     console.log(`Claude Code: skill ${report.claude.skill.status} at ${report.claude.skill.path}`);
     console.log(`Claude Code agents: ${summarizeStatuses(report.claude.agents)}`);
-    console.log(`Claude Code commands: ${summarizeStatuses(report.claude.commands)}`);
+    if (report.claude.legacy_commands_cleanup?.removed) {
+      console.log(`Claude Code: removed legacy command at ${report.claude.legacy_commands_cleanup.path}`);
+    }
   }
 
   if (report.errors.length) {
@@ -1654,6 +1640,10 @@ function normalizeVersion(value) {
   return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
 }
 
+function isSupportedVersion(value) {
+  return /^v?\d+\.\d+\.\d+(?:[-+].*)?$/.test(String(value).trim());
+}
+
 function compareVersions(left, right) {
   const leftParts = normalizeVersion(left).split(".").map((part) => Number.parseInt(part, 10) || 0);
   const rightParts = normalizeVersion(right).split(".").map((part) => Number.parseInt(part, 10) || 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A /goal operating system for Codex and Claude Code: Scout/Judge/Worker boards with visual board surfaces, receipts, and verification.",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Turn broad Claude Code work into verified GoalBuddy boards with Scout, Judge, Worker, visual boards, and receipts.",
   "author": {
     "name": "tolibear",

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

@@ -1,6 +1,6 @@
 {
   "name": "goalbuddy",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Turn broad Codex and Claude Code work into verified GoalBuddy boards with Scout, Judge, Worker, visual boards, and receipts.",
   "author": {
     "name": "tolibear",

package/plugins/goalbuddy/commands/goal-prep.md

@@ -1,12 +0,0 @@
----
-description: Prepare a GoalBuddy board for a broad, long-running, or ambiguous goal. Compiles intake, writes goal.md/state.yaml, and prints the /goal command to run next. Does not start /goal automatically.
-allowed-tools: Read, Write, Edit, Bash, Grep, Glob
----
-
-Invoke the GoalBuddy `goal-prep` skill to prepare a board for the user's goal.
-
-Follow the canonical GoalBuddy invocation boundary: prepare intake, create or repair `docs/goals/<slug>/goal.md`, `state.yaml`, and `notes/`, optionally open a visual board, then print exactly `/goal Follow docs/goals/<slug>/goal.md.` and stop.
-
-Do not perform the requested work during this turn, even if it looks read-only or obviously useful. Put implementation, research, asset generation, and named-skill loading into Scout, Judge, or Worker tasks for the later `/goal` run.
-
-User goal: $ARGUMENTS