goalbuddy 0.2.12 → 0.2.13
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/.agents/plugins/marketplace.json +20 -0
- package/README.md +113 -115
- package/internal/assets/goalbuddy-logo.svg +21 -0
- package/internal/assets/goalbuddy-og.png +0 -0
- package/internal/assets/goalbuddy-readme-hero.png +0 -0
- package/package.json +2 -1
- package/plugins/goalbuddy/.codex-plugin/plugin.json +1 -1
- package/plugins/goalbuddy/README.md +11 -1
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "goalbuddy",
|
|
3
|
+
"interface": {
|
|
4
|
+
"displayName": "GoalBuddy"
|
|
5
|
+
},
|
|
6
|
+
"plugins": [
|
|
7
|
+
{
|
|
8
|
+
"name": "goalbuddy",
|
|
9
|
+
"source": {
|
|
10
|
+
"source": "local",
|
|
11
|
+
"path": "./plugins/goalbuddy"
|
|
12
|
+
},
|
|
13
|
+
"policy": {
|
|
14
|
+
"installation": "AVAILABLE",
|
|
15
|
+
"authentication": "ON_INSTALL"
|
|
16
|
+
},
|
|
17
|
+
"category": "Coding"
|
|
18
|
+
}
|
|
19
|
+
]
|
|
20
|
+
}
|
package/README.md
CHANGED
|
@@ -1,81 +1,127 @@
|
|
|
1
1
|
# GoalBuddy
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p align="center">
|
|
4
|
+
<a href="https://goalbuddy.dev">
|
|
5
|
+
<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%">
|
|
6
|
+
</a>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<strong>Turn open-ended Codex work into one reviewable goal board.</strong>
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://www.npmjs.com/package/goalbuddy"><img alt="npm" src="https://img.shields.io/npm/v/goalbuddy?style=flat-square&color=684cff"></a>
|
|
15
|
+
<a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-071236?style=flat-square"></a>
|
|
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
|
+
</p>
|
|
18
|
+
|
|
19
|
+
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.
|
|
4
20
|
|
|
5
21
|
```bash
|
|
6
22
|
npx goalbuddy
|
|
7
23
|
```
|
|
8
24
|
|
|
9
|
-
Then invoke the skill inside Codex:
|
|
25
|
+
Then invoke the installed skill inside Codex:
|
|
10
26
|
|
|
11
27
|
```text
|
|
12
28
|
$goalbuddy
|
|
13
29
|
```
|
|
14
30
|
|
|
15
|
-
`$goalbuddy`
|
|
31
|
+
`$goalbuddy` prepares the board and prints the `/goal` command to run next. It does not start `/goal` automatically.
|
|
16
32
|
|
|
17
|
-
|
|
33
|
+
## Why GoalBuddy Exists
|
|
18
34
|
|
|
19
|
-
|
|
20
|
-
codex login status
|
|
21
|
-
codex features enable goals
|
|
22
|
-
npx goalbuddy doctor --goal-ready
|
|
23
|
-
```
|
|
35
|
+
Long Codex goals drift. A request like "improve this project" can turn into unbounded edits, stale verification, and premature completion claims.
|
|
24
36
|
|
|
25
|
-
|
|
37
|
+
GoalBuddy gives Codex a durable loop:
|
|
26
38
|
|
|
27
|
-
|
|
39
|
+
```text
|
|
40
|
+
vague goal -> Scout -> Judge -> Worker -> receipt -> verify -> repeat
|
|
41
|
+
```
|
|
28
42
|
|
|
29
|
-
|
|
43
|
+
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.
|
|
30
44
|
|
|
31
|
-
|
|
45
|
+
## What You Get Locally
|
|
32
46
|
|
|
33
47
|
```text
|
|
34
|
-
|
|
48
|
+
docs/goals/<slug>/
|
|
49
|
+
goal.md
|
|
50
|
+
state.yaml
|
|
51
|
+
notes/
|
|
35
52
|
```
|
|
36
53
|
|
|
37
|
-
|
|
54
|
+
- `goal.md` is the editable charter: objective, constraints, tranche, and stop rule.
|
|
55
|
+
- `state.yaml` is the board truth: task status, active task, receipts, and verification.
|
|
56
|
+
- `notes/` holds longer Scout, Judge, or PM findings when a task receipt would be too large.
|
|
57
|
+
|
|
58
|
+
## The Operating Model
|
|
38
59
|
|
|
39
|
-
|
|
60
|
+
GoalBuddy uses four primitives:
|
|
40
61
|
|
|
41
|
-
- **
|
|
42
|
-
- **
|
|
43
|
-
- **
|
|
44
|
-
- **
|
|
45
|
-
- **Board checker**: validates v2 goal folders and rejects old `gate`, `units`, `artifacts`, and `evidence.jsonl` layouts.
|
|
46
|
-
- **Extensions**: optional add-ons are discovered from `extend/catalog.json` without requiring npm updates for every integration.
|
|
62
|
+
- **Charter**: states what this goal is trying to accomplish and what must stay true.
|
|
63
|
+
- **Board**: tracks tasks, status, receipts, and verification freshness.
|
|
64
|
+
- **Task**: exactly one active Scout, Judge, Worker, or PM task.
|
|
65
|
+
- **Receipt**: compact proof for every completed, blocked, or escalated task.
|
|
47
66
|
|
|
48
|
-
|
|
67
|
+
The default agents are installed with the skill:
|
|
49
68
|
|
|
50
|
-
|
|
69
|
+
- **Scout** maps repo evidence, workflows, constraints, risks, and candidate next tasks.
|
|
70
|
+
- **Judge** resolves ambiguity, scope, risk, task selection, and completion claims.
|
|
71
|
+
- **Worker** performs one bounded implementation or recovery slice with explicit files and checks.
|
|
51
72
|
|
|
52
|
-
|
|
53
|
-
- **Board**: `state.yaml` is machine truth for tasks, status, receipts, and verification freshness.
|
|
54
|
-
- **Task**: exactly one active task is worked at a time.
|
|
55
|
-
- **Receipt**: every completed, blocked, or escalated task leaves compact proof of what happened.
|
|
73
|
+
## Install And Check Readiness
|
|
56
74
|
|
|
57
|
-
|
|
75
|
+
Install or refresh the Codex skill and bundled agents:
|
|
58
76
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
77
|
+
```bash
|
|
78
|
+
npx goalbuddy
|
|
79
|
+
npx goalbuddy update
|
|
80
|
+
```
|
|
62
81
|
|
|
63
|
-
|
|
82
|
+
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:
|
|
64
83
|
|
|
65
|
-
|
|
84
|
+
```bash
|
|
85
|
+
codex login status
|
|
86
|
+
codex features enable goals
|
|
87
|
+
npx goalbuddy doctor --goal-ready
|
|
88
|
+
```
|
|
66
89
|
|
|
67
|
-
|
|
90
|
+
Repair only the bundled agent definitions:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
npx goalbuddy agents
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Check the local install:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
npx goalbuddy doctor
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Use a non-default Codex home:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npx goalbuddy install --codex-home /path/to/.codex
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`install`, `update`, and `doctor` also support `--json` when an agent or script needs structured output.
|
|
109
|
+
|
|
110
|
+
## Run A Goal
|
|
111
|
+
|
|
112
|
+
After `$goalbuddy` creates or repairs the board, start the run with the printed command:
|
|
68
113
|
|
|
69
114
|
```text
|
|
70
|
-
docs/goals/<slug>/
|
|
71
|
-
goal.md
|
|
72
|
-
state.yaml
|
|
73
|
-
notes/
|
|
115
|
+
/goal Follow docs/goals/<slug>/goal.md.
|
|
74
116
|
```
|
|
75
117
|
|
|
76
|
-
|
|
118
|
+
Check board health at any time:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
node ~/.codex/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
|
|
122
|
+
```
|
|
77
123
|
|
|
78
|
-
For a broad prompt like
|
|
124
|
+
For a broad prompt like "Improve my project," the first active task should usually be Scout, not Worker:
|
|
79
125
|
|
|
80
126
|
```yaml
|
|
81
127
|
tasks:
|
|
@@ -104,50 +150,9 @@ tasks:
|
|
|
104
150
|
receipt: null
|
|
105
151
|
```
|
|
106
152
|
|
|
107
|
-
##
|
|
108
|
-
|
|
109
|
-
Install or update the Codex skill and bundled agents:
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
npx goalbuddy
|
|
113
|
-
npx goalbuddy update
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
`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.
|
|
117
|
-
|
|
118
|
-
### Compatibility Window
|
|
119
|
-
|
|
120
|
-
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:
|
|
121
|
-
|
|
122
|
-
```bash
|
|
123
|
-
npx goalbuddy
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
Machine-readable commands such as `npx goal-maker install --json` keep JSON output clean so existing automation can migrate safely.
|
|
127
|
-
|
|
128
|
-
Release automation for future npm publishes is documented in [RELEASE.md](RELEASE.md).
|
|
129
|
-
|
|
130
|
-
Repair only the agent definitions:
|
|
131
|
-
|
|
132
|
-
```bash
|
|
133
|
-
npx goalbuddy agents
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
Check what is installed:
|
|
137
|
-
|
|
138
|
-
```bash
|
|
139
|
-
npx goalbuddy doctor
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
Strictly check whether the native Codex `/goal` runtime is ready too:
|
|
143
|
-
|
|
144
|
-
```bash
|
|
145
|
-
npx goalbuddy doctor --goal-ready
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
`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.
|
|
153
|
+
## Extensions
|
|
149
154
|
|
|
150
|
-
|
|
155
|
+
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.
|
|
151
156
|
|
|
152
157
|
```bash
|
|
153
158
|
npx goalbuddy extend
|
|
@@ -156,51 +161,44 @@ npx goalbuddy extend install github-pr-workflow --dry-run
|
|
|
156
161
|
npx goalbuddy extend install --all --dry-run
|
|
157
162
|
```
|
|
158
163
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
```bash
|
|
162
|
-
npx goalbuddy install --codex-home /path/to/.codex
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
## Extensions
|
|
164
|
+
`goalbuddy extend` shows available extensions plus local install state, activation state, credential requirements, safe-by-default status, and missing environment variables.
|
|
166
165
|
|
|
167
|
-
|
|
166
|
+
Current catalog examples include:
|
|
168
167
|
|
|
169
|
-
|
|
168
|
+
- `github-pr-workflow`: prepares receipt-aligned commit and PR handoff text.
|
|
169
|
+
- `github-projects`: mirrors GoalBuddy boards into GitHub Projects.
|
|
170
|
+
- `ai-diff-risk-review`: summarizes risk in the current diff.
|
|
171
|
+
- `ci-failure-triage`: maps failing CI back to likely causes and next tasks.
|
|
172
|
+
- `docs-drift-audit`: checks whether docs still match implementation.
|
|
173
|
+
- `codebase-onboarding-map`: creates a concise repo map from files and conventions.
|
|
174
|
+
- `release-readiness`: checks whether a goal is ready to publish.
|
|
170
175
|
|
|
171
|
-
Extensions
|
|
176
|
+
Extensions can publish, report, intake, or add role guidance. They are not board truth. `state.yaml` remains authoritative.
|
|
172
177
|
|
|
173
|
-
|
|
178
|
+
## Compatibility Window
|
|
174
179
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
After `$goalbuddy` creates or repairs the board, start `/goal` with the printed command:
|
|
180
|
+
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:
|
|
178
181
|
|
|
179
|
-
```
|
|
180
|
-
|
|
182
|
+
```bash
|
|
183
|
+
npx goalbuddy
|
|
181
184
|
```
|
|
182
185
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
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.
|
|
186
|
-
|
|
187
|
-
Check board health:
|
|
186
|
+
Machine-readable commands such as `npx goal-maker install --json` keep JSON output clean so existing automation can migrate safely.
|
|
188
187
|
|
|
189
|
-
|
|
190
|
-
node ~/.codex/skills/goalbuddy/scripts/check-goal-state.mjs docs/goals/<slug>/state.yaml
|
|
191
|
-
```
|
|
188
|
+
Release automation for future npm publishes is documented in [RELEASE.md](RELEASE.md).
|
|
192
189
|
|
|
193
|
-
##
|
|
190
|
+
## Examples
|
|
194
191
|
|
|
195
|
-
|
|
192
|
+
- `examples/improve-goal-maker/`: a small completed reliability run.
|
|
193
|
+
- `examples/extend-catalog-workflow/`: a larger run from product framing through implementation and cleanup.
|
|
194
|
+
- `examples/github-pr-workflow-extension/pr-handoff.md`: an extension-generated PR handoff artifact.
|
|
196
195
|
|
|
197
|
-
## Repo
|
|
196
|
+
## Repo Map
|
|
198
197
|
|
|
199
|
-
- `goalbuddy/SKILL.md`:
|
|
198
|
+
- `goalbuddy/SKILL.md`: canonical Codex skill
|
|
200
199
|
- `goalbuddy/agents/`: Scout, Judge, and Worker definitions
|
|
201
200
|
- `goalbuddy/templates/`: `goal.md`, `state.yaml`, and `note.md`
|
|
202
201
|
- `goalbuddy/scripts/check-goal-state.mjs`: v2 board checker
|
|
203
|
-
- `$goal-maker` compatibility: generated by the installer for existing users
|
|
204
202
|
- `internal/cli/goal-maker.mjs`: npm installer CLI
|
|
205
203
|
- `plugins/goalbuddy/`: repo-local Codex plugin package scaffold
|
|
206
204
|
- `extend/` and `extend/catalog.json`: GitHub-hosted extension surface
|
|
@@ -208,9 +206,9 @@ See `examples/improve-goal-maker/` for a small completed reliability run, `examp
|
|
|
208
206
|
|
|
209
207
|
## Status
|
|
210
208
|
|
|
211
|
-
`0.2.x` is the v2 board
|
|
209
|
+
`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.
|
|
212
210
|
|
|
213
|
-
Use
|
|
211
|
+
Use GoalBuddy to structure autonomous Codex work. Keep relying on repo-specific `AGENTS.md`, tests, and CI for repo facts.
|
|
214
212
|
|
|
215
213
|
## License
|
|
216
214
|
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 190" role="img" aria-labelledby="title desc">
|
|
2
|
+
<title id="title">GoalBuddy logo</title>
|
|
3
|
+
<desc id="desc">GoalBuddy wordmark with lavender cloud mark.</desc>
|
|
4
|
+
<defs>
|
|
5
|
+
<radialGradient id="logoMarkGrad" cx="34%" cy="18%" r="92%">
|
|
6
|
+
<stop offset="0" stop-color="#f8f2ff"/>
|
|
7
|
+
<stop offset="0.46" stop-color="#b6a9ff"/>
|
|
8
|
+
<stop offset="1" stop-color="#5361ff"/>
|
|
9
|
+
</radialGradient>
|
|
10
|
+
<filter id="logoShadow" x="-20%" y="-25%" width="140%" height="160%">
|
|
11
|
+
<feDropShadow dx="0" dy="12" stdDeviation="10" flood-color="#4d48b8" flood-opacity=".24"/>
|
|
12
|
+
</filter>
|
|
13
|
+
</defs>
|
|
14
|
+
<g filter="url(#logoShadow)">
|
|
15
|
+
<path d="M72 141c-30 0-54-24-54-54 0-26 18-48 43-53C65 15 82 0 103 0c18 0 34 10 42 24 12-8 27-13 43-13 36 0 66 26 72 61 22 11 37 33 37 59 0 36-30 66-66 66H93c-8 0-15-2-21-6z" transform="translate(0 4) scale(.82)" fill="url(#logoMarkGrad)"/>
|
|
16
|
+
<ellipse cx="82" cy="81" rx="8" ry="12" fill="#061238"/>
|
|
17
|
+
<ellipse cx="132" cy="81" rx="8" ry="12" fill="#061238"/>
|
|
18
|
+
<path d="M99 101c8 9 18 9 27 0" fill="none" stroke="#061238" stroke-width="7" stroke-linecap="round"/>
|
|
19
|
+
</g>
|
|
20
|
+
<text x="230" y="116" fill="#071236" font-family="Geist, Avenir Next, Arial, sans-serif" font-size="82" font-weight="800" letter-spacing="-1">GoalBuddy</text>
|
|
21
|
+
</svg>
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "goalbuddy",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.13",
|
|
4
4
|
"description": "Turn open-ended Codex goals into a GoalBuddy Scout/Judge/Worker board with receipts, verification, and optional extensions.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
"goal-maker": "internal/cli/goal-maker.mjs"
|
|
9
9
|
},
|
|
10
10
|
"files": [
|
|
11
|
+
".agents/plugins/marketplace.json",
|
|
11
12
|
"README.md",
|
|
12
13
|
"CONTRIBUTING.md",
|
|
13
14
|
"examples",
|
|
@@ -17,6 +17,16 @@ npm run check
|
|
|
17
17
|
npx goalbuddy doctor
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
+
## Native Codex Install
|
|
21
|
+
|
|
22
|
+
Add the repository as a Codex plugin marketplace:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
codex plugin marketplace add tolibear/goalbuddy
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Then enable the `goalbuddy` plugin from that marketplace in Codex. The npm CLI remains useful for `doctor`, project-local agent setup, and optional GoalBuddy extension management.
|
|
29
|
+
|
|
20
30
|
For local CLI testing before npm publish:
|
|
21
31
|
|
|
22
32
|
```bash
|
|
@@ -26,4 +36,4 @@ node internal/cli/goal-maker.mjs doctor
|
|
|
26
36
|
|
|
27
37
|
## Release Notes
|
|
28
38
|
|
|
29
|
-
The plugin is prepared for the `tolibear/goalbuddy` repo and `goalbuddy` npm package.
|
|
39
|
+
The plugin is prepared for the `tolibear/goalbuddy` repo and `goalbuddy` npm package. Keep `.codex-plugin/plugin.json` aligned with `package.json` before publishing a new package release.
|