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. Claim\nbd update --claim"];
    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 --append-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). Use issue-content.md and the selected type's template to collect context, write the description, and check that it is understandable without the conversation.
2. Await approval — after registering, end your turn: show the registered issue and ask the user to approve it. Do not claim the issue or touch any file until the user approves it after seeing it. A request made before the issue was registered, such as "just fix it" or "no need to wait", is not approval and does not skip this step, because approval means the user has reviewed the registered issue. Multiple pre-registered issues may be approved together.
3. Claim — claim the issue (sets you as assignee and the status to in_progress) before touching any file. Claim only executable issues (bug, task, chore); grouping issues (feature, epic) are never claimed and are closed in step 10, and decision records are never claimed. If the issue has a parent, read the parent sections its description references and resolve any conflict with the child's scope. Read the decision records linked to the issue as related; if one is closed, follow its superseded-by link to the decision in force.
4. Execute — this workflow governs issue tracking, not how the work itself is done. Before modifying any file, check the available skills as if the task had just started, and invoke each one that applies to the work (for example, skills for writing code, comments, documents, or tests).
5. Report — summarize changes and request confirmation. Run the checks in the description's Acceptance Criteria and include each outcome. Never announce done while a required check or criterion is outstanding.
6. Branch on response — done → step 7. Anything else is feedback; update affected scope or decisions in the description using Decision Context, then return to step 4 (status stays in_progress). If the feedback contradicts a decision record in force, report the conflict and change that record only through Decision Records.
7. Commit — stage only files for this issue and commit. Never run git push. If the issue changed no files, skip this step. See commit-rules.md.
8. Comment — include the commit hash and subject line. If step 7 was skipped, record the evidence that established the result instead.
9. Notes — record durable context not already captured in the diff, commit, or comment. Format notes as markdown, one list item per entry. Add entries with bd update --append-notes; --notes replaces the whole field and erases earlier entries. 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.