orchestration

orchestration

Covers multi-agent system design: how agents start up, maintain memory, delegate tasks, communicate, and coordinate work across sessions.

1) Agent session startup protocol

# Canonical startup sequence (from AGENTS.md)
1. Read SOUL.md           — identity, principles, non-negotiables
2. Read USER.md           — who you serve, their preferences and goals
3. Read AGENTS.md         — this session protocol and available agents
4. Read memory/TODAY.md   — what happened today so far
5. Read memory/YYYY-MM-DD.md  — yesterday's notes if today's empty
6. Check MEMORY.md index  — long-term context (scan, don't deep-read)
7. Read project README    — only if the task is project-specific

# Total token budget for startup: < 8,000 tokens
# If startup reads exceed this, summarise before proceeding

2) Memory protocol

# Memory file hierarchy
MEMORY_STRUCTURE = {
    "session":    "memory/YYYY-MM-DD.md",       # daily notes, in-progress context
    "index":      "MEMORY.md",                  # persistent long-term index
    "entries":    "memory/",                    # individual memory entries
}

# Daily note format
DAILY_NOTE_TEMPLATE = """
# {date}

## Done today
- {completed_task_1}
- {completed_task_2}

## In progress
- {wip_task}: {status_and_next_step}

## Decisions made
- {decision}: {rationale}

## Blockers
- {blocker}: {what_is_needed}

## Tomorrow
- {priority_1}
"""

# Write to memory after significant work (not after every action)
WRITE_THRESHOLD = "significant decision, completed unit of work, or end of session"

3) Task delegation patterns

# Delegation contract: what to hand off and what to expect back
DELEGATION_SPEC = {
    "task":       str,   # precise instruction (verb-first)
    "context":   str,   # minimum context the sub-agent needs
    "output":    str,   # exact format expected back
    "timeout":   int,   # seconds before assuming failure
    "fallback":  str,   # what to do if delegation fails
}

# Example: orchestrator delegates to a specialist
delegate(
    to="seo-agent",
    task="Analyse SERP for 'keto diet for beginners' and return top-3 citation gaps",
    context=f"Domain: ketoandhealthy.com. Existing article: /keto-diet/beginners",
    output="JSON: [{source_url, gap_type, suggested_citation}]",
    timeout=120,
    fallback="Use cached SERP data from last 24h",
)