paladin council - Quick Group Discussions

Execute quick multi-agent discussions without writing configuration files. Get diverse perspectives from multiple AI Paladins on any topic.

Table of Contents

• Overview
• Quick Start
• Command Syntax
• Agent Roles
• Discussion Modes
• Output Options
• Best Practices
• Examples
• Troubleshooting

Overview

The council command enables:

• Ad-hoc multi-agent discussions without configuration files
• Diverse perspectives from multiple AI personas
• Parallel or sequential execution modes
• Structured output with synthesis and analysis
• Quick iterations for brainstorming and decision-making

When to Use Council

✅ Use council when:

• Need quick input from multiple AI perspectives
• Brainstorming solutions to problems
• Evaluating options from different viewpoints
• Quick analysis without formal configuration
• Prototyping multi-agent workflows

❌ Don't use council when:

• Need precise control over agent configuration
• Building production workflows (use paladin run instead)
• Require state persistence across sessions
• Need custom tools or memory systems

Quick Start

Basic Usage

# Simple discussion with default agents
paladin council "What are the best practices for API design?"

# Specify number of agents
paladin council -n 5 "Should we migrate to microservices?"

# Use specific discussion mode
paladin council --mode sequential "Analyze this business proposal..."

# Save results to file
paladin council -o results.md "Security implications of cloud migration"

Command Syntax

paladin council [OPTIONS] <QUESTION>

Arguments:
  <QUESTION>
      The question, topic, or problem to discuss
      Can be a question, statement, or detailed scenario

Options:
  -n, --num-agents <N>
      Number of agents to participate (2-10)
      Default: 3

  -m, --mode <MODE>
      Discussion mode: parallel, sequential, or debate
      Default: parallel

  -r, --roles <ROLES>
      Comma-separated agent roles
      Example: "technical,business,security,ux"
      If not specified, uses default diverse roles

  -o, --output <FILE>
      Save discussion results to file
      Supports: .md, .txt, .json

  -f, --format <FORMAT>
      Output format: markdown (default), json, or plain

  --synthesize
      Generate a synthesis/summary of all perspectives
      Enabled by default, use --no-synthesize to disable

  --provider <PROVIDER>
      LLM provider to use (openai, deepseek, anthropic)

  --model <MODEL>
      Specific LLM model for all agents
      Example: gpt-4, deepseek-chat, claude-3-sonnet

  --temperature <TEMP>
      Temperature for agent responses (0.0-2.0)
      Default: 0.7

  --max-tokens <N>
      Maximum tokens per agent response
      Default: 500

  --timeout <SECONDS>
      Timeout for the entire council session
      Default: 120 seconds

  -v, --verbose
      Show detailed execution information

Agent Roles

Default Roles

When roles aren't specified, council uses diverse default perspectives:

1. Analyst - Data-driven, analytical approach
2. Critic - Identifies risks, challenges, and weaknesses
3. Optimist - Focuses on opportunities and benefits

Custom Roles

# Technical perspectives
paladin council --roles "architect,security,devops,qa" "System design question"

# Business perspectives
paladin council --roles "ceo,cfo,cmo,product" "Product launch strategy"

# Creative perspectives
paladin council --roles "creative,pragmatic,critic,synthesizer" "Marketing campaign"

# Domain-specific
paladin council --roles "legal,compliance,privacy,security" "Data governance policy"

Role Examples

Discussion Modes

Parallel Mode (Default)

All agents respond simultaneously without seeing each other's responses.

paladin council --mode parallel "What are the pros and cons of NoSQL?"

Characteristics:

• ✅ Fastest execution
• ✅ Independent perspectives
• ✅ No groupthink
• ❌ No interaction between agents
• ❌ May have redundant points

Best for:

• Quick diverse input
• Independent perspectives needed
• Time-sensitive discussions

Sequential Mode

Agents respond one after another, each seeing previous responses.

paladin council --mode sequential "How should we approach this technical debt?"

Characteristics:

• ✅ Builds on previous ideas
• ✅ More coherent discussion
• ✅ Can challenge/refine points
• ❌ Slower execution
• ❌ May create groupthink

Best for:

• Building consensus
• Iterative refinement
• Complex problem-solving

Debate Mode

Agents present opposing viewpoints and counter-arguments.

paladin council --mode debate "Should we use serverless architecture?"

Characteristics:

• ✅ Explores trade-offs deeply
• ✅ Identifies weaknesses
• ✅ Structured pro/con analysis
• ❌ Slower than parallel
• ❌ May be adversarial

