cc-os/plugins/os-backlog/skills/capture/SKILL.md

description

Capture work discovered mid-session as a Backlog card on the current repo's Planka board — resolves the board deterministically from the repo path, creates a missing board transparently via board-ensure, and always lands the card at Backlog. Use unprompted WHEN a concrete follow-up task, bug, or piece of deferred work surfaces mid-session that will not be done in this session. Invoked by `/os-backlog:capture`.

Capture a piece of work as a card on the right Planka board, cheaply, without interrupting the current task.

Column-ownership rules (non-negotiable)

• The AI creates cards at Backlog only. Never create a card in any other list.
• Working a card means moving it, via card-move (see below): Doing when work starts, Waiting plus a blocker comment when blocked, Review when a semi card ships, Done when an afk-ready card ships and is verified.
• Next stays human-curated in both directions — never move a card into or out of Next.
• Never move a card labeled hitl — hitl cards are human-owned, never self-assigned or moved by the AI.
• These rules are enforced deterministically by the CLI (card-move), not just documented here — a violating move fails with a one-line reason naming the rule.
• Priority/autonomy labeling is not capture's job — leave new cards unlabeled; the card-triage agent batches that later. Triage is initiated by the SessionStart hook of the board's OWNING project (the project the card was filed onto, or a parent umbrella labeling its own/child boards) — never by whichever project happened to file the card. A cross-project filer (see CROSS-PROJECT below) must never label the destination board's cards itself.

Procedure

All commands use the plugin CLI at ${CLAUDE_PLUGIN_ROOT}/bin/os-backlog.

1. Resolve the board for the current repo. Gather the inputs and run the pure resolver (no network):

   # config: contents of .cc-os/config if present, else null
   # boards: names from Planka — every project's boards, including archived--* ones
   echo '{"repo_path": "<repo root>", "config": <config-or-null>, "boards": [...]}' \
     | ${CLAUDE_PLUGIN_ROOT}/bin/os-backlog resolve
   

   To build the boards inventory, list boards via snapshot/the Planka client; if Planka is unreachable, stop here and report the error — do not guess.
2. Act on the decision:
   • use <board> → proceed to step 3.
   • activate <archived board> → run os-backlog activate <name> (activation is automatic — an archived board matching this repo is simply renamed back), then proceed.
   • stop-and-discuss → do NOT create anything. Tell the user the repo doesn't map to a board and ask where the card should go.
3. Ensure the board exists (idempotent — safe to run every time):

   ${CLAUDE_PLUGIN_ROOT}/bin/os-backlog board-ensure <board>
   

   Omit --project and it derives the right Planka project from the repo path: Dev under ~/dev/, Clients under ~/clients/, Servers under ~/servers/. Pass --project <name> to target (or create) any other project explicitly — board-ensure creates the project too if it doesn't exist yet. There's no command to move an existing board between projects; that's a manual step in the Planka UI.
4. Create the card at Backlog:

   ${CLAUDE_PLUGIN_ROOT}/bin/os-backlog card-add --board <board> --title "<short imperative title>" [--description "<context: repo, file paths, why>"]
   

5. Confirm to the user in one line: board, title. Then return to the interrupted task.

Moving a card

When work on a card starts, blocks, or ships, move it with:

${CLAUDE_PLUGIN_ROOT}/bin/os-backlog card-move --board <board> --card <ID> --to Backlog|Doing|Waiting|Review|Done

The CLI refuses (one-line reason, exit 1) any move into/out of Next, any move of a hitl card, any move out of Done, or a move to Done without the afk-ready label.

Failure behavior

Fail soft. If the planka-api gem or the Planka instance is unavailable, the CLI prints one clear error and exits nonzero — report that error to the user verbatim and offer to note the task elsewhere. Never retry destructively, never leave partial state unmentioned.