staff-session

name	staff-session
description	PM-GATED: ask first; never from subagent. Agent Teams collaborative planning/review for architectural decisions only. Modes: plan, review.
allowed-tools	["Agent","Read","Write","Bash","Glob","Grep","TaskCreate","TaskUpdate","TaskList","TaskGet","SendMessage"]
argument-hint	--mode plan|review --tier standard|full [--members "the Staff Engineer,the Director of Engineering,..."] <input>

Staff Session — Agent Teams Planning and Review Driver

The EM scopes the work, selects the team, creates the team, spawns all teammates, and is freed. The team works autonomously:

• Debaters (2-5, Opus, persona agents) — read input independently, research the codebase, form positions, debate peers via messaging, converge, write position documents, send DONE to synthesizer
• the Director of Engineering / Synthesizer (1, Opus) — Director of Engineering. Blocked until all debaters complete, then reads all positions and writes the final output through his ambition-calibrated lens. Represents all positions fairly but resolves contested topics with an eye toward what's achievable with AI execution capacity

Lightweight tier falls through to single-reviewer dispatch via /review (plan) or /review-code (code) — no team created.

Arguments

$ARGUMENTS:

• --mode plan|review — required. plan for crafting a new plan from objectives; review for critiquing an existing artifact
• --tier lightweight|standard|full — required. lightweight routes to single-reviewer dispatch (/review for plan artifacts, /review-code for code artifacts). standard = 2 debaters. full = 3-5 debaters
• --members "persona-a,persona-b,..." — optional. Override auto-selection with explicit persona slugs (e.g., "the Staff Engineer,the Director of Engineering")
• <input> — required. Plan mode: path to objectives document or free-text objectives. Review mode: path to the artifact to review

Step 1 — Parse Arguments and Setup

Parse $ARGUMENTS:

• Extract --mode (plan|review) — required; fail with usage message if missing
• Extract --tier (lightweight|standard|full) — required; fail with usage message if missing
• Extract --members (optional) — comma-separated persona slugs
• Remaining text after flags is the <input> — artifact path or objectives

Generate run ID: YYYY-MM-DD-HHhMM (current timestamp, e.g., 2026-03-22-09h30)

Record spawn timestamp:

date +%s

Generate topic slug from input (e.g., camera-refactor-plan, pipeline-d-review).

Create scratch directory:

mkdir -p tasks/scratch/staff-session/{run-id}

Set output path based on mode:

• Plan mode: docs/plans/YYYY-MM-DD-{topic-slug}.md (canonical output for /enrich-and-review)
• Review mode: state/review-findings/YYYY-MM-DD-{topic-slug}-staff-review.md

Set advisory path: {scratch-dir}/advisory.md

Announce: "Running /staff-session --mode {mode} --tier {tier} on '{topic}'."

Step 2 — Tier Routing

If --tier lightweight:

Do NOT create a team. Route directly to /review (plan artifacts) or /review-code (code artifacts) with the specified member (or the Staff Engineer as default if --members not provided).

Announce: "Routing to single-reviewer dispatch (/review or /review-code) for single-reviewer gut-check."

STOP — the rest of this command does not execute.

If --tier standard or --tier full: Continue to Step 3.

Step 3 — Scope (EM Direct)

Write {scratch-dir}/scope.md per the template in pipelines/staff-session/templates-and-fields.md § Step 3. Plan mode: EM writes objectives and constraints only — never the plan. Review mode: EM provides artifact path and focus areas only — never pre-formed findings.

Step 4 — Select Team Composition

If --members specified: Use those exact personas. Validate each slug maps to a known persona agent. Fail with a clear error if any slug is unknown.

If --members not specified: Auto-select based on domain signals from the input topic and scope.

Important: the Director of Engineering is the synthesizer, not a debater. the Director of Engineering cannot appear in the debater list — he reads all debater positions and produces the final output. If the user specifies --members "the Staff Engineer,the Director of Engineering", reject with: "the Director of Engineering is the staff session synthesizer — he can't also debate. Choose a different second debater, or I'll auto-select one."

Domain Signal	Default Pair
Architecture / infrastructure	the Staff Engineer + sid
Game dev / Unreal	sid + the Staff Engineer
Frontend / UI	the Front-End Reviewer + the UX Reviewer
Data science / ML	the Data Science Reviewer + the Staff Engineer
Cross-cutting / unclear	the Staff Engineer + sid

For --tier full: add domain experts on top of the default pair. Use judgment based on the input topic to identify which additional personas are most relevant.

Determine debater count:

• standard: 2 debaters
• full: 3-5 debaters (determined by domain signals and persona relevance)

Announce team composition to PM before creating the team:

"I'll run this with {Persona A} and {Persona B} [+ {Persona C}...] debating, plus a staff synthesizer. Proceeding."

Persona slug → agent file mapping:

Slug	Agent File
the Staff Engineer	coordinator/agents/staff-eng.md
sid	game-dev/agents/staff-game-dev.md
the UX Reviewer	coordinator/agents/staff-ux.md
the Front-End Reviewer	coordinator/agents/senior-front-end.md
the Data Science Reviewer	coordinator/agents/staff-data-sci.md
vp-product	coordinator/agents/vp-product.md

Note: the Director of Engineering is NOT a valid debater slug — he is the synthesizer. See Step 6.

Step 5 — Create Tasks

Order matters. Task IDs from earlier steps are referenced in blocking chain setup.

Spawn the first teammate via the Agent tool — the team auto-forms on first spawn; no explicit create step.

Create Tasks

1. Synthesizer task (created first — will be blocked by all debaters later):

