goalbuddy 0.2.10

package/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for improving `goalbuddy`.
+
+## Local Setup
+
+Clone the repo and run the checks:
+
+```bash
+git clone https://github.com/tolibear/goalbuddy.git
+cd goalbuddy
+npm run check
+```
+
+Until the GitHub repository rename is complete, use the current local clone or the existing `tolibear/goal-maker` remote.
+
+## Local Install Test
+
+Use a temporary Codex home so local testing does not overwrite your real install:
+
+```bash
+tmp=$(mktemp -d)
+node internal/cli/goal-maker.mjs install --codex-home "$tmp"
+node internal/cli/goal-maker.mjs doctor --codex-home "$tmp"
+rm -rf "$tmp"
+```
+
+## Package Check
+
+Before opening a PR, verify the npm package contents:
+
+```bash
+npm pack --dry-run
+```
+
+The package should include `README.md`, `internal/assets/`, `package.json`, `internal/cli/`, the canonical `goalbuddy/` skill directory, the temporary `goal-maker/` compatibility skill directory, and `plugins/goalbuddy/`.
+
+## Contribution Guidelines
+
+- Keep the runtime dependency-free unless there is a strong reason.
+- Keep `goalbuddy/` installable as the canonical Codex skill directory.
+- Keep `goal-maker/` working as a temporary compatibility skill directory until the migration window ends.
+- Prefer small, reviewable changes.
+- Update README or templates when behavior changes.
+- Run `npm run check` before submitting changes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tolibear
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# GoalBuddy
+
+Turn open-ended Codex work into a living Scout/Judge/Worker board with receipts, verification, and optional extensions.
+
+```bash
+npx goalbuddy
+```
+
+Then invoke the 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.
+
+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
+```
+
+![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
+
+Long Codex goals drift. A broad 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:
+
+```text
+vague goal -> discovery -> task board -> one active task -> receipt -> board update -> 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.
+
+## Core Features
+
+- **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.
+
+## The 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.
+
+Scout, Judge, and Worker are installed by default:
+
+- **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.
+
+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.
+
+## Goal Folder
+
+For each goal, `$goalbuddy` prepares:
+
+```text
+docs/goals/<slug>/
+  goal.md
+  state.yaml
+  notes/
+```
+
+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.
+
+For a broad prompt like “Improve my project,” the first 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
+```
+
+## 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.
+
+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.
+
+Discover optional extensions from the GitHub-hosted catalog:
+
+```bash
+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
+```
+
+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` 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.
+
+Extensions are not board truth. They may publish, report, intake, or add role guidance, but `state.yaml` remains authoritative.
+
+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`.
+
+## Running A Goal
+
+After `$goalbuddy` creates or repairs the board, start `/goal` with the printed command:
+
+```text
+/goal Follow docs/goals/<slug>/goal.md.
+```
+
+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:
+
+```bash
+node ~/.codex/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
+```
+
+## Example
+
+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.
+
+## Repo Contents
+
+- `goalbuddy/SKILL.md`: the 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/`: temporary compatibility skill payload 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
+- `examples/`: completed sample runs
+
+## 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.
+
+Use this to structure autonomous Codex work. Keep relying on repo-specific `AGENTS.md`, tests, and CI for repo facts.
+
+## License
+
+MIT

package/examples/extend-catalog-workflow/goal.md

@@ -0,0 +1,53 @@
+# Extend Catalog Workflow
+
+## Objective
+
+Design and implement Goal Maker's extension catalog workflow so optional features can move through GitHub-hosted extension metadata without requiring frequent npm package releases.
+
+## Goal Kind
+
+`open_ended`
+
+## Current Tranche
+
+Decide the product language and architecture for optional extensions, implement the first catalog-backed `extend` CLI workflow, add a visible root `extend/` surface, clean the skill/package layout, and leave a reviewable completion audit.
+
+## Non-Negotiable Constraints
+
+- `state.yaml` remains the only board truth.
+- Extensions are optional support surfaces, not the control plane.
+- Use `extend` as the repo surface and `extensions` as the item name.
+- Avoid implying bidirectional sync with external services.
+- Keep npm as the stable core; catalog entries should be updateable from GitHub.
+- Keep package-only infrastructure out of the installable skill payload.
+- Do not require provider credentials for discovery or dry-run installation.
+
+## Stop Rule
+
+Stop when the extension/catalog UX is implemented, the repo layout reflects the skill/package boundary, verification passes, and the final audit maps the shipped changes to receipts and commits.
+
+## Canonical Board
+
+Machine truth lives at:
+
+`examples/extend-catalog-workflow/state.yaml`
+
+If this charter and `state.yaml` disagree, `state.yaml` wins for task status, active task, receipts, verification freshness, and completion truth.
+
+## Run Command
+
+```text
+/goal Follow examples/extend-catalog-workflow/goal.md
+```
+
+## PM Loop
+
+On every `/goal` continuation:
+
+1. Read this charter.
+2. Read `state.yaml`.
+3. Work only on the active board task.
+4. Assign Scout, Judge, Worker, or PM according to the task.
+5. Write a compact task receipt.
+6. Update the board.
+7. Select the next active task or finish with a Judge/PM audit receipt.

