using-board-superpowers

name	using-board-superpowers
description	Use as the FIRST skill in any board-superpowers session AND as the plugin's manual page. Read this skill (body + references/) for a complete, self-contained orientation — what the plugin is, the 14-skill catalog, the 6-state Card lifecycle, on-disk state, and dispatch routing. Routes ambiguous sessions into the correct Producer routine (briefing-daily / intaking-requirement / reviewing-pr-queue / triaging-board) or Consumer mode (consuming-card, for claiming card N). Skip when the message clearly matches a downstream skill directly (e.g., "[board-card:#12]" → consuming-card).
when_to_use	Use when intent is ambiguous, when no other board-superpowers skill matched, when the user asks "what is this plugin / how does this work / what skills exist / explain the architecture", OR when the SessionStart hook injected an INVOKE marker pointing at a downstream skill.

using-board-superpowers

The entry skill — first touch when a board-superpowers session starts. Two jobs:

1. Manual page. Reading this body and its references/ gives a complete, self-contained picture of the plugin: what it is, what skills it ships, how a Card flows, what state lives where. Everything you need to act on the next user message is here.
2. Router. Once oriented, dispatch the session to the right downstream skill based on the user's message OR a hook-injected INVOKE: <skill> marker.

What board-superpowers is

board-superpowers turns a GitHub Project into a Producer/Consumer board for AI-driven engineering, packaged as a dual-platform plugin (Claude Code + OpenAI Codex CLI):

