goalbuddy 0.2.21 → 0.3.0

package/CONTRIBUTING.md

@@ -14,12 +14,20 @@ npm run check
 
 ## Local Install Test
 
-Use a temporary Codex home so local testing does not overwrite your real install:
+GoalBuddy installs into Codex and Claude Code by default. Use temporary home directories so local testing does not overwrite your real install:
 
 ```bash
+# Both targets
+root=$(mktemp -d)
+node internal/cli/goal-maker.mjs --codex-home "$root/codex" --claude-home "$root/claude"
+node internal/cli/goal-maker.mjs doctor --target codex --codex-home "$root/codex"
+node internal/cli/goal-maker.mjs doctor --target claude --claude-home "$root/claude"
+rm -rf "$root"
+
+# One target
 tmp=$(mktemp -d)
-node internal/cli/goal-maker.mjs install --codex-home "$tmp"
-node internal/cli/goal-maker.mjs doctor --codex-home "$tmp"
+node internal/cli/goal-maker.mjs install --target claude --claude-home "$tmp"
+node internal/cli/goal-maker.mjs doctor --target claude --claude-home "$tmp"
 rm -rf "$tmp"
 ```
 
@@ -31,7 +39,7 @@ Before opening a PR, verify the npm package contents:
 npm pack --dry-run
 ```
 
-The package should include `README.md`, `internal/assets/`, `package.json`, `internal/cli/`, the canonical `goalbuddy/` skill directory, and `plugins/goalbuddy/`. The temporary `$goal-maker` compatibility skill is generated by the installer; do not add a second tracked skill payload.
+The package should include `README.md`, `internal/assets/`, `package.json`, `internal/cli/`, the canonical `goalbuddy/` skill directory, and `plugins/goalbuddy/` (with both `.codex-plugin/` and `.claude-plugin/` manifests). The temporary `$goal-maker` compatibility skill is generated by the installer; do not add a second tracked skill payload.
 
 ## Releases
 
@@ -40,7 +48,8 @@ GoalBuddy publishes from GitHub Actions with npm trusted publishing. See [RELEAS
 ## Contribution Guidelines
 
 - Keep the runtime dependency-free unless there is a strong reason.
-- Keep `goalbuddy/` installable as the canonical Codex skill directory.
+- Keep `goalbuddy/` installable as the canonical skill directory.
+- Keep installation working for both Codex and Claude Code.
 - Keep `$goal-maker` working as a generated compatibility alias until the migration window ends.
 - Prefer small, reviewable changes.
 - Update README or templates when behavior changes.

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 turns vague Codex goals into structured progress with Scout, Judge, Worker, receipts, and verification." width="100%">
+    <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%">
   </a>
 </p>
 
 <p align="center">
-  <strong>Turn open-ended Codex work into one reviewable goal board.</strong>
+  <strong>A /goal operating system for Codex and Claude Code: intake, live boards, agents, receipts, and verification.</strong>
 </p>
 
 <p align="center">
@@ -16,10 +16,12 @@
   <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.
+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.
 
 ```bash
-npx goalbuddy
+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
 ```
 
 Or install it globally:
@@ -28,19 +30,20 @@ Or install it globally:
 npm i -g goalbuddy
 ```
 
-Then restart Codex and invoke the installed skill:
+Then restart your AI coding agent and invoke the installed skill:
 
 ```text
-$goal-prep
+$goal-prep      # in Codex
+/goal-prep      # in Claude Code
 ```
 
-`$goal-prep` prepares the GoalBuddy board and prints the `/goal` command to run next. It does not start `/goal` automatically.
+`goal-prep` prepares the GoalBuddy board and prints the `/goal` command to run next. It does not start `/goal` automatically.
 
 ## Why GoalBuddy Exists
 
-Long Codex goals drift. A request like "improve this project" can turn into unbounded edits, stale verification, and premature completion claims.
+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 Codex a durable loop:
+GoalBuddy gives your AI coding agent a durable loop:
 
 ```text
 vague goal -> Scout -> Judge -> Worker -> receipt -> verify -> repeat
@@ -70,40 +73,32 @@ GoalBuddy uses four primitives:
 - **Task**: exactly one active Scout, Judge, Worker, or PM task.
 - **Receipt**: compact proof for every completed, blocked, or escalated task.
 
-The default agents are installed with the skill:
+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 And Check Readiness
-
-Install and enable the native Codex plugin:
+## Install Everywhere
 
 ```bash
 npx goalbuddy
 ```
 
-Restart Codex, then use `$goal-prep`. To add the optional extension bundle:
-
-```bash
-npx goalbuddy extend install --all
-```
+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, install the npm package globally and run `goalbuddy`:
+If you prefer a global executable:
 
 ```bash
 npm i -g goalbuddy
 goalbuddy
 ```
 
-Use the skill-only fallback if your Codex build does not support plugins:
-
-```bash
-npx goalbuddy install
-npx goalbuddy update
-```
-
 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
@@ -112,35 +107,40 @@ codex features enable goals
 npx goalbuddy doctor --goal-ready
 ```
 
