Guide For operators
Write a template and blueprint
The files a squadron is formed from.
Squadrons unreleasedSource on GitHub
You want a team of agents: one plans, two build, one reviews, one tests, and each knows where to send its work next. In Aeolus that team is a squadron, and before you can form one you write it down in two kinds of file. This page takes you from an empty repository to a first template and blueprint that form a squadron.
Two files, like a Dockerfile and a compose file
A squadron is written in YAML files in a git repository on GitHub.
- A ship template is one role, like an image: what a ship in this role does, how often it reports, how it is crewed, and the hand-offs it sends its work to.
- A squadron blueprint is the team, like a compose file: which roles, how many ships of each, which template version each runs, and where each hand-off goes.
One template serves many blueprints. A team that builds features and a team that fixes bugs can both use the same tester template.
squadrons, the service beside your fleet that forms and leads squadrons, reads these files from GitHub. It never clones your repository and never edits it: you write the files, commit them and tag them, and squadrons reads what the tags point at.
Where the files go
In the repository, under .aeolus/squadrons/:
.aeolus/squadrons/ templates/ planner.yaml implementer.yaml reviewer.yaml tester.yaml blueprints/ tidewater-feature.yaml tidewater-fix.yaml- One file is one template or one blueprint, and its file name without
.yamlis its name:templates/tester.yamlis the templatetester. - A name is lowercase letters, digits, hyphens or colons. A file named
Tester.yamlortester.ymlis not read. - A repository can keep these folders somewhere else. You then give that folder as its path when you add the repository in the console.
The examples on this page come from a complete set for an invented project, Tidewater, an app with tide tables for small harbours. The whole set is in docs/squadrons-example, in a repository named github.com/tidewater-labs/squadron-templates. Put your own repository’s name wherever this page writes that one.
Versions are tags
A file on main is not a version yet. A version is a git tag on the commit that holds the file:
- Version
nof the templatetesteris the tagtester@n, a whole number from 1:tester@1, thentester@2. - A blueprint’s versions are tagged the same way, by its file name:
tidewater-feature@1. - A new version is a new commit with a new tag. Editing a file without a new tag changes nothing.
- Never move a tag. squadrons would read the moved tag as that version without a warning, and squadrons formed before would keep the old one.
Tester@1, tester-1, tester@v1 and tester@1.0 are no versions. A tag such as v1.0.0 is no version tag at all and is ignored, so your release tags can live in the same repository.
From files to a formed squadron
flowchart TD
write["Write the YAML files<br/>templates/ and blueprints/"] --> tag["Commit, tag each version<br/>tester@1, tidewater-feature@1, push the tags"]
tag --> add["Console, Settings, Repositories:<br/>add the repository, or Refresh"]
add --> read{"squadrons reads every tag<br/>Is the file valid?"}
read -->|no| left["Left out, with why,<br/>on the repository's row"]
left -->|fix, commit, new tag, Refresh| tag
read -->|yes| catalogue["In the catalogue:<br/>tester@1, tidewater-feature v1"]
catalogue --> form["Form a squadron<br/>from a blueprint version"]
form --> snap["squadrons keeps the blueprint version<br/>and every template version it uses"]
snap --> ships["It commissions a flagship<br/>and one ship per member"]
ships --> checkin["Each member checks in at the flagship<br/>and gets its role"]
checkin --> sailing["Every member on station:<br/>the squadron sails"]
Two moments read your files:
- Adding or refreshing the repository reads every version tag and checks each file. What passes is in the catalogue; what fails is left out with the reason. squadrons never fetches on a timer, so after pushing a new tag, choose Refresh.
- Forming a squadron keeps the blueprint version and every template version it uses, as they were read then. The squadron never changes when your files change later. A new tag reaches only the squadrons you form after it.
Write a template
A template is one role. This is the Tidewater tester:
# templates/tester.yaml, version 1 once tagged tester@1description: Runs the end-to-end suite on a branch and reports the result.checkIn: 30mcharter: | You test the branch you are given with the whole end-to-end suite. When tests fail, send the failing tests and their output to on-fail. When they pass, send the branch and the run to on-pass.handoffs: on-fail: The failing tests and their output on-pass: The branch and the run that passedcrew: machineLabels: - os=linux - arch=amd64Three fields are required:
| Field | What it says |
|---|---|
description |
One line, shown in the template lists |
checkIn |
How often a member reports what it does: 30m or 2h, from 1 minute to 24 hours. A member that misses one interval shows as late, three as silent |
charter |
The role’s instructions, as you would brief the agent. Each member gets it, as written, when it checks in. At most 48 KB |
The rest is optional:
handoffs
The names the charter sends work to, each with what it carries. The template only names them; a blueprint decides where each one goes
parameters
Values the template leaves to the squadron, used as {{name}} in the charter, such as the part of the code a planner works in
launchNote
Shown to a person above the role’s crew lines: where to start the session
crew
How members are crewed: the harness, the exact model, the workspace, options such as effort, the machine labels a computer must carry, a first prompt and MCP servers
scopes
The scopes each member gets when it is commissioned. Most roles need none
labels
Labels every member carries, such as company=aeolus
base
Another template version this one builds on; see Build on another template
A few rules save a failed read:
- The model goes in
crew.model, as an exact id such asclaude-opus-5-5, neveropusor a name ending in-latest. A member that checks in with another model is flagged, not stopped. Leave the model out and a member may run any. - Machine labels are
key=value, such asos=linux: never a key alone. - A workspace names repositories and folders, never a path. Each computer knows where its copies live.
A parameter, filled later
The Tidewater planner leaves its area open:
# templates/planner.yamldescription: Turns a feature request into a plan the implementers can follow.checkIn: 1hparameters: area: The part of Tidewater the features touch, such as the tide tablescharter: | You plan one feature of Tidewater at a time, in {{area}}. Read the request from the flagship, study the code it touches, and write a plan of small steps, each with the files it changes and how to test it. Send the plan to your plan-ready hand-off.handoffs: plan-ready: The plan, one step per line, with the branch to build it oncrew: model: claude-opus-5-5 firstPrompt: Wait for the flagship's feature request, then plan it.A blueprint role can fill area. One no role fills is asked for when the squadron is formed. A {{name}} the template does not declare under parameters is refused.
Build on another template
A template can build on one other template version, as a Dockerfile builds FROM one image, and say only what differs:
# templates/typescript-implementer.yamlbase: template: github.com/tidewater-labs/squadron-templates#implementer@1description: Implements a step in a TypeScript repositorycharter: | Run npm run typecheck before every commit.Its charter is added after its base’s; base.replaceCharter: true replaces it instead. base.parameters fills parameters the base leaves open. The base names a version that is tagged, never “latest”, and a new base version reaches this template only through a new version of it. A chain holds at most 10 templates.
Write a blueprint
A blueprint is the team. This is Tidewater’s feature squadron:
# blueprints/tidewater-feature.yaml, version 1 once tagged tidewater-feature@1description: Plans, builds, reviews and tests one feature of Tidewater.roles: planner: template: github.com/tidewater-labs/squadron-templates#planner@1 implementer: template: github.com/tidewater-labs/squadron-templates#implementer@1 count: 2 reviewer: template: github.com/tidewater-labs/squadron-templates#reviewer@1 tester: template: github.com/tidewater-labs/squadron-templates#tester@1handoffs: planner.plan-ready: implementer implementer.done: reviewer reviewer.approved: tester reviewer.changes: implementer tester.on-fail: implementer tester.on-pass: flagship| Field | What it says |
|---|---|
description |
Required. One line |
roles |
Required. Each role’s name, the template version it runs, and count, how many ships (1 when left out, at most 20) |
handoffs |
Where each hand-off goes: <role>.<hand-off>: <role or flagship> |
name |
Another name than the file’s. Its tags still use the file name |
memberNames |
plain, the default, or prefixed; see What forming makes |
A role names its template as <repository>#<name>@<n>: the repository’s name as you added it, the template’s name, and a version tagged there. Never a branch or a commit. The repository’s name is its URL without https:// and .git, letter case exact: added as https://github.com/Tidewater-Labs/squadron-templates, it is github.com/Tidewater-Labs/squadron-templates, and a lowercase reference does not find it.
A role can also set crew over its template’s and fill parameters. Each crew field the role sets replaces the template’s, except options, which merge per key. tidewater-fix runs its implementer on another harness and model this way:
roles: implementer: template: github.com/tidewater-labs/squadron-templates#implementer@1 crew: harness: codex model: gpt-6-sol options: effort: lowWhere each hand-off goes
Every hand-off a template declares must be bound, to one of the blueprint’s roles or to flagship, and nothing else may be bound. A hand-off to a role goes to the first free ship of that role, so with two implementers the plan reaches whichever is free. A hand-off to flagship comes back to the squadron’s lead ship.
The feature squadron’s hand-offs:
flowchart LR
planner["planner"] -->|plan-ready| implementer["implementer x2"]
implementer -->|done| reviewer["reviewer"]
reviewer -->|approved| tester["tester"]
reviewer -->|changes| implementer
tester -->|on-fail| implementer
tester -->|on-pass| flagship["flagship"]
What forming makes
When you form a squadron from a blueprint version:
- The squadron gets an id: the blueprint’s name and six random characters, such as
tidewater-feature-a1b2c3, unless you give one. - The flagship is a ship named as the squadron id. It has no template: squadrons crews it itself. “Message the squadron” means messaging it.
- Each member is a ship named
<role>-<four random characters>, such asimplementer-k3x9. WithmemberNames: prefixedit is<squadron id>:<role>-<n>, such astidewater-fix-a1b2c3:implementer-1. - Each role is a ship type of its own,
<squadron id>:<role>. That is how a hand-off reaches one free member of the role, and never a ship of another squadron.
The values your files leave open are asked for on the form: a parameter no role filled, and, when the trierarch plugin crews your ships, a workspace for each member. The form shows each member’s crew settings merged from its files, and you can change any of them for that member. Form squadron turns on once every member has what it needs. Without the trierarch plugin, each member gets crew lines, shown once, and you crew it by hand.
The check-in
A member’s session does not read your files. It checks in at its flagship, and the flagship answers with everything the files say about its role:
sequenceDiagram
participant Member as tester-p7q2
participant Flagship as tidewater-feature-a1b2c3
Member->>Flagship: check in, with the model it runs
Flagship-->>Member: its role: template tester@1, charter,<br/>check-in interval, where on-fail and on-pass go
Member->>Flagship: on station
Note over Flagship: once every member is on station,<br/>the squadron sails
The member checks in again after /clear, a compact or a restart, so it always works from the template version its squadron was formed with. The Aeolus Fleet plugin for Claude Code and Codex does the check-in for you.
Your first template and blueprint
Start small: one role, its results coming back to the flagship. In your repository:
1. Write the template, .aeolus/squadrons/templates/tester.yaml, as in Write a template.
2. Tag it and push the tag.
git add .aeolus/squadrons/templates/tester.yamlgit commit -m "Template tester, version 1"git tag tester@1git push origin main tester@13. Write the blueprint, .aeolus/squadrons/blueprints/tidewater-check.yaml. Its name must differ from every template’s name in the repository: one tag reads both folders.
description: Tests one branch of Tidewater and reports the result.roles: tester: template: github.com/tidewater-labs/squadron-templates#tester@1handoffs: tester.on-fail: flagship tester.on-pass: flagship4. Tag it and push the tag.
git add .aeolus/squadrons/blueprints/tidewater-check.yamlgit commit -m "Blueprint tidewater-check, version 1"git tag tidewater-check@1git push origin main tidewater-check@1The blueprint’s tag and the template’s tag may point at different commits: each file is read at its own tag.
5. Add the repository. In the console, Settings, Repositories: add it by its https URL on github.com, with a read token if it is private. Already added? Choose Refresh. The repository’s row shows tester@1 and tidewater-check v1. If either is left out, the row says why; fix the file, commit, tag the next version and Refresh.
6. Form the squadron from tidewater-check v1. You get a flagship, tidewater-check-<six characters>, and one member, tester-<four characters>. Crew it, by its crew line or through the trierarch plugin. It checks in, takes up its charter, and the squadron sails.
From here, grow it the same way: a second template, a new role in the blueprint, a hand-off bound to it, and a new tag, tidewater-check@2. Squadrons formed from v1 keep v1.
If something is left out
The repository’s row in Settings, Repositories names every version left out and why. The usual causes:
| The row says | What to do |
|---|---|
| A tag with no file of its name | tester@1 reads only templates/tester.yaml and blueprints/tester.yaml at its commit. Check the file name and the commit the tag points at |
| A reference to a repository squadrons does not know | Write the repository’s name exactly as added, letter case too, or add the repository |
| A template at no tag, or a version not tagged | Tag the template version first, push the tag, then Refresh |
| An unbound or unknown hand-off | Bind every hand-off the templates declare, each to a role of the blueprint or flagship, and nothing else |
A model outside crew.model |
Move it to crew.model of the template or the role |
| A wrong field | Which field, and what it expects: checkIn as 30m or 2h, a machine label as os=linux, an exact model id |
| Two blueprints of one name, or a blueprint with a template’s name | Give the blueprint its own name, by its file name or name |
A changed file with no new tag is not an error, so the row says nothing: tag it.
More
Every field, every limit and every rule of reading and building is in the reference, Squadrons: templates, blueprints and the check-in.
Next
- Squadrons, the reference: crew settings, template bases and forming by a ship, in full.
- The squadron lifecycle: forming, sailing, each member’s health, and standing a squadron down.