Skip to content
BranchesTags

Repository files navigation

Multi-Agent Orchestration System

A markdown-only, framework-agnostic multi-agent orchestration boilerplate. No code dependencies, no database — agents are defined entirely through structured .md files, state is tracked in JSON, and automation is driven by a language-agnostic runner. Clone into any project (Python, Next.js, React Native, Go, etc.) and start building agents.

Architecture

Human → Orchestrator → Runner (checks schedule) → Agent (runs skill) → Output
                          ↕                              ↕
                    state/ (JSON)                   journal/ (shared memory)
                          ↕                              ↑
                    STATUS.md (dashboard)           All agents read
Component Location Role
Orchestrator orchestrator/ Routes tasks, defines pipelines, sets priorities
Agents agents/ Each agent has a single mission with measurable KPIs. Runs on a scheduled heartbeat cycle: read context → assess → execute skill → log
Runner RUNNER_SPEC.md Automation layer — checks schedules, triggers agents, updates state, processes pipelines. Language-agnostic
Knowledge knowledge/ Static reference files (brand voice, strategy, audience). Agents read but never write here
Journal journal/ Living shared memory. All agents write here. Format: YYYY-MM-DD_HHMM.md
Outputs outputs/ Dated agent outputs. Format: YYYY-MM-DD_agent-name_description.md
State state/ JSON files tracking runs, agent snapshots, pipeline progress, and alerts
STATUS.md root Auto-generated dashboard — agent health, pipelines, alerts, KPI trends. Never edit manually

Folder Structure

.
├── orchestrator/                # Orchestrator definitions
│   ├── IDENTITY.md              # Orchestrator identity and mission
│   ├── PRIORITIES.md            # Priority stack
│   └── PIPELINES.md             # Pipeline definitions
├── agents/                      # Agent definitions
│   └── standard-agent/          # Template agent (copy to create new agents)
├── knowledge/                   # Static reference files (brand, strategy, audience)
├── journal/                     # Shared memory (agents write here)
├── outputs/                     # Dated agent outputs
├── templates/                   # Reusable templates
├── examples/                    # Example files
│   ├── podcast-agent/           # Completed example agent
│   ├── runners/                 # Example runner implementations (Bash, Python, Node)
│   └── pipelines/               # Example pipeline definitions
├── state/                       # JSON state files (managed by the runner)
│   ├── agents/                  # Per-agent state ({name}.json)
│   ├── runs.json                # All run records (append-only)
│   ├── alerts.json              # Active and resolved alerts
│   └── pipelines.json           # Pipeline state
├── CLAUDE.md                    # Project instructions for Claude Code
├── CONVENTIONS.md               # Naming rules and file structure
├── RUNNER_SPEC.md               # Runner specification
├── STATUS.md                    # Auto-generated system dashboard
├── AGENT_REGISTRY.md            # Master list of all agents
├── AGENT_CREATION_CHECKLIST.md  # Agent creation verification checklist
└── NEW_AGENT_BOOTSTRAP.md       # Step-by-step agent creation guide

Quick Start

# 1. Clone the boilerplate
git clone https://github.com/your-org/multi-agent-orchestration.git
cd multi-agent-orchestration

# 2. Create your first agent from the template
cp -r agents/standard-agent agents/my-agent

# 3. Configure your agent
#    Edit agents/my-agent/AGENT.md     → mission, KPIs, skills
#    Edit agents/my-agent/HEARTBEAT.md → schedule (cron), cycle steps
#    Edit agents/my-agent/RULES.md     → boundaries, triggers
#    Create agents/my-agent/skills/    → one .md file per skill

# 4. Register the agent
#    Add an entry to AGENT_REGISTRY.md

# 5. Implement a runner in your language of choice
#    See RUNNER_SPEC.md for the full specification
#    Or copy an example from examples/runners/

# 6. Run
runner run

See examples/podcast-agent/ for a fully configured reference agent.

Orchestration

The orchestration system manages scheduled agent execution, state tracking, and automation.

What Is a Runner?

A runner is a script or program that automates agent orchestration. It is implemented according to the specification in RUNNER_SPEC.md and is language-agnostic — write it in whatever language your project uses (Bash, Python, Node.js, Go, etc.).

