mk:party

Party Mode — Multi-Agent Collaboration

Bring multiple agent perspectives into one room. Agents debate, challenge, and build on each other's ideas to catch design flaws before code exists.

Required Agents

This skill orchestrates discussion among existing agent definitions. The following must exist under .claude/agents/ (per agent-routing.md):

architect, developer, security, tester, reviewer, ui-ux-designer, analyst, planner, researcher

If a referenced agent is missing, fall back to the Default row in "1. Agent Selection". Never silently skip a topic-mapped agent without falling back — the discussion loses its challenge dimension.

When to Use

• Architecture trade-offs ("REST vs GraphQL?", "monolith vs microservices?")
• Security vs UX trade-offs ("session timeout: 5min or 24hr?")
• Large refactors that touch many files (risk assessment)
• Brainstorming with domain expertise

For dedicated retrospectives, use mk:retro. mk:party is for architectural trade-off deliberation.

Protocol

Execution model: Agents are simulated personas in the single orchestrator session — NOT real subagent spawns via the Agent tool. The per-round token caps (150 / 175 / 100) are enforced by the orchestrator generating each response in-context. For real parallel multi-session work (separate context windows, worktree isolation), see mk:team-config.

1. Agent Selection

Based on topic keywords, select 2-4 agents:

Topic Signals	Agents Selected
architecture, design, system, scale	architect + developer + planner
security, auth, token, session, encrypt	security + developer + planner
UI, UX, design, responsive, accessible	ui-ux-designer + developer + planner
test, coverage, TDD, quality	tester + developer + reviewer
performance, latency, optimize, cache	architect + developer + analyst
refactor, migration, breaking change	architect + developer + reviewer
sprint, retro, what went wrong	planner + developer + tester + reviewer
Default (no keyword match)	planner + architect + developer

User can override with --agents flag.

Selection constraints (canonical):

