# Planning and Flowcharts

## Overview

**This is not a "team lead" skill reserved for whichever agent happens to
receive the user's request.** Any agent whose work fits the scope in
[SKILL.md](../SKILL.md) (genuine multi-agent work) uses it, and the same
judgment recurses: the top-level agent may decide to split the user's
ask into nodes and dispatch them; an agent that receives one of those nodes
independently judges whether *its* piece should be done directly or split
further into its own sub-nodes, using this same skill again in its own
session. Whether to split is never decided by how the task was phrased
(the owner may say "帮我做 X", not "你来统筹") — it is decided by the shape of
the work itself, per the [judgment criteria](#when-to-split-vs-do-it-directly)
below.

When you do split, the flowchart message you post and edit is the entire
state of *your own* piece of the work — the backend holds no flow state at
all. Whoever dispatched you (if anyone) never sees your diagram directly;
they only see what you report back.

This skill assumes you already know `grix-agent-dispatch` (dispatch
mechanics, `report_dispatch_result` wire format), `message-edit` (the
`grix_message_edit` tool's contract and limits), `grix-egg` (egg market
discovery and install), `grix-admin` (creating a new agent), and
`grix-scheduled-trigger` (webhook + scheduler wake-ups). Read those first if
you have not used them before — this skill only adds the orchestration layer
on top; it does not repeat their contracts.

## When to split vs. do it directly

When a task may need other agents — your own first turn on the user's ask, or
a node task someone else dispatched to you — judge it against these signals. None of
them require the sender to have said anything like "coordinate this":

Split it when one or more of these is true:

- It genuinely needs **another machine or another working directory** you
  cannot reach yourself (a different repo, a different host).
- It needs a **CLI, tool, or skill you do not have**, that another of the
  owner's agents does have (or that the egg market can supply — Step 2).
- It contains **multiple independent sub-tasks that can run in parallel**,
  where doing them serially yourself would waste real wall-clock time the
  owner is waiting on.
- It is large enough that finishing it **in one session would run past a
  reasonable single-turn length** (a multi-day migration, a feature spanning
  several unrelated modules, anything you would otherwise have to checkpoint
  awkwardly mid-way).

Do it directly — do not invoke the rest of this skill — when none of those
apply. Concretely: a single fix, a single file, a question you can just
answer, anything you could finish in one normal turn yourself. **Do not draw
a flowchart and dispatch a node for something you could just do.** The
overhead of this skill (inventory, flowchart message, watchdog, multi-step
bookkeeping) only pays off once the task actually has more than one
independent piece to track.

If you are unsure, default to doing it directly — dispatch-and-track has an
API and time cost, wrongly avoiding it does not.

## Step 1 — Inventory available agents

Call `grix_query` with `action: "contact_search"` (agent contacts come back
with `peer_type: 2`) to list the owner's agents: `peer_id` (agent id),
`display_name`, `introduction`.

Be honest about what this data can and cannot tell you:

- There is **no direct query for client type or online/connectivity status**.
  Do not claim to have checked either — infer capability and fit only from
  `introduction` text (agents typically self-describe their role, tech stack,
  and sometimes which project directories or machines they work in — this
  session's own introduction is an example of that pattern).
- **Prefer an agent whose introduction already names the target `cwd` /
  project** for a node in that directory — it avoids the cross-machine
  "wrong local checkout" mismatch that comes from assigning a directory-bound
  node to an agent that has never worked in that tree. If no introduction
  gives you enough to judge, ask the owner rather than guessing.
- There is no reliable pre-flight "is this agent online" check either.
  Treat unavailability as something `grix_dispatch_agent` or the receipt
  wait tells you, not something you predict in advance: a dispatch that
  errors, or a node that never reports back even after the watchdog checks
  `grix_chat_state_query` (see [watchdog procedure](receipts-and-watchdogs.md#step-8--watchdog-for-dispatched-but-silent-nodes)), is your actual signal that an agent
  is not currently usable — reassign the node then, not before.

Never invent an agent name or ID that is not in this list.

## Step 2 — Fill a capability gap (缺人就配人)

If no existing agent fits a node, do not leave the node stuck or silently
drop it — go to the egg market via the `grix-egg` skill:

1. `grix_egg_search` with keywords distilled from the node's task (per
   `grix-egg`'s search strategy). Present/consider the top candidates.
2. **A skill egg** (`existing_agent_client_types` matches an existing
   candidate agent's likely client type): `grix_egg_get` for `skill_zip_url`.
   You cannot write into another agent's skill directory yourself — instead,
   dispatch that agent with a task whose *first* instruction is to self-install
   the package (`技能包: <skill_zip_url>`, per `grix-egg` Part 2's self-install
   steps) and only then proceed with the node's actual task. Say so plainly in
   the dispatch `task` text so the target agent knows to install before working.
3. **A persona egg** (`can_create_agent: true`) or no existing agent could
   ever fit: use `grix-admin`'s `create-and-connector-bind` workflow to create
   a **new** agent on this machine, apply `persona_zip_url` the same way a
   `人格包: <URL>` instruction would if the egg has one, then dispatch the
   node to it normally.
4. **Nothing in the egg market fits either**: stop and ask the owner — tell
   them which node has no candidate and what the egg search turned up (or
   that it turned up nothing). Do not fabricate a capability or force a
   mismatched agent onto the node.

Track every agent you newly created or newly equipped with a skill this way —
list them separately in the final summary (see [closeout procedure](receipts-and-watchdogs.md#step-9--close-out-final-summary-and-reporting-up)) so the owner can decide
whether to keep them.

## Step 3 — Decompose and plan

For each node, decide and write down (for your own planning):

- Which agent it goes to (name + numeric ID) — from Step 1 or newly
  provisioned in Step 2.
- The working directory (`cwd`) it will operate in.
- The task text, and what counts as done (the acceptance evidence you expect
  in its `report_dispatch_result` `detail`).
- Its relationship to other nodes: parallel (no dependency) or sequential
  (depends on one or more other nodes finishing first).

Before dispatching anything, send the owner a short **2–3 line plan
summary** in plain text (which nodes, which agents, parallel vs. sequential,
what evidence closes each node), followed immediately by the initial mermaid
flowchart message from Step 4. This lets the owner object to the plan or the
agent choice before any work starts.

## Step 4 — Post the flowchart message

Send **one** message containing a mermaid `flowchart` — this is the message
you will keep editing for the rest of the flow. Include:

- One node per agent/step, labelled `<agent name>: <one-line task>`.
- A status style class per node: `pending` (not yet dispatched),
  `running` (dispatched, no receipt yet), `done`, `failed`.
- One line above or below the diagram with a flow id (any short string you
  generate, e.g. a timestamp-based tag) and the start time — you need the flow
  id to recognize this as your own flow if you look back at message history
  later.

Send it with `grix_message_send` (as yourself — this is your own status
message, not an owner-relay send) and **record the returned `msg_id`**. That
id is both the flowchart message you will edit, and the callback anchor for
every node's `report_dispatch_result` (i.e. every dispatched node's callback
`quoted_message_id` points at this same message).

See the [example](recursion-and-examples.md#example-three-node-flow-two-parallel--one-sequential-roll-up)
for exact mermaid syntax and styling.

## Step 5 — Dispatch every ready node

For each node whose dependencies are already satisfied (all parallel nodes,
plus any sequential node whose predecessors are already `done`), call
`grix_dispatch_agent` per `grix-agent-dispatch`, with the callback pointer's
`callback_session_id` = your current session, `quoted_message_id` = the
flowchart message's `msg_id` from Step 4. Dispatch **all** currently-ready
nodes together — do not stagger parallel nodes one at a time.

Do not dispatch a node whose dependencies have not finished yet. Do not
dispatch a node twice — if a node already has a live dispatched session
(you have not yet received its receipt), leave it alone; a duplicate dispatch
wastes the target agent's time and produces two racing receipts for one node.

Immediately after dispatching, set up the watchdog (see [watchdog procedure](receipts-and-watchdogs.md#step-8--watchdog-for-dispatched-but-silent-nodes)) before you end
your turn.

For the recursion cap, layer 3 rule, dispatcher boundary, and worked examples, read [Recursion and Examples](recursion-and-examples.md).
