name	managing-the-task-board
description	Use when creating, updating, moving, or reviewing tasks on the project's Backlog.md board (the backlog/ folder) — adding a work stream, changing a task's status, linking a plan/spec, or checking what is open / in progress / done.

Managing the Task Board

Overview

Project work streams are tracked on a local, git-native Backlog.md board: markdown task files in backlog/, no external service. Keep it coarse — one card per stream/epic, not per in-feature subtask. Subtask detail lives in the matching docs/superpowers/plans/*.md, which the card links to.

Critical rule

Operate the board only through the backlog CLI (npx backlog.md@latest …). Never hand-edit, rename, move, or delete files under backlog/ — the CLI owns IDs, frontmatter, status, and git commits. Use --plain for clean, parseable output when reading. (pnpm backlog opens the board.)

Statuses

To Do → In Progress → Done (defined in backlog/config.yml). The canonical board lives on main; check_active_branches is on, so task state rolls up across branches.

Quick reference

Goal	Command
See the board	`npx backlog.md board` (terminal) · `npx backlog.md browser` (web UI)
List / filter	`npx backlog.md task list --plain` · add `-s "In Progress"`
Read one task	`npx backlog.md task <id> --plain`
Create a stream	`npx backlog.md task create "Title" -s "To Do" -l <label> -d "what's next" --ref <plan-or-spec-path>`
Move / edit	`npx backlog.md task edit <id> -s "In Progress"` (also `-d`, `-l`, `--ac`, `--plan`, `--notes`)
Check acceptance criterion	`npx backlog.md task edit <id> --check-ac <index>`

Run any subcommand with --help for the full flag list.

Conventions

One card per stream; link its driving plan/spec with --ref.
Put what's next in the task description, not a list of micro-steps.
Don't open cards for trivial in-feature work — that belongs in the plan file's checkboxes.

Lifecycle (agents do this too)

Move the card's status as the stream moves — this is part of the work, not an afterthought:

Starting a stream (the moment you begin its plan via superpowers:writing-plans) → set In Progress: npx backlog.md task edit task-<n> -s "In Progress"
Merged / shipped → set Done.

Run status edits from the main checkout (the board is canonical there).

`Done` requires a merge (anti-drift — non-negotiable)

A card flips to Done only after its branch has landed on main. "Done" means merged, not "the code exists on a branch." Flipping Done while task-<n>--<topic> is unmerged strands the work and lets main drift past it — exactly what happened to TASK-8 (overlay v3 sat unmerged while main moved through the P1 MCP removal + packages/ refactor; TASK-13 had to replay it). Before editing a card to Done:

Merge task-<n>--<topic> into main (local merge — no remote).
From the main checkout, verify the commits are present: git branch --merged main lists the branch (or git log main --oneline shows the work). Only then run npx backlog.md task edit task-<n> -s "Done".

If a branch has fallen behind main, rebase/replay it promptly — the longer it drifts, the more a naive merge risks reintroducing already-removed work.

Branch / worktree naming

One card ↔ one branch. Name the branch (and a worktree, if you use one) task-<n>--<short-topic> so the mapping is obvious. This project has no Docker/devcontainer setup and defaults to a feature branch in the main checkout:

git checkout -b task-3--vite-adapter        # feature branch in place (default)
# or, if you want isolation:
git worktree add -b task-3--vite-adapter ../pinpoint-task-3 main

Relationship to superpowers & repo docs

The board is only an index of streams + their status — it does not replace the doc system. Keep responsibilities split, and confine Backlog.md to backlog/tasks/:

Concern	Lives in
Stream exists / status (open · in progress · done)	`backlog/tasks/` (this board)
Design / spec	`docs/superpowers/specs/`
Stepped plan + subtask checkboxes (in-feature source of truth)	`docs/superpowers/plans/`
Decisions log	`docs/decisions.md` (single running file)
Product / architecture docs	`docs/`

A card maps to one superpowers spec/plan effort; link it with --ref <plan-or-spec-path>. Do not use Backlog.md's backlog/docs/, backlog/decisions/, or backlog/milestones/ — they would fragment knowledge that already lives in docs/. A pre-commit guard (scripts/guard-backlog-boundary.sh) enforces this.

Common mistakes

Hand-editing backlog/*.md → corrupts IDs/git. Always use the CLI.
Creating granular subtasks → bloats the board. Keep it coarse; subtasks live in the plan file.
Writing decisions/specs into backlog/ → use docs/decisions.md and docs/superpowers/ instead.

name	managing-the-task-board
description	Use when creating, updating, moving, or reviewing tasks on the project's Backlog.md board (the backlog/ folder) — adding a work stream, changing a task's status, linking a plan/spec, or checking what is open / in progress / done.