openclaw/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:

./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.