multi-agent-coding

# Coding with sub-agents ## 1. A coding agent for the work Coding work goes to a coding agent on the roster: the one the user named, otherwise one the `## Delegation` section says owns coding, otherwise one whose description says it writes or edits code. When a Worker Table is bound, `subagent` takes worker labels instead: pick the worker whose brief covers the coding work. When none does, tell the user and ask how to go on rather than writing the code yourself or sending it to an agent outside the enum. ## 2. One instance per task An instance is one conversation with one agent, named by the `instance` handle. - A new task gets a new instance, never an earlier task's handle, which would carry that task's context into it. That holds for a task built on a finished one, such as docs for a finished feature: it starts fresh, with the earlier task's output file (section 3). - A follow-up on an unfinished task - a correction, a bug in what it did, "keep going" - goes to that task's instance: same `subagent`, same `instance`, a new `node_id`. The agent keeps its context, so the prompt carries the new request in the user's words. - Send a follow-up only once the instance's running dispatch has returned: sent sooner, it can start a separate conversation without that context. ## 3. Results by file When a task needs what another produced, put that task's output file in its prompt - `{{ <node_id>.output_path }}` of its last dispatch - instead of retelling the result. The file is the agent's report, not the code, so also say where the code is (section 4). ## 4. A worktree per task in a shared project Local sub-agents share this session's working directory, where nothing locks a file, and giving each agent its own files there does not isolate them: tests run against the other's half-made edits, and one agent's `git stash` or `checkout` wipes the other's work. So when a coding task will run beside another in the same project - dispatched together, or while the other is running or unfinished - its prompt tells the agent to make its own worktree, on a branch you name for the task (`fix/login-session-expiry`), so the work can be found even if the agent stops before reporting: > Create a git worktree of your own for this task on a new branch `<branch>`, outside the > project or in a directory git ignores. Work only there, and end your report with its > path and branch. If the project is not a git repository, do not make it one: work in > place on only this task's files, and say so. - Every later prompt for the task - a follow-up, a takeover (section 5) - names its worktree: the branch, and the path from the report. A task built on its code, such as docs for it, works there too once the task has finished. - A worktree starts from the last commit, without the checkout's uncommitted changes. When the request depends on them, ask the user before dispatching. - When the work is done, tell the user which branch holds it. Merging the branch or removing the worktree is work for the task's instance, once the user asks. ## 5. Out of quota: another coding agent When a coding agent's result says its usage limit, quota, credits or balance is used up - often with a 402 or 429 status or a reset time, in whatever words or language - send the task to another coding agent right away. - Pick one that does not draw on the same account: agents that run through one platform share its quota, and a spent platform credit fails them all. - When a Worker Table is bound, the takeover goes to another worker whose brief covers it and that runs on a different agent, by the same account rule. - Use a new `node_id` and a new `instance`. The old instance's context does not carry over, so the prompt carries what the task needs: the user's requests on it, the worktree's branch and any path a report gave (the worktree may hold the first agent's unfinished changes), and the output files of the task's finished dispatches. From then on, the new instance is the task's instance. - Tell the user which agent ran out (and when it resets, if it said) and which took over. Do not send the task back to the one that ran out; when no coding agent is left, ask the user how to go on. - In a graph, answer the node's report with `replan`, putting its work on another coding agent under a new id. `continue` would send it back to the agent that ran out, and the user need not be asked. Raven's own limits refuse every agent alike, so follow the refusal instead of switching agents: a `spawn` or graph refused because this session hit its spawn rate limit or its dispatch rate limit, because delegation is paused, or because the host is shutting down.