conventions

conventions

Operating wisdom for Backlog.md-managed repositories. This skill answers the when and why questions that the Backlog.md docs and backlog --help cannot.

When This Skill Runs

Trigger phrases:

• "create a backlog task" / "should this be a task?"
• "split this task" / "merge these tasks"
• "is this a decision?" / "mark this decision as accepted"
• "group these tasks into one PR"
• Any time the agent is about to write to backlog/tasks/, backlog/drafts/, or backlog/decisions/.

Prerequisites

• The repository already has Backlog.md installed (see this plugin's setup skill).
• A backlog/tasks/ directory exists.

Allowed Tools

Read, Write, Edit, Glob, Grep, Bash (for backlog CLI).

Why these conventions exist

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.

The conventions

1. When to create a backlog task

Create a task when any of these hold:

• Work spans ≥ 2 files OR ≥ 1 day of effort.
• Work needs cross-session memory — the next agent or developer must be able to pick up where you left off.
• Acceptance criteria must be tracked.
• The change warrants a design rationale (alternatives, trade-offs, constraints).
• It belongs to a roadmap initiative (a phase, a milestone, a planned cleanup).

Do not create a task when:

• A single trivial fix ships in the current session — use TodoWrite (or no list at all).
• The intent is "remember this someday" — that goes in backlog/drafts/, not backlog/tasks/. Drafts have no status: and do not appear on the active board.
• A larger task already covers it — extend that task's Implementation Plan instead of fragmenting.

When in doubt, prefer not creating. backlog/tasks/ is active work; idle ideas go to drafts/.

2. Tasks double as design documents

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.

3. Tasks are a permanent record

Tasks are the project's design history. Future agents read closed tasks to understand what was decided and why.

• Write each task self-contained — do not rely on chat context that won't survive the session.
• Cite file paths and (where stable) line numbers, not "the file we just edited".
• After a task is Done, do not rewrite the original Description, Acceptance Criteria, or Implementation Plan retroactively. Append divergence as Implementation Notes at the bottom of the file.

4. Tasks vs decisions — authority

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.

5. Multi-task PRs are allowed

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.

6. Frontmatter language vs body language

This is project-policy, not Backlog.md policy. The plugin recommends:

• Frontmatter keys and values (status: "To Do", priority: high, id: TASK-N): English — match Backlog.md's tool definitions exactly so its CLI/MCP can parse them.
• Body (Description, AC, Plan, Notes): the project's primary documentation language.
• Labels: pick one convention and keep it consistent. Mixing English and other languages is fine if the team agrees.

A common label scheme: one domain label (frontend, backend, infra, docs) + one kind label (feature, bug, refactor, chore, spec).

Output

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

Constraints

• Never set decisions/<file>.md status: accepted without explicit user confirmation in the current chat.
• Never rewrite a Done task's original sections. Append Implementation Notes for divergence.
• Never silently move a task between backlog/tasks/, drafts/, archive/, or completed/. State it clearly first.