# Bds Workflow

> 10-step beads-starter workflow guide. Runs only on explicit invocation.

- Skill: `seungyeop-lee/bds-workflow` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add seungyeop-lee/bds-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/seungyeop-lee/bds-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: seungyeop-lee (https://skillmd.com/u/seungyeop-lee)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/seungyeop-lee/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:

```dot
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: <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.

**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.