Planning work across agents with metis

Work that takes several agents, written down as steps with the moments that need you marked — drafted with metis in a terminal, followed in the app.

A project plan is a piece of work that spans several agents, written down as a list of steps, in order. (An agent is a named worker with its own instructions. A repository is the folder of code your team works in, kept in git.) Some steps are an agent’s work. Some are moments that need you — a question to answer, a folder or a link to bring, an agent to start — and the plan marks each of them. Zeus keeps the plan, files its tasks on the work board when you say go, and shows you where it stands. A plan lives on the Mac that drafted it: teammates do not see the plan itself, though its tasks travel as any task does.

metis is the agent that drafts the plan with you. It is built into Zeus for every repository Zeus knows: nothing declares it, it is not listed in .zeus/agent.toml or by zeus agent list, and it cannot be retired — unless your repository declares its own metis in .zeus/agent.toml; then that one runs. It only drafts. It never starts an agent, never takes a task, never merges a pull request, never writes code, and never answers a gate for you (a gate is a question in the plan that only you answer; section 5 lists every kind of step).

This guide assumes Zeus is installed and set up on your Mac — see Getting started. If the repository belongs to a team, Joining a team explains how to join it first.

1. Start metis

Open a terminal, go into the repository the work is for, and run:

zeus run metis

That opens Claude Code with metis as the agent, in that repository. To use Codex instead:

zeus run metis --runtime codex

The conversation with metis happens in that terminal. Nothing in the app drafts a plan; where the app names metis, it shows this command as text for you to run.

Its first words: it says who it is — “I am metis. I turn a piece of work into a plan: one step per agent, in order, with the points where you decide.” — then asks “What matters most to you in this plan — what should it highlight?”, then “How would you like to start?”: give it a document or a write-up (a path, or paste it), answer a few short questions, or do some of both. Only when plans already exist in this repository, a last line names them: “Plans already here: <list>. Say one to return to it, or go on.”

2. As you talk

metis asks four questions, one at a time, in this order: what the goal is; how you will know it is finished; what must not change while it is done; who will use or read the result. It skips any that your document already answers, and you can say “stop” at any time and give it material instead.

It writes the plan into Zeus as it goes, and says the plan’s id once, so you can watch it in the app. This guide uses P-1 as the example. Every step in a plan has a short key that metis gives it, such as package or start-g, and is named by its plan and key together: P-1/package.

For every step that is an agent’s work, metis proposes which agent takes it, with a reason. Zeus calls each agent’s row in a plan a lane. Only an agent your repository declares in .zeus/agent.toml can take a step. A step that no agent fits stays “nobody yet” — metis never hands it to a default agent — and a plan cannot start while one is: Zeus refuses with “P-1 cannot be set in motion while a task or launch step is for nobody yet: … — route it first.” Give that step an agent, or drop it, before you say go.

When the product itself is not decided yet, metis may run one design helper inside its own session, and show you its draft. That helper is not one of the plan’s agents and takes no task; its draft is a proposal, and you approve, change or stop it in the conversation.

metis drafts the whole plan first and shows it to you once, in plain words, with one question: approve, change it (say what), or go through the choices one by one.

3. The plan written down

After you approve, metis writes the plan as a Markdown file, P-1-<short-title>-plan.md, and when a design was made a second file, P-1-<short-title>-design.md, into the folder where the repository keeps its design documents. It opens one pull request with them — a proposed change to the repository that a person reviews and merges. Merging it is yours to do. The plan holds a check step, design-merged, that waits for that merge, so the steps that build things wait too.

4. Say go

metis asks once: “Shall I set P-1 in motion? Yes puts every task on the board for its agent, with you as the sponsor.” The sponsor is the person each task is filed for. Say yes in the metis session: metis records your words on the plan’s own gate, P-1/set-in-motion, and then files the tasks. (An answer to that gate from a terminal records your yes and files nothing until metis starts the plan — Zeus replies “approved; P-1 is set in motion when its project manager starts it.”) Say “revise” and what to change, or “stop”, and nothing is filed. If you leave the session before saying yes, the plan stays a draft: run zeus run metis again and name the plan to go on from there.

After your yes, metis says what is next, and stops. First it is the plan’s pull request: until that is merged, metis names its check step with its link, and the steps that build things wait. Merge it. Then the next move is an agent to run — “Next: run athena — it will find T-12 ready. Starting an agent is yours to do, not mine.” — and you start it, in the plan’s repository:

zeus run athena

5. The six kinds of step

In the order Zeus lists them:

A plan is a draft until you say go, then in motion, and stopped if you stop it. A plan in motion reads done when every step has ended.

6. When it needs you

In a plan in motion, a gate, a handoff or a launch whose turn has come appears as a card on the Needs you page, headed with the plan’s title, the kind and its age — for example “Ship 0.9 · gate · 40 min”. The same cards appear in the Dashboard’s For you band. Tasks, checks and milestones never make a card.

A gate is a question card. Press Answer: its options appear, with a field for your words. Choose one — the button then reads Answer: Approve, or the option you chose — add your words for revise or stop, and press it.

A handoff shows what is expected, a drop well that says Drop a folder or a file here · inside the repository, and a field, or paste a link, with a Hand over button. Drag a folder or a file from inside the repository onto the well (“Release to hand it over” — Zeus takes its path; nothing in it is read), or paste one link and press Hand over. The card clears when Zeus has recorded it. If Zeus refuses — for example “… is not inside a checkout of <repository> — drop a folder from inside the repository, or supply a link.” — the card comes back with that sentence. The card appears once the steps before the handoff have ended, and a handoff is supplied once.

