Compile the board
Turn rough intent into a scoped goal.md, state.yaml, and starter /goal command.
Goal Buddy
Open source Codex /goal companion
Give /goal a best friend.
Goal Buddy prepares a goal.md for the Codex /goal command, keeps state.yaml as local truth, and lets you extend goal state into GitHub, Slack, Linear, and other places when the workflow needs it.
$npx goalbuddy
$goal-prep
Prepared docs/goals/improve-project/
goal.md
state.yaml
notes/
/goal follow goal.md
Keep one truth
Codex reads and updates local state instead of relying on a hosted tracker.
Extend outward
Optional extensions publish handoffs or mirrors while state.yaml stays primary.
Scout, Judge, Worker
A bounded loop for long Codex runs.
Goal Buddy separates mapping, decision, and implementation so /goal can continue from explicit state instead of re-inferring the project every turn.
Map repo facts
Capture file ownership, commands, constraints, risks, and unknowns before selecting implementation work.
Choose the next slice
Convert findings into one task with allowed files, stop conditions, and concrete acceptance checks.
Patch and receipt
Implement the slice, record changed files and verification output, then hand updated state back to /goal.
Local truth
Repo files stay authoritative.
Goal Buddy writes the goal charter, machine-readable state, and notes into your repository. /goal can resume from those files, and extensions can mirror the state without replacing it.
goal.md
Human-readable charter for Codex /goal: intent, scope, acceptance criteria, and run instructions.
# Goal Charter
/goal Follow docs/goals/<slug>/goal.md
state.yaml
Structured board state for active agent, tasks, dependencies, receipts, and verification status.
version: 2
active_agent: judge
notes/
Longer Scout findings, Worker receipts, blocked-task notes, and command output summaries.
T003-worker-receipt.md
Install and prepare a board
Run the CLI once to install the Codex plugin. Restart Codex, use $goal-prep, then start with the printed /goal command.
State advances only after evidence.
Each role writes enough information for the next role to continue, and verification gates completion claims.
- Capture intent
- Scout constraints
- Judge the slice
- Worker patches
- Verify and update state
Extension surface
Install focused state extensions.
Install the optional bundle with one command, or pick individual catalog IDs. The core board still runs from goal.md and state.yaml.
GitHub PR workflow
Prepare receipt-aligned commit boundaries and PR handoff Markdown without requiring GitHub credentials.
GitHub Projects
Mirror state.yaml tasks into ProjectV2 draft issues, fields, and a Goal Board view.
Codebase onboarding
Generate a concise repo map from files, workflows, conventions, and entry points.
CI failure triage
Turn failed checks, logs, changed files, and receipts into a recovery brief.
Linear ticket handoff
Convert scoped follow-ups, blockers, verification, and review notes into ticket-ready Markdown.
Slack standup digest
Summarize completed work, blockers, verification status, and next steps for Slack handoff.
Give Codex a board, a receipt trail, and a next task.
MIT licensed. Dependency-free runtime. Built around local goal.md and state.yaml files.