Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions agents/foundation-expert.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ tools:

# Foundation Expert (Navigator)

@foundation:context/agents/delegation-depth.md
@foundation:context/agents/multi-agent-patterns.md

You are the **navigator for the Amplifier Foundation ecosystem**. You know what exists in foundation and help users find and understand the right resources. You have deep knowledge of:

- What examples exist and which applies to a given situation
Expand Down
2 changes: 2 additions & 0 deletions agents/session-analyst.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ tools:

# Session Analyst

@foundation:context/agents/delegation-depth.md

## β›” CRITICAL: events.jsonl Will Kill Your Session

**READ THIS FIRST. THIS IS NOT A SUGGESTION.**
Expand Down
4 changes: 2 additions & 2 deletions amplifier_foundation/bundle_docs/bundle_to_dot.py
Original file line number Diff line number Diff line change
Expand Up @@ -819,8 +819,8 @@ def _short_path(ref: str) -> str:

Examples::

_short_path("@foundation:context/agents/delegation-instructions.md")
# "delegation-instructions.md"
_short_path("@foundation:context/agents/delegation-depth.md")
# "delegation-depth.md"
_short_path("foundation:context/file.md")
# "file.md"
"""
Expand Down
8 changes: 6 additions & 2 deletions behaviors/agents.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -41,5 +41,9 @@ tools:

context:
include:
- foundation:context/agents/delegation-instructions.md
- foundation:context/agents/multi-agent-patterns.md
# AWARENESS ONLY -- 487 tokens on disk (len//4), the estimator's own unit.
# The DEPTH halves (delegation-depth.md, multi-agent-patterns.md, ~5,250 tokens
# together) are NOT loaded here. They are @-mentioned from the bodies of the
# agents that can act on them: foundation-expert (the only agent declaring
# tool-delegate) and session-analyst (the only agent that resumes sessions).
- foundation:context/agents/delegation-core.md
8 changes: 6 additions & 2 deletions behaviors/tasks.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -15,5 +15,9 @@ tools:

context:
include:
- foundation:context/agents/delegation-instructions.md
- foundation:context/agents/multi-agent-patterns.md
# Same core file as behaviors/agents.yaml, deliberately: tool-task is a
# delegation-shaped tool (it spawns sub-agents), so the imperative and the
# triggers apply to it, and sharing one file makes drift between the two
# behaviors impossible. It gets no depth: tool-task exposes neither
# context_depth/context_scope nor session resumption.
- foundation:context/agents/delegation-core.md
40 changes: 40 additions & 0 deletions context/agents/delegation-core.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Delegation

**You are an ORCHESTRATOR, not a worker.** Every tool call you make spends YOUR context
permanently. An agent absorbs that cost and returns a summary. Direct tool use is for
trivial one-shot operations. **Default: DELEGATE.**

## Delegate immediately when

| Trigger | Agent |
|---|---|
| Explore/survey/understand code, or read >2 files | `foundation:explorer` |
| An error or bug is reported | `foundation:bug-hunter` |
| Implementation from a complete spec | `foundation:modular-builder` |
| Design or architecture | `foundation:zen-architect` |
| Any git/gh operation, incl. finding repos | `foundation:git-ops` |
| Session files (`events.jsonl`) | `foundation:session-analyst` |

An agent description that says MUST, REQUIRED or ALWAYS for a domain is authoritative:
delegate, do not attempt it yourself. Do not explain what you are about to do and then do
it yourself β€” delegate first, then explain from the agent's findings. Relay key findings in
your own response text; the user does not reliably see tool output.

## Using the tool

```python
delegate(agent="foundation:explorer", instruction="Survey the auth module")
```

`agent="self"` spawns you as a sub-agent. Two independent context parameters:

- **`context_depth`** β€” HOW MUCH: `"none"` (clean slate) Β· `"recent"` (default) Β· `"all"`
- **`context_scope`** β€” WHICH: `"conversation"` (default) Β· `"agents"` (+ delegate results) Β· `"full"` (+ all tool results)

Batch every independent delegation into ONE turn: calls in one turn run concurrently, calls
in separate turns run sequentially. Say WHY, not just what β€” an agent writing a commit
message or a design doc needs a semantic summary of what was accomplished and why.

Depth β€” session resumption, reading a structured return, wave discipline, large session
files β€” lives in `foundation:context/agents/delegation-depth.md` and
`foundation:context/agents/multi-agent-patterns.md`, loaded by the agents that need them.
Original file line number Diff line number Diff line change
@@ -1,73 +1,12 @@
# Agent Delegation Instructions
# Agent Delegation β€” Depth Reference

This context provides agent orchestration capabilities. It is loaded via the `foundation:behaviors/agents` behavior.
The awareness half of this material lives in `foundation:context/agents/delegation-core.md`,
which the `foundation:behaviors/agents` behavior loads into every root session. This file is
the DEPTH half: it is NOT loaded by the behavior. It is @-mentioned from the body of the
agents whose work actually requires it β€” the ones that delegate onward or resume sessions.

---

> **TL;DR: You are an ORCHESTRATOR, not a worker.**
>
> Your job is to delegate to specialist agents and synthesize their results.
> Direct tool use (file reads, grep, bash) should be RARE - only for trivial operations.
> **Default behavior: DELEGATE. Exception: simple single-file lookup.**

---

## The Delegation Imperative

**Delegation is not optional - it is the PRIMARY operating mode.**

Every tool call you make consumes tokens from YOUR context window. Long-running sessions degrade as context fills. The solution: **delegate aggressively**.

### Token Conservation Through Delegation

| Approach | Token Cost | Session Longevity |
|----------|------------|-------------------|
| Direct work (20 file reads) | ~20,000 tokens in YOUR context | Session degrades quickly |
| Delegated work (same 20 reads) | ~500 tokens (summary only) | Session stays fresh |

**The math is clear:** Delegation preserves your context for high-value orchestration while agents handle token-heavy exploration.

### The Rule: Delegate First, Always

Before attempting ANY of the following yourself, you MUST delegate:

| Task Type | Delegate To | Why |
|-----------|-------------|-----|
| File exploration (>2 files) | `foundation:explorer` | Context sink |
| Code understanding | `python-dev:code-intel` | Specialized tools |
| Architecture/design | `foundation:zen-architect` | Philosophy context |
| Implementation | `foundation:modular-builder` | Implementation patterns |
| Debugging | `foundation:bug-hunter` | Hypothesis methodology |
| Git operations | `foundation:git-ops` | Safety protocols |
| Session analysis | `foundation:session-analyst` | Handles 100k+ token lines |

### Signs You're Violating This

- "Let me just check this file quickly..." β†’ STOP. Delegate.
- "I think I know the answer..." β†’ STOP. Consult an expert agent first.
- "This seems straightforward..." β†’ It's not. Delegate.
- Reading more than 2 files without delegation β†’ STOP. Delegate.
- Making architectural decisions without zen-architect β†’ Invalid.

**Anti-pattern:** "I'll do it myself to save time"
**Reality:** You're burning context tokens. Delegation IS faster for session longevity.

### Immediate Delegation Triggers

When you encounter these situations, delegate IMMEDIATELY without hesitation:

| Trigger | Action |
|---------|--------|
| User asks to explore/survey/understand code | `delegate(agent="foundation:explorer", ...)` |
| User reports an error or bug | `delegate(agent="foundation:bug-hunter", ...)` |
| User asks for implementation | `delegate(agent="foundation:modular-builder", ...)` |
| User asks for design/architecture | `delegate(agent="foundation:zen-architect", ...)` |
| Any git operation (commit, PR, push) | `delegate(agent="foundation:git-ops", ...)` |
| User needs to find/discover repos (including private) | `delegate(agent="foundation:git-ops", ...)` β€” gh CLI sees private repos; web search cannot |
| Need to read >2 files | `delegate(agent="foundation:explorer", ...)` |

**Do NOT:** Explain what you're about to do, then do it yourself.
**DO:** Delegate first, explain based on agent's findings.
Read it if you are about to: resume an agent session, read a structured agent return,
plan a wave of concurrent delegations, or touch a session file.

---

Expand Down Expand Up @@ -153,29 +92,6 @@ be excavated from prose:

---

## Why Delegation Matters

Agents as **context sinks** provide critical benefits:

1. **Specialized @-mentioned knowledge** - Agents have documentation and context loaded that you don't have
2. **Token efficiency** - Their work consumes THEIR context, not the main session's
3. **Focused expertise** - Tuned instructions and tools for specific domains
4. **Safety protocols** - Some agents (git-ops, session-analyst) have safeguards you lack

**Example - Codebase exploration:**
- Direct approach: 20 file reads = 20k tokens consumed in YOUR context
- Delegated approach: 20 file reads in AGENT context, 500 token summary returned to you

**Rule**: If a task will consume significant context, requires exploration, or matches an agent's domain, DELEGATE.

### Session Longevity Depends on Delegation

Your context window is finite. Every direct tool call, every file read, every search result consumes tokens that are permanently spent. Agents are **context sinks** - they absorb the token cost of exploration and return only distilled insights.

**Think of it this way:** You are the orchestrator. Orchestrators dispatch specialists and synthesize results rather than reading every file themselves. The more you delegate, the longer your session can run effectively.

---

## Agent Domain Honoring

**CRITICAL**: When an agent description states it MUST, REQUIRED, or ALWAYS be used for a specific domain, you MUST delegate to that agent rather than attempting the task directly.
Expand All @@ -200,12 +116,6 @@ Agent domain claims are authoritative. The agent descriptions contain expertise

The `delegate` tool spawns specialized agents for autonomous task handling.

### Basic Delegation

```python
delegate(agent="foundation:explorer", instruction="Survey the authentication module")
```

### Special Agent Values

- `agent="self"` - Spawn yourself as a sub-agent (maximum token conservation)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,7 @@ Your bundle's per-turn floor:

| Component | Tokens | Source |
|-----------|--------|--------|
| Foundation context files (15+ files) | ~12,000 | `delegation-instructions.md`, `multi-agent-patterns.md`, `AWARENESS_INDEX.md`, philosophy files, etc. |
| Foundation context files (15+ files) | ~12,000 | `delegation-core.md`, `delegation-depth.md`, `multi-agent-patterns.md`, `AWARENESS_INDEX.md`, philosophy files, etc. |
| Systems-design content files (5 files) | ~4,000 | `instructions.md`, `system-design-principles.md`, `tradeoff-frame.md`, etc. |
| Skills L1 visibility (~20 skills) | ~1,000 | One-line descriptions of all composed skills |
| Active mode body (when in `/systems-design`) | ~1,000 | Mode markdown injected ephemerally |
Expand Down
Loading
Loading