claude-configs/skills/council-meeting/SKILL.md

Council Meeting

Multi-round deliberation between product owner agents to discuss a topic and produce a ranked recommendation.

Usage

/council-meeting [rounds] [topic]

• rounds (optional): Number of deliberation rounds (default: 3, max: 5)
• topic (optional): Specific question to deliberate on

Examples

/council-meeting
/council-meeting 5
/council-meeting 3 "Should we prioritize pack opening UX or content pipeline automation?"

Council Configuration

The orchestrator must define the council before spawning agents. The council is project-specific — read the project's CLAUDE.md to identify PO agents and their domains.

Required configuration (built by orchestrator at runtime):

COUNCIL_MEMBERS:
  - name: {agent-name}          # e.g. "database-po"
    subagent_type: {agent-type}  # matches .claude/agents/{type}.md
    model: opus                  # PO agents should use Opus for depth
    domain: {domain}             # e.g. "Database API"
    repo: {gitea-repo}           # e.g. "paper-dynasty-database" (optional)

MODERATOR:
  name: moderator
  subagent_type: general-purpose
  model: sonnet

CONTEXT_GATHERING:
  # Project-specific commands to run before the meeting
  # e.g. "pd-plan summary", "pd-plan list", issue lookups

The orchestrator determines this configuration by:

1. Reading the project's CLAUDE.md for the agent table
2. Identifying which PO agents are relevant to the topic
3. Fetching topic context (Gitea issues, tracker state, etc.)

Architecture: Team-Based Communication

This skill uses TeamCreate so agents communicate directly with each other via SendMessage, not hub-and-spoke through the orchestrator.

┌─────────────────────────────────────────────────┐
│              council-meeting team                │
│                                                  │
│   agent-1 ◄──────────► agent-2                   │
│       ▲  ▲                ▲  ▲                   │
│       │  └────────────────┘  │                   │
│       │                      │                   │
│       ▼                      ▼                   │
│   agent-3 ◄──────────► agent-4                   │
│       ▲                      ▲                   │
│       │      moderator       │                   │
│       └─────► (rounds) ◄────┘                   │
│                  │                               │
│                  ▼                               │
│      SendMessage → team-lead (orchestrator)      │
└─────────────────────────────────────────────────┘

Key Constraints (learned from testing)

1. Orchestrator spawns ALL agents. Teammates cannot spawn other teammates — only the orchestrator (team-lead) can call Agent with team_name.
2. Moderator coordinates via SendMessage only. It does NOT spawn agents, does NOT broadcast Round 1 instructions (POs are pre-prompted with Round 1 when spawned).
3. Moderator returns results via SendMessage to "team-lead". Team agents cannot "return text output" to the orchestrator — they must explicitly SendMessage their final report.
4. Orchestrator may need to nudge slow agents. If a PO agent hasn't broadcast within ~30 seconds, the orchestrator or moderator should SendMessage them directly with a reminder.

Workflow

Step 1: Gather Context (orchestrator does this)

Before creating the team, the orchestrator:

1. Reads the project's CLAUDE.md to identify PO agents and their domains
2. Fetches topic context (e.g., Gitea issue details, project tracker state)
3. Builds the council configuration and context block

Step 2: Create Team and Spawn ALL Agents (orchestrator does this)

1. TeamCreate with name council-meeting
2. Spawn ALL agents in parallel using the Agent tool with team_name: "council-meeting":
   • N PO agents (Opus) with Round 1 instructions
   • 1 moderator (Sonnet) with deliberation management instructions

The orchestrator spawns everything. The moderator does NOT spawn agents.

PO Agent Prompt Template (Round 1)

Each PO agent gets this prompt when spawned:

You are participating in a council meeting as {agent_name}. The other council members are: {list the other PO agents} and a moderator who manages rounds.

You can message agents directly via SendMessage (by name) or broadcast to all via SendMessage to "*".

Topic: {topic}

Context: {context block — project tracker, issue details, recent activity}

Round 1 — Opening Proposal:

1. Check your domain's current state (open issues, PRs, recent changes)
2. Assess the topic from your domain's perspective
3. Write a concise proposal (3-5 sentences) for your position
4. Broadcast your proposal to the team via SendMessage to "*"

