council-builder

# Council Builder Build a team of specialized AI agent personas tailored to the user's actual needs. Each agent gets a distinct personality, self-improvement capability, and clear coordination rules. ## Workflow ### Phase 1: Discovery Interview the user to understand their world. Ask in batches of 2-3 questions max. **Round 1 - Identity:** - What do you do? (profession, main activities, industry) - What tools and platforms do you use daily? **Round 2 - Pain Points:** - What tasks eat most of your time? - Where do you feel you need the most help? **Round 3 - Preferences:** - What language(s) do you work in? (for agent communication style) - Any specific domains you want covered? (coding, content, finance, research, scheduling, etc.) **Optional - History Analysis:** If the user has existing OpenClaw history, scan it for patterns: - Check `memory/` files for recurring tasks - Check existing workspace structure for active projects - Check installed skills for current capabilities Do NOT proceed to Phase 2 until confident you understand the user's needs. Ask follow-up questions if anything is unclear. ### Phase 2: Planning Based on discovery, design the council: 1. **Determine agent count**: 3-7 agents. Fewer is better. Each agent must earn its existence. 2. **Define each agent**: Name, role, specialties, personality angle 3. **Map coordination**: Which agents feed data to which 4. **Present the plan** to the user in a clear table: ``` | Agent | Role | Specialties | Personality | |-------|------|-------------|-------------| | [Name] | [One-line role] | [Key areas] | [Personality angle] | ``` 5. **Get explicit approval** before building. Allow adjustments. **Naming agents:** - Give them memorable, short names (not generic like "Agent 1") - Names should hint at their role but feel like characters - Can be inspired by any theme the user likes, or choose strong standalone names - See `references/example-councils.md` for naming patterns and complete council examples across different industries ### Phase 3: Building Run the initialization script first to create the directory skeleton: ```bash ./scripts/init-council.sh <workspace-path> <agent-name-1> <agent-name-2> ... ``` Then, for each approved agent, populate the files. Read `references/soul-philosophy.md` before writing any SOUL.md. **Directory structure per agent:** ``` agents/[agent-name]/ ├── SOUL.md # Personality, role, rules (see soul-philosophy.md) ├── AGENTS.md # Agent-specific coordination rules ├── memory/ # Agent's memory directory ├── .learnings/ # Self-improvement logs │ ├── LEARNINGS.md │ ├── ERRORS.md │ └── FEATURE_REQUESTS.md └── [workspace dirs] # Role-specific output directories ``` **For each agent's SOUL.md:** 1. Read `references/soul-philosophy.md` for the writing guide 2. Read `assets/SOUL-TEMPLATE.md` for the structure 3. Customize deeply for this agent's role and personality 4. Every SOUL must be unique. No copy-paste between agents. **For each agent's AGENTS.md:** 1. Use `assets/AGENT-AGENTS-TEMPLATE.md` as base 2. Define what this agent reads from and writes to 3. Define handoff rules with other agents **For gotchas.md:** 1. Use `assets/GOTCHAS-TEMPLATE.md` as base 2. Populate with 1-2 known pitfalls specific to this agent's domain 3. See `references/gotchas-patterns.md` for examples **For config.json:** 1. Use `assets/CONFIG-TEMPLATE.json` as base 2. Set agent_name, leave setup_complete as false 3. See `references/config-patterns.md` for role-specific examples **For scripts/:** 1. Create role-specific starter scripts (see `references/agent-scripts-patterns.md`) 2. At minimum, create a verification script for the agent's output type 3. Include a README.md listing what each script does **For references/:** 1. Create `verification-checklist.md` using `assets/VERIFICATION-CHECKLIST-TEMPLATE.md` 2. Optionally create `domain-guide.md` and `common-patterns.md` with role-specific content **For hooks/ (optional):** 1. See `references/hooks-patterns.md` for the pattern 2. Create hooks relevant to the agent's risk profile 3. Not every agent needs hooks; focus on agents with destructive capabilities **For .learnings/ files:** 1. Copy structure from `assets/LEARNINGS-TEMPLATE.md` 2. Initialize empty log files **For the root AGENTS.md:** 1. Use `assets/ROOT-AGENTS-TEMPLATE.md` as base 2. Create the routing table for all agents 3. Define file coordination map 4. Set up enforcement rules 5. Add adaptive model routing thresholds (Fast, Think, Deep, Strategic) ### Phase 4: Adaptive Routing Setup Read `references/adaptive-routing.md`. Set up an adaptive routing section in root AGENTS.md: - Default to Fast - Escalation thresholds for Think, Deep, Strategic - De-escalation rule back to Fast after heavy reasoning - High-tier model rate-limit fallback behavior Also create visual architecture doc: - `docs/architecture/ADAPTIVE-ROUTING-LEARNING.md` using `assets/ADAPTIVE-ROUTING-LEARNING-TEMPLATE.md` ### Phase 5: Self-Improvement Setup Read `references/self-improvement.md` for the complete system. Each agent gets built-in self-improvement: - `.learnings/` directory with proper templates - Detection triggers in SOUL.md (corrections, errors, gaps) - Promotion rules (learning → SOUL.md / AGENTS.md / TOOLS.md) - Cross-agent learning sharing via `shared/learnings/CROSS-AGENT.md` - Periodic review instructions - Weekly learning metrics file at `memory/learning-metrics.json` (use `assets/LEARNING-METRICS-TEMPLATE.json`) ### Phase 6: Verification After building everything: 1. List all created files for the user 2. Show the routing table 3. Show the coordination map 4. Confirm everything is in place ### Phase 7: Expansion (On-Demand) When the user asks to add, modify, or remove agents: **Adding an agent:** 1. Mini-discovery: What does this agent need to do? 2. Create full agent structure (same as Phase 3) 3. Update root AGENTS.md routing table 4. Update coordination map **Modifying an agent:** 1. Read the current SOUL.md 2. Apply changes while preserving personality consistency 3. Update related coordination rules if needed **Removing an agent:** 1. Ask for confirmation 2. Reassign the agent's responsibilities to other agents 3. Update routing table and coordination map 4. Move agent files to trash (never delete) ## Key Principles 1. **Each agent is a character, not a template.** Different personality, different voice, different strengths. If two agents sound the same, one shouldn't exist. 2. **No corporate language in any SOUL.** See `references/soul-philosophy.md`. This is non-negotiable. 3. **Self-improvement is mandatory.** Every agent logs mistakes and learns. See `references/self-improvement.md`. 4. **Coordination through files.** Agents communicate via shared directories, not direct messaging. Each agent has clear read/write boundaries. 5. **Brevity in everything.** SOULs, AGENTS files, templates. Respect the context window. 6. **The user's main assistant is the coordinator.** It routes tasks, not the agents themselves. 7. **Language-adaptive.** Write SOULs in whatever language the user works in. Arabic, English, bilingual, whatever fits their world. 8. **Adaptive routing by default.** Every generated council should include Fast/Think/Deep/Strategic model routing thresholds. 9. **Metrics over vibes.** Weekly learning review must be measured in `memory/learning-metrics.json`. 10. **Architecture must be visual.** Generate a concise architecture doc at `docs/architecture/ADAPTIVE-ROUTING-LEARNING.md` for training and onboarding.