# Concepts

Weyaw keeps agent work in project-local artifacts so it can be resumed,
reviewed, and verified without reconstructing the task from chat history.

## Project workspace

An initialized project normally stores workflow state under `.aw/`. The
workspace contains the project profile, blueprint guidance, roadmap index,
task artifacts, knowledge, configuration, and runtime metadata. Git remains
the source of truth for project code; Weyaw records the intent and evidence
around changes.

## Task lifecycle

A task starts in `todo`, moves to `active` before implementation, and moves to
`archive` only after closure steps finish. The standard steps are:

1. `create` — record the intention and roadmap association.
2. `brainstorm` — clarify an underspecified request when needed.
3. `analyze` — collect direct source, test, contract, and prior-task evidence.
4. `plan` — define executable steps, verification signals, and any user-confirmed delivery limits.
5. `execute` — apply project changes and record action evidence.
6. `verify` — run checks against the accepted goal and close every discovered open risk.
7. `review` — inspect quality and required follow-ups when useful.
8. `consolidate` — preserve reusable learning when useful.

Optional steps may be skipped only with a recorded reason. Failed or blocked
work remains resumable through its task id.

## Blueprint and roadmap

Blueprint documents hold durable project language, boundaries, standards, and decisions. A large root may list canonical child documents under `## Components` using ordinary relative Markdown links. Only those ordered links form composition edges; nested files inherit the root role and heading contract, remain independently indexed, and are never copied into a generated durable aggregate. Use `aw docs --compose <root-id>` for an explicit root-first source-attributed view.

The roadmap orders candidate work and links executable tasks to specific items. Task progress does not replace either surface: implementation evidence stays in task artifacts, while durable direction is promoted through explicit workflow feedback.

## Evidence and direct reads

Index and guidance results narrow candidate files; they are not proof. Agents
must read referenced source or workflow artifacts directly before using them
as evidence. Plan records user-confirmed delivery boundaries in
`accepted_limits[]`. Verify records command evidence in `checks[]` and
unresolved issues in `open_risks[]`; completion means passed checks with no
open risk, not mere process completion.

See [Artifacts](artifacts.md), [Skills](skills.md), and
[Getting Started](getting-started.md).