After broadcasting, go idle and wait. The moderator will message you with instructions for the next round.

Moderator Prompt

You are the moderator of a council meeting.

You manage a structured {total_rounds}-round deliberation between {N} PO agents who are already running in this team: {list agent names}.

You do NOT spawn agents. They are already running and have been pre-prompted with Round 1 instructions. Do NOT broadcast Round 1 instructions — the PO agents will broadcast their proposals on their own.

Topic: {topic}

Context: {context block}

Your process:

1. Wait for all Round 1 proposals

The PO agents will broadcast their opening proposals automatically. Track incoming broadcasts and count them. Do not proceed until you have received proposals from all {N} agents: {list names}.

If an agent hasn't broadcast within ~30 seconds of the others, send them a direct message reminder.

2. Run debate rounds (Rounds 2 through {total_rounds - 1})

Once all Round 1 proposals are in, broadcast to all agents ("*"):

Round {n} of {total_rounds} — Deliberation

Here are the positions from Round {n-1}: {summarize each agent's current position}

Instructions:

• Challenge proposals you disagree with — explain WHY from your domain's perspective
• Defend your position if challenged — bring evidence (issue numbers, user impact, dependencies)
• You MAY revise your position if another agent's argument is compelling
• You may message other agents directly for focused exchanges
• Broadcast your updated position via SendMessage to "*" when ready

Be direct. Disagree openly. The goal is the best decision, not consensus for its own sake.

Wait for all agents to respond before the next round. Nudge stragglers if needed.

3. Final round — Vote

Broadcast to all agents ("*"):

Round {total_rounds} of {total_rounds} — Final Vote

Positions after {total_rounds - 1} rounds: {summarize current positions}

Submit your FINAL priority ordering as a numbered list (top 3-5). For each item:

1. Initiative/issue name and number
2. One sentence on why it's at this position
3. Which domain it primarily affects

Broadcast your final vote via SendMessage to "*". This is your last round.

Wait for all final votes. Nudge stragglers if needed.

4. Synthesize and report

After all final votes are in:

1. Tally rankings (lowest average rank = highest priority)
2. Note strong dissents
3. Shut down all PO agents via SendMessage with {type: "shutdown_request"}
4. Send the final recommendation to the orchestrator via SendMessage to "team-lead" — this is how results get back. Do NOT rely on text output; team agents must explicitly message team-lead.

Format the recommendation as:

## Council Recommendation

**Topic:** {topic}

### Consensus Ranking
1. **{item}** — {one-line rationale} ({votes: N agents ranked this #1})
2. ...

### Key Arguments
- {2-3 bullet points on the strongest arguments}

### Dissents
- {any notable disagreements, or "None — council reached consensus"}

### Suggested Next Steps
- {2-3 actionable next steps}

Step 3: Wait for Results

The orchestrator waits for the moderator's SendMessage containing the council recommendation. If the moderator goes idle without sending it, nudge via SendMessage.

Step 4: Present and Cleanup

The orchestrator:

1. Presents the moderator's recommendation to Cal
2. Shuts down the moderator via SendMessage with {type: "shutdown_request"}
3. Cleans up the team with TeamDelete

Important Rules

• Orchestrator spawns ALL agents — moderator cannot spawn teammates (TeamCreate constraint)
• POs are pre-prompted — moderator does NOT re-broadcast Round 1 instructions
• Moderator sends results to team-lead — team agents cannot return text output to the orchestrator; they must use SendMessage
• Nudge slow agents — if a PO hasn't broadcast within ~30 seconds of others, send a direct reminder
• Never auto-execute — the output is a recommendation, not an action plan that gets kicked off automatically
• All agents get equal voice — no single agent outranks domain expertise
• Disagreement is valuable — if agents converge too quickly, the moderator should prompt steelmanning
• Cap at max rounds — if no convergence after max rounds, present the split and let the user decide
• Include evidence — proposals without issue numbers, PR references, or user impact data should be challenged
• Direct communication — agents should use direct messages for focused exchanges and broadcasts for position statements