oat-project-split

name	oat-project-split
version	1.1.0
description	Use when a discovery or brainstorm should split one broad scope into coordinated OAT child projects.
argument-hint	--plan-file <path>
disable-model-invocation	true
user-invocable	true
allowed-tools	Read, Write, Bash(oat:*), Bash(pnpm:*), Glob, Grep, AskUserQuestion

Split OAT Project

Decompose a confirmed multi-project discovery or brainstorm into a coordination-only parent and flat child projects.

Mode Assertion

Use this skill only after one of these split triggers is present:

• The user explicitly declared the work is multiple projects.
• Discovery signals crossed the split threshold and the user confirmed.
• End-of-discovery convergence confirmed that the scope should split.
• The brainstorm destination picker selected a split into projects.

Detected split recommendations in non-interactive mode must fail fast through the CLI run command; do not silently split or silently continue as one project.

Progress Indicators (User-Facing)

Print a banner once at start:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OAT ▸ PROJECT SPLIT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Before multi-step work, print step indicators:

• [1/5] Writing coordination parent...
• [2/5] Scaffolding and seeding children...
• [3/5] Marking parent terminal...
• [4/5] Selecting active child...
• [5/5] Refreshing dashboard...

Process

Step 1: Resolve Split Plan

Require a persisted SplitPlanDocument JSON file. If $ARGUMENTS does not include --plan-file <path>, ask for the plan file path before proceeding.

Step 2: Run Split Orchestrator

Invoke the CLI as the single execution entry point:

oat project split run --plan-file "{plan-file}"

Use --non-interactive only when the caller is running without a human confirmation path.

Step 3: Write Coordination Parent

The run command writes the parent project as oat_kind: coordination, persists references/split-plan.json, records ordered children in state.md, writes the broad discovery.md with any integration sketch, and removes executable phase files.

Step 4: Scaffold + Seed Children

The run command scaffolds each child in plan order and writes split-specific child discovery content from scratch with the required inherited-context revalidation gate.

Step 5: Mark Parent Terminal + Select Active Child

The run command marks the parent oat_phase: decomposition and oat_phase_status: complete, then activates the initial child using the repo-relative project path.

Step 6: Resume From Partial State

If a previous split wrote a coordination parent but did not finish all children, the run command resumes from references/split-plan.json. Do not reconstruct missing child seed data from slugs alone.

Children Resume At Discovery (Revalidation Contract)

A split seeds children with inherited context, but that context is only a starting point. By the time an agent resumes a child it may be stale, so children must never be treated as discovered, planned, or implementation-ready just because the split wrote their files.

What the run command guarantees, and what reviewers should expect:

• Child state.md routes to discovery. Each child is written with oat_phase: discovery and oat_phase_status: in_progress, plus preserved oat_parent, oat_siblings, and oat_depends_on links. Resume, progress, and quick-start all key off state.md, so they pick the child back up at discovery — not at plan or implementation.
• Child discovery.md is in progress with an unmet revalidation gate. It carries oat_status: in_progress and oat_inherited_context_revalidated: false, an explicit "Inherited Context Revalidation Gate" section, and language stating that parent-derived scope is a seed, not a final decision. The discovery-completion gate blocks marking discovery complete until oat_inherited_context_revalidated: true.
• Child discovery is never marked complete during split generation. Seeding only provides a provisional starting point.
• Placeholder plan.md cannot be mistaken for a real plan. The seeded plan.md is re-marked as a not-started template (oat_template: true, oat_template_name: plan). Routing decisions read state.md (oat_phase: discovery), and oat-project-next treats oat_template: true as a still-a-template signal, so the placeholder never reads as plan-ready.

A child sitting at discovery / in_progress after a split is expected work-in-progress, not stale bookkeeping. Do not flag it as drift or "skipped discovery" — revalidating inherited context is the next intended step.

Success Criteria

• Coordination parent exists and has no spec.md, design.md, plan.md, or implementation.md.
• Parent state.md records oat_kind: coordination, ordered oat_children, and terminal decomposition status.
• references/split-plan.json contains the full SplitPlanDocument.
• Every child state.md records oat_phase: discovery and oat_phase_status: in_progress so resume/progress/quick-start route it back to discovery.
• Every child has seeded discovery content, parent/sibling/dependency links, oat_inherited_context_revalidated: false, and an explicit revalidation gate; no child discovery is marked complete by the split.
• Every child plan.md is a not-started template placeholder (oat_template: true) that never reads as plan-ready.
• .oat/config.local.json.activeProject points at the repo-relative initial child path.