@zenera/cli 1.1.25 → 1.1.27

package/templates/project/agents/fork-instructions.md

@@ -45,34 +45,31 @@ Every `fork` call takes an array under `branches`, even for a single branch:
 Never pass branch fields (`name`, `instructions`, `agent`) at the top level of
 the tool call.
 
-Do not fork a sequence. Branches run at once and can exchange nothing, so a step
-that needs the step before it has to stay in this conversation.
-
 ## When the assignment is yours
 
 These rules reach a branch as well as the agent that forked it, and a branch
-arrives in the middle of someone else's sentence. Your assignment comes to you
-as the result of a `fork` call, because that is how the runtime delivers it —
-and that is indistinguishable, in a transcript, from a fork you made yourself
-coming back with an answer.
+arrives in the middle of someone else's sentence. Under `inherit` or `compact`
+your assignment comes to you as the result of a `fork` call, because that is how
+the runtime delivers it — and that is indistinguishable, in a transcript, from a
+fork you made yourself coming back with an answer.
 
 It is not one. When a message begins "You are branch ... of the fork above", you
-are that branch and that text is your assignment:
+are that branch and that text is your assignment. Under `none` there is no such
+message, only the instructions as the first message of the conversation; when
+they say you are a branch, the same holds:
 
 - **Nothing has run yet.** There is no result in it and nothing to verify. The
   fork it names is above in the conversation you were forked out of, which is
   not the one you are in — yours begins with that message.
-- **Do the work yourself.** Never fork a branch to carry out the assignment you
-  were handed: that branch is you one level down holding the same instructions,
+- **Do the work yourself.** Never fork one branch holding your whole
+  assignment: that branch is you one level down holding the same instructions,
   it will read them the same way, and each level spends a whole system prompt to
   arrive back where it started. At the depth cap the tool is withdrawn and the
-  work comes back undone.
+  work comes back undone. If the assignment names two or more independent
+  deliverables, fork one branch for each, or do them all yourself.
 - **Do not go looking for proof it was already done.** An empty workspace is
   what an unstarted job looks like, not a sign that something failed upstream.
 
-Fork from inside a branch only for work that is genuinely divisible further and
-that you were not handed already divided.
-
 ## When it is worth it
 
 One question decides it: **could this be finished by someone who cannot ask you
@@ -82,7 +79,7 @@ no, the work stays here.
 | The work in front of you                                                                     | What it is                                               |
 | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | The same question asked of twenty things — files, endpoints, regions, candidate fixes        | A fan-out: one branch each, merged by you                |
-| One task whose parts need different skills and none of them the others                       | A fan-out too: each branch on the agent that fits        |
+| One task whose parts need different skills and no part needs another's result to start       | A fan-out too: each branch on the agent that fits        |
 | A job another agent is plainly better at                                                     | Delegation: one branch, on that agent                    |
 | Long and noisy with a short verdict — a build loop, a bisect, a survey that may find nothing | Delegation: you get the verdict, not the noise           |
 | Find the config, then change it, then test it                                                | Not a fork. Each step needs the one before it            |
@@ -92,6 +89,36 @@ no, the work stays here.
 | The assignment you were handed, whole                                                        | Not a fork. It is yours — see above                      |
 | Two jobs that would write the same file                                                      | Not a fork until they write different files — see below  |
 
+Do not fork a sequence. Branches run at once and can exchange nothing, so a step
+that needs the step before it has to stay in this conversation. A step depends
+on another only when it cannot be _written_ without that result. When that
+result can only be one of a few values known in advance, it is not a
+dependency: fork the step now for all of them, have it return its result keyed
+by value, and keep the one that applies after the join.
+
+Before a one-branch `fork`, list what the request asks you to hand back. If two
+or more of those items are independent — none needs another's result, and each
+takes more than one call — give each its own branch in the same call.
+
+## Hand-off or fork
+
+Both reach another agent; they differ in who holds the conversation afterwards.
+
+|                   | `transfer_to_<agent>`                                                 | `fork`                                             |
+| ----------------- | --------------------------------------------------------------------- | -------------------------------------------------- |
+| Control           | moves to the other agent and stays there; it answers every later turn | comes back to you at the join                      |
+| What it sees      | this whole conversation, every tool result included                   | what `context` gives it, plus your instructions    |
+| What you get back | nothing; you are done                                                 | its final message                                  |
+| Parallel          | no, one agent at a time                                               | yes, one branch per part                           |
+| Cost              | the whole transcript on every call it makes from now on; no merge     | each branch's own context, plus your turn to merge |
+
+Hand off when the rest of the conversation belongs to the other agent: the
+user's next question will be in its domain too, and you have nothing to add to
+its answer. Fork when you need the result back — to combine it with other parts,
+check it, or keep the conversation yourself. A request with two or more
+independent deliverables is a fork, even when one agent could do all of them: a
+hand-off cannot fan out and cannot come back.
+
 ## Fanning out
 
 Branches run at the same time, so a fan-out costs about as long as its slowest
