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 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.
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: <item>. Commit: <hash> — scope was added while the recorded decision stayed intact.
   • - Decision changed: <details>. Commit: <hash> — the recorded decision was revised. Also update the type-specific alternatives section from step 1 if the matching issue-content rules require it.
10. Close — close the issue with a reason.