GainForest Beads Planning Workflow

You are an agent working inside a team of humans and other agents. Your shared memory is the beads graph — a git-backed issue tracker managed via the bd CLI. Everything you plan, claim, and complete is recorded there. If you lose all context mid-session, the next agent reads the graph and continues seamlessly.

Run bd onboard and bd prime to learn the full CLI.

When to Apply

Every time a user asks you to do work. Feature requests, bug fixes, refactors, investigations — all of it. Don't wait for the user to mention beads.

Prerequisites

bd CLI installed (bd version to verify; npm install -g @beads/bd to install)
The user's GitHub handle (ask if you don't know it — you need it for every bead you create)

How It Works: Three Phases

Everything follows three phases in strict order: Plan, Execute, Record. Never skip or reorder.

Phase 1: Plan

Goal: The beads graph reflects what needs to be done before you touch any code.

1a. Sync the graph

Always start here. Every session. No exceptions.

bd init --quiet
bd sync

1b. Find or create an epic

Check if an existing epic covers the user's request:

bd list --type epic --json

If one fits, confirm with the user. If not, create one:

bd create "Epic: <goal>" -t epic -p <priority> --assignee <user-github-handle> --json

1c. Break the epic into tasks

Propose a task breakdown to the user. Iterate until they approve.

bd create "<detailed task description>" -t task -p <priority> --parent <epic-id> --assignee <user-github-handle> --json

1d. Add dependencies (only when justified)

Before adding a dependency, answer: why can't these run in parallel?

Task B needs output from task A? Add it.
Task A must be tested before B integrates? Add it.
Same area but truly independent? Don't add one.

bd dep add <blocked-task> <blocking-task>

Document the reasoning in the blocked task's description.

1e. Commit the plan

bd sync
git add .beads/ && git commit -m "beads: plan tasks for <epic-id>" && git push

This makes the plan visible to all team members and agents immediately.

Phase 2: Execute

Goal: Work on tasks one at a time, following a strict claim-work-commit-close loop.

The loop (repeat for each task):

Step 1 — Pick. See what's unblocked:

bd ready --json

Step 2 — Claim. This tells everyone you're working on it:

bd update <task-id> --claim
bd sync

Step 3 — Work. Write code, fix bugs, whatever the task requires.

Step 4 — Commit the code. Include the task ID so the commit is traceable:

git add <files>
git commit -m "<what you did> (<task-id>)"

Step 5 — Close the bead. Always close after committing — the commit is proof of work, the close is bookkeeping:

bd close <task-id> --reason "Completed: <commit-hash>"

Step 6 — Sync and push the graph:

bd sync
git add .beads/ && git commit -m "beads: close <task-id>" && git push

Step 7 — Loop back to Step 1. Pick the next unblocked task and repeat. Never skip Steps 4-6.

Phase 3: Handle Problems

If you hit a blocker that prevents completing the current task:

Mark the task as deferred with a clear explanation:

bd update <task-id> --status deferred --notes "Blocked: <what went wrong and why>"
bd sync
git add .beads/ && git commit -m "beads: defer <task-id> — <reason>" && git push

Ask the user to create new beads tasks that address the blocker. Don't silently work around it.

Rules at a Glance

#	Rule	Why
1	Sync first, always	Stale graphs cause duplicate work and conflicts
2	Plan before code	Unplanned work is invisible to the team
3	User's handle on every bead	The user owns the work, not the agent
4	Tasks must survive memory loss	A fresh agent should execute any task from its description alone
5	Reason about dependencies	Wrong deps block work; missing deps cause integration failures
6	Claim before working	Prevents two agents from doing the same task
7	Commit code, then close bead, then next task	The commit is proof; the close is bookkeeping; never skip or reorder
8	Link the commit on close	`bd close <id> --reason "Completed: <hash>"` — no exceptions
9	Git-commit `.beads/` after every graph change	This is how the team sees what's happening
10	Blockers stop work	Defer and escalate; don't silently work around problems

Resuming After Context Loss

bd init --quiet
bd sync
bd list --status open --status in_progress --json   # what exists?
bd ready --json                                      # what's unblocked?
bd show <id> --json                                  # read a task's full context

Look at in_progress tasks first — someone (possibly you in a past session) was working on them. The task descriptions contain everything you need to continue.

What Makes a Good Task Description

Bad:

Fix the auth bug

Good:

Fix OAuth callback race condition in app/api/oauth/callback/route.ts. When two callbacks arrive within 100ms, the second overwrites the first session in Supabase. Add a mutex or check-and-set pattern on the atproto_oauth_session table. Acceptance: concurrent callback test passes. Depends on bd-a3f8.1 (session store refactor) because the fix requires the new upsert method.

The difference: the good description lets a stranger complete the task without asking a single question.

gainforest-beads