package/examples/extend-catalog-workflow/notes/T001-extension-model-map.md

@@ -0,0 +1,47 @@
+# T001: Extension Model Map
+
+Task: `T001`
+Kind: `scout`
+Status: `done`
+
+## Summary
+
+The scalable frame is `extend`: optional extension folders live at the repo root under `extend/`, and catalog metadata lives at `extend/catalog.json`. The npm CLI should read the GitHub-hosted catalog so extension discovery can change without publishing a new npm version.
+
+Board publishing is the first likely extension family, but the extension surface should also support unrelated add-ons such as role guidance, reports, intake tools, and external channel publishing.
+
+## Recommended Vocabulary
+
+- Repo surface: `extend/`
+- Items inside `extend/`: extensions
+- Catalog file: `extend/catalog.json`
+- Public action for external surfaces: publish
+- Avoid umbrella words: export, sync, capabilities
+
+## Architecture Notes
+
+Core should own:
+
+- skill installation;
+- agent installation;
+- board checker scripts;
+- extension catalog discovery;
+- checksum-verified extension installation;
+- extension doctor checks.
+
+Extensions should own:
+
+- provider-specific behavior;
+- provider docs;
+- auth requirements;
+- fixtures and tests;
+- optional role or reporting guidance.
+
+No extension may define a second meaning of `state.yaml`.
+
+## Candidate Tasks
+
+- Add a catalog-backed `goal-maker extend` command.
+- Add root `extend/` documentation.
+- Keep package-only CLI/tests out of the installable skill folder.
+- Add repo agent guidance so future improvements consider docs, skill instructions, CLI, tests, examples, and extensions together.

package/examples/extend-catalog-workflow/notes/T002-architecture-decision.md

@@ -0,0 +1,48 @@
+# T002: Architecture Decision
+
+Task: `T002`
+Kind: `judge`
+Status: `done`
+
+## Decision
+
+Use `extend` as the high-level optional surface and call each item an extension. Keep the default catalog GitHub-hosted at:
+
+```text
+https://raw.githubusercontent.com/tolibear/goal-maker/main/extend/catalog.json
+```
+
+The npm package should contain the stable core and CLI. The catalog can change on GitHub without requiring users to update npm for every optional integration.
+
+## CLI Shape
+
+Use one top-level extension command instead of separate browse/list/show verbs:
+
+```bash
+goal-maker extend
+goal-maker extend <extension-id>
+goal-maker extend install <extension-id>
+goal-maker extend doctor [extension-id]
+```
+
+This keeps the UX simple:
+
+- no argument means "show the catalog";
+- an id means "show this extension";
+- `install` copies checksum-verified files into the local Goal Maker install;
+- `doctor` verifies installed extension files and required environment.
+
+## Repo Shape
+
+Keep the root relatively clean:
+
+```text
+goal-maker/   # installable skill payload
+internal/     # package/dev infrastructure
+extend/       # optional extension folders
+examples/     # completed sample runs
+extend/catalog.json  # GitHub-hosted extension catalog
+AGENTS.md     # repo-specific agent guidance
+```
+
+`goal-maker/scripts/` stays inside the skill because installed skill docs call those scripts directly.

package/examples/extend-catalog-workflow/notes/T003-implementation-summary.md

@@ -0,0 +1,43 @@
+# T003: Catalog CLI Implementation
+
+Task: `T003`
+Kind: `worker`
+Status: `done`
+
+## Summary
+
+Implemented the first catalog-backed `goal-maker extend` workflow.
+
+Commit:
+
+- `105850e Add extension catalog workflow`
+
+## Shipped Behavior
+
+- `goal-maker extend` reads the GitHub-hosted catalog and reports available/install/configuration state.
+- `goal-maker extend <id>` shows extension details.
+- `goal-maker extend install <id>` installs checksum-verified extension files.
+- `goal-maker extend doctor [id]` validates installed extension files and required environment.
+- Root `catalog.json` provides an initially empty GitHub-hosted catalog.
+- README documents the extension discovery/install flow.
+
+## Files Touched
+
+At this point in the run, the CLI still lived under `goal-maker/bin/`. A later cleanup task moved it to `internal/cli/`.
+
+- `README.md`
+- `catalog.json`
+- `goal-maker/bin/goal-maker.mjs`
+- `goal-maker/test/goal-maker-cli.test.mjs`
+- `package.json`
+
+## Verification
+
+Commands passed:
+
+```bash
+npm run check
+git diff --check
+node goal-maker/bin/goal-maker.mjs extend --catalog-url catalog.json --json
+npm publish --dry-run --json
+```

package/examples/extend-catalog-workflow/notes/T004-root-extend-folder.md

