Documentation Index
Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
Use this file to discover all available pages before exploring further.
A flight is a Markdown document that defines a directed acyclic graph (DAG) of agent tasks. Each H2 section is an agent with a prompt, dependencies, and optional configuration. A pilot agent reads the flight and orchestrates the sub-agents.
Basic structure
# Refactor Authentication
## design
> persona: architect
> out: respond
Analyze the current auth system and propose a refactoring plan.
Focus on session management and token refresh logic.
## implement
> needs: design
> out: pr
Implement the refactoring plan from the design phase.
Follow the architectural recommendations exactly.
## test
> needs: implement
> gate: ci
Write comprehensive tests for the new auth system.
Ensure all edge cases are covered.
- H1: Flight name
- H2: Agent slug (must be unique within the flight)
- Blockquote lines (
> key: value): Agent metadata
- Body text: The agent’s task prompt
Each agent can have these blockquote directives:
| Directive | Type | Description |
|---|
persona | string | Agent persona: programmer, architect, pm, or custom name |
model | string | Model override (e.g., claude-opus-4-6) |
needs | CSV | Upstream agents that must complete first (new branch, new VM) |
continues | string | Upstream agent to send a follow-up to (same branch, same VM) |
gate | CSV | Completion criteria: ci, review, approve, merge |
branch | string | Explicit branch name (auto-generated if omitted) |
each | string | Collection description for fanout (one agent per item) |
out | string | Expected output: pr, push, respond, or freeform |
Dependencies
needs — new context
When agent B needs agent A, B starts only after A completes. B gets a new thread — fresh workflow, new branch, new VM. No inherited conversation context.
## backend-api
Implement the REST API.
## frontend
> needs: backend-api
Build the UI that calls the API.
> needs: design, backend-api — all must complete before the dependent starts.
continues — same context
When agent B continues agent A, B sends a follow-up to agent A on the same branch and VM. Full conversation context is preserved. This is a 1:1 relationship.
## initial-implementation
Write the first draft of the feature.
## refinement
> continues: initial-implementation
Review your implementation, fix edge cases, and clean up.
needs and continues are mutually exclusive. An agent can have one or the other, not both.
Fanout with each
The each directive creates a template agent that’s expanded into one instance per item:
## fix-module
> each: every Go package that has failing tests
Fix the failing tests in this package: {}
each value, enumerates items, and spawns one agent per item. The {} placeholder is replaced with each item. When another agent needs an each agent, all expanded instances must complete.
Gates
Gates block downstream agents until conditions are met:
| Gate | Description |
|---|
ci | CI checks must pass on the agent’s PR |
review | A reviewer agent is spawned to review the PR |
approve | Pilot waits for human approval |
merge | PR must be merged |
## implement
> out: pr
> gate: ci, review
Build the feature and open a PR.
YAML frontmatter
Flights stored in the catalog can have optional frontmatter:
---
workspace: backend-team
on:
issue_opened:
repos: [https://github.com/acme-corp/api]
labels: [bug]
daemon: true
max_concurrent: 3
---
# Bug Fixer
## triage
> persona: architect
Analyze the bug report and determine the fix.
| Frontmatter field | Description |
|---|
workspace | Required for catalog flights |
on | Event triggers (see below) |
daemon | Keep the flight alive after idle (for long-lived processors) |
max_concurrent | Limit on parallel flight instances |
out | Expected output for the pilot |
persona | Pilot persona (for zero-agent flights) |
model | Model override for the pilot |
disabled | Skip during schedule sync |
Event triggers
Flights can be triggered by GitHub events:
on:
issue_opened:
repos: [https://github.com/acme-corp/api]
labels: [bug, enhancement]
pr_opened:
repos: [https://github.com/acme-corp/api]
push:
repos: [https://github.com/acme-corp/api]
branches: [main]
schedule:
cron: "0 9 * * 1-5"
ci_failure:
repos: [https://github.com/acme-corp/api]
check: [TestSuite]
branch: [main]
Running flights
From the CLI:
murmur spawn --flight plan.md my-flight "Execute the refactoring plan"
murmur spawn --flight triage.md --input repo=acme-corp/api --input number=42 bug-42
murmur flight validate plan.md
Stored flights
Save flights to the catalog for reuse and event-triggered execution:
murmur set flight bug-fixer < bug-fixer.md
