Council - Multi-Model Plan Review with Iterative Refinement

Get your plans reviewed by Gemini-3-Pro and GPT-5.2 via OpenCode in parallel. Council supports iterative refinement where you orchestrate multiple rounds until consensus.

Triggers

• /council - review most recent plan from ~/.claude/plans/
• /council <file.md> - review specified file
• "review this plan", "fact-check", "get council feedback"

Iterative Refinement Process

Council automatically iterates until consensus or max 10 rounds.

Your Role (Claude)

You orchestrate the refinement loop autonomously until consensus:

Iteration Phase (Claude + Models):

1. Review: Call council review plan.md
2. Evaluate: For each agent's feedback, decide:
   • Accept: Valid issue that improves the plan
   • Reject: Already handled, not applicable, or preference
   • Clarify: Use council discuss to ask follow-up
3. Discuss rejections: Use council discuss to explain rejected feedback
4. Revise: Update plan based on accepted feedback (Write tool)
5. Repeat: Call council review again with revised plan
6. Continue until all models approve (consensus reached)

User Review Phase (After Consensus): 7. Present each decision to user: Use AskUserQuestion with multiSelect:

• Show each accepted change with reasoning - user can Keep/Remove
• Show each rejected feedback with reasoning - user can Keep rejected/Include

8. Apply user's final decisions:
   • Revise plan based on user overrides
   • Present final plan
9. User final approval:
   • Accept: Proceed to GitHub issue creation
   • More changes needed: Discuss and revise
   • Start over: New approach

GitHub Issue Creation (After User Approval): 10. Check if in GitHub repo: - Run: git rev-parse --git-dir - Run: git remote get-url origin (check for GitHub remote) 11. Create GitHub issue with final plan: - Claude decides appropriate title based on plan content - For features: "Add [feature]" or "Implement [feature]" - For bugs: "Fix [issue]" - For refactoring: "Refactor [component]" - Run: gh issue create --title "[AI-generated title]" --body-file plan.md - No labels or assignees (keep simple) - Show user the issue URL 12. Begin implementation with issue for tracking

Evaluation Guidelines

Claude (you) parses verdicts using AI reasoning, not string matching.

For EACH agent's output:

1. Read the full response and determine if they approved or raised concerns
2. Categorize feedback as Accept/Reject based on validity

Accept if:

• Identifies a gap in the plan
• Raises a valid error case not covered
• Suggests concrete improvement with clear benefit

Reject if:

• Plan already addresses this (explain where)
• Theoretical concern with no practical impact
• Style/structure preference without functional issue
• Contradicts user requirements

Always explain your reasoning when rejecting feedback.

Detecting approval:

• Use your judgment to determine if an agent approved
• Don't rely on keywords - understand the full context
• "Cannot approve" = not approved
• "Looks good" = approved (unless they raise concerns)

Anti-Laziness Check

If consensus happens before round 3:

1. Check feedback quality: Did agents provide specific, detailed critiques?
2. If vague ("looks good", no specifics): Call council review --press
3. If substantive: Accept consensus, they really reviewed it

Example vague approval to press:

"The plan is well-structured and comprehensive."

Example substantive approval to accept:

"Reviewed all 7 steps:
- Step 3: Error handling covers timeout, network, and auth failures
- Step 5: Rollback strategy is clear and atomic
- All edge cases addressed in steps 4-6
No remaining concerns."

Deciding Consensus

Consensus = All models approve (you parse and decide)

Stop iterating when ONE of these is true:

1. All models approve (you read their outputs and determine consensus) - Present to user
2. Reached 10 rounds - Present current state to user, ask if they want to continue
3. Need clarification on requirements - Ask user, then resume

IMPORTANT: If you reject model feedback, discuss it first:

Gemini raised: "Add rate limiting"
Your reasoning: "Rate limiting isn't needed - we have a single client with controlled request rate"

Next step: council discuss "I don't think rate limiting is needed because we have a single client with controlled request rate. Do you still think this is necessary?"

Wait for model response. If they accept your reasoning, they'll approve in next round.
If they push back with valid reasoning, accept the feedback and revise.

After consensus, present each decision to user for review:

Use AskUserQuestion with multiSelect to present evaluation decisions:

## Council Review Complete (4 rounds)

Please review each decision. You can accept my recommendations or override:

Questions:
1. "Added error handling for API timeouts (Gemini, Round 1)"
   - Accepted because: Missing timeout handling could cause hanging
   - Options: Keep / Remove

2. "Clarified retry logic (GPT, Round 1)"
   - Accepted because: Ambiguous about exponential backoff
   - Options: Keep / Remove

3. "Added rate limit handling (GPT, Round 2)"
   - Accepted because: API has 100 req/min limit we weren't handling
   - Options: Keep / Remove

4. "Database connection pooling suggestion (Gemini, Round 2)"
   - Rejected because: Already configured in step 4
   - Options: Keep rejected / Include anyway

5. "Verbose logging suggestion (GPT, Round 3)"
   - Rejected because: Style preference, not a functional gap
   - Options: Keep rejected / Include anyway

Based on user's selections:

• Apply final changes to plan
• If user overrides any rejections: add those changes
• If user removes any acceptances: revert those changes
• Present final plan for confirmation

Commands

# Install session hook and check dependencies
council setup

# Start a review (uses most recent plan if no file specified)
council review
council review ~/path/to/plan.md

# Continue with press prompt (anti-laziness check)
council review --press plan.md