A runner needs four capabilities:

  1. Read and write files on disk (Markdown and JSON)
  2. Execute the Claude Code CLI (or an equivalent LLM interface)
  3. Parse cron expressions
  4. Make HTTP requests (for optional notifications — curl, urllib, https)

The runner does not replace the Orchestrator. The Orchestrator defines what and why; the runner is the mechanical layer that executes it on schedule.

Example Runners

The examples/runners/ directory contains example runner implementations in three languages:

File Language
runner-bash.sh Bash
runner-python.py Python
runner-node.js Node.js

Copy any of these and adapt them to your project.

State System

State tracking operates on two layers:

Layer Format Purpose Managed By
Machine state JSON Run logs, agent snapshots, pipeline progress, alerts Runner (auto-generated)
Human state Markdown Readable dashboard with agent status, pipelines, alerts, KPI trends Runner → STATUS.md

Note: STATUS.md is regenerated after every runner execution. Do not edit it manually — your changes will be overwritten.

Running Agents

The following CLI commands are available. Exact syntax may vary depending on your runner implementation.

runner run

Checks schedules and runs all agents whose heartbeat is due. After each execution, the runner updates state, processes pipelines, evaluates alerts, and regenerates STATUS.md.

runner run

runner run {agent-name}

Force-runs a specific agent without checking its schedule (triggered_by: "manual").

runner run podcast

runner status

Prints the current STATUS.md content to the terminal. Creates the file first if it does not exist.

runner status

runner pipeline {name}

Starts the specified pipeline from step 1. The pipeline definition is read from orchestrator/PIPELINES.md and the first agent is executed immediately.

runner pipeline content-pipeline

runner alerts

Lists all active (unresolved) alerts.

runner alerts

To mark an alert as resolved:

runner alerts resolve alert_001

Pipelines

A pipeline is a multi-step workflow where multiple agents run in sequence. One agent's output becomes the trigger for the next. Pipelines answer the question: "After Agent A finishes, what should happen next?"

How It Works

The pipeline system has two layers:

  1. Local triggers in RULES.md: Each agent declares which pipelines it triggers in the Triggers section of its RULES.md. The runner checks these triggers when an agent completes.
  2. Centralized definitions in PIPELINES.md: Pipeline steps, conditions, and error handling are defined in orchestrator/PIPELINES.md. All pipeline definitions live in one place.

Condition Types

Each pipeline step has a condition that must be met before advancing to the next step:

Condition Description Example
output_exists Checks whether a specified file exists output_exists: outputs/TODAY_research-agent_*.md
agent_status Checks the last run status of an agent agent_status: review-agent = success
kpi_above Checks whether an agent's KPI metric exceeds a threshold kpi_above: content-writer.articles_published > 3
manual_approval Pauses the pipeline and waits for human approval manual_approval: true

Failure Handling

  • If any step fails, the pipeline pauses and an alert is created
  • If a step is skipped, the reason is recorded in state/pipelines.json
  • Steps not completed within 48 hours trigger a pipeline_stuck alert

Example

See examples/pipelines/content-pipeline.md for a complete end-to-end pipeline covering research, content creation, review, and publishing.

Monitoring & Alerts

The runner automatically monitors the system after every execution and creates alerts when needed.

STATUS.md Dashboard

STATUS.md is auto-regenerated by the runner after every execution. It includes:

  • Agent Status — Last run time, result, streak, and next scheduled run for each agent
  • Active Pipelines — Current step for each running pipeline
  • Alerts — Unresolved active alerts
  • KPI Trends — Last 4 KPI measurements per agent

Note: Do not edit STATUS.md manually — it will be overwritten on the next runner execution.

Alert Types

Type Condition Default Severity
run_failed An agent's execution failed warning
overdue An agent missed more than 1 scheduled cycle warning
kpi_decline 2+ consecutive drops in an agent's KPI warning
pipeline_stuck A pipeline step was not completed within 48 hours critical

Severity Levels

Level Meaning
info Informational — no action required
warning Needs attention — intervene soon
critical Urgent — immediate action required

Journal Integration

Alerts at warning and critical severity are not only written to state/alerts.json but also generate an entry in journal/. This ensures all agents are aware of active alerts.

