@open-agent-toolkit/cli 0.3.13 → 0.3.14

package/assets/docs/workflows/waves/wave-workflows.md

@@ -0,0 +1,206 @@
+---
+title: Wave Workflows
+description: How OAT coordinates a corpus of external plans into waves while preserving project-lifecycle ownership and human judgment.
+---
+
+# Wave Workflows
+
+A wave is a program layer above the per-project OAT lifecycle. It groups external implementation plans into an ordered delivery unit, then runs that unit as a wrapper OAT project. The wrapper uses the normal project lifecycle rather than replacing it.
+
+Use wave workflows when a plan corpus is too large to execute as one project and needs durable sequencing across multiple projects, worktree groups, and merges.
+
+Terms used on this page:
+
+- **Wave:** one ordered batch of external implementation plans that is executed and merged together.
+- **Wrapper project:** the ordinary quick-mode OAT project that `oat-wave-execute` creates to run one wave. Its plan points to the wave's source plans.
+- **Worktree:** a separate Git checkout of the same repository on its own branch, so parallel lanes do not overwrite each other's files.
+- **Active project:** the project your checkout currently points to, stored as `activeProject` in `.oat/config.local.json`.
+- **Orchestrator:** the root agent session (with you) that makes the judgment calls the skills leave open.
+
+## The Two Wave Skills
+
+The workflow pack provides two complementary skills:
+
+- `oat-wave-program` 1.5.3 maintains the durable execution-program artifact over the full plan corpus. Its `new` mode inventories the corpus, verifies the coverage invariant, and records the orchestrator-composed, operator-approved first program; `refresh` adds newly landed plans to the artifact and records the orchestrator's re-composition of waves not yet started; and `wave-close` records a completed wave. Composing waves is the orchestrating agent's judgment; the skill records the result.
+- `oat-wave-execute` 1.9.5 runs one wave. It owns the repeatable mechanical layer: wrapper-project scaffolding, branch conventions, worktree bootstrap, briefs, gates, merge choreography, bookkeeping cadence, and closeout order.
+
+`oat-wave-program` records which plans belong to each wave. `oat-wave-execute` consumes that mapping and executes one wave through the project lifecycle.
+
+## Mechanical Work and Judgment
+
+The ownership split is load-bearing. The skills automate mechanics, but the orchestrator retains judgment.
+
+The skills own:
+
+- integration and phase branch naming
+- wrapper-project scaffolding
+- worktree bootstrap
+- merge choreography
+- artifact and ledger bookkeeping
+- repeatable verification and closeout sequencing
+
+The orchestrator owns:
+
+- wave and parallel-group composition
+- review-finding dispositions
+- verification of load-bearing worker claims
+- merge-order decisions under live drift
+- cross-lane and end-of-run synthesis
+- all user checkpoints
+
+Do not treat a generated grouping or a mechanically successful lane as a substitute for these decisions.
+
+## Composition With Project Implementation
+
+Each wave is scaffolded as a quick-mode wrapper project. Its plan points to the source plans while preserving their requirements, and `oat-project-implement` remains the lifecycle owner for phase execution, independent review, bounded fixes, checkpoints, and project state.
+
+For plan-declared parallel groups, `oat-wave-execute` invokes its bundled `scripts/bootstrap-group.sh` helper. The helper wraps the standard worktree bootstrap flow, creates phase worktrees at an explicit base, initializes each worktree, checks provider-view parity, and reports structured status. `oat-project-implement` then dispatches and verifies each phase in its assigned worktree. The wave layer owns the serialized fan-in and integration gates after those phases pass.
+
+This composition keeps the responsibilities separate:
+
+1. `oat-wave-program` records the program and wave membership.
+2. `oat-wave-execute` scaffolds and coordinates one wrapper project.
+3. `oat-project-implement` executes that project's phases.
+4. `oat-wave-program wave-close` updates the durable program after the wave merges.
+
+## Execution-Program Artifact Format
+
+The execution-program artifact is durable reference material under `.oat/repo/reference/external-plans/`. It is not an executable plan or an `oat-project-import-plan` target.
+
+The current format contains:
+
+- **Wave table:** one row per source plan, including its link, source index, assigned wave, ordering or dependency notes, and status (`pending`, `in-wave`, `done`, `deferred`, or `dropped`).
+- **Coverage invariant:** every plan in every source plan index appears in exactly one row. A deferred or dropped plan includes a reason and re-entry trigger; an omitted plan is an error.
+- **Wave sections:** the theme, lane list, intra-wave ordering, and cross-wave prerequisites for each wave.
+- **Status ledger:** each wave advances from composed to in-progress to merged, with the wrapper-project link, PR, merge SHA, and completion-record link recorded as they become available.
+
+> **Important:** This format is documented as a description, not a stable contract. Two related pieces of work are planned but not yet done: documenting the execution-program artifact as a stable OAT contract, and adding an `oat wave` family of lifecycle CLI commands.
+
+Until that grouped work ships, consumers should follow the bundled skill and template rather than depending on an independently versioned schema.
+
+## oat-wave-program
+
+Use program to record which external plans belong in each wave. The
+orchestrator composes the waves and retains dependency, risk, and concurrency
+judgment. The skill maintains the inventory and approved result.
+
+**Invocation:** Select `new`, `refresh`, or `wave-close <wave-id>` as the
+situation requires. With no mode, the skill runs `refresh` against the current
+artifact. These are agent-skill requests, not `oat` CLI commands. Providers
+with `$` syntax use `$oat-wave-program` instead of the slash name.
+
+```text
+/oat-wave-program new
+```
+
+```text
+/oat-wave-program refresh
+```
+
+```text
+/oat-wave-program wave-close wave-2
+```
+
+**Prerequisites:** Needs an active OAT project: no. New mode needs the external
+plan indexes and their actual plan files.
+Refresh needs the live execution-program artifact and current indexes.
+Wave-close needs the completed wave's merge and completion evidence. Missing
+indexed files stop the flow rather than being guessed from names.
+
+**What it does without asking:** every mode writes the execution-program
+artifact and commits it. New mode shows you the proposed wave map and waits
+for your approval before the first wave starts. When the final wave merges,
+the skill stops at one human-gated checkpoint that asks whether to run the
+deferred completion tail (archive, S3 upload, and active-project clear) for
+every wave's wrapper project; autonomous runs never answer that question
+themselves.
+
+**Example scenario:** Twelve reviewed external plans include a shared API
+foundation, client changes, and independent documentation work. Use `new` to
+inventory every indexed plan and record an operator-approved sequence. When
+three more plans arrive, use `refresh` to recompose only unstarted waves. After
+wave two merges, use `wave-close wave-2` to record that boundary instead of
+inventing another execution program.
+
+**Expected output:** A dated execution-program artifact under
+`.oat/repo/reference/external-plans/`, with exactly one row per indexed plan,
+explicit deferral reasons, ordered waves, dependencies, and a current status
+ledger. Started waves cannot be reshuffled, and merged membership is frozen
+history. Plan rows can become `done`; wave-ledger states are `composed`,
+`in-progress`, and `merged`.
+
+At final program close, recap and deferred wrapper completion receive explicit
+dispositions. The completion-tail checkpoint remains human-gated, including
+autonomous runs. Program bookkeeping is not an executable project plan or an
+import target.
+
+**Next step:** Invoke `oat-wave-execute` for an approved wave. Record each merge
+through wave-close, and resolve any program-end completion deferral with its
+named owner.
+
+## oat-wave-execute
+
+Use execute for one wave, not for composing the whole corpus. It prepares and
+coordinates a quick wrapper project while the normal project lifecycle owns
+phase implementation and review.
+
+**Invocation:** Name the wave. Its lanes normally resolve from the live program
+artifact, with plan-index hints used only when no program exists. You can also
+list specific plan names after the wave ID.
+
+```text
+/oat-wave-execute wave-2
+```
+
+**Prerequisites:** Needs an active OAT project: no. The skill creates the
+wrapper project itself and makes it the active project, which replaces any
+project that was active before. Start from an up-to-date `main` with a clean
+working tree. The named source plans must exist, and their drift checks must
+allow the lanes to proceed. You also need worktree tooling, reviewer
+capabilities, and permission for the Git operations listed below. The default
+concurrency ceiling is three worktrees at a time, and the operator can change
+it.
+
+**What it does without asking:** running this skill authorizes all of the
+following. It creates the `wave-N-execution` branch from `main`, installs
+dependencies, and runs the repository's build and type checks. It scaffolds
+the wrapper project and commits it. It dispatches a read-only recon subagent,
+creates one worktree per parallel lane on a `wave-N/pNN` branch, and, through
+`oat-project-implement`, dispatches implementer and reviewer subagents in
+those worktrees. It merges passing lane branches into `wave-N-execution` with
+`git merge --no-ff`, then deletes the merged worktrees and their branches. At
+closeout it archives the wave's backlog items with `oat backlog archive` and
+runs the configured closeout sequence (which can open the PR). It then stops
+once at a HiLL (human-in-the-loop) approval checkpoint before running the
+`oat-project-complete` process, including project archive and any configured
+S3 upload. After you merge the wave, it resets the working branch, deletes
+stale phase branches, and runs `oat-wave-program wave-close`. Merging the wave
+into `main` stays your decision.
+
+**Example scenario:** The approved second wave contains client changes after
+its API foundation merged. Execute refreshes drift against the current base,
+intersects every plan's write set, and records safe groups in the wrapper plan.
+Overlapping files force separate groups even when the plans looked independent
+when authored. Choose execute rather than program because wave membership is
+already approved and now needs verified delivery.
+
+**Expected output:** A `wave-N-execution` wrapper with source-plan pointers,
+drift evidence, a plan, discovery, and an orchestration log. Passing lanes produce
+verified task commits and review dispositions in isolated worktrees. Serialized
+fan-in is followed by integration gates, so individual lane passes are not
+presented as proof the integrated tree passes.
+
+Closeout writes end-of-run synthesis before archive work. Autonomous execution
+can defer a wrapper's archive tail to program close only with an explicit
+ledger disposition. That deferral does not satisfy the full completion tail.
+Source-plan requirements remain intact even when live drift changes a mechanism.
+
+**Next step:** Follow the wave's reported review and merge boundary. After the
+operator merges, reconcile the result and invoke program wave-close. Do not mark
+an unmerged wave `merged` or treat a deferred archive as completed.
+
+## Related
+
+- [Project lifecycle](../projects/lifecycle.md)
+- [Implementation execution](../projects/execution/implementation-execution.md)
+- [Project artifacts](../../reference/project-artifacts.md)

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.13",
-  "docs-config": "0.3.13",
-  "docs-theme": "0.3.13",
-  "docs-transforms": "0.3.13"
+  "cli": "0.3.14",
+  "docs-config": "0.3.14",
+  "docs-theme": "0.3.14",
+  "docs-transforms": "0.3.14"
 }

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.3
+  version: 1.0.4
 ---
 
 # OAT Docs
