Skip to content

feat(council): Add adaptive rounds, file-first output, and recovery mode #567

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
A13xSM wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(council): Add adaptive rounds, file-first output, and recovery mode #567

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fb08087
feat(council): Add adaptive rounds, file-first output, and recovery mode
A13xSM Feb 3, 2026
fa93861
fix(council): Address Copilot review feedback
A13xSM Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 44 additions & 18 deletions Packs/pai-council-skill/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
name: PAI Council Skill
pack-id: danielmiessler-pai-council-skill-v2.3.0
version: 2.3.0
pack-id: danielmiessler-pai-council-skill-v2.5.0
version: 2.5.0
author: danielmiessler
description: Multi-agent debate system where specialized agents discuss topics in rounds, respond to each other's points, and surface insights through intellectual friction.
description: Multi-agent debate system where specialized agents discuss topics in rounds, respond to each other's points, and surface insights through intellectual friction. Now with adaptive rounds, file-first output, and recovery mode.
type: skill
purpose-type: [decision-making, collaboration, multi-agent, debate, synthesis]
purpose-type: [decision-making, collaboration, multi-agent, debate, synthesis, recovery, resilience]
platform: claude-code
dependencies: [pai-core-install]
keywords: [council, debate, multi-agent, perspectives, synthesis, decision, architect, designer, engineer, researcher]
keywords: [council, debate, multi-agent, perspectives, synthesis, decision, architect, designer, engineer, researcher, recovery, adaptive, patchlist]
---