Severity Escalation

overdue or kpi_decline alerts that remain unresolved for 7 days are automatically escalated from warning to critical.

Notifications (Optional)

The system can send Telegram notifications for important events. Configure in config.json:

{
  "notifications": {
    "telegram": {
      "enabled": true,
      "bot_token": "YOUR_BOT_TOKEN",
      "chat_id": "YOUR_CHAT_ID",
      "events": ["run_completed", "run_failed", "alert_created", "pipeline_completed"]
    }
  }
}

Setup: Create a Telegram bot via @BotFather, get your chat ID, and set enabled: true.

Fully optional — if config.json is missing or Telegram is disabled, everything works silently. Notification failures never block the runner.

18 events available across 5 categories:

Category Events
Agent lifecycle run_completed, run_failed, run_skipped, agent_first_run, agent_overdue, agent_streak
Alerts alert_created, alert_escalated, alert_resolved
Pipelines pipeline_started, pipeline_step_completed, pipeline_completed, pipeline_failed, pipeline_stuck
KPIs kpi_decline, kpi_target_hit
System weekly_summary, system_error

Quiet hours — suppress non-critical notifications during configured hours. Critical events always send.

See EVENTS.md for the complete event catalog with message templates.

Creating a New Agent

  1. Copy the template: cp -r agents/standard-agent agents/your-agent-name
  2. Fill in all files following the Four Pillars
  3. Configure orchestration: cron schedule, triggers, pipeline participation
  4. Register in AGENT_REGISTRY.md
  5. Verify with AGENT_CREATION_CHECKLIST.md

See NEW_AGENT_BOOTSTRAP.md for the full step-by-step guide and examples/podcast-agent/ for a completed reference.

Required Agent Files

File Purpose
AGENT.md Mission, KPIs, skill registry, pipeline participation, input/output contracts, hard boundaries
skills/*.md One file per skill, using _SKILL_TEMPLATE.md format
HEARTBEAT.md Cron schedule, cycle steps, decision tree, escalation rules
MEMORY.md Agent-local learnings — starts empty, earned from real data
RULES.md CAN/CANNOT do lists, handoff rules, triggers (on completion/failure/KPI decline)

Four Pillars

Every agent must satisfy all four:

  1. Measurable Goals — KPIs with baselines and targets defined in AGENT.md
  2. Focused Skills — Each skill maps to a goal; delete any that don't (skills/*.md)
  3. Heartbeat — Scheduled cycle with read → assess → execute → log steps + cron schedule (HEARTBEAT.md)
  4. Journal Integration — Reads from and writes to journal/

Key Rules

  • Agents read from knowledge/ and journal/, write to journal/ only
  • Knowledge files are static — agents propose changes but never edit directly
  • MEMORY.md starts empty; pre-filling with assumptions is an anti-pattern
  • Every skill must serve a goal; every goal must have a skill
  • Max 4 goals per agent — if you need more, split into two agents
  • Weekly review is mandatory — without it the agent never learns
  • STATUS.md is auto-generated — never edit manually
  • State JSON files are managed by the runner — manual edits may break tracking
  • Trigger pipeline names in RULES.md must match names in PIPELINES.md exactly
  • Every new feature must emit appropriate events (see EVENTS.md)
  • Check CROSS_REFERENCE.md before modifying any system file
  • Notification failures must never block the runner
  • config.json is optional — the system works without it

Reference Files

File Description
RUNNER_SPEC.md Runner specification — what to implement in your language
CONVENTIONS.md Naming rules, file structure, state conventions
NEW_AGENT_BOOTSTRAP.md Step-by-step agent creation guide
AGENT_CREATION_CHECKLIST.md Post-creation verification checklist
AGENT_REGISTRY.md Master list of all agents and their status
templates/ Reusable output formats (journal entry, weekly review, task intake)
EVENTS.md Complete event catalog with triggers, severities, and message templates
CROSS_REFERENCE.md What to update when you change something — the system integrity guide
config.json System configuration (notifications, timeouts, thresholds)
examples/ Completed agent (podcast-agent), example pipeline, runner implementations

Turkce README

About

Collection of all future agents

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors