Compile the board
Turn rough intent into a scoped goal.md, state.yaml, and starter /goal command.
Goal Buddy
A /goal operating system for long runs
Give /goal a best friend.
Goal Buddy prepares a goal.md for long /goal runs, keeps state.yaml as local truth, and pressures the work with a local board, receipts, and final proof.
$npx goalbuddy
$$goal-prep # Codex
$/goal-prep # Claude Code
Prepared docs/goals/improve-project/
goal.md
state.yaml
notes/
/goal follow goal.md
Loved by teams at
Keep one truth
/goal reads and updates local state instead of relying on a hosted tracker.
Finish with proof
Receipts map back to the original outcome before /goal can claim the work is complete.
Watch the board appear while your AI agent keeps working.
GoalBuddy opens a local live board before the task list is finished, so the work becomes visible as Scout, Judge, and Worker tasks populate.
Scout, Judge, Worker
A bounded loop for long /goal runs.
Goal Buddy separates mapping, decision, and implementation so /goal can continue from explicit state and keep checking the same finish line 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 the local board shows the same truth without replacing it.
goal.md
Human-readable charter for /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, restart your agent, prepare the board, and 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
- Set proof
- Judge the slice
- Worker patches
- Verify and update state
Goal pressure
Finish only when the oracle says the outcome is real.
GoalBuddy keeps the model small: one local board, one active task, one receipt trail, and a final audit that maps evidence back to the original owner outcome.
Goal oracle
Record the observable signal that proves the original outcome, then keep testing each slice against it.
Local surface
Open the live board as tasks populate, without credentials or a hosted tracker.
Receipts
Every completed or blocked task leaves changed files, commands, evidence, and remaining blockers.
Final audit
Completion requires a Judge or PM audit with full_outcome_complete: true.
Continuation
If safe local work remains, /goal advances instead of stopping after the first passing slice.
Whole slices
Judge chooses the largest safe useful slice, and Worker completes it before returning a receipt.
Give /goal a board, receipts, and a proof loop.
MIT licensed. Dependency-free runtime. Built around local goal.md and state.yaml files.
Star History
Track GoalBuddy’s open source momentum over time.