Research Agent Playbook

Stop re-explaining yourself to every new agent.

Every fresh session

S1CI is green. Can I merge? PLAYBOOK.md · Authority
S2The requested model is unavailable. Use another? skills/orchestrate
S3Should I fan this out to five subagents? PLAYBOOK.md · Intent, evidence, and cost
S4How do I report that the task is done? PLAYBOOK.md · Completion

Every fresh session begins with a quiet tax: untangling whether “done” means merged or merely pushed, whether a missing model may silently downgrade, and when five subagents are worse than one. The Agent Playbook writes those answers down once—a portable operating philosophy you can feed to any assistant as context, or adopt as consented skills in a coding harness.

Read as memory Install optional skills View on GitHub ↗

MIT licensed · plain Markdown & YAML · no runtime, no installer, no account

agent-playbook/repository anatomy

MEMORY.md (opens in a new tab)conversational entryLayer 1
PLAYBOOK.md (opens in a new tab)canonical policyLayer 1
skills/
orchestrate/ (opens in a new tab)route & bound workLayer 2
prompting/ (opens in a new tab)compact briefsLayer 2
profiles/
marco/ (opens in a new tab)dated operator exampleLayer 3
template/ (opens in a new tab)blank slate for yoursLayer 3
examples/ (opens in a new tab)task & review briefs

Four questions you shouldn’t answer twice.

A blank context window remembers none of your standards. Without a shared text, the agent either interrupts for routine policy or guesses with your authority.

Unguided sessionCI is green. Can I merge?
Playbook standardPreview, push, merge, and deploy are distinct permissions. Approving a preview never authorizes a merge.PLAYBOOK.md · Authority
Unguided sessionThe requested model is unavailable. Use another?
Playbook standardNever downgrade silently. A missing model or altered billing route requires a visible diagnostic and your choice.skills/orchestrate
Unguided sessionShould I fan this out to five subagents?
Playbook standardOnly when independent lanes beat coordination tax, with concurrency and budget bounded before dispatch.PLAYBOOK.md · Intent, evidence, and cost
Unguided sessionHow do I report that the task is done?
Playbook standardSeparate what ran, passed, and was skipped—unknown is never passed—and close with the four-line receipt.PLAYBOOK.md · Completion

One finish line across every harness.

Authorized GitHub work closes with a pushed branch, a PR, a committed handoff report, and this exact receipt. READY FOR REVIEW means delivered for inspection—never approved, merged, or deployed.

PR: <number and URL>
Commit: <pushed HEAD SHA>
Handoff: <repository-relative path>
Status: READY FOR REVIEW | BLOCKED

How the Agent Playbook differs from a prompt template5 architectural distinctions

How the Agent Playbook differs from a prompt template
Aspect	Prompt template	Agent Playbook
Covers	The phrasing of a single task	How work is directed, verified, and handed off across tasks
Lives in	A snippet you re-paste	A versioned git repository with reviewed diffs
Authority	Usually implicit	Explicit precedence: current instruction → repo rules → adopted profile → defaults
Personal choices	Hardcoded into the prompt	Isolated in a profile you can swap without touching the skills
Updates	Manual copy-paste drift	Inspectable commits; memory updates only when you re-approve

Three layers, adopted separately.

Take one layer or all three. Reading context never installs a skill; installing a skill never adopts someone else’s profile.

Layer 1 · Memory & context

Read by any assistant.

MEMORY.md is distilled for ingestion; PLAYBOOK.md holds the full policy. Your assistant proposes entries and saves only what you approve.

Path A: Read it in →

Layer 2 · Optional skills

Two consented coding skills.

orchestrate bounds delegation and handoffs; prompting shapes compact, falsifiable briefs. Neither requires Pi or private infrastructure.

Path B: Install with consent →

Layer 3 · Personal configuration

Your convictions, kept apart.

Model roles, concurrency caps, and effort live in a replaceable profile. Marco’s is a dated example; the template is yours to fill in.

See profile & template →

Interactive Walkthrough · Doors & Layers

Trace what happens before a single rule is adopted.

Conversational context for ChatGPT, Claude, or any assistant—nothing is installed or executed.

Step 01 / 04Assistant (Read-only)

Ingest MEMORY.md and PLAYBOOK.md

The assistant reads the self-contained summary and canonical policy from GitHub (or raw text you paste).

Boundary: No local files touched; no tools or shell commands invoked.

SOURCE READ

GET github.com/gaia-research/agent-playbook/{MEMORY.md,PLAYBOOK.md}

Jump to Path A prompt ↓

Never implied: Reading never syncs automatically across accounts or authorizes commands, installs, or deploys.

Path A · Read as memory · no installation

Feed a chat assistant the operating context.

For ChatGPT, Claude, or any conversational AI. This is not an automatic memory importer: the assistant reads the documents, proposes dated entries, and saves only what you approve.