-Repair only the bundled agent definitions:
+## Install One Target
+
+Use `--target` when you only want to install or update one agent environment:
 
 ```bash
-npx goalbuddy agents
+npx goalbuddy --target codex
+npx goalbuddy --target claude
 ```
 
-Check the local install:
+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:
 
-```bash
-npx goalbuddy doctor
+```text
+/goal-prep
 ```
 
-Check whether a newer GoalBuddy release is available:
+Check the local Claude Code install:
 
 ```bash
-npx goalbuddy check-update
+npx goalbuddy doctor --target claude
 ```
 
-Use a non-default Codex home:
+Use non-default homes:
 
 ```bash
-npx goalbuddy --codex-home /path/to/.codex
+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
 ```
 
-`plugin install`, `install`, `update`, and `doctor` also support `--json` when an agent or script needs structured output.
+`install` and `update` prepare both targets by default. `install`, `update`, `doctor`, and `agents` all accept `--target claude|codex`, and `--json` for structured output.
 
 ## Run A Goal
 
-After `$goal-prep` creates or repairs the board, start the run with the printed command:
+After `goal-prep` creates or repairs the board, start the run with the printed command:
 
 ```text
 /goal Follow docs/goals/<slug>/goal.md.
@@ -149,17 +149,12 @@ After `$goal-prep` creates or repairs the board, start the run with the printed
 Check board health at any time:
 
 ```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
 ```
 
-Launch the optional local board viewer for a goal:
-
-```bash
-npx goalbuddy board docs/goals/<slug>
-```
-
-`goalbuddy board` installs the `local-goal-board` extension from the catalog if needed, writes `.goalbuddy-board/` into the goal directory, and serves a local live-updating board.
-
 For a broad prompt like "Improve my project," the first active task should usually be Scout, not Worker:
 
 ```yaml
@@ -189,16 +184,24 @@ tasks:
     receipt: null
 ```
 
+## Visual 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.
+
+<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. 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.
+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
-npx goalbuddy extend install --all --dry-run
-npx goalbuddy extend install --all
 ```
 
 `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.
