@tacuchi/agent-workflow-cli 20.24.0 → 20.26.0

package/skills/w/harness/HARNESS.md

@@ -34,7 +34,7 @@ The capabilities the harness layer depends on, with their universal fallback (wh
 |---|---|---|
 | **command-invocation** | the user triggers a flow by name (`spec-new`, `plan-exec`, …) | the user writes "run the `<cmd>` procedure" and the AI reads its doc |
 | **procedure-loading** | load a loop's/command's doctrine | the AI **reads the `.md`** of the loop and follows it (read-and-follow) |
-| **structured-choice** | ask the human ≤3 content questions **+ always** a `flow` control (`Compactar`/`Cerrar`) through a side channel | a **numbered markdown** question in chat; the `flow` control is offered as one more option |
+| **structured-choice** | ask the human ≤3 content questions **+ always** a `flow` control (`Compactar`/`Cerrar`); every option has a semantic label + one-sentence functional explanation/example | **labeled markdown** in chat; answer by label or ratify all first options with `Aceptar recomendaciones` |
 | **compaction** | shrink the context without losing the thread (+ a context-pressure **signal** for the chassis' self-regulation) | write `CHECKPOINT` and ask the user to restart the context and resume (resume keys off `CHECKPOINT`) |
 | **subagent-dispatch** | *(optional)* parallelize research breadth | **inline sequential** research in the same session (the default anyway) |
 | **persistent-context** | the `WORKSPACE` block + conventions always present | the repo's context file (standard **`AGENTS.md`**; `CLAUDE.md` on Claude Code) |
@@ -47,25 +47,31 @@ The capabilities the harness layer depends on, with their universal fallback (wh
 
 ## Harness binding matrix
 
-Concrete mechanism per harness (**Jul-2026**, verified against official docs; `~` partial). Antigravity CLI reuses Gemini's surfaces (`~/.gemini/`); Oz reuses Warp's (they share the **Warp / Oz** column, with MCP via flag — see the note under the matrix).
+Concrete mechanism per harness (matrix base verified **Jul-2026**; the `structured-choice` row was refreshed **Aug-2026** against current official docs/source and local host probes; `~` partial). Antigravity CLI reuses Gemini's surfaces (`~/.gemini/`); Oz reuses Warp's (they share the **Warp / Oz** column, with MCP via flag — see the note under the matrix).
 
-| Capability | Claude Code | Codex | Gemini / Antigravity | OpenCode | Crush | Warp / Oz | Generic |
-|---|---|---|---|---|---|---|---|
-| command-invocation | `.claude/commands/` (slash) | skills only (`$` mention; no commands dir, prompts removed) | skills only in agy (system slash commands; `.gemini/commands/*.toml` = legacy Gemini CLI) | `.opencode/command/` | `.crush/commands` (palette) + user-invocable skills | skills as `/name` | text |
-| procedure-loading (skills) | `SKILL.md` `.claude/skills` | `SKILL.md` `.agents/skills` | `SKILL.md` (agentskills) | `SKILL.md` `.opencode`+`.claude`+`.agents` | `SKILL.md` `~/.config/crush`+`.agents`+`.claude` (`.crush/skills` is project-only) | `SKILL.md` `.agents`+`.warp`+`.claude` | read-and-follow `.md` |
-| structured-choice | `AskUserQuestion` (**main-agent only**) | — | — | — | — | — | numbered markdown |
-| compaction | `/compact` | Pre/PostCompact hooks | ~ | `session.compacted` | ~ | ~ | CHECKPOINT + resume |
-| subagent-dispatch | `Task` (parallel) | `SubagentStart` / agents | agents (`.gemini/agents`) | `.opencode/agent/*.md` | ~ | ~ (cloud agents) | inline |
-| persistent-context | `CLAUDE.md` (does **not** read AGENTS.md → symlink) | `AGENTS.md` | `GEMINI.md` + `AGENTS.md` | `AGENTS.md` | `CRUSH.md` + `AGENTS.md` | `AGENTS.md` (auto) | `AGENTS.md` |
-| **host-memory** | `MEMORY.md` (cheap) + transcripts/`--resume` (deep) | `AGENTS.md` (static → fallback) | `GEMINI.md`+`AGENTS.md` (static → fallback) | `AGENTS.md` (static → fallback) | `CRUSH.md`+`AGENTS.md` (static → fallback) | rules / history (~) | git/`docs/` + ask |
-| **web-research** | `WebSearch` / `WebFetch` | `web_search` (opt-in config) | `google_web_search` + `web_fetch` | `webfetch` (~) | ~ | ~ (agent web access) | — (offline + declare) |
-| external-data (MCP) | `.mcp.json` | `.codex/config.toml` `[mcp_servers]` | `settings.json` `mcpServers` | `opencode.json` `mcp` | `crush.json` `mcp` | `.warp/.mcp.json` (+auto-discovers `.mcp.json`) · Oz: `--mcp` flag | — |
-| **enforcement (deny tool)** | `PreToolUse` → `permissionDecision:deny` / exit 2 | `PreToolUse` (**≈same protocol**) | `BeforeTool` → `decision:deny` / exit 2 | plugin `tool.execute.before` (`throw`) | `allowed_tools` (+ preliminary hooks) | allow/deny lists (**coarse**) | doctrine (git-safe #5) |
-| plugin / dist | `.claude-plugin` + marketplace | `.codex-plugin` + `/plugins` marketplace | Extension `gemini-extension.json` | JS/TS plugin (npm) | MCP + skills + config | Warp Drive | — |
+| Capability | Claude Code | Codex | Kimi Code | Gemini / Antigravity | OpenCode | Crush | Warp / Oz | Generic |
+|---|---|---|---|---|---|---|---|---|
+| command-invocation | `.claude/commands/` (slash) | skills only (`$` mention; no commands dir, prompts removed) | skills only, as `/skill:<name>` (no commands dir) | skills only in agy (system slash commands; `.gemini/commands/*.toml` = legacy Gemini CLI) | `.opencode/command/` | `.crush/commands` (palette) + user-invocable skills | skills as `/name` | text |
+| procedure-loading (skills) | `SKILL.md` `.claude/skills` | `SKILL.md` `.agents/skills` | `SKILL.md` `.kimi-code/skills`+`.agents/skills` (user and project tiers) | `SKILL.md` (agentskills) | `SKILL.md` `.opencode`+`.claude`+`.agents` | `SKILL.md` `~/.config/crush`+`.agents`+`.claude` (`.crush/skills` is project-only) | `SKILL.md` `.agents`+`.warp`+`.claude` | read-and-follow `.md` |
+| structured-choice | `AskUserQuestion` (**main-agent only**; 1–4 questions, 2–4 options; label + description) | `request_user_input` when exposed (~; 1–3 questions, 2–3 options; label + description) | `AskUserQuestion` (1–4 questions, 2–4 options; label + description; failure → text) | `ask_user` (Gemini: 1–4 questions, 2–4 choice options; label + description) · `AskQuestion` (Antigravity: option text + write-in; public limits undocumented) | `question` (label + description; custom answer; public limits undocumented) | `question` (≤5 questions, ≤5 choices; descriptions + fill-in) | no documented structured-choice surface → labeled markdown | labeled markdown (label + sentence) |
+| compaction | `/compact` | Pre/PostCompact hooks | `/compact` + Pre/PostCompact hooks | ~ | `session.compacted` | ~ | ~ | CHECKPOINT + resume |
+| subagent-dispatch | `Task` (parallel) | `SubagentStart` / agents | sub-agents (`SubagentStart`/`SubagentStop`) | agents (`.gemini/agents`) | `.opencode/agent/*.md` | ~ | ~ (cloud agents) | inline |
+| persistent-context | `CLAUDE.md` (does **not** read AGENTS.md → symlink) | `AGENTS.md` | `AGENTS.md` (hierarchical) | `GEMINI.md` + `AGENTS.md` | `AGENTS.md` | `CRUSH.md` + `AGENTS.md` | `AGENTS.md` (auto) | `AGENTS.md` |
+| **host-memory** | `MEMORY.md` (cheap) + transcripts/`--resume` (deep) | `AGENTS.md` (static → fallback) | sessions with resume/fork (`kimi -S`) + `AGENTS.md` | `GEMINI.md`+`AGENTS.md` (static → fallback) | `AGENTS.md` (static → fallback) | `CRUSH.md`+`AGENTS.md` (static → fallback) | rules / history (~) | git/`docs/` + ask |
+| **web-research** | `WebSearch` / `WebFetch` | `web_search` (opt-in config) | moonshot search + fetch services | `google_web_search` + `web_fetch` | `webfetch` (~) | ~ | ~ (agent web access) | — (offline + declare) |
+| external-data (MCP) | `.mcp.json` | `.codex/config.toml` `[mcp_servers]` | `~/.kimi-code/mcp.json` `mcpServers` (also reads project `.mcp.json`) | `settings.json` `mcpServers` | `opencode.json` `mcp` | `crush.json` `mcp` | `.warp/.mcp.json` (+auto-discovers `.mcp.json`) · Oz: `--mcp` flag | — |
+| **enforcement (deny tool)** | `PreToolUse` → `permissionDecision:deny` / exit 2 | `PreToolUse` (**≈same protocol**) | `PreToolUse` → block / exit 2 | `BeforeTool` → `decision:deny` / exit 2 | plugin `tool.execute.before` (`throw`) | `allowed_tools` (+ preliminary hooks) | allow/deny lists (**coarse**) | doctrine (git-safe #5) |
+| plugin / dist | `.claude-plugin` + marketplace | `.codex-plugin` + `/plugins` marketplace | plugins + marketplace (no manifest we ship) | Extension `gemini-extension.json` | JS/TS plugin (npm) | MCP + skills + config | Warp Drive | — |
 
-> **Notes (field research Jul-2026):** **`SKILL.md` skills** are the **universal** portable unit — **all six** harnesses support them (Codex added them Dec-2025; **`.agents/skills` is the cross-host anchor**, read by Codex/OpenCode/Crush/Warp). **Structured choice** (`AskUserQuestion`) remains **Claude Code / main-agent only** → elsewhere `structured-choice` degrades to numbered markdown. The **enforcement layer** (new row) is **NO longer Claude-exclusive**: Codex + Gemini use a near-identical protocol (`permissionDecision:deny` / exit 2) and OpenCode blocks via `throw` in a JS plugin; Crush/Warp only offer **coarse** allow/deny (no custom per-command logic) → there, conventions stay **advisory** + allow/deny lists. Enforced **plan mode** is never trusted for safety; git-safe (invariant #5) is our own — though a host-planner's *output* (the plan it built) is adoptable input (`../commands/plan-new.md` § *Input resolution*, mode 4). **MCP** is universal (each host its file/key). The **guaranteed floor** (last column) runs the full model.
+> **Kimi Code caveats** (verified 2026-07-29 vs the shipped v0.29.2 binary + live probes): it exports **no env markers** to its subprocesses, so `aw harness` legitimately answers `unknown` inside it and detection goes through binary + config dir. Its hooks live **only** in the user-global `config.toml` — there is no project-level config — and their schema is `event`/`matcher`/`command`/`timeout`, so the bundled JSON template is *transformed*, not copied: `type: "prompt"` hooks cannot be expressed and are reported as skipped, and matchers are carried only for the tool-name events.
 
-> **Oz (Warp's cloud sibling).** `oz agent run` is a cloud agent orchestrator that **reuses Warp's surfaces**: same skills (`.agents/skills`, top-level dirs like Warp) and `AGENTS.md`, with `structured-choice` equally degraded to numbered markdown. It differs in three points: **detection** via `OZ_RUN_ID` (takes priority over Warp when both markers coexist); **MCP without a config file** — the JSON is passed via the `--mcp` flag of `oz agent run` (or the `OZ_MCP_CONFIG` env), it never writes `.warp/.mcp.json`; and **no plugin or hooks** (advisory enforcement, like Warp). Hence it shares the **Warp / Oz** column with that MCP caveat.
+> **Notes (field research Aug-2026):** **`SKILL.md` skills** are the **universal** portable unit — **every harness in the matrix** supports them (Codex added them Dec-2025; **`.agents/skills` is the cross-host anchor**, read by Codex/OpenCode/Crush/Warp/Oz/**Kimi Code** — every host except Claude Code, which reads only `.claude/skills`). The **enforcement layer** is **not Claude-exclusive**: Codex + Gemini use a near-identical protocol (`permissionDecision:deny` / exit 2) and OpenCode blocks via `throw` in a JS plugin; Crush/Warp only offer **coarse** allow/deny (no custom per-command logic) → there, conventions stay **advisory** + allow/deny lists. Enforced **plan mode** is never trusted for safety; git-safe (invariant #5) is our own — though a host-planner's *output* (the plan it built) is adoptable input (`../commands/plan-new.md` § *Input resolution*, mode 4). **MCP** is universal (each host its file/key). The **guaranteed floor** (last column) runs the full model.
+
+> **structured-choice routing.** A native binding qualifies only when the current client exposes it and can display the option's functional sentence without loss. When it has separate fields, map the semantic label and sentence to them; when it exposes one visible option string, render `Label — functional sentence`. Otherwise use labeled markdown. Respect the per-call ceilings in the row and reserve one question slot for `flow`; carry overflow into a later call. If the native tool already injects a custom/free-text option, do not add a duplicate `Other` option.
+
+> **structured-choice evidence (checked 2026-08-02):** [Claude Code](https://code.claude.com/docs/en/agent-sdk/user-input) · [Codex App Server](https://learn.chatgpt.com/docs/app-server.md) · [Kimi Code](https://moonshotai.github.io/kimi-code/en/reference/tools.html) · [Gemini CLI](https://geminicli.com/docs/tools/ask-user/) · [Antigravity changelog](https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md) · [OpenCode](https://dev.opencode.ai/docs/tools/) · [Crush source](https://github.com/charmbracelet/crush) · [Warp agents](https://docs.warp.dev/agent-platform/getting-started/agents-in-warp) / [Oz CLI](https://docs.warp.dev/reference/cli). Public docs do not expose Antigravity's full question schema or a dedicated Warp/Oz structured-choice schema; the row says so instead of inferring one.
+
+> **Oz (Warp's cloud sibling).** `oz agent run` is a cloud agent orchestrator that **reuses Warp's surfaces**: same skills (`.agents/skills`, top-level dirs like Warp) and `AGENTS.md`. No dedicated structured-choice schema is documented for Oz itself, so a direct Oz run uses labeled markdown; if Oz delegates to another harness and exposes that harness's native question surface, follow that harness's own binding. Oz differs from Warp in three points: **detection** via `OZ_RUN_ID` (takes priority over Warp when both markers coexist); **MCP without a config file** — the JSON is passed via the `--mcp` flag of `oz agent run` (or the `OZ_MCP_CONFIG` env), it never writes `.warp/.mcp.json`; and **no plugin or hooks** (advisory enforcement, like Warp). Hence it shares the **Warp / Oz** column with those caveats.
 
 > **compaction (signal & self-regulation).** The chassis' *Self-regulation (proactive compaction)* doctrine (`../modules/COMPACTION.md`, loaded under the `compaction` signal) needs two per-host facts: the **context-pressure signal** (does the host surface one the agent can read?) and **`auto`-mode viability** (can compaction fire **without user interaction**?). Claude Code: the signal is the harness' own context warnings; `/compact` is user-invoked — the agent cannot run it itself, so `auto` **degrades to `confirm`** there (the native auto-compact is already cushioned by the PreCompact/PostCompact hooks: checkpoint-write + resume-summary). Hosts with compaction hooks/events (Codex Pre/PostCompact, OpenCode `session.compacted`) cushion resume the same way; hosts with neither signal nor mechanism run the universal fallback (CHECKPOINT + restart + resume) and `auto` likewise degrades. Mode semantics (`[compaction]` config, default, consent): the chassis' subsection — single source.
 
@@ -83,8 +89,8 @@ Concrete mechanism per harness (**Jul-2026**, verified against official docs; `~
 ## Convention for the rest of the corpus
 
 - Loops/commands reference the **capability** by name (e.g. "*structured-choice* (see `harness/HARNESS.md`)"), **never** the concrete tool.
-- The historical name `AskUserQuestion` survives **only** as the Claude-Code binding of `structured-choice` (this table), never as doctrine vocabulary.
-- The `flow` lifecycle control (`Compactar`/`Cerrar`) belongs to the `structured-choice` capability, not to a tool: on harnesses without structured choice it is offered as one more textual option.
+- Concrete tool names survive **only** as per-host bindings in this document, never as doctrine vocabulary.
+- The `flow` lifecycle control (`Compactar`/`Cerrar`) belongs to the `structured-choice` capability, not to a tool: a required native field adds neutral `Continuar`; the text fallback leaves flow optional.
 
 ## Distribution (install-time)
 
@@ -92,7 +98,7 @@ Proven pattern (Spec Kit, 30+ agents): **one canonical source** + generate/symli
 
 ## Command packaging (harness-specific)
 
-Each command's **contract** (Flow, Trigger, Input, Mode, …) is agnostic. The **file** the harness executes wraps that contract in its native format — the installer (`aw self install-skill`) emits the right wrapper per host:
+Each command's **contract** (Flow, Trigger, Input, Mode, …) is agnostic. The **file** the harness executes wraps that contract in its native format — the installer (`aw self install-skill`) emits the right wrapper per host, retargets bundle-relative links to that host's installed `skills/w` directory and materializes the authored `${CLAUDE_PLUGIN_ROOT}/skills/w` token to the same absolute bundle for `aw context-plan --root`. Claude's plugin surface expands that token natively; installed wrappers never rely on the CLI's potentially different packaged copy:
 
 | Host | Wrapper installed | Invoked as |
 |---|---|---|
@@ -102,9 +108,14 @@ Each command's **contract** (Flow, Trigger, Input, Mode, …) is agnostic. The *
 | OpenCode | `~/.opencode/command/w/<cmd>.md` | `/w/<cmd>` |
 | Crush | `~/.crush/commands/w/<cmd>.md` (plain body — Crush parses no frontmatter) | palette `user:w:<cmd>` |
 | Warp/Oz | synthesized skill `w-<cmd>/SKILL.md` next to the bundle (Warp lists skills as `/name`) | `/w-<cmd>` |
+| Kimi Code | synthesized skill `~/.kimi-code/skills/w-<cmd>/SKILL.md` (reads no commands dir; verified vs v0.29.2) | `/skill:w-<cmd>` |
 
 *Skill-as-command* (a synthesized `w-<cmd>` skill whose body is the command, with bundle references rewritten to `../w/…`) is the **universal fallback** for any host without a native commands surface. The loop/role/export manuals are deliberately **not** `SKILL.md` files (`LOOP.md`/`ROLE.md`/`EXPORT.md`/`HARNESS.md`): hosts that scan skill roots **recursively** (Codex ≤6 levels; OpenCode and Crush — which also cross-read `~/.claude/skills` and `~/.agents/skills`) must never index the internals as invocable skills. The contract never changes; the wrapper does (another column).
 
 ## Status
 
-Capability model + binding matrix **defined** and **validated** with field research (**Jul-2026**, against official docs). Coverage: **6 real harnesses** (families; Warp/Oz counts as one, like Gemini/Antigravity): Claude Code, Codex, Gemini/Antigravity, OpenCode, Crush, Warp/Oz — all support `SKILL.md` (anchor `.agents/skills`) + MCP + `AGENTS.md`; deterministic enforcement on Claude/Codex/Gemini/OpenCode, advisory + coarse allow/deny on Crush/Warp/Oz. The CLI (`aw`) implements the registry (`domain/harnesses.ts`), the per-host MCP writers, `detect-hosts` and `install-skill --target <host>`. The universal floor (`AGENTS.md` + text + files + skills) runs the full model today.
+Capability model + binding matrix **defined** and **validated** with field research (base **Jul-2026**; `structured-choice` refreshed **Aug-2026** against the linked official docs/source and current local probes).
+
+The catalog counts **8 hosts** — `claude-code`, `codex`, `oz`, `warp`, `gemini`, `opencode`, `crush`, `kimi` — each with its own entry in `domain/harnesses.ts`. The columns above group two pairs that share a config surface (Warp/Oz, Gemini/Antigravity), which is a presentation choice, not a second taxonomy: the host set is whatever `HARNESSES` says. Anti-drift guards cover the CODE projections (TUI, install targets, doctor, detection); `chassis-consistency.test.ts` additionally parses the `structured-choice` row and asserts every host binding or explicit limitation. Support levels: **official** — Claude Code, Codex, Warp, Gemini/Antigravity, Kimi Code; **best-effort** — Oz, OpenCode, Crush. `agents` (`~/.agents/skills`) is a **shared destination**, never a host.
+
+All support `SKILL.md` (anchor `.agents/skills`) + MCP + `AGENTS.md`; deterministic enforcement on Claude/Codex/Kimi/Gemini/OpenCode, advisory + coarse allow/deny on Crush/Warp/Oz. The CLI (`aw`) implements the registry (`domain/harnesses.ts`), the per-host MCP writers, `detect-hosts` and `install-skill --target <host>`. The universal floor (`AGENTS.md` + text + files + skills) runs the full model today.

package/skills/w/loops/CHASSIS.md

@@ -105,14 +105,15 @@ Investigation is **inline**: an activity **inside the run's current session**, n
 
 ## Structured-choice (design & batching)
 
-**Canonical rule (single source — the rest of the corpus only references it):** *structured-choice* = **≤3 content questions + 1 `flow` control**, always. Per-harness binding in [`../harness/HARNESS.md`](../harness/HARNESS.md) (Claude Code: `AskUserQuestion`, max 4 questions/call; without structured choice it degrades to **numbered markdown**).
+**Canonical rule:** *structured-choice* = **≤3 content questions + 1 `flow` control**, always. Each option is a **short semantic label + one functional sentence** (outcome/trade-off or simple example), never a positional code. Use the richest current binding in [`HARNESS.md`](../harness/HARNESS.md); otherwise use labeled markdown.
 
-- **`flow` control** (lifecycle, always present): `Compactar` | `Cerrar`. Answering only the content questions = keep iterating. Under context pressure the loop **raises the choice itself**, with `Compactar` recommended.
-- **Content questions** are: human doubts (non-factual gaps) · MCP choice (DB rule), before running queries · at **convergence**, the loop's own closing action — each heir defines it in its *Convergence / exit* (e.g. `Guardar especificación refinada` · `Cerrar tarea`) — | `Preguntar algo más`.
-- **Batching**: up to 3 human gaps per call; with more pending, prioritize the ones that unblock others and defer the rest.
-- **Recommended answer per question**: every content question **always** carries the AI's recommended answer — the first option, marked *recommended*. Never ask "cold": the human ratifies or corrects a proposal, never starts from zero. The recommendation comes from what was researched (ask-vs-research rule), never from an empty default.
+- **Flow:** `Compactar` | `Cerrar`; an unanswered control means continue (`Continuar` when the UI requires it). Under context pressure the loop **raises the choice itself**, recommending `Compactar`.
+- **Content/batching:** human gaps, pre-query MCP choice and the convergence action | `Preguntar algo más`; at most 3 per call. Honor a smaller native ceiling by reserving one question slot for `flow`; carry overflow, prioritizing blockers.
+- **Options/encoding:** prefer 2–3 alternatives. Map label/sentence to separate fields or `Label — functional sentence`. If it cannot fit, use labeled markdown; never truncate or merge candidates or duplicate a host-provided free-text option.
+- **Recommendation:** the first option is marked *recommended* and comes from research; the human ratifies or corrects it, never starts cold.
+- **Text fallback:** answer by label; `Aceptar recomendaciones` accepts all first options. Never require composite coordinates such as `1A, 2A, 3A`.
 
-> **Label language:** the literal option labels (`Compactar`, `Cerrar`, `Guardar plan`, …) are **canonical product strings** — present them **verbatim**. All other user-facing output follows [`../SKILL.md`](../SKILL.md) § *Language policy*.
+> Canonical labels (`Continuar`, `Compactar`, `Cerrar`, `Aceptar recomendaciones`, `Guardar plan`, …) stay verbatim; other user-facing text follows [`SKILL.md`](../SKILL.md) § *Language policy*.
 
 ## Compact / resume