gainforest-beads

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GainForest Beads Planning Workflow

GainForest Beads 规划工作流

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.

你是一个在人类和其他Agent组成的团队中工作的Agent。你们的共享记忆是beads图——一个由

bd

CLI管理、基于Git的问题追踪器。你所规划、认领和完成的所有工作都会记录在其中。如果在会话中途丢失所有上下文，下一个Agent可以读取该图并无缝继续工作。

运行

bd onboard

和

bd prime

来了解完整的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.

每当用户要求你执行工作时。功能需求、Bug修复、代码重构、调查分析——所有工作都适用。无需等待用户提及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)

已安装
```
bd
```
CLI（运行
```
bd version
```
验证；使用
```
npm install -g @beads/bd
```
安装）
用户的GitHub账号（如果不知道请询问——创建每个bead都需要它）

How It Works: Three Phases

工作流程：三个阶段

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

所有工作都严格遵循三个阶段：规划、执行、记录。绝不要跳过或调整顺序。

Phase 1: Plan

阶段1：规划

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

目标：在编写任何代码前，beads图中已完整记录需要执行的工作。

1a. Sync the graph

1a. 同步图表

Always start here. Every session. No exceptions.

bash

bd init --quiet
bd sync

每次会话都必须从这里开始，没有例外。

bash

bd init --quiet
bd sync

1b. Find or create an epic

1b. 查找或创建Epic

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

bash

bd list --type epic --json

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

bash

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

检查是否已有Epic覆盖用户的请求：

bash

bd list --type epic --json

如果找到匹配的Epic，请与用户确认。如果没有，创建一个新的：

bash

bd create "Epic: <目标>" -t epic -p <优先级> --assignee <用户GitHub账号> --json

1c. Break the epic into tasks

1c. 将Epic拆解为任务

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

bash

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

向用户提出任务拆分方案，迭代直到用户批准。

bash

bd create "<详细任务描述>" -t task -p <优先级> --parent <epic-id> --assignee <用户GitHub账号> --json

1d. Add dependencies (only when justified)

1d. 添加依赖（仅在必要时）

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.

bash

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

Document the reasoning in the blocked task's description.

添加依赖前，请先回答：为什么这些任务不能并行执行？

任务B需要任务A的输出？添加依赖。
任务A必须先完成测试，任务B才能集成？添加依赖。
属于同一领域但完全独立？不要添加依赖。

bash

bd dep add <被阻塞任务> <阻塞任务>

在被阻塞任务的描述中记录添加依赖的原因。

1e. Commit the plan

1e. 提交规划

bash

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.

bash

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

这样团队所有成员和Agent都能立即看到规划内容。

Phase 2: Execute

阶段2：执行

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:

bash

bd ready --json

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

bash

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:

bash

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:

bash

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

Step 6 — Sync and push the graph:

bash

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.

步骤1 — 选择任务。查看哪些任务未被阻塞：

bash

bd ready --json

步骤2 — 认领任务。这会告知所有人你正在处理该任务：

bash

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

步骤3 — 执行工作。编写代码、修复Bug或完成任务所需的其他工作。

步骤4 — 提交代码。包含任务ID，以便追踪提交记录：

bash

git add <文件>
git commit -m "<你完成的工作> (<task-id>)"

步骤5 — 关闭bead。必须在提交代码后再关闭——提交记录是工作完成的证明，关闭操作仅用于记录：

bash

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

步骤6 — 同步并推送图表：

bash

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

步骤7 — 返回步骤1。选择下一个未被阻塞的任务并重复流程。绝不要跳过步骤4-6。

Phase 3: Handle Problems

阶段3：处理问题

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

Mark the task as deferred with a clear explanation:

bash

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.

如果遇到阻塞当前任务的问题：

将任务标记为延迟，并附上清晰的说明：

bash

bd update <task-id> --status deferred --notes "Blocked: <问题详情及原因>"
bd sync
git add .beads/ && git commit -m "beads: defer <task-id> — <原因>" && git push

请用户创建新的beads任务来解决阻塞问题。不要私下绕过问题。

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

序号	规则	原因
1	始终先同步图表	过时的图表会导致重复工作和冲突
2	先规划再编码	未规划的工作对团队不可见
3	每个bead都关联用户账号	工作的所有者是用户，而非Agent
4	任务描述需支持无上下文恢复	新Agent应仅通过任务描述就能完成工作
5	谨慎添加依赖	错误的依赖会阻塞工作；缺失的依赖会导致集成失败
6	工作前先认领任务	避免两个Agent重复执行同一任务
7	先提交代码，再关闭bead，然后处理下一个任务	提交记录是工作证明；关闭仅用于记录；绝不要跳过或调整顺序
8	关闭时关联提交记录	`bd close <id> --reason "Completed: <hash>"` ——无例外
9	每次图表变更后Git提交 `.beads/`	这是团队了解工作进展的方式
10	遇到阻塞立即停止工作	标记延迟并升级问题；不要私下绕过问题

Resuming After Context Loss

上下文丢失后恢复工作

bash

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.

bash

bd init --quiet
bd sync
bd list --status open --status in_progress --json   # 查看已有的任务
bd ready --json                                      # 查看未被阻塞的任务
bd show <id> --json                                  # 读取任务的完整上下文

优先查看

in_progress

状态的任务——可能是你之前的会话或其他Agent正在处理的任务。任务描述中包含了继续工作所需的所有信息。

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.

糟糕的描述：

修复认证Bug

优秀的描述：

修复
app/api/oauth/callback/route.ts
中的OAuth回调竞态条件。当两个回调在100ms内到达时，第二个回调会覆盖Supabase中的第一个会话。在
atproto_oauth_session
表中添加互斥锁或检查-设置模式。验收标准：并发回调测试通过。依赖bd-a3f8.1（会话存储重构），因为修复需要新的
upsert
方法。