# Skills Weyaw installs project-local skills for coding agents. Initialize the project, then select the integration target: ```bash aw init "Short project summary" aw install --target agents ``` Use `--target claude-code` for Claude Code, `--target codex` for Codex, or `--target all` for every supported target. ## Common skills The generated bundle contains these fifteen user-facing skills: - `$aw` — load lightweight project workflow context without starting a task. - `$aw-init` — initialize or reconcile the project profile. - `$aw-help` — suggest a project-aware next action. - `$aw-blueprint` — update durable design language, standards, and core guidance. Ordinary Blueprint roots follow explicit `## Components` links, edit canonical sources, and validate the graph without writing a flattened aggregate. `aw.md` remains standalone free-form guidance. - `$aw-commit` — stage and commit one active task in source and workflow repositories after explicit confirmation; task worktrees rebase onto the current main checkout, rerun required verification, and integrate only by fast-forward. - `$aw-config` — inspect, explain, or modify typed project configuration through Weyaw-owned config commands rather than editing `config.toml` directly. - `$aw-index` — inspect index capability, freshness, and discovery surfaces. - `$aw-roadmap` — maintain roadmap phases and items without creating tasks. - `$aw-uiux` — provide UI/UX, visual, interaction, or motion-design guidance only when the user explicitly requests that judgment. - `$aw-task ` — create or locate one roadmap-linked task and run its lifecycle. - `$aw-resume ` — continue the recorded next step. - `$aw-status` — summarize task lifecycle and blockers. - `$aw-health` — automatically recover deterministic health findings within the current project, including registered members when invoked at a workspace; user-invoked maintenance may select a broader discovery scope. After explicit approval it routes an archived `worktree_pending_removal` finding through `aw task retire-worktree --reason --confirm` rather than force-removing the checkout. - `$aw-dream` — diagnose post-onboarding blueprint-versus-code drift through a normal task without assuming either side is authoritative or applying fixes itself. - `$aw-goal ` — run a bounded ordered batch in one shared isolated worktree for eligible Git repositories, committing and integrating each task before archive, then reconciling remaining items from completion evidence before continuing. `$aw-goal` reuses one named task worktree leaf across the batch; multi-repository projects use the existing per-repository checkout layout. Non-Git worktree isolation is inapplicable, and incompatible frozen bindings pause the batch rather than silently falling back to the main checkout. Each task retains its normal rebase, required verification, and fast-forward integration gate. Keep the shared worktree through task boundaries and pauses, and request cleanup separately through `$aw-health` after the batch. Resume with the original scope so completed task references remain available to recover the binding. After each task archives, the Host reviews its actual implementation and verification against the remaining items. Necessary title, intention, prerequisite, or validation refinements go through `$aw-roadmap`, preserving item ids, task refs, unfinished outcomes, and the accepted goal. No-change reviews continue immediately. Scope expansion, meaningful target removal or replacement, weaker acceptance, changes to user-specified order, and unresolved decisions require confirmation. The next task uses the reread roadmap rather than a stale pre-run intention. ## Health scope Agent-detected health problems enter the existing automatic recovery protocol without a scope question. The default is the current artifact root, plus registered member roots when that root is a workspace. Invoking health inside an ordinary member does not include its parent or siblings. A shared Skills diagnostic may route only the reported reinstall to the workspace bundle owner; it does not authorize wider artifact repair. An explicit user invocation without a scope may offer current project (recommended), a specified directory, or global discovery. Global means filesystem anchors confirmed by the user, not an automatic scan of every disk. An already specified scope needs no repeated question. Explicit check-only requests remain read-only, including Skills installation. These are Skill instructions, not new `aw check` or `aw repair` flags: ```text $aw-health repair the current project and its registered workspace members $aw-health check and repair all .aw roots under /path/to/Nextcloud $aw-health check all .aw roots under /path/to/Nextcloud without modifying anything ``` The Host deduplicates canonical artifact roots and shared bundle installations, processes each root through the existing guarded repair protocol, and reports healthy, repaired, warning-only, blocked, pending, or skipped outcomes. Failed roots and incomplete discovery remain visible without stopping independent roots. Uninitialized directories are not initialized, uncertain copies are not silently repaired, and semantic or destructive decisions retain their existing approval boundary. Automatic recovery rechecks and retries the original operation when its own prerequisites pass; unrelated roots do not block it. ## Static and dynamic guidance Installed `SKILL.md` files define stable orchestration rules. At activation, skills load dynamic guidance from the current project, including core context from `.aw/blueprint/aw.md`. One centralized guidance block also provides the absolute path to the version-matched product docs shipped with the installed package; individual skill files do not repeat that path. Dynamic guidance can narrow evidence, render matching official Agent triggers, or describe runtime boundaries; it does not replace direct source reads. `complex.reasoning` may activate in any Weyaw context, while project-writing AGT-X is limited to official Brainstorm, Analyze, and Execute triggers with frozen-worktree, common-sandbox, and explicit write-root readiness evidence. `$aw-task` and `$aw-resume` may also render `control.aw-cli-chain` to open one temporary broad `aw **` capability under a device-local runtime owner; the harness cannot edit workflow files directly and the Host reconciles compact mutation receipts, rereading only when the receipt cannot safely determine the next route. Task-scoped step guidance is intentionally a delta after the router has loaded stable protocol and core context: it keeps task-sensitive index, Agent readiness, capability, recovery, fallback, and config facts without expanding the same core, product-doc, host-boundary, or overlapping wildcard definition text again. It also returns a bounded deterministic `command_specs[]` list derived from the compiled Clap tree. Skills trust each listed `usage`, never query broad or parent help, and permit at most one exact-leaf help fallback when a needed spec is absent or a listed invocation is rejected. At task creation or resume, the Host inspects its own Agent environment for a real `name=version` and supplies it through `aw create --agent-runtime` or `aw task config --agent-runtime`. Skills must stop when that evidence is unavailable; they do not infer it from project config, copy a prior task value, or emit `unknown`/`unrecorded`. Every changed task JSON root records that semantic-author runtime and the executing AW runtime, while JSONL and action-specific evidence retain their record-level provenance. Use the packaged `aw` command in installed projects. Within the Weyaw source checkout, use `node bin/aw-debug.js` so guidance reflects the current code. To revise existing core context, use `$aw-blueprint`: read `aw blueprint read aw --json`, then apply an approved exact edit with `aw blueprint replace aw --expected-sha256 --match --input `. The writer preserves unmatched prose and rejects stale content. `aw.md` has no required headings or Components family; `aw init` seeds missing or empty guidance and preserves existing nonempty content. Subsequent guidance requests deliver the revised content with a new core-context fingerprint. ## Runtime briefs Every skill activation and workflow step entry requires a user-visible **Weyaw Runtime Brief**, including cached-context replay and degraded or failed guidance. The Host prints it before continuing or stopping; tool output, a plugin or a status bar does not replace this obligation. The Core Action `guidance.compose` returns a structured `runtime_brief` and default text. Composed `step enter` forwards the same brief. One installed protocol, `aw-task/shared/runtime-brief.md`, defines presentation, localization, conditional fields and failure fallback for all skills and task routers. The brief distinguishes current guidance integrity from runtime observations. AgentServer evidence reports the current projected service state and worker heartbeat capacity with its source and observation time, while preserving explicit limits around operating-system process liveness and executable-generation matching. Core remains blind to Host MCP transports: when the harness exposes current MCP inspection, the Host checks the already-established connection, compares discovered tools with `mcp_host_recommendation.required_tools`, and presents scoped evidence with provenance and time. Successful `tools/list` proves the connection and discovery path, while successful `tools/call` additionally proves invocation. Guidance composition reports Action execution readiness as `not_applicable` until an exact owner, Trigger, capability and resource request exists; existing readiness runs immediately before dispatch. These checks never establish or restart MCP connections, probe providers, start services, or modify Host configuration merely to fill the brief. ## Host-owned step todos The `$aw-task` Host seeds and updates durable ordered todo DAGs for `brainstorm`, `analyze`, `plan`, `verify`, and `review` through `aw step todo add`, `update`, and `remove`. Each stable node has a bounded `id`, short title, required `abstract` of at most 256 display columns, explicit `depends_on[]`, and `todo|doing|done` status. Repeat `--depends-on ` to set edges or use `--clear-depends-on` to remove them; missing references, self-edges, duplicate edges, and cycles are rejected. Multiple nodes may be `doing` when every predecessor is Host-accepted `done`, and every retained node must be done before close-out. Compact receipts return normalized rows, `doing_ids`, `ready_ids`, and progress. The complete-list `replace --input ''` or `--input-file ` operation is reserved for repair. Blueprint roots may use ordered rows shaped like `- [Concepts](concepts.md)` under `## Components`. Only those links compose; ordinary links remain references and directory contents are never auto-included. Skills read each canonical source with `aw blueprint read --json`; Dashboard clients may request `GET /api/blueprint?compose=` when they need the bounded root-first projection. Normal structured task artifacts use semantic `aw artifact` subcommands, so the Host sends typed scalar or repeatable argv instead of staging whole JSON payloads. Registered Markdown uses section or exact text mutations. Exactly-one opaque payloads use mutually exclusive `--input` or `--input-file `, where dash reads stdin; `aw write` remains a complete-document creation and repair boundary. Structural replacement selectors use `--match`. Typed semantic fields remain direct argv. `execute` uses `plan.json` plus `execution.json` instead of task-status todos. Plan-backed nodes inherit ids, titles, abstracts, and dependencies from Plan, while execution rows own status and evidence; their execution `depends_on[]` remains empty. Newly discovered execution-only rows provide their own title, abstract, explicit dependencies over the merged graph, and deviation evidence before work starts. The approved Plan is not silently rewritten, and no second progress or scheduler artifact is created. ## Agent ownership and authority Task Agent runs keep durable task-linked session evidence. Generic non-task reasoning and control operations use device-local runtime-operation owners instead of creating placeholder tasks. Project config selects worker order and narrows bounded turns, fan-out, and content budgets per official Agent Action; Trigger config owns permitted activation disablement. Additive `local.*` Actions and Triggers may extend one official binding but cannot override official ids or widen context, executor, writable, root, resource, or project-access authority. Agent Action prompt contracts own role, objective, scope, behavior, ordered execution, retry behavior, and evidence reporting. Project-content authority uses the same ordered `AccessMode = none < read < write` as Plan. Each Action declares a resource-bounded `project_access_ceiling`, and each resolved invocation carries an effective `project_access` grant; Core rejects any grant whose mode or roots exceed the ceiling. The Host compares Plan required access, invocation grant, and Action ceiling before launch and requests the minimum grant. Existing generic `writable` and `write_roots` still bound filesystem mutation such as workflow-only control Actions, so project access is not inferred from sandbox writability. Public `read-only|read-write` and `AGT-R|AGT-X` values remain boundary mappings: project `none|read` is AGT-R and project `write` is AGT-X, while a workflow-only artifact writer retains its existing AGT-X sandbox behavior. No AGT-N exists. Every parallel-safe official Action defaults to `fan_out=8`, including complex reasoning, while `control.aw-cli-chain` remains fixed at `1`; task-step configuration may use any positive `u32` value. Effective Action, group, project, and worker limits remain finite running-capacity gates. The Host derives each complete stable-order logical Wave from canonical task artifacts without splitting it by node count, `fan_out`, capacity, available slots, or queue state. When at least two assignments are Agent-safe, the Host publishes all of them in one group and excess assignments remain queued; exactly one stays Host-owned. The Host may continue dependency-, write-scope-, and resource-disjoint work while Agents run. Agent completion and joins are candidate evidence only: the Host validates the original node before marking it done and unlocking successors. Core hard gates own official Trigger/context matching, Trigger-to-Action resolution, task or operation identity, access and writable agreement, frozen worktree selection, canonical root containment, readiness, and resource conflicts. The Host remains the sole owner of workflow gates, artifact semantics, acceptance, lifecycle, and commits. See [Concepts](concepts.md) and [Artifacts](artifacts.md).