@@ -91,21 +91,21 @@ Read the user's question from `$ARGUMENTS`. If no question was provided or the q
 
 Classify the question into one or more topic areas to guide the search:
 
-| Topic Area       | Docs Path                                   | Key Content                                  |
-| ---------------- | ------------------------------------------- | -------------------------------------------- |
-| Getting started  | `quickstart.md`, `guide/getting-started.md` | Installation, first project setup            |
-| Concepts         | `guide/concepts.md`                         | Core OAT concepts and terminology            |
-| CLI commands     | `guide/cli-reference.md`                    | Full CLI command reference                   |
-| Tool packs       | `guide/tool-packs.md`                       | Installing and managing skill packs          |
-| Skills           | `guide/skills/`                             | Skill authoring, SKILL.md format             |
-| Workflows        | `guide/workflow/`                           | Project lifecycle, state machine, artifacts  |
-| Ideas            | `guide/ideas/`                              | Idea capture and brainstorming               |
-| Provider sync    | `guide/provider-sync/`                      | Multi-provider sync, config, commands        |
-| Documentation    | `guide/documentation/`                      | Docs analysis and apply workflows            |
-| Contributing     | `contributing/`                             | Code contributions, design principles, hooks |
-| File locations   | `reference/file-locations.md`               | Where OAT puts things                        |
-| Directory layout | `reference/oat-directory-structure.md`      | `.oat/` and `.agents/` structure             |
-| Troubleshooting  | `reference/troubleshooting.md`              | Common issues and fixes                      |
+| Topic Area       | Docs Path                                                       | Key Content                                  |
+| ---------------- | --------------------------------------------------------------- | -------------------------------------------- |
+| Getting started  | `getting-started/quickstart.md`, `getting-started/bootstrap.md` | Installation, first project setup            |
+| Concepts         | `getting-started/concepts.md`                                   | Core OAT concepts and terminology            |
+| CLI commands     | `reference/cli-reference.md`                                    | Full CLI command reference                   |
+| Tool packs       | `getting-started/tool-packs.md`                                 | Installing and managing skill packs          |
+| Skills           | `contributing/skills.md`                                        | Skill authoring, SKILL.md format             |
+| Workflows        | `workflows/projects/`                                           | Project lifecycle, state machine, artifacts  |
+| Ideas            | `workflows/ideas/`                                              | Idea capture and brainstorming               |
+| Provider sync    | `provider-sync/`                                                | Multi-provider sync, config, commands        |
+| Documentation    | `docs-tooling/`                                                 | Docs analysis and apply workflows            |
+| Contributing     | `contributing/`                                                 | Code contributions, design principles, hooks |
+| File locations   | `reference/file-locations.md`                                   | Where OAT puts things                        |
+| Directory layout | `reference/oat-directory-structure.md`                          | `.oat/` and `.agents/` structure             |
+| Troubleshooting  | `reference/troubleshooting.md`                                  | Common issues and fixes                      |
 
 ### Step 3: Search and Read Documentation
 