@@ -207,7 +210,7 @@ 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 GoalBuddy-branded board that updates live from `state.yaml` and `notes/`.
+- `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.
@@ -236,20 +239,30 @@ Release automation for future npm publishes is documented in [RELEASE.md](RELEAS
 
 ## Repo Map
 
-- `goalbuddy/SKILL.md`: canonical Codex skill
-- `goalbuddy/agents/`: Scout, Judge, and Worker definitions
+- `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
-- `plugins/goalbuddy/`: repo-local Codex plugin package scaffold
+- `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
 
 ## Status
 
-`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.
+`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.
+
+Use GoalBuddy to structure autonomous coding-agent work. Keep relying on repo-specific `AGENTS.md`/`CLAUDE.md`, tests, and CI for repo facts.
+
+## Star History
 
-Use GoalBuddy to structure autonomous Codex work. Keep relying on repo-specific `AGENTS.md`, tests, and CI for repo facts.
+<a href="https://www.star-history.com/?repos=tolibear%2Fgoalbuddy&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=tolibear/goalbuddy&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=tolibear/goalbuddy&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=tolibear/goalbuddy&type=date&legend=top-left" />
+ </picture>
+</a>
 
 ## License
 

package/goalbuddy/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: goal-prep
-description: Goal Prep for GoalBuddy. Use for broad, long-running, stalled, vague, detailed, planned, or unhealthy Codex work that needs a structured /goal intake, autonomous task discovery, role-tagged Scout/Judge/Worker delegation, one active task, durable receipts, and a PM-owned rolling board that maximizes the chance of a successful goal run.
+description: Goal Prep for GoalBuddy. Use for broad, long-running, stalled, vague, detailed, planned, or unhealthy Codex or Claude Code work that needs a structured /goal intake, autonomous task discovery, role-tagged Scout/Judge/Worker delegation, one active task, durable receipts, and a PM-owned rolling board that maximizes the chance of a successful goal run.
 ---
 
 # Goal Prep
 
-`$goal-prep` prepares a GoalBuddy board. It does not start `/goal` automatically, but the board and starter `/goal` command must be shaped so the next run continues into safe execution by default.
+`$goal-prep` (Codex) or `/goal-prep` (Claude Code) prepares a GoalBuddy board. It does not start `/goal` automatically, but the board and starter `/goal` command must be shaped so the next run continues into safe execution by default.
 
-GoalBuddy is for autonomous, long-running Codex work where the PM thread may need to discover the work, define tasks, sequence them, delegate them, execute them, verify them, and keep going without the human decomposing every step.
+GoalBuddy is for autonomous, long-running Codex or Claude Code work where the PM thread may need to discover the work, define tasks, sequence them, delegate them, execute them, verify them, and keep going without the human decomposing every step.
 
 The loop is:
 
@@ -24,15 +24,16 @@ 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.
 
@@ -72,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 (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.
+
+If the user chooses the local live board, create the goal directory, `notes/`, and an initial minimal `state.yaml` as soon as the slug is known, then run `npx goalbuddy board docs/goals/<slug>` and open the printed local URL in the AI coding agent's in-app browser (the Codex in-app Browser, the Claude Code preview, or the user's regular browser). In short: start the local board before filling the task list so the board pops up right away and cards populate live as `state.yaml` changes. Keep the printed URL in the final prep response as a fallback, but do not make the URL the primary experience.
+
+If the user chooses 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.
@@ -117,14 +134,15 @@ 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. Goal handling: reuse an existing goal, create a fresh goal, 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.
 
-For "make GoalBuddy better", a good first question is which improvement target matters most: intake clarity, board/execution reliability, completion proof/eval coverage, or user experience during long-running goals. A good second question asks what proof would convince the user it improved. A good third question asks whether to reuse an existing board, create a fresh board, or inspect first.
+For "make GoalBuddy better", a good first question is which improvement target matters most: intake clarity, board/execution reliability, completion proof/eval coverage, or user experience during long-running goals. A good second question asks what proof would convince the user it improved. A good third question asks whether to reuse an existing goal, create a fresh goal, or inspect first.
 
 ## Direct `/goal` Entry
 
@@ -155,9 +173,10 @@ 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;
 - 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.
 
@@ -221,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.
 
@@ -472,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/goalbuddy/agents/README.md

@@ -1,17 +1,22 @@
 # GoalBuddy Agents
 
-This directory contains both skill metadata and bundled agent definitions.
+This directory contains skill metadata and bundled agent definitions for Codex and Claude Code.
+
+## Files
 
 - `openai.yaml` stays with the skill as metadata.
-- `goal_*.toml` files can be copied into `.codex/agents/` for project-scoped agents or `~/.codex/agents/` for personal agents.
+- `goal_scout.toml`, `goal_judge.toml`, `goal_worker.toml` — Codex agent configs. Copy into `.codex/agents/` for project-scoped agents or `~/.codex/agents/` for personal agents.
+- Claude Code agent markdown lives in `plugins/goalbuddy/agents/` (installed to `~/.claude/agents/` by `npx goalbuddy --target claude`).
+
+## Agent Matrix
 
-| Agent | File | Reasoning effort | Sandbox |
-|---|---|---:|---|
-| Scout | `goal_scout.toml` | medium | read-only |
-| Worker | `goal_worker.toml` | low | workspace-write |
-| Judge | `goal_judge.toml` | high | read-only |
+| Agent | Codex file | Claude Code file | Reasoning effort | Write scope |
+|---|---|---|---:|---|
+| Scout | `goal_scout.toml` | `goal-scout.md` | medium | read-only |
+| Worker | `goal_worker.toml` | `goal-worker.md` | low | workspace-write |
+| Judge | `goal_judge.toml` | `goal-judge.md` | high | read-only |
 
-Recommended config:
+## Recommended Codex Config
 
 ```toml
 [agents]
@@ -20,4 +25,6 @@ max_depth = 1
 job_max_runtime_seconds = 1800
 ```
 
+## Authority Boundary
+
 Only the main `/goal` PM loop may select the active task, mark tasks done, update board truth, or mark the goal complete.

package/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.

package/goalbuddy/extend/github-projects/examples/goal-board-sync/state.yaml

@@ -0,0 +1,63 @@
+version: 2
+
+goal:
+  title: "Goal board sync MVP"
+  slug: "goal-board-sync-mvp"
+  kind: specific
+  tranche: "Mirror a GoalBuddy board into an external Kanban surface."
+  status: active
+
+rules:
+  pm_owns_state: true
+  one_active_task: true
+  max_write_workers: 1
+  no_implementation_without_worker_or_pm_task: true
+  no_completion_without_judge_or_pm_audit: true
+
+active_task: T002
+
+tasks:
+  - id: T001
+    type: scout
+    assignee: Scout
+    status: done
+    priority: P3
+    objective: "Map external board API requirements."
+    inputs:
+      - "Board API docs"
+    constraints:
+      - "Read-only."
+    expected_output:
+      - "Required scopes"
+      - "Field mapping"
+    receipt:
+      result: done
+      summary: "The board sync can read GoalBuddy state.yaml and mirror tasks into an external board."
+  - id: T002
+    type: worker
+    assignee: Worker
+    status: active
+    priority: P1
+    objective: "Implement one-way external board sync."
+    parent: T001
+    depends_on:
+      - T001
+    allowed_files:
+      - "extend/github-projects/scripts/**"
+      - "README.md"
+    verify:
+      - "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"
+    stop_if:
+      - "Board API credentials are unavailable."
+    receipt: null
+  - id: T003
+    type: judge
+    assignee: Judge
+    status: queued
+    priority: P2
+    objective: "Audit whether the board sync MVP is ready to document."
+    parent: T002
+    depends_on:
+      - T002
+    receipt: null