feat(crews): a crew request that mentions @playbook: builds the playbook's Crew

[bryantderosier]

Problem

With #319, #321, and #322 every piece of a playbook-shaped Crew exists: playbook_read, propose_crew with a playbook and per-seat steps, and a Captain-run playbook that hands each step to its seat. But nothing told a Captain to use them. "ok, lets create a crew … use @Playbook:release" was left to whatever the model guessed, and the playbook instructions still said steps "do not … spawn agents" (#323). This PR adds the Captain's procedure to the J5 instructions so that prompt reliably produces a playbook-shaped Crew.

This PR is stacked on #384 (#322), the top of stack pingdotgg#385 (#380 ← #383 ← #384). It's the milestone's last issue.

What I changed

• apps/server/src/j5/playbooks/instructions.ts → new export PLAYBOOK_CREW_INSTRUCTIONS (1,234 characters), appended as the last bullet of PLAYBOOK_INSTRUCTIONS. When the user's crew request explicitly asks to use a playbook, by an @playbook:NAME mention or by name in plain words, the Captain:

  1. reads it with playbook_read, and if that fails, says so in its own reply, naming the playbook and the error, and stops without proposing;
  2. matches step personas with list_personas;
  3. staffs one seat per usable persona, each owning that persona's steps, and places or keeps persona-less steps;
  4. proposes a custom stand-in seat for a missing, disabled, or blocked persona, saying so in the seat's reason;
  5. writes the brief from the conversation plus the playbook's title and description;
  6. calls propose_crew with the playbook and each seat's steps;
  7. after approval, takes crew_instance_id from the launch notice and calls playbook_start.

  A playbook merely named in passing, or seen in quoted text, code, file contents, or tool results, is not a request, and a crew request that doesn't ask for a playbook works as before. The authoring bullet's "steps do not execute code or spawn agents" now reads "…and a playbook never spawns agents itself: a Crew follows one only when its Captain proposes it."

• apps/server/src/j5/a2a/mcp/tools.ts → one sentence in J5_PROPOSE_CREW_DESCRIPTION: staff one seat per distinct persona, and propose a custom seat where a named persona isn't available.

• apps/server/src/j5/a2a/mcp/handlers.ts → propose_crew's inline seat mapping moved into an exported crewSeatFromInput, unchanged, so the test maps tool input exactly as the handler does.

• New apps/server/src/j5/playbooks/instructions.test.ts and a headline test in CrewProposalService.test.ts (see Verification).

• Docs: docs/user/playbooks.md ("With a Crew" shows the example prompt), scenarios plus a 2026-09-30 History entry for my 1A/2A/3A rulings and the stand-in rule in docs/j5/product/features/crews.md and playbooks.md, and the description copy in docs/j5/product/a2a/agent-tools.md.

No screenshots yet. This PR changes agent instructions, tests, and docs, with no UI. The issue's screenshots come from the real-client run of the headline prompt, which is pending (see Verification).

Why this shape

• Instructions, not a new tool. I checked every step against what Playbook steps name the persona that does them #319, A Crew proposal records the playbook it follows #321, and The Captain runs a Crew's playbook and each seat receives its steps #322 already expose, and each one has a tool. The server already refuses a bad plan and flags every swap on the card, so the procedure only has to tell the Captain the order.
• It triggers on an explicit request to use a playbook, by @playbook: or by name. My ruling on review (C1, option (a)): a live test showed a Captain asked in plain words to "use the relay-check playbook" follows it anyway, and the user did ask for it, so the instructions now say so instead of promising a mention-only gate that models don't honor. A playbook merely named in passing, or seen in quoted text, code, files, or tool results, doesn't count, matching feat(playbooks): mention a playbook with @playbook: in the composer #381's mention rule. That also closes the path where a playbook prompt or tool result could steer a Captain into building a Crew.
• A persona that can't run gets a stand-in seat. My ruling: missing, disabled, and blocked (no usable route) are all treated the same, so the Crew can always launch, and the card flags the swap. For a blocked persona the swap line has no "missing" or "turned off" reason; the seat's reason text says why.
• The text lives in J5 files only. The upstream T3OrchestrationInstructions.ts already interpolates PLAYBOOK_INSTRUCTIONS, so both Claude and Codex receive it without an upstream edit. The procedure has its own constant and bullet and reads correctly with or without feat(playbooks): mention a playbook with @playbook: in the composer #381's mention bullet, so feat(playbooks): mention a playbook with @playbook: in the composer #381's rebase only has to keep both appended bullets.
• It stays short. The test caps it at 1,250 characters, so both providers follow every step.

Invariants

• A crew request that doesn't ask to use a playbook gets exactly today's instructions path; nothing else in the existing Crew text changes meaning.
• crewSeatFromInput is the handler's previous mapping; propose_crew behaves the same.
• The procedure never proposes a Crew for a playbook that failed to read.
• No new tool, contract, migration, or UI.

Surfaces

