From board-superpowers
Use whenever any board operation in board-superpowers needs the canonical contract — the 6-state machine, the Card body schema, the branch-naming convention (claim/<kanban-id>-<key-slug>-<title-slug>), or the WIP counting formula. This is the read-only source of truth that every other board-superpowers skill consults before transitioning a card, validating a claim, or checking WIP. Use it even when the user doesn't say "schema" or "state machine" — any time card, branch, Status, or WIP comes up, this is what defines the rules.
How this skill is triggered — by the user, by Claude, or both
Slash command
/board-superpowers:board-canonThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Consult this skill before any card transition, claim push, branch name, or WIP check. It answers "what is the contract" — it does not perform actions itself. Read the relevant § below to settle the rule, then return to the calling skill to act.
Consult this skill before any card transition, claim push, branch name, or WIP check. It answers "what is the contract" — it does not perform actions itself. Read the relevant § below to settle the rule, then return to the calling skill to act.
| What you need to do | Look up here |
|---|---|
| Validate a card transition (e.g., Backlog → Ready) | § State machine + references/state-machine.md |
| Resolve a claim conflict or release a stale claim | § Claim protocol + references/claim-protocol.md |
| Generate a claim branch name from a card | § Branch naming + references/branch-naming.md |
| Compute a Consumer's WIP count vs cap | § WIP counting + references/wip-counting.md |
| Validate a card body's section shape | § Card body schema + references/card-body-schema.md |
A card lives in exactly one of six Status field values at any moment. Every transition writes one entry to the plugin's audit log (a local JSON-lines file at ~/.board-superpowers/repos/<normalized>/audit-local.jsonl).
Backlog ─────► Ready ─────► In Progress ─────► In Review ─────► Done
│ ▲ │
│ │ │
▼ │ ▼
Blocked (rework loops back to In Progress)
Legal transitions:
| From | To | Trigger |
|---|---|---|
| Backlog | Ready | Card body has all 5 mandatory sections + Acceptance criteria pass INVEST (Independent / Negotiable / Valuable / Estimable / Small / Testable) + an Estimate is set + no hard depends-on is still in Backlog or Ready |
| Ready | In Progress | A Consumer claims the card by pushing a claim/<kanban-id>-<key-slug>-<title-slug> branch (per § Claim protocol). Consumer's WIP count + 1 must not exceed the cap; no other Consumer may already hold a claim branch on this card |
| In Progress | Blocked | An external dependency is unresolved. The blocker MUST be named in a card comment; "I haven't started yet" is not a blocker |
| Blocked | In Progress | The named blocker is resolved |
| In Progress | In Review | The Consumer opens a PR from the card's claim branch whose body passes the three-section PR contract (see the enforcing-pr-contract skill) |
| In Review | In Progress | Reviewer requests changes (rework loop). The Consumer addresses comments on the same claim branch, NOT a new branch |
| In Review | Done | The PR is merged (NOT closed without merge); no outstanding "request changes" review remains |
Illegal transitions (the plugin's scripts and CI gates reject these):
references/state-machine.md documents each transition's checklist + audit catalogue.
Every Card body MUST have this structure. Sections appear in this order. The Producer writes them at intake; the Consumer reads them at claim time.
<!-- thin-pointer -->
**Spec**: <relative path to the spec / design doc, with section anchor>
**Owner**: @<github-handle>
**Estimate**: XS | S | M | L
<!-- /thin-pointer -->
## Goal
<one-sentence outcome statement; what the user will be able to do once this card is Done>
## Acceptance criteria
- [ ] criterion 1 (verifiable independently; not "tests pass" — be specific)
- [ ] criterion 2
- [ ] ...
## Out of scope
<things this card explicitly does NOT do, even though they're tempting>
## Dependencies
- depends-on: #<other-card-N> (hard — cannot start until that card is Done)
- depends-on (soft): #<other-card-M> (preferable but not required)
- depended-on-by: #<other-card-K> (this card unblocks K)
## Execution Hints
(optional — Producer-to-Consumer signals: recommended execution skill, known gotcha, type tag for conditional gate routing like `## Execution Hints: ui` or `: security`)
## Notes
<free-form context the Consumer will need; design rationale; gotchas>
<!-- board-superpowers:audit-trail -->
**Audit trail**: query ~/.board-superpowers/repos/<normalized>/audit-local.jsonl by `card_number = N`.
<!-- /board-superpowers:audit-trail -->
The 5 visible sections (Goal / Acceptance criteria / Out of scope / Dependencies / Notes) are MANDATORY. An optional 6th section, ## Execution Hints, may appear before ## Notes for Producer-to-Consumer signals (recommended skill, known gotcha, conditional-gate routing tags). The thin-pointer block at the top and the bottom marker are auto-generated by tooling — hand edits to the bottom marker are explicitly rejected.
When a Card is read from the backend, the projection may also surface read-only display metadata (display_parent, display_children_count, display_hierarchy_path) — these are agent-readable for context only and never participate in state, claim, WIP, or PR-linkage decisions. See references/card-body-schema.md § "Display-only metadata" for the field contract and absence semantics.
Two bottom-region marker pairs are reserved (machine-managed):
<!-- board-superpowers:creator-trace --> — platform + session id of the creating session (per card #44; new cards only — see references/card-body-schema.md § "Creator-trace marker").<!-- board-superpowers:audit-trail --> — query pointer to the audit log (existing behavior).The creator-trace marker is auto-prepended by intake tooling
(via bsp_render_creator_trace_block in scripts/lib/common.sh)
at gh issue create time and is NOT part of the manual
schema-block template above. The audit-trail marker IS part of
the manual schema and appears in every Card body authored by
hand or by decomposition tooling.
references/card-body-schema.md documents the filler-detection rules applied to each section + the INVEST checklist for Acceptance criteria.
A Consumer claims a card by pushing an empty branch named per § Branch naming below to origin. The branch push is the claim signal — the board's Status field flip is a downstream effect, not the source of truth.
Why a branch push, not a Status edit:
git reflog + the backend's event stream; a Status edit alone is harder to forensically trace later.git push origin --delete <claim-branch> releases the claim cleanly.The transactional write order (performed by scripts/claim-card.sh):
$HOME/.config/superpowers/worktrees/<repo>/<claim-branch> (override base path with BOARD_SP_WORKTREE_DIR).origin/main inside the worktree.If step 4 fails, steps 1-3 are NOT rolled back automatically — the Consumer must explicitly surface the partial state to the architect rather than silently retry.
references/claim-protocol.md documents the conflict-resolution playbook for race conditions and stale-claim release.
The plugin enforces a per-Consumer WIP cap. The formula:
WIP_count(consumer) =
(cards in In Progress claimed by this consumer)
+ (cards in In Progress with the `suspended` label, claimed by this consumer)
+ (cards in In Review whose PR was authored by this consumer and is still open)
Cards in Blocked are excluded from the count — being blocked is not active work; the Consumer should be picking up something else while waiting.
The default cap is 5 per Consumer (per spec). Each architect overrides per-repo by writing wip_limit: <N> in .board-superpowers/config.local.yml — this file is per-user (gitignored via the project-wide *.local.* pattern), so Alice running 5 parallel sessions and Bob running 1 do not impose their preferences on each other. A Consumer attempting to claim a card past their wip_limit gets a hard rejection at the agent layer (this skill enforces it before invoking claim-card.sh).
references/wip-counting.md documents corner cases (suspended cards, abandoned worktrees, post-merge accounting lag, override mechanism).
Canonical format: claim/<kanban-id>-<key-slug>-<title-slug>
Where:
<kanban-id> is the local id of the active kanban this card belongs to (read from <repo>/.board-superpowers/settings.yml § modules.m10_kanban). For repos with one active kanban, the id is typically primary.<key-slug> is slugify(Card.key) — Card.key is the backend's display-stable opaque card identifier (GitHub Project v2: the issue number 42; Linear: eng-42; Jira: proj-42). The slugifier (bsp_slugify in scripts/lib/common.sh) lowercases and reduces to alphanumeric + hyphens.<title-slug> is the card title slugified by the same rules: lowercase, alphanumeric + hyphens, max 40 characters.Examples:
| Active kanban | Card key | Card title | Branch |
|---|---|---|---|
primary (GitHub Project v2) | 12 | Implement board-canon SKILL.md | claim/primary-12-implement-board-canon-skill-md |
primary (GitHub Project v2) | 47 | Fix issue with WIP counter (race) | claim/primary-47-fix-issue-with-wip-counter-race |
legal (future Jira projection) | comp-7 | Audit log retention review | claim/legal-comp-7-audit-log-retention-review |
Banned characters in branch names (replaced with hyphens by the slugifier; runs collapsed): spaces, /, :, ?, [, ], ^, ~, \, *, control characters.
The same card uses exactly one claim branch across its lifetime, including rework. Push new commits to the same branch on a "request changes" review — do NOT create a -v2 suffixed variant.
A two-segment legacy form exists on repos authored under earlier plugin versions; the parser accepts both, and only the canonical three-segment form is emitted for new claims. See references/branch-naming.md § "Legacy two-segment form" for the parser contract and migration path.
references/branch-naming.md documents the slugifier edge cases, the legacy-form parser contract, and the rare exception flow for materially-renamed cards.
briefing-daily, intaking-requirement, reviewing-pr-queue, triaging-board) and consuming-card (Consumer).enforcing-pr-contract for PR shape and the audit log writer for the trace.This skill defines WHAT the contract is. The other skills decide when and how to act on it.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub panqiwei/board-superpowers --plugin board-superpowers