Bds Workflow

Beads Workflow

Project-specific beads workflow conventions for any file-modifying task.

Initialization

Before any workflow step below, verify bd where succeeds. If bd is not installed or bd where fails (the repo has not been initialized for bd), invoke the bds-setup skill to install bd and run the init flow, then resume.

Agent Workflow

Every file-modifying task, including trivial doc edits, follows these 10 steps:

digraph agent_workflow {
    rankdir=TB;
    node [shape=box, style=filled, fillcolor="#f8f8f8"];
    edge [color="#333333"];

    register  [label="1. Register\nEnsure issue exists"];
    await     [label="2. Await approval\nWait for user"];
    progress  [label="3. In Progress\nbd update --status=in_progress"];
    execute   [label="4. Execute\nModify files"];
    report    [label="5. Report\nSummarize, request review"];
    branch    [label="6. Branch" shape=diamond fillcolor="#ffe0b2"];
    commit    [label="7. Commit\nStage only issue files"];
    comment   [label="8. Comment\nbd comments add"];
    notes     [label="9. Notes (if needed)\nbd update --notes"];
    close     [label="10. Close\nbd close"];

    register -> await;
    await -> progress [label="approved"];
    progress -> execute;
    execute -> report;
    report -> branch;
    branch -> commit [label="done"];
    branch -> execute [label="feedback" style=dashed];
    commit -> comment;
    comment -> notes;
    notes -> close;

    discovery [label="mid-execution discovery\ncreate issue + dep" shape=note fillcolor="#e1f5fe"];
    execute -> discovery [style=dotted];
    discovery -> execute [label="continue parent" style=dotted];
}

1. Register — ensure a beads issue exists (create if needed, or confirm an existing one covers the scope). See [issue-content.md](issue-content.md) to choose the issue type, collect required intake fields, and then load the matching type-specific detail rules.
2. Await approval — do not start until the user approves. Multiple pre-registered issues may be approved together.
3. In progress — transition before touching any file.
4. Execute.
5. Report — summarize changes and request confirmation. If the description contains a verification section (e.g., ## Verification), execute every item and include the outcomes; never announce done while any verification item is still outstanding.
6. Branch on response — done → step 7. Anything else is feedback; return to step 4 (status stays in_progress).
7. Commit — stage only files for this issue and commit. Never run git push. See [commit-rules.md](commit-rules.md).
8. Comment — include the commit hash and subject line.
9. Notes — record durable context not already captured in the diff, commit, or comment. Format notes as markdown, one list item per entry. bd update --notes replaces the whole field; read the existing notes first and append the new entry. Required when step 6 feedback modified the recorded decision, using the matching prefix so the two cases stay separable later:

• - Added via feedback: . Commit: — scope was added while the recorded decision stayed intact.
• - Decision changed: . Commit: — the recorded decision was revised. Also update the type-specific alternatives section from step 1 if the matching issue-content rules require it.

1. Close — close the issue with a reason.

Session signals: only approved (step 1→3) and done (step 6→7) carry workflow meaning.

Before running any bd command for this workflow, follow the CLI forms in [commands.md](commands.md). Do not rely on memory or inferred bd syntax. For shell-quoting safety when calling bd with narrative args, see [shell-safety.md](shell-safety.md).

Operating Mode

Local-only shared-server (no Dolt remote). Do not run bd dolt pull / bd dolt push. The entire .beads/ directory is gitignored.

Concurrency

Only one issue may be in_progress per session, released on close.

Setup Exceptions

If a one-time setup prerequisite is missing (e.g., issue_prefix not configured), ask the user before configuring it, then resume the normal flow.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: seungyeop-lee
• Source: seungyeop-lee/beads-starter
• License: MIT

Install and usage instructions live in the source repository linked above.