goalbuddy 0.3.1 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -2,12 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
4
|
<a href="https://goalbuddy.dev">
|
|
5
|
-
<img src="internal/assets/goalbuddy-
|
|
5
|
+
<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%">
|
|
6
6
|
</a>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
10
|
-
<strong>A
|
|
10
|
+
<strong>A simple operating loop for long <code>/goal</code> runs.</strong>
|
|
11
11
|
</p>
|
|
12
12
|
|
|
13
13
|
<p align="center">
|
|
@@ -16,243 +16,96 @@
|
|
|
16
16
|
<a href="https://goalbuddy.dev"><img alt="goalbuddy.dev" src="https://img.shields.io/badge/site-goalbuddy.dev-684cff?style=flat-square"></a>
|
|
17
17
|
</p>
|
|
18
18
|
|
|
19
|
-
GoalBuddy
|
|
19
|
+
GoalBuddy helps Codex and Claude Code stay oriented during long coding tasks.
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
npx goalbuddy # installs for Codex and Claude Code
|
|
23
|
-
npx goalbuddy --target codex # installs for Codex only
|
|
24
|
-
npx goalbuddy --target claude # installs for Claude Code only
|
|
25
|
-
```
|
|
21
|
+
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.
|
|
26
22
|
|
|
27
|
-
|
|
23
|
+
## Start Here
|
|
24
|
+
|
|
25
|
+
Run one command:
|
|
28
26
|
|
|
29
27
|
```bash
|
|
30
|
-
|
|
28
|
+
npx goalbuddy
|
|
31
29
|
```
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
Restart Codex or Claude Code.
|
|
32
|
+
|
|
33
|
+
Then prepare a goal:
|
|
34
34
|
|
|
35
35
|
```text
|
|
36
|
-
$goal-prep
|
|
37
|
-
/goal-prep # in Claude Code
|
|
36
|
+
$goal-prep
|
|
38
37
|
```
|
|
39
38
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
## Why GoalBuddy Exists
|
|
43
|
-
|
|
44
|
-
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.
|
|
45
|
-
|
|
46
|
-
GoalBuddy gives your AI coding agent a durable loop:
|
|
39
|
+
In Claude Code, use:
|
|
47
40
|
|
|
48
41
|
```text
|
|
49
|
-
|
|
42
|
+
/goal-prep
|
|
50
43
|
```
|
|
51
44
|
|
|
52
|
-
|
|
45
|
+
Goal Prep creates the board and prints the exact `/goal` command to run next. That is the whole path.
|
|
53
46
|
|
|
54
|
-
## What
|
|
47
|
+
## What It Creates
|
|
55
48
|
|
|
56
49
|
```text
|
|
57
|
-
docs/goals/<
|
|
50
|
+
docs/goals/<your-goal>/
|
|
58
51
|
goal.md
|
|
59
52
|
state.yaml
|
|
60
53
|
notes/
|
|
61
54
|
```
|
|
62
55
|
|
|
63
|
-
|
|
64
|
-
- `state.yaml` is the board truth: task status, active task, receipts, and verification.
|
|
65
|
-
- `notes/` holds longer Scout, Judge, or PM findings when a task receipt would be too large.
|
|
66
|
-
|
|
67
|
-
## The Operating Model
|
|
68
|
-
|
|
69
|
-
GoalBuddy uses four primitives:
|
|
70
|
-
|
|
71
|
-
- **Charter**: states what this goal is trying to accomplish and what must stay true.
|
|
72
|
-
- **Board**: tracks tasks, status, receipts, and verification freshness.
|
|
73
|
-
- **Task**: exactly one active Scout, Judge, Worker, or PM task.
|
|
74
|
-
- **Receipt**: compact proof for every completed, blocked, or escalated task.
|
|
75
|
-
|
|
76
|
-
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:
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
npx goalbuddy agents # Codex TOML agents
|
|
80
|
-
npx goalbuddy agents --target claude # Claude Code markdown subagents
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
- **Scout** maps repo evidence, workflows, constraints, risks, and candidate next tasks.
|
|
84
|
-
- **Judge** resolves ambiguity, scope, risk, task selection, and completion claims.
|
|
85
|
-
- **Worker** performs one bounded implementation or recovery slice with explicit files and checks.
|
|
86
|
-
|
|
87
|
-
## Install Everywhere
|
|
88
|
-
|
|
89
|
-
```bash
|
|
90
|
-
npx goalbuddy
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
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.
|
|
94
|
-
|
|
95
|
-
If you prefer a global executable:
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
npm i -g goalbuddy
|
|
99
|
-
goalbuddy
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
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:
|
|
56
|
+
`goal.md` says what you want.
|
|
103
57
|
|
|
104
|
-
|
|
105
|
-
codex login status
|
|
106
|
-
codex features enable goals
|
|
107
|
-
npx goalbuddy doctor --goal-ready
|
|
108
|
-
```
|
|
58
|
+
`state.yaml` tracks the board.
|
|
109
59
|
|
|
110
|
-
|
|
60
|
+
`notes/` keeps longer findings out of the main thread.
|
|
111
61
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
```bash
|
|
115
|
-
npx goalbuddy --target codex
|
|
116
|
-
npx goalbuddy --target claude
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
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:
|
|
62
|
+
## How It Thinks
|
|
120
63
|
|
|
121
64
|
```text
|
|
122
|
-
/goal
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
Check the local Claude Code install:
|
|
126
|
-
|
|
127
|
-
```bash
|
|
128
|
-
npx goalbuddy doctor --target claude
|
|
65
|
+
rough idea -> goal prep -> /goal -> scout -> judge -> worker -> receipt -> verify
|
|
129
66
|
```
|
|
130
67
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
```bash
|
|
134
|
-
npx goalbuddy --codex-home /path/to/.codex --claude-home /path/to/.claude
|
|
135
|
-
npx goalbuddy --target codex --codex-home /path/to/.codex
|
|
136
|
-
npx goalbuddy --target claude --claude-home /path/to/.claude
|
|
137
|
-
```
|
|
68
|
+
Scout maps the repo.
|
|
138
69
|
|
|
139
|
-
|
|
70
|
+
Judge chooses the next bounded slice.
|
|
140
71
|
|
|
141
|
-
|
|
72
|
+
Worker changes code and leaves a receipt.
|
|
142
73
|
|
|
143
|
-
|
|
74
|
+
`/goal` keeps the loop honest until the original goal is actually done.
|
|
144
75
|
|
|
145
|
-
|
|
146
|
-
/goal Follow docs/goals/<slug>/goal.md.
|
|
147
|
-
```
|
|
76
|
+
## Update
|
|
148
77
|
|
|
149
|
-
|
|
78
|
+
When a new GoalBuddy version ships:
|
|
150
79
|
|
|
151
80
|
```bash
|
|
152
|
-
|
|
153
|
-
node ~/.codex/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
|
|
154
|
-
# Claude Code
|
|
155
|
-
node ~/.claude/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
|
|
81
|
+
npx goalbuddy update
|
|
156
82
|
```
|
|
157
83
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
```yaml
|
|
161
|
-
tasks:
|
|
162
|
-
- id: T001
|
|
163
|
-
type: scout
|
|
164
|
-
assignee: Scout
|
|
165
|
-
status: active
|
|
166
|
-
objective: "Map repo health and identify improvement candidates."
|
|
167
|
-
receipt: null
|
|
168
|
-
- id: T002
|
|
169
|
-
type: judge
|
|
170
|
-
assignee: Judge
|
|
171
|
-
status: queued
|
|
172
|
-
objective: "Choose the next safe implementation task."
|
|
173
|
-
receipt: null
|
|
174
|
-
- id: T003
|
|
175
|
-
type: worker
|
|
176
|
-
assignee: Worker
|
|
177
|
-
status: queued
|
|
178
|
-
objective: "Execute the safe implementation task selected by Judge."
|
|
179
|
-
allowed_files: []
|
|
180
|
-
verify: []
|
|
181
|
-
stop_if:
|
|
182
|
-
- "Need files outside allowed_files."
|
|
183
|
-
- "Verification fails twice."
|
|
184
|
-
receipt: null
|
|
185
|
-
```
|
|
84
|
+
That updates both Codex and Claude Code.
|
|
186
85
|
|
|
187
|
-
##
|
|
86
|
+
## Live Boards
|
|
188
87
|
|
|
189
|
-
GoalBuddy can
|
|
88
|
+
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.
|
|
190
89
|
|
|
191
90
|
<p align="center">
|
|
192
91
|
<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%">
|
|
193
92
|
</p>
|
|
194
93
|
|
|
195
|
-
##
|
|
196
|
-
|
|
197
|
-
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.
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
npx goalbuddy board docs/goals/<slug>
|
|
201
|
-
npx goalbuddy extend github-projects
|
|
202
|
-
npx goalbuddy extend
|
|
203
|
-
npx goalbuddy extend github-pr-workflow
|
|
204
|
-
npx goalbuddy extend install github-pr-workflow --dry-run
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
`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.
|
|
208
|
-
|
|
209
|
-
Current catalog examples include:
|
|
210
|
-
|
|
211
|
-
- `github-pr-workflow`: prepares receipt-aligned commit and PR handoff text.
|
|
212
|
-
- `github-projects`: mirrors GoalBuddy boards into GitHub Projects.
|
|
213
|
-
- `local-goal-board`: serves a local live board that updates from `state.yaml` and `notes/`.
|
|
214
|
-
- `ai-diff-risk-review`: summarizes risk in the current diff.
|
|
215
|
-
- `ci-failure-triage`: maps failing CI back to likely causes and next tasks.
|
|
216
|
-
- `docs-drift-audit`: checks whether docs still match implementation.
|
|
217
|
-
- `codebase-onboarding-map`: creates a concise repo map from files and conventions.
|
|
218
|
-
- `release-readiness`: checks whether a goal is ready to publish.
|
|
219
|
-
|
|
220
|
-
Extensions can publish, report, intake, or add role guidance. They are not board truth. `state.yaml` remains authoritative.
|
|
221
|
-
|
|
222
|
-
## Compatibility Window
|
|
223
|
-
|
|
224
|
-
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:
|
|
225
|
-
|
|
226
|
-
```bash
|
|
227
|
-
npx goalbuddy
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
Machine-readable commands such as `npx goal-maker install --json` keep JSON output clean so existing automation can migrate safely.
|
|
231
|
-
|
|
232
|
-
Release automation for future npm publishes is documented in [RELEASE.md](RELEASE.md).
|
|
233
|
-
|
|
234
|
-
## Examples
|
|
235
|
-
|
|
236
|
-
- `examples/improve-goal-maker/`: a small completed reliability run.
|
|
237
|
-
- `examples/extend-catalog-workflow/`: a larger run from product framing through implementation and cleanup.
|
|
238
|
-
- `examples/github-pr-workflow-extension/pr-handoff.md`: an extension-generated PR handoff artifact.
|
|
94
|
+
## Good For
|
|
239
95
|
|
|
240
|
-
|
|
96
|
+
- broad project improvements
|
|
97
|
+
- release prep
|
|
98
|
+
- bug hunts that need evidence
|
|
99
|
+
- refactors with verification steps
|
|
100
|
+
- anything too large for one prompt
|
|
241
101
|
|
|
242
|
-
|
|
243
|
-
- `goalbuddy/agents/`: Scout, Judge, and Worker agent definitions (Codex TOML; Claude Code markdown lives under `plugins/goalbuddy/agents/`)
|
|
244
|
-
- `goalbuddy/templates/`: `goal.md`, `state.yaml`, and `note.md`
|
|
245
|
-
- `goalbuddy/scripts/check-goal-state.mjs`: v2 board checker
|
|
246
|
-
- `internal/cli/goal-maker.mjs`: npm installer CLI for Codex and Claude Code
|
|
247
|
-
- `plugins/goalbuddy/`: Codex plugin (`.codex-plugin/`) and Claude Code plugin (`.claude-plugin/`) scaffolds
|
|
248
|
-
- `extend/` and `extend/catalog.json`: GitHub-hosted extension surface
|
|
249
|
-
- `examples/`: completed sample runs
|
|
102
|
+
## For This Repo
|
|
250
103
|
|
|
251
|
-
|
|
104
|
+
GoalBuddy is MIT licensed and published on npm.
|
|
252
105
|
|
|
253
|
-
|
|
106
|
+
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.
|
|
254
107
|
|
|
255
|
-
|
|
108
|
+
For release process details, see [RELEASE.md](RELEASE.md).
|
|
256
109
|
|
|
257
110
|
## Star History
|
|
258
111
|
|
|
Binary file
|
|
@@ -1240,6 +1240,7 @@ function installedPluginSkillRoot() {
|
|
|
1240
1240
|
const versions = readdirSync(root, { withFileTypes: true })
|
|
1241
1241
|
.filter((entry) => entry.isDirectory())
|
|
1242
1242
|
.map((entry) => entry.name)
|
|
1243
|
+
.filter(isSupportedVersion)
|
|
1243
1244
|
.sort(compareVersions)
|
|
1244
1245
|
.reverse();
|
|
1245
1246
|
for (const version of versions) {
|
|
@@ -1403,9 +1404,9 @@ function preserveInstalledExtensions(targets, { tempRoot = "" } = {}) {
|
|
|
1403
1404
|
if (!target) continue;
|
|
1404
1405
|
const source = join(target, "extend");
|
|
1405
1406
|
if (!existsSync(source)) continue;
|
|
1406
|
-
mkdirSync(tempPath, { recursive: true });
|
|
1407
1407
|
for (const entry of readdirSync(source, { withFileTypes: true })) {
|
|
1408
1408
|
if (bundledCoreExtensionIds.has(entry.name)) continue;
|
|
1409
|
+
mkdirSync(tempPath, { recursive: true });
|
|
1409
1410
|
const from = join(source, entry.name);
|
|
1410
1411
|
const to = join(tempPath, entry.name);
|
|
1411
1412
|
cpSync(from, to, { recursive: true, force: true });
|
|
@@ -1639,6 +1640,10 @@ function normalizeVersion(value) {
|
|
|
1639
1640
|
return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
|
|
1640
1641
|
}
|
|
1641
1642
|
|
|
1643
|
+
function isSupportedVersion(value) {
|
|
1644
|
+
return /^v?\d+\.\d+\.\d+(?:[-+].*)?$/.test(String(value).trim());
|
|
1645
|
+
}
|
|
1646
|
+
|
|
1642
1647
|
function compareVersions(left, right) {
|
|
1643
1648
|
const leftParts = normalizeVersion(left).split(".").map((part) => Number.parseInt(part, 10) || 0);
|
|
1644
1649
|
const rightParts = normalizeVersion(right).split(".").map((part) => Number.parseInt(part, 10) || 0);
|
package/package.json
CHANGED