hierarchical-agent-system

---
name: hierarchical-agent-system
description: >
  Hierarchical agent system with dynamic, domain-agnostic bootstrapping.
  Use it WHENEVER the user says things like: "bootstrap agents for...",
  "set up an agent system for this project", "I need an agent hierarchy",
  "create the full agent system", "I want self-organizing agents",
  "build the hierarchy for...", "start the Designator for...", "designate agents for...",
  or any variant implying the creation of a multi-layer hierarchical agent system
  that self-builds from an objective. Also activate on Spanish triggers:
  "montá un sistema de agentes", "bootstrapeá agentes", "armá la jerarquía",
  "iniciá el Designator", "necesito una jerarquía de agentes".
  DO NOT confuse with agent-team-builder, which creates flat teams for one task.
  This skill creates COMPLETE HIERARCHIES with Director, PM, Orchestrator and
  Specialists that bootstrap themselves, with a centralized mapping, capability
  checking, and dynamic agent generation. Also activate when the user mentions
  "Designator", "agent mapping", "agent bootstrap", or "domain-agnostic agent system".
---

# Hierarchical Agent System

Hierarchical agent system with dynamic, domain-agnostic bootstrapping.
The system self-builds from an objective using a central agent called
**The Designator**.

## Key concepts

### Architecture

```
YOU (objective in human language)
  └─ Director (translates intent into a roadmap)
       └─ PM (translates roadmap into technical tasks with dependencies)
            └─ Orchestrator (distributes tasks among agents, verifies results)
                 ├─ Specialist A
                 ├─ Specialist B
                 └─ Specialist C
```

Hierarchy depth is **variable**: the Designator decides how many levels the
project needs. A small project may have only Orchestrator + 2 specialists.
A large one may have Director + 2 PMs + 3 Orchestrators + N specialists.

### Design principles

1. **Lazy bootstrapping**: the system builds itself on the first run.
   An empty state file is the trigger.
2. **Domain-agnostic**: the infrastructure is fixed, the domain is an input.
   Same system for code, research, writing, analysis, whatever.
3. **Centralized mapping**: a single JSON file is the source of truth about
   which agents exist, what they do, and how they relate.
4. **Capability checking**: before each task, the system verifies whether the
   current team can solve it. If not, it calls the Designator to add what's missing.
5. **Selective invocation**: only the agents needed for each task are called,
   not all of them.
6. **Infra/context separation**: system prompts define the ROLE (fixed),
   the project context is injected separately (variable).

---

## Step 0 — Understand the user's request

Before doing anything, identify:

1. **Is this a new or existing project?**
   - New: full bootstrap required
   - Existing: check whether a mapping and agents already exist

2. **What kind of project is it?**
   - Code (web app, bot, API, etc.)
   - Research / analysis
   - Writing / content
   - Mixed

3. **What is the high-level objective?**
   - Extract it in ONE clear sentence from the user's message

---

## Step 1 — Check system state

Look in the project root (or the folder the user specifies):

```
project/
├── .agents/
│   ├── mapping.json          ← centralized agent index
│   ├── project-context.json  ← active project context
│   ├── templates/
│   │   ├── director.md
│   │   ├── pm.md
│   │   ├── orchestrator.md
│   │   └── specialists/
│   │       ├── [name].md
│   │       └── ...
│   └── logs/
│       └── [timestamps].json ← decision history
```

**If `.agents/mapping.json` doesn't exist or is empty** → run full bootstrap (Step 2).

**If `.agents/mapping.json` exists and has content** → skip to Step 4 (capability check).

---

## Step 2 — Bootstrap: invoke the Designator

The Designator is the most important agent in the system. It is the only one
that can create, modify, or discard other agents. It always runs on the most
capable model available.

### The Designator's system prompt

Read the file `references/designator-prompt.md` in this skill to get the full
system prompt for the Designator.

### Input the Designator receives

```json
{
  "objective": "User's objective in one sentence",
  "domain": "code | research | writing | analysis | mixed",
  "project_context": {
    "name": "project name",
    "description": "what it is and what it's for",
    "stack": ["relevant technologies if applicable"],
    "constraints": ["deadline, budget, restrictions"],
    "existing_files": "structure summary if it exists"
  },
  "current_mapping": null
}
```

### Output the Designator produces

The Designator generates TWO things:

**1. The mapping.json** — full team index:

```json
{
  "project": "project-name",
  "created_at": "ISO timestamp",
  "updated_at": "ISO timestamp",
  "hierarchy_depth": 3,
  "agents": [
    {
      "id": "director-01",
      "name": "Director",
      "type": "leader",
      "level": 0,
      "specialty": "Strategic direction and product decision-making",
      "capabilities": [
        "Break down business objectives into roadmaps",
        "Prioritize features by impact and effort",
        "Make trade-off decisions when there's conflict"
      ],
      "limitations": [
        "Does not write code or design architecture",
        "Does not make technical implementation decisions"
      ],
      "reports_to": null,
      "directs": ["pm-01"],
      "model_tier": "fable",
      "metrics": {
        "invocations": 0,
        "successes": 0,
        "failures": 0,
        "last_invoked": null
      }
    },
    {
      "id": "pm-01",
      "name": "ProjectManager",
      "type": "leader",
      "level": 1,
      "specialty": "...",
      "capabilities": ["..."],
      "limitations": ["..."],
      "reports_to": "director-01",
      "directs": ["orch-01"],
      "model_tier": "sonnet",
      "metrics": { "..." : "..." }
    }
  ]
}
```

**2. The filled templates** — one .md file per agent in `.agents/templates/`.

### Structure of an agent template

Templates use scaffolding with fixed zones and variable zones:

```markdown
# {agent_name}

## Role
{role_description}

## Hierarchy level
{level_type}: Level {level_number}
Reports to: {reports_to}
Directs: {directs}

## Specialty
{specialty}

## Capabilities
{capabilities_list}

## Limitations
{limitations_list}

## Communication protocol

### Receiving tasks
When you receive a task from {reports_to}:
1. Confirm receipt with a summary of what you understood
2. If there's ambiguity, ask BEFORE executing
3. Estimate complexity (low/medium/high)

### Reporting results
On completion, report to {reports_to}:
1. Summary of what was done (max 3 sentences)
2. Decisions made and why
3. Problems encountered (if any)
4. Suggestions for future similar tasks

### Peer communication
{peer_communication_rules}

## Project context
> This block is injected dynamically from project-context.json
> It is NOT hardcoded in the template.

{project_context_injection_point}

## Expected output
{expected_output_format}
```

**Leader templates** have additional fields:

```markdown
## Managing subordinates

### Work distribution
{distribution_criteria}

### Result verification
{verification_protocol}

### Problem escalation
Escalate to {reports_to} when:
{escalation_criteria}
```

---

## Step 3 — Save the bootstrap result

After the Designator generates the mapping and templates:

1. Create the `.agents/` structure if it doesn't exist
2. Save `mapping.json`
3. Save each template in `.agents/templates/`
4. Save `project-context.json` with the project context
5. Create `.agents/logs/` for history

**IMPORTANT**: Before saving, SHOW the user the generated mapping and templates
for review. The user must approve the structure before it's crystallized.
Ask explicitly:

> "The Designator proposes this team for your project. Review it and tell me
> if you want to change anything before I save it."

Only save after the user approves.

---

## Step 4 — Capability check (before each task)

This step runs EVERY TIME a new task arrives, not just at bootstrap.

### Check flow

1. Read `mapping.json` (cheap, small file)
2. Compare the task against the specialties and capabilities of the listed agents
3. Decide:
   - **SUFFICIENT**: current agents can solve the task → go to Step 5
   - **INSUFFICIENT**: capability is missing → call the Designator with the task
     and ask it to add the needed agents. Then return to Step 4.

### Criteria to decide SUFFICIENT vs INSUFFICIENT

- Is there at least one agent whose specialty covers the task's main domain?
- Do the agent's listed capabilities include what the task requires?
- Do the agent's limitations NOT exclude what the task asks for?

If all three hold: SUFFICIENT. If any fails: INSUFFICIENT.

### Cost optimization of the check

The check must be AS CHEAP AS POSSIBLE. Strategies:

- Use the cheapest model available for the check (Haiku if API,
  small local model if local)
- The mapping is designed to be readable at a glance — don't load full
  templates for the check
- If the task is clearly in an existing agent's domain (e.g. a frontend task
  when there's a FrontendDev), don't run a formal check, assign directly

---

## Step 5 — Agent selection and invocation

DON'T invoke all agents. Only the ones needed for the current task.

### Invocation flow

1. From the mapping, identify which agents are relevant to this task
2. Load ONLY the templates of those agents
3. Inject the project context from `project-context.json`
4. Run the hierarchical chain top-down:
   - Director receives the objective → produces a roadmap
   - PM receives the roadmap → produces tasks with dependencies
   - Orchestrator receives the tasks → distributes among specialists
   - Specialists execute → report to the Orchestrator
   - Orchestrator consolidates → reports to the PM
   - PM consolidates → reports to the Director
   - Director produces an executive summary for the user

**For small tasks**: skip Director and PM, go straight to the Orchestrator.
**For medium tasks**: skip Director, start at PM.
**For large tasks**: full chain.

The criteria for deciding the entry level:
- **Small**: a single clear technical task, no ambiguity, <1 hour of work
- **Medium**: multiple related subtasks, some planning, <1 day
- **Large**: a business or product objective, requires decomposition, >1 day

---

