---
title: Project Artifacts
description: 'Project artifact contracts: state.md, spec.md, design.md, plan.md, and implementation.md.'
---

# Project Artifacts

Project artifacts live under `.oat/projects/<scope>/<project>/`.

## Core artifacts

- `state.md`: lifecycle state and checkpoint metadata
- `discovery.md`: problem framing, constraints, solution space exploration (for exploratory requests), and discovery outcomes
- `spec.md`: requirements + acceptance criteria
- `design.md`: architecture and implementation approach (full in spec-driven mode; optional lightweight version in quick mode covering architecture, components, and testing strategy)
- `plan.md`: phase/task breakdown and review tracking
- `implementation.md`: execution log, verification, final summary
- `summary.md`: institutional memory artifact — generated from project artifacts at closeout, used as PR description source and archive cover page

Mode-sensitive notes:

- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`) for routing.
- `spec.md` and `design.md` are required in spec-driven mode, optional in quick/import mode. Quick mode offers a lightweight `design.md` (architecture, components, testing strategy) at a post-discovery decision point.
- `plan.md` remains canonical execution artifact across all modes.

## Supporting artifacts

- `summary.md`: generated by `oat-project-summary` — re-runnable, tracks its own state via frontmatter for incremental updates after revisions
- `reviews/*.md`: phase/final review files
- `pr/*.md`: generated PR descriptions
- `references/imported-plan.md`: preserved source plan for import mode
- `references/split-plan.json`: persisted split plan for a coordination parent, used as the durable resume source when `oat-project-split` is interrupted

### Gate review frontmatter

Review artifacts produced by `oat gate review` use the normal review fields plus
an exact copy of the gate-owned configured invocation:

```yaml
oat_review_invocation: gate
oat_project: .oat/projects/shared/example
oat_gate_run_id: 00000000-0000-0000-0000-000000000000
oat_gate_target: codex-sol-max
oat_gate_runtime: codex
oat_invocation_model: gpt-5.6-sol
oat_invocation_reasoning_effort: max
oat_invocation_source: exec-target-config
```

`oat_invocation_model` and `oat_invocation_reasoning_effort` may be
`provider-default` when OAT deliberately leaves a control to the provider, or
`unknown` when the target does not declare it. These fields are configured
invocation metadata, not runtime-confirmed or self-reported model identity.
Manual and auto review artifacts do not require the gate-only fields.

## Contract

Artifacts are the project system of record; automation and routing should derive from these files, not memory.

### Formatting and verification hygiene

Tracked artifacts are part of the repository diff, so artifact writers format
them before finishing or committing. During plan authoring, OAT resolves the
repository's documented write/fix command from applicable `AGENTS.md` /
`CLAUDE.md` instructions and relevant package manifests. Each task that writes
an artifact receives a concrete invocation, scoped to that task's files when
the command supports paths.

Downstream implementers execute that supplied command without repeating
discovery. Roles and lifecycle skills that write outside a planned task,
including reviewers and documentation, summary, PR, and quick-start flows, use
the same discovery procedure as a fallback. Gate-originated review prompts also
carry the contract so review artifacts follow the same rule across runtimes.

Writers must:

- prefer a documented write/fix command over a check-only command;
- avoid inferring or hardcoding a formatter;
- scope the write to created or edited files when supported;
- avoid whole-tree rewrites that could absorb unrelated changes; and
- warn once with
  `no format command discovered in repo instructions; skipping` when no command
  is discoverable, then continue.

Formatting supplements the applicable verification contract. Phase
implementation runs repository gates over its produced diff, including
artifact writes. Prose-only lifecycle work runs only checks relevant to the
files it changed.

## Coordination parents

Project splitting introduces a coordination-only parent artifact. It records shared context and child relationships, but it is not an executable lifecycle project.

A coordination parent uses:

- `oat_kind: coordination`
- `oat_phase: decomposition`
- `oat_phase_status: complete`

Coordination parents do not contain executable phase files. `spec.md`, `design.md`, `plan.md`, and `implementation.md` are removed from the parent and represented in state prose as not applicable.

The parent still keeps `state.md`, `discovery.md`, and `references/split-plan.json`. Child projects are flat siblings and link back to the parent through state metadata. Each child starts from a distilled discovery seed and must revalidate inherited context before moving beyond discovery/design.

See [Project Splitting](splitting.md) for the full parent/child model.

### plan.md frontmatter

`plan.md` carries frontmatter that the implementation skill consumes. Notable fields:

- `oat_plan_hill_phases` — list of phase IDs to pause at for HiLL checkpoints.
- `oat_plan_parallel_groups` — declares which phases may execute concurrently in worktrees. See below.
- `oat_phase_review_gate` — opt-in non-pausing external review gate that runs after a phase's standard reviewer passes. See below.

#### oat_plan_parallel_groups

Declare phase groups that run in parallel during `oat-project-implement`:

```yaml
oat_plan_parallel_groups: [['p02', 'p03'], ['p04', 'p05']]
```

Each inner array is a group of phases that execute concurrently in their own worktrees and merge back to the orchestration branch in plan order. Phases not listed in any group run sequentially.

**Semantics:**

- Empty or missing field → fully sequential, no worktrees created (default).
- Each group must contain **2 or more** phases — singleton groups are rejected.
- Every phase ID must exist in the plan body.
- No phase may appear in more than one group.
- Parallelism is only honored at Tier 1 (native subagents). Tier 2 degrades parallel groups to sequential target-preserving execution, not unconditional inline review. Concrete managed Claude reviewers retain the exact resolver-returned `dispatchArgs.model`; Cursor reviewers retain the exact `providers.cursor.dispatchArgs.variant` native agent type; Codex retains its exact role or pinned child. Every retry preserves the complete target. Inline review requires verified equivalent host controls or an explicit inherit/default or managed-uncapped base-role exception, and otherwise blocks.

**Authoring responsibility:**

- `oat-project-plan` proposes parallel groups when phases have file-disjoint task sets; it never infers parallelism silently.
- Phases listed in a group should have no file-level overlap. Overlap will produce merge conflicts during fan-in that stop the run.

**Validation:**

Before dispatching, `oat-project-implement` invokes `oat project validate-plan --project-path "${PROJECT_PATH}"`. Non-zero exit blocks the run. See [CLI Reference](../../reference/cli-reference.md) and [Implementation Execution](implementation-execution.md) for details.

#### oat_phase_review_gate

Enable an optional, non-pausing external review gate that runs after each selected phase's standard reviewer passes and its bookkeeping is committed:

Planning offers this setting after stable phase IDs exist and before the plan
artifact review. The read-only target probe qualifies only an explicitly
configured, enabled, and available target, then offers all phases, selected
phases, or disabled. An explicit `oat_phase_review_gate` value from a resumed or
imported plan is preserved unchanged without re-prompting. If the probe fails,
no target qualifies, the run is non-interactive, or the user declines, planning
leaves phase review disabled.

```yaml
oat_phase_review_gate:
  enabled: true
  phases: [] # empty or omitted = every implementation phase
  review_type: code
  exit_nonzero_on: important
```

**Semantics:**

- Missing, `null`, or `enabled: false` → disabled (default). `enabled: true` activates the gate.
- `phases` → optional. Empty or missing runs the gate after every implementation phase; a populated list restricts it to those phase IDs, each of which must exist in the plan body.
- `review_type` → optional, defaults to `code`. Only `code` is supported for phase gates.
- `exit_nonzero_on` → optional, defaults to `important`. One of `critical`, `important`, `medium`, `minor`. This is the blocking threshold: findings at or above it stop the phase; sub-threshold findings are dispositioned by the judgment sweep rather than ignored.

A malformed gate stops the run before task execution rather than being silently disabled. The gate is independent of HiLL checkpoints and reuses the existing `oat gate review` target config — it does not hardcode a `--target`. See [Reviews → Phase review gate](reviews.md#phase-review-gate) for the runtime behavior and disposition rules.

## Reference artifacts

- `.oat/templates/*.md`
- `.oat/projects/<scope>/<project>/spec.md`
- `.oat/projects/<scope>/<project>/design.md`
- `.oat/projects/<scope>/<project>/plan.md`
- `.oat/projects/<scope>/<project>/implementation.md`
- `.oat/projects/<scope>/<project>/summary.md`