Start a conversation with an assistant that can fetch URLs—or paste MEMORY.md (raw) (opens in a new tab) and PLAYBOOK.md (raw) (opens in a new tab) directly.
Run the prompt. It requests a short summary and proposed memory entries while withholding profiles/marco unless you ask.
Approve line by line. Keep live model availability, prices, credentials, and private endpoints out of saved memory.
Verify what persisted. Where platform memory is unavailable, the rules still govern the active chat and can be saved as plain text.

Prompt for a chat assistant

Read the Agent Playbook at https://github.com/gaia-research/agent-playbook.
Start with MEMORY.md, then PLAYBOOK.md.

1. Summarize its operating philosophy in a few lines.
2. Propose memory entries. Keep universal defaults separate from
   personal preferences, and note the source and today's date.
3. Do not adopt the example profile in profiles/marco unless I ask.
4. Tell me what this platform can actually save. Save nothing until
   I approve each entry, then tell me exactly what was saved.

Reading this playbook does not authorize installing anything or
running commands.

Remembering these principles grants zero permission to install skills, run commands, alter credentials, or deploy. Repository edits never auto-sync; re-run the review when adopting a newer revision.

Path B · Install optional skills · requires your consent

Have your coding agent propose a copy plan.

There is no one-line installer, by design. Each skill is a plain SKILL.md folder; your agent checks how your harness discovers skills, shows a copy plan, and writes nothing until you agree.

Select orchestrate, prompting, or both, and choose project or user scope.
Inspect. The agent checks current harness docs and existing skill folders, then reports paths and any file collisions.
Consent. Nothing is copied before your explicit yes—no hooks, extensions, or dependencies.
Verify. The agent confirms discovery and rolls back only its own files if verification fails.

Documented harness discovery paths (Claude Code, Codex, Pi)Checked 2026-11-08

Documented discovery locations from the repository’s harness notes
Harness	Project	User
Claude Code ↗ (opens in a new tab)	`.claude/skills/<name>/SKILL.md`	`~/.claude/skills/<name>/SKILL.md`
Codex ↗ (opens in a new tab)	`.agents/skills/<name>/SKILL.md`	`~/.agents/skills/<name>/SKILL.md`
Pi ↗ (opens in a new tab)	`.agents/skills/<name>/SKILL.md`	`~/.agents/skills/<name>/SKILL.md`

Sourced from official harness docs (read 2026-11-08); no live installation was tested in the repository. Managed policies and cloud sessions may differ—have your agent confirm against current docs.

Prompt for a coding agent

I'm considering the optional skills in
https://github.com/gaia-research/agent-playbook
(skills/orchestrate and/or skills/prompting). Read its README.md and
profiles/marco/harnesses.md first.

Before changing anything:
1. Identify this harness, its version, and the skill format and
   discovery location it documents.
2. Show me which skill directories you would copy, the destination
   (user or project scope), and any existing files they collide with.
3. Wait for my explicit yes.

After I approve: copy only the selected skill directories, unchanged.
No hooks, extensions, dependencies or config changes. Then verify the
skill is discovered and report exactly what was installed where.

Installing a skill grants a procedure, not authority. The orchestrate skill explicitly forbids installing integrations or widening merge/deployment permissions merely to finish a task.

Policy vs. conviction: a real profile and a blank one.

The portable policy states how to decide; a profile records what one operator actually decided. Marco’s profile is a working example—adopt it only by choice, or replace it with your own.

profiles/marco · dated 2026-11-08

DelegationMax four concurrent subagents unless overridden; no ceremony that costs more than the task.
EffortPlanners request MAX (falling back to HIGH); other roles match effort to workload.
Model rolesEconomical models for scouting and routine execution; stronger models for architecture and review.
ReviewDedicated read-only reviewers with an independent escalation route; workers are not assumed reviewers.
EscalationNamed specialists fail closed when unavailable—no silent model, provider, or credential swap.

# roster.yaml (excerpt)
max_subagents: 4
planner_effort_preference: [max, high]
fallback_policy: fail_closed_without_explicit_authorization
credential_changes: never_implicit

Concrete model IDs in models.yaml carry runtime_verified: false—observed in a source config, not certified as live on any account.

Read Marco’s profile ↗

What it refuses to do.

No memory sync. Nothing updates your assistant’s memory automatically, now or on future commits.
No installer. Skills are copied by your agent only after consent, using native harness discovery.
No runtime. Plain documents only—it never dispatches agents, provisions keys, or stores secrets.
No performance claim. Records operating conventions; not benchmarked against unguided baselines.
No universal ranking. Model preferences reflect one operator’s dated setup; verify locally.

Companion reading

The guide teaches the decision. The playbook remembers yours.

The Orchestration Guide measures how much coordination a task actually earns, from one warm agent to a human at the wheel. The Playbook is where your chosen rules live.

Read the Orchestration Guide gaia-research/agent-playbook ↗

Source checked: agent-playbook @ 9346fc1 (opens in a new tab) (main). The repository is canonical; where this page and it disagree, the repository wins.