Carry flow guidance in the catalogue instead of CLI skills

README.md

@@ -605,10 +605,13 @@ It provides these generic tools:
 - **`send_to_participant`** — send a follow-up message to a participant role declared by the flow definition (single-participant definitions use `"reviewer"`; the server rejects an unknown role, naming the valid ones). One round runs at a time per role — a second send to a busy role is rejected naming the busy round, while other roles remain addressable. Returns the new round's findings.
 - **`get_flow_status`** — get the current status (running, waiting, completed, failed) and last result of a flow run. Optional `wait` (boolean, default `false`): when `true`, blocks — via repeated bounded internal checks, never a raw long-poll — until the round is terminal or roughly 3.5 minutes pass, instead of returning the current snapshot immediately. A long-running round is expected, not an error; on that cap this returns the same benign "still running" text an unset/false `wait` already returns on the round-submission path, so simply call it again with `wait: true`. `flow_run_id` is optional: omitted, the newest open flow this session started is read (Cursor, Copilot, Gemini, Kiro, OpenCode and Antigravity give the flows server no session, so there it reads the flows started from the same repository — or working directory — on this machine, which the flows server records in `flow-runs-v1.json` under the config directory) — with several open, the reply lists them to choose from; with none open, the newest settled one, so a failure you were not watching for is still readable — and `session_id` selects another session's flows. The lookup needs a server with the by-session flow route; an older server answers with an error that says to pass the id.
 - **`close_flow`** — mark a completed flow run as closed.
-- **`list_flow_definitions`** — list the definitions this server can start right now: each one's id (what `start_flow` takes as `definition_id`), version, description, whether it is single- or multi-participant, and its participants' role, authored vendor and model. Read-only. Disabled or deleted definitions are absent, a server that predates the route is reported as unable to list rather than as an error, and a catalog still catching up after a read-model rebuild is a retryable `server_catching_up`.
+- **`list_flow_definitions`** — list the definitions this server can start right now: each one's id (what `start_flow` takes as `definition_id`), version, description, whether it is single- or multi-participant, and its participants' role, authored vendor and model. Read-only. Disabled or deleted definitions are absent, a server that predates the route is reported as unable to list rather than as an error, and a catalog still catching up after a read-model rebuild is a retryable `server_catching_up`. Each entry also carries when to use it and whether agents may offer it unprompted (`offer: proactive`) or run it only on request.
+- **`get_flow_definition`** — read one definition's driver guide before starting it: its participants, when to use it, and the authored guidance on what context to submit, how to iterate and when to close. Read-only. An unknown, disabled or deleted id is an error; a server that predates flow guides is reported as publishing none.
 - **`list_start_agent_options`** — read before `start_agent`: which of your daemons are connected on this machine (matched by the machine id a daemon has persisted here; nothing is written), how many agent slots each has free, and which harnesses each can start, plus the harness running the calling session. When no daemon runs on this machine it says so and names `kcap daemon start -d`, because `start_agent` would be refused. A daemon with `max_agents` 0 is shown with no limit. Called from a hosted agent, it says that every start runs on the daemon hosting that agent, which ignores `daemon`. Read-only.
 - **`start_agent`** — start one separate hosted agent in a git repository on this machine, and return at once. **It does not block and it does not poll**: unlike the flow tools above, it sends one request and answers `requested` as soon as the server has sent the launch command, before the agent registers, with the agent's id and the URL of its page. Required: `cwd` (an absolute directory inside the repository; a path inside a linked worktree resolves to the repository the worktree belongs to), `prompt` (the whole task, at most 16 384 bytes of UTF-8 — the agent shares none of the calling conversation) and `work_item` (a `wi:` or `le:` target key from the next-work feed, a work item id, `requester`, or `none`; there is no default). Optional: `vendor` (the harness to start; defaults to the harness running the session), `model`, `daemon` (only when several of your daemons run on this machine) and `session_id` (defaults to the calling session). The agent is an ordinary hosted agent that you supervise from the dashboard — unlike a harness's own subagent, it is not part of the calling session. The server tries once to attach its session to the named work item after that session starts, so nothing is attached when the call returns. A refusal comes back with the server's own reason: no daemon on this machine, the daemon at capacity, the limit of live agents, a start on the same key already in progress. When the server could not confirm that the launch command was sent, or does not answer within 60 seconds, the tool says the agent may or may not have started instead of reporting a failure. A server without the route, or with `Features:AgentStart` off, answers a bare 405 or an uncoded 404, and the tool says that the server cannot start agents.
 
+**Offered flows.** When `kcap-flows` is registered for a harness, the SessionStart hook adds a short "Flows you may offer" block listing the catalogue flows marked `offer: proactive`, each with when to use it. The agent offers one at that moment and starts it only after you accept. The built-in `spec-review` and `code-review` flows ship as proactive; an admin controls any flow's offer through the `guidance` block of its definition. Against a server that predates flow guidance nothing is listed, and the built-ins are offered only by a server that ships their guidance.
+
 Every flow response reports which **workspace** the reviewer actually used, so you can tell whether it saw your uncommitted work:
 
 ```
@@ -1520,11 +1523,10 @@ Installing any vendor that reads the shared tree — `--codex`, `--cursor`, `--c
 | `kcap-disable` | `kcap disable` | Stop recording + delete server data |
 | `kcap-validate-plan` | `kcap validate-plan` | Verify plan items were completed |
 | `kcap-review-flows` | `kcap mcp flows` | Structured iterative spec/code review loops |
-| `kcap-agent-flows` | `kcap mcp flows` | Multi-participant agent flows by `definition_id` or inline `definition_yaml` |
+| `kcap-agent-flows` | `kcap mcp flows` | Drive any catalogue flow — named by you or offered from session context — following its driver guide |
 | `kcap-work-items` | `kcap mcp workitems` | Declare a work item's breakdown and its blocks / blocked-by dependencies |
 | `kcap-plans` | `kcap mcp plans` | Declare the plan document and task list a session executes |
 | `kcap-guided-tour` | analytics + sessions MCP | Onboarding tour of what Capacitor has recorded |
-| `kcap-suggest-review-flow` | `kcap mcp flows` | Proactively offer an independent second-harness review flow at spec/implementation completion |
 | `kcap-start-agents` | `kcap mcp flows` | Hand tasks to separate hosted agents that run on their own: check this machine's daemon, ask which harness, one `start_agent` call each |
 
 The first five (`kcap-recap`, `kcap-errors`, `kcap-hide`, `kcap-disable`, `kcap-validate-plan`) auto-resolve the active session from `CODEX_THREAD_ID`; pass `<sessionId>` explicitly to operate on a different session. `kcap-review-flows` and `kcap-agent-flows` work differently — they operate via flow IDs through `kcap mcp flows`; only the two status tools fall back to the session (from `CODEX_THREAD_ID`, or an explicit `session_id`) when no flow ID is passed; see [Flows MCP server (for agents)](#flows-mcp-server-for-agents) for details. `kcap-start-agents` also goes through `kcap mcp flows`; its tools take the calling session from the harness, or from an explicit `session_id`. `kcap-work-items` declares structure through `kcap mcp workitems` and needs no session id for its breakdown and relation tools. `kcap-plans` writes through `kcap mcp plans` and defaults the session the same way `kcap-work-items` does. `kcap-guided-tour` shells out to `kcap whoami` and otherwise reads through the `kcap-analytics` and `kcap-sessions` MCP servers, so it needs those registered (setup does it) rather than a session id.