@open-agent-toolkit/cli 0.1.5 → 0.1.6

package/assets/docs/workflows/projects/artifacts.md

@@ -29,11 +29,28 @@ Mode-sensitive notes:
 - `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](splitting.md) for the full parent/child model.
+
 ### plan.md frontmatter
 
 `plan.md` carries frontmatter that the implementation skill consumes. Notable fields:

package/assets/docs/workflows/projects/index.md

@@ -17,12 +17,14 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 
 - Start with [Lifecycle](lifecycle.md) for the end-to-end flow.
 - Read [Artifacts](artifacts.md) once you need the file contract behind project execution.
+- Use [Project Splitting](splitting.md) when one discovery or brainstorm should become coordinated child projects.
 - Use [HiLL Checkpoints](hill-checkpoints.md) when you want to understand pause/approval behavior.
 
 ## Common Tasks
 
 - Understand lifecycle order and alternate lanes in [Lifecycle](lifecycle.md).
 - Learn the artifact system of record in [Artifacts](artifacts.md).
+- Split broad scopes into coordination parents and focused children in [Project Splitting](splitting.md).
 - Understand lifecycle and review transitions in [State Machine](state-machine.md).
 - Learn review and PR expectations in [Reviews](reviews.md) and [PR Flow](pr-flow.md).
 
@@ -32,6 +34,7 @@ This sub-section is the deep technical surface for how tracked OAT projects exec
 - [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
 - [HiLL Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
 - [Artifacts](artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
+- [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.
 - [State Machine](state-machine.md) - Lifecycle and review status transitions across a project.
 - [Reviews](reviews.md) - How review request/receive loops work inside OAT projects.
 - [PR Flow](pr-flow.md) - Progress and final PR generation expectations.

package/assets/docs/workflows/projects/splitting.md

@@ -0,0 +1,79 @@
+---
+title: Project Splitting
+description: 'How OAT splits broad discoveries or brainstorms into a coordination parent and focused child projects.'
+---
+
+# Project Splitting
+
+Use project splitting when one discovery or brainstorming thread turns into several independently shippable projects that should keep shared context but execute separately.
+
+`oat-project-split` is the handoff skill for that moment. It creates a durable coordination parent, scaffolds flat sibling child projects, seeds each child with focused discovery context, and activates the first child by dependency or value order.
+
+## When To Split
+
+Split when the work has multiple deliverables that can ship independently, no single shared design surface owns all of them, separate PRs are expected, or the scope clearly spans distinct subsystems.
+
+Do not split just because a project has many tasks. A large but coherent implementation can stay one project when it has one design surface and one release boundary.
+
+## Entry Paths
+
+Splitting can start from either discovery or brainstorming:
+
+- **Declared:** the user states multi-project intent up front. `oat-brainstorm` skips detection and hands off to `oat-project-split`.
+- **Detected mid-stream:** `oat-project-discover` evaluates codified split signals during solution-space exploration and prompts when the threshold is crossed.
+- **Detected at convergence:** `oat-project-discover` performs an end-of-discovery scope check, and `oat-brainstorm` can expose a split destination when the accumulated scope is large.
+
+Declared non-interactive runs can proceed. Detected non-interactive runs record the split recommendation and fail fast rather than silently creating projects.
+
+## Coordination Parent
+
+The parent becomes a coordination artifact, not an implementation project.
+
+It stays in place under `.oat/projects/<scope>/<parent>/` with:
+
+- `oat_kind: coordination`
+- `oat_phase: decomposition`
+- `oat_phase_status: complete`
+- broad context, split rationale, shared constraints, child registry, and integration sketch
+- `references/split-plan.json` as the durable resume source
+
+Coordination parents do not keep executable phase artifacts. They should not contain `spec.md`, `design.md`, `plan.md`, or `implementation.md`.
+
+## Child Projects
+
+Children are flat sibling projects under the same projects root. They are not nested under the parent.
+
+Each child gets:
+
+- parent backlink and sibling links in `state.md`
+- `depends-on` metadata when ordering or dependency constraints exist
+- a seeded `discovery.md` with Origin, Inherited Context, Child Scope, Known Dependencies, Assumptions To Revalidate, Likely Workflow Mode, and Sibling Projects
+- `oat_inherited_context_revalidated: false` until the child revalidates inherited assumptions
+
+Only one child is activated immediately. The rest remain parked until opened or resumed.
+
+## Resume And Recovery
+
+The split plan is persisted before child writes. If a split is interrupted, resume reads `references/split-plan.json` from the coordination parent instead of reconstructing child inputs from state.
+
+Resume requires explicit confirmation and seeds only missing child projects.
+
+## Listing And Dashboard Behavior
+
+Completed coordination parents are hidden from default `oat project list` output so normal project lists stay focused on executable work.
+
+Use:
+
+```bash
+oat project list --include-coordination
+```
+
+to show them. Completed coordination parents render as `decomposition (complete)` with recommendation `none`.
+
+`oat state refresh` also groups completed coordination parents under the repo dashboard's decompositions section.
+
+## Related Pages
+
+- [Lifecycle](lifecycle.md)
+- [Artifacts](artifacts.md)
+- [Implementation Execution](implementation-execution.md)

package/assets/docs/workflows/skills/index.md

@@ -18,6 +18,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Resume an existing project: `oat-project-open` and `oat-project-progress`
 - Execute a ready plan: `oat-project-implement`
 - Import an existing plan: `oat-project-import-plan`
+- Split a broad discovery or brainstorm into child projects: `oat-project-split`
 - Retroactively capture existing work: `oat-project-capture`
 - Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
@@ -53,6 +54,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-project-design`
     - `oat-project-plan`
     - `oat-project-plan-writing`