# Discuss with reviewers (auto-continues session)
council discuss "Can you elaborate on the first issue?"

# Continue a review conversation (explicit session ID)
council continue <session-id> "Here's more context..."

# Check session status
council status
council status <session-id>

# Clean up old sessions (default: 7 days)
council cleanup [days]

# Show help
council help

Session ID Format

Session IDs follow the pattern: session-<timestamp>-<hex> (e.g., session-1704067200000-a1b2c3d4e5f6)

Session Mapping

Council automatically maps Claude Code sessions to council sessions:

• SessionStart Hook: Captures Claude's session ID via $CLAUDE_SESSION_ID
• Mapping Storage: ~/.council/session-map.json stores Claude → Council mappings
• Auto-Detection: council discuss automatically continues your current session

Setup Required: Run council setup to install the SessionStart hook automatically. This creates ~/.claude/hooks/get-session-id.sh and registers it in ~/.claude/settings.json.

Usage:

# In any Claude Code session, run a review
council review my-plan.md

# Later in the SAME Claude session, discuss automatically
council discuss "Can you elaborate on point 1?"

# The command automatically:
# 1. Reads CLAUDE_SESSION_ID env var
# 2. Looks up your council session
# 3. Continues with the right OpenCode sessions

Multiple Sessions: If you have multiple Claude Code sessions in the same project directory:

• Each session has its own CLAUDE_SESSION_ID
• Each maps to its own council session
• No conflicts even in shared directories

JSON Output Schema

Review Output (stdout)

{
  "sessionId": "session-1704067200000-a1b2c3d4e5f6",
  "file": "/path/to/plan.md",
  "round": 1,
  "results": {
    "gemini-3-pro": "... review output ...",
    "gpt-5-2": "... review output ..."
  },
  "errors": {
    "agentName": "error message"
  }
}

Key fields:

• round: Current round number (starts at 1)
• results: Raw agent outputs
• You parse verdicts using AI and decide when consensus is reached

Note: errors field only present if errors occurred. Progress messages go to stderr.

Session Auto-Continuation:

• Round 1: council review plan.md - creates new session
• Round 2: council review plan.md (revised) - auto-continues session with context
• Models see their previous critique and can verify fixes

Status Output

{
  "sessions": [
    {
      "id": "session-...",
      "file": "/path/to/plan.md",
      "startedAt": "2024-01-01T00:00:00.000Z",
      "agents": ["gemini-3-pro", "gpt-5-2"]
    }
  ]
}

Output Format

Present to the user after each round:

• Round number and session ID
• Each agent's verdict + key issues
• Your synthesis of what's valid/actionable
• Your accept/reject decisions with reasoning
• Next steps (revise, discuss, or consensus reached)

Critical Framing

• Gemini-3-Pro and GPT-5.2 are peers giving feedback, not blocking reviewers
• Use your own judgment on their comments - don't accept everything blindly
• Council provides diverse perspectives; you decide what's valid
• Iterate: revise plan, re-review until consensus

Session Mapping

Council automatically maps Claude Code sessions to council sessions:

• SessionStart Hook: Captures Claude's session ID via $CLAUDE_SESSION_ID
• Mapping Storage: ~/.council/session-map.json stores Claude -> Council mappings
• Auto-Detection: council review and council discuss automatically continue your session

Error Handling

• If a reviewer times out or errors, the errors field will contain details
• Set COUNCIL_DEBUG=1 for stack traces in errors
• Errors indicate bugs that need investigation - don't silently recover

Example Workflow

Round 1:
- Call: council review plan.md
- Gemini: "Missing error handling for API timeout"
- GPT: "Step 3 is ambiguous about retry logic"
- Evaluate: Both valid
- Revise: Add timeout handling and clarify retries
- Write updated plan.md

Round 2:
- Call: council review plan.md (again)
- Gemini: "Error handling looks good now"
- GPT: "Retry logic is clear. One minor: what about rate limits?"
- Evaluate: Rate limit concern valid
- Revise: Add rate limit handling

Round 3:
- Call: council review plan.md
- Gemini: "All good now"
- GPT: "Still concerned about database connection pooling"
- Evaluate: Gemini vague (press), GPT raises new concern
- Call: council review --press (for Gemini)
- Call: council discuss "Regarding connection pooling - our pool size is configurable in the DB client, detailed in step 4. Is this sufficient?" (for GPT)

Round 4:
- Call: council review plan.md (auto-continues session with context)
- Gemini (pressed): "Confirmed - reviewed all error cases, retry logic, rate limits. Ready."
- GPT (discussed): "Yes, if it's configurable that addresses my concern. Approved."
- **You parse:** Both approve
- Consensus reached!

Present to User (AskUserQuestion with individual decisions):
1. "Error handling for timeouts" - Keep/Remove
2. "Retry logic clarification" - Keep/Remove
3. "Rate limit handling" - Keep/Remove
4. "Connection pooling (rejected)" - Keep rejected/Include
5. "Verbose logging (rejected)" - Keep rejected/Include

User reviews each decision individually
-> Apply final changes based on user selections
-> Show final plan
-> User approves

GitHub Issue Creation:
-> Check: `git rev-parse --git-dir` && `git remote get-url origin | grep github`
-> Claude generates title: "Add iterative refinement feature"
-> Create: `gh issue create --title "[generated]" --body-file plan.md`
-> No labels/assignees
-> Show issue URL

-> Begin implementation