Imported from mschreib28/agentic-self-improving-template (AGENTS.md). Install upstream with npx skills add mschreib28/agentic-self-improving-template. Copyright stays with the author.

AGENTS.md — Agent Team Structure and Protocols

This document defines the agent hierarchy, responsibilities, communication protocols, and the Completion Signal Standard used across the system.

Team Org Chart

                         ┌─────────────┐
                         │   Foreman   │
                         │    (R2)     │
                         └──────┬──────┘
                                │
        ┌───────┬───────┬───────┼───────┬───────┬───────┬───────┬───────┐
        │       │       │       │       │       │       │       │       │
   ┌────┴──┐ ┌──┴───┐ ┌┴────┐ ┌┴────┐ ┌┴───┐ ┌┴─────┐ ┌┴──────┐ ┌┴──────┐
   │Research│ │Archi-│ │Build│ │De-  │ │ QA │ │Growth│ │Report-│ │PM-    │
   │  Head  │ │tect  │ │Head │ │sign │ │Head│ │ Head │ │  er   │ │ Sync  │
   └────┬───┘ └──┬───┘ └┬────┘ └┬────┘ └┬───┘ └┬─────┘ └┬──────┘ └┬──────┘
        │        │      │       │       │      │        │         │
     sub-agents  ...   ...    ...     ...    ...      ...       ...

Role Definitions

Foreman (R2)

Department Heads

Each department head follows the same interface but with domain-specific prompts and tools.

Sub-Agents

Sub-agents are spawned by department heads for focused, single-responsibility tasks. They:

• Receive a scoped task description and context from their department head.
• Execute the task using their permitted tool set.
• Return a result with a completion signal.
• Do not spawn other agents (leaf nodes in the hierarchy).

Completion Signal Standard

Every agent, upon finishing a unit of work, emits one of three signals:

Signal Schema

{
  "signal": "done | blocked | needs-review",
  "agent_id": "build-sub-003",
  "task_id": "TASK-1234",
  "parent_id": "build-head",
  "timestamp": "2025-01-15T10:32:00Z",
  "payload": {
    "summary": "Short description of what was done or why it's blocked.",
    "artifacts": ["path/to/output"],
    "blockers": [],
    "review_notes": ""
  }
}

Signal Flow

Sub-agent completes work
        │
        ▼
  Emit signal ──────────────────────────────┐
        │                                   │
   ┌────┴────┐                              │
   │  done   │──► Parent consumes result    │
   └─────────┘                              │
   ┌─────────┐                              │
   │ blocked  │──► Parent attempts fix ─────┤
   └─────────┘    or escalates to Foreman   │
   ┌─────────────┐                          │
   │ needs-review │──► Route to reviewer ───┘
   └─────────────┘    (human or QA agent)

Spawning Rules

See config/policies/spawn_rules.yaml for the machine-readable version.

Core rules:

1. Only the Foreman can spawn department heads.
2. Department heads can spawn sub-agents within their own department.
3. Cross-department work requires Foreman coordination (e.g., Build requesting QA).
4. Sub-agents cannot spawn other agents.
5. Maximum concurrent sub-agents per department: configurable (default 3).

Escalation Rules

See config/policies/escalation_rules.yaml for the machine-readable version.

How to Map Your Current Setup

If you already have a multi-agent system running, use this section to plug it in.

1. Identify Your Agents

Fill in this table with your actual agent names and IDs. Not every row needs to be filled — delete departments you don't have, add ones you do.

2. Update Policies

Once the table above is filled in, propagate those names into:

• config/policies/spawn_rules.yaml — replace template agent IDs with yours.
• config/policies/escalation_rules.yaml — adjust thresholds for your system's cadence.

3. Copy Prompts

For each department you're using, copy config/prompts/department_head.md to a department-specific file (e.g., config/prompts/build.md) and fill in the {{template}} variables with your actual tools and quality criteria.

4. Start Small

Pick one department — ideally the one producing the most output — and wire in Tier 1 reflection first. See docs/getting_started.md for the step-by-step.

Adding a New Department

1. Add a row to the Department Heads table above.
2. Create a system prompt in config/prompts/ (copy department_head.md, fill in {{variables}}).
3. Create a department playbook at config/playbooks/{department}_playbook.md (copy the template — see below).
4. Add spawn and escalation entries in config/policies/.
5. Create an evaluation rubric in self_improvement/evaluation/rubrics.yaml.
6. Optionally add an example under examples/.

Department Playbook Convention

Every department should have a playbook file — a living document of learned guidelines that the department head reads as context on every invocation. This is how the system retains knowledge across restarts and prompt updates.

Template — copy this for each new department:

# {Department} Playbook

Guidelines derived from past episodes. Read by the {department} head
as context on every task. Maintained by the meta-agent.

---

## Guidelines

*No guidelines yet.*

<!-- Entries follow this format:

### Rule [N] — [date]
**Rule:** Concise actionable statement.
**Evidence:** What data supported this (episode ID, metric delta).
**Confidence:** high / medium / low
**Source episode:** ep-YYYYMMDD-NNN

-->

---

## Archived / Superseded Rules

<!-- Move rules here when newer evidence contradicts them. -->

See examples/growth_agent/growth_playbook.md for a working example.