docs(pipeline-crew): plugin How-to — add a role · configure personalization · reboot · carry a §CP PR · retire a crew

[usirin]

What

Authors the How-to Diátaxis quadrant for the pipeline-crew plugin surface: claude-plugins/pipeline-crew/HOW-TO.md, beside REFERENCE.md / EXPLANATION.md / PERSONALIZATION.md. Single-mode, task-oriented (precedent: Wave 3B split, #3392).

Five goal-focused recipes against a running crew:

• Add a role — /spawn-role a scaled engine or the HITL cartographer; the roster-law cardinality rule; adding a brand-new role kind is a config + runtime change.
• Configure personalization — fill the placeholder-only crew.config.jsonc from the template; change a dimension later; the optional cliVersion pin.
• Reboot the crew — one member (retire-role + spawn-role) or the whole crew (stand-down + stand-up); a reboot is how a config edit takes effect; no partial crew.
• Carry a §CP PR — the current approve-then-enqueue model (ADR 0135): engine banks → chief-of-staff relays to the approver → approval at the current head → engine spawns the approval-aware shipper to enqueue → confirm it landed (QUEUED ≠ MERGED). No stale maintainer-hand-merge language.
• Retire a crew — retire-role one member or stand-down the whole crew; drain in-flight lanes first.

Each recipe links into the plugin Reference and Explanation rather than re-deriving roster law or the §CP gate.

Surface separation

• No cross-links into the pipeline-crew-mcp package docs tree — all links stay within the plugin dir (README/REFERENCE/EXPLANATION/PERSONALIZATION, commands/) plus ADR pointers. Substrate CLI subcommands (stand-down, retire-role) are referenced by command name, consistent with how the README/commands already reference the substrate.

README wiring (minimal, localized)

• Added the HOW-TO.md Layout-tree row and one See-also link only — no reorder/reformat of existing rows, to minimize conflict with the concurrent Tutorial PR (Diátaxis: pipeline-crew Tutorial — stand up your first crew (zero → live crew draining the board) #3567) editing the same README.

Merge model

Non-control-plane docs PR (crew surfaces are non-§CP by design) — ships on green, no bank.

Fixes #3566

[usirin]

review-code: PASS @ 7bdb45b — merge-ready

Verified PR #3611 against the acceptance criteria of #3566, one at a time:

• [PASS] Single-mode How-to doc covering all five recipes — claude-plugins/pipeline-crew/HOW-TO.md lands with a Diátaxis mode: how-to banner ("One mode per doc") and five goal-focused recipe sections: ## Add a role, ## Configure personalization, ## Reboot the crew, ## Carry a §CP PR, ## Retire a crew. Grounded in the shipped substrate — the four crew agent defs (agents/crew-*.md), crew.config.template.jsonc (copy-the-template step), and PERSONALIZATION.md (the seam these recipes fill). Single-mode-per-doc house style per precedent Wave 3B — Split the three fused docs by Diátaxis mode #3392.
• [PASS] "Carry a §CP PR" recipe reflects the current approve-then-enqueue model (ADR 0135), not stale hand-merge language — verified against .decisions/0135-hard-gate-control-plane-team-codeowners-approve-then-enqueue.md: engine banks the PR → chief-of-staff relays to the approver → approval at the current head (rebase/force-push un-binds it) → author cannot self-approve (needs the other control-plane human) → the engine spawns the approval-aware shipper which enqueues → confirm it landed (QUEUED ≠ MERGED). Explicit "Humans approve; they never hand-merge." No maintainer-hand-merge language present.
• [PASS] Each recipe links into Reference/Explanation instead of duplicating them; surface separation holds (no package cross-links) — every link target resolves at head: README.md, REFERENCE.md, EXPLANATION.md, PERSONALIZATION.md, commands/spawn-role.md, commands/stand-up.md all exist; heading-slug anchors into REFERENCE/PERSONALIZATION/README resolve. No links into the pipeline-crew-mcp package docs tree, no packages/ or ../ paths — every pipeline-crew-mcp … reference is a bare substrate-binary command name in a code block (consistent with the README). README wired minimally: one Layout-tree row + one See-also link added, no reorder.

Notes:

• No user-local/absolute paths — the doc uses ${CLAUDE_PLUGIN_ROOT} and repo-relative .claude/crew.config.jsonc.
• The three EXPLANATION.md#cp-gate / #verify-dont-relay / #roster-law fragment anchors target {#id} custom anchors that GitHub does not honor — but these are a pre-existing property of EXPLANATION.md (present at those headings before this PR), not introduced here. The FILE target resolves, which is the bar for Diátaxis: pipeline-crew How-to — add a role · configure personalization · reboot · carry a §CP PR · retire a crew #3566; the {#id} rendering is a candidate follow-up against EXPLANATION.md, not a defect of this PR.

Run-evidence bundle: N/A — docs-only PR (two *.md files under claude-plugins/pipeline-crew/); no code behavior to typecheck/test. Verified from the diff + files read at head.

Read the PR head (§HEAD): all files under review sourced from 7bdb45b74c5ab81faf57194088ee40be6992593c via git cat-file -p <sha>:<path>, never the launched checkout's working copy. Non-§CP (crew surfaces are outside the §CP boundary by founder ruling).

All criteria pass. This PR is merge-ready. review-code does not merge — ship-it is the authorized merge step; merging will auto-close #3566 via Fixes #3566.