• Minimum 2 agents, maximum 4.
• Always include one agent who will IMPLEMENT the decision (usually developer).
• Always include one agent who will CHALLENGE the decision (reviewer, security, or architect).
• Never include orchestrator or analyst in challenge slots — they manage, not debate. (analyst may participate in performance-domain rows where it's already mapped.)

2. Discussion Rounds

Each round, every selected agent responds to the topic in their role:

• Round 1: Each agent states their position (max 150 tokens each)
• Round 2: Each agent responds in two dimensions (max 175 tokens combined — slightly higher than Round 1 to accommodate both dimensions):
  • critique, build on, or counter at least one other agent's position
  • name one thing every agent — including itself — has NOT yet addressed (the blind-spot probe forces collective gap detection, not just pairwise critique)
• Round 3: Each agent gives final recommendation (max 100 tokens each)

User can interject between rounds. User can say "decide" to skip to synthesis.

See "Example" below for one full round + synthesis at the prescribed token caps.

3. Synthesis

After rounds complete (max 3) or user says "decide", produce a synthesis using the canonical Decision Record Template (see "Decision Record Template (canonical)" below). The same template is used for both the in-discussion synthesis output and the persistent memory write — single source of truth.

See "Example" for a populated record.

Example

Topic: "REST or GraphQL for the public API?"

Selected agents (architecture row): architect + developer + planner.

Round 1 — positions (≤150 tokens each):

• architect: GraphQL surfaces structural coupling earlier — clients declare exact fields, the schema is the contract. REST hides this in undocumented response shapes. Risk: GraphQL adds a resolver layer that can N+1 if not cached. Verdict: GraphQL.
• developer: REST is cheaper to implement. We have OpenAPI tooling, existing middleware, no new ops surface. GraphQL needs a schema-codegen pipeline and rate-limit-by-cost (not by-request). Verdict: REST unless the client federation case is real.
• planner: What clients are we actually serving? If <3, REST. If 5+ with different field needs, GraphQL pays back. We have 2 today, 4 on roadmap. Verdict: REST now, plan for GraphQL when the 5th lands.

Round 2 — challenges + blind spots (≤175 tokens combined each):

• architect → developer: "Cheaper to implement" ignores client cost — three iOS engineers writing parallel field-fetchers cost more than one resolver layer. Blind spot: nobody has named what "public API" means here. Are external partners on roadmap? That changes the schema-stability calculus entirely.
• developer → planner: "Plan for GraphQL when the 5th lands" defers migration cost. If we know it's coming, build now. Blind spot: we haven't discussed the auth model. REST + per-route auth is one cost shape; GraphQL field-level auth is another. Both absent from the trade-off so far.
• planner → architect: Resolver N+1 is real and we lack query-cost rate limiting — operationally we'd ship a footgun. Blind spot: nobody has asked who maintains either layer in 12 months. Bus factor matters more than the technology choice.

Round 3 — final recommendations (≤100 tokens each):

• architect: GraphQL with persisted queries only. Block ad-hoc queries at the gateway.
• developer: REST + a thin BFF layer per client. Defer GraphQL.
• planner: REST now, BFF when client #4 lands, GraphQL re-evaluation at #5. Cap each step at one quarter.

Synthesis (using Decision Record Template):

## 2026-05-09 — Public API: REST first, GraphQL re-eval at client #5
**Context:** 2 clients today, 4 on roadmap; team has REST tooling but no GraphQL ops experience.
**Decision:** REST + per-client BFF. Re-evaluate GraphQL when client #5 ships, with persisted-queries-only as a hard constraint if adopted.
**Rationale:** Operational cost of GraphQL (N+1, no query-cost rate limiting) outweighs schema-coupling benefit at current client count. Migration cost was raised but discounted given <5 clients. Round-2 blind spots also surfaced: external-partner exposure, field-level auth model, and 12-month maintainer bus factor — all flagged as open questions before any GraphQL re-evaluation.
**Dissent:** architect argued for GraphQL-now with persisted queries only. Acknowledged but overruled because the team lacks GraphQL ops experience and the client count doesn't yet justify the operational surface.
**Next Action:** Spec the per-client BFF interface for client #3 (next on roadmap). Cap at 1 sprint; delivery unblocks the re-evaluation criteria.

The verdict in this example is illustrative only — not a project-wide stance on REST vs GraphQL. What it calibrates is response SHAPE: token-bounded position, terse challenge, compressed final recommendation, and a Decision Record that names dissent without erasing it.

Constraints (Anti-Token-Explosion)

• Max 4 agents per session
• Max 3 rounds before forced synthesis
• Max 150 tokens per agent response in Round 1, 175 tokens in Round 2 (covers critique + blind-spot probe), 100 tokens in Round 3
• Budget ceiling: ~8K tokens per party session
• No code changes during party mode — discussion only

Prompts

• prompts/agent-selector.md — Logic for choosing relevant agents
• prompts/synthesis.md — Template for decision summary

Gotchas

• LLM sycophancy: agents tend to agree rather than critique — prompts explicitly instruct agents to challenge and counter
• Token budget is PER SESSION, not per round — a 4-agent × 3-round session at the new caps (150 / 175 / 100) ≈ 1700 tokens of agent output plus synthesis
• Party mode is discussion-only — if an agent suggests code changes during party, redirect to the normal pipeline after the decision
• Decision write is NOT optional — see "Memory Write" below
• "decide" keyword ends the discussion immediately — don't use it in the topic itself (e.g., avoid "decide between REST and GraphQL")
• allowed-tools is intentionally broad: Bash for mkdir -p .claude/memory, Grep/Glob for topic-keyword grounding against the codebase, Read for prompts/*.md references, AskUserQuestion for the "decide" gate. Do not trim without measuring loss.

Decision Record Template (canonical)

This template is the single source of truth for both the in-discussion synthesis output and the persistent record written to .claude/memory/decisions.md. Do NOT introduce alternative shapes elsewhere in the skill.

## {ISO-date} — {decision-title}
**Context:** {1-sentence problem}
**Decision:** {chosen option}
**Rationale:** {key reasons from synthesis, including notable Round-2 blind spots}
**Dissent:** {minority position, if any}
**Next Action:** {single concrete first step, OR `(none — decision is its own action)`}

Synthesis rules:

• Synthesis must be factual — do not invent consensus that didn't emerge.
• If no consensus reached, set **Decision:** No consensus. and list the options with their advocates under **Rationale:**.
• Always populate **Dissent:** if any agent disagreed; "(none)" only if every agent converged.
• Always populate **Next Action:**. Use (none — decision is its own action) when the decision needs no separate follow-up step (e.g., "use REST" — the codebase choice IS the action). Otherwise name ONE concrete first step (not a list).
• Roll Round-2 blind spots into **Rationale:** when they materially shaped the decision; ignore probes that surfaced no new information.

Memory Write (required, not optional)

After synthesis concludes, append the populated Decision Record (using the template above) to .claude/memory/decisions.md. Run mkdir -p .claude/memory first to create the directory if it does not exist.

This step is NOT optional. Decisions lost to session end cannot be recovered.

Integration

Party mode is opt-in:

• User invokes /mk:party "topic"
• Orchestrator may suggest it for COMPLEX architectural decisions
• Never auto-triggered without user consent
• Does not replace or bypass any gates