Best for:

• Decision between alternatives
• Risk/benefit analysis
• Evaluating trade-offs

Output Options

Markdown (Default)

paladin council -o discussion.md "Cloud strategy"

# Council Discussion: Cloud Strategy

## Question
What cloud strategy should we adopt?

## Participants
- Technical Architect
- Business Analyst  
- Security Specialist

## Responses

### Technical Architect
**Perspective:** Technical Implementation

[Response content...]

**Key Points:**
- Multi-cloud for redundancy
- Containerization strategy
- Migration roadmap

### Business Analyst
**Perspective:** Business Value

[Response content...]

**Key Points:**
- Cost optimization
- Scalability benefits
- Time to market

### Security Specialist
**Perspective:** Security & Compliance

[Response content...]

**Key Points:**
- Data sovereignty
- Encryption standards
- Compliance requirements

## Synthesis

[Synthesized recommendations...]

## Action Items

1. Evaluate cloud providers
2. Conduct security audit
3. Create migration plan

JSON Format

paladin council -f json -o discussion.json "API design"

{
  "question": "What are best practices for API design?",
  "mode": "parallel",
  "participants": [
    {
      "role": "technical",
      "model": "gpt-4"
    },
    {
      "role": "business",
      "model": "gpt-4"
    },
    {
      "role": "ux",
      "model": "gpt-4"
    }
  ],
  "responses": [
    {
      "role": "technical",
      "perspective": "Technical Implementation",
      "response": "...",
      "key_points": ["...", "..."],
      "duration_ms": 1250
    }
  ],
  "synthesis": {
    "summary": "...",
    "recommendations": ["...", "..."],
    "action_items": ["...", "..."]
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "total_duration_ms": 3500
  }
}

Plain Text

paladin council -f plain "Design patterns discussion"

Simple text output without formatting, useful for piping to other tools.

Best Practices

1. Frame Questions Clearly

✅ Good:

paladin council "
Should we adopt GraphQL for our public API?

Context:
- RESTful API with 50+ endpoints
- 100k requests/day
- Mobile and web clients
- Team of 5 backend developers
"

❌ Avoid:

paladin council "graphql?"

2. Choose Appropriate Roles

# For technical decisions
paladin council --roles "architect,security,devops" "Kubernetes vs. ECS"

# For product decisions
paladin council --roles "product,ux,engineering,business" "Feature prioritization"

# For strategic decisions
paladin council --roles "ceo,cto,cfo,cmo" "Market expansion strategy"

3. Select the Right Mode

# Quick diverse input → parallel
paladin council --mode parallel "Initial thoughts on blockchain integration"

# Building on ideas → sequential  
paladin council --mode sequential "Refine our architecture approach"

# Evaluating options → debate
paladin council --mode debate "Build vs. buy for authentication"

4. Synthesize Results

# Always get synthesis (default)
paladin council "Complex decision" --synthesize

# Review synthesis for action items
paladin council "Decision" -o results.md
# Then extract action items from results.md

5. Iterate and Refine

# First pass - broad input
paladin council "App architecture options" -o round1.md

# Review results, then deep dive
paladin council "Microservices concerns from round 1" -o round2.md

# Final decision
paladin council "Final architecture decision" --mode debate -o final.md

Examples

Example 1: Quick Technical Decision

paladin council -n 4 "
Should we use TypeScript or JavaScript for our new service?

Context:
- Team has JavaScript experience
- Large codebase (100k+ LOC)
- Need to maintain velocity
- Some junior developers
"

Example 2: Security Review

paladin council --roles "security,privacy,compliance,devops" --mode sequential "
Review our authentication approach:

Current:
- JWT tokens
- 1-hour expiration  
- Stored in localStorage
- No refresh tokens

Concerns:
- XSS vulnerability?
- CSRF protection?
- Mobile app considerations?
"

Example 3: Architecture Debate

paladin council --mode debate --roles "monolith-advocate,microservices-advocate" "
Should we migrate from monolith to microservices?

Current state:
- Monolithic Rails app
- 5-year-old codebase
- 10 developers
- Deployment issues
- Scaling challenges
"

Example 4: Product Strategy

paladin council --roles "product,marketing,sales,engineering,support" -o strategy.md "
Should we build a mobile app or focus on responsive web?

Data:
- 60% mobile traffic
- Limited mobile team
- 6-month timeline
- Competitor has native apps
"

