@tacuchi/agent-workflow-cli 21.3.0 → 21.4.0

package/skills/w/harness/HARNESS.md

@@ -45,6 +45,29 @@ The capabilities the harness layer depends on, with their universal fallback (wh
 
 > **Only two capabilities are `must` for a loop's cycle**: `structured-choice` and `compaction`. Both degrade to a purely textual fallback → **any** harness with chat + a filesystem runs the full model. The rest (subagents, MCP, slash commands, native skills) is *enhancement*.
 
+## Resource authority — the CLI spends, the host supplies
+
+The host advertises primitives; the CLI owns whether their cost is justified.
+`aw harness` reports **`agent_host`** and **`terminal_host`** separately, so Codex
+inside Warp is not mistaken for Warp. A host-specific installed wrapper binds its
+own target explicitly; environment detection is the fallback, while a shared
+`.agents/skills` wrapper stays unbound because several hosts can read it.
+
+- A deterministic tranche dispatches **zero** model workers, subagents and
+  external processes. `aw flow advance` exhausts it locally until the first
+  semantic, human, authorization, execution, blocked or final frontier.
+- A semantic tranche is inline by default. It may use subagents only for three
+  or more independent partitions with no dependency and no overlapping writes;
+  then the CLI caps them at **3** (at most **4** model workers including the
+  coordinator). Human and authorization frontiers never fan out.
+- An execution frontier has one external invocation at a time and returns its
+  actual evidence; it is not a request to run more agents.
+- Token usage is recorded only when the host supplies a real count. Bytes,
+  context size and estimates are never relabeled as tokens.
+
+This lets a capable host contribute parallel analysis when it is cheaper than
+coordination, without turning a deterministic CLI rule into model work.
+
 ## Harness binding matrix
 
 Concrete mechanism per harness (matrix base verified **Jul-2026**; the `structured-choice` row re-verified **2026-08-04** and the Codex `hooks` row **2026-08-05**, both against the INSTALLED runtimes plus real runs — not 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).
@@ -55,7 +78,7 @@ Concrete mechanism per harness (matrix base verified **Jul-2026**; the `structur
 | 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; free-text always offered) | `request_user_input` **not reachable** (~): its router refuses it in Default mode and exec mode never offers it; opt-in `default_mode_request_user_input` still *under development* → labeled markdown | `AskUserQuestion` (1–4 questions, 2–4 options; label + description; free-text offered) — **not called in `auto`/non-interactive mode** by the host's own rule → labeled markdown | `AskQuestion` (Antigravity/`agy`, the live binary: option `text` only, **no description field** → `Label — sentence`; write-in; no ceiling declared). `ask_user` is the retired Gemini CLI's and is **absent** from `agy` | `question` (label + description as separate fields; `custom` free-text on by default; no ceiling declared) — **denied in a non-interactive run** → labeled markdown | `question` (≤5 questions, ≤5 choices; description required per question <300 chars and **per choice <100 chars**; automatic fill-in) | no 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 |
+| subagent-dispatch | `Task` (parallel) | `agents` | `SubagentStart` | agents (`.gemini/agents`) | `.opencode/agent/*.md` | inline | inline (Oz cloud orchestration is not a direct worker binding) | 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) |
@@ -124,7 +147,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, 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:
+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, binds its flow/capability calls with `--host <target>`, 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 |
 |---|---|---|

package/skills/w/loops/CHASSIS.md

@@ -2,7 +2,7 @@
 
 This document is the **common engine** of the Workline loops: the doctrine every loop runs underneath its deltas. **It is not a skill** — it is a referenced document: every loop orders it read from its `## Inherits`, **always, before its deltas**. If you edit the engine, edit it **here** — heirs never repeat it, they only reference it.
 
-> **When each step below happens is no longer this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. What stays is what each rule is FOR — the half no engine carries.
+> **When each step below happens is no longer this document's call:** the deterministic steps below are decided by the CLI (`aw flow advance`), not by this document. They consume no model worker, subagent or external process: the CLI advances them locally to the first real frontier. What stays is what each rule is FOR — the half no engine carries.
 
 ## Heirs (canonical list)
 
@@ -45,7 +45,7 @@ The persistent objective needs a **checkable done-condition** — otherwise the
 
 **Gate integrity (anti-gaming + independent verification).** The gate only counts if it is not gamed to pass. The loop does **not**: modify the check or loosen a `Success criterion` to force green; weaken, delete or skip tests/validations; use trivial or tautological asserts that always pass (the expected value comes from an independent source, never from the output itself); patch the test instead of fixing the cause (prefer fixing production code).
 
-Facing a real blocker it **stops and reports it** (→ `Open questions`/`BACKLOG`) instead of gaming the metric. The verdict counts **only the check's output, never the implementer's self-declaration**: when the deliverable warrants it, the final verification is an **independent** pass (subagent or clean re-read) that does not assume the implementation is correct — *only command output counts*.
+Facing a real blocker it **stops and reports it** (→ `Open questions`/`BACKLOG`) instead of gaming the metric. The verdict counts **only the check's output, never the implementer's self-declaration**: when the deliverable warrants it, the final verification is an **independent** pass (subagent only when the CLI's independent-partition rule admits it, or a clean re-read) that does not assume the implementation is correct — *only command output counts*.
 
 **Minimality (anti-over-engineering).** Passing the criteria is **necessary, not sufficient**: the gate also rejects a deliverable **heavier than its `Success criteria` require** — YAGNI at the deliverable's altitude. A spec can be coherent yet over-specified; a plan sound yet over-engineered; a diff green yet padded with reinvented stdlib, speculative abstractions or dead flexibility. At its own altitude the gate asks the laziest-that-works questions:
 

package/skills/w/loops/plan-new-loop/LOOP.md

@@ -6,7 +6,8 @@ description: >-
   TECHNICAL-NOTE level + Tasks phased by verifiable functional state
   (### Fn blocks with live state),
   code/impact-mapping research, planning gap taxonomy, and promotion of the
-  design closure to handoff via `design`
+  design closure to handoff via `design`: reuse a valid one, promote the rest,
+  then pin the roots
   when the plan includes UI. If the spec is not refined it suggests
   spec-refine first. Started by /w:plan-new; resumable. Invoke when a spec
   must become an executable plan.
@@ -137,7 +138,7 @@ Replaces the spec gap taxonomy with a planning-oriented one:
 | Missing deps | order unclear | research / human |
 | Spec criteria uncovered | tasks don't trace to acceptance criteria | the AI derives + human confirms |
 | Unaddressed risks | technical risks unmitigated/undeclared | human / **probe** (Delta 5) |
-| UI without design *(if it applies)* | the plan includes UI (FE/screens in `Impacted`, `## Design references` in the spec, or UI tasks) and pins no exact root, or its roots are not `handoff` | **`design`** (promote the closure, pin the roots) |
+| UI without design *(if it applies)* | the plan includes UI (FE/screens in `Impacted`, `## Design references` in the spec, or UI tasks) and pins no exact root, or its roots are not `handoff` | **`design`** (promote the closure, pin the roots — reusing an already valid compact handoff instead of re-promoting it) |
 
 > **Author the Solution the laziest-that-works way** (chassis § *Minimality*, generative side): reuse what the codebase/stdlib/platform already provides before proposing new abstractions, layers or dependencies — the coherence gate then only *confirms* minimality, never repairs over-engineering after the fact.
 
@@ -161,7 +162,7 @@ plan-new-loop(spec):
     gaps = detect_gaps(work)  (Delta 2 taxonomy)  minus the exhausted ones
     if gaps == ∅: break
     batch ≤3 → seed CHECKPOINT.Pending/Next → resolve each gap:
-      research · human (structured-choice) · probe · design (promote closure + pin roots)
+      research · human (structured-choice) · probe · design (reuse valid handoff or promote missing closure + pin roots)
     integrate + update CHECKPOINT
   coherence gate (read-only) = Success criteria green:
     - every spec criterion traces to a phase/task (split: exactly one sibling)

package/skills/w/loops/spec-refine-loop/LOOP.md

@@ -66,9 +66,9 @@ Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's
 
 ## Composes
 
-The **UI unspecified** gap (when the requirement involves UI; see *Gap taxonomy*) is resolved by the composed **`design`** capability ([`../../roles/design/ROLE.md`](../../roles/design/ROLE.md)) over the **UI Design Package v1**: reuse a compatible baseline or open an `outline` revision, publish it through the CLI, and leave in the spec **only** its `## Design references` — package, baseline hint and digest. The loop contributes iteration/Q&A (design system, theme, variants, disambiguation) **via the same structured-choice**; the capability contributes what a correct package looks like. Full rule: [`DESIGN-REFERENCES.md`](../../modules/DESIGN-REFERENCES.md).
+The **UI unspecified** gap (when the requirement involves UI; see *Gap taxonomy*) is resolved by the composed **`design`** capability ([`../../roles/design/ROLE.md`](../../roles/design/ROLE.md)) over the **UI Design Package v1**: reuse a compatible baseline or open an `outline` revision when expanded; a compact delta publishes its `handoff` in one pass. Publish it through the CLI, and leave in the spec **only** its `## Design references` — package, baseline hint and digest. The loop contributes iteration/Q&A (design system, theme, variants, disambiguation) **via the same structured-choice**; the capability contributes what a correct package looks like. Full rule: [`DESIGN-REFERENCES.md`](../../modules/DESIGN-REFERENCES.md).
 
-> **Two levels of the same capability:** here (SPEC) the design closes at `outline` and the spec keeps its exact reference; in PLAN the plan loops promote to `handoff` exactly the closure they implement and pin the exact roots (see [`DESIGN-REFERENCES.md`](../../modules/DESIGN-REFERENCES.md)). One package, two questions — never two formats.
+> **Two levels of the same capability:** a compact SPEC may already close its exact roots at `handoff`; otherwise SPEC keeps an `outline` reference and PLAN promotes exactly the closure it implements. A valid handoff is reused, never re-authored. One package, two questions — never two formats.
 
 Other transversal capabilities the engine always uses: `research` (**inline** — chassis § *Research*), `sql` (DB rule inside research — chassis). All resolved by config; `off` → the loop continues without the capability and, if it was needed, says so or asks. The spec's **prose** follows the **ambient** writing conventions (the host auto-applies an installed writing skill if present), not a composed role.
 

package/skills/w/modules/DESIGN-REFERENCES.md

@@ -34,21 +34,24 @@ cannot be superseded without editing it.
 Publishing the package is the loop writing a composed deliverable through the
 CLI, not graduating a session artifact (chassis § *docs/ boundary*).
 
-## `handoff` asks to SEE it
+## Evidence and lifecycle
 
-A `handoff` screen owes evidence, not only prose: a local static preview of its
-`default_state`, and a `trace` classifying every criterion `visual`,
-`interaction` or `not_visual`. A package published under the earlier gate can stop
-qualifying; it reports `DESIGN_VISUAL_EVIDENCE_REQUIRED` with the screen, the
-criterion and the fix.
+`trace` marks each criterion `visual`, `interaction` or `not_visual`. Preview
+only visual acceptance; interaction relies on states, semantics and implementation
+proof, never a storyboard merely to satisfy format.
+
+The CLI marks a delta **compact** only with an existing surface, ≤2 screens, and
+no journey, rule, token, asset, external dependency, blocker or adaptation.
+Compact publishes one `handoff` for PLAN to reuse. Otherwise it is **expanded**:
+SPEC keeps `outline`; PLAN promotes only its consumed closure. The model authors
+content, not this routing.
 
 ## SPEC — close the requirement at `outline`
 
 1. **Reuse before minting.** `aw designs` lists what the workspace already has; a
    compatible baseline is reused rather than given a second identity.
-2. **Otherwise open an `outline` revision.** Not a shortcut: the spec closes *what*
-   the interface must accomplish and legitimately still holds unknowns. `handoff`
-   is PLAN's call — PLAN knows what will actually be implemented.
+2. **Classify the lifecycle.** Compact publishes `handoff` now; otherwise open
+   `outline`, which may hold unknowns until PLAN promotes its implemented roots.
 3. **Publish, then reference.** Citing a baseline that was never published is the
    dangling reference this contract removes.
 
@@ -66,9 +69,8 @@ before `## Decisions`.
    reach the rules, tokens and assets they depend on. It stops there. `flow_refs`
    is *not* followed — it is the inverse relation, and following it drags in
    designs the plan never consumes.
-4. **Promote exactly that closure to `handoff`**, nothing else. Ten screens in
-   `outline` and three promoted is a package's normal shape; promoting it wholesale
-   because one task needed one screen makes maturity meaningless.
+4. **Reuse a valid `handoff`, or promote exactly the missing closure.** A compact
+   handoff from SPEC is already the plan's baseline, not work to repeat.
 5. **Publish the revision**, then write the roots.
 
 The plan declares its own `## Design references` — same block — after

package/skills/w/roles/design/ROLE.md

@@ -41,11 +41,12 @@ The package is the deliverable. A spec **references** it; it never contains it.
 ## Composed by
 
 - **`spec-refine-loop`** — the requirement involves UI: reuse a compatible
-  baseline or open an `outline` revision, and leave only `## Design references`
-  in the spec document.
-- **`plan-new-loop` · `plan-refine-loop`** — the plan consumes UI: promote to
-  `handoff` exactly the closure the plan consumes, and write the exact roots
-  into each phase or task.
+  baseline or, for a compact delta, publish the exact `handoff` in one pass;
+  expanded work opens an `outline` revision. The spec leaves only `## Design
+  references`.
+- **`plan-new-loop` · `plan-refine-loop`** — the plan consumes UI: reuse that
+  valid handoff, or promote exactly the missing closure, and write the exact
+  roots into each phase or task.
 - **`plan-exec-loop`** — reads and validates; **never redesigns**. A design that
   turns out wrong stops execution and goes back to the refining loop.
 
@@ -111,6 +112,9 @@ what is not yet decided. A document may declare `handoff` only when:
   revision and digest;
 - no essential section answers with a **rendition and nothing else**: an
   approved image is not the current semantics and is not a WCAG conformance.
+- a screen with a **visual** criterion preserves a local static preview of its
+  default state; a purely interaction/non-visual screen does not fabricate a
+  storyboard just to satisfy this gate.
 
 ### Governance: four independent dimensions