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

Contract

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

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_plan_parallel_groups

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

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 inline execution.

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 and Implementation Execution for details.

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