TaskCreate(
  subject: "Synthesize all debater positions into final {plan|findings}",
  description: "Read all position documents from {scratch-dir}/. Cross-reference, resolve conflicts, write output to {output-path} and {scratch-dir}/synthesis.md. If advisory warranted, write to {scratch-dir}/advisory.md."
)

Save as {synthesizer-task-id}.

2. Debater tasks (one per persona — no blockers on creation): For each debater persona:

TaskCreate(
  subject: "{Persona Name}: {mode} session on {topic}",
  description: "Read scope from {scratch-dir}/scope.md. {Plan mode: Research codebase, form architectural position, debate peers, write consensus-ready plan contribution.} {Review mode: Review artifact at {input-path}, form findings, debate peers, write final position.} Output to {scratch-dir}/{persona-slug}-position.md. Send DONE to synthesizer when complete."
)

Collect all debater task IDs as [{debater-A-id}, {debater-B-id}, ...].

3. Block synthesizer on all debaters:

TaskUpdate(taskId: "{synthesizer-task-id}", addBlockedBy: [{debater-A-id}, {debater-B-id}, ...])

Step 6 — Spawn All Teammates

Read the planner / reviewer / synthesizer prompt templates from ${CLAUDE_PLUGIN_ROOT}/pipelines/staff-session/. For each debater, read the persona identity excerpt from its agent definition file (injected at [PERSONA_IDENTITY]). Fill ALL [BRACKETED_FIELD] placeholders before spawning — see pipelines/staff-session/templates-and-fields.md § Step 6 for the full common/debater/synthesizer field list.

Spawn ALL teammates in a single message (parallel):

Agent(
  name: "{persona-slug-A}",
  model: "opus",
  # Review: code-reviewer — prefix varies by persona; see the subagent_type mapping table below for the correct plugin prefix (e.g., game-dev: for the Game Dev Reviewer, not coordinator:)
  subagent_type: "{subagent_type-A}",
  prompt: <filled debater prompt for persona A>
)
TaskUpdate(taskId: "{debater-A-id}", owner: "{persona-slug-A}")

Agent(
  name: "{persona-slug-B}",
  model: "opus",
  subagent_type: "{subagent_type-B}",
  prompt: <filled debater prompt for persona B>
)
TaskUpdate(taskId: "{debater-B-id}", owner: "{persona-slug-B}")

[repeat for each additional debater in full tier]

Agent(
  name: "synthesizer",
  model: "opus",
  subagent_type: "coordinator:eng-director",
  prompt: <filled synthesizer prompt>
)
TaskUpdate(taskId: "{synthesizer-task-id}", owner: "synthesizer")

Persona slug → subagent_type mapping:

Slug	subagent_type
the Staff Engineer	coordinator:staff-eng
sid	game-dev:staff-game-dev
the UX Reviewer	coordinator:staff-ux
the Front-End Reviewer	coordinator:senior-front-end
the Data Science Reviewer	coordinator:staff-data-sci
vp-product	coordinator:vp-product

Step 7 — EM Is Freed

After spawning all teammates, announce:

"Staff session running on '{topic}' with {N} debaters ({names}) + 1 synthesizer.

• Debate phase: floor 3 min, ceiling {MAX_MINUTES} min. Debaters research independently, form positions, and challenge each other.
• Synthesizer unblocks when all debaters complete.

I'm available for other work — I'll be notified when the synthesizer completes."

You are now free to continue the conversation with the PM. Do not poll, do not monitor, do not send WRAP_UP. The team self-governs via the timing and convergence protocol in team-protocol.md.

Step 8 — On Completion Notification

When you receive a notification that the synthesizer task is complete:

1. Read the output at {output-path}. Verify it has substantive content (not just headers or a stub).

2. Mode-specific verification:

   • Plan mode: Verify the plan has an ## Implementation Plan section with tasks, files, and steps in plan format (per docs/wiki/writing-plans.md). Verify **Review:** Staff session ({participants}) — debated and synthesized. Ready for enrichment. is present.
   • Review mode: Verify findings are structured with severities and persona attributions. Verify a ## Verdict line is present.

3. Check for advisory: test -f {scratch-dir}/advisory.md — if the file exists, read it.

4. Commit the output (plain-git scoped — SC-DR-008, lessons.md:207):

   # Stage only the output files this session wrote (scratch dir contents + any plan/review artifact)
   git add -- {output-paths} && git commit -m "staff-session: {mode} — {topic-slug}" -- {output-paths}
   

5. Archive the paper trail:

   mkdir -p docs/research/archive/YYYY-MM-DD-staff-{topic-slug}
   cp -r {scratch-dir}/* docs/research/archive/YYYY-MM-DD-staff-{topic-slug}/
   

6. Remove scratch directory:

   rm -rf {scratch-dir}
   

7. The team auto-cleans on session exit — no explicit teardown step.

8. Commit cleanup (plain-git scoped — SC-DR-008, lessons.md:207):

   git add -- docs/research/archive/YYYY-MM-DD-staff-{topic-slug}/ && git commit -m "staff-session: archive + cleanup" -- docs/research/archive/YYYY-MM-DD-staff-{topic-slug}/
   

9. Present output to PM:

   • Mode-specific framing: plan mode → "Here's the staff session plan, ready for /enrich-and-review"; review mode → "Here are the synthesized findings"
   • Brief executive summary (2-3 bullets of the most important content)
   • Output path
   • If advisory exists: "The synthesizer flagged observations beyond scope — see {scratch-dir} (archived at docs/research/archive/YYYY-MM-DD-staff-{topic-slug}/advisory.md)."

Error Handling

See pipelines/staff-session/templates-and-fields.md § Error Handling Matrix for the full failure-mode → action table (debater crash, synthesizer failure, DONE-not-received, debate loops, unknown slug, missing output).