From backlog-md-workflow
Apply Backlog.md operating conventions — when to create a backlog task vs a todo list vs nothing, treating tasks as design documents, decisions/ acceptance authority, and multi-task PR grouping. Use this whenever the user is creating, editing, splitting, or reviewing backlog tasks or decisions, or when an agent must decide whether work belongs in a tracked task at all.
How this skill is triggered — by the user, by Claude, or both
Slash command
/backlog-md-workflow:conventionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Operating wisdom for Backlog.md-managed repositories. This skill answers the *when* and *why* questions that the Backlog.md docs and `backlog --help` cannot.
Operating wisdom for Backlog.md-managed repositories. This skill answers the when and why questions that the Backlog.md docs and backlog --help cannot.
Trigger phrases:
backlog/tasks/, backlog/drafts/, or backlog/decisions/.setup skill).backlog/tasks/ directory exists.Read, Write, Edit, Glob, Grep, Bash (for backlog CLI).
backlog/tasks/ files are committed to git. That makes them the project's permanent design record — future agents read closed tasks to understand why a change was made. Treating them as ephemeral todo items destroys that value. These conventions distinguish the tracked-task surface from in-session todo lists, and protect the integrity of the historical record.
Create a task when any of these hold:
Do not create a task when:
TodoWrite (or no list at all).backlog/drafts/, not backlog/tasks/. Drafts have no status: and do not appear on the active board.When in doubt, prefer not creating. backlog/tasks/ is active work; idle ideas go to drafts/.
Each task in backlog/tasks/ is also the design document for its change. Description + Implementation Plan together must answer:
| Section | Answers |
|---|---|
| What | The scope of the change |
| Why | The problem and the constraints driving this approach |
| How | The chosen approach, as concrete steps (often a PR-A / PR-B / PR-C breakdown) |
| Alternatives | Other approaches considered, with reason for rejection — required whenever a non-obvious technical choice is made |
| Open questions | Explicit unknowns the implementer must resolve before merging |
If a task is too small to merit any of this, it probably should not be a task — see "When to create" above.
Tasks are the project's design history. Future agents read closed tasks to understand what was decided and why.
Done, do not rewrite the original Description, Acceptance Criteria, or Implementation Plan retroactively. Append divergence as Implementation Notes at the bottom of the file.| Surface | What | Who may write | Who may "accept" |
|---|---|---|---|
backlog/tasks/ | What to do | Any agent | n/a (status: To Do/In Progress/Done) |
backlog/decisions/ | What was decided across tasks | Any agent (drafts a status: proposed file) | Human only |
Agents must default new decisions to status: proposed. Only set status: accepted after the user explicitly confirms in chat. This is the boundary between agent autonomy and human authority over architectural direction.
There is no "one task = one PR" rule. Group tasks into a single PR when their changes touch the same code paths and tests. Always list the closed TASK-N IDs in the PR description so reviewers can map the diff back to the design docs.
Example: a single PR may legitimately close 13 work items if they form a coherent refactor of the same subsystem.
This is project-policy, not Backlog.md policy. The plugin recommends:
status: "To Do", priority: high, id: TASK-N): English — match Backlog.md's tool definitions exactly so its CLI/MCP can parse them.A common label scheme: one domain label (frontend, backend, infra, docs) + one kind label (feature, bug, refactor, chore, spec).
This skill primarily applies decisions inline rather than producing a separate artifact. When the user wants a written summary (e.g. before adopting these conventions), reproduce the table-of-contents above and link to ${CLAUDE_PLUGIN_ROOT}/assets/conventions.md, which is a drop-in markdown file teams can place under .ai/memories/, .claude/memories/, or docs/agents/.
decisions/<file>.md status: accepted without explicit user confirmation in the current chat.Done task's original sections. Append Implementation Notes for divergence.backlog/tasks/, drafts/, archive/, or completed/. State it clearly first.npx claudepluginhub ether-moon/backlog-md-workflow --plugin backlog-md-workflowCreates bite-sized, testable implementation plans from specs or requirements, with file structure and task decomposition. Activates before coding multi-step tasks.