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

Contract

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

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 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_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