• Producer — one agent (typically the human architect's session) plans work, decomposes requirements into Cards, and reviews PRs.
• Consumer — many parallel agents, each claiming exactly one Card, implementing it on a dedicated git worktree, and submitting one PR.

It is a scheduling layer, not an execution engine. It owns "what work is in flight, who's on what, what state is it in" — and delegates the actual work (TDD, debugging, QA, security review) to two sibling plugins, superpowers and gstack. board-superpowers never reimplements those disciplines.

What it does at runtime

Four jobs:

1. Routes every session into Producer (board orchestration) or Consumer (one-card-to-PR) based on the first user message, first-time / version-transition state, or a hook-injected intent marker.
2. Coordinates work through GitHub. No plugin server, no shared backend. Truth lives on the user's GitHub Project; plugin state splits into a host-local state.yml (out of git) and a per-repo config.yml (in git).
3. Delegates the actual work to superpowers:* and gstack:/*. Composition is permanent; we never reimplement upstream disciplines.
4. Records every mutating action (status change, claim, branch push, PR merge) to a BYO RDBMS audit log (Postgres / MySQL / SQLite). When the DB is unreachable, writes degrade to a local jsonl trace and the entry's mode field records the cause.

The two roles you might be playing

Role	You're in this role when the user says ...	Routes to
Producer — daily	"what should I work on" / "morning briefing" / "today's plan" / "board overview"	board-superpowers:briefing-daily
Producer — intake	"new requirement" / "intake this idea" / "I have a feature" / "add a card"	board-superpowers:intaking-requirement
Producer — review	"review the PRs" / "what's in In Review" / "merge ready"	board-superpowers:reviewing-pr-queue
Producer — triage	"what's blocked" / "triage the board" / "release stale claims"	board-superpowers:triaging-board
Consumer	[board-card:#N] / "claim card N" / "work on card N" / "implement #N"	board-superpowers:consuming-card
Bootstrap (first time)	"set up board-superpowers" / "first time on this repo" / OR state probe finds host or per-repo state files absent	board-superpowers:bootstrapping-repo

If the message doesn't match any of these and isn't clearly off-topic, ask — don't guess.

The 6 Card states

Every Card on the board sits in exactly one of these states:

Backlog ─▶ Ready ─▶ In Progress ─▶ In Review ─▶ Done
                        │   ▲          │
                        ▼   │          ▼
                     Blocked       (rework loops back
                                   to In Progress on
                                   "request changes")

• Backlog — captured but not yet shaped enough to claim.
• Ready — INVEST-compliant, has acceptance criteria, sized, claimable.
• In Progress — claimed by exactly one Consumer, branch claim/<kanban-id>-<key-slug>-<title-slug> exists (e.g., claim/default-42-refactor-cache), work happening.
• Blocked — claimed but cannot progress (dep / external answer needed). Released or unblocked.
• In Review — PR open, awaiting Producer review + CI.
• Done — PR merged, branch deleted, post-merge cleanup ran.

WIP cap (per architect): count(In Progress) + count(suspended-label) + count(In Review) ≤ wip_limit. Blocked is NOT counted — so a stuck card doesn't lock the cap.

Branch naming (canonical form): claim/<kanban-id>-<key-slug>-<title-slug> (e.g., claim/default-42-refactor-cache). <kanban-id> identifies the kanban; <key-slug> is the canonical Card.key with hyphens rewritten to underscores (so a Linear-shaped key ENG-42 becomes branch segment eng_42); <title-slug> is the kebab-case shortened title.

The 10 skills, by layer

Three layers, strictly downward dependency (Entry → Molecular → Atomic). Atomic skills are reflexes — they MUST NOT call any same-plugin skill.

Entry layer (1) — auto-matched on user prompt, never does real work itself:

• using-board-superpowers (this skill) — manual + router.

Molecular layer (7) — business workflows, state-machine-shaped:

• briefing-daily — Producer daily orientation. Board read, WIP flagging, stale-claim detection, next-action recommendation.
• intaking-requirement — Producer intake. Acknowledge, shape-judge, spec-first check, route to sibling skill or create card.
• reviewing-pr-queue — Producer review queue. Validate PRs via enforcing-pr-contract, comment on violations, transition cards.
• triaging-board — Producer triage. Blocked-card 3-class remediation, stale-claim detection and release.
• consuming-card — Consumer lifecycle. Claim → implement → PR → cleanup.
• decomposing-into-milestones — Turns a design artifact into INVEST-compliant vertically-sliced Cards on the board.
• bootstrapping-repo — Sole executor for setup-stages, including version-transition migrations per ADR-0012. First-time host + per-repo setup, plugin-upgrade reconvergence, and agentic config-item elicitation; injects routing block into AGENTS.md / CLAUDE.md.

Atomic layer (6) — single-purpose contracts, reused by molecular skills:

• board-canon — read-only contract: state machine + Card body schema + branch naming + WIP rules.
• enforcing-pr-contract — PR three-section enforcement (Automated Verification / Human Verification TODO / Retro Notes) + Card acceptance-criteria sync at submit.
• classifying-actions — autonomy-classification SPOT. Per board-superpowers:classifying-actions (the atomic SKILL that owns the autonomy matrix + override merging + 5-step triage rule), invoke that skill with the action_id and act on its A (auto) / R (architect approval required) / N (forbidden) decision.
• auditing-actions — Audit log schema + propose/resolve sequencing + BYO-RDBMS write conventions.
• operating-kanban — 8-action protocol dispatch over the active projection (backend selection from <repo>/.board-superpowers/settings.yml § modules.m10_kanban, per-projection action invocation, failure-mode dispatch).

Catalog status: 10 of 10 shipped (v1 catalog complete).

The 5 bounded contexts

Context	Scope
Board	Card + PR aggregates; GitHub Project + Issues + git refs
Session	ProducerSession + ConsumerLogical aggregates; OS processes + worktrees
Bootstrap	Host + per-repo first-time setup; per-repo config.yml, host-local state.yml
Audit	AuditTrail aggregate; the BYO RDBMS write path
Spec	Thin SpecPointer linking a Card body to authoritative architecture docs

Each skill operates over one or more of these contexts; the catalog above hints which.

How a Card flows (lifecycle)

 IDEA ─▶ DESIGN ─▶ READY ───▶ CLAIMED ───▶ IN REVIEW ─▶ DONE
   │       │         │           │             │           │
 user   Producer  Producer   Consumer       Producer    Producer
 brings + intake  + decom-   + worktree     + review    + merge
 to     skills    posing-    + super-       + /qa       + cleanup
 board            into-      powers TDD     + /cso        runs
                  milestones loop                     (audit logged)

Every transition that mutates state (claim, status change, PR push, merge) flows through classifying-actions (A/R/N decision) and auditing-actions (audit log write).

How we compose superpowers + gstack

board-superpowers is a scheduling layer; the actual coding-discipline work is permanent composition with two sibling plugins:

• gstack — bookends. Direction-setting before a Card is claimed (/office-hours, /plan-ceo-review, /plan-eng-review) and delivery-side verification (/review, /qa, /cso).
• superpowers — middle. The coding-discipline loop inside a Consumer: brainstorming → writing-plans → test-driven-development → systematic-debugging → verification-before-completion → requesting-code-review. TDD is mandatory.

Conflict arbitration follows superpowers:using-superpowers precedence: user instructions > skill > default behavior. A planning skill's "ready, start coding" advice does NOT override TDD discipline unless the user explicitly says so in the current conversation.

board-superpowers does NOT prescribe a release process. gstack:/ship / /canary / /land-and-deploy are project-specific — enable only if they fit the consuming repo's deployment shape.

State on disk

Path	Tracked?	Contents
~/.board-superpowers/manifest.yml	host-local, NOT in git	List of repos this host has bootstrapped
~/.board-superpowers/repos/<normalized>/state.yml	host-local, NOT in git	Per-(host, repo) state: schema version, last-seen plugin version, routing-block hashes, features-enabled list
<repo>/.board-superpowers/config.yml	committed	Project coords (<owner>/<number>), team-shared settings
<repo>/.board-superpowers/config.local.yml	gitignored	Per-user: wip_limit, autonomy_overrides
<repo>/.board-superpowers/.venv/	gitignored	Per-repo Python venv (uv-managed) for plugin runtime deps
BYO RDBMS (Postgres / MySQL / SQLite)	external	Audit log table written by audit-log-write.sh
~/.board-superpowers/repos/<normalized>/audit-local.jsonl	host-local, NOT in git	Local degradation trace when the BYO DB is unreachable
~/.board-superpowers/credentials.yml	host-local, chmod 0600, NOT in git	BYO RDBMS connection string (audit_db_url) when configured

<normalized> is the primary repo's absolute path with leading / stripped and remaining / replaced by - (e.g. /Users/foo/proj → Users-foo-proj).

Routing decision tree

flowchart TD
    A["Session message arrives"] --> B{"Hook injected\nINVOKE marker?"}
    B -- yes --> C["Route per marker"]
    B -- no --> D{"State probe:\nmanifest.yml or\nper-repo state.yml\nabsent?"}
    D -- yes --> E["Route to\nbootstrapping-repo"]
    D -- no --> F{"Message signal?"}
    F -- "[board-card:#N] /\nclaim card N" --> G["Route to\nconsuming-card"]
    F -- "what should I work on /\nreview the PRs /\nintake / triage" --> H["Route to\nappropriate\nroutine SKILL"]
    F -- "what is this plugin /\nhow does this work" --> I["Answer inline\nfrom this skill"]
    F -- "no clear signal" --> J["Ask user to\ndisambiguate"]

Routing table

Signal in user message	Route to
Literal [board-card:#N]	board-superpowers:consuming-card (with N as $card_number)
"claim card N" / "work on card N" / "implement #N"	board-superpowers:consuming-card
"what should I work on" / "morning briefing" / "today's plan" / "board overview"	board-superpowers:briefing-daily
"review the PRs" / "what's in In Review" / "merge ready" / "PR queue"	board-superpowers:reviewing-pr-queue
"new requirement" / "intake this idea" / "I have a feature" / "add a card"	board-superpowers:intaking-requirement
"what's blocked" / "triage the board" / "release stale claims" / "stale claims"	board-superpowers:triaging-board
"what is this plugin" / "what skills exist" / "explain the architecture"	Answer inline from this skill — see "Sections" below
"set up board-superpowers" / "first time on this repo"	board-superpowers:bootstrapping-repo
Anything board-related but not in this table	Ask the user to disambiguate — do NOT pick a default

Skills with strong direct triggers — decomposing-into-milestones ("decompose this design", "split into cards", "break into milestones") and bootstrapping-repo (state-probe match or direct phrasing) — auto-fire on their own description matchers. This entry skill does NOT need to route to them; the table above lists only the routes this skill is responsible for.

Reliable gate (Step 1/2/3)

The SessionStart hook is best-effort; this skill is the contract. Always run all three steps below itself, even if the hook fired correctly.

1. Dep check. Run bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-deps.sh --machine. Empty stdout = OK. Non-empty = surface the dep / routing problem before any further routing.

2. State probe. Check ~/.board-superpowers/manifest.yml and ~/.board-superpowers/repos/<normalized>/state.yml. Resolve the primary repo root via bsp_primary_repo_root "${PWD}" from scripts/lib/common.sh — NEVER git rev-parse --show-toplevel directly (worktree-vs-primary repo path mismatch).

3. Marker consumption. Inspect this turn's additionalContext payload for INVOKE: <skill> + REASON: <line>. Recognized skill name → route immediately. Unknown name → surface "unrecognized hook intent marker" rather than guess. Marker absent but step 2 found state files absent → route the same way (Layer 2 reliable gate).

For the gate's full mechanics — the bsp_primary_repo_root vs bsp_pick_worktree_dir distinction, fence sentinels, state.yml:routing_blocks[] tamper detection — see references/runtime-mechanism.md.

Sections (deeper references)

Want to understand ...	Read
The three-layer architecture, 5 bounded contexts, how skills compose	references/architecture-overview.md
What happens between "user message arrives" and "downstream skill invoked", end-to-end	references/runtime-mechanism.md
The full Card lifecycle from idea to merged PR, who drives each step	references/card-lifecycle.md
Every state file, env var, and DB table, who reads/writes each	references/state-on-disk.md
Definitions: Producer / Consumer / Card / WIP / SPOT / autonomy class / propose-resolve	references/glossary.md
Edge cases in routing decisions (multi-row matches, off-topic, ambiguous)	references/routing.md
The canonical bytes injected into AGENTS.md / CLAUDE.md at bootstrap	references/agentsmd-routing.md
First-time setup: what bootstrap-host.sh / bootstrap-project.sh automate, manual fallback	references/installation.md

The references are self-contained — each answers its question on its own.

Cross-plugin signals to NOT capture

Some user messages sound board-related but actually belong to sibling plugins:

Phrase	Belongs to
"let's brainstorm this"	superpowers:brainstorming (will route itself)
"investigate this bug"	gstack:/investigate
"QA this URL"	gstack:/qa
"code review my diff"	gstack:/review + superpowers:requesting-code-review

This entry skill exists to route board-scoped intent — not to be the universal entry point for all sessions in this repo.

If you're working inside the board-superpowers repo itself

This plugin dogfoods: changes to its own skills / scripts / spec flow through the same Producer/Consumer board it ships to consuming repos. The board lives at the PanQiWei/board-superpowers GitHub Project. Treat plugin-maintenance work like any other Card claim.

The only exception is changes to the dogfood loop itself (the Self-hosting section in this repo's AGENTS.md, working-tree discipline, the routing block in this skill). Those may bypass the loop with direct PRs — circular dependency.

Cross-platform notes

Works on both Claude Code and Codex CLI. Routing logic uses only Tier 1 frontmatter. On Codex CLI, the SessionStart hook is wired via ~/.codex/hooks.json after running bash scripts/register-codex-hooks.sh --install-user once per Codex install.

Anti-pattern: routing that becomes work

If you find yourself writing procedure inline ("first do X, then do Y, then check Z"), STOP — that's downstream-skill territory. Route to (or ask the architect to create) the right skill instead. Entry-skill routing is one decision per turn, not a procedure.