agileflow 3.4.2 → 4.0.0-alpha.1

package/src/core/commands/council.md

@@ -1,592 +0,0 @@
----
-description: Convene AI Council for strategic decisions with three perspectives (Optimist, Advocate, Analyst)
-phase: planning
-argument-hint: "<question> [--mode parallel|debate] [--rounds N]"
-compact_context:
-  priority: high
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:council - AI Council for strategic decisions"
-    - "CRITICAL: Deploy ALL 3 council agents in SINGLE message with parallel Task calls"
-    - "MUST wait for all agents via TaskOutput with block=true before synthesis"
-    - "Council members: council-optimist, council-advocate, council-analyst"
-    - "Modes: parallel (default, single round) or debate (multi-round deliberation)"
-    - "Session folder: .agileflow/council/sessions/{timestamp}/"
-  state_fields:
-    - session_id
-    - question
-    - mode
-    - rounds
-    - council_results
----
-
-# /agileflow:council
-
-Convene an AI Council for strategic decisions. Three perspectives (Optimist, Devil's Advocate, Neutral Analyst) deliberate in parallel to provide balanced, high-quality recommendations.
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:council` - Deploy 3-perspective AI Council for strategic decisions
-
-**Magic Phrases**: "agents gather", "council assemble", "convene the council"
-
-**Quick Usage**:
-```
-/agileflow:council Should we adopt microservices architecture?
-/agileflow:council --mode debate --rounds 2 Is GraphQL better than REST for our API?
-```
-
-**Council Members**:
-| Role | Agent | Focus |
-|------|-------|-------|
-| Optimist Strategist | council-optimist | Best-case scenarios, opportunities, success pathways |
-| Devil's Advocate | council-advocate | Risks, blind spots, stress-testing assumptions |
-| Neutral Analyst | council-analyst | Trade-offs, evidence synthesis, decision criteria |
-
-**Modes**:
-- **parallel** (default): All 3 agents deliberate once, then synthesize
-- **debate**: Multiple rounds where agents respond to each other's perspectives
-
-**Critical Rules**:
-- Deploy ALL 3 agents in ONE message with multiple Task calls (not sequential)
-- Wait for all results before synthesis (use TaskOutput with block=true)
-- Create session folder in `.agileflow/council/sessions/{timestamp}/`
-- Write perspectives to `shared_reasoning.md` in session folder
-
-**Output Structure**:
-```markdown
-## AI Council Deliberation: [Question]
-
-### Perspectives
-- Optimist: [summary]
-- Advocate: [summary]
-- Analyst: [summary]
-
-### Synthesis
-- Common Ground: [what all agree on]
-- Key Tensions: [where they differ]
-- Recommendation: [decision with confidence]
-
-### Next Steps
-1. [action]
-2. [action]
-```
-
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## When to Use
-
-The AI Council is designed for **strategic, non-technical decisions** where balanced perspectives matter:
-
-- **Architecture decisions**: "Should we adopt microservices?"
-- **Technology choices**: "GraphQL vs REST for our API?"
-- **Process decisions**: "Should we implement feature flags?"
-- **Business tradeoffs**: "Build vs buy for this feature?"
-- **Strategy questions**: "Should we prioritize mobile or web?"
-
-**NOT for**:
-- Code implementation (use domain experts)
-- Simple questions with clear answers
-- Tasks requiring codebase changes
-- Research tasks (use `/agileflow:research:ask`)
-
----
-
-## How It Works
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    USER QUESTION                             │
-│          "Should we adopt microservices?"                    │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    COUNCIL ORCHESTRATOR                      │
-│  1. Create session: .agileflow/council/sessions/{ts}/        │
-│  2. Initialize shared_reasoning.md from template             │
-│  3. Log to bus: {"type":"council","event":"init"}           │
-│  4. Deploy 3 agents IN PARALLEL                              │
-└─────────────────────────────────────────────────────────────┘
-                            │
-            ┌───────────────┼───────────────┐
-            ▼               ▼               ▼
-    ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
-    │   OPTIMIST    │ │   ADVOCATE    │ │   ANALYST     │
-    │   STRATEGIST  │ │ (Devil's Adv) │ │   (Neutral)   │
-    ├───────────────┤ ├───────────────┤ ├───────────────┤
-    │ Opportunities │ │ Risks         │ │ Trade-offs    │
-    │ Success paths │ │ Blind spots   │ │ Evidence      │
-    │ Enablers      │ │ Stress tests  │ │ Criteria      │
-    │ Best case     │ │ Mitigations   │ │ Synthesis     │
-    └───────────────┘ └───────────────┘ └───────────────┘
-            │               │               │
-            └───────────────┼───────────────┘
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    SYNTHESIS                                 │
-│  • Common Ground (all 3 agree) = HIGH CONFIDENCE             │
-│  • Optimist Unique = OPPORTUNITIES                           │
-│  • Advocate Unique = RISKS TO MONITOR                        │
-│  • Analyst Assessment = RECOMMENDATION                       │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    FINAL OUTPUT                              │
-│  📊 Confidence: High/Medium/Low                              │
-│  ✅ Common Ground (all agree)                                │
-│  🚀 Opportunities (optimist)                                 │
-│  ⚠️ Risks (advocate)                                         │
-│  📋 Recommendation (analyst)                                 │
-│  📌 Next Steps                                               │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Usage
-
-### Basic (Parallel Mode)
-
-```
-/agileflow:council Should we adopt microservices architecture?
-```
-
-All 3 council members deliberate once in parallel, then results are synthesized.
-
-### Debate Mode
-
-```
-/agileflow:council --mode debate --rounds 2 Should we use GraphQL?
-```
-
-Multiple rounds where council members can respond to each other's perspectives:
-1. Round 1: Initial perspectives
-2. Round 2: Responses and rebuttals
-3. Final synthesis
-
-### Magic Phrases
-
-You can also invoke the council with natural language:
-- "agents gather" + question
-- "council assemble" + question
-- "convene the council" + question
-
-Example: "Agents gather - should we implement feature flags?"
-
----
-
-## Arguments
-
-| Argument | Default | Description |
-|----------|---------|-------------|
-| `<question>` | (required) | The strategic question to deliberate |
-| `--mode` | `parallel` | Deliberation mode: `parallel` or `debate` |
-| `--rounds` | `1` | Number of rounds for debate mode (1-3) |
-
----
-
-## Orchestration Instructions
-
-When this command is invoked:
-
-### STEP 1: Create Session
-
-```bash
-# Create session folder with timestamp
-SESSION_ID=$(date +%Y%m%d-%H%M%S)
-mkdir -p .agileflow/council/sessions/$SESSION_ID
-```
-
-Initialize `shared_reasoning.md` from template:
-- Replace `{{session_id}}` with timestamp
-- Replace `{{question}}` with user question
-- Replace `{{mode}}` with parallel or debate
-- Replace `{{rounds}}` with number
-
-### STEP 2: Log to Bus
-
-Append to `docs/09-agents/bus/log.jsonl`:
-```jsonl
-{"ts":"<ISO>","type":"council","event":"init","session_id":"<SESSION_ID>","question":"<QUESTION>","mode":"<MODE>"}
-```
-
-### STEP 3: Deploy Council (CRITICAL - PARALLEL)
-
-Deploy ALL 3 agents in a SINGLE message with multiple Task calls:
-
-```xml
-<invoke name="Task">
-  <parameter name="description">Council Optimist perspective</parameter>
-  <parameter name="prompt">
-You are the Optimist Strategist in an AI Council deliberation.
-
-SESSION: .agileflow/council/sessions/{SESSION_ID}/
-QUESTION: {QUESTION}
-
-Read your agent definition first:
-- .agileflow/agents/council-optimist.md
-
-Then write your perspective to:
-- .agileflow/council/sessions/{SESSION_ID}/shared_reasoning.md
-
-Focus on:
-1. Key opportunities (at least 3)
-2. Success pathways
-3. Enablers in the codebase
-4. Addressing anticipated concerns
-
-Ground all optimism in evidence.
-  </parameter>
-  <parameter name="subagent_type">agileflow-council-optimist</parameter>
-  <parameter name="run_in_background">true</parameter>
-</invoke>
-
-<invoke name="Task">
-  <parameter name="description">Council Advocate perspective</parameter>
-  <parameter name="prompt">
-You are the Devil's Advocate in an AI Council deliberation.
-
-SESSION: .agileflow/council/sessions/{SESSION_ID}/
-QUESTION: {QUESTION}
-
-Read your agent definition first:
-- .agileflow/agents/council-advocate.md
-
-Then write your perspective to:
-- .agileflow/council/sessions/{SESSION_ID}/shared_reasoning.md
-
-Focus on:
-1. Key risks (at least 3 with mitigations)
-2. Blind spots and assumptions
-3. Stress tests and edge cases
-4. Alternative approaches
-
-Be constructive - offer solutions, not just criticism.
-  </parameter>
-  <parameter name="subagent_type">agileflow-council-advocate</parameter>
-  <parameter name="run_in_background">true</parameter>
-</invoke>
-
-<invoke name="Task">
-  <parameter name="description">Council Analyst perspective</parameter>
-  <parameter name="prompt">
-You are the Neutral Analyst in an AI Council deliberation.
-
-SESSION: .agileflow/council/sessions/{SESSION_ID}/
-QUESTION: {QUESTION}
-
-Read your agent definition first:
-- .agileflow/agents/council-analyst.md
-
-Then write your perspective to:
-- .agileflow/council/sessions/{SESSION_ID}/shared_reasoning.md
-
-Focus on:
-1. Evidence summary (for and against)
-2. Trade-off analysis with quantification
-3. Decision criteria
-4. Synthesis and recommendation
-
-Be objective - follow the evidence.
-  </parameter>
-  <parameter name="subagent_type">agileflow-council-analyst</parameter>
-  <parameter name="run_in_background">true</parameter>
-</invoke>
-```
-
-### STEP 4: Collect Results
-
-Wait for all 3 agents to complete:
-
-```xml
-<invoke name="TaskOutput">
-  <parameter name="task_id">{optimist_task_id}</parameter>
-  <parameter name="block">true</parameter>
-</invoke>
-
-<invoke name="TaskOutput">
-  <parameter name="task_id">{advocate_task_id}</parameter>
-  <parameter name="block">true</parameter>
-</invoke>
-
-<invoke name="TaskOutput">
-  <parameter name="task_id">{analyst_task_id}</parameter>
-  <parameter name="block">true</parameter>
-</invoke>
-```
-
-### STEP 5: Debate Mode (If Applicable)
-
-If mode is `debate` and rounds > 1, for each additional round:
-
-1. Log round start: `{"type":"council","event":"debate_round","round":N}`
-2. Have each agent read others' perspectives and respond
-3. Collect updated responses
-4. Repeat for specified rounds
-
-### STEP 6: Synthesize
-
-Read the complete `shared_reasoning.md` and create final synthesis:
-
-1. **Common Ground**: Points where all 3 agree (HIGH CONFIDENCE)
-2. **Opportunities**: Unique insights from Optimist
-3. **Risks**: Unique insights from Advocate
-4. **Trade-offs**: Assessment from Analyst
-5. **Recommendation**: Final decision with confidence level
-6. **Next Steps**: Actionable items
-
-### STEP 7: Log Completion
-
-```jsonl
-{"ts":"<ISO>","type":"council","event":"synthesis_complete","session_id":"<SESSION_ID>","confidence":"<HIGH|MEDIUM|LOW>"}
-```
-
-### STEP 8: Offer Next Steps
-
-After presenting synthesis, offer:
-- `/agileflow:adr` - Create an ADR documenting this decision
-- `/agileflow:epic` - Create an epic to implement the decision
-- `/agileflow:story` - Create stories for immediate actions
-
----
-
-## Output Format
-
-```markdown
-## AI Council Deliberation
-
-**Question**: [Original question]
-**Session**: [Session ID]
-**Mode**: [parallel/debate]
-
----
-
-### Council Perspectives
-
-#### Optimist Strategist
-**Summary**: [1-2 sentence summary]
-
-**Key Opportunities**:
-1. [Opportunity] - Evidence: [source]
-2. [Opportunity] - Evidence: [source]
-3. [Opportunity] - Evidence: [source]
-
-**Success Pathway**: [Brief description]
-
----
-
-#### Devil's Advocate
-**Summary**: [1-2 sentence summary]
-
-**Key Risks**:
-1. [Risk] - Mitigation: [approach]
-2. [Risk] - Mitigation: [approach]
-3. [Risk] - Mitigation: [approach]
-
-**Stress Tests**: [Key scenarios tested]
-
----
-
-#### Neutral Analyst
-**Summary**: [1-2 sentence summary]
-
-**Trade-offs**:
-| Factor | For | Against | Weight |
-|--------|-----|---------|--------|
-| [Factor] | [Pro] | [Con] | [H/M/L] |
-
-**Decision Criteria**: [Key factors]
-
----
-
-### Synthesis
-
-#### Common Ground (High Confidence)
-*All 3 council members agree:*
-- [Point 1]
-- [Point 2]
-
-#### Opportunities (Optimist Unique)
-- [Opportunity not covered by others]
-
-#### Risks to Monitor (Advocate Unique)
-- [Risk that needs attention]
-
-#### Key Trade-offs
-- [Trade-off 1]: [Assessment]
-- [Trade-off 2]: [Assessment]
-
----
-
-### Recommendation
-
-**Decision**: [Clear recommendation]
-**Confidence**: [High/Medium/Low]
-
-**Rationale**:
-1. [Key reason 1]
-2. [Key reason 2]
-3. [Key reason 3]
-
----
-
-### Next Steps
-
-1. [Immediate action]
-2. [Follow-up action]
-3. [Validation action]
-
----
-
-### Session Files
-
-- Session: `.agileflow/council/sessions/[SESSION_ID]/`
-- Full deliberation: `shared_reasoning.md`
-
----
-
-**Want to document this decision?** Run `/agileflow:adr` to create an Architecture Decision Record.
-```
-
----
-
-## Why Three Perspectives?
-
-| Perspective | Purpose | Counterbalances |
-|-------------|---------|-----------------|
-| **Optimist** | Ensures opportunities aren't missed | Claude's risk aversion |
-| **Advocate** | Prevents groupthink and blind spots | Claude's "yes person" tendency |
-| **Analyst** | Grounds decision in evidence | Emotional or biased reasoning |
-
-Together, they produce balanced, high-quality recommendations.
-
----
-
-## Benefits
-
-1. **Context Quality**: Each agent runs with fresh context (avoids 40-50% degradation)
-2. **Balanced Perspectives**: Forces consideration of multiple viewpoints
-3. **Transparency**: `shared_reasoning.md` provides audit trail
-4. **Non-Technical Decisions**: Fills gap - domain experts handle code, council handles strategy
-5. **Debate Mode**: Deeper analysis through multiple rounds
-
----
-
-## Related Commands
-
-- `/agileflow:choose` - Single-perspective decision making
-- `/agileflow:multi-expert` - Domain expert analysis (technical)
-- `/agileflow:adr` - Document architectural decisions
-- `/agileflow:research:ask` - Research before deciding
-- `/agileflow:rpi` - Research-Plan-Implement workflow
-
----
-
-## Examples
-
-### Example 1: Architecture Decision
-
-```
-/agileflow:council Should we migrate from monolith to microservices?
-```
-
-The council will analyze:
-- **Optimist**: Scalability benefits, team autonomy, deployment flexibility
-- **Advocate**: Complexity increase, distributed systems challenges, team readiness
-- **Analyst**: Current pain points, team capacity, incremental migration options
-
-### Example 2: Technology Choice
-
-```
-/agileflow:council --mode debate --rounds 2 GraphQL vs REST for our public API?
-```
-
-Round 1: Initial perspectives
-Round 2: Respond to each other's arguments
-Final: Synthesized recommendation with confidence
-
-### Example 3: Process Decision
-
-```
-/agileflow:council Should we adopt trunk-based development?
-```
-
-The council evaluates from three angles to provide balanced guidance.
-
----
-
-## Expected Output
-
-### Success - Council Decision
-
-```
-🏛️ AI Council Convened
-══════════════════════════════════════════════════════════════
-Question: Should we migrate to microservices?
-Mode: standard (3 perspectives)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-🌟 OPTIMIST PERSPECTIVE
-Microservices offer significant benefits:
-- Independent scaling per service
-- Technology flexibility
-- Team autonomy and faster releases
-Recommendation: Proceed with migration
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-😈 ADVOCATE PERSPECTIVE
-Critical concerns to address:
-- Distributed systems complexity
-- Network latency overhead
-- Operational burden (monitoring, debugging)
-- Team may lack experience
-Recommendation: Caution - validate team readiness
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-⚖️ ANALYST SYNTHESIS
-Balanced assessment:
-- Current monolith pain points are real
-- Full migration is high-risk
-- Incremental approach reduces risk
-
-Recommendation: Start with one bounded context
-Confidence: 75%
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 COUNCIL VERDICT: Proceed with caution
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Document decision? /agileflow:adr TITLE="Microservices Migration"
-```
-
-### Success - Debate Mode
-
-```
-🏛️ AI Council Debate (Round 2 of 2)
-══════════════════════════════════════════════════════════════
-
-[Optimist responds to Advocate's concerns...]
-[Advocate counters with specific risks...]
-[Analyst synthesizes final position...]
-
-Final Verdict: GraphQL for internal APIs, REST for public
-Confidence: 85%
-```
-
-### Error - Question Too Vague
-
-```
-❌ Error: Question too vague for meaningful analysis
-
-"Should we do it?" - What is "it"?
-
-Please provide specific context:
-/agileflow:council "Should we use Redis or Memcached for session caching given our 10k DAU scale?"
-```