<p align="center">
Expand All @@ -25,11 +25,15 @@ keywords: [council, debate, multi-agent, perspectives, synthesis, decision, arch

## What This Pack Provides

- **Multi-Agent Debate System** - Structured 3-round debates between specialized agents
- **Multi-Agent Debate System** - Structured 2-3 round debates between specialized agents
- **Adaptive Rounds** - Round 3 runs only when needed based on convergence detection
- **File-First Output** - Session state persists to `~/.claude/MEMORY/` for resilience
- **Recovery Mode** - Resume interrupted sessions from checkpoint
- **Quick Consensus Check** - Fast single-round perspective gathering
- **Council Members** - Architect, Designer, Engineer, Researcher (with optional Security, Intern, Writer)
- **Visible Transcripts** - Full conversation history showing intellectual friction
- **Synthesis Engine** - Convergence detection and recommendation generation
- **Output Modes** - Deliberative (conversational) or Patchlist (structured changes)
- **Model Tiering** - Automatic model selection per round for cost efficiency

## Key Differentiator

Expand All @@ -44,20 +48,23 @@ keywords: [council, debate, multi-agent, perspectives, synthesis, decision, arch
```
Council Skill
├── SKILL.md # Main entry point and routing
├── Config.md # Default settings, model tiering, output modes
├── CouncilMembers.md # Agent roles, perspectives, voices
├── RoundStructure.md # 3-round debate structure
├── RoundStructure.md # Round structure and timing
├── OutputFormat.md # Transcript format templates
└── Workflows/
├── Debate.md # Full 3-round structured debate
└── Quick.md # Fast single-round check
├── Debate.md # Full 2-3 round structured debate (adaptive)
├── Quick.md # Fast single-round check
└── Recovery.md # Resume interrupted sessions
```

## Workflows

| Workflow | Purpose | Rounds | Output |
|----------|---------|--------|--------|
| **DEBATE** | Full structured discussion | 3 | Complete transcript + synthesis |
| **DEBATE** | Full structured discussion | 2-3 (adaptive) | Complete transcript + synthesis |
| **QUICK** | Fast perspective check | 1 | Initial positions only |
| **RECOVERY** | Resume interrupted session | Remaining | Continue from checkpoint |

## Default Council Members

Expand All @@ -68,37 +75,47 @@ Council Skill
| **Engineer** | Implementation reality, tech debt | Marcus Webb |
| **Researcher** | Data, precedent, external examples | Ava Chen |

## Three-Round Debate Structure
## Adaptive Round Debate Structure

1. **Round 1 - Initial Positions**: Each agent states their perspective
2. **Round 2 - Responses & Challenges**: Agents respond to each other's points
3. **Round 3 - Synthesis**: Identify convergence, disagreements, final recommendations
1. **Round 1 - Initial Positions**: Each agent states their perspective (sonnet)
2. **Round 2 - Responses & Challenges**: Agents respond to each other's points (haiku)
3. **Round 3 - Synthesis** (conditional): Only runs if low convergence or blocking issues (sonnet)

**Total Time:** 30-90 seconds for full debate (parallel execution within rounds)
**Convergence Check:** After Round 2, the orchestrator evaluates whether agents have reached consensus. Round 3 is skipped if 3+ agents agree and no blocking issues remain.

**Total Time:** 20-60 seconds (2 rounds) or 30-90 seconds (3 rounds)

## Usage Examples

```
"Council: Should we use WebSockets or SSE?"
-> Invokes DEBATE workflow -> 3-round transcript
-> Invokes DEBATE workflow -> 2-3 round transcript

"Quick council check: Is this API design reasonable?"
-> Invokes QUICK workflow -> Fast perspectives

"Council with security: Evaluate this auth approach"
-> DEBATE with Security agent added

"Council (patchlist): Review these specifications"
-> DEBATE with structured output format

"Council recovery: Resume session 20260202-143052-a1b2c3d4"
-> RECOVERY workflow -> Continue from checkpoint
```

## What's Included

| Component | File | Purpose |
|-----------|------|---------|
| Main Skill | src/skills/Council/SKILL.md | Entry point and workflow routing |
| Configuration | src/skills/Council/Config.md | Default settings, model tiering, output modes |
| Council Members | src/skills/Council/CouncilMembers.md | Agent roles and voice mapping |
| Round Structure | src/skills/Council/RoundStructure.md | Debate timing and phases |
| Output Format | src/skills/Council/OutputFormat.md | Transcript templates |
| Debate Workflow | src/skills/Council/Workflows/Debate.md | Full 3-round debate |
| Debate Workflow | src/skills/Council/Workflows/Debate.md | Full 2-3 round adaptive debate |
| Quick Workflow | src/skills/Council/Workflows/Quick.md | Fast consensus check |
| Recovery Workflow | src/skills/Council/Workflows/Recovery.md | Resume interrupted sessions |

## Integration

Expand All @@ -115,6 +132,15 @@ Council Skill

## Changelog

### 2.5.0 - 2026-02-02
- **Adaptive Rounds** - Round 3 now conditional based on convergence detection
- **File-First Output** - Session state persists to `~/.claude/MEMORY/` for resilience against context compaction and rate limits
- **Recovery Workflow** - Resume interrupted sessions with partial or full rerun options
- **Config.md** - Centralized configuration for rounds, agents, output modes, and model tiering
- **Output Modes** - Added `patchlist` mode for structured specification reviews
- **Model Tiering** - Automatic model selection (sonnet/haiku) per round for cost efficiency
- **Scope Limits** - Guidance on max items per council to prevent token explosion

### 2.3.0 - 2026-01-14
- Initial public release
- Complete debate and quick workflows
Expand Down
126 changes: 126 additions & 0 deletions Packs/pai-council-skill/src/skills/Council/Config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# Council Configuration

Default configuration for Council debates. These values can be overridden per-session by specifying config inline with the council request.

## Debate Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `rounds` | 2-3 (adaptive) | Round 3 runs only if convergence is low after Round 2 |
| `agents` | 4 | Default: Architect, Designer, Engineer, Researcher |
| `output_mode` | `deliberative` | Options: `deliberative` (conversational), `patchlist` (structured changes) |
| `file_output` | `true` | Write each round to `~/.claude/MEMORY/` |

## Model Tiering

| Phase | Model | Rationale |
|-------|-------|-----------|
| Round 1 | sonnet | Initial positions need nuance |
| Round 2 | haiku | Responses are shorter, more constrained |
| Round 3 | sonnet | Synthesis needs quality |
| Final Synthesis | sonnet | Orchestrator synthesis |

To use a specific model, add `model: "haiku"` or `model: "sonnet"` to the Task call.

## Adaptive Round 3

Round 3 is **conditional**. After Round 2, the orchestrator evaluates:

**Run Round 3 if ANY of these are true:**
1. Agents express explicit disagreement in Round 2
2. Round 2 responses identify BLOCKING issues
3. The topic involves security, compliance, or irreversible decisions
4. User explicitly requested 3 rounds

**Skip Round 3 if ALL of these are true:**
1. High convergence detected (majority of agents agree on core recommendation)
2. No BLOCKING items identified
3. No unresolved contradictions
4. Topic is exploratory, not normative

When skipping Round 3, output:
```markdown
**Round 3 skipped:** High convergence detected. Proceeding to synthesis.
```

## Output Modes

### Deliberative (default)
Conversational format for architectural debates, design decisions, exploratory discussions.

```markdown
### Round N: [Phase Name]

**🏛️ Architect (Serena):**
[Prose response, 50-150 words]
```

### Patchlist
Structured format for TaskSpec reviews, document improvements, code changes.

```markdown
### Round N: [Phase Name]

**🏛️ Architect (Serena):**

**BLOCKING:**
- B1: [issue] → [proposed change] | Affects: [specs]

**HIGH:**
- H1: [issue] → [proposed change]

**MEDIUM/LOW:**
- M1: [issue]
```

To invoke patchlist mode: `"Council (patchlist): Review these TaskSpecs..."`

## File Output Location

When `file_output` is enabled (default), rounds are written to:

```
~/.claude/MEMORY/STATE/council-sessions/{session-id}/
├── metadata.json # Topic, members, timing, config
├── round-1.md # All Round 1 responses
├── round-2.md # All Round 2 responses
├── round-3.md # Round 3 (if run)
└── convergence.json # Convergence assessment after Round 2
```

After synthesis, the final output is archived to:
```
~/.claude/MEMORY/RESEARCH/YYYY-MM/
└── YYYY-MM-DD-HHMMSS_COUNCIL_{topic-slug}.md
```

This enables:
- **Recovery** from interrupted sessions (partial round data preserved)
- **Cross-session context** (prior council findings available)
- **Resistance to context compaction** (durable external state)

## Scope Limits

To prevent token explosion and rate-limit issues:

| Limit | Value | Rationale |
|-------|-------|-----------|
| Max items per council | 5 | TaskSpecs, documents, or topics |
| Max agents | 7 | Diminishing returns beyond this |
| Max words per response | 150 | Prevents verbose agents |

For larger reviews, run multiple councils with a shared context preamble.

## Recovery Mode

If a council session is interrupted (rate limit, timeout, crash), use the Recovery workflow:

```
"Council recovery: Resume session {session-id}"
```

See `Workflows/Recovery.md` for details.

---

**Last Updated:** 2026-02-02
34 changes: 27 additions & 7 deletions Packs/pai-council-skill/src/skills/Council/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,20 @@ science_cycle_time: meso

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.

## Configuration

Load `Config.md` for default settings:
- **Adaptive rounds:** 2-3 based on convergence
- **File output:** Enabled by default (writes to `~/.claude/MEMORY/`)
- **Model tiering:** sonnet for Round 1/3, haiku for Round 2
- **Output modes:** `deliberative` (default) or `patchlist`

# Council Skill

Multi-agent debate system where specialized agents discuss topics in rounds, respond to each other's points, and surface insights through intellectual friction.

**Key Differentiator from RedTeam:** Council is collaborative-adversarial (debate to find best path), while RedTeam is purely adversarial (attack the idea). Council produces visible conversation transcripts; RedTeam produces steelman + counter-argument.


## Voice Notification

**When executing a workflow, do BOTH:**
Expand Down Expand Up @@ -50,42 +57,53 @@ Running the **WorkflowName** workflow from the **Council** skill...

| Trigger | Workflow |
|---------|----------|
| Full structured debate (3 rounds, visible transcript) | `Workflows/Debate.md` |
| Full structured debate (2-3 rounds, visible transcript) | `Workflows/Debate.md` |
| Quick consensus check (1 round, fast) | `Workflows/Quick.md` |
| Resume interrupted session | `Workflows/Recovery.md` |
| Pure adversarial analysis | RedTeam skill |

## Quick Reference

| Workflow | Purpose | Rounds | Output |
|----------|---------|--------|--------|
| **DEBATE** | Full structured discussion | 3 | Complete transcript + synthesis |
| **DEBATE** | Full structured discussion | 2-3 (adaptive) | Complete transcript + synthesis |
| **QUICK** | Fast perspective check | 1 | Initial positions only |
| **RECOVERY** | Resume interrupted session | Remaining | Continue from last checkpoint |

## Context Files

| File | Content |
|------|---------|
| `Config.md` | Default settings, model tiering, output modes |
| `CouncilMembers.md` | Agent roles, perspectives, voice mapping |
| `RoundStructure.md` | Three-round debate structure and timing |
| `RoundStructure.md` | Adaptive 2-3 round structure and timing |
| `OutputFormat.md` | Transcript format templates |

## Core Philosophy

**Origin:** Best decisions emerge from diverse perspectives challenging each other. Not just collecting opinions - genuine intellectual friction where experts respond to each other's actual points.

**Speed:** Parallel execution within rounds, sequential between rounds. A 3-round debate of 4 agents = 12 agent calls but only 3 sequential waits. Complete in 30-90 seconds.
**Speed:** Parallel execution within rounds, sequential between rounds. A 2-round debate of 4 agents = 8 agent calls but only 2 sequential waits. Complete in 20-60 seconds.

**Resilience:** File-first output means session state survives context compaction and rate limits.

## Examples

```
"Council: Should we use WebSockets or SSE?"
-> Invokes DEBATE workflow -> 3-round transcript
-> Invokes DEBATE workflow -> 2-3 round transcript

"Quick council check: Is this API design reasonable?"
-> Invokes QUICK workflow -> Fast perspectives

"Council with security: Evaluate this auth approach"
-> DEBATE with Security agent added

"Council (patchlist): Review these specifications"
-> DEBATE with structured output format

"Council recovery: Resume session 20260202-143052-a1b2c3d4"
-> RECOVERY workflow -> Continue from checkpoint
```

## Integration
Expand All @@ -101,7 +119,9 @@ Running the **WorkflowName** workflow from the **Council** skill...
2. Add domain-specific experts as needed (security for auth, etc.)
3. Review the transcript - insights are in the responses, not just positions
4. Trust multi-agent convergence when it occurs
5. Use patchlist mode for specification reviews
6. For large reviews (5+ items), run multiple councils with shared context

---

**Last Updated:** 2025-12-20
**Last Updated:** 2026-02-02
Loading