@@ -139,30 +166,54 @@ whatever that branch needs, because a sibling's finding will never reach it.
 ## Choosing `context`
 
 `context` decides what each branch starts from. It is one setting for the whole
-call, chosen per call:
+call, chosen per call; leave it out and you get `inherit`, the most expensive:
 
 - `inherit` — everything said here so far. For work that only makes sense
   against the case as it stands: reviewing what has just been written here,
   continuing an investigation whose earlier findings are the thing being built
   on.
-- `compact` — the same, without the tool traffic: what was decided, not how it
-  was found out. The usual choice for a wide fan-out, where branches need the
-  case and the plan but not the fifty reads that produced them.
+- `compact` — the same, without tool calls, tool results or memory recalls:
+  what was decided, not how it was found out. The usual choice for a wide
+  fan-out, where branches need the case and the plan but not the fifty reads
+  that produced them.
 - `none` — nothing but its own instructions. The cheapest, and the honest one
   when the assignment is self-contained: a lookup, one file summarised, a
   command run elsewhere. Everything the branch needs must then be written out in
   the instructions, paths included.
 
-When two modes seem possible, write the missing facts into the instructions and
-take the cheaper one. Instructions are exact; an inherited transcript is only
-approximately about the branch's job.
+| What the branch starts with                        | `inherit`                            | `compact` | `none`                                      |
+| -------------------------------------------------- | ------------------------------------ | --------- | ------------------------------------------- |
+| Its own agent's system prompt and tools            | yes                                  | yes       | yes                                         |
+| The user's request and the messages here           | yes                                  | yes       | no                                          |
+| Tool calls, tool results, memory recalls           | yes                                  | no        | no                                          |
+| Results of earlier forks                           | yes                                  | yes       | no                                          |
+| Skills loaded here                                 | only if it runs on your agent        | the same  | no                                          |
+| Your whole `fork` call, siblings' instructions too | yes                                  | yes       | no                                          |
+| A fresh memory recall on its instructions          | no                                   | no        | if its agent recalls automatically          |
+| How its assignment arrives                         | "You are branch ...", siblings named | the same  | your instructions alone, as a plain message |
+
+A `none` branch is never told it is a branch. Its instructions must say so, what
+to return, and that only its final message comes back.
+
+When two modes seem possible, or branches would each want a different one, write
+the missing facts into the instructions and take the cheaper one. Instructions
+are exact; an inherited transcript is only approximately about the branch's job.
+
+Under `inherit` or `compact` a branch sees the user's whole request and will
+take all of it as its own. When it gets only part, its instructions must name
+the parts it does not own.
 
 ## What comes back, and what stays
 
-Only the answer comes back, and it is prose. Everything else a branch does is
-real and outlasts it: branches share this workspace with you and with each
-other, so a file one of them writes is a file you can read after the join, and
-anything committed to memory is there for every later run.
+Everything a branch does besides its answer is real and outlasts it: branches
+share this workspace with you and with each other, so a file one of them writes
+is a file you can read after the join, and anything committed to memory is there
+for every later run.
+
+The join is one result for your `fork` call: a `### name (status)` block per
+branch, in the order you declared them, each holding that branch's last message
+or, if it failed, its error. Anything a branch said before its last message is
+not in it.
 
 So decide, for each branch, which of the two carries its result:
 
@@ -187,8 +238,7 @@ builds, two branches reformatting the same tree.
 
 ## When a branch comes back wrong
 
-Each branch reports under its own name, with its status, and a failed one says
-why. What the final answer is remains your decision, not the join's.
+What the final answer is remains your decision, not the join's.
 
 A branch rarely fails at random; the usual cause is an assignment missing
 something it could not ask for. Re-running the same instructions gets the same