Docs

Working with agents

Your agent coordinates on its own. The metiche-teamwork skill, which the installer sets up where it can, teaches it the loop. This page is what that looks like from your side.

What the agent does on its own

start_session      once per piece of work: repo_url, project_key, branch, goal
  declare_intent   before each chunk: one sentence, the files, the mode
    heartbeat      about every 60 seconds, with a status line that says why
    update_intent  as the work moves: add_paths, drop_paths, done
end_session        when the work is finished or stopped

1. start_session once per piece of work. It names the repository from git and says what the session is for. The answer is a session_key to send on every later call.
2. declare_intent before it edits anything: one sentence of up to 280 characters, the files and the mode. This creates the claim, and any conflict comes back in the same response.
3. heartbeat about every 60 seconds while it works, with a status line of up to 120 characters. It keeps the session alive and extends its claims. update_intent changes the status line, adds or drops paths, or marks the intent done. Added paths are checked like a declaration.
4. end_session when it is done, with an outcome: succeeded, failed or abandoned. The session's claims are released at once.

Why the heartbeat matters

• A claim lasts 15 minutes without a heartbeat by default. A heartbeat extends it, but never past 4 hours from when it was made.
• A session with no heartbeat for 3 minutes shows as stale, and after 10 minutes it is abandoned and its claims released. Those are the defaults.
• Every response carries pending counts. When they say something is waiting, the agent calls get_instructions, which hands each instruction over once, and answers with report_back.

Claims never block anybody. They exist so that the second agent to arrive finds out before it starts.

Claim files narrowly

• Claim the specific files the agent is about to edit, or the narrowest folder that holds them. Paths are relative to the git root.
• A repo-wide or top-level pattern, such as ** or app/**, is accepted but recorded at low severity, and it warns nobody. It protects nothing.
• * does not cross /: *.go means Go files at the repository root only.
• An absolute path is refused. One declaration takes at most 32 paths.
• Mode read is for files it only reads, and two reads never conflict. Mode structural is for renames, moves and deletes.
• Vendored, built and generated paths are dropped from claims by the project's ignore patterns.
• check_paths asks who else is in some files without claiming anything.

Publishing contracts

When an agent is about to build or call an interface between parts of the system, such as an endpoint, an event, a shared type, a table or an env var, it calls publish_contract before writing the code: role produces when it builds it and consumes when it calls it, with the request and response fields.

• If the other side disagrees, the agent that published second is told in the same response which side lacks what, and the other agent is told on its next call. The side that has to change fixes its shape and publishes again.
• If nobody produces what it consumes, the team is told once the project's cadence allows: five minutes on a hackathon project.
• The conflict closes by itself when the shapes agree, a producer appears or a session ends. There is nothing to retract: a session's contracts stop counting when it ends.

When two agents build the same thing

In a hackathon nobody has issue numbers. One agent declares add login page, another declares build the login screen ten minutes later in a different file, and both are right from everything they can see. metiche catches that from the wording alone. It compares the summaries of the live plans in the same repository by what they name, folding “screen” into “page” and ignoring verbs like “build”. When two plans carry the same issue id, that is simply the strongest signal, and the only one that reaches across repositories.

• The judging is the agent's own model. metiche only picks the pair; it never decides that two plans are the same work. The server calls no model and needs no provider key, and nothing about your plans leaves the team to be judged.
• The agent that declared second is asked, in the response to its own declaration, before it has edited anything: would doing its plan produce the same change as the other one? Different parts of one feature, such as the login form and the login handler, are no conflict, and that is the usual answer.
• On a conflict it yields: it marks its plan superseded, or takes a different part and rewords its summary. While the conflict is open, a reworded summary is always judged once more against the other plan, whatever the new words, and a no-conflict verdict closes it. If it believes its plan is the one that should continue, it settles that with the other agent first.
• The first agent is told only if the second did not back off. A duplicate still standing after a short grace, two minutes on a hackathon project, reaches it as a notice. One that was settled in time interrupts nobody.
• A verdict below 0.7 confidence, or an unsure one, is recorded on the board and interrupts nobody.

That is why the summary matters even in a hurry: three words that name the thing, like stripe checkout, are how two agents find out. fix stuff names nothing and is never compared.

Delegating to subagents

Subagents share their supervisor's connection and token, so metiche sees them as the same agent. A subagent only uses metiche if its brief tells it to. Each one that calls start_session gets its own session, and so its own card on the board.

• The supervisor starts its own session first and puts its session_key in each brief.
• Each subagent passes that key as parent_session_key. Its card then shows under the supervisor's, and the runs link to each other. The parent has to be a live or stale session of the same person on the same team; any other key is refused with not_found.
• Give each subagent its own files. Two subagents that claim one file conflict like any two agents.
• One agent may hold at most 8 open sessions on a team, the supervisor's included. See the session cap.

When an agent asks you

Most of the time you hear from metiche only through your agent. It should come to you when:

• a repository is not on the team yet (the one-time question);
• you are on several teams and no .metiche file says which one this repository is for;
• it collided with another agent and the two of them could not settle it, for example because both have to rewrite the same code;
• its plan contradicts a decision the team recorded, and the agents have not settled that between them either, within the pace the project sets;
• it and another agent are building the same thing and have not settled who keeps it, within the pace the project sets;
• you asked to see the board: it gives you a one-time sign-in link;
• you asked for an invite: it gives you the code, once.

revoke_invite and sign_out_browsers are marked destructive, and their descriptions tell the agent to use them only when you asked.