## Step 6 — Update metrics and state

After each completed task:

1. Update `metrics` in `mapping.json` for each invoked agent:
   - Increment `invocations`
   - Increment `successes` or `failures` depending on the result
   - Update `last_invoked`
2. Save a log in `.agents/logs/` with:
   - Timestamp
   - Task executed
   - Agents invoked
   - Result (success/failure)
   - Relevant decisions made

**IMPORTANT**: metric updates are direct writes to the JSON, they do NOT
require invoking the Designator. They are cheap and automatic.

---

## Step 7 — Periodic consolidation (optional, user-initiated)

When the user asks for it, or when the agent catalog exceeds 15 entries,
invoke the Designator in consolidation mode:

### Consolidation input

```json
{
  "mode": "consolidate",
  "current_mapping": { "...current mapping..." },
  "request": "Review the team and propose changes"
}
```

### The Designator in consolidation mode evaluates

1. **Overlapping agents**: are there two or more with nearly identical specialties?
   → Propose a merge
2. **Inactive agents**: are there agents with 0 invocations in the last 20 tasks?
   → Propose archiving (not deletion, archive to `.agents/templates/archived/`)
3. **Overloaded agents**: are there agents with far more invocations than the rest?
   → Propose splitting their role into finer specialists
4. **Detected gaps**: did recent tasks fail for lack of capability?
   → Propose new agents

**ALWAYS show the proposals to the user before executing them.**

---

## Implementation notes

### Model compatibility and tiering

This system is **model-agnostic**, but each agent has a `model_tier`
assigned in the mapping indicating which model it should use. The Designator
assigns the tier when creating each agent.

#### Available tiers (Claude API, prices per million tokens)

| Tier | Model | Price in/out | When to use |
|---|---|---|---|
| `fable` | Claude Fable 5 | $10 / $50 | ONLY decisions that crystallize: Designator at bootstrap/consolidation, Director on complex projects. Few invocations, high impact. Strong on long-horizon, multi-step tasks. |
| `opus` | Claude Opus 4.8 | ~$5 / $25 | Frequent deep reasoning: Director on medium projects, PM on complex projects. |
| `sonnet` | Claude Sonnet (latest) | ~$3 / $15 | Default for execution: Orchestrator and specialists. Most work happens here. |
| `haiku` | Claude Haiku 4.5 | $0.80 / $4 | Mechanical tasks: capability checks, task complexity classification, log updates. |
| `local` | Ollama (Qwen/DeepSeek) | $0 | Development, architecture testing, and the whole flow when the budget is zero. |

#### Tier assignment rules

1. **Fable NEVER in loops.** Output at $50/MTok dominates cost in agentic
   loops. Fable is used in one-off invocations whose result is saved and
   reused (the team designed at bootstrap, a consolidation). A bootstrap with
   Fable costs ~$0.70-1.00 and happens once per project: it amortizes.
   A specialist with Fable in a 50-turn loop: no.
2. **Sonnet is the default.** If in doubt about an agent's tier, it's sonnet.
3. **Haiku for anything that doesn't require judgment.** Checks, classifications,
   state updates.
4. **Escalation on failure**: if a sonnet specialist fails the same task twice,
   the Orchestrator can retry once with the higher tier before escalating the
   problem upward.
5. **Prompt caching always on** for repeated context (mapping, project-context,
   templates): cuts input cost ~90%.

#### Operating modes

- **All local**: development and architecture testing at zero cost. The full
  system works; the Designator is less precise but sufficient to validate design.
- **Mixed (recommended)**: `local` or `haiku` for checks and mechanics,
  `sonnet` for execution, `fable` only for the Designator. Typical monthly
  cost under heavy use: $10-20.
- **All API**: production with a budget. Respect the mapping's tiering.

### Difference from agent-team-builder

| Aspect | agent-team-builder | hierarchical-agent-system |
|---|---|---|
| Scope | ONE team for ONE task | Full multi-layer system |
| Hierarchy | Flat (leader + specialists) | Variable (Director → PM → Orch → Spec) |
| Persistence | No (generated and used) | Yes (mapping, templates, logs) |
| Domain | Project-specific | Agnostic, configurable |
| Self-building | No | Yes (Designator + bootstrap) |
| Pre-check | No | Yes (capability before each task) |
| Growth | Fixed | Dynamic (agents added/archived) |

### When to use which

- **agent-team-builder**: one-off task, disposable team, no persistence or
  growth needed. "Build me a team to refactor this module."
- **hierarchical-agent-system**: long project, multiple tasks, you want the
  team to grow and learn. "Set up an agent system for Permutia that lasts
  the whole development."

---

## Reference files

- `references/designator-prompt.md` — Full system prompt for the Designator
- `references/mapping-schema.json` — JSON schema for the mapping
- `references/template-examples.md` — Examples of filled templates