+    - `oat-project-split`
     - `oat-project-implement`
     - `oat-project-progress`
     - `oat-project-next`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.5",
-  "docs-config": "0.1.5",
-  "docs-theme": "0.1.5",
-  "docs-transforms": "0.1.5"
+  "cli": "0.1.6",
+  "docs-config": "0.1.6",
+  "docs-theme": "0.1.6",
+  "docs-transforms": "0.1.6"
 }

package/assets/skills/oat-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-brainstorm
-version: 1.0.2
+version: 1.0.4
 description: Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
 disable-model-invocation: false
 user-invocable: true
@@ -29,6 +29,21 @@ Enter OAT brainstorm mode immediately when the user invokes `/oat-brainstorm` or
 
 Hard Activation runs the full Process flow below: print the mode banner (Step 2), assess visual need (Step 3), detect packs and active project (Step 4), and proceed.
 
+### Declared Multi-Project Mode
+
+If the opening request explicitly says the scope is multiple projects, several sub-projects, an umbrella project, or otherwise declares decomposition intent, still enter brainstorm mode through Hard Activation, but switch the conversation shape immediately to umbrella framing. This is a first-class split path, not an ordinary destination guess.
+
+Do not treat ambiguous exploratory phrasing as declared mode. Put another way: do not treat ambiguous exploratory phrasing as declared mode. Messages like "help me think through a broad thing", "what if this has multiple parts", or "this might get big" remain on the Soft Exploratory Path unless the user explicitly declares that the desired outcome is multiple projects.
+
+In declared mode, ask this boundary question before ordinary free brainstorming:
+
+> "Do you already know the child projects, or should we decompose the scope together?"
+
+- If the user already knows the children, capture light parent-level context: shared context, child list, dependencies, sequencing, and integration risks.
+- If the children are unknown, brainstorm the boundaries first until a child list is clear.
+
+Once the child list is clear, invoke `oat-project-split` with a `SplitPayload` using `origin: "declared"`, `interactive: true`, `declaredChildren`, and the parent/umbrella slug when known. The brainstorm hook only frames and hands off; `oat-project-split` owns normalization, parent writing, child scaffolding, and activation.
+
 ### Soft Exploratory Path
 
 Do **not** print the banner, assert mode, run pack detection, or offer the visual companion on the first response. Answer normally with brainstorm-quality structure (options, tradeoffs, open questions, no premature implementation, no destination guess). Examples:
@@ -278,7 +293,21 @@ If "keep going", return to step 5. If "wrap up", surface the **pack-filtered ter
    - Gated by `PJM_INSTALLED == "true"`: `Scoped backlog item`.
    - Gated by `WORKFLOWS_INSTALLED == "true"` AND `ACTIVE_PROJECT_VALID != "true"`: `Promote to new OAT project`.
    - Gated by `WORKFLOWS_INSTALLED == "true"` AND `ACTIVE_PROJECT_VALID == "true"`: `Active project: fold-back` and `Active project: brainstorming reference file`. When this branch fires, present the **3-way active-project router first** (see step 9 active-project branches) — its outcome controls whether the rest of the picker is even surfaced.
-3. Present the filtered list to the user. Wait for selection.
+3. Evaluate whether the accumulated brainstorm scope is large enough to offer a split destination. Track the same four split signals used by discovery and evaluate them through the installed CLI:
+
+   ```bash
+   oat project split evaluate-signals --fired "<comma-list>"
+   ```
+
+   Use the local-development fallback only when the installed `oat` command is unavailable:
+
+   ```bash
+   pnpm run cli -- project split evaluate-signals --fired "<comma-list>"
+   ```
+
+   If the JSON result has `triggered: true`, add `Promote to N projects` to the picker. Below 2 split signals, do not show this option.
+
+4. Present the filtered list to the user. Wait for selection.
 
 Once a destination is identified (either path), proceed to step 7.
 
@@ -581,6 +610,16 @@ git commit -m "chore(oat): capture brainstorming reference for <project-name>"
 
 Use only `git add -- <path>` so unrelated working-tree changes are not swept into the commit. After the commit succeeds, capture the short hash via `git rev-parse --short HEAD` and report it alongside the absolute path written (for example: "Wrote `<absolute-path>` and committed as `<hash>`."). End mode assertion.
 
+#### 9k — Promote to N projects
+
+This branch is available only when the step 6 picker added `Promote to N projects` after `oat project split evaluate-signals` returned `triggered: true`.
+
+Confirm the parent/umbrella slug and the inferred child list at step 8 using the minimal confirmation pattern. If the child list is still unclear, ask one boundary question and return briefly to step 5 to decompose the scope.
+
+When confirmed, invoke `oat-project-split` with a `SplitPayload` using `origin: "brainstorm-picker"`, `interactive: true`, `inferredChildren`, the parent/umbrella slug when known, and the brainstorm session note as inherited parent context. The brainstorm hook does not create project directories itself; `oat-project-split` owns normalization, `SplitPlanDocument` validation, coordination-parent writing, child seeding, activation, and dashboard refresh.
+
+End mode assertion when the split handoff completes or reports its own blocker.
+
 ## Success Criteria
 
 - ✅ Activation Contract is honored: Hard Activation fires only on explicit brainstorm-verb phrasing or `/oat-brainstorm`; Soft Exploratory Path messages ("help me think through", "I've been thinking about", "what if we") respond conversationally without the banner and offer mode only after ≥2 sustained exploratory turns; No Activation Path messages (advisory / review / debug / PR / status / implementation / active-workflow) get a direct response with no banner and no offer.
@@ -590,9 +629,10 @@ Use only `git add -- <path>` so unrelated working-tree changes are not swept int
 - ✅ Pack and active-project detection (`oat config get tools.<pack>` and `oat config get activeProject`) runs once per session at step 4, before the conversation starts.
 - ✅ Conversation cadence holds the Superpowers contract: one question at a time, multiple-choice preferred, 2-3 distinct approaches with a recommendation, per-question visual-companion routing.
 - ✅ Destination is identified via either trigger-phrase opportunistic surfacing (loose substring + paraphrase tolerance, not regex; ambiguity → ask) or convergence cue (pack-filtered terminal-state picker).
+- ✅ The terminal-state picker conditionally includes `Promote to N projects` only when `oat project split evaluate-signals` reports `triggered: true`; small-scope convergence keeps the option hidden.
 - ✅ Synthesis payload is built per the design Data Models `SynthesizedPayload` schema: `title`, `summary`, `motivation`, `vision`, `approachesConsidered[]`, `chosenDirection`, `openQuestions[]`, `nextSteps[]`, `transcriptSessionNote`.
 - ✅ Confirmation pattern matches `references/destinations.md`: `full` for scoped backlog item (field-by-field with example wording), `minimal` for slug/path/artifact destinations, `none` for inline-only and summarize-idea-directly.
-- ✅ Each handoff branch (9a-9j) reads the correct downstream `SKILL.md` path and enters at the documented step. Project promotion writes `discovery.md` only — never `design.md` — and does not auto-chain into the next phase.
+- ✅ Each handoff branch (9a-9k) reads the correct downstream `SKILL.md` path and enters at the documented step. Project promotion writes `discovery.md` only — never `design.md` — and does not auto-chain into the next phase.
 - ✅ Doc-to-path validation handles all four cases: path-is-directory, parent-missing (with explicit out-of-repo confirmation), file-already-exists (overwrite or rename), unwritable (surface OS error).
 - ✅ Fold-back commit safety contract honored: preflight `git status --porcelain -- "$ARTIFACT_PATH"` runs before any artifact mutation; clean → append + `git add -- "$ARTIFACT_PATH"` (explicit `--`, never `-A`, never globs) + scoped commit; dirty → three-option picker (commit-prior-first / mix / abort-to-reference-file); handoff prompt prints only after `git commit` succeeds.
 - ✅ Handoff target for fold-back resolves correctly per `oat_workflow_mode` + `oat_pr_status`: `oat-project-plan` (spec-driven, no/closed PR) / `oat-project-quick-start` (quick, no/closed PR) / `oat-project-revise` (either mode, open PR).

package/assets/skills/oat-project-discover/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: oat-project-discover
-version: 2.0.0
+version: 2.0.2
 description: Use when starting a project or when requirements are still unclear. Runs structured discovery to gather requirements, constraints, and context.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Glob, Grep, AskUserQuestion
 ---
 
 # Discovery Phase
@@ -262,6 +262,59 @@ This focuses the conversation on what matters most to the user.
 
 Before converging on an approach, invest in genuine divergent exploration. Simple projects are where unexamined assumptions cause the most wasted work.
 
+**Step 9 Split Detection: Evaluate Multi-Project Signals**
+
+During solution-space exploration, silently evaluate whether the current thread is really multiple loosely related projects. Re-evaluate after each user turn while approaches are being shaped; do not interrupt normal discovery unless the threshold is met.
+
+Track the four codified signals:
+
+1. `independently-shippable` — at least two deliverables can ship independently.
+2. `no-shared-design-surface` — the work lacks a single shared design surface.
+3. `expect-separate-prs` — a reviewer would reasonably expect separate PRs.
+4. `distinct-subsystems` — the work spans distinct subsystems, packages, layers, or ownership areas.
+
+Evaluate the current comma-separated signal list through the installed CLI:
+
+```bash
+oat project split evaluate-signals --fired "<comma-list>"
+```
+
+Use the local-development fallback only when the installed `oat` command is unavailable:
+
+```bash
+pnpm run cli -- project split evaluate-signals --fired "<comma-list>"
+```
+
+Parse the JSON output:
+
+```json
+{ "fired": [], "triggered": false, "confidence": "below" }
+```
+
+Branch on `confidence`:
+
+- `high` — both load-bearing signals 1 and 2 fired. Use high-confidence wording and ask directly: "This looks like multiple independent projects. Split now, do one round of broad cross-cutting discovery first, or keep this as one project?"
+- `soft` — at least two signals fired, but not both load-bearing signals. Use soft wording: "This may be multiple projects. Split, do one round of broad cross-cutting discovery first, or keep it as one project?"
+- `below` — Below 2 signals, do not surface a split offer.
+
+If the user confirms split, invoke the `oat-project-split` skill with a `SplitPayload` using `origin: "detected-mid-stream"`, `interactive: true`, the active discovery path as `priorDiscovery.path`, and any inferred children already named in the conversation. The discover hook only detects and hands off; it does not scaffold children or write the coordination parent itself.
+
+**Non-interactive branch:** if `OAT_NON_INTERACTIVE=1` and detection triggers (`confidence` is `high` or `soft`), do not show an offer prompt and do not silently choose. Append this section to `"$PROJECT_PATH/discovery.md"` and exit non-zero:
+
+```markdown
+## Detected Split Recommendation
+
+Discovery detected multi-project scope via `oat project split evaluate-signals`.
+
+- Fired signals: <comma-list>
+- Confidence: <high|soft>
+- Recommendation: rerun discovery interactively and choose whether to invoke `oat-project-split`.
+```
+
+```bash
+exit 1
+```
+
 **Step 9a: Propose Approaches**
 
 Propose 2-3 **genuinely distinct** approaches (not minor variations). For each:
@@ -313,6 +366,19 @@ Update discovery.md sections:
 
 ### Step 11: Human-in-the-Loop Lifecycle (HiLL) Gate (If Configured)
 
+Before the HiLL gate or discovery completion, run the same split signal evaluation one final time.
+
+**Non-interactive convergence branch:** if `OAT_NON_INTERACTIVE=1`, do not show the scope-check prompt and do not silently choose. Parse the final `oat project split evaluate-signals --fired "<comma-list>"` result:
+
+- `high` or `soft` — append the same section to `"$PROJECT_PATH/discovery.md"` as the Step 9 non-interactive branch, using the final fired signal list and confidence, then exit non-zero.
+- `below` — proceed as one cohesive project without prompting.
+
+For interactive runs, show an always-visible scope-check confirmation. The prompt is required even when no mid-stream offer fired:
+
+> "This reads as one cohesive project — proceed, or split into multiple?"
+
+Pre-fill the recommendation from `oat project split evaluate-signals --fired "<comma-list>"`: recommend splitting for `high`, suggest considering a split for `soft`, and recommend proceeding as one cohesive project for `below`. If the user chooses split at this convergence point, invoke `oat-project-split` with `origin: "detected-convergence"` and `interactive: true`.
+
 Read `"$PROJECT_PATH/state.md"` frontmatter:
 
 - `oat_hill_checkpoints`
@@ -342,13 +408,11 @@ If discovery is not configured as a HiLL checkpoint, or user explicitly approves
 
 ### Step 12: Mark Discovery Complete
 
-Update frontmatter:
+Use the CLI completion boundary so split-created child discoveries cannot
+complete until inherited context has been revalidated:
 
-```yaml
----
-oat_status: complete
-oat_ready_for: oat-project-design
----
+```bash
+oat project complete-discovery "$PROJECT_PATH" --ready-for oat-project-design
 ```
 
 ### Step 13: Update Project State

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 2.1.0
+version: 2.1.1
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name> ["project description"]'
 disable-model-invocation: true
@@ -211,10 +211,12 @@ Use `AskUserQuestion` to present this choice.
 
 **If user chooses "Promote to spec-driven":**
 
-- Update `discovery.md` frontmatter:
-  - `oat_status: complete`
-  - `oat_ready_for: oat-project-design`
-  - `oat_last_updated: {today}`
+- Complete discovery through the CLI validation boundary:
+
+```bash
+oat project complete-discovery "$PROJECT_PATH" --ready-for oat-project-design
+```
+
 - Update `state.md`:
   - `oat_workflow_mode: spec-driven`
   - `oat_phase: discovery`
@@ -287,6 +289,13 @@ fi
 # Route the user accordingly. Do NOT loop back into the gate.
 ```
 
+Before continuing to Step 3, complete discovery through the CLI validation
+boundary:
+
+```bash
+oat project complete-discovery "$PROJECT_PATH" --ready-for oat-project-quick-start
+```
+
 ### Step 2.75a: Lightweight Design Mode Choice
 
 Resolve the interaction mode before drafting. Same mechanics as the full `oat-project-design` skill (Component 1): argument precedes env var, config fallback, **explicit** non-interactive fallback to draft.

package/assets/skills/oat-project-split/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: oat-project-split
+version: 1.0.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:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+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:
+
+```bash
+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.
+
+## 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 has seeded discovery content, parent/sibling/dependency links, and `oat_inherited_context_revalidated: false`.
+- `.oat/config.local.json.activeProject` points at the repo-relative initial child path.

package/assets/templates/state.md

@@ -3,10 +3,15 @@ oat_current_task: null
 oat_last_commit: null
 oat_blockers: []
 associated_issues: [] # [{type: backlog|project|jira|linear, ref: "identifier"}]
+oat_kind: implementation # implementation | coordination; coordination parents may use oat_phase: decomposition
+oat_parent: null # optional child-only coordination parent slug
+oat_siblings: [] # optional child-only sibling slugs
+oat_depends_on: [] # optional child-only sibling dependencies
+oat_children: [] # optional coordination-parent child slugs
 oat_hill_checkpoints: { OAT_HILL_CHECKPOINTS } # Configured: which phases require human-in-the-loop lifecycle approval
 oat_hill_completed: [] # Progress: which HiLL checkpoints have been completed
 oat_parallel_execution: false
-oat_phase: { OAT_PHASE } # Current phase: discovery | spec | design | plan | implement
+oat_phase: { OAT_PHASE } # Current phase: discovery | spec | design | plan | implement | decomposition
 oat_phase_status: in_progress # Status: in_progress | complete | pr_open
 # oat_orchestration_retry_limit: 2  # optional; override fix-loop retry limit (range 0-5)
 oat_workflow_mode: { OAT_WORKFLOW_MODE } # spec-driven | quick | import

package/dist/__tests__/skills/split-flow-fixtures.d.ts

@@ -0,0 +1,50 @@
+import { type SplitChildInput, type SplitPayload, type SplitPlanDocument } from '../../projects/split/child-plan.js';
+import { type Signal } from '../../projects/split/signals.js';
+export type TranscriptSpeaker = 'assistant' | 'user';
+export interface TranscriptTurn {
+    speaker: TranscriptSpeaker;
+    text: string;
+}
+export type StubbedUserChoice = 'broad-first' | 'children-known' | 'decompose-children' | 'inline-only' | 'keep-one-project' | 'promote-n-projects' | 'split-now';
+export interface StubbedQuestion {
+    id: string;
+    prompt: string;
+    options: string[];
+    response: StubbedUserChoice;
+}
+export interface TranscriptFixture {
+    transcript: TranscriptTurn[];
+    parentSlug: string;
+    children: SplitChildInput[];
+    discoveryPath?: string;
+    inheritedContext?: string;
+    integrationSketch?: string;
+}
+export declare const SPLIT_HANDOFF_TARGET: {
+    readonly skill: "oat-project-split";
+    readonly hookCreatesProjects: false;
+    readonly responsibilities: readonly ["normalize-split-plan", "write-coordination-parent", "scaffold-children", "activate-initial-child"];
+};
+export declare function inferSplitSignals(transcript: TranscriptTurn[]): Signal[];
+export declare function runDiscoverDetectionFixture(fixture: TranscriptFixture, responses: Record<string, StubbedUserChoice>): {
+    asked: StubbedQuestion[];
+    confidence: 'below' | 'high' | 'soft';
+    decision?: StubbedUserChoice;
+    document?: SplitPlanDocument;
+    payload?: SplitPayload;
+    triggered: boolean;
+};
+export declare function runDeclaredBrainstormFixture(fixture: TranscriptFixture, responses: Record<string, StubbedUserChoice>): {
+    asked: StubbedQuestion[];
+    document?: SplitPlanDocument;
+    handoffTarget: typeof SPLIT_HANDOFF_TARGET;
+    payload?: SplitPayload;
+};
+export declare function runBrainstormPickerFixture(fixture: TranscriptFixture, responses: Record<string, StubbedUserChoice>): {
+    asked: StubbedQuestion[];
+    document?: SplitPlanDocument;
+    handoffTarget: typeof SPLIT_HANDOFF_TARGET;
+    options: string[];
+    payload?: SplitPayload;
+};
+//# sourceMappingURL=split-flow-fixtures.d.ts.map

package/dist/__tests__/skills/split-flow-fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"split-flow-fixtures.d.ts","sourceRoot":"","sources":["../../../src/__tests__/skills/split-flow-fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,gBAAgB,GAChB,oBAAoB,GACpB,aAAa,GACb,kBAAkB,GAClB,oBAAoB,GACpB,WAAW,CAAC;AAEhB,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,eAAO,MAAM,oBAAoB;;;;CASvB,CAAC;AAsBX,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CA+BxE;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAC3C;IACD,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACtC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB,CAqDA;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAC3C;IACD,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,aAAa,EAAE,OAAO,oBAAoB,CAAC;IAC3C,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB,CAmCA;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAC3C;IACD,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,aAAa,EAAE,OAAO,oBAAoB,CAAC;IAC3C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB,CA4CA"}