@@ -143,7 +143,7 @@ Frame these as suggestions, not automatic actions. Let the user decide.
 ```
 Based on the docs, here's how OAT project workflows work: [answer]
 
-You can read more in `guide/workflow/lifecycle.md`.
+You can read more in `workflows/projects/lifecycle.md`.
 
 Would you like me to:
 - Start a new project? (I'd invoke oat-project-lite for single-sitting work, or oat-project-quick-start for a larger quick workflow)
@@ -181,7 +181,7 @@ Both create a project directory under your projects root
 state.md, plan.md, and implementation.md; quick and spec-driven modes also use
 discovery.md.
 
-See: guide/workflow/lifecycle.md, guide/getting-started.md
+See: workflows/projects/lifecycle.md, getting-started/quickstart.md
 
 Would you like me to create a project for you?
 ```
@@ -207,7 +207,7 @@ There are four packs:
 Install with: oat init tools
 Manage with: oat tools list, oat tools update, oat tools outdated
 
-See: guide/tool-packs.md
+See: getting-started/tool-packs.md
 
 Would you like me to check which packs you have installed? (I'd run /oat-doctor --summary)
 ```

package/assets/skills/oat-docs-analyze/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat docs nav sync --check:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.6.1
+  version: '1.6.2'
 ---
 
 # Docs Analysis

package/assets/skills/oat-docs-apply/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.4.1
+  version: '1.4.2'
 ---
 
 # Docs Apply

package/assets/skills/oat-docs-authoring/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.1.1
+  version: '1.1.2'
 ---
 
 # OAT Docs Authoring

package/assets/skills/oat-docs-bootstrap/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.3.1
+  version: '1.3.2'
 ---
 
 # Docs Bootstrap

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.0.2
+  version: 2.0.3
 ---
 
 # OAT Doctor
@@ -194,38 +194,38 @@ Docs citations below name a page under `~/.oat/docs/` (the same tree as `apps/oa
 
 Walk every distinct `group` value in the `describe` output — nine today, including `PJM Remote Shared Policy`, `Explainer Defaults (local > shared)`, and `User Sync (~/.oat/sync/config.json)`; never a hard-coded list. For each group, say what is set (from the dump or the sync files), what is deprecated, and what is unset; for an unset group, teach it from the entry descriptions and its docs section:
 
-| Group                                                              | Docs section                                                                    |
-| ------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
-| The five surfaces themselves (which file owns what)                | `cli-utilities/configuration.md` § The five config surfaces                     |
-| `Shared Repo (.oat/config.json)`                                   | `cli-utilities/configuration.md` § Shared repo config you will touch most often |
-| `Repo Local (.oat/config.local.json)`, `User (~/.oat/config.json)` | `cli-utilities/configuration.md` § Repo-local and user state                    |
-| `Workflow Preferences` (dispatch policy keys)                      | `cli-utilities/configuration.md` § Dispatch policy resolution                   |
-| `Workflow Preferences` (everything else)                           | `cli-utilities/configuration.md` § Workflow preferences                         |
-| `Workflow Preferences` (gate keys)                                 | `cli-utilities/workflow-gates.md` § Gate config                                 |
-| `Sync/Provider`, `User Sync`                                       | `cli-utilities/configuration.md` § Provider sync config is different            |
-| `PJM Remote Shared Policy`                                         | `cli-utilities/remote-project-management.md`                                    |
-| the `pjm.*` keys under Shared Repo                                 | `cli-utilities/backlog-lifecycle.md` § Adoption comes first                     |
-| `Explainer Defaults`                                               | the entry descriptions (`oat config describe explainers.defaults.style`)        |
+| Group                                                              | Docs section                                                                 |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| The five surfaces themselves (which file owns what)                | `reference/configuration.md` § The five config surfaces                      |
+| `Shared Repo (.oat/config.json)`                                   | `reference/configuration.md` § Shared repo config you will touch most often  |
+| `Repo Local (.oat/config.local.json)`, `User (~/.oat/config.json)` | `reference/configuration.md` § Repo-local and user state                     |
+| `Workflow Preferences` (dispatch policy keys)                      | `reference/configuration.md` § Dispatch policy resolution                    |
+| `Workflow Preferences` (everything else)                           | `reference/configuration.md` § Workflow preferences                          |
+| `Workflow Preferences` (gate keys)                                 | `workflows/advanced/workflow-gates.md` § Gate config                         |
+| `Sync/Provider`, `User Sync`                                       | `reference/configuration.md` § Provider sync config is different             |
+| `PJM Remote Shared Policy`                                         | `workflows/backlog-and-planning/remote-project-management.md`                |
+| the `pjm.*` keys under Shared Repo                                 | `workflows/backlog-and-planning/backlog-lifecycle.md` § Adoption comes first |
+| `Explainer Defaults`                                               | the entry descriptions (`oat config describe explainers.defaults.style`)     |
 
 A deprecated key is explained through its `deprecated.supersededBy` and the successor's `owningCommand`.
 
 #### PJM dive
 
-State the adoption state (`declared`, `inferred-legacy`, `partial-initialization`, or `none`) and what it means (`cli-utilities/backlog-lifecycle.md` § Adoption comes first). Then each non-passing check and its fix:
+State the adoption state (`declared`, `inferred-legacy`, `partial-initialization`, or `none`) and what it means (`workflows/backlog-and-planning/backlog-lifecycle.md` § Adoption comes first). Then each non-passing check and its fix:
 
-| Check                                                                                                                                                                                                                                         | Fix path                                                                                                                                                                         |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pjm:adoption`                                                                                                                                                                                                                                | not reported separately: the `adoption.state` rule owns it; fix `oat pjm init`                                                                                                   |
-| `pjm:canonical_files`, `pjm:template_frontmatter`, `pjm:top_level_layout`                                                                                                                                                                     | `oat pjm init` re-creates canonical files; unknown top-level folders are the person's to move (`cli-utilities/backlog-lifecycle.md` § Catching lifecycle drift)                  |
-| `pjm:legacy_monoliths`, `pjm:loose_reference_files`, `pjm:second_roadmap`                                                                                                                                                                     | structural drift: `cli-utilities/backlog-lifecycle.md` § Catching lifecycle drift and the migration guidance it links; `oat-pjm-update-repo-reference` for the reference records |
-| `pjm:backlog_terminal_in_items`, `pjm:backlog_completed_unarchived`                                                                                                                                                                           | `oat backlog archive <id>` for each named item, then `oat backlog regenerate-index`                                                                                              |
-| `pjm:backlog_invalid_status`, `pjm:backlog_archived_open`, `pjm:backlog_duplicate_id`                                                                                                                                                         | edit the named item's frontmatter (the person), then `oat backlog regenerate-index`                                                                                              |
-| `pjm:remote_schema`, `pjm:remote_binding_ids`, `pjm:remote_metadata_state`, `pjm:remote_storage_content`, `pjm:remote_policy`, `pjm:remote_concurrent_intents`, `pjm:remote_operations`, `pjm:remote_retention`, `pjm:remote_host_capability` | emitted only when a remote binding is adopted: `oat-pjm-remote` (reconcile or refresh) and `cli-utilities/remote-project-management.md`                                          |
-| any other `pjm:*` name                                                                                                                                                                                                                        | `info` with the check's message; no fix path is invented                                                                                                                         |
+| Check                                                                                                                                                                                                                                         | Fix path                                                                                                                                                                                          |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pjm:adoption`                                                                                                                                                                                                                                | not reported separately: the `adoption.state` rule owns it; fix `oat pjm init`                                                                                                                    |
+| `pjm:canonical_files`, `pjm:template_frontmatter`, `pjm:top_level_layout`                                                                                                                                                                     | `oat pjm init` re-creates canonical files; unknown top-level folders are the person's to move (`workflows/backlog-and-planning/backlog-lifecycle.md` § Catching lifecycle drift)                  |
+| `pjm:legacy_monoliths`, `pjm:loose_reference_files`, `pjm:second_roadmap`                                                                                                                                                                     | structural drift: `workflows/backlog-and-planning/backlog-lifecycle.md` § Catching lifecycle drift and the migration guidance it links; `oat-pjm-update-repo-reference` for the reference records |
+| `pjm:backlog_terminal_in_items`, `pjm:backlog_completed_unarchived`                                                                                                                                                                           | `oat backlog archive <id>` for each named item, then `oat backlog regenerate-index`                                                                                                               |
+| `pjm:backlog_invalid_status`, `pjm:backlog_archived_open`, `pjm:backlog_duplicate_id`                                                                                                                                                         | edit the named item's frontmatter (the person), then `oat backlog regenerate-index`                                                                                                               |
+| `pjm:remote_schema`, `pjm:remote_binding_ids`, `pjm:remote_metadata_state`, `pjm:remote_storage_content`, `pjm:remote_policy`, `pjm:remote_concurrent_intents`, `pjm:remote_operations`, `pjm:remote_retention`, `pjm:remote_host_capability` | emitted only when a remote binding is adopted: `oat-pjm-remote` (reconcile or refresh) and `workflows/backlog-and-planning/remote-project-management.md`                                          |
+| any other `pjm:*` name                                                                                                                                                                                                                        | `info` with the check's message; no fix path is invented                                                                                                                                          |
 
 #### Agent instructions dive
 
-Explain the sync strategy in use (`oat instructions validate --json` `.strategy`: `none`, the default, keeps no CLAUDE.md because Claude Code reads AGENTS.md itself; `pointer`, `symlink`, and `copy` keep a shim beside each AGENTS.md) and each non-`ok` entry and leftover-CLAUDE.md warning with its path. Explain each missing heading: what the CLI writes there and why an agent needs it (`cli-utilities/bootstrap.md` for `## Tool Packs`; `cli-utilities/backlog-lifecycle.md` § Adoption comes first for the PJM sections). Offer `oat instructions sync`, `oat tools guidance` (read-only: prints the `OAT tools` block to add), or `oat pjm init` (appends absent PJM blocks) as the finding names; for wording and coverage beyond presence, hand off to `oat-agent-instructions-analyze` then `oat-agent-instructions-apply`.
+Explain the sync strategy in use (`oat instructions validate --json` `.strategy`: `none`, the default, keeps no CLAUDE.md because Claude Code reads AGENTS.md itself; `pointer`, `symlink`, and `copy` keep a shim beside each AGENTS.md) and each non-`ok` entry and leftover-CLAUDE.md warning with its path. Explain each missing heading: what the CLI writes there and why an agent needs it (`getting-started/bootstrap.md` for `## Tool Packs`; `workflows/backlog-and-planning/backlog-lifecycle.md` § Adoption comes first for the PJM sections). Offer `oat instructions sync`, `oat tools guidance` (read-only: prints the `OAT tools` block to add), or `oat pjm init` (appends absent PJM blocks) as the finding names; for wording and coverage beyond presence, hand off to `oat-agent-instructions-analyze` then `oat-agent-instructions-apply`.
 
 #### Docs dive
 
@@ -233,7 +233,7 @@ Say what surface was detected and what `documentation.*` says. This dive owns no
 
 #### Tools dive
 
-List outdated tools with installed and bundled versions and scope, packs at both scopes, and packs enabled but not installed, each with its command. Explain scopes from `cli-utilities/tool-packs.md`.
+List outdated tools with installed and bundled versions and scope, packs at both scopes, and packs enabled but not installed, each with its command. Explain scopes from `getting-started/tool-packs.md`.
 
 ### Step 4: Summary Mode (`--summary`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.13"
+    "@open-agent-toolkit/control-plane": "0.3.14"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/assets/docs/cli-utilities/backlog-lifecycle.md

@@ -1,80 +0,0 @@
----
-title: Backlog Lifecycle
-description: The states a file-backed backlog item moves through, how oat backlog archive closes it out atomically, and how oat pjm doctor catches lifecycle drift.
----
-
-# Backlog Lifecycle
-
-The file-backed backlog under `.oat/repo/pjm/backlog/` tracks work as one Markdown file per item. This page describes the lifecycle those items move through, the atomic close-out command that keeps the pieces in sync, and the diagnostics that flag drift when a close-out is done by hand and something is missed.
-
-For the flag-by-flag command reference, see [`oat backlog archive`](config-and-local-state.md#oat-backlog-archive). For the two-layer PJM surface that hosts the backlog, see [Tool Packs](tool-packs.md#install-vs-initialize).
-
-## Adoption comes first
-
-`oat backlog` mutations require this repository to have adopted PJM. Installing
-the `project-management` pack makes the capability available — including at user
-scope, which is the default — but it does not adopt PJM for a repository, and
-`oat backlog init` is not an alternate adoption path.
-
-Run `oat pjm init` once per repository. Until adoption is recorded, backlog
-mutations write nothing and return an error naming the repository path and
-`oat pjm init` as the recovery. Check the current state with
-`oat pjm doctor --json` and read its `adoption.state` field.
-
-## Where a backlog item lives
-
-- **`items/<id>.md`** - active, file-backed records. Each carries frontmatter with a `status` and an `updated` timestamp.
-- **`archived/<id>.md`** - the resting place for closed-out items, preserving the full item file as history.
-- **`completed.md`** - a newest-first summary log of completed work, one line per entry (`YYYY-MM-DD — BL-YYMMDD-slug — Title — one-line outcome`).
-- **`index.md`** - the human-facing curated overview plus a managed, generated index table rebuilt from item frontmatter.
-
-## Item statuses
-
-An item's `status` frontmatter field is one of exactly four values:
-
-- `open` - captured, not yet started.
-- `in_progress` - actively being worked.
-- `closed` - completed.
-- `wont_do` - abandoned or intentionally declined.
-
-`closed` and `wont_do` are the two **terminal** statuses. These are the only valid values — never invent variants like `done`. A terminal item belongs in `archived/`, not `items/`.
-
-## Closing out an item
-
-When an item reaches a terminal state, close it out with the atomic command rather than editing files by hand:
-
-```bash
-# completed work
-oat backlog archive BL-260705-example --summary "shipped the thing"
-
-# abandoned work
-oat backlog archive BL-260705-example --wont-do --summary "superseded by BL-260706-other"
-```
-
-A single `oat backlog archive` run performs the whole close-out so its parts cannot drift apart:
-
-1. Sets the terminal `status` (`closed` by default, `wont_do` with `--wont-do`) and stamps `updated`.
-2. Validates and trims a nonblank `--summary` before mutating a `closed` item, then appends its canonical newest-first `completed.md` entry. `wont_do` items may omit the summary and get an entry only when one is provided.
-3. Moves `items/<id>.md` into `archived/` — with `git mv` inside a work tree, or a plain rename outside git.
-4. Rewrites inbound references to the moved file across Markdown under `.oat/repo/**` (tracked and untracked files that Git does not ignore; a code span whose whole content is the item's path, such as an external plan's source citation, is rewritten, while other code spans and fenced code are left as written with a warning) — external plans, decision records, and other backlog items — so no link dangles at `items/<id>.md`, and reports each rewritten file. A reference it cannot resolve is left alone with a warning.
-5. Regenerates the managed backlog index.
-
-The command is safe to re-run: an item already in `archived/` produces a no-op warning and only retries the reference rewrite and index regeneration, so an interrupted close-out finishes on the next run. A missing closed-item summary or an out-of-enum current status (for example a hand-set `done`) is a hard error before mutation and includes recovery guidance. See the [command reference](config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
-
-## Catching lifecycle drift
-
-The manual close-out this command replaces is exactly where the two motivating repos drifted — an item was marked closed in frontmatter and summarized in `completed.md` but never moved to `archived/`, and one shipped with the invalid status `done`. `oat pjm doctor` (and therefore `oat doctor`, which aggregates the `pjm:*` checks) now surfaces that drift:
-
-- **`pjm:backlog_terminal_in_items`** (fail) - a `closed` or `wont_do` item is still sitting in `items/`. Fix: run `oat backlog archive <id>` to finish the move.
-- **`pjm:backlog_invalid_status`** (fail) - an item carries an out-of-enum or missing `status`. The message lists the offending file paths and the valid statuses.
-- **`pjm:backlog_archived_open`** (warn) - an `open` or `in_progress` item is in `archived/`, which usually means it was archived prematurely.
-- **`pjm:backlog_completed_unarchived`** (warn) - `completed.md` references an item whose file still lives in `items/`.
-- **`pjm:backlog_duplicate_id`** (fail) - the same `<id>.md` exists in both `items/` and `archived/`. `oat backlog archive` refuses to auto-resolve this (it would clobber the archived record), so the duplicate must be reconciled by hand.
-
-These backlog checks run once the repository is adopted. `oat doctor` keys the
-`pjm:*` family on repository adoption state rather than on
-`tools.project-management`, so a repository whose PJM capability lives at user
-scope still gets full backlog diagnostics. An unadopted repository reports
-`pjm:adoption` with the `oat pjm init` recovery instead of backlog drift.
-
-Doctor reports drift; it never auto-fixes. A human or agent runs `oat backlog archive` (or corrects the status) and re-runs doctor to confirm the backlog is clean again.

package/assets/docs/cli-utilities/index.md

@@ -1,74 +0,0 @@
----
-title: CLI Utilities
-description: Standalone adoption lane for general OAT CLI surfaces outside provider sync, docs tooling, and tracked workflows.
----
-
-# CLI Utilities
-
-CLI Utilities is the OAT lane for the useful command surface that does not primarily belong to Provider Sync, Docs Tooling, or tracked workflow lifecycle execution.
-
-Use this section when you want bootstrap guidance, tool-pack lifecycle details, configuration help, and general-purpose command references. It covers general-purpose setup, configuration, pack-management, and diagnostic utilities that support the rest of the toolkit without being specific to provider sync, docs tooling, or tracked workflow execution.
-
-## Contents
-
-- [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
-- [Tool Packs and Installed Assets](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
-- [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
-- [Remote Project Management](remote-project-management.md) - Provider-neutral remote bindings, policy, previews, approvals, storage, and recovery.
-- [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
-- [Project Log](project-log.md) - Append-only project observations, synthesis, inspection, and durable roll-up.
-- [Backlog Lifecycle](backlog-lifecycle.md) - Backlog item states, atomic close-out with `oat backlog archive`, and lifecycle drift detection in `oat pjm doctor`.
-- [Workflow Gates](workflow-gates.md) - Completion-safe headless reviews, budgets, liveness evidence, and cross-runtime dispatch with `oat gate`.
-
-## What Lives Here
-
-This section collects the command groups that help you initialize OAT, manage installed packs, inspect local or config state, and use the wider CLI without implying that you are adopting provider sync or tracked workflows.
-
-Examples include:
-
-- bootstrap and setup flows such as `oat init`
-- bundled pack management through `oat tools`
-- general configuration guidance
-- workflow gate commands for per-skill final checks and cross-runtime review dispatch
-- utility command groups for config, local state, diagnostics, and related inspection flows
-- a guided health check, the `/oat-doctor` skill, that sweeps config, project management, agent instructions, docs, and installed tools, then explains and offers fixes for what it finds (described in [Config and Local State](config-and-local-state.md))
-
-## Who It's For
-
-- Users getting OAT set up in a repo
-- Teams managing installed tool packs and local config
-- People who need a general command map without diving into workflow lifecycle docs
-
-## When To Use This Section
-
-Use CLI Utilities when:
-
-- you are first setting up OAT in a repo
-- you need to install or update OAT packs
-- you are looking for configuration or local-state inspection help
-- you need the general CLI surface without committing to one of the deeper lanes yet
-
-## Start Here
-
-- Use [CLI Bootstrap](bootstrap.md) when you are starting with `oat init`.
-- Go to [Tool Packs](tool-packs.md) when you are managing bundled OAT packs and installed assets.
-- Read [Configuration](configuration.md) for config semantics, or [Config and Local State](config-and-local-state.md) for inspection and diagnostic command groups.
-- Read [Remote Project Management](remote-project-management.md) before binding local planning records to GitHub, Linear, or Jira.
-- Use [Workflow Gates](workflow-gates.md) when you want a skill to run a configured final command before it is considered done.
-
-## Common Tasks
-
-- Bootstrap OAT in a repo with [CLI Bootstrap](bootstrap.md).
-- Manage installed packs in [Tool Packs](tool-packs.md).
-- Adjust settings in [Configuration](configuration.md).
-- Use [Config and Local State](config-and-local-state.md) for the utility command groups that support inspection and diagnostics.
-- Configure cross-runtime review gates in [Workflow Gates](workflow-gates.md).
-
-## Go Deeper
-
-- [CLI Bootstrap](bootstrap.md) - Foundational `oat init` guidance outside provider-sync-specific onboarding.
-- [Tool Packs](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
-- [Configuration](configuration.md) - OAT configuration guidance.
-- [Remote Project Management](remote-project-management.md) - Safely operate explicit remote planning-record bindings.
-- [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
-- [Workflow Gates](workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch.

package/assets/docs/cli-utilities/meta.json

@@ -1,13 +0,0 @@
-{
-  "title": "CLI Utilities",
-  "pages": [
-    "bootstrap",
-    "tool-packs",
-    "configuration",
-    "remote-project-management",
-    "config-and-local-state",
-    "project-log",
-    "backlog-lifecycle",
-    "workflow-gates"
-  ]
-}