# CLI The installed command is `aw`. Dynamic skill and step guidance returns compact `command_specs[]` rendered in-process from the compiled Clap tree; task workflows should trust those entries and use at most one exact-leaf `--help` fallback when a needed spec is absent or rejected, never broad or parent help. Manual users may still run an exact `aw --help` display command. In a source checkout, use `node bin/aw-debug.js` for current-source evidence. ## Project setup - `aw init "summary"` initializes or reconciles the project workspace. - `aw install --target agents` installs project skills in `.agents/skills/`. - `aw install --target claude-code` installs Claude Code skills. - `aw install --target codex` installs the Codex integration target. - `aw check [task-id]` validates workflow structure. With no task id it runs the complete project-wide structural report. With an explicit task id it uses fixed lifecycle probes and validates only that task's durable directory, registered artifacts, and local consistency rules. `aw repair`, dashboard health, and TUI health remain project-wide. ## Tasks and artifacts - `aw create --agent-runtime "intention"` creates a task record for lower-level automation. The caller obtains this exact runtime from its own Agent environment; creation rejects missing, malformed, guessed, or placeholder values. - `aw status [task-id]` reports project or task state. - `aw next [task-id]` reports the next recorded action. - The explicit task-id forms use bounded probes of the fixed lifecycle paths and read only that task's direct artifacts. The no-id forms intentionally build a project-wide inventory for global status and routing. - `aw render --for ` renders task routing facts plus only the registered input artifacts for that step. It does not append unrelated Plan, Execute, action-log, verification, or task-status bodies. - `aw step enter ` is the replay-safe routine entry surface. It composes standalone step start, post-start render, and task-scoped guidance into one typed result containing `start`, `render`, `guidance`, and one non-duplicated `command_specs[]` array. Re-entering the same running step performs no start write. A later render or guidance failure retains the successful start and reports `failed_component` plus partial-result evidence so the same command can be retried safely. - `aw contract list|show|validate` exposes the current compiled artifact registry read-only. `list` returns every stable template id plus an aggregate SHA-256 fingerprint, `show ` returns its ownership, write command, shape, example, and fingerprint, and `validate --input ` or `--input-file ` validates caller content without persistence. JSONL failures retain physical line-aware paths. - `aw read` returns a complete registered task artifact. `aw write --input ''` or `--input-file ` is the full-document creation and strict repair boundary and is not the normal workflow path. For task JSON, AW validates the latest strict template, uses the registered task-session Agent runtime, overwrites `workflow_runtime` with the executing AW version, and persists atomically. The repair writer can locate one uniquely placed task without first parsing an invalid `task-status.json`. - Successful mutators return compact authoritative receipts for their exact target. Use explicit read commands for full state or when a receipt omits a fact needed for the next decision; do not reread only to confirm fields already returned by the mutator. - Normal structured artifacts use semantic commands instead of whole JSON payloads: - `aw artifact analysis init|file-set|function-set|question-add` - `aw artifact plan init|step-set`; Plan init accepts repeatable `--accepted-limit ` values - `aw artifact execution init|summary-set|step-set|deviation-add` - `aw artifact action-log add` - `aw artifact verify init|check-add`; Verify init accepts repeatable `--open-risk ` values - `aw artifact consolidate init|candidate-add|doc-add` - `aw artifact commit set` - Registered Markdown uses `aw artifact section read|set|append|replace|clear`. Heading lookup is exact, required-heading constrained, duplicate-sensitive, and ignores headings inside fenced code blocks. `aw artifact text set|append|replace` provides exact whole-text or chunk operations; replacement rejects zero or multiple matches. - `aw summary append` accepts repeatable `--item ` values. `aw step done` accepts repeatable `--summary-item ` values for distinct close-out evidence. - Roadmap phase/item add and update commands accept typed scalar and repeatable flags. Blueprint feedback uses `propose-blueprint` or `propose-roadmap`; knowledge add accepts exactly one opaque source through `--input` or `--input-file `. - Narrow roadmap item and phase mutations return the changed entity rather than the complete composed roadmap. `aw roadmap read` remains the full-roadmap retrieval surface. - `aw step todo add|update|remove ...` mutates one running-step DAG node with typed fields. Rows have a unique bounded `id`, bounded `title`, required bounded `abstract`, explicit `depends_on[]`, and `todo|doing|done` status. Add or replace edges with repeatable `--depends-on ` and clear them with `--clear-depends-on`. Missing references, self-edges, duplicate edges, cycles, and active nodes with incomplete predecessors are rejected. Multiple dependency-ready rows may be `doing`. Receipts and `step.todos_set` events include normalized rows, `doing_ids`, `ready_ids`, completed, and total. `aw step todo replace ... --input ''` or `--input-file ` is reserved for complete-list repair. A tracked step requires a non-empty all-done graph before completion. - `aw artifact execution step-set` writes explicit `depends_on[]`. Plan-backed rows must leave it empty because they inherit Plan edges; execution-only rows may repeat `--depends-on ` over the merged Plan and execution-only graph. Running, completed, or skipped rows are rejected until every predecessor is completed or skipped. - `aw step done verify`, `aw step done commit`, and `aw task move archive` require Verify `status=passed`, `open_risks=[]`, and every `checks[].result=passed`. `partial`, `failed`, and `blocked` artifacts remain evidence for repair routing but cannot close Verify. - `aw task config --agent-runtime ` registers the current semantic-author runtime. Runtime-only refresh remains allowed after execution settings freeze and cannot change worktree, retry, or reverse-feedback fields. - `aw task move|cancel|reactivate|rollback` owns lifecycle mutations. - `aw task migrate-worktree --reason [--worktree-dir ] [--acknowledge-head-only]` converts one already-frozen worktree-disabled task into a worktree-enabled task and creates its isolated checkout in the same invocation. See [Task worktree migration](#task-worktree-migration). - `aw task retire-worktree --reason --confirm` safely removes an archived task's recorded worktrees and branches. See [Archived task worktree retirement](#archived-task-worktree-retirement). For normal agent-driven work, prefer `$aw-task` and `$aw-resume`; the skills add roadmap association, step protocols, gates, and closure behavior around these CLI primitives. ## Workflow cost baseline Representative repository measurements for this minimization pass: | Surface | Before | After | Change | |---|---:|---:|---:| | Narrow roadmap mutation JSON | 227,397 B | 1,118 B | -99.5% | | Task-scoped Execute guidance JSON | 22,913 B | 13,990 B | -38.9% | | Execute render | 29,992 B | 20,488 B | -31.7% | | Commit render after step scoping | n/a | 1,409 B | current size | | Strict-schema JSON, current-only sample | 5,515,104 B | 4,695,013 B | -14.9% | | Concise prose simulation, 240/160 targets | 5,515,104 B | 4,199,266 B | -23.9% | | Concise prose simulation, 160/120 targets | 5,515,104 B | 3,849,786 B | -30.2% | | Minimal tracked-step mutation path | 9 AW calls | 6 AW calls | -33.3% | The current-only sample keeps independently meaningful fields required, writes explicit empty arrays, requires `abstract` within 256 display columns, replaces per-action runtime duplication with one required file-root `schema_version`/Agent/AW provenance set, removes Plan `notes[]`, and uses compact JSON serialization for comparison. The prose rows are historical simulations, not hard limits: one shared prompt rule asks for the shortest complete fact uniquely owned by each field, while exact commands, paths, identifiers, and errors remain unchanged. The command-count row covers start, one todo seed/completion cycle, artifact mutation, close-out, and next routing; health, render, and guidance entry calls are unchanged. Successful mutation receipts remove immediate confirmation rereads. Step completion uses repeatable `--summary-item` only when a distinct overview is needed. Retained rereads are intentional for warnings, ambiguity, missing routing facts, recovery, cross-owner results, and detected external changes. ## Repository VCS capability Each configured source repository has one of two fixed `vcs` values: `git` or `none`. This is a concrete capability choice, not a plugin surface. Reads, writes, indexing, and source-writable AGT-X execution remain available for `vcs = "none"`, and those paths do not discover, require, or launch Git. Git-only operations select the repository's configured capability before any process call. Commit-skip gates ignore repositories without Git commit capability. Task worktree creation and frozen-binding migration require a configured Git repository. `aw agent review` and `aw agent adjust` are explicitly Git-only because their diff and restore semantics come from Git; non-Git Agent execution remains valid, but review or adjustment returns an `artifact_validation` error with `reason=repository_vcs_unsupported`, `repository_id`, `vcs`, and `operation` details. No Mercurial/SVN adapter or non-Git snapshot and restore engine is inferred. ## Task worktree migration The first Execute entry freezes a task's `worktree` mode. A frozen config is otherwise immutable, so `aw task migrate-worktree` exists as its own narrow operation rather than as a relaxation of the frozen guard: it moves one task from `worktree = disabled` to `worktree = enabled` and creates the isolated checkout in the same invocation. The migration resolves the configured workspace-root repository first and requires `vcs = "git"`; a root configured with `vcs = "none"`, or no configured root repository, returns the structured unsupported outcome without launching Git. Eligibility is exact, and each refusal carries its own reason code: - the task is in `todo`, has no running step, and its next step is Brainstorm, Analyze, or Plan — Execute and later keep the binding they already froze; - its config is frozen, still `worktree = disabled`, and records no prior migration. The new worktree is created at the main checkout's committed HEAD, so uncommitted work stays in the main checkout. When the main checkout is dirty the command refuses until you either commit that work or pass `--acknowledge-head-only` to accept a HEAD-only binding; the acknowledgement is recorded as evidence. The direction is one-way by construction: there is no reverse mode, no unfreeze, and no force. `aw task rollback` restarts step work and never changes a task's recorded worktree binding. `frozen_at` keeps its original value, because the freeze itself is not re-performed; `updated_at` becomes the migration timestamp. Replay is idempotent but never repairing. Re-running with the same leaf against an intact binding reports no change. A recorded binding whose worktree, branch, or canonical `.aw` link no longer holds is an error naming what broke, and `aw check` reports the same state as a fatal `task_migration_binding_broken` issue — recreate the binding by hand at the recorded `source_head`. Migrating an already-migrated task, or the same task onto a different leaf, is also refused, because silently rebinding would invalidate work already done in the old checkout. While a migration runs it publishes a per-task fence under `.aw/.runtime/task-worktree-migrations//`, and Agent dispatch for that task fails closed until the fence is released. A fence whose owner process died is reclaimed by the next attempt; `aw check` surfaces live and stale fences, and any worktree an interrupted migration created but never bound, as warnings. Either the operation produces a complete binding — config metadata, a registered worktree at the recorded commit, the canonical artifact-root link, and the `task.worktree_migrated` event — or it produces nothing: a failure after publication restores the original config bytes and removes only what that invocation created, and the returned error carries the compensation outcome. Run the migration with the CLI that matches the installed package version, and never hand-edit `task-config.json` to change a binding. This worktree command is unrelated to historical JSON contract repair: old task JSON is manually rewritten by an Agent from current templates through existing validated writers. There is no artifact migration command, compatibility parser, or Runtime-selected fallback. ## Archived task worktree retirement `aw task retire-worktree --reason --confirm` is the archive-only cleanup path for an immutable enabled worktree binding. The explicit confirmation is required because the command removes Git resources. Before publishing any cleanup evidence, it requires the task to be archived, its config to be frozen with `worktree = enabled`, all task Agent sessions to be quiescent, every recorded checkout to be registered on the recorded branch with a canonical artifact-root link, every checkout to be clean, and every recorded branch to be merged into that repository's current branch. Cleanup is two-phase and never uses Git force flags. First, the command records `worktree_retirement.status = "in_progress"` with the ordered binding snapshot, start time, and operator reason. It then runs ordinary `git worktree remove` for each still-registered checkout and `git branch -d` for each remaining branch. Only after every recorded directory, registration, and branch is absent does it record `status = "completed"`, `completed_at`, and the `task.worktree_retired` event. An interrupted cleanup is recoverable by re-running the same command with the same reason and `--confirm`. The durable binding snapshot controls the retry, already-removed resources are accepted, and remaining resources must still pass the safe preflight. Repeating a completed retirement returns `updated = false` only while every recorded resource remains absent; recreated or leftover resources fail closed for manual inspection instead of being deleted implicitly. Once retirement starts, `aw task rollback` refuses to reopen the task because its frozen checkout is terminally retired; create a new task if more work is required. Canceled and trashed tasks retain their worktrees by design, and orphan worktrees without an owning archived task are outside this typed task command. ## Project guidance - `aw guidance` is the read-only request surface for Core Action `guidance.compose`: Signal `guidance.requested` resolves exact Trigger `guidance.`, then the composer returns dynamic fields plus flat Action Outcome identity and status. JSON results also carry deterministic, deduplicated `command_specs[]` entries shaped as `path` plus compact Clap-rendered `usage`; no nested `aw --help` process or duplicated argument registry is involved. Task-scoped step guidance remains a compact delta: it reports core guidance as an available source without expanding it again, omits static product and host sections already loaded by the task router, and prefers exact step Agent Trigger bindings over the overlapping `complex.reasoning` wildcard. Human output remains only the generated Markdown. - `aw roadmap` composes `roadmap/phases.json` with authoritative flat `roadmap/items/.json` files. Use phase `update` with repeatable `--item-order` for explicit display-order changes and typed narrow item commands for item facts. Removal refuses a non-empty `task_refs[]` unless `--accept-unlinking` explicitly accepts losing those links. Item ids stay stable; correct an id through unlink, remove, add, and relink. There is no aggregate roadmap write command. - A successful changed `aw task move` emits Signal `task.lifecycle.changed` from Core Hook Point `task.lifecycle.after`. An archive target resolves Trigger `task.archive.roadmap-sync` to non-blocking Core Action `roadmap.progress-sync`; the lifecycle result remains authoritative while `action_outcomes[]` returns the Action's identity, status, typed warnings, `actions_required[]`, and evidence. Callers do not need a second `blueprint-update read` to discover follow-up work. - `aw blueprint-update propose-blueprint|propose-roadmap` records typed task feedback candidates. Blueprint proposals append an exact-id `blueprint-candidate-recorded` event. `aw blueprint-update apply ` changes only `proposed` to `applied` and appends one `blueprint-candidate-applied` event. `aw blueprint-update reject --reason [--replacement-candidate ]` changes only `proposed` to `rejected` and appends one `blueprint-candidate-rejected` event containing the required reason and optional distinct known replacement id. Both commands locate exact candidates in any task lifecycle and never edit Blueprint Markdown or candidate content. Repeating the same terminal decision returns `changed=false` without rewriting or duplicating evidence; an opposite terminal decision returns a typed lifecycle error. Unknown ids, invalid replacement ids, and empty reasons fail without writing. Historical proposed and applied candidates remain readable without migration, and decisions are never inferred from text matches. - `aw knowledge add ... --input ` or `--input-file ` adds retained knowledge; `load` reads it. - `aw docs` discovers project and task documentation surfaces. `aw docs --compose ` additionally returns one explicit bounded Blueprint projection in root-first Components order with source id, role, path, depth, parent, and raw content. Without the selector, canonical nested source files are listed independently and no composition field is emitted. - `aw guidance` also injects the absolute directory of the version-matched product docs shipped with the installed package; agents can read detailed CLI, skill, and artifact references there without guessing npm layout. ## Services and inspection - `aw server` supervises enabled core background services. - `aw agent-server status|start|stop|restart` and `aw index-server` expose individual project-bound lifecycle control. Agent Server runtime state lives under `.aw/.runtime/agent-server`, and Project Index runtime state lives under `.aw/.runtime/index-server`. Main checkouts, linked task worktrees, and concurrent sessions resolving to one canonical artifact root share the same project-local service state. Separate projects own independent pools; there is no host-global registry, queue, supervisor, or capacity pool. - `agent_server.project_concurrency` configures fixed slots for one project and defaults to eight. Current config is strict, versionless, and complete. `aw config repair` restores missing or incorrectly typed current-template fields while preserving recognized current settings; it does not interpret retired fields or formats. A current config structural failure is labeled `reason=cli_artifact_contract_skew` only when its complete issue batch contains both `missing_field` and `redundant_field`; the original `artifact_validation` kind remains, and details include the project-config contract fingerprint, resolved executable path, executable mtime, and config mtime with rebuild or reinstall guidance. - `aw agent-server status` reports `.aw/.runtime/agent-server`, lifecycle sequence, generation identity, draining state, queue state, fixed-slot heartbeats, and operational capacity. It is read-only and never refreshes authority or starts reconciliation. Only current-generation slots with a fresh owner heartbeat and matching launch, digest, nonce, and process-start identity count as live. - `aw agent-server restart` is the public recovery path after package upgrades, source rebuilds, executable deletion or replacement, worker-runtime config changes, stale heartbeats, or terminal reconciliation failure. It fences old claims and drains old in-flight sessions under their original timeout. Foreign-host ownership requires explicit `--confirm-host-takeover`. Do not invoke hidden worker commands or edit `.aw/.runtime` files. - Agent Server uses atomic create/replace, owner tokens, expiry, and generation fencing. Runtime locks live under `.aw/.runtime/locks`; durable Agent evidence lives under `.aw/agents`. - Installed projects execute the npm/system `aw` binary directly; source checkouts execute their own `target/debug/aw`. Agent Server records that original path and digest and creates no project-local binary copy. Provider profiles execute directly with the recorded normalized `PATH`; shell syntax must be explicit in the configured command, such as `["bash", "-lc", "..."]`. - `aw dashboard` is unmaintained: `start`, `restart`, and the internal `serve` entry all fail with a lifecycle error, and `aw server` never launches it. Current config has no `services.dashboard` setting. `aw dashboard status` and `aw dashboard stop` remain available for winding down a service record left by an earlier version. - `aw tui` launches the terminal inspector. Settings is its only writable tab; observation tabs, `--json`, and scripted fallback remain read-only. - `aw observe activity [task-id] [--goal-scope ]` is Weyaw's compact read-only activity contract for lightweight status consumers. Without a task id it returns only the nearest Weyaw project display name and never selects or lists repository tasks. An explicit project-bound task returns its roadmap title, lifecycle, effective step, and one normalized `current_step` detail containing `todo|doing|done` rows in AW-owned durable order plus `completed`, `total`, and optional derived `wave`. The wave contains one-based `current` and `total` logical Wave numbers plus the complete ordered `waves` array. Brainstorm, Analyze, Plan, Verify, and Review project their durable step todo DAGs; Execute projects the merged Plan and execution-only graph. Every logical Wave is the full stable-order dependency layer: node count, Action `fan_out`, group or project concurrency, worker availability, slots, and queue state do not split or narrow membership. The projection remains read-only and does not claim to reconstruct historical runtime launches. Consumers may derive presentation order without mutating this durable row order. A caller-supplied aw-goal stage or ordered item scope adds only one-based current/total position. Agent rows are task-scoped, bounded to 32, and returned in canonical display order: running, queued or pending, then terminal, with stable group, assignment, semantic id, and title tie-breakers inside each rank. Every row exposes bounded `id`, `title`, and objective-backed `abstract` plus AGT-R/AGT-X mode, optional submit-time `order_preset`, selected worker `profile`, provider `harness`, status, content-token usage/budget, turn and attempt counts, and optional group position. Current rows use durable group/session identity and derive task ownership by loading `group.json`; unavailable optional presentation fields remain null. Bounded terminal rows may be returned for presentation, but only queued/running agents drive activity polling. Prompts, unbounded objective records, outputs, events, paths, model identifiers, raw provider payloads, worker commands, mutable current configuration, health, service state, and mutation controls are omitted. AW TUI lists show `id · title` and expose the abstract in detail; Pi never renders the abstract and uses one 100-column responsive breakpoint. Detail presentation at 100 columns or above shows `P1 · Title` todo rows and `Step Wave(current/total) [P1] → [P2] → [P3,P4]`; compact presentation below 100 uses `1. Title` and `Step Wcurrent/total [1]→[2]→[3,4]` only when compact IDs stay one-to-one across the complete current workload and otherwise retains full IDs such as `S1. Title` and `[S1,X1,X2]`. Neither tier adds parentheses or `+N` compaction, and long headers wrap into terminal-safe rows. The Weyaw Pi extension publishes task status as ` · AGT` through `ctx.ui.setStatus("weyaw", ...)` and does not own or replace the footer. A footer owner such as Pi Choco Chips can combine that status with the `mcp` key as ` · AGT · MCP`, reserving the marker suffix and applying terminal-cell truncation only to the task id. Pi's Agent widget groups included rows by first appearance in canonical activity order: one GroupID heading supplies the only Group context, and child rows omit repeated Group id and assignment position. Compact Group headings show active/total plus aggregate used tokens; detail headings add the `active` label but keep the same aggregate used-token total rather than summing context limits. Group and Agent fields use two-space list columns instead of repeated middle-dot separators. Compact Agent rows use status marker, mode, `harness/profile`, authored title, used tokens, and the individual Action order preset. Detail rows add Agent id, full status, token budget, turns above one, and retries above the first attempt. HUD compact mode still includes only queued/running Agents and expanded mode includes all bounded rows independently of responsive presentation. Historical rows without identity use the label-first fallback, and every Group or Agent row is truncated by terminal display cells. - `aw index` reports or queries local project/workflow index state. - `aw index source-map` projects compact structural roles published with each active index generation. It never walks source corpora at query time. A corpus reports `available: false` with warnings while unbuilt, dirty, backlogged, refreshing, or migrating; `scanned_files` is the number of files classified in that published generation, not a query-time scan count. `explore-plan` continues with ready lexical search evidence and does not reconstruct the map in the foreground. - Manifest/source-map schema upgrades are performed by index-server background reconciliation or explicit index administration, not by normal task steps. ### TUI Settings The interactive Settings tab presents seven semantic groups: Services, Index, Actions, Workers, Workflow, Documentation, and Signals. Booleans use toggles, bounded choices use selectors, numbers and text use inline editors, optional values use enable/edit controls, ordered values use list editors, and profiles or order presets use grouped object operations. The editor never exposes a raw TOML tree or asks users to manage dotted keys. Settings edits the stored raw value. For interpolated path fields it shows the `${project_root}` or `${artifact_root}` expression alongside a resolved preview and never writes the preview back as an absolute path. Profiles and presets stay name-sorted. Renaming either updates all references transactionally; referenced deletion is blocked with dependency paths; only profile-member order inside a preset has explicit reorder semantics. Profiles and presets are deleted separately without cascading. Drafts remain memory-only until Save. `Ctrl+S`, leaving Settings, or quitting enters the same validated save path; dirty leave and quit offer Save, Discard, or Cancel. Every write takes the short config lock, compares the load-time digest inside the lock, validates, preserves representable TOML decoration, and atomically replaces the file. A stale external edit rejects the save and preserves the draft. Watcher events for the saved digest do not reset focus or modals; different bytes become a visible conflict instead of overwriting a dirty draft. After a successful save, one modal lists `Start`, `Stop`, `Restart`, or `None` for Agent Server and Index Server. The user may apply the consolidated list or skip all operations. Activation is a separate phase: failure never rolls back the valid config, successful operations are removed from the retry list, and the remaining failed operations can be retried without rewriting the file. Dashboard is not part of this workflow. Long-running lifecycle commands require a host environment that can retain processes; ordinary reads, status, guidance, roadmap, and artifact commands do not. ## Official Agent dispatch Weyaw ships immutable, version-matched official Agent Actions and Trigger bindings. Every parallel-safe official Action defaults to `fan_out=8`, including `agent.complex.reasoning`; the temporary broad-control Action `agent.control.aw-cli-chain` remains the sole exception at immutable default and maximum `1`. Task-step project config may choose any positive `u32` value rather than a dedicated 8, 12, or 64 ceiling. Effective Action `fan_out`, `agent_server.project_concurrency`, group concurrency, worker availability, readiness, sandbox, write-root, and resource gates remain finite running-capacity limits. Current versionless config stores every Agent Action at `actions.""`, selects a reusable worker `order_preset`, narrows turns, fan-out, and content-token limits within bundled ceilings, and names per-project Agent Server capacity as `agent_server.project_concurrency`. It stores official activation enablement at `triggers."".enabled` only where the Trigger permits project disablement. Fresh config creates empty `explorer`, `thinker`, `reviewer`, `executor`, `light-reviewer`, and `light-executor` presets; configuring the first real profile fills those empty bootstrap presets without guessing a provider. `extensions/actions.json` may add `local.*` Actions and Triggers only by extending the same official binding; it cannot override official ids or widen source, context, executor, capability, write-root, or resource authority. Current config is never inferred from retired fields or layouts. Run `aw config repair` to restore the complete strict versionless template from recognized current settings. Repair removes unknown fields, fills current defaults, validates the full result, and never converts retired names, values, or extension files. Use `aw agent readiness --json` before dispatch. Every task or non-task readiness request names `--trigger`; task requests also name `--task` and may assert the recorded `--step`, while non-task requests name `--context` and may name an existing `--operation` or let readiness allocate one. Readiness resolves and reports both `trigger_id` and `action_id` together with context, owner, workdir, canonical write roots, recovery decision, and resource conflicts. Requests use `--trigger`; there is no definition alias or alternate selector. Every `aw agent readiness --json` result and each Agent-capable Dynamic Guidance result includes `mcp_host_recommendation`. The object contains `advisory=true`, `transport="stdio"`, `command=["aw","agent","mcp"]`, the initialized project path in `cwd`, `shared_methods=["tools/list","tools/call"]`, and `required_tools=["agent_monitor","agent_join"]`. These fields describe the complete currently verified useful cross-Harness intersection and therefore the maximal shared capability baseline; newly universal useful capabilities are promoted into it. The descriptor is advisory: it does not gate readiness, submit, or fallback and never changes Host-owned configuration. - Task writers are bound to the task's frozen worktree. Brainstorm, Analyze, and Execute official project contributors require explicit project-relative `--write-root` values outside the artifact root. Each write root is directory authority, not a file selector. Declare each existing or planned file separately with `--target-file`; every target file must be strictly contained by at least one validated root and never widens or narrows that authority. An existing file passed as a write root is rejected with a correction to pass its parent directory as the root and the file as the target. - Before either provider launches, the shared runtime creates missing directory roots and missing target-file parents only. It never creates the target file or a directory at that path. Empty, absolute, parent-escaping, root-equal, outside-root, directory-valued, or symlink-escaping target files fail before session publication; Codex and Claude transports do not implement separate target rules. - Every non-task read-only launch still creates durable project-owned group/session evidence under `.aw/agents`. Promote useful conclusions into task, action-log, or knowledge artifacts before treating advisory Agent output as workflow authority. - `control.aw-cli-chain` is the only official non-task writer. It matches `weyaw.operation.aw-cli` and may open one temporary broad `aw **` capability. The harness runs in the common sandbox with project and workflow files read-only; AW invocations are proxied, recorded, and followed by Host reread. - `aw agent submit` requires exactly one `--task` or `--operation` plus `--trigger`, `--id`, `--title`, and `--objective`, and repeats the resolved readiness and identity policy immediately before persistence. `aw agent start` requires the same semantic identity inputs plus `--trigger`. Agent ids use 1..48 ASCII characters from `[A-Za-z0-9._-]`; titles use 1..48 terminal display columns. Objective remains execution truth and the detailed abstract source. - `aw agent group start` accepts the same owner forms and reads its strict assignment document through `--input` or `--input-file `. Every assignment requires `id`, `title`, `objective`, `role`, `trigger`, `scope`, and `prompt`; assignment `id` becomes the persisted `agent_id`. Writable assignments may add `write_roots` as explicit directory grants and `target_files` as existing or planned files inside those grants; omitting `target_files` preserves a directory-only assignment. Target files become conflict evidence automatically, but do not make overlapping directory grants safe for parallel execution. For a task-step logical Wave, the Host publishes the complete set of Agent-safe assignments in one group when at least two exist and handles a singleton directly. Assignment count is not capped by task-step `fan_out`; the effective Action and AgentServer capacities are persisted as group running concurrency, so excess assignments remain queued and start as slots become available. While sessions are queued or running, the Host may continue dependency-, write-scope-, and resource-disjoint Host-owned or control work. If one writable member completes while peers remain live, group status recommends that member's `aw agent review` before another aggregate status read; once all latest turns finish, status continues to recommend cooperative group join for shell closure. Runtime-operation groups retain their bounded assignment-count enforcement. Missing identity, Trigger, or valid target authority fails before the group manifest or any member is written. Group retry and follow-up preserve the same logical node id and require current Trigger/Action identity, while history, output, interruption, cancellation, review, and adjustment remain available for inspection and safe cleanup. - Use `aw agent group status|join|cancel|retry --task ...` for task groups or the corresponding `--operation ` form for runtime-operation groups. - Interpret AGT-X evidence as three independent facts: session `status` is the runtime outcome, `observed_changes` records mutation evidence, and `review_decision` records the parent disposition. No field implies either of the others; a completed writable run is not accepted until the parent records its review decision. ## Agent progress monitoring - `aw agent monitor --session [--since-line ]` performs one bounded read of current session identity, adapter, token, timing, progress, latest-turn, output, and terminal evidence. Add `--wait` to block without mutation until unread progress exists, the latest durable turn is terminal, or the runtime session finishes. - `aw agent monitor --session --stream [--jsonl]` emits a low-noise current activity feed until one terminal result. Stream mode does not replay old activity and cannot be combined with wait, cursors, group mode, or global `--json`. - `aw agent monitor --group --task [--wait] [--assignment-since-line =]` projects current evidence for every latest assignment attempt. Group mode is single-shot or one-wake and does not stream. - A monitor cursor is a complete progress-log line position. Carry `next_line` into a later call to receive only unseen events. An out-of-range cursor is an error; reread without a cursor and compare the current attempt and progress evidence. - When a latest turn becomes terminal and output is durable, inspect AGT-R through `aw agent history` or `aw agent output`, and inspect AGT-X through `aw agent review` followed by `aw agent adjust`. Agent completion never accepts changes or advances workflow state. - `aw agent mcp` runs a foreground, project-bound MCP server over newline-delimited stdin/stdout. `agent_monitor` accepts `session_id`, optional `since_line`, and optional `wait`; `agent_join` accepts one ordered non-empty `session_ids` list of at most 64 entries. Session resources use `weyaw://agent/sessions/`. `agent_join` is the normal MCP all-of dependency barrier. It rereads current session state until every declared session is terminal, preserves input order, and owns no join artifact, inbox, delivery ledger, or copied result store. A successful response includes each session and group identity, normalized owner projection, terminal status, durable evidence paths, bounded final-message text, and caller-local `barrier_wait_ms`. Canceling the tool call stops only that wait; it never cancels Agent sessions. Hosts without MCP retain session ids and use `aw agent monitor --session --wait [--since-line ]` plus `aw agent output ` at dependency barriers. Cooperative groups use group monitor mode and `aw agent group join` only to close lingering shells after useful turns finish. Stream records contain bounded status and activity metadata only; they omit prompts, reasoning, provider payloads, tool inputs or results, commands, paths, stdout, stderr, and full evidence arrays. Closing a stream ends only the observer. Durable group/session/turn artifacts remain authoritative evidence, while monitor and join durations remain read-time projections. See [Getting Started](getting-started.md) and [Dashboard](dashboard.md).