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?

• What tasks eat most of your time?
• Where do you feel you need the most help?

• What language(s) do you work in? (for agent communication style)
• Any specific domains you want covered? (coding, content, finance, research, scheduling, etc.)

• Check memory/ files for recurring tasks
• Check existing workspace structure for active projects
• Check installed skills for current capabilities

Phase 2: Planning

Based on discovery, design the council:

• Determine agent count: 3-7 agents. Fewer is better. Each agent must earn its existence.
• Define each agent: Name, role, specialties, personality angle
• Map coordination: Which agents feed data to which
• Present the plan to the user in a clear table:

| Agent | Role | Specialties | Personality |
|-------|------|-------------|-------------|
| [Name] | [One-line role] | [Key areas] | [Personality angle] |

• Get explicit approval before building. Allow adjustments.

• 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:

• Read references/soul-philosophy.md for the writing guide
• Read assets/SOUL-TEMPLATE.md for the structure
• Customize deeply for this agent's role and personality
• Every SOUL must be unique. No copy-paste between agents.

• Use assets/AGENT-AGENTS-TEMPLATE.md as base
• Define what this agent reads from and writes to
• Define handoff rules with other agents

• Copy structure from assets/LEARNINGS-TEMPLATE.md
• Initialize empty log files

• Use assets/ROOT-AGENTS-TEMPLATE.md as base
• Create the routing table for all agents
• Define file coordination map
• Set up enforcement rules
• 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

• 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:

• List all created files for the user
• Show the routing table
• Show the coordination map
• Confirm everything is in place

Phase 7: Expansion (On-Demand)

When the user asks to add, modify, or remove agents:

Adding an agent:

• Mini-discovery: What does this agent need to do?
• Create full agent structure (same as Phase 3)
• Update root AGENTS.md routing table
• Update coordination map

• Read the current SOUL.md
• Apply changes while preserving personality consistency
• Update related coordination rules if needed

• Ask for confirmation
• Reassign the agent's responsibilities to other agents
• Update routing table and coordination map
• Move agent files to trash (never delete)

Key Principles

• Each agent is a character, not a template. Different personality, different voice, different strengths. If two agents sound the same, one shouldn't exist.
• No corporate language in any SOUL. See references/soul-philosophy.md. This is non-negotiable.
• Self-improvement is mandatory. Every agent logs mistakes and learns. See references/self-improvement.md.
• Coordination through files. Agents communicate via shared directories, not direct messaging. Each agent has clear read/write boundaries.
• Brevity in everything. SOULs, AGENTS files, templates. Respect the context window.
• The user's main assistant is the coordinator. It routes tasks, not the agents themselves.
• Language-adaptive. Write SOULs in whatever language the user works in. Arabic, English, bilingual, whatever fits their world.
• Adaptive routing by default. Every generated council should include Fast/Think/Deep/Strategic model routing thresholds.
• Metrics over vibes. Weekly learning review must be measured in memory/learning-metrics.json.
• Architecture must be visual. Generate a concise architecture doc at docs/architecture/ADAPTIVE-ROUTING-LEARNING.md for training and onboarding.