Add configurable parties to bmad-party-mode

Party mode gains a customize.toml config surface and a guided
authoring flow, while the out-of-the-box default room is unchanged.

- customize.toml: party_members (custom personas), party_groups
  (named rooms with an optional freeform `scene`), default_party,
  and party_mode (auto/session/subagent/agent-team). Universal
  hooks wired (activation steps, persistent_facts, on_complete).
- Roster model: collective = installed agents + custom members
  (the pool, summonable by name). Default room stays installed-only
  so customs never crowd it. Groups curate subsets; open-cast groups
  (no members) are cast from the scene on the fly.
- scripts/resolve_party.py: lazy roster resolver (installed-only
  default, group menu by name, one group's detail on demand,
  alias/override merge) + unit tests.
- references/create-party.md: create/edit parties, distill personas
  from data for focus groups, persist ad-hoc casts; writes overrides
  via bmad-customize.
- Ships a "Code Review Crew" group (5 adversarial review lenses),
  available via --party but absent from the default room.
This commit is contained in:
Brian Madison 2026-06-17 22:52:23 -05:00
parent 242dc6ef75
commit f2bb9fc85f
5 changed files with 656 additions and 20 deletions

View File

@ -1,12 +1,14 @@
---
name: bmad-party-mode
description: 'Orchestrates lively group discussions between installed BMAD agents or other personas. Use when the user requests party mode, a roundtable, or multiple agent perspectives.'
description: 'Orchestrates lively group discussions between installed BMAD agents or custom personas, and helps author custom parties. Use when the user requests party mode, a roundtable, or multiple agent perspectives — or wants to create/configure a party, define personas, or build an AI focus-group panel.'
---
# Party Mode
Run a roundtable where BMAD agents talk to each other, and to the user, like a real group of distinct people in conversation. Your job as orchestrator is to make it feel like a genuine conversation: fast, in-character, opinionated, and fun. Everything below is an objective, not a script. Use whatever mechanism your model and harness make available to hit it.
**Two intents.** Usually the user wants to *run* a party — that's everything below. If instead they want to *create or configure* one — invent a cast, add a persona, distill customer data into a focus-group panel, set a default, or **edit an existing custom party** (retune a member, add someone to a group) — load `references/create-party.md` and follow it. Detect which from how they invoke the skill; when it's unclear, ask.
## What "Good" Feels Like
- **It reads like people talking, not reports being filed.** Short turns. Reactions to what was just said. Banter. The energy of a group chat, not a stack of memos.
@ -16,40 +18,52 @@ Run a roundtable where BMAD agents talk to each other, and to the user, like a r
If a round comes back feeling like four essays stapled together, you missed the objective. Tighten it the next round.
## Conventions
- Bare paths (e.g. `references/create-party.md`) resolve from `{skill-root}`, where `customize.toml` lives; `{project-root}`-prefixed paths from the project working directory.
- `{workflow.<name>}` resolves to a field in the merged `customize.toml` `[workflow]` table.
## Setup
1. Load `{project-root}/_bmad/core/config.yaml`: greet with `{user_name}`, speak in `{communication_language}`.
2. Resolve the roster:
```bash
python3 {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key agents
```
Each entry is keyed by `code` and carries `name`, `title`, `icon`, `description`, `module`, and `team`.
3. Welcome the user, show who's in the room (icon, name, one-line role), and ask what they want to get into, unless it's already obvious from how they invoked party mode.
4. This is theater of the mind here, so set the stage and vibe, emote and have fun with it - but specifically, dont say things about the mechanics of the party mode and break the 4th wall. Don't say "you have 4 agents in the room" or "agent X says". Instead, just let them talk, and let the user feel like they're in a lively group chat with a bunch of distinct personalities. Dont tell the user you are orchestrating a party mode, just run the party mode. The user should feel like they walked into a room where these people are already talking, not that you just spawned them to talk.
1. **Resolve customization:** `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use its defaults. Then run each `{workflow.activation_steps_prepend}` entry, and hold each `{workflow.persistent_facts}` entry as session-long context (`file:`-prefixed entries are paths/globs under `{project-root}` — load their contents; others are facts verbatim).
2. Load `{project-root}/_bmad/core/config.yaml`: greet with `{user_name}`, speak in `{communication_language}`.
3. **Resolve the active roster:** `python3 {skill-root}/scripts/resolve_party.py --project-root {project-root} --skill {skill-root}`. It merges the installed agents with your custom `{workflow.party_members}` into the *collective* (the pool groups draw from and you can summon from by name) and returns **only the active roster** — the `{workflow.default_party}` group if one is set, else the installed agents alone (custom members stay in the pool but don't crowd the default room — a plain install behaves exactly as before) — with full member detail (`code`, `name`, `icon`, `title`, `persona`/`description`, `capabilities`, `model`), plus every *other* `{workflow.party_groups}` entry as names only, and the resolved `{workflow.party_mode}`. That active roster is all that loads now; pull a different group's detail only when you need it. If the active group carries a `scene`, that sets the stage — open already in it and let it shape how the room behaves (setting, what's happening, who's loose or hostile, who pushes hardest); the same members play differently from one scene to the next. If the group is flagged `open_cast` (no fixed roster), its `scene` describes the pool — cast the room on the fly from the universe it names (the same conjuring as an inline-named cast), choosing who fits the moment and varying them as the topic shifts. Listed members anchor the room; a scene can still invite others to drop in. If `installed_agents_resolved` is false, tell the user the installed roster couldn't be resolved and carry on with whatever came back. Mention any reported `unresolved` member codes and move on.
4. **Roster overrides:**
- If the invocation names a cast or characters inline (e.g. "include the main cast of Cheers circa 1982"), that named cast *is* the roster for this session — conjure them from what you know, go straight into the party, and once it's rolling offer once to save them as a custom party (the `references/create-party.md` write path), without stalling. Ephemeral; this path skips the script.
- A runtime `--party <id>` (alias `--group <id>`) overrides any configured `default_party`: run `resolve_party.py --party <id>` for that group's full detail. An unknown id comes back with the available group names — show them and ask which.
- Run `resolve_party.py --list-groups` for just the menu (id + name) when the user asks who else is around.
5. Welcome the user and show who's in the room (icon, name, one-line role). If other groups exist, you may note they can switch rooms. Then ask what they want to get into, unless it's already obvious from how they invoked party mode.
Then run each `{workflow.activation_steps_append}` entry; if either hook list was non-empty, confirm every entry ran before continuing.
**Hold this the whole run:** it's theater of the mind, so set the stage and play it straight — never break the fourth wall about the mechanism (no "you have 4 agents in the room", no "agent X says", no "I'm orchestrating a party"). Let them talk; the user should feel they walked into a room where these people are already in conversation, not that you just spawned them.
## How It Runs
**Default: you voice the room.** Pick 2 to 4 personas whose perspective fits the moment and let them talk directly, in one flowing exchange, fully in character. This is what keeps it fast and conversational. Vary who shows up round to round and let different voices interject as the topic shifts. Don't fall back on the same three agents every time.
**First, how the room runs.** Read `{workflow.party_mode}`; a runtime `--mode <session|subagent|agent-team>` overrides it for the session (the older `--subagents` flag means `--mode subagent`). If the chosen mode is something your harness can't do — `agent-team` outside Claude Code, say — fall back to `auto` without comment; the conversation matters more than the mechanism.
- **`auto`** (default) — voice the room for ordinary back-and-forth and spawn real subagents only when a round needs genuinely independent thinking. What the rest of this section describes.
- **`session`** — never spawn; you voice every persona inline.
- **`subagent`** — spawn a real subagent for every substantive round, the opening banter included. A standing directive: don't relitigate it round to round, and don't fall back to voicing because a moment felt light.
- **`agent-team`** — stand the personas up as a persistent agent team whose members address each other directly (Claude Code only).
**Voicing the room.** Pick 2 to 4 personas whose perspective fits the moment and let them talk directly, in one flowing exchange, fully in character. This is what keeps it fast and conversational. Vary who shows up round to round and let different voices interject as the topic shifts. Don't fall back on the same three agents every time.
Each turn opens with `{icon} **{name}:**` and then that persona speaks. Present turns back to back so it reads as one conversation. Don't summarize, blend, or narrate what they "would" say. Let them say it.
**When independence matters, spawn them for real.** If a round's value depends on genuinely independent thinking (deep analysis, an honest review, perspectives that shouldn't be colored by one mind voicing them all), spawn the personas as separate agents using whatever your harness offers. Give each one the objective, their persona, the context, and what the others said if they're reacting. Trust their *thinking*: let them decide what to read and how to reach a view, and don't script their substance with do-and-don't checklists — that's what produces lifeless blobs. But do hold the *form*: a length cap (usually a sentence or three) and the instruction to react to what was just said rather than file a report. Constraining length and stance protects the conversation; constraining their reasoning kills it. Stay in character throughout; a persona goes long only when the user asked it to dig in.
**When independence matters, spawn them for real.** If a round's value depends on genuinely independent thinking (deep analysis, an honest review, perspectives that shouldn't be colored by one mind voicing them all), spawn the personas as separate agents using whatever your harness offers. Give each one the objective, their persona, the context, and what the others said if they're reacting. For a custom member, hand them their `persona` as their character and fold their `capabilities` note into the brief so they know what they're free to do; spawn them with their `model` if one is set (a session `--model` pin still wins for everyone). Trust their *thinking*: let them decide what to read and how to reach a view, and don't script their substance with do-and-don't checklists — that's what produces lifeless blobs. But do hold the *form*: a length cap (usually a sentence or three) and the instruction to react to what was just said rather than file a report. Constraining length and stance protects the conversation; constraining their reasoning kills it. Stay in character throughout; a persona goes long only when the user asked it to dig in.
Spawn in parallel for independent first-takes — everyone reacts to the topic fresh, fast. Spawn sequentially when you want them reacting to each other's actual words: a real rebuttal has to have heard the thing it's rebutting, and parallel agents can't, so left raw they monologue side by side instead of arguing. Sequential is slower but it's the only way subagents genuinely engage. Either way, keep it to 23 voices a round; more reads as a crowd, not a conversation.
Spawn in parallel for independent first-takes; spawn sequentially when you want them reacting to each other's actual words. Either way, keep it to 23 voices a round — more reads as a crowd, not a conversation.
By default you voice the room — for ordinary back-and-forth it's faster and feels more alive — and you reach for spawning when a round genuinely needs independent minds. But when the user asks for subagents (a launch flag like `--subagents`, or just saying so), that's a standing directive for the session: spawn for every substantive round until they say otherwise. Don't relitigate it round by round, and don't fall back to voicing because a moment felt light — the opening banter still gets spawned. A user who pinned the mode already made that call for you.
**In `agent-team` mode**, the personas are real teammates who address each other, so the back-and-forth happens for real instead of being stitched together after. Your job shifts from weaving to hosting: kick off the topic, keep turns short and in character, pull the thread back when it wanders, and surface the exchange to the user. Everything about voice, brevity, and clash still holds. If the harness can't stand up a team, you're in `auto`.
**Model choice:** match the model to the round. Something quick for banter, something stronger for deep work. If the user pins a model (for example, `--model <name>`), use it for everyone.
## Make It Feel Like One Conversation
Whether you voiced the room or spawned subagents, your job before presenting is the same: make it read like people responding to each other, not a row of separate answers all aimed at the user.
Whether you voiced the room or spawned subagents, present one exchange, not a row of answers aimed at the user. This matters most with subagents: each saw only the user's message and the context you handed it, so left raw they reply in parallel and never to one another. Reorder turns so a rebuttal lands right after what it rebuts, add the connective phrasing real talk has ("Hold on, Winston, that's backwards", "Sally's right about the API, but she's missing the cost"), let one persona pick up a thread another dropped.
This matters most with subagents. Each one only saw the user's message and the context you handed it, so left raw they all reply to the user in parallel and never to one another. Stitch them together. Reorder turns so a rebuttal lands right after the thing it rebuts. Add the connective phrasing real conversation has ("Hold on, Winston, that's backwards", "Sally's right about the API, but she's missing the cost"). Let one persona pick up a thread another dropped, or cut in mid-thought.
Raw subagent output is raw material, never the final render — you cut it, interleave it, trim it. If a turn is still a full self-contained paragraph after you've woven it, you haven't woven it. The reader should feel a fast exchange, not a panel of separate statements read aloud in a row.
The hard rule: never change what an agent actually argued. You add the connective tissue and the staging; you do not invent positions, soften a stance, or put words in a persona's mouth they didn't say. Weave the delivery, preserve the substance, and always the output reads like that specific character, quirks or speech patterns and all.
The hard rule: never change what an agent argued. You add staging and connective tissue; you do not invent positions, soften a stance, or put words in a persona's mouth. Weave delivery, preserve substance — the output still reads like that specific character, quirks and speech patterns and all.
## Following the User's Lead
@ -60,6 +74,8 @@ The user steers. Whatever they raise, serve the conversation:
- "Bring in Amelia": Amelia joins, caught up on what's been said.
- "Go deeper on that, John": this is the cue to let John stretch out. Depth is earned by a direct ask.
- A question to the whole room: everyone relevant chimes in.
- "Switch to the writers' room" / "bring in the strategy crew": swap the active roster to that group (`resolve_party.py --party <id>`), set its `scene` if it has one, carry the thread over, and let the new faces react to where things stand.
- "Bring in Morpheus": summon any custom member from the collective by name, even if they aren't in the current group.
Any combination, any time, from one voice to the whole table.
@ -72,4 +88,4 @@ Any combination, any time, from one voice to the whole table.
## Wrapping Up
When the user signals they're done (any phrasing: "thanks", "that's all", "end party"), give a quick read-back of the best takeaways and drop back to normal mode. Read the room; don't wait for a magic word.
When the user signals they're done (any phrasing: "thanks", "that's all", "end party"), give a quick read-back of the best takeaways, then run `{workflow.on_complete}` if non-empty (a string scalar is one instruction, an array is a sequence run in order) and drop back to normal mode. Read the room; don't wait for a magic word.

View File

@ -0,0 +1,150 @@
# DO NOT EDIT -- overwritten on every update.
#
# Workflow customization surface for bmad-party-mode.
#
# Override files (not edited here):
# {project-root}/_bmad/custom/bmad-party-mode.toml (team)
# {project-root}/_bmad/custom/bmad-party-mode.user.toml (personal)
[workflow]
# --- Configurable below. Overrides merge per BMad structural rules: ---
# scalars: override wins • plain arrays: append
# arrays of tables keyed by `code`/`id`: matching key replaces, new keys append
# Steps to run before the standard activation (config load, greet).
# Use for pre-flight loads, compliance checks, etc.
activation_steps_prepend = []
# Steps to run after greet but before the room comes alive.
activation_steps_append = []
# Persistent facts the orchestrator keeps in mind for the whole session
# (house rules, running gags, topics to avoid). Each entry is a literal
# sentence, a `skill:`-prefixed reference, or a `file:`-prefixed path/glob whose
# contents load as facts. Default picks up project-context.md if one exists.
persistent_facts = [
"file:{project-root}/**/project-context.md",
]
# Which party loads when the user just says "party mode" with no override.
# Empty = the installed BMAD agents — exactly the default behavior of a plain
# install. Custom members defined below join the POOL (usable in groups, and
# summonable by name) but do NOT crowd this default room. Set this to a
# `party_groups` id to pin a curated room as the default instead. A runtime
# `--party <id>` always wins.
#
# Example (set in team/user override TOML): default_party = "writers-room"
default_party = ""
# How the room is run — who actually does the talking. A runtime `--mode <value>`
# wins for the session. If a mode isn't supported by the harness (e.g. agent-team
# outside Claude Code), it falls back to "auto".
# "auto" (default) voice the room for banter, spin up real subagents only
# when a round needs genuinely independent thinking. The current,
# always-supported behavior.
# "session" never spawn — the orchestrator voices every persona inline.
# Fastest and fully conversational; one mind behind every voice.
# "subagent" spawn a real subagent for every substantive round, so each
# persona thinks independently (the opening banter included).
# "agent-team" stand the personas up as a persistent agent team whose members
# address each other directly. Claude Code only.
party_mode = "auto"
# Executed when the party wraps (after the read-back, before dropping to normal
# mode). String scalar = one instruction; array = instructions run in order.
on_complete = ""
# ---------------------------------------------------------------------------
# Custom party members — personas, added to the POOL alongside the installed
# agents. The default room stays installed-only; a custom member shows up when a
# group uses them or you summon one by name. Keyed by `code`: an override entry
# with a matching code replaces the base one (retune a shipped member), a new
# code appends. Fields:
# code short unique handle, used in party_groups and to summon them
# name display name
# icon single emoji shown on their turns
# title one-line role/identity
# persona voice, humor, ethos, pet peeves, how they argue — the meat;
# what makes them unmistakably themselves
# capabilities (optional) what they can do when spawned as a real subagent;
# woven into their spawn prompt as guidance, not a hard tool grant
# model (optional) model to use when this member is spawned
#
# The members below ship the "Code Review Crew" (see the party_groups section).
# They cost nothing until summoned — the default room never includes them.
# ---------------------------------------------------------------------------
[[workflow.party_members]]
code = "sec-hawk"
name = "Vex"
icon = "🔒"
title = "Security Engineer"
persona = "Threat-models everything. Hunts injection, broken authz, leaked secrets, SSRF, supply-chain risk. Assumes every input is hostile and every dependency compromised until proven otherwise. Names the exploit path concretely — 'here's how I'd own this box' — never hand-waves 'might be insecure.'"
capabilities = "Reads the code and traces data flow from untrusted input to sink before judging."
[[workflow.party_members]]
code = "adversary"
name = "Grumbal"
icon = "😤"
title = "The Adversary"
persona = "Assumes the code is broken and his job is to prove it. Grumpy, blunt, zero praise sandwiches. Starts from 'this will page someone at 3am' and works backward to the line that does it. Allergic to optimism and 'should be fine.'"
[[workflow.party_members]]
code = "edge-hunter"
name = "Boundary"
icon = "🌶️"
title = "Edge-Case Hunter"
persona = "Walks every branch and boundary. Empty input, null, the off-by-one, the huge payload, the concurrent call, the unicode name, the timezone, the retry storm. Method-driven, not mean: 'what happens when this is called twice at once?'"
[[workflow.party_members]]
code = "craftsman"
name = "Yui"
icon = "🎯"
title = "The Craftsman"
persona = "Cares about simplicity, naming, and reuse. Allergic to cleverness and duplication. 'You reimplemented something that already exists,' 'this name lies about what it does,' 'three nested abstractions where one would do.' Wants the boring, obvious, maintainable version."
[[workflow.party_members]]
code = "shipper"
name = "Dana"
icon = "🚢"
title = "The Pragmatist"
persona = "Counters the perfectionists so the room isn't a pile-on. 'Does this actually matter to a user? Ship the 80%, file the rest.' Pushes back on gold-plating and theoretical risks, forces everyone to rank what's real versus what's a nit."
# ---------------------------------------------------------------------------
# Named party groups — curated rooms picked at runtime with `--party <id>`
# (alias `--group <id>`) or switched to mid-session. Keyed by `id`.
#
# `members` is a list of codes — installed agent codes, custom member codes, or
# a mix. Override by `id` to retune a group; new ids append.
#
# An optional `scene` sets the stage: a freeform line (or a few) describing the
# setting, what's happening, how the room behaves, and any in-the-moment
# character notes — who's had a few, who's hostile to whom, who pressure-tests
# hardest. The same members can power many scenes; define a member once, then
# drop them into different rooms. No fixed vocabulary — the model reads it and
# plays it.
#
# `members` is OPTIONAL. Leave it off and the group is open-cast: the `scene`
# names a pool or universe and the room is cast on the fly — you don't enumerate
# who shows up; the model picks who fits and can vary them by topic. List a few
# members AND a scene to anchor some faces while the scene invites others in.
#
# More examples to drop into your override TOML:
# [[workflow.party_groups]] # anchored room with a scene
# id = "writers-room"
# name = "The Writers' Room"
# scene = "Late-night room, everyone a little punchy. Pitch hard, kill darlings faster."
# members = ["analyst", "tech-writer", "morpheus"]
#
# [[workflow.party_groups]] # open-cast room (no roster; the scene casts it)
# id = "star-wars-rebels"
# name = "Star Wars Rebels"
# scene = "Aboard the Ghost. Figures from the Rebels universe drop in depending on the situation — pick whoever fits the topic, and let the roster shift as the conversation moves."
# ---------------------------------------------------------------------------
[[workflow.party_groups]]
id = "code-review-crew"
name = "Code Review Crew"
scene = "Adversarial code review. Each reviewer attacks from their own lens and they argue with each other about what actually matters — security versus shipping, elegance versus pragmatism. No rubber-stamping, no praise sandwiches: surface the real problems before they ship. Point at the line, name the failure mode, and defend it when someone pushes back. Best run with `--mode subagent` so each lens reviews independently before they clash."
members = ["sec-hawk", "adversary", "edge-hunter", "craftsman", "shipper"]

View File

@ -0,0 +1,65 @@
# Creating a Party
A guided authoring flow that turns an idea — a themed cast, a one-off persona, or a pile of raw profile data — into custom party members and groups, written to the user's customize.toml override. The output is configuration; `bmad-customize` does the actual write.
## What you're producing
Sparse `[workflow]` override entries for `bmad-party-mode`:
- `[[workflow.party_members]]` — one per persona: `code`, `name`, `icon`, `title`, `persona`, optional `capabilities`, optional `model`.
- `[[workflow.party_groups]]` — when the personas form a named room: `id`, `name`, an optional freeform `scene`, and `members` (codes). `members` is optional: leave it off for an open-cast room whose `scene` names a pool the model casts from on the fly.
- `default_party` — set only if the user wants this group to load by default.
A `scene` is one freeform line (or a few) that sets the stage for a room: the setting, what's happening, how the room behaves, and any in-the-moment character notes — who's three drinks in, who's hostile to whom, who pressure-tests hardest. It's how the same members power many different rooms (a bridge crew on duty vs. the same crew off-duty in the lounge vs. a hostile buyer panel). Define each member once; vary the `scene` per group rather than redefining people. There's no fixed vocabulary — write it plainly and the model plays it.
The `persona` field is the whole game. A flat title produces a flat voice; the detail you elicit is what makes a member unmistakably themselves at the table.
## Find the shape
Open by understanding what they're building. Three common shapes — stay open, anything that yields distinct voices is fair game:
- **A cast** — a themed ensemble ("the Star Trek TOS bridge crew", "a board of famous investors"). Several members plus a group that holds them.
- **One-offs** — a persona or two added to the collective, no group needed.
- **Distilled from data** — the user hands you source material (a spreadsheet of customer profiles, survey exports, interview notes) to compress into N stereotypical personas. This is how you stand up an AI focus group for product ideation or feedback.
- **A panel of lenses** — purpose-built reviewers, each a sharp critical angle (a security engineer, an adversarial skeptic who assumes it's broken, an edge-case hunter, a craftsman who hates cleverness and duplication, a pragmatist who counters perfectionism). The group's `scene` tells them to attack from their lens and argue with each other about what actually matters. A great adversarial-review or red-team room.
- **Open-cast** — no fixed roster at all. The group's `scene` names a pool or universe ("figures from the Star Wars Rebels universe drop in depending on the situation") and the room is cast on the fly. Leave `members` off; the model already knows the universe and picks who fits the moment. Anchor a face or two by listing them if some should always be present.
Ask which they're after if it isn't obvious, then proceed.
**Persisting a cast already in play.** When you arrive here from a live session — the user spun up an ad-hoc cast inline and wants to keep it — the personas are already drafted and voiced. Don't re-interrogate: capture them as they've been playing, give the group an `id` and name, ask the default question, and go straight to the write.
## Editing an existing party
When the user wants to change a party that already exists (retune a member's persona, add someone to a group, swap the default), read the current state first so you change rather than clobber: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` returns the merged `party_members`, `party_groups`, and `default_party`. Show the member or group being touched, capture only the delta with the user, and hand that sparse change to `bmad-customize` — it replaces a `party_members`/`party_groups` entry whose `code`/`id` matches and appends the rest, so an edit is just the changed entry, never a full rewrite.
## Distill from source data (when provided)
When the user points you at data — a file path, a pasted table, exported profiles — read it and compress it into the requested number of representative personas. Cluster by what actually differentiates behavior (goals, budget, pains, adoption posture), not surface demographics alone. Each cluster becomes one persona with a real name and face. Name your reasoning: tell the user which segments you found and which traits drove the split, so they can correct the cut before you flesh the personas out. If they didn't say how many, propose a number from the spread in the data and let them adjust.
For a focus-group panel, independent answers matter more than banter, so offer to set `party_mode` to `subagent` (or remind them `--mode subagent` does it per session) — otherwise one mind voices every customer and they bleed together.
## Flesh out each persona
Draft, don't interrogate. Propose a first cut of each persona and let the user react — far faster than a questionnaire. Push each one until it has a voice you could pick out blind. The dimensions that earn their place:
- **Identity** — name, a one-line title, an emoji that fits.
- **Voice & ethos** — how they talk, what they value, how they argue, their pet peeves.
- **Agenda** — what they're really after in any conversation; what they push for.
- **Quirks** — the specific, human details (a catchphrase, a bias, a blind spot).
- For focus-group personas, also **likes and dislikes**: what would make them champion or reject an idea, and their relationship to the product space.
- **Capabilities** (optional) — if this persona should research or read files when spawned, note it; it becomes soft guidance in their spawn prompt.
Keep pushing for specificity. "Skeptical CFO" is a placeholder; "won't approve anything without a payback under 18 months, and says so in the first thirty seconds" is a persona.
## Close it out
- Ask straight: **anything else about this party to specify** before you write it — a house dynamic, a missing voice, a member who should lead.
- Ask whether **this group should be the default party going forward**. Yes → set `default_party` to the group's id. One-offs with no group can't be a default; skip the ask.
## Write via bmad-customize
**First, check for code collisions.** A custom member whose `code` matches an installed agent silently *overrides* that agent in the collective. Before composing, resolve the collective once — `python3 {skill-root}/scripts/resolve_party.py --project-root {project-root} --skill {skill-root}` — and check each new member's `code` against the returned members. On a collision, surface it ("`analyst` would override the installed Analyst — intended, or pick a different code?") and let the user confirm or rename. One check, not a gate.
Compose the sparse override and hand it to `bmad-customize` to place, confirm, and write — target skill `bmad-party-mode`, `[workflow]` surface. Default to the **user** override (`bmad-party-mode.user.toml`); offer the **team** file when the party is meant to be shared. Hand it the exact entries: the `party_members` tables, any `party_groups` table, and `default_party` if the user opted in. Keep it sparse — only the new entries, never a copy of the base customize.toml. `bmad-customize` shows the TOML, waits for an explicit yes, writes, and verifies the merge; don't write the file yourself.
After it lands, tell the user how to use it: `--party <id>` to summon the group, or that it's now the default if they set it.

