Core model
autodev uses a small set of typed entities so that the plan, the work in flight, and the result do not blur into one another.
Planning entities
The board is the complete planning surface loaded from the repository working tree. Its main entities are:
| Entity | What it means |
|---|---|
| Story | A dispatchable unit of work: a goal plus individually numbered acceptance criteria |
| Epic | A larger problem and scope that groups stories |
| Design | A design document referenced by stories or epics |
| Decision | A proposed, accepted, rejected, or superseded architectural decision |
| Glossary term | A stable project term with aliases, relationships, and affected areas |
| Workflow | States, allowed transitions, and gates expressed as data |
A story also carries a kind, optional complexity, optional impact, urgency, dependencies, claimed
areas, and links to its surrounding epic or design. Complexity describes what the work demands;
repository configuration decides which model, if any, that level maps to. Impact describes what
landing the work is worth — low, medium, high, or critical — and is independent of
complexity; it is recorded but not yet consulted by scheduling, and an unstated impact means
unassessed rather than low. Urgency changes scheduling, not the proof required for acceptance.
A story can also carry human approvals. Each is a recorded decision naming a human gate, the actor,
and an optional note; it satisfies that gate at the next transition whose edge carries it, and that
transition spends it.
An acceptance criterion can declare a verification handle: a command, named test, or expected artifact. These handles are planning metadata in the current release; handoff creation does not yet execute and bind each handle individually. If verification is intentionally skipped, the criterion carries a waiver with an actor and reason. A checked Markdown box is a human-facing progress signal, not proof.
Workflow state is not fleet state
A story moves through its configured workflow. A workflow declares states, directed edges, and the gates attached to each edge. Gate kinds are deterministic checks, mechanical evidence, an agent judge, or an opt-in human decision.
A wave has a different lifecycle. It describes execution rather than planning: queued, dispatched, awaiting handoffs, reviewing, integrating, gated, applied, or a reason-carrying recovery state such as reopened, parked, stranded, or cancelled.
Keeping those state machines separate matters. “The worker finished a turn,” “the change passed a gate,” “the commit was delivered,” and “the story moved to done” are distinct facts and can fail at different points.
Runtime entities
| Entity | What it records |
|---|---|
| Wave | A batch of stories, a pinned base ref, pinned story contracts, state, and retry budget |
| Worker | One agent attempt for one story, including process ownership and terminal outcome |
| Handoff | The candidate commit, observed write set, evidence, and optional note for a retry |
| Evidence | The validation command and the observed before/after failure classes |
| Judge verdict | An independent review turn and its reasoned pass or refusal |
| Delivery | The runtime's attribution of a story to a wave, commit, and time |
| Event | A timestamped, actor-attributed fact in the fleet history |
| Request | Verbatim operator or agent intent with principal, profile, surface, time, and idempotency key |
| Answer | A named request's explicit answered, refused, or waiting-human outcome |
| Coordinator cycle | One typed workflow run, its observation cursor, node outcomes, and any question or refusal |
A worker ID names one attempt. A retry creates a new worker so the earlier transcript and outcome remain intact. Delivery records and conversation outcomes are append-only facts. A request without an answer remains unanswered; absence does not become a synthetic success or task.
Workspace and control entities
A workspace is one registered repository root and its runtime-store identity. Registration is machine-local and optional. A live daemon addresses a registered workspace by id inside its one global runtime store. Without a live recorded endpoint that registered workspace's runtime history is unreachable; only an unregistered repository uses a repository-local store. Registration does not copy the planning board out of Git.
A canvas is a validated declarative UI tree over a closed component vocabulary. It binds panels to datasource handles, never to credentials or scripts; a host resolver supplies data under the current principal's grants.
A connector describes a compiled provider and its operations, credential requirements, risk, and wiring state. In the current release Connect can inspect that catalogue and manage local credentials, but a catalogued operation is not automatically an executable workflow action. See Current limitations.
Pinned contracts
Dispatch captures both the exact base commit and the story fields that affect execution: title, goal, criteria, areas, complexity, and urgency. The author can continue editing the planning file, but an in-flight wave does not silently change its assignment. Board checks report drift between the live story and the pinned snapshot.
That boundary is central to the model:
editable plan -> pinned execution contract -> observed delivery facts
Next, follow these entities through the delivery lifecycle, or see why autodev distinguishes claims from observations in Trust and evidence.