@@ -0,0 +1,24 @@
+# T004: Root Extend Folder
+
+Task: `T004`
+Kind: `pm`
+Status: `done`
+
+## Summary
+
+Added a visible root `extend/` folder with documentation so GitHub shows the extension surface even before real extensions exist.
+
+Commit:
+
+- `17c65c9 Document extension folder`
+
+## Files Touched
+
+- `README.md`
+- `extend/README.md`
+
+## Receipt Notes
+
+The folder intentionally contains only documentation for now. Git cannot track an empty directory, and the product decision was to avoid bundling sample extensions until a real extension is ready.
+
+The README now says extensions live under `extend/` and move through the GitHub-hosted `extend/catalog.json`.

package/examples/extend-catalog-workflow/notes/T005-layout-cleanup.md

@@ -0,0 +1,46 @@
+# T005: Skill Package Layout Cleanup
+
+Task: `T005`
+Kind: `worker`
+Status: `done`
+
+## Summary
+
+Separated package-only infrastructure from the installable skill payload while keeping the repo root clean.
+
+Commit:
+
+- `6faa5de Clean skill package layout`
+
+## Files Touched
+
+- `AGENTS.md`
+- `CONTRIBUTING.md`
+- `README.md`
+- `extend/README.md`
+- `goal-maker/SKILL.md`
+- `goal-maker/bin/goal-maker.mjs` -> `internal/cli/goal-maker.mjs`
+- `goal-maker/test/*.test.mjs` -> `internal/test/*.test.mjs`
+- `package.json`
+
+## Result
+
+The installable skill payload is now focused:
+
+```text
+goal-maker/
+  SKILL.md
+  agents/
+  scripts/
+  templates/
+```
+
+Package/dev infrastructure is grouped under:
+
+```text
+internal/
+  cli/
+  test/
+```
+
+Root `AGENTS.md` now tells future agents to consider README, SKILL.md, templates, checker behavior, CLI UX, examples, package contents, and extension catalog design when improving this repo.

package/examples/extend-catalog-workflow/notes/T006-catalog-location.md

@@ -0,0 +1,50 @@
+# T006: Catalog Location
+
+Task: `T006`
+Kind: `worker`
+Status: `done`
+
+## Summary
+
+Moved the hosted catalog from the repo root to `extend/catalog.json`.
+
+Commit:
+
+- This example/catalog-location commit.
+
+## Why
+
+The repo root should stay relatively clean, and `catalog.json` is part of the extension surface. Keeping it under `extend/` makes the shape easier to understand:
+
+```text
+extend/
+  README.md
+  catalog.json
+  <extension-id>/
+```
+
+The npm CLI still reads the catalog from GitHub raw, now at:
+
+```text
+https://raw.githubusercontent.com/tolibear/goal-maker/main/extend/catalog.json
+```
+
+## Files Touched
+
+- `catalog.json` -> `extend/catalog.json`
+- `internal/cli/goal-maker.mjs`
+- `README.md`
+- `AGENTS.md`
+- `extend/README.md`
+- `examples/extend-catalog-workflow/`
+
+## Verification
+
+Commands to verify this task:
+
+```bash
+npm run check
+git diff --check
+node internal/cli/goal-maker.mjs extend --catalog-url extend/catalog.json --json
+npm publish --dry-run --json
+```

package/examples/extend-catalog-workflow/notes/T999-completion-audit.md

@@ -0,0 +1,36 @@
+# T999: Completion Audit
+
+Task: `T999`
+Kind: `judge`
+Status: `done`
+
+## Decision
+
+Complete.
+
+## Audit
+
+| Requirement | Evidence | Status |
+|---|---|---|
+| Use `extend` as the high-level surface | `extend/README.md`, `README.md`, `AGENTS.md` | Complete |
+| Items inside `extend` are extensions | `extend/README.md`, `README.md`, catalog terminology | Complete |
+| Avoid frequent npm releases for catalog updates | `extend/catalog.json` and default raw GitHub catalog URL | Complete |
+| Keep extension discovery credential-free | `goal-maker extend` and `goal-maker extend <id>` inspect catalog metadata only | Complete |
+| Verify installed extensions safely | checksum validation and `.installed.json` manifest in CLI implementation | Complete |
+| Keep root reasonably clean | package/dev files grouped under `internal/` | Complete |
+| Keep skill payload clean | `goal-maker/` contains skill, agents, scripts, and templates only | Complete |
+| Teach future agents about improvement surfaces | root `AGENTS.md` and SKILL.md note | Complete |
+
+## Verification
+
+Commands passed during the implementation tranche:
+
+```bash
+npm run check
+git diff --check
+node internal/cli/goal-maker.mjs extend --catalog-url extend/catalog.json --json
+npm publish --dry-run --json
+node goal-maker/scripts/check-goal-state.mjs examples/extend-catalog-workflow/state.yaml
+```
+
+The final state is reviewable and maps to actual commits rather than simulated history.