Consuming Card

consuming-card

Consumer-session skill: carries one card from claim through PR submit. All 23 lifecycle nodes are hosted here — stages F1-F4, bootstrap B1-B5, governance G1-G5, and cross-plugin handoffs C1-C4. Stage detail lives in the four references/stage-*.md files loaded on demand.

This SKILL hosts the 23 journey nodes (A1-A3, B1-B5, C1-C4, D1-D3, E1-E2, F1, G1-G5) per 04-consumer-surface-redesign.md archetype catalog as 4 stages × multiple nodes per stage. G1-G5 are cross-cutting governance nodes that apply uniformly across all stages; see § "G1-G3 — Governance" and § "G4 — Mode topology" below. G5 (cross-platform parity verification) tracks that both Claude Code and Codex CLI consumer paths are exercised for non-trivial cards. See references/migration-fc0-to-23-nodes.md for the full old-feature-code → 23-node mapping.

G4 — Mode topology (cross-cutting, applies to every stage)

Mode-1 (architect-spawned) — architect types [board-card:#N] or /board-superpowers:consuming-card N. Runs as the architect's primary session. Full tool budget; sub-skill spawning allowed at depth 1. Supported on both Claude Code and Codex CLI.

Mode-2 (Producer-spawned) — a Producer routine SKILL session (any of briefing-daily / intaking-requirement / reviewing-pr-queue / triaging-board) spawns this skill as a CC subagent via Agent tool. The subagent runs with isolated context and max_depth=1, meaning it CANNOT itself spawn further subagents. Every cross-plugin sub-skill invocation MUST be procedural (load the sibling SKILL.md into this agent's own context; do NOT call Agent again). Verify each sibling skill is procedural before invoking it from Mode-2 — consult board-superpowers:composing-siblings references/procedural-fallback-rules.md. Mode-2 is Claude Code only.

Mode-2 R-class callback protocol: A Producer-spawned Consumer cannot pause and ask the architect directly — the subagent context has no architect in the loop. When a mutating action is R-class in Mode-2:

1. The Consumer subagent prepares a structured proposal JSON.
2. The Consumer subagent calls report_agent_job_result with the proposal payload.
3. The Producer skill receives the result, evaluates it against

autonomy_overrides in /.board-superpowers/config.yml, and either acknowledges autonomously (if override allows) or surfaces to the architect.

1. On architect approval, the Producer re-spawns the Consumer subagent (new

isolated context) with an explicit "act on the previously-proposed action" prompt. The audit log records two entries: propose (written before step 2) and resolve (written after step 4's execution). This 4-step dance is expensive; cards selected for Mode-2 overnight-dispatch should have a high ratio of A-class actions. The subagent-spawn constraint is the max_depth=1 rule: a subagent already at depth 1 cannot itself spawn further subagents.

Mode-2 procedural fallback table (SKILL invocation is always safe; the risk is a sibling skill's body instructing an Agent spawn, which would push past the depth-1 budget):

| Sibling | Mode-2 safe? | If not safe | |---------|-------------|------------| | superpowers:writing-plans | Yes | n/a | | superpowers:test-driven-development | Yes | n/a | | superpowers:systematic-debugging | Yes | n/a | | superpowers:verification-before-completion | Yes | n/a | | superpowers:requesting-code-review | Verify first | If spawning: use gstack:/review only; surface gap as Retro Note | | superpowers:subagent-driven-development | procedural-verified (per composing-siblings/references/procedural-fallback-rules.md, dated 2026-04-26; re-verify on superpowers release) | n/a — safe if still procedural | | gstack:/review | Yes | n/a | | gstack:/investigate | Yes | n/a | | gstack:/qa | Yes | n/a | | gstack:/cso | Yes | n/a | | gstack:/codex | No | Mode-1 only; in Mode-2 ask architect to run it | | superpowers:dispatching-parallel-agents | NOT usable (Mode-2 itself runs as a subagent; spawning parallel subagents from within a subagent exceeds the depth-1 budget) | Raise to architect; do not invoke from Consumer Mode-2 |

Required sub-skills (atomic layer)

• board-superpowers:board-canon — canonical state machine + Card schema + branch naming + WIP rules.
• board-superpowers:operating-kanban — protocol-action dispatch: read_card (F1/F2 entry), claim_card (F1 claim transaction embedded in claim-card.sh), transition_card (F3 → Blocked / In Review), link_pr_to_card (F4 PR submit embedded in submit-pr.sh).
• board-superpowers:composing-siblings — cross-plugin handoff rules and Mode-2 compatibility check; invoke at every C1-C4 point.
• board-superpowers:enforcing-pr-contract — Contract A (PR three-section shape) + Contract B (AC terminal-state sync) at F4 submit.
• board-superpowers:classifying-actions — autonomy classification for every mutating action.
• board-superpowers:auditing-actions — audit row write after every A/R decision.

Stage F1 — Claim

Detailed procedure: references/stage-1-claim.md.

F1 summary (nodes A1-A3, B1-first):

1. Resolve card number: from $card_number arg, or $ARGUMENTS first token,

or parse #N from the prompt. Ambiguous → ask.

1. Read card via board-superpowers:operating-kanban action read_card.

Status MUST be Ready; unmet depends-on → stop, surface to architect.

1. Invoke board-superpowers:classifying-actions (action_id 100 — claim).

If R: propose → await architect ack → proceed.

1. Run bash scripts/claim-card.sh --owner --project --repo --card --title "". The script executes the 4-step claim transaction (branch push → Status flip to In Progress via transition_card). On failure: read stderr and surface.
2. Enter the worktree at $HOME/.config/superpowers/worktrees//claim/--. Do NOT return to repo root for work. See board-superpowers:board-canon § "Branch naming" for the canonical slug format.
3. Audit row via board-superpowers:auditing-actions (action_id 100).

Stage F2 — Implement (TDD-driven)

Detailed procedure: references/stage-2-implement.md.

F2 summary (nodes A3, B1-B5):

B1 — Plan synthesis: invoke board-superpowers:composing-siblings then delegate to superpowers:writing-plans. Turns the card's acceptance criteria into an executable TDD plan. (C1 handoff)

B2 — TDD mutation cycle: invoke board-superpowers:composing-siblings then delegate to superpowers:test-driven-development for Red → Green → Refactor. When stuck: superpowers:systematic-debugging or gstack:/investigate. (C2 handoff)

B3 — TDD-skip refusal: Do not bypass TDD even when implementation feels "obvious." The verification chain's integrity depends on every AC having a failing test first. This is a non-negotiable governance reflex.

B4 — Cross-card refusal: Edits are restricted to files claimed by this card. Refuse to modify infrastructure or files claimed by other cards without explicit architect authorization. Surface as R-class proposal if boundary crossing is genuinely necessary.

B5 — Permission-boundary: Every mutating action passes through board-superpowers:classifying-actions first. Do not bypass for convenience. R-class actions require architect acknowledgement before acting.

In-flight blocker (transition to Blocked): invoke board-superpowers:classifying-actions (action_id 103 — Consumer Blocked/terminate-failure), then board-superpowers:operating-kanban action transition_card with target Blocked. Comment on the card naming the blocker. Audit via board-superpowers:auditing-actions.

How every mutating action is handled:

1. Resolve action_id (catalog in board-superpowers:classifying-actions references/action-id-catalog.md).
2. Invoke board-superpowers:classifying-actions → receive A / R / N.
3. A: act → invoke board-superpowers:auditing-actions (1 entry).
4. R: audit propose → surface → await ack → on approve: act + audit resolve; on decline: audit decline + abort.
5. N: refuse, surface block reason.

Consumer action_id range: 100-113 (100-111 review cycle + 112 PR-submit pre-flight + 113 post-merge cleanup). Full catalog: board-superpowers:classifying-actions references/action-id-catalog.md.

Stage F3 — Verify

Detailed procedure: references/stage-3-verify.md.

F3 summary (nodes C1-C4, D3 rework):

Iron law: never open a PR without completing the full verification chain.

C1 — Verification chain: invoke board-superpowers:composing-siblings, then:

• superpowers:verification-before-completion (evidence-first; run actual checks named in ACs)
• gstack:/review (production-bug viewpoint)
• superpowers:requesting-code-review (independent second-pair-of-eyes)

All three required. None optional.

C2 — Cross-platform review (non-trivial cards): invoke board-superpowers:composing-siblings, then gstack:/codex (from CC). Mode-2: not possible from subagent; ask architect to run it. Skip for 1-line fixes.

C3 — Conditional QA: invoke board-superpowers:composing-siblings, then gstack:/qa for any UI-touching card (label or path heuristic). Mandatory when the card changes any user-visible surface.

C4 — Conditional security audit: invoke board-superpowers:composing-siblings, then gstack:/cso for cards with security label or body mentioning auth / crypto / PII.

Status transition to In Review: invoke board-superpowers:operating-kanban action transition_card with target In Review after verification chain completes and PR is ready to submit.

Common rationalizations to reject

| Rationalization | Reality | |-----------------|---------| | "Small change — verification is overkill" | Small changes hide gaps. Chain calibrated for smallest meaningful card. | | "Skip code-review, let the human reviewer do it" | Consumer hasn't reduced architect load — just passed it through. | | "Tests pass = done" | Name which tests, which edge cases, which integration points. |

Stage F4 — Submit PR

Detailed procedure: references/stage-4-submit.md.

F4 summary (nodes D1-D3, E1-E2):

D1+D2 — PR-submit pre-flight (action_id 112, A-class):

1. Toggle all AC checkboxes to [x] or [!]. Bare [ ] is forbidden.
2. If Notes invites a summary, append 3-5 line implementation summary.
3. Compute before/after SHA256 and gh issue edit --body-file .
4. Audit via board-superpowers:auditing-actions (action_id 112).

D1 — PR submit with three-section contract. Invoke board-superpowers:enforcing-pr-contract for templates. Then:

bash scripts/submit-pr.sh --title "" --body-file  --card 

The script validates Contract A (three-section shape) + Contract B (AC terminal state) before opening the PR. Retry with corrected body if validation fails. The script auto-appends the Closes # trailer — do NOT hand-add it or use gh pr create / gh pr edit --body-file directly (both strip the trailer, breaking the GitHub auto-close webhook chain). For post-OPEN body updates: bash scripts/submit-pr.sh --update-body --pr --body-file --card .

The link_pr_to_card protocol action IS bash scripts/submit-pr.sh for the github-project-v2 projection — the auto-trailer registers the PR↔Issue link.

D3 — Review-feedback rework loop: pull changes into the SAME worktree (do NOT create a new branch). Re-run F2 implement + F3 verify + F4 submit. Card stays In Review; re-pushing triggers re-review.

E1 — Post-merge cleanup (action_id 113, A-class):

1. Verify gh pr view --json state returns MERGED.
2. Verify card Status flipped to Done (webhook; 30 s typical; surface lag after 5 min).
3. Local cleanup: git worktree remove + git branch -d claim/.
4. Audit via board-superpowers:auditing-actions (action_id 113).

See references/stage-4-submit.md for the full Stage (a) / Stage (b) PR↔Issue link verification procedure and manual-recovery path.

E2 — Crash / failure path: surface partial state to architect via card comment; record a heartbeat audit row; leave the worktree intact for next-session pickup.

G1-G3 — Governance (cross-cutting reflexes)

G1 — Every mutating action produces an audit row via board-superpowers:auditing-actions.

G2 — R-class actions surface a propose-await before acting. Proposal records an audit entry; architect ack records a second entry.

G3 — A-class actions execute without interruption (no architect-visible gate). Both G2 + G3 use board-superpowers:classifying-actions as the single classifier.

v1.x roadmap stubs

Three SPOT-watchlist items deliberately kept inline (not extracted to atomics):

• scope-judgment (F1 stakeholder routing node) — extract when ≥2 callers emerge.
• mode-projection (G4) — extract when Producer overnight-dispatch ships (2nd caller).
• refusing-out-of-scope (B3 + B4 + B5) — extract when a 4th refusal node lands AND ≥3 share same-rhythm pattern.

References

| File | When to read | |------|-------------| | references/stage-1-claim.md | Full Stage 1 claim protocol detail (card read → claim transaction → worktree entry) | | references/stage-2-implement.md | Full Stage 2 implementation protocol (plan → TDD cycle → in-flight governance) | | references/stage-3-verify.md | Full Stage 3 verification chain detail (pre-PR checks + conditional passes + surface channels) | | references/stage-4-submit.md | Full Stage 4 PR submit + rework + post-merge cleanup detail | | references/post-merge-cleanup.md | Extended post-merge cleanup: four-part close-out contract + auto-cron path + failure modes | | references/migration-fc0-to-23-nodes.md | Archived mapping: old feature-grouped codes → 23-node journey encoding (historical reference for maintainers reading old PRs) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: PanQiWei
• Source: PanQiWei/board-superpowers
• License: MIT

Install and usage instructions live in the source repository linked above.