@open-agent-toolkit/cli 0.1.4 → 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/implementation-execution.md

@@ -53,7 +53,7 @@ Model and effort are separate axes. Each axis logs one of four states:
 - `not-applicable` — this host/API has no meaningful per-dispatch concept for that axis.
 - `host-auto` — exceptional; the host uses that axis internally but the orchestrator cannot read or pin it.
 
-In Codex, the normal model choice is inherited unless the user requested a model override or the phase clearly requires one. Implementation dispatch maps selected `low`, `medium`, and `high` effort to configured Codex implementer roles (`oat-phase-implementer-low`, `oat-phase-implementer-medium`, and `oat-phase-implementer-high`) rather than relying on per-call effort overrides. The base `oat-phase-implementer` role represents inherited effort. `xhigh` is inherited-only: use it when the parent/orchestrator session is already xhigh, otherwise split/revise the phase or stop for user re-invocation instead of inventing an `xhigh` variant. In Claude Code, subagent model selection is a model axis when available; the separate effort axis is `not-applicable`.
+In Codex, the normal model choice is inherited unless the user requested a model override or the phase clearly requires one. Implementation and fix dispatch default to selected effort: classify the phase, choose the lowest sufficient `low`, `medium`, or `high`, and dispatch the matching configured Codex implementer role (`oat-phase-implementer-low`, `oat-phase-implementer-medium`, or `oat-phase-implementer-high`) rather than relying on per-call effort overrides. The base `oat-phase-implementer` role represents inherited effort, which is the parent-session ceiling path, not a neutral default. Use inherited effort only for an explicit user/Dispatch Profile override, when the phase needs the parent-session ceiling and `selected:high` is insufficient, or when selected-effort roles are unavailable. `xhigh` is inherited-only: use it when the parent/orchestrator session is already xhigh, otherwise split/revise the phase or stop for user re-invocation instead of inventing an `xhigh` variant. In Claude Code, subagent model selection is a model axis when available; the separate effort axis is `not-applicable`.
 
 Dispatch logs use a consistent structured block so provider behavior is comparable without flattening the model and effort axes:
 
@@ -100,7 +100,7 @@ Add Dispatch Profile rows only when the user has an explicit constraint or prefe
 For each phase in the plan (whether sequential or inside a parallel group):
 
 1. **Select runtime dispatch control** for the phase and log the chosen control plus rationale.
-2. **Dispatch the selected implementer role** with a Phase Scope block (project path, phase id, artifact paths, commit convention, workflow mode, and dispatch context when known). In Codex, `effort_axis=selected:low|medium|high` uses `oat-phase-implementer-low|medium|high`; inherited effort uses base `oat-phase-implementer`.
+2. **Dispatch the selected implementer role** with a Phase Scope block (project path, phase id, artifact paths, commit convention, workflow mode, and dispatch context when known). In Codex, `effort_axis=selected:low|medium|high` uses `oat-phase-implementer-low|medium|high`. Inherited effort uses base `oat-phase-implementer` only for an explicit ceiling/override/fallback reason; it should not be used just to avoid choosing a selected effort.
 3. **Receive the summary:** `DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
    - `BLOCKED` stops the run and surfaces the blocker to the user.
 4. **Dispatch `oat-reviewer`** with a Review Scope block (phase id, commit range, optional files-changed hint, and inherited review dispatch context). Review dispatches inherit the parent session's model and effort axes unless the user explicitly requested an override. The commit range is authoritative; the file list is only orientation metadata. In Codex, pass this as a self-contained packet with `fork_context: false`, use the base reviewer role without model or effort overrides, and record `model_axis=inherited, effort_axis=inherited` so the reviewer reads git/OAT artifacts directly instead of inheriting the orchestration thread. In Claude Code, do not pass a per-review model override and record `effort_axis=not-applicable` since Claude Code does not expose a per-dispatch effort axis. If the reviewer does not conclude on the first wait, poll once more, then send a concise "return now with current findings" nudge before falling back inline for that phase.

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.4",
-  "docs-config": "0.1.4",
-  "docs-theme": "0.1.4",
-  "docs-transforms": "0.1.4"
+  "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-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.15
+version: 2.0.16
 description: Use when plan.md is ready for execution. Dispatches phase-level subagents with bounded fix loops; supports plan-declared parallel phase groups with worktree-isolated execution and ordered fan-in.
 argument-hint: '[--retry-limit <N>] [--dry-run]'
 disable-model-invocation: true
@@ -180,7 +180,7 @@ Selection rule:
    - `inherited` — host exposes the axis and the orchestrator deliberately defers to the parent session.
    - `not-applicable` — this host/API has no meaningful per-dispatch concept for that axis.
    - `host-auto` — exceptional; the host uses that axis internally but the orchestrator cannot read or pin it.
-4. In Codex, the model axis normally logs `inherited`; choose `effort_axis=selected:low|medium|high` from phase complexity and dispatch the matching effort-specific implementer role. Use `effort_axis=inherited` for the base implementer role.
+4. In Codex implementation/fix dispatch, the model axis normally logs `inherited`; choose `effort_axis=selected:low|medium|high` from phase complexity and dispatch the matching effort-specific implementer role. Treat `effort_axis=inherited` as the parent-session ceiling path, not a neutral default.
 5. In Claude Code, when subagent model selection is available, choose the lowest sufficient model on the model axis; the effort axis is `not-applicable` because Claude Code does not expose a separate `reasoning_effort` control for subagent dispatch.
 6. If a host uses model/effort internally but exposes neither axis to the orchestrator, log `model_axis=host-auto, effort_axis=host-auto` and include the rationale that would have informed selection.
 7. If confidence is low, choose a stronger available control before dispatch rather than knowingly underpowering the phase.
@@ -190,7 +190,8 @@ Selection rule:
 **Passing axis values to the host dispatch API.** The log shape and the actual dispatch call must agree: never log a `selected:<value>` axis without passing the corresponding parameter on the dispatch invocation, and never pass an explicit parameter that the log does not reflect.
 
 - **Claude Code implementer/fix dispatch:** when `model_axis=selected:<value>`, pass `model: "<value>"` on the Task tool call. When `model_axis=inherited`, omit the `model` parameter so Claude Code uses its own default. `effort_axis=not-applicable` for both cases because the Task tool exposes no per-dispatch `reasoning_effort` control.
-- **Codex implementer/fix dispatch:** when `effort_axis=selected:low|medium|high`, dispatch the matching configured role: `agent_type: "oat-phase-implementer-low"`, `agent_type: "oat-phase-implementer-medium"`, or `agent_type: "oat-phase-implementer-high"`. Those roles set `model_reasoning_effort` in `.codex/agents/*.toml`. Use the base `agent_type: "oat-phase-implementer"` only for `effort_axis=inherited`. Do not use top-level per-call `reasoning_effort` as the standard OAT selected-effort path; dogfooding showed that path can be inconsistent in some Codex runs.
+- **Codex implementer/fix dispatch:** default to a selected effort. Classify phase complexity, choose the lowest sufficient `effort_axis=selected:low|medium|high`, and dispatch the matching configured role: `agent_type: "oat-phase-implementer-low"`, `agent_type: "oat-phase-implementer-medium"`, or `agent_type: "oat-phase-implementer-high"`. Those roles set `model_reasoning_effort` in `.codex/agents/*.toml`. Use the base `agent_type: "oat-phase-implementer"` only when `effort_axis=inherited` is intentionally selected for an allowed reason below. Do not use top-level per-call `reasoning_effort` as the standard OAT selected-effort path; dogfooding showed that path can be inconsistent in some Codex runs.
+- **Codex inherited effort is the ceiling path:** because inherited effort follows the parent/orchestrator session and may be `xhigh`, do not use `effort_axis=inherited` merely because it is valid, convenient, or avoids choosing a selected effort. Use inherited effort for Codex implementer/fix dispatch only when the user explicitly requested inherited/default parent controls; a valid Dispatch Profile row explicitly requests inherited/default controls; the phase requires the parent-session ceiling and `selected:high` is insufficient; or the selected-effort roles are unavailable or fail to resolve. The dispatch rationale must cite the allowed reason. For ceiling-needed dispatch, explain why `selected:high` is insufficient.
 - **Codex xhigh:** do not create or select an `xhigh` implementer variant. Use `xhigh` only when the parent/orchestrator session is already xhigh and therefore `effort_axis=inherited` on the base role is the correct representation. If a phase appears to require xhigh while the parent is not xhigh, choose `selected:high` only if high is sufficient; otherwise split/revise the phase or stop for user re-invocation at xhigh.
 - **Claude Code `opus`:** unlike Codex `xhigh`, `opus` is directly selectable. Claude Code exposes `opus` through the Task tool's `model` parameter, so OAT may select it when available (`model_axis=selected:opus`) — including as a terminal escalation step. There is no `opus` inherited-only restriction; the `xhigh` rule above is specific to Codex's effort-variant mechanism, not a general "never select the maximum tier" rule.
 - **Reviewer dispatch on either host:** use `model_axis=inherited` by default. For `effort_axis`: use `inherited` on hosts that expose an effort axis (such as Codex); use `not-applicable` on hosts that do not expose a meaningful effort axis (such as Claude Code). Omit `model` and, on Codex, `reasoning_effort` overrides entirely.
@@ -231,6 +232,8 @@ Dispatch target: {host-specific subagent/role/tool target}
 Rationale: {short rationale grounded in phase scope}
 ```
 
+For Codex implementation/fix dispatches, the rationale must include the phase complexity class that drove the selected effort (for example, mechanical, normal multi-file, or broad/high-risk). If `Effort axis: inherited`, the rationale must also cite the allowed reason for using the parent-session ceiling instead of `selected:low|medium|high`.
+
 Examples:
 
 ```text
@@ -563,10 +566,11 @@ For each phase `pNN` in the plan (or each phase in the current parallel group),
 
 2. Perform a pre-dispatch assertion against the host invocation parameters. The Phase Scope fields are audit/context fields; selected axes must also be represented in the actual host dispatch call.
    - Codex implementer/fix dispatch:
+     - Before building the `spawn_agent` argument map, classify the phase complexity and choose the lowest sufficient selected effort (`low`, `medium`, or `high`) when the matching effort-specific role is available.
      - Build the `spawn_agent` argument map before logging the dispatch. If `effort_axis=selected:low|medium|high`, the argument map MUST use the matching `agent_type`: `"oat-phase-implementer-low"`, `"oat-phase-implementer-medium"`, or `"oat-phase-implementer-high"`. Then derive the `OAT Dispatch:` block `Effort axis:` field from that same argument map.
      - Example selected low payload shape: `agent_type: "oat-phase-implementer-low"` and a Phase Scope message containing `effort_axis: selected:low`.
      - Immediately after spawning, compare the returned Codex status line with the selected effort before waiting on the agent. If the spawned status reports a different effort than the selected value (for example, the log says `effort_axis=selected:medium` but the spawn result reports `gpt-5.5 high`), treat this as an orchestration deviation. Stop, record the deviation in `implementation.md`, and redispatch with corrected parameters before continuing. Do not use work from the mismatched dispatch.
-     - If `effort_axis=inherited`, use base `agent_type: "oat-phase-implementer"` and omit `reasoning_effort`.
+     - If `effort_axis=inherited`, use base `agent_type: "oat-phase-implementer"` and omit `reasoning_effort`. This is the parent-session ceiling path, so the dispatch rationale MUST cite the explicit user/Dispatch Profile override, explain why `selected:high` is insufficient, or record that the selected-effort roles are unavailable or failed to resolve.
    - Claude Code implementer/fix dispatch:
      - If `model_axis=selected:<value>`, the Task tool call MUST include `model: "<value>"`.
      - If `model_axis=inherited`, omit `model`.

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