Project Artifacts

Project artifacts use one of three active scopes:

• shared artifacts live directly on the feature branch under .oat/projects/shared/<project>/.
• synced artifacts live in a gitignored nested worktree at .oat/projects/synced/<project>/, backed by refs/oat/projects/<project> on origin. The feature branch tracks only .oat/projects/synced/<project>.json.
• local artifacts stay untracked on the current machine under .oat/projects/local/<project>/.

projects.defaultScope controls creation when a command does not pass --scope; its default is synced.

Synced artifact bookkeeping

Lifecycle skills write the same project files in every scope. After a synced write, they use oat project push instead of staging the artifact path on the parent branch. The command makes an artifact commit in the nested checkout, rebases it on the fetched project ref, and pushes only that ref. Arrival skills run oat project pull before reading artifacts so a record or remote ref can materialize the checkout first.

The tracked JSON record is active routing metadata, not a copy of the project. It identifies the slug, origin, active ref, and status. The active project ref remains the source of truth for active artifact content and history.

Archived closeout transitions terminal identity to refs/oat/completed/<project>, deletes the active record and checkout, and persists source-ref identity in local archive metadata. Arrival and pull flows never rematerialize a completed project as active state: the completed ref and archive metadata own terminal reachability and retry identity.

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, lite) for routing.
• plan.md remains the canonical execution artifact across all modes.

Every Lite plan keeps Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria. User-visible changes add numbered, testable Product Behavior. Changes that cross module boundaries, alter data or state formats, or change a contract consumed by another surface add Technical Design. That section covers current operation, proposed changes, and data flow when data or state crosses a boundary. The Decisions section records the selected shape and why it fits.

Each Lite task also records an implementation and proof strategy: the risk it covers, why the evidence is proportionate, and the exact command or manual proof. Strategies may be test-first, characterization-first, implementation-then-regression, static/build, or manual/visual. Static or build checks alone fit only changes that cannot affect runtime behavior; every behavioral change needs evidence that fails without the change.

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
• references/project-retro.md: optional post-approval retrospective with machine-scannable repo-improvement (RP-NN) and upstream-feedback (UP-NN) registers. Promotion and filing rollups let the retro skills resume approved applications and tracker filing without repeating settled work. See Project Retrospectives.

Explainer artifacts

Explainer Kit writes project runs under <resolved-project-path>/explainers/<slug>/. The two project products have different retention contracts:

• A project-explainer is a working artifact. In a shared project it can be tracked while the project is active, but project completion removes it from the tracked branch with the active project tree. It remains only in the local archived project.

• A selected final project-recap is a durable completion record. Before a shared project is removed, archive copies the complete selected run to .oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/, verifies its immutable package hashes, and reports that tracked export path. Summary and PR links use this export, never the gitignored local archive. Lifecycle callers identify the selected project-relative run with:

  oat project archive <project-path> \
    --project-recap-run explainers/<recap-slug>

The archive exports at most one selected recap package. It preserves structured failure outcomes and successful intermediates, rejects an existing dated destination, and requires the selected path to stay under the project's explainers/ directory with a project-recap manifest. Verification covers the complete mode-aware package:

• privacy-safe request and content approval;
• fact-base JSON and Markdown;
• the five immutable set-plan records and authored drafts;
• declared author results and authored content;
• resolved theme and every built artifact;
• canonical mobile, tablet, and desktop screenshots;
• paired browser-evidence/v2 metrics with launched Chromium name, version, and capture identity;
• cohesion observations and each visual-review request/result; and
• the bounded revision record when a correction occurred.

Canonical object hashes identify normalized fact-base, theme, runtime, and capture objects; manifest.immutableHashes independently covers serialized file bytes. The archive requires one complete, internally consistent browser and review chain for a successful unattended recap. Missing, stale, forged, cross-record-mismatched, or tampered coverage fails before the active project is deleted.

built-needs-review is a terminal review-gate outcome, not a non-durable success. Its partial evidence remains available for diagnosis, but it cannot be finalized, exported, attested, archived, or pushed. Review and rebuild the recap to a passing visual-review outcome first.

Local-scope projects are not archived through this export path. Their explainer packages inherit the local project's untracked posture and remain built-not-durable unless independent publish evidence exists. Non-project OAT explainer runs use .oat/repo/reference/explainers/<slug>/; direct core callers must provide their own explicit output root.

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:

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

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

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