A launch shows the command, such as zeus run hephaestus, and says Run it in a terminal. This clears when Zeus sees hephaestus start. There is nothing to click.

From a terminal

Answer a gate with the step’s name and your choice; revise and stop need your words:

zeus plan answer P-1/<key> approve "your words"

zeus plan answer P-1/<key> revise "what to change"

zeus plan answer P-1/<key> stop "why"

Zeus replies with what your answer did — “answered P-1/start-g — the step ended, and T-12 is ready for athena.”, “… the plan stays open with your words on the gate.”, or “… the plan is stopped.” For the plan’s own gate it is “answered P-1/set-in-motion — approved; P-1 is set in motion when its project manager starts it.” The same answer can be given as zeus work answer P-1/<key> approve, the way you answer any task.

Supply a handoff with a path or a link:

zeus plan supply P-1/<key> <path-or-link>

A path must exist and lie inside a checkout of the plan’s repository; a link starts with http:// or https:// and is written on one line. Zeus replies “supplied P-1/package: … — the step ended”, and names any task the handoff made ready.

7. Follow the plan

In the rail, the list down the left side of the window, Project plans sits under the workspace, with a count of what waits on you. Until a plan exists it says No project plans in this workspace. Run zeus run metis to draft one.

The list has one row per plan: its repository, its title, its state (“in motion since 5 Oct · amended 7 Oct”), its progress (“5 of 11 done · 1 failed · 2 in hand · 1 waiting on you · 2 not yet”), waits on you: and what, the next move in the same words as the terminal (“you — answer P-1/start-g”), and Since you looked: — the steps that ended since you last opened it. Plans in motion come first, then done ones, then stopped ones with your stopping words in quotes, and drafts last. A draft reads Draft · continue with metis, with the command to run.

A plan’s page opens from the list. At the top, a lead sentence says where the plan is — “Three steps are in hand. Nothing waits on you.”, or when nothing is in hand and nothing waits on you, “Idle. Next is: run athena.” — followed by three lines:

• Progress — “6 of 13 done · 1 failed · 3 in hand · 3 not yet”;
• Where we are — the last milestone reached and the next one (“stage 0 reached · next: ready for the site”); absent when the plan has no milestone;
• Working now — “2 agents working now ›”, which unfolds to one row per step in hand, or “Nobody is working on this plan right now.”

Below is the plan drawn as rows: one row per lane, and your own row first, holding every gate, handoff, check and milestone. A YOU ARE HERE band marks the present, and the next milestone is named beside it. Each step is a card — “done · 5 Oct”, “failed”, or how long it has been in hand. Click a step to open its details, including, for a handoff, what was supplied and by whom. Steps that ended since you last looked carry a dot. At the bottom, History lists what happened — asked, answered, filed, reached — with who did it and your words in quotes. The page reads from the board, so it needs no metis session to be open.

The Dashboard’s Work items tab puts one section per plan in motion above everything else, with the plan’s progress, open plan ›, and its rows: what is in hand, what waits on you, and what is ready with no one running. The sections below are marked · outside a plan.

From a terminal

Both commands read your Mac’s own copy of the work board directly.

zeus plan list

One line per plan in this checkout’s repository: its id, title and state (“draft”, “in motion since 2d ago”, “done”, “stopped”), how many steps ended, who it waits on, and “next: …”. With no plan it prints “no project plans here — a plan is drafted by the project-manager agent through its plan tool.”

zeus plan show P-1

A header — the id, the title, the state, “k of n ended” and the repository — then goal:, done when:, the start question’s state and your words, and one numbered line per step: its key, its kind, whose move it is, its state, and the command that moves it. After the steps, next: names the next move (“you — answer P-1/start-g”, “you — supply P-1/package”, “you — start athena in the plan’s repository”, or “athena — T-12 (ready)”). Then HISTORY: every event, with your words as you said them.

8. Change or stop a plan

To change a plan, talk to metis again. Run zeus run metis in the same repository and name the plan. metis reads the board and says what happened since you last looked, what is in hand, what waits on you and what is next, then asks what you would like to change. You can remove a step, restate one whose task failed, change one, re-order one, or move one to another agent. A removed step’s task fails with your words on it; it is never deleted. A change made before the plan is in motion asks the start question again; a plan already in motion keeps going, and new steps are filed when metis starts them.

To stop a plan:

zeus plan stop P-1 --note "your words"

Its open tasks fail with your words, and Zeus replies “P-1 stopped: k tasks failed with your words, m questions answered.” Answering any gate of the plan with Stop the plan stops it the same way.

A step’s state is never typed in by metis or by you: Zeus reads it, every time, from the one thing the step points at — its task, its question, the file you supplied, or the agent’s session.

9. Commands

zeus plan --help prints:

zeus plan                         (no verb) this help
zeus plan list                    every project plan in this checkout's repository
zeus plan show <P-n>              one plan: its steps, what each waits on, what is next
zeus plan answer <P-n/key> <approve|revise|stop> ["words"]
                       [--via app]  answer a gate; revise and stop need your words
zeus plan supply <P-n/key> <path-or-link> [--via app]
                                  supply a handoff: a link as given, or a path in this checkout
                                  (or, from no checkout, an absolute path inside one)
zeus plan stop <P-n> --note "words" stop a plan; its open tasks fail with your words

  Plans are DRAFTED by the project-manager agent through its `plan` tool —
  never from here. Here you answer a gate, supply a handoff, stop a plan, and
  look. `zeus work answer P-n/key approve` reaches the same answer.

The verbs take no --help of their own.