Example 5: Incident Post-Mortem

paladin council --mode sequential --roles "sre,security,engineering,management" "
Post-mortem for database outage:

Incident:
- 2-hour downtime
- Caused by failed migration
- No rollback plan
- Manual recovery

Questions:
- What went wrong?
- How to prevent?
- Process improvements?
"

Example 6: Code Review Perspectives

paladin council --roles "security,performance,maintainability,testing" "
Review this architecture decision:

Plan to use Redis for:
- Session storage
- Cache layer  
- Message queue
- Rate limiting

Is this appropriate?
"

Troubleshooting

Common Issues

Issue: Responses are too generic

Solution:

# Provide more context
paladin council "Question with detailed context: ..."

# Use more specific roles
paladin council --roles "senior-architect,principal-engineer" "..."

# Try sequential mode for depth
paladin council --mode sequential "..."

Issue: Conflicting perspectives without resolution

Solution:

# Ensure synthesis is enabled (default)
paladin council --synthesize "..."

# Use debate mode for structured comparison
paladin council --mode debate "..."

# Do a follow-up round
paladin council "Based on previous discussion, recommend best approach"

Issue: Timeout before completion

Solution:

# Increase timeout
paladin council --timeout 300 "complex question"

# Reduce number of agents
paladin council -n 3 "..."

# Use parallel mode (faster)
paladin council --mode parallel "..."

# Reduce max tokens per response
paladin council --max-tokens 300 "..."

Issue: Not enough detail in responses

Solution:

# Increase max tokens
paladin council --max-tokens 1000 "detailed analysis needed"

# Ask more specific questions
paladin council "Specific aspect of broader topic"

# Use higher temperature for creativity
paladin council --temperature 1.0 "creative problem-solving"

Issue: Agent perspectives are too similar

Solution:

# Use more diverse roles
paladin council --roles "conservative,progressive,radical,pragmatic" "..."

# Try debate mode
paladin council --mode debate "..."

# Increase temperature
paladin council --temperature 1.2 "diverse viewpoints needed"

Debugging

# Enable verbose mode to see execution details
paladin council --verbose "..."

# Test with simpler question first
paladin council "Hello, how are you?" -n 2

# Check provider configuration
paladin setup-check

# Try different provider
paladin council --provider deepseek "..."

Advanced Usage

Combining with Other Commands

# Generate config, then discuss it
paladin muster "workflow" -o workflow.yaml
paladin council "Review this workflow config: $(cat workflow.yaml)"

# Council for planning, then execute
paladin council "Best approach for task X" -o plan.md
# Review plan.md
paladin run -c final_approach.yaml

Batch Processing

# Multiple questions from file
while IFS= read -r question; do
    paladin council "$question" -o "output_$(echo "$question" | md5sum | cut -c1-8).md"
done < questions.txt

# Different role combinations
for roles in "tech,security" "business,legal" "ux,product"; do
    paladin council --roles "$roles" "Same question" -o "perspective_${roles}.md"
done

Custom Synthesis

# Get detailed JSON output
paladin council -f json -o raw.json "Complex decision"

# Process with jq or custom script
jq '.responses[].key_points[]' raw.json > all_points.txt

# Feed back for meta-analysis
paladin council "Synthesize these points: $(cat all_points.txt)"

Integration with Scripts

#!/usr/bin/env python3
import subprocess
import json

def council_discussion(question, roles, mode="parallel"):
    result = subprocess.run([
        "paladin", "council",
        "--format", "json",
        "--mode", mode,
        "--roles", roles,
        question
    ], capture_output=True, text=True)

    return json.loads(result.stdout)

# Use in automation
discussion = council_discussion(
    "Should we proceed with migration?",
    "technical,business,security",
    mode="sequential"
)

# Extract recommendations
recommendations = discussion["synthesis"]["recommendations"]
print(f"Recommendations: {recommendations}")

Performance Tips

See Also

• CLI Usage Guide - Overview of all CLI commands
• Muster Command - Generate full Battalion configurations
• Conclave Pattern - Detailed council/conclave documentation
• Battalion Patterns - Understanding orchestration patterns
• Examples Directory - Sample implementations

Support

• Issues: Report bugs at https://github.com/yourusername/paladin/issues
• Discussions: Ask questions in GitHub Discussions
• Documentation: Full docs at https://paladin-ai.dev

Council discussions are ephemeral and don't persist state. For production workflows with state management, use paladin run with configuration files.