View File

@ -0,0 +1,267 @@
#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# ///
"""Resolve the party-mode roster, lazily.
Merges the installed BMAD agents with the user's custom `party_members`
into one collective, then projects only what the moment needs:
* default (no flag) the active roster to load on entry: the
`default_party` group if one is configured, else the whole collective.
Other groups come back as names only, so nothing you aren't using is
loaded into the party.
* --list-groups just id + name + size for every configured group. The
cheap menu for "which room?", with no member detail.
* --party <id> full member detail for one chosen group, on demand
(e.g. when the user switches rooms). Unknown id returns the available
names instead of an error wall.
The merge is deterministic (a keyed union; a custom member whose code
matches an installed agent overrides it), so the orchestrator consumes a
resolved roster instead of re-deriving it every session.
Stdlib only (Python 3.11+ for tomllib). Shells out to the project's
resolve_config.py and resolve_customization.py; falls back to reading
customize.toml directly if the customization resolver is unavailable.
resolve_party.py --project-root P --skill S
resolve_party.py --project-root P --skill S --list-groups
resolve_party.py --project-root P --skill S --party writers-room
"""
import argparse
import json
import subprocess
import sys
from pathlib import Path
try:
import tomllib
except ImportError: # pragma: no cover - guarded for <3.11
sys.stderr.write("error: Python 3.11+ is required (stdlib `tomllib`).\n")
sys.exit(3)
def _run_json(cmd):
"""Run a resolver script and parse its JSON stdout. None on any failure."""
try:
out = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
except (OSError, subprocess.SubprocessError):
return None
if out.returncode != 0 or not out.stdout.strip():
return None
try:
return json.loads(out.stdout)
except json.JSONDecodeError:
return None
def load_agents(project_root: Path):
"""Installed agents as {code: entry}. Empty dict (with a flag) on failure."""
script = project_root / "_bmad" / "scripts" / "resolve_config.py"
data = _run_json([sys.executable, str(script), "--project-root", str(project_root), "--key", "agents"])
if data is None:
return {}, False
return data.get("agents", {}) or {}, True
def load_workflow(project_root: Path, skill_root: Path):
"""Merged [workflow] table. Falls back to the skill's base customize.toml."""
script = project_root / "_bmad" / "scripts" / "resolve_customization.py"
data = _run_json([sys.executable, str(script), "--skill", str(skill_root), "--key", "workflow"])
if data is not None and "workflow" in data:
return data["workflow"]
# Fallback: read the skill's base customize.toml directly (no override merge).
toml_path = skill_root / "customize.toml"
if toml_path.exists():
try:
with toml_path.open("rb") as f:
return tomllib.load(f).get("workflow", {})
except (OSError, tomllib.TOMLDecodeError):
pass
return {}
def _alias(code: str) -> str:
"""Short alias for an installed agent code: bmad-agent-analyst -> analyst."""
for prefix in ("bmad-agent-", "bmad-"):
if code.startswith(prefix):
return code[len(prefix):]
return code
def build_collective(agents: dict, party_members: list):
"""One pool keyed by code. Custom members override matching installed agents.
Returns (collective, index, installed_codes):
* collective every member (installed + custom), the pool groups draw
from and the orchestrator can summon by name.
* index maps every resolvable token (code, prefix-stripped alias,
lower-cased name) to a canonical code.
* installed_codes the codes occupying an installed-agent slot, in
order. This is the DEFAULT room: installed agents (with any custom
override applied in place), and NOT the pure-custom additions. So
shipping or defining custom members grows the pool without crowding
the default party.
"""
collective = {}
index = {}
installed_codes = []
def register(code, entry):
collective[code] = entry
index[code] = code
index[code.lower()] = code
index[_alias(code).lower()] = code
name = entry.get("name")
if name:
index[name.lower()] = code
for code, info in agents.items():
register(code, {
"code": code,
"name": info.get("name", code),
"icon": info.get("icon", ""),
"title": info.get("title", ""),
"description": info.get("description", ""),
"module": info.get("module", ""),
"team": info.get("team", ""),
"source": "installed",
})
installed_codes.append(code)
for m in party_members or []:
code = m.get("code")
if not code:
continue
# A custom member overrides an installed agent it matches by code/alias/name.
canonical = index.get(code) or index.get(code.lower()) or code
entry = {"code": canonical, "source": "custom"}
for field in ("name", "icon", "title", "persona", "capabilities", "model"):
if m.get(field) is not None:
entry[field] = m[field]
entry.setdefault("name", canonical)
register(canonical, entry)
# An override keeps the installed slot; a brand-new custom does not join it.
return collective, index, installed_codes
def resolve_members(member_tokens, collective, index):
"""(resolved entries in listed order, unresolved tokens)."""
resolved, unresolved = [], []
for token in member_tokens or []:
code = index.get(token) or index.get(str(token).lower())
if code and code in collective:
resolved.append(collective[code])
else:
unresolved.append(token)
return resolved, unresolved
def group_menu(groups):
"""Names only — the cheap menu. Open-cast groups (no roster) are flagged."""
out = []
for g in groups or []:
if not isinstance(g, dict) or not g.get("id"):
continue
members = g.get("members", []) or []
entry = {"id": g["id"], "name": g.get("name", g["id"]),
"member_count": len(members)}
if not members:
entry["open_cast"] = True
out.append(entry)
return out
def find_group(groups, group_id):
for g in groups or []:
if isinstance(g, dict) and g.get("id") == group_id:
return g
return None
def group_detail(g, collective, index):
"""Full detail for one group: resolved members + the optional scene.
`scene` is a freeform line the orchestrator plays setting, what's
happening, room dynamics, in-the-moment character notes. Surfaced only
here (when a group is the active/chosen roster), never in the menu.
`members` is optional. With none, the group is open-cast: `open_cast`
is flagged and the scene describes the pool the orchestrator casts from
on the fly (e.g. "figures from the Star Wars Rebels universe"). A few
listed members anchor the room; the scene can still invite more.
"""
raw_members = g.get("members", []) or []
members, unresolved = resolve_members(raw_members, collective, index)
detail = {"active": g["id"], "name": g.get("name", g["id"]),
"members": members, "unresolved": unresolved}
if g.get("scene"):
detail["scene"] = g["scene"]
if not raw_members:
detail["open_cast"] = True
return detail
def main():
ap = argparse.ArgumentParser(description="Resolve the party-mode roster, lazily.")
ap.add_argument("--project-root", required=True)
ap.add_argument("--skill", required=True, help="Path to the bmad-party-mode skill dir")
ap.add_argument("--party", help="Resolve full detail for this group id")
ap.add_argument("--list-groups", action="store_true", help="Group names only")
args = ap.parse_args()
project_root = Path(args.project_root).resolve()
skill_root = Path(args.skill).resolve()
workflow = load_workflow(project_root, skill_root)
groups = workflow.get("party_groups", []) or []
default_party = workflow.get("default_party", "") or ""
party_mode = workflow.get("party_mode", "auto") or "auto"
# Group menu never needs the (more expensive) installed-agent resolve.
if args.list_groups:
_emit({
"party_mode": party_mode,
"default_party": default_party,
"groups": group_menu(groups),
})
return
agents, agents_ok = load_agents(project_root)
collective, index, installed_codes = build_collective(agents, workflow.get("party_members", []))
if args.party:
g = find_group(groups, args.party)
if g is None:
_emit({"error": "unknown_group", "requested": args.party,
"available": group_menu(groups)})
return
_emit({**group_detail(g, collective, index), "party_mode": party_mode})
return
# Default: the active roster to load on entry.
result = {"party_mode": party_mode, "groups": group_menu(groups),
"installed_agents_resolved": agents_ok}
g = find_group(groups, default_party) if default_party else None
if g is not None:
result.update(group_detail(g, collective, index))
else:
# No default group: the installed agents (custom additions stay in the
# pool but don't crowd the default room), exactly like a plain install.
result.update({"active": "installed",
"members": [collective[c] for c in installed_codes]})
_emit(result)
def _emit(obj):
reconfigure = getattr(sys.stdout, "reconfigure", None)
if reconfigure is not None:
reconfigure(encoding="utf-8")
sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
if __name__ == "__main__":
main()

