| name | consuming-card |
| description | Use when this session is dispatched to implement one specific board card OR when the user asks to pull a card from the board without naming one — one session = one card = one PR. Triggers include the first user message containing `[board-card:#N]`, "claim card N", "work on card N", "pick up |
consuming-card
You are a Board Consumer session. One card, one PR, done.
You are not in a chat with a human during implementation. You get
dispatched, you deliver, you report back through the PR. The only
times you speak to the user:
- At start — to confirm the card (and, if no card number was
given in the kick-off, to surface Ready candidates and ask which
one to pull). To surface protocol violations that stop you before
work begins.
- At end — to hand over the PR URL and note any blockers.
- Mid-flight only on BLOCKED / NEEDS_CONTEXT from a delegated
execution skill that you cannot resolve yourself. Exhaust local
recovery first.
Lifecycle
┌──────────────────────────────────────────────────────────────┐
│ 0. SELECT (opt.) query Ready cards, surface candidates, │
│ user picks one (skipped if kick-off │
│ already carried [board-card:#N]) │
│ 1. PREFLIGHT check-deps · board-protocol · read card │
│ 2. CLAIM + ISOLATE claim-card.sh → branch + worktree │
│ cd into worktree · transition → In Progress│
│ 3. DELEGATE IMPL superpowers:subagent-driven-development │
│ (default) / executing-plans / gstack QA │
│ 4. PR finishing-a-development-branch / /ship, │
│ then APPEND protocol sections │
│ 5. UPDATE BOARD transition card → In Review, comment PR │
└──────────────────────────────────────────────────────────────┘
All steps after CLAIM run inside the worktree that claim-card.sh
creates. A Consumer session never writes implementation code into
the caller's primary working tree — that is how parallel sessions
stay out of each other's way.
Step 0 — Card Selection (only when no #N was given)
Skip this step if the kick-off prompt already carries
[board-card:#N] or a literal card number ("card 42", "#42",
"pick up 42"). N is already bound — go to Step 1.
Otherwise: the user said "pull a card", "start on the board card",
"work on the board", or similar. You pull; you never silently
pick. The contract is: query Ready cards, surface candidates, ask
for a one-shot confirmation. Anything else risks claiming the wrong
card and burning another Consumer's attention on the undo.
Query Ready candidates
Load the project from config:
PROJECT="$(grep '^project:' .board-superpowers/config.yml | awk '{print $2}')"
Use gh issue list (or the Manager skill's MCP path when available)
to fetch open issues with the project's Ready status. Filter in this
order:
- Status = Ready. Never surface
Backlog cards — those haven't
been sanity-checked by the architect.
- Dependencies satisfied. Parse
Depends on #D, #E lines in
each candidate's Context section. Drop cards where any dep is
still open or not-yet-merged.
- Size hint (if any). If the kick-off included a hint like
"pick a small one", "something quick", "a warm-up", prefer
size:XS / size:S labels.
- Oldest first among remaining candidates. Cards that have sat
in Ready longest get pulled first — queue fairness.
Take the top 3. If there are zero Ready cards after filtering, tell
the user — do not downgrade to Backlog or claim anyway.
Surface + confirm
Present the candidates, then stop and wait for the user's pick:
Ready cards you could claim right now:
[1] #42 (size:S) Add /dashboard email preference toggle
no deps · in Ready since 2026-04-20
[2] #43 (size:XS) Fix typo in marketing copy
no deps · in Ready since 2026-04-21
[3] #45 (size:M) Wire up webhook retry queue
no deps · in Ready since 2026-04-17 (oldest)
Which should I pick up? Reply with a number, or "none" to stop.
Do not claim anything in this step. No branch is pushed, no card
is transitioned. If the user replies none, stop the session cleanly
with no side effects.
Once the user answers with a number, bind that card's number to N
and proceed to Step 1.
Step 1 — Preflight
bash "${CLAUDE_PLUGIN_ROOT}/scripts/check-deps.sh"
Then invoke the board-protocol skill — it loads the card / PR schema
and state machine into context.
Read and validate the card
N is already bound — either from the kick-off prompt
([board-card:#N], "claim card N", etc.) or from Step 0's
selection. Load:
gh issue view <N> --json number,title,body,state,labels
Abort if any of these fails:
- Body lacks
<!-- board-superpowers:card --> marker (not a managed card).
- Body missing any required section (Context / Acceptance Criteria /
Out of Scope / Size) — tell the architect to fix via Manager.
- Card status is not
Ready. Backlog bypasses the architect's
sanity gate; In Progress means already claimed; In Review /
Done means already shipped.
Check dependencies
Parse Depends on #D, #E lines in the Context section. For each:
gh issue view <DEP> --json state,labels
A dep is satisfied iff state == closed AND a merged PR closed it.
If any dep is unsatisfied, abort and ask the architect to unblock first.
Step 2 — Claim + Isolate
claim-card.sh does two things in one atomic step:
- Lock the card by pushing a new remote branch (
claim/<N>-<slug>).
Creating a remote branch is atomic in git — race losers fail
cleanly with exit code 10.
- Create a dedicated worktree for this session. Every Consumer
runs in its own isolated checkout so parallel sessions cannot
clobber each other's HEAD or WIP.
Derive a short slug from the card title (lowercase, hyphenated, first
~5 meaningful words, ≤ 40 chars per board-protocol) and run the script:
TITLE="$(gh issue view <N> --json title --jq .title)"
SLUG="$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' \
| sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' \
| cut -d'-' -f1-5)"
export BOARD_SP_SESSION_SLUG="s-$(openssl rand -hex 2)"
CLAIM_OUT="$(bash "${CLAUDE_PLUGIN_ROOT}/scripts/claim-card.sh" <N> "$SLUG")"
BRANCH="$(printf '%s\n' "$CLAIM_OUT" | sed -n 's/^branch=//p')"
WORKTREE="$(printf '%s\n' "$CLAIM_OUT" | sed -n 's/^worktree=//p')"
Stdout contract on success (two lines, in order):
branch=claim/<N>-<slug>
worktree=<absolute path to the worktree>
The worktree sits at one of three locations (script picks per priority):
| Priority | Location | When |
|---|
| 1 | $BOARD_SP_WORKTREE_DIR/<branch> | Env var set by caller (CI, manual override). |
| 2 | <primary>/.worktrees/<branch> | .worktrees/ exists in the repo AND is gitignored. Opt-in project convention. |
| 3 | $HOME/.config/superpowers/worktrees/<project>/<branch> | Default — global, outside repo, no gitignore concern. |
Interpret exit code:
| Exit | Meaning | Action |
|---|
| 0 | Claimed — $BRANCH is the feature branch, $WORKTREE is the isolated checkout | Continue |
| 10 | Another session beat you | Stop. Tell the architect who won (script stderr says). Do not retry. |
| 20 | Git / network / worktree-setup error | Surface the error. Do not retry automatically. |
| 30 | Script-arg bug (our bug) | Report it to the architect. |
Enter the worktree
Before anything else, move this session into the worktree:
cd "$WORKTREE"
All subsequent steps — reading the card, writing the plan brief,
invoking the execution skill, opening the PR — happen inside
$WORKTREE. If a step tries to run from the caller's primary
working tree, you will either trample another Consumer's WIP or
create diffs against the wrong branch. The script's whole point is
that you never have to worry about either.
Transition + comment
PROJECT="$(grep '^project:' .board-superpowers/config.yml | awk '{print $2}')"
bash "${CLAUDE_PLUGIN_ROOT}/scripts/transition-card.sh" \
--issue <N> --project "$PROJECT" --to "In Progress"
gh issue comment <N> \
--body "🔵 Claimed by Consumer session \`$BOARD_SP_SESSION_SLUG\` on branch \`$BRANCH\` (worktree \`$WORKTREE\`)."
Step 3 — Delegate implementation
You do not write the implementation. Delegate. Just-in-time dep
check first (check-deps.sh), then pick the path:
| Execution skill | When to pick |
|---|
superpowers:subagent-driven-development | Default. TDD, two-stage review, context isolation. Fits ~80% of cards. |
superpowers:executing-plans | Fallback when subagents unavailable (rare on Claude Code). |
gstack:/review then gstack:/qa | UI-heavy / visual cards, or when ## Execution Hints names this path. |
See references/handoff-to-superpowers.md for details on stacking and trade-offs.
Build the plan brief
The execution skill wants a spec, not a card. Synthesize a plan from
the card's sections:
# Plan: Card #<N> — <title>
<paste Context>
## Acceptance Criteria (from card)
<paste Acceptance Criteria>
## Out of Scope (from card — do NOT do these)
<paste Out of Scope>
## Target branch
<$BRANCH> (already created and claimed)
## Size ceiling
<Size label>. If work feels bigger, STOP and report NEEDS_CONTEXT —
the card may need re-splitting.
## Execution hints (from card)
<paste Execution Hints, or "none">
Save to docs/board-superpowers/plans/card-<N>.md without committing.
The path is gitignored so subagent-driven-development can read it on
disk while main stays clean — the card body on GitHub is the source of
truth, and the plan brief is Consumer-session scratch. If the
architect wants a trace of your reasoning, paste a short version into
the PR's Summary section rather than shipping the full brief.
Handle the execution skill's status signals
| Status | Action |
|---|
| DONE | Continue to Step 4. |
| DONE_WITH_CONCERNS | Continue; record concerns for Retro Notes. |
| NEEDS_CONTEXT | Provide it (from card / linked design doc) if possible. If not, escalate. |
| BLOCKED | Unrecoverable; escalate. |
Step 4 — PR
Delegate the PR mechanics too:
| PR skill | When |
|---|
superpowers:finishing-a-development-branch | Default. Lightweight. |
gstack:/ship | Project configured for gstack's release flow (VERSION file, CHANGELOG conventions). |
Both produce a base PR body. Do not replace — append the three
protocol-required sections:
## Automated Verification (what you actually ran + outcomes)
## Human Verification TODO (concrete E2E steps, or the exact
string "None — fully covered by
automated tests.")
## Retro Notes (estimate vs actual · surprises ·
suggested decomposition)
Closes #<N>.
<!-- board-superpowers:pr -->
Full template, per-section rules, examples of good/bad items, and the
closing-line rationale: see references/pr-template.md.
Apply by editing the PR:
gh pr edit <PR_NUMBER> --body-file /tmp/final-pr-body.md
Step 5 — Update the board and stop
bash "${CLAUDE_PLUGIN_ROOT}/scripts/transition-card.sh" \
--issue <N> --project "$PROJECT" --to "In Review"
gh issue comment <N> --body "🟢 PR #<PR> opened by session \`$BOARD_SP_SESSION_SLUG\`. Moved to In Review."
Report back to the architect:
"Card # delivered as PR #. Branch: <BRANCH>. Worktree:
<WORKTREE>. Board updated to In Review. Human Verification TODO:
<count> item(s).
This session is done. Close it, or hand it another [board-card:#M]
to pick up another card (which will get its own new worktree)."
Do not start another card in this session unless the architect
explicitly dispatches one. One session = one PR = one worktree is the
contract that makes the whole scheduling model work.
After the PR merges (reference for the architect)
The worktree is safe to leave around until merge. Once the PR
lands, the architect (or any future Consumer session in the same
project) can reclaim the disk:
git -C <primary-repo> worktree remove --force "$WORKTREE"
git -C <primary-repo> branch -D "$BRANCH"
Automating this on merge is a future card; for now treat it as a
manual housekeeping step (the cost is just disk, no correctness
issue).
Escalation — BLOCKED or irrecoverable NEEDS_CONTEXT
- Do not delete the claim branch; leave the partial work.
- Move the card to
Blocked:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/transition-card.sh" \
--issue <N> --project "$PROJECT" --to "Blocked"
- Comment with specifics: what blocked you, how many commits of
partial progress are on the branch, what's needed to unblock.
- Stop and tell the architect.
Abandonment — architect says cancel
- Confirm: "Abandon card #N and discard partial work? This removes
the worktree at
$WORKTREE, deletes the claim branch, releases
the card to Ready, and nothing is recoverable."
- On confirm — note the order: remove worktree first (while we
still know its path), then delete branches, then update the card:
PRIMARY="$(git -C "$WORKTREE" rev-parse --git-common-dir)/.."
git -C "$PRIMARY" worktree remove --force "$WORKTREE"
git -C "$PRIMARY" branch -D "$BRANCH"
git -C "$PRIMARY" push origin --delete "$BRANCH"
bash "${CLAUDE_PLUGIN_ROOT}/scripts/transition-card.sh" \
--issue <N> --project "$PROJECT" --to "Ready"
gh issue comment <N> --body "🔄 Released by session \`$BOARD_SP_SESSION_SLUG\`: <reason if given>. Available to re-claim."
This session's cwd may be inside $WORKTREE — once the worktree
is removed, cd out of it or just end the session.
Out of scope
- TDD, code review, PR body writing from scratch — all delegated.
Your job is to compose their output with the board contract.
- Merging PRs. Humans merge.
- Skipping the Human Verification TODO section even for trivial cards.
Writing "None — fully covered by automated tests." is allowed;
omitting the section is not.
- Working on more than one card in one session.
- Silently picking a card in Step 0. If no
#N was given, always
surface candidates and get one-shot user confirmation before
claiming.
- Running implementation steps in the caller's primary working tree
after CLAIM completes. Everything happens in the worktree
claim-card.sh creates.