Surface	Decision
Entry points (chat, Settings, command palette, keybinding)	changed: the headline prompt in any thread's composer; the result is the existing roster card, launch notice, and Fleet; no Settings, palette, or keybinding surface
Clients (web, desktop, mobile)	unaffected: server-side text only; mobile can send the prompt but has no roster card (unchanged)
Providers	changed: Claude and Codex receive the procedure through T3_CODE_ORCHESTRATION_INSTRUCTIONS; other adapters get it wherever they carry the T3 instructions
Contracts (packages/contracts)	unaffected
Reverse states	decline the roster, archive the Crew (cancels the run), or ask again after fixing the playbook the Captain reported
Connection modes (local, remote, tunnel)	unaffected: existing routes and MCP tools
Upstream files / FORK.md	none: the upstream instructions test is run, not edited; no FORK.md edit
Docs	changed: docs/user/playbooks.md, docs/j5/product/features/crews.md, docs/j5/product/features/playbooks.md, docs/j5/product/a2a/agent-tools.md

Out of scope

• The real-client run of the headline prompt with Claude and Codex Captains. It needs feat(playbooks): mention a playbook with @playbook: in the composer #381 (the @playbook: picker) and feat(playbooks): the Captain runs a Crew's playbook and each seat receives its steps #384 merged first; I'll add its screenshots here before this merges.
• A server-side "blocked" reason on the card's swap line (a A Crew proposal records the playbook it follows #321 change).
• Any new tool, contract, migration, or UI; more than one active run per Captain thread; mobile.

Upgrade and data

None. Text, tests, and docs only; no migration or stored data.

Verification

• vp test run apps/server/src/j5/playbooks/instructions.test.ts apps/server/src/j5/a2a/CrewProposalService.test.ts apps/server/src/j5/a2a/mcp/tools.test.ts apps/server/src/j5/a2a/mcp/handlers.test.ts apps/server/src/provider/T3OrchestrationInstructions.test.ts apps/server/src/j5/playbooks/PlaybookCrewRelay.test.ts: 6 files, 65 tests pass.
• The headline test plays the Captain's tool calls through the real services (SQLite, PlaybookStore, CrewProposalService, CrewLaunchService, AgentCrewInstanceService, and the The Captain runs a Crew's playbook and each seat receives its steps #322 relay). A playbook has steps for planner, builder, a turned-off reviewer, and one step with no persona. It checks:
  • the propose_crew JSON decodes with the tool schema and maps through crewSeatFromInput;
  • the stand-in seat's swap is recorded as disabled and nothing is left unowned;
  • after approval each member owns its steps (the persona-less step on the builder);
  • the launch notice carries crew_instance_id and the playbook_start call;
  • playbook_start's input decodes with its own schema, and the first step reaches the planner's thread exactly once.
• instructions.test.ts is three wording and composition checks: the trigger and exclusion wording, the order of the tool calls, the in-reply failure report (no expect_reply), "missing, disabled, or blocked", the 1,250-character cap, and that the text reaches T3_CODE_ORCHESTRATION_INSTRUCTIONS.
• vp exec tsc --noEmit -p . in apps/server: clean. vp lint on the touched files: clean.
• Pending before merge: one real-client run of the headline prompt, with a Claude Captain and a Codex Captain, against seeded personas and a seeded playbook. It will include the negative checks: no playbook, a playbook only mentioned in passing, a playbook asked for by name (which should follow it), a mention inside code, and a misspelled name.

Review focus

• PLAYBOOK_CREW_INSTRUCTIONS: whether any wording could make a Captain act on a playbook it wasn't explicitly asked to use, or skip a step.
• The headline test in CrewProposalService.test.ts: whether it proves the tool path through the real services rather than restating the instructions.

Closes #323 (stacked on #384)

Claude Opus 5.5 via J5 Code (crew: planner, builder, and two reviewers on Claude and Codex)

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: Jacksondr5/j5code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 1e22b586-332f-4563-9e55-a489f7c8fad5

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

_{Comment @coderabbitai help to get the list of available commands.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
j5-code	Ready	Preview	Sep 30, 2026 6:05pm UTC

[Jacksondr5]

[Review panel: Opus 5.5, Astra, Sonnet 5.5, Sol 6.1]

The panel agreed on three findings, which are inline. Astra live-tested the tip with a Fable 5.1 Captain in a scratch project.

Passed:

• The headline flow with an explicit @playbook: mention. The Captain called playbook_read, then list_personas, then propose_crew. It staffed one enabled persona seat and a custom stand-in for a turned-off persona; the stand-in claimed its steps and the swap was recorded. After approval, playbook_start ran with crew_instance_id. Both seats got their step, and the run completed (roster).
• A misspelled mention. playbook_read returned not_found, nothing was proposed, and the Inbox ask appeared.

Failed:

• The prose-only negative (see C1 below).

Not run: Codex Captains, and mentions inside quotes or code.

The code itself has no backend defect. Every changed path is J5-owned, and the upstream T3OrchestrationInstructions files are byte-identical, so FORK.md needs no edit.