View File

@ -0,0 +1,138 @@
#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# ///
"""Unit tests for resolve_party.py — merge, alias, override, group resolution."""
import sys
import unittest
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
import resolve_party as rp # noqa: E402
AGENTS = {
"bmad-agent-analyst": {"name": "Mary", "icon": "📊", "title": "Analyst"},
"bmad-agent-pm": {"name": "John", "icon": "📋", "title": "PM"},
}
class TestAlias(unittest.TestCase):
def test_strips_known_prefixes(self):
self.assertEqual(rp._alias("bmad-agent-analyst"), "analyst")
self.assertEqual(rp._alias("bmad-foo"), "foo")
def test_passes_through_unprefixed(self):
self.assertEqual(rp._alias("morpheus"), "morpheus")
class TestBuildCollective(unittest.TestCase):
def test_installed_agents_indexed_by_code_alias_and_name(self):
col, idx, _ = rp.build_collective(AGENTS, [])
self.assertEqual(set(col), {"bmad-agent-analyst", "bmad-agent-pm"})
self.assertEqual(idx["analyst"], "bmad-agent-analyst") # alias
self.assertEqual(idx["mary"], "bmad-agent-analyst") # name (ci)
self.assertEqual(idx["bmad-agent-pm"], "bmad-agent-pm") # full code
self.assertEqual(col["bmad-agent-analyst"]["source"], "installed")
def test_custom_member_appends(self):
col, _, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus", "persona": "riddles"}])
self.assertIn("morpheus", col)
self.assertEqual(col["morpheus"]["source"], "custom")
self.assertEqual(col["morpheus"]["persona"], "riddles")
def test_custom_overrides_installed_by_alias(self):
col, _, _ = rp.build_collective(AGENTS, [{"code": "analyst", "name": "Mary-Custom", "persona": "p"}])
# Override lands on the canonical installed code, not a new "analyst" entry.
self.assertNotIn("analyst", col)
self.assertEqual(col["bmad-agent-analyst"]["source"], "custom")
self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
def test_member_without_code_skipped(self):
col, _, _ = rp.build_collective(AGENTS, [{"name": "Nameless"}])
self.assertEqual(set(col), {"bmad-agent-analyst", "bmad-agent-pm"})
class TestResolveMembers(unittest.TestCase):
def setUp(self):
self.col, self.idx, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus"}])
def test_resolves_in_listed_order_and_flags_unknowns(self):
resolved, unresolved = rp.resolve_members(["morpheus", "analyst", "ghost"], self.col, self.idx)
self.assertEqual([m["code"] for m in resolved], ["morpheus", "bmad-agent-analyst"])
self.assertEqual(unresolved, ["ghost"])
def test_empty(self):
self.assertEqual(rp.resolve_members([], self.col, self.idx), ([], []))
class TestGroups(unittest.TestCase):
GROUPS = [
{"id": "wr", "name": "Writers", "members": ["analyst", "morpheus"]},
{"id": "bad"}, # no name -> falls back to id; no members -> count 0
{"name": "no-id"}, # dropped from menu
]
def test_menu_is_names_only_with_counts_and_open_cast_flag(self):
menu = rp.group_menu(self.GROUPS)
self.assertEqual(menu, [
{"id": "wr", "name": "Writers", "member_count": 2},
{"id": "bad", "name": "bad", "member_count": 0, "open_cast": True},
])
def test_find_group(self):
self.assertEqual(rp.find_group(self.GROUPS, "wr")["name"], "Writers")
self.assertIsNone(rp.find_group(self.GROUPS, "missing"))
class TestGroupDetail(unittest.TestCase):
def setUp(self):
self.col, self.idx, _ = rp.build_collective(AGENTS, [{"code": "morpheus", "name": "Morpheus"}])
def test_scene_passes_through_when_present(self):
g = {"id": "tos-10-forward", "name": "Ten Forward", "members": ["morpheus"],
"scene": "Late evening, a few rounds in."}
d = rp.group_detail(g, self.col, self.idx)
self.assertEqual(d["scene"], "Late evening, a few rounds in.")
self.assertEqual([m["code"] for m in d["members"]], ["morpheus"])
def test_scene_omitted_when_absent_or_empty(self):
for g in ({"id": "g", "members": ["morpheus"]},
{"id": "g", "members": ["morpheus"], "scene": ""}):
self.assertNotIn("scene", rp.group_detail(g, self.col, self.idx))
def test_anchored_group_is_not_open_cast(self):
g = {"id": "g", "members": ["morpheus"]}
self.assertNotIn("open_cast", rp.group_detail(g, self.col, self.idx))
def test_open_cast_group_flagged_with_empty_members(self):
g = {"id": "rebels", "name": "Star Wars Rebels",
"scene": "Figures from the Rebels universe drop in as the topic calls for them."}
d = rp.group_detail(g, self.col, self.idx)
self.assertTrue(d["open_cast"])
self.assertEqual(d["members"], [])
self.assertEqual(d["scene"][:7], "Figures")
class TestInstalledCodesIsDefaultRoom(unittest.TestCase):
"""The default room is installed agents only; pure customs stay in the pool."""
def test_pure_custom_excluded_override_kept_in_default_room(self):
col, _, installed = rp.build_collective(AGENTS, [
{"code": "morpheus", "name": "Morpheus"}, # pure custom
{"code": "analyst", "name": "Mary-Custom", "persona": "p"}, # override
{"code": "sec-hawk", "name": "Vex"}, # shipped crew member
])
# Pure customs are in the pool...
self.assertIn("morpheus", col)
self.assertIn("sec-hawk", col)
# ...but NOT in the default room.
self.assertEqual(installed, ["bmad-agent-analyst", "bmad-agent-pm"])
default_room = [col[c]["code"] for c in installed]
self.assertEqual(default_room, ["bmad-agent-analyst", "bmad-agent-pm"])
# An override keeps its installed slot (and its custom content).
self.assertEqual(col["bmad-agent-analyst"]["name"], "Mary-Custom")
if __name__ == "__main__":
unittest.main()