tolimarchuk/goalbuddy

GoalBuddy – A lightweight orchestration layer for long‑running AI‑assisted coding tasks

What it is

• GoalBuddy is an npm‑distributed CLI that creates a tiny, file‑based “board” inside your repository to keep large coding goals organized when you are using LLM‑powered coding assistants such as OpenAI Codex or Anthropic Claude Code.
• The board stores a charter (goal.md), a state file (state.yaml), notes, sub‑goal folders and a hidden .goalbuddy-board directory. All of this lives next to your normal source code, so the work can be paused, resumed, or handed off between different agents without losing context.

How it works

1. Start a run – npx goalbuddy installs the tool and prints a /goal‑prep command.
2. Goal‑prep – Running $goal‑prep (or /goal‑prep inside Claude) creates the board and tells you the exact command the LLM harness should execute next.
3. Dispatch – goalbuddy dispatch <board> --to codex|claude-code renders the current task’s prompt, calls the chosen LLM CLI head‑lessly, captures the returned receipt (a YAML proof of work), and verifies that any file changes stay inside the task’s declared allowed_files range using git.
4. Resume / hand‑off – npx goalbuddy resume lists all live boards and shows the continuation commands for each harness, letting you switch from Codex to Claude (or vice‑versa) without recreating the plan.
5. Verification loop – After a worker finishes, a judge agent validates the receipt against an oracle (test suite, demo, benchmark, or human sign‑off). The board’s state.yaml is updated with the outcome, completing the “Intent → Oracle → Surface → Loop → Proof” cycle described in the README.

Key concepts

• Board – The persistent, repo‑local representation of a goal.
• Receipt (v1) – A plain‑YAML, harness‑neutral record of what the LLM did, automatically validated.
• Scout / Judge / Worker – Built‑in agent roles that respectively map the repo, pick a safe slice of work, and execute it.
• Oracle – Any concrete signal that tells you the goal is truly achieved (tests, demos, benchmarks, etc.).
• Subgoals – Depth‑1 child boards for bounded branches of work, linked from a parent board.

Why it matters

• Continuity across tools – Because the board is just files, a goal started with Codex can be resumed tomorrow in Claude Code, or mixed‑vendor runs can happen on the same board.
• Safety & auditability – Receipts are stored, git‑verified, and later audited by a judge, giving a clear provenance trail for large code changes generated by LLMs.
• Minimal footprint – The only runtime artifact is the goalbuddy npm package; everything else lives in your repo, keeping the tool lightweight and easy to version‑control.

Typical use‑cases

• Large refactors that need step‑by‑step verification.
• Release preparation where multiple LLM‑driven tasks (bug fixes, documentation updates, version bumps) must be coordinated.
• Bug‑hunt investigations that require evidence (test failures, logs) to be captured as receipts.
• Any multi‑prompt project that would otherwise lose context between separate LLM calls.

Installation & basic commands

# Install and start a new board
npx goalbuddy

# Prepare the goal (creates board, prints next command)
$goal-prep   # or /goal-prep inside Claude

# Run the active task with a specific harness
npx goalbuddy dispatch docs/goals/my‑feature --to codex

# List and resume existing boards
npx goalbuddy resume

# Verify your Codex installation
npx goalbuddy doctor --target codex --goal-ready

# Update to the latest version
npx goalbuddy update

Where to learn more

• Full documentation lives in the repo under docs/ (including the receipt spec and release process).
• A live visual board can be opened at http://goalbuddy.localhost:<port>/<slug>/ to watch tasks, receipts, and subgoals update in real time.
• The project’s website: https://goalbuddy.dev

License – MIT (open source, free to use and modify).