Skip to content

A Crew proposal records the playbook it follows #321

Description

@bryantderosier

My rule: a Crew built from a playbook remembers which playbook it follows, and each seat knows which steps it owns. You approve that plan on the roster card, not just a list of people.

Where it stands today:

  • propose_crew takes name, brief, and seats of { seat, persona?, reason, instructions?, model_selection?, runtime_mode? } (apps/server/src/j5/a2a/mcp/tools.ts → J5ProposeCrewInput, J5CrewSeatInput). Nothing links a Crew to a playbook.
  • j5_agent_crew_proposal, j5_agent_crew_instance, and j5_agent_crew_member (migrations/014_AgentCrews.ts) have no playbook or step columns.
  • The roster gate (apps/web/src/j5/crew/CrewRosterGate.tsx, CrewProposalCard.tsx) shows seats, reasons, and resolved runtime.

What should change:

  • Tool input: propose_crew takes optional playbook (a definition name in the Captain's workspace). Each seat takes optional steps, a list of step ids it owns. request_crew_member takes steps too, so an added seat can pick up unowned steps (The Captain runs a Crew's playbook and each seat receives its steps #322).
  • Validation at propose time: the server reads the live definition. An unknown playbook, an invalid definition, or a step id that isn't in it is refused with a next step. A step claimed by two seats is refused. Steps nobody owns are allowed but reported back, so the Captain can decide.
  • One run per Captain thread: propose_crew with a playbook is refused while the Captain's thread already has an active playbook run (runs allow one active per owner thread), with a next step naming the run to finish or cancel. Crews without a playbook are unaffected. Lifting this limit is out of scope. This moved here from The Captain runs a Crew's playbook and each seat receives its steps #322 so every propose-time refusal lives in one validator and this issue can ship without letting a second playbook Crew collide with a live run.
  • Persona swaps are visible: when a step names persona X and the seat that owns it isn't X (a custom seat or a different persona, because X is missing or disabled), the proposal records the swap and the card flags it on that seat. Read the definition through Playbook steps name the persona that does them #319's playbook_read path and judge personas with the checks CrewProposalService already runs, so a swap here matches Playbook steps name the persona that does them #319's warning.
  • Storage: a J5 migration adds the playbook name and definition path to the proposal and instance, and each member's step ids. Existing rows get nulls and behave exactly as today.
  • Roster card (web and desktop): shows "Follows playbook: <title>", each seat's steps by title, unowned steps, and swap flags. Editing a seat in CrewSeatDialog keeps its steps; removing a seat moves its steps to unowned, and the card says so before you approve.
  • Launch: each seat's first turn (CrewLaunchService.startBriefs → spawnFirstTurnText) names the playbook and lists the steps it owns by id and title, so a seat knows its part before the run moves.
  • Reads: the crew reads the Fleet page uses (AgentCrewReadsHttp.ts, FleetReadsHttp.ts) return the playbook and per-seat steps.
  • Docs: the Crews section of docs/user/personas.md and docs/j5/product/features/crews.md (Launch and the gate).

Tests to ship:

  • propose with a playbook and step ownership persists and reads back on proposal, instance, and members
  • unknown playbook, invalid definition, unknown step id, and double-claimed step are each refused with a next step
  • a playbook proposal from a Captain with an active run is refused and names that run; a proposal without a playbook still goes through
  • a persona swap is recorded and reaches the card's read model
  • a proposal without a playbook is unchanged, and old rows migrate to nulls
  • the launch brief lists each seat's steps

Done when the roster card shows the playbook plan and approval records it on the Crew.

Surfaces: mobile has no Crew roster or Fleet UI today, so nothing changes there. Remote and tunnel clients read the same J5 routes.

Upstream footprint: none. The tool input, validation, migration, roster card, launch brief, and reads are all J5-owned.

Follows #319.

Activity

  1. added this to the Crew playbooks milestone on Sep 25, 2026
  2. added
    size:L100-499 effective changed lines (test files excluded in mixed PRs).
    on Sep 25, 2026
  3. added a commit that references this issue on Sep 30, 2026
    a6fe6c3
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

size:L100-499 effective changed lines (test files excluded in mixed PRs).

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions