@open-agent-toolkit/cli 0.3.13 → 0.3.15

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

@@ -23,7 +23,9 @@ OAT lifecycle order:
 
 **Shortcut:** `oat-project-next` reads project state and invokes the correct next skill automatically — use it instead of remembering which skill comes next. Complements `oat-project-progress` (which is read-only diagnostic).
 
-Full spec-driven design supports three interaction modes: collaborative, selective collaborative, and draft-and-review. Selective collaborative drafts routine sections silently and presents high-risk or uncertain sections for live review. Quick-start lightweight design stays simpler and offers only collaborative or draft-and-review. See [Design Modes](design-modes.md) for details.
+Full spec-driven design supports three interaction modes: collaborative, selective collaborative, and draft-and-review. Selective collaborative drafts routine sections silently and presents high-risk or uncertain sections for live review. Quick-start lightweight design stays simpler and offers only collaborative or draft-and-review. See [Design Modes](planning/design-modes.md) for details.
+
+For a one-page view of where people approve and what runs automatically in each mode, see [Approvals and Automation](../approvals-and-automation.md).
 
 ## Quick Look
 
@@ -33,14 +35,21 @@ Full spec-driven design supports three interaction modes: collaborative, selecti
 
 ## Lifecycle Map
 
-```mermaid
-flowchart LR
-  D["Discovery"] --> S["Spec"] --> G["Design"] --> P["Plan"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Review loop"] --> PR["PR flow"]
-  PR --> DOC["Docs sync (optional)"]
-  DOC --> C["Complete"]
-```
+=== "Diagram"
+
+    ![Project lifecycle map: discovery, spec, design, plan, implement, review loop, PR flow, optional docs sync, complete](/diagrams/project-lifecycle-1-lifecycle-map-light.svg)
+    ![Project lifecycle map: discovery, spec, design, plan, implement, review loop, PR flow, optional docs sync, complete](/diagrams/project-lifecycle-1-lifecycle-map-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      D["Discovery"] --> S["Spec"] --> G["Design"] --> P["Plan"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Review loop"] --> PR["PR flow"]
+      PR --> DOC["Docs sync (optional)"]
+      DOC --> C["Complete"]
+    ```
 
 This map shows the spec-driven default. The quick, lite, import, and capture
 lanes each skip part of it — see [Lane diagrams](#lane-diagrams) below. Lite in
@@ -126,7 +135,7 @@ On completion, OAT treats archive handling as an explicit closeout choice:
   pointer immediately, as does any completion that declines archive. An archive
   failure therefore leaves the pointer intact and the completion directly
   resumable. See
-  [Picking Up a Project](picking-up-projects.md#archive-contents) for the
+  [Picking Up a Project](execution/picking-up-projects.md#archive-contents) for the
   post-archive resume and its manual recovery path.
 - When archiving is disabled or declined, durable projects remain at their
   active path. Synced completion still finalizes and pushes the project ref,
@@ -144,7 +153,7 @@ On completion, OAT treats archive handling as an explicit closeout choice:
   valid terminal shapes. The active alias is inert: list omits it and pull/open
   reject it. Differing SHAs are a hard mismatch with recovery guidance.
 - If `.oat/config.json` enables `archive.s3SyncOnComplete` and sets `archive.s3Uri`, completion requires the S3 upload of a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/` to succeed before terminal record/ref cleanup. A failed configured upload leaves retry identity intact and does not claim closeout.
-- If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../cli-utilities/config-and-local-state.md) for the full precedence chain.
+- If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../reference/config-and-local-state.md) for the full precedence chain.
 - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
 - Missing or unusable AWS CLI configuration blocks synced terminal cleanup when S3 durability is configured; when S3 sync is not configured, it is not part of the durability requirement.
 - `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
@@ -225,6 +234,8 @@ This distinction matters during completion: `oat-project-complete` can skip the
 
 ### Auto-review at HiLL checkpoints
 
+When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (low findings auto-converted to fix tasks, no user prompts). The preference is unset by default; interactive implementation asks with "no" suggested, while autonomous non-lite implementation forces it on. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
+
 ### Approval-aware post-implementation sequencing
 
 `workflow.postImplementSequence` can use the legacy string values or a structured
@@ -264,8 +275,6 @@ registers. Non-interactive completion skips this offer, so autonomous
 generation occurs only through an explicitly configured post-approval `retro`
 step.
 
-When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (low findings auto-converted to fix tasks, no user prompts). Disabled by default. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
-
 ### Phase-review setup during planning
 
 Spec-driven, quick, and import planning run one shared setup after stable phase
@@ -302,7 +311,7 @@ Within either tier, parallelism is expressed as plan metadata:
 - **Sequential (default):** plans with no `oat_plan_parallel_groups` field, or with an empty array. Phases run in plan order on the orchestration branch.
 - **Parallel groups:** phases listed together in `oat_plan_parallel_groups` run concurrently in worktrees (Tier 1 only) and merge back to the orchestration branch in plan order. Groups themselves execute sequentially.
 
-See [Implementation Execution](implementation-execution.md) for the full execution model — tier detection, bounded fix loop, fan-in, merge-conflict handling, dry-run, and resumption.
+See [Implementation Execution](execution/implementation-execution.md) for the full execution model — tier detection, bounded fix loop, fan-in, merge-conflict handling, dry-run, and resumption.
 
 ## Review receive behavior
 
@@ -312,7 +321,7 @@ See [Implementation Execution](implementation-execution.md) for the full executi
 
 ## Alternate lifecycle lanes
 
-### Quick lane diagram
+### Quick lane steps
 
 1. `oat-project-quick-start` (adaptive discovery — provide a project name and optional description; if only the name is provided, quick-start asks for the missing description before discovery. Well-understood requests synthesize quickly, exploratory requests invest in solution space exploration. Before scaffolding, the skill checks inherited git state and asks whether to commit, proceed, or abort when the worktree is already dirty.)
 2. Decision point: straight to plan, optional lightweight `design.md`, or promote to spec-driven
@@ -320,14 +329,14 @@ See [Implementation Execution](implementation-execution.md) for the full executi
 4. `oat-project-review-provide` / `oat-project-pr-final`
 5. Optional `oat-project-promote-spec-driven` to backfill spec-driven lifecycle artifacts in-place
 
-### Lite lane diagram
+### Lite lane steps
 
 1. `oat-project-lite` runs one batched interview, authors a single-phase `plan.md` with validation criteria, and pauses once for approval
 2. Implement: `oat-project-implement` runs the single phase without HiLL checkpoint prompts
 3. Pass the mandatory final review, then route directly to `oat-project-pr-final`
 4. Optional `oat project promote <project-path> --to quick` when the work no longer fits one sitting
 
-### Import lane diagram
+### Import lane steps
 
 1. `oat-project-import-plan` (checks inherited git state before import scaffolding so sync-generated or unrelated dirty files do not silently roll into project bookkeeping)
 2. Implement: `oat-project-implement` (sequential by default; parallel when `oat_plan_parallel_groups` is declared)
@@ -338,12 +347,19 @@ See [Implementation Execution](implementation-execution.md) for the full executi
 
 ### Spec-Driven workflow lane
 
-```mermaid
-flowchart LR
-  D["Discover"] --> S["Spec"] --> G["Design"] --> P["Plan"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Review"] --> PR["PR"] --> Doc["Docs (optional)"] --> C["Complete"]
-```
+=== "Diagram"
+
+    ![Spec-driven lane: discover, spec, design, plan, implement, review, PR, optional docs, complete](/diagrams/project-lifecycle-2-spec-driven-light.svg)
+    ![Spec-driven lane: discover, spec, design, plan, implement, review, PR, optional docs, complete](/diagrams/project-lifecycle-2-spec-driven-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      D["Discover"] --> S["Spec"] --> G["Design"] --> P["Plan"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Review"] --> PR["PR"] --> Doc["Docs (optional)"] --> C["Complete"]
+    ```
 
 During the Design step, `oat-project-design` asks how to work through the document unless a mode was selected by argument, environment, or `workflow.designMode`. The three full-design choices are collaborative, selective collaborative, and draft-and-review.
 
@@ -363,15 +379,22 @@ effort controls.
 
 ### Quick lane
 
-```mermaid
-flowchart LR
-  Q["Quick Start\n(adaptive discovery)"] --> D{"Design depth?"}
-  D -->|Straight to plan| P["Plan"]
-  D -->|Lightweight design| LD["Design (quick)"] --> P
-  D -->|Promote| SD["→ Spec-Driven lane"]
-  P --> QI["Implement (oat-project-implement)"]
-  QI --> QR["Review / PR"]
-```
+=== "Diagram"
+
+    ![Quick lane: quick start with adaptive discovery, then a design-depth choice (straight to plan, lightweight design, or promote to spec-driven), plan, implement, review and PR](/diagrams/project-lifecycle-3-quick-lane-light.svg)
+    ![Quick lane: quick start with adaptive discovery, then a design-depth choice (straight to plan, lightweight design, or promote to spec-driven), plan, implement, review and PR](/diagrams/project-lifecycle-3-quick-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      Q["Quick Start\n(adaptive discovery)"] --> D{"Design depth?"}
+      D -->|Straight to plan| P["Plan"]
+      D -->|Lightweight design| LD["Design (quick)"] --> P
+      D -->|Promote| SD["→ Spec-Driven lane"]
+      P --> QI["Implement (oat-project-implement)"]
+      QI --> QR["Review / PR"]
+    ```
 
 Quick lane lightweight design intentionally keeps a smaller collaborative/draft choice. Selective collaborative becomes available only after promotion into the full spec-driven design lane.
 
@@ -384,13 +407,20 @@ should use the dispatch-policy names, including explicit `Uncapped` and
 
 ### Lite lane
 
-```mermaid
-flowchart LR
-  L["Lite interview\n(one batched round)"] --> P["Single-phase plan\n(one approval)"]
-  P --> I["Implement (oat-project-implement)"]
-  I --> R["Final review"] --> PR["PR (default closeout)"]
-  P -->|Scope grows| Q["Promote to Quick"]
-```
+=== "Diagram"
+
+    ![Lite lane: one batched interview, a single-phase plan with one approval, implement, final review and PR, with promotion to quick if scope grows](/diagrams/project-lifecycle-4-lite-lane-light.svg)
+    ![Lite lane: one batched interview, a single-phase plan with one approval, implement, final review and PR, with promotion to quick if scope grows](/diagrams/project-lifecycle-4-lite-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      L["Lite interview\n(one batched round)"] --> P["Single-phase plan\n(one approval)"]
+      P --> I["Implement (oat-project-implement)"]
+      I --> R["Final review"] --> PR["PR (default closeout)"]
+      P -->|Scope grows| Q["Promote to Quick"]
+    ```
 
 Lite keeps planning and validation in `plan.md`. The interview selects a
 `minimal`, `product`, `technical`, or `both` content shape and records the
@@ -418,29 +448,36 @@ from its five core sections plus any adaptive Product Behavior and Technical
 Design, a **fresh** quick template takes over the `plan.md` path, and `state.md`
 is **rewritten** to quick mode.
 
-```mermaid
-flowchart LR
-  subgraph Before
-    LPLAN["plan.md\nfive core sections plus adaptive\nProduct Behavior / Technical Design"]
-    LSTATE["state.md\noat_workflow_mode: lite"]
-  end
-
-  CMD["oat project promote\n--to quick"]
-
-  subgraph After
-    DISC["discovery.md\nderived from the lite plan\noat_ready_for: oat-project-quick-start"]
-    REF["references/lite-plan.md\noriginal lite plan, preserved"]
-    QPLAN["plan.md\nfresh quick-start template"]
-    QSTATE["state.md\noat_workflow_mode: quick\noat_phase: discovery (complete)\noat_ready_for: oat-project-quick-start"]
-  end
-
-  LPLAN --> CMD
-  LSTATE --> CMD
-  CMD -->|derive| DISC
-  CMD -->|move| REF
-  CMD -->|scaffold| QPLAN
-  CMD -->|rewrite| QSTATE
-```
+=== "Diagram"
+
+    ![Promoting a lite project to quick: oat project promote --to quick derives discovery.md from the lite plan, moves the original to references/lite-plan.md, scaffolds a fresh quick plan.md, and rewrites state.md to quick mode](/diagrams/project-lifecycle-5-promote-lite-to-quick-light.svg)
+    ![Promoting a lite project to quick: oat project promote --to quick derives discovery.md from the lite plan, moves the original to references/lite-plan.md, scaffolds a fresh quick plan.md, and rewrites state.md to quick mode](/diagrams/project-lifecycle-5-promote-lite-to-quick-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      subgraph Before
+        LPLAN["plan.md\nfive core sections plus adaptive\nProduct Behavior / Technical Design"]
+        LSTATE["state.md\noat_workflow_mode: lite"]
+      end
+
+      CMD["oat project promote\n--to quick"]
+
+      subgraph After
+        DISC["discovery.md\nderived from the lite plan\noat_ready_for: oat-project-quick-start"]
+        REF["references/lite-plan.md\noriginal lite plan, preserved"]
+        QPLAN["plan.md\nfresh quick-start template"]
+        QSTATE["state.md\noat_workflow_mode: quick\noat_phase: discovery (complete)\noat_ready_for: oat-project-quick-start"]
+      end
+
+      LPLAN --> CMD
+      LSTATE --> CMD
+      CMD -->|derive| DISC
+      CMD -->|move| REF
+      CMD -->|scaffold| QPLAN
+      CMD -->|rewrite| QSTATE
+    ```
 
 The project slug, directory, and branch are untouched, so history and any open
 work continue uninterrupted. `oat_ready_for` is stamped on **both** `discovery.md`
@@ -453,21 +490,35 @@ categorical `reason` and exit non-zero. See
 
 ### Import lane
 
-```mermaid
-flowchart LR
-  I["Import Plan"] --> II1["Implement (oat-project-implement)"]
-  II1 --> IR["Review / PR"]
-```
+=== "Diagram"
+
+    ![Import lane: import a plan, implement, then review and PR](/diagrams/project-lifecycle-6-import-lane-light.svg)
+    ![Import lane: import a plan, implement, then review and PR](/diagrams/project-lifecycle-6-import-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      I["Import Plan"] --> II1["Implement (oat-project-implement)"]
+      II1 --> IR["Review / PR"]
+    ```
 
 ### Capture lane
 
 Retroactive project creation for work done outside the OAT project workflow. Common scenario: mobile/cloud sessions where you brainstorm and implement with an agent, then want to open a PR and review from your desktop.
 
-```mermaid
-flowchart LR
-  W["Work on branch\n(no project)"] --> Cap["oat-project-capture"]
-  Cap --> R["Review / PR"]
-```
+=== "Diagram"
+
+    ![Capture lane: work on a branch without a project, run oat-project-capture, then review and PR](/diagrams/project-lifecycle-7-capture-lane-light.svg)
+    ![Capture lane: work on a branch without a project, run oat-project-capture, then review and PR](/diagrams/project-lifecycle-7-capture-lane-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      W["Work on branch\n(no project)"] --> Cap["oat-project-capture"]
+      Cap --> R["Review / PR"]
+    ```
 
 Entry point: `/oat-project-capture` (skill-only, no CLI command — requires agent conversation context).
 
@@ -513,7 +564,7 @@ Capture lane progression:
 
 The lifecycle has several interactive prompts that power users often answer the same way every time — HiLL checkpoint behavior, archive on complete, auto-create PR, post-implementation chaining, final review execution model, and re-review scope narrowing. These can be configured once via `workflow.*` preference keys and respected automatically by skills.
 
-See the [Workflow preferences section in the Configuration guide](../../cli-utilities/configuration.md#workflow-preferences-workflow) for the full list of keys and how to set them. Preferences resolve through a three-layer chain (`env > repo-local > repo-shared > user > default`), so you can set personal defaults at user scope once and override per-repo only when needed.
+See the [Workflow preferences section in the Configuration guide](../../reference/configuration.md#workflow-preferences-workflow) for the full list of keys and how to set them. Workflow preferences resolve through `repo-local > repo-shared > user > default`; there is no generic workflow environment layer. Individual skills may separately read environment controls such as `OAT_DESIGN_MODE`. Set personal defaults at user scope and override per-repo when needed.
 
 ## Active project resolution
 
@@ -538,7 +589,7 @@ separate checks, and both must hold before any PJM write:
 Pack presence is never treated as evidence of repository adoption. A skill that
 finds the capability available but the repository unadopted reports the
 actionable `oat pjm init` stop instead of scaffolding implicitly. See
-[Install vs. initialize](../../cli-utilities/tool-packs.md#install-vs-initialize).
+[Install vs. initialize](../../getting-started/tool-packs.md#install-vs-initialize).
 
 ## Brainstorming integration with the project lifecycle
 
@@ -566,3 +617,37 @@ The fold-back path is what makes "we got to plan and realized the design missed
 - `.oat/projects/<scope>/<project>/design.md`
 - `.oat/projects/<scope>/<project>/plan.md`
 - `.oat/projects/<scope>/<project>/implementation.md`
+
+## Choosing lifecycle controls
+
+OAT has four separate controls that are easy to confuse. Each one adds a
+different kind of check:
+
+- **Planning checkpoints** hold a spec-driven project after discovery and after
+  design until a person approves.
+- **Implementation checkpoints** (HiLL checkpoints) pause implementation after
+  chosen phases until a person approves.
+- **Artifact review loops** have the same agent session check a generated plan
+  or analysis and fix clear problems before handing it on.
+- **Gates** send the work to a second agent CLI, preferably running a different
+  family of models, and turn its findings into a pass or a fail.
+
+None of these replaces the code reviews that run after every implementation
+phase and before closeout; those run whatever you choose here.
+
+Decide in this order: first the
+[workflow mode](../choose-workflow.md#which-mode-should-i-choose), then the
+[design interaction mode](planning/design-modes.md#choosing-an-interaction-mode),
+then the [checkpoint frequency](planning/hill-checkpoints.md#choosing-checkpoint-frequency).
+
+- If your team needs to approve the architecture before any code is written,
+  choose a spec-driven project for its planning checkpoints, or add a gate to a
+  planning skill.
+- If you want to steer implementation after risky phases, choose
+  implementation checkpoints for those phases.
+- If a plan or analysis will be handed to another workflow, keep its artifact
+  review loop on.
+- If a high-risk change needs a reviewer from a different model family, add a
+  [gate](../advanced/workflow-gates.md#choosing-gate-posture) and check which
+  reviewer it actually used. Adding more reviews makes a run slower; it does not
+  by itself make them independent.

package/assets/docs/workflows/projects/meta.json

@@ -1,25 +1,4 @@
 {
-  "title": "Workflow & Projects",
-  "pages": [
-    "lifecycle",
-    "retro",
-    "autonomy",
-    "cursor-cloud",
-    "design-modes",
-    "hill-checkpoints",
-    "dispatch-ceiling",
-    "orchestration-model",
-    "review-flavors",
-    "evidence-layers",
-    "programmatic-execution",
-    "artifacts",
-    "implementation-execution",
-    "reviewing-oat-prs",
-    "picking-up-projects",
-    "splitting",
-    "state-machine",
-    "reviews",
-    "pr-flow",
-    "repo-analysis"
-  ]
+  "title": "Projects",
+  "pages": ["lifecycle", "reviews", "planning", "execution", "closeout"]
 }

package/assets/docs/workflows/projects/{design-modes.md → planning/design-modes.md}

@@ -106,3 +106,32 @@ oat config set workflow.designMode draft --local
 Valid values are `collaborative`, `selective`, and `draft`.
 
 Runtime non-interactive signals still win over this preference. If `OAT_NON_INTERACTIVE=1` is set, design runs in draft-and-review mode so automation does not block on prompts.
+
+## Choosing an interaction mode
+
+The design mode decides how the agent reviews the design with you while it
+writes `design.md`.
+
+| Mode          | Choose it when                                                                  | What you give up                                                               |
+| ------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Collaborative | The design is uncertain, or the repository has little documentation to build on | Time: you confirm every section before the file is written                     |
+| Selective     | A spec-driven project in a repository whose architecture is well documented     | Seeing routine sections live; you review them only in the final recap          |
+| Draft         | You want a complete proposal first, or nobody is available to answer prompts    | Live input: the final review of the whole file is your only chance to steer it |
+
+If you have not set `workflow.designMode`, the design skill asks you each time
+and suggests collaborative. When more than one source sets a mode, the skill
+uses the first of these it finds: the `--mode` argument, the `OAT_DESIGN_MODE`
+environment variable, draft for a non-interactive run (so automation never
+waits on a prompt), and finally your configured preference or the prompt. Quick
+projects offer only collaborative and draft; a configured `selective` behaves
+as collaborative there.
+
+- If you are trying OAT on your own and are unsure, leave the preference unset
+  and pick collaborative when asked.
+- If your team is still debating the architecture, choose collaborative so
+  people can steer each section before the design is written.
+- If a spec-driven project follows well-documented repository patterns, choose
+  selective: risky sections such as security and migration are still shown to
+  you live, and routine ones appear in the final recap.
+- If you need a complete proposal before a scheduled review meeting, or the run
+  is scripted, choose draft and set aside time to read the whole result.

package/assets/docs/workflows/projects/planning/hill-checkpoints.md

@@ -0,0 +1,167 @@
+---
+title: Human-in-the-Loop Lifecycle (HiLL) Checkpoints
+description: 'Checkpoint configuration and behavior for pauseable, human-in-the-loop lifecycle execution.'
+---
+
+# Human-in-the-Loop Lifecycle (HiLL) Checkpoints
+
+OAT supports two checkpoint classes:
+
+- Workflow phase checkpoints
+- Plan phase checkpoints
+
+The [Phase gate review](../reviews/index.md#phase-review-gate) (`oat_phase_review_gate`) is a separate, non-pausing mechanism — it does not pause on a passing gate and never modifies the HiLL keys below (`oat_hill_completed`, `oat_plan_hill_phases`).
+
+## Workflow checkpoints (`state.md`)
+
+Frontmatter keys:
+
+- `oat_hill_checkpoints`
+- `oat_hill_completed`
+
+Example:
+
+```yaml
+oat_hill_checkpoints: ['discovery', 'design']
+oat_hill_completed: ['discovery']
+```
+
+An older project may still list `spec`, and the design skill honors it by
+asking for your review at the design step unless the standalone
+`oat-project-spec` skill already completed that checkpoint.
+
+## Plan phase checkpoints (`plan.md`)
+
+Frontmatter key written after implementation confirmation:
+
+- `oat_plan_hill_phases`
+
+Semantics:
+
+- Field absent: valid before the first `oat-project-implement` run confirms checkpoint selection. Planning may intentionally leave the field unset until that first execution starts.
+- Empty list: checkpoint after every phase boundary, but only after implementation has confirmed the choice and written `oat_plan_hill_phases: []` into `plan.md`.
+- Explicit list: checkpoint only after completing the named phases (`p01`, `p04`, etc).
+
+### Lite checkpoint bypass
+
+Lite projects have no HiLL checkpoints. `oat-project-implement` resolves
+`oat_workflow_mode` from project state before any checkpoint field read, and
+when the mode is `lite` it resolves checkpoint state as `none` without reading
+or interpreting `oat_plan_hill_phases`. An empty list cannot represent lite's
+policy, because for every other mode an empty list means "checkpoint after every
+phase". `oat-project-implement`'s Lite checkpoint bypass writes:
+
+```yaml
+oat_auto_review_at_hill_checkpoints: false # lite: no checkpoints
+```
+
+The workflow preference prompt, the standard checkpoint prompt, and the
+auto-review preference prompt are all skipped in both interactive and autonomous
+runs. Only HiLL approval pauses are absent — the root-owned per-phase review and
+the final review remain required.
+
+The rest of this section applies to `spec-driven`, `quick`, and `import`
+projects.
+
+On the first implementation run, `oat-project-implement` must summarize every plan phase, state the total phase count and final phase ID, and then ask an explicit three-option checkpoint question:
+
+- Stop after each phase
+- Stop after specific phases
+- Stop only after the final phase is completed
+
+It then writes the confirmed value into `plan.md`. If the field is later missing during a resumed implementation run, treat that as bookkeeping drift rather than as an implicit default.
+
+Listed phases are where you stop **after completing them**, not before. `["p03"]` means "complete p03, then pause" — not "pause before starting p03." Setting the last phase ID (e.g., `["p03"]` when p03 is final) means "stop only at the end of implementation."
+
+### Setting a default via `workflow.hillCheckpointDefault`
+
+The first-run checkpoint prompt can be skipped entirely by setting the `workflow.hillCheckpointDefault` preference:
+
+- `every` — automatically write `oat_plan_hill_phases: []` (pause after every phase) without prompting
+- `final` — automatically write `oat_plan_hill_phases: ["<final-phase-id>"]` (pause only at the end) without prompting
+
+When set, `oat-project-implement` reads the preference before the prompt and prints `HiLL checkpoints: <every|final> (from workflow.hillCheckpointDefault)`, skipping the interactive choice. When unset (default), the skill prompts as before.
+
+Treat this setting as a personal preference by default and set it at user
+level (`--user`, stored in `~/.oat/config.json`), so it applies to every
+repository you work in. Set it at shared level (`--shared`, stored in the
+committed `.oat/config.json`) only when your team has agreed on a rule for
+where agents must pause. Configuration resolves local first, then shared, then
+user, so a shared value overrides each person's user-level value, and anyone
+can still override it for their own checkout with `--local`.
+
+A configured value is used on each project's first implementation run without
+asking, and it replaces any checkpoint value already written in that project's
+`plan.md` (see the warning under
+[Choosing checkpoint frequency](#choosing-checkpoint-frequency)).
+
+- If you want more control and the chance to steer between phases, use
+  `every`:
+
+  ```bash
+  oat config set workflow.hillCheckpointDefault every --user
+  ```
+
+- If you want fewer interruptions and you trust the plan and the automatic
+  reviews, use `final`:
+
+  ```bash
+  oat config set workflow.hillCheckpointDefault final --user
+  ```
+
+- If you want to decide per project, or to pause after specific phases, leave
+  the setting unset and answer the prompt on the first implementation run.
+
+See [Workflow preferences in the Configuration guide](../../../reference/configuration.md#workflow-preferences-workflow) for the full list of preference keys and surface guidance.
+
+## Reference artifacts
+
+- `.oat/templates/plan.md`
+- `.oat/projects/<scope>/<project>/plan.md`
+- `.oat/projects/<scope>/<project>/state.md`
+
+## Choosing checkpoint frequency
+
+A HiLL (human-in-the-loop lifecycle) checkpoint is a point where the
+implementing agent stops and waits for a person to approve before it continues.
+This choice decides how often that happens during implementation. Lite projects
+have no checkpoints, so it does not apply to them.
+
+| Choice             | Choose it when                                    | What you give up                             |
+| ------------------ | ------------------------------------------------- | -------------------------------------------- |
+| Every phase (`[]`) | The work is high-risk and you want to steer often | Speed: you approve after every phase         |
+| Specific phases    | Only some phases are risky                        | Pauses after the other phases                |
+| Final phase only   | You trust the plan and the automatic reviews      | The chance to correct course partway through |
+
+You can pick any of the three at the first-run prompt. The
+`workflow.hillCheckpointDefault` setting can express only `every` or `final`, so
+choosing specific phases needs the prompt or a hand edit of
+`oat_plan_hill_phases` in `plan.md`. The setting is unset by default, and the
+prompt suggests stopping after every phase.
+
+> [!WARNING]
+> On a project's first implementation run (unless the run is autonomous), a
+> configured `workflow.hillCheckpointDefault` is used without asking, and it
+> replaces any checkpoint value already written in that project's `plan.md`. After the first
+> run, the value stored in `plan.md` is what applies; changing the config later
+> does not change that project. To choose specific phases, remove the setting
+> before the first run from the layer that sets it (for example
+> `oat config unset workflow.hillCheckpointDefault --user` if you set it with
+> `--user`), or edit `oat_plan_hill_phases` in `plan.md` afterwards.
+
+- If you are a solo developer working from a plan you trust, choose final only,
+  for example with `oat config set workflow.hillCheckpointDefault final --user`.
+- If the change is high-risk or regulated, such as a data migration, run
+  implementation interactively and choose every phase. Check that no
+  `workflow.hillCheckpointDefault` is configured first, because it would skip
+  the prompt.
+- If only a few phases need sign-off, such as a migration phase and a
+  deployment phase, list those phases at the first-run prompt.
+
+Autonomous runs (started with `OAT_AUTONOMOUS=1`) ignore
+`workflow.hillCheckpointDefault`. If `plan.md` has no checkpoint value, they
+write the final phase only; a valid value already in `plan.md` is kept as
+written. Autonomous runs also turn on the automatic review at checkpoints: at
+each checkpoint the agent runs that review, handles its findings, and continues
+instead of waiting for a person. The per-phase and final code reviews run in
+every mode.

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

@@ -0,0 +1,16 @@
+---
+title: Planning
+description: 'Design modes, lifecycle checkpoints and project splitting.'
+---
+
+# Planning
+
+Use these guides to plan a tracked project and choose its collaboration boundaries.
+
+## Contents
+
+- [Starting projects](starting-projects.md) - Choose an entry point, import a plan, capture work or split a broad scope.
+- [Planning skills](planning-skills.md) - Discovery, requirements, design, planning and workflow promotion.
+- [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.
+- [Human-in-the-Loop Lifecycle (HiLL) Checkpoints](hill-checkpoints.md) - Human-in-the-Loop Lifecycle configuration and approval behavior.
+- [Project Splitting](splitting.md) - How broad discoveries or brainstorms become coordination parents and child projects.

package/assets/docs/workflows/projects/planning/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Planning",
+  "pages": [
+    "starting-projects",
+    "planning-skills",
+    "design-modes",
+    "hill-checkpoints",
+    "splitting"
+  ]
+}