# Artifacts

Weyaw stores durable workflow evidence in the initialized project workspace,
normally `.aw/`. Use Weyaw commands and skills to mutate registered artifacts;
do not hand-edit task state or lifecycle JSON.

## Project-level surfaces

- `project.md` — project goal, users, constraints, decisions, and source
  evidence.
- `blueprint/` — durable specifications, standards, vocabulary, and core
  guidance such as `aw.md`.
- `roadmap/index.json` and phase item files — ordered candidate work and task
  references.
- `knowledge/` — retained project knowledge written through the knowledge
  command.
- `config.toml` — project service, agent, docs, and workflow configuration.

## Task-level surfaces

Tasks live under lifecycle directories such as `tasks/todo/`, `tasks/active/`,
and `tasks/archive/`. A task may contain:

- `intention.md` and `task-status.json`; tracked `analyze`, `plan`, `verify`,
  and `review` step records may carry ordered `todo | doing | done` rows;
- `analysis.json` and `plan.json`;
- `execution.json` and `action-log.json`; Execute progress lives here rather
  than in task-status todos. Plan-backed rows omit `title` and use the owning
  Plan title, while titled execution-only work records deviations discovered
  after plan approval;
- `verify.json` and `review.md`;
- `summary.jsonl`, blueprint feedback, and task-local Agent evidence.

The CLI validates artifact schemas and owns lifecycle moves. The Host replaces
tracked step todos atomically through `aw step todo set`; Pi and generated
contributors only observe the resulting artifacts. Archived artifacts remain
readable for later tasks and index discovery.

## Runtime and generated content

`.aw/.runtime/` contains ephemeral service, job, heartbeat, and other
project-bound state. It is not durable task evidence and must not enter the npm
package. Rebuildable index contents live outside the artifact root in a
project-keyed per-host user cache such as
`<platform-user-cache>/weyaw/index/<project-key>`. Legacy
`.aw/.runtime/index/` content may remain quiescent and can be rebuilt rather
than treated as workflow truth.

Non-task Agent runs add device-local operation evidence under
`.aw/.runtime/agent-server/operations/<operation-id>/`; group publication
manifests live under `.aw/.runtime/agent-server/groups/`. A temporary control
operation may also carry a broad `aw **` grant whose proxied invocations and
results remain runtime-only. These jobs, sessions, messages, event logs,
manifests, grants, and control locks may be rebuilt or discarded without
changing durable workflow truth. Historical task jobs without an explicit owner
remain readable as task-owned records.

Generated agent skill directories such as `.agents/`, `.codex/`, and `.claude/`
are project integration surfaces rather than packaged project history.

The workflow workspace may be a separate Git repository. Commit tooling treats
project changes and workflow artifacts independently and stages only the
current archived task scope.

See [Concepts](concepts.md) and [CLI](cli.md).