@open-agent-toolkit/cli 0.1.53 → 0.1.54

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

@@ -11,6 +11,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 - [Writing Skills](../../contributing/skills.md) - Contributor guide to skill authoring, contracts, and governance.
 - [Docs Workflows](../../docs-tooling/workflows.md) - How docs CLI helpers and docs skills work together.
+- [Repo Improve](repo-improve.md) - Source modes, external-plan boundaries, optional tracking, and OAT import handoff.
 
 ## Key Skills by Use Case
 
@@ -23,6 +24,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - 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
 - Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
+- Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
 - Work on docs surfaces: `authoring-docs` (general documentation baseline), `oat-docs-authoring` (targeted OAT/Fumadocs authoring), `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
 - Research a topic in depth: `deep-research`
@@ -99,6 +101,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-review-receive-remote`
     - `oat-repo-knowledge-index`
     - `oat-repo-maintainability-review`
+    - `oat-repo-improve`
     - `oat-pjm-add-backlog-item`
     - `oat-pjm-update-repo-reference`
     - `oat-pjm-review-backlog`

package/assets/docs/workflows/skills/repo-improve.md

@@ -0,0 +1,45 @@
+---
+title: Repo Improve
+description: 'Turn repository audits, maintainability reviews, and backlog sources into standalone external implementation plans.'
+---
+
+# Repo Improve
+
+Use `oat-repo-improve` when the desired output is an executable implementation plan rather than another analysis report. Every successful run writes one or more standalone plans under `.oat/repo/reference/external-plans/`.
+
+## Choose a source
+
+| Source                 | Use it when                                                                                                                                          |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Repo audit             | You need fresh repository reconnaissance and vetted improvement findings.                                                                            |
+| Maintainability review | A file-backed `oat-repo-maintainability-review` already identifies candidates. Improve verifies selected evidence without repeating the broad audit. |
+| Backlog review         | A living backlog review and optional priority alignment already establish value, dependencies, and sequencing.                                       |
+| Backlog directory      | You want to start from active items. Substantive backlogs should pass through backlog review and alignment before plan generation.                   |
+| Backlog item           | One existing item needs enough repository investigation to become executable.                                                                        |
+
+With no source argument, the skill probes for available review and backlog artifacts, annotates all five options, and asks which source to use.
+
+## Output boundary
+
+External plans are not canonical OAT project `plan.md` files. They contain self-contained context, scope, steps, verification, done criteria, and STOP conditions, but no OAT phase/task IDs or lifecycle bookkeeping.
+
+After generation, choose either execution path:
+
+- Execute a plan directly as a standalone handoff.
+- Run `oat-project-import-plan <external-plan-path>` to preserve and normalize one plan for tracked OAT execution.
+
+Project-sized candidates are split when possible. If inseparable work needs multiple design decisions or lacks one coherent verification boundary, improve recommends an OAT project workflow instead of emitting a mega-plan.
+
+## Optional tracking
+
+Plans are always the primary output. Tracking is optional and source-aware:
+
+- `--backlog-items` creates missing PJM items for repo-audit or maintainability-review plans. Backlog-backed sources reuse their existing items and add `external_plans` reverse links.
+- `--issues` previews one GitHub issue per plan, checks repository visibility and sensitive content, and requires explicit confirmation before publication. It is useful as a fallback when PJM is not installed.
+- Request both modifiers explicitly to create both forms. Neither implies the other.
+
+Failure to publish a backlog item or issue does not invalidate a successfully written plan; the skill reports partial tracking results precisely.
+
+## Orchestration
+
+Full repository audits use `oat-dispatch-subagents` for bounded read-only reconnaissance while the root agent retains vetting, prioritization, and plan writing. Dispatch is native-first. Configured project/workflow policy may authorize required CLI or cross-runtime routes; an agent-improvised alternate route requires explicit current-run approval.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.53",
-  "docs-config": "0.1.53",
-  "docs-theme": "0.1.53",
-  "docs-transforms": "0.1.53"
+  "cli": "0.1.54",
+  "docs-config": "0.1.54",
+  "docs-theme": "0.1.54",
+  "docs-transforms": "0.1.54"
 }

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.0.0
+version: 1.1.0
 description: Use when an OAT skill or workflow needs provider-neutral selection, launch, recovery, or evidence for bounded subagent work without project lifecycle policy.
 disable-model-invocation: true
 user-invocable: false
@@ -73,6 +73,7 @@ Require the caller to provide:
 - expected output and verification evidence;
 - authority, deadline, escalation conditions, and retry limit;
 - fallback policy and authorization scope;
+- route-selection source for any non-native route;
 - optional resolved dispatch policy or named ceiling.
 
 Reject an over-broad request before selection. Every nontrivial request must
@@ -98,12 +99,42 @@ or run expensive work inline merely because one approval question is needed.
 The caller owns the user interaction; this skill returns the question and
 required scope.
 
+## Native-First Route Selection
+
+Use these route tiers:
+
+1. **Native same-runtime:** Always the preferred default when it can satisfy
+   the resolved role, model, effort, authority, and isolation requirements. It
+   needs no additional authorization.
+2. **Policy-resolved CLI/programmatic or cross-runtime:** Permitted without a
+   per-run prompt when configured dispatch policy selected the route. Project
+   policy resolved by `oat-project-dispatch-subagents` and configured
+   cross-family gates are standing, scope-bound authorization. Some harnesses
+   require this tier—for example Cursor task subagents when native model
+   availability cannot satisfy the resolved project target.
+3. **Agent-improvised CLI/programmatic or cross-runtime:** Prohibited unless
+   the user explicitly approves the named target and scope for the current
+   run. Approval from a prior run, task, branch reset, or materially different
+   scope does not carry forward.
+
+Availability of a provider CLI, SDK, API, or other programmatic surface is
+capability evidence, not route authorization. The engine must distinguish a
+policy-resolved alternate route from one proposed by the agent. If neither
+configured policy nor current explicit approval authorizes the alternate
+route, use an eligible native route or block.
+
+Do not re-prompt for each task or gate when the caller provides a complete
+policy-resolved route and scope. Record `selection_source: policy-resolved`
+with the owning configuration evidence. Use
+`selection_source: explicit-user` for a current-run operator grant and
+`selection_source: native-default` for the preferred native route.
+
 ## Dispatch Axes
 
 Keep these controls independent in selection and evidence:
 
-- dispatch context: root native, nested native, provider CLI, workflow, gate,
-  or blocked;
+- dispatch context: root native, nested native, provider CLI/programmatic,
+  workflow, gate, or blocked;
 - role or agent definition;
 - model selector and selector granularity;
 - effort or reasoning selector, when exposed;
@@ -158,11 +189,12 @@ For every dispatch:
 2. Resolve provider, context, role class, policy, ceiling, and candidates.
 3. Observe the launching dispatcher's relevant catalogs.
 4. Compute the exact native intersection.
-5. Select one native, inherited, provider-CLI, workflow, gate, or blocked route
-   before launch.
+5. Prefer an eligible native route. Otherwise select one policy-resolved or
+   explicitly authorized inherited, provider-CLI/programmatic, workflow, gate,
+   or blocked route before launch.
 6. Build the complete redacted payload.
-7. Record route, selection reason, candidates, catalog source, authority, and
-   deadline.
+7. Record route, selection source, selection reason, candidates, catalog
+   source, authority, and deadline.
 8. Launch once.
 9. Record launch acceptance separately from child outcome and runtime identity.
 

package/assets/skills/oat-dispatch-subagents/references/record-schema.md

@@ -25,6 +25,7 @@ verification_evidence: file-line-references
 deadline_seconds: 300
 retry_limit: 1
 authorization_scope: this-audit-run
+selection_source: native-default
 fallback:
   mode: explicit-downgrade
   target: reduced-quick-audit
@@ -59,7 +60,7 @@ role_selector: oat-recon-worker
 model_selector: opaque-provider-selector
 model_selector_granularity: opaque
 effort_selector: economical
-selection_source: explicit-call
+selection_source: native-default
 candidates_considered:
   - opaque-provider-selector
 selection_reason: native-catalog
@@ -78,6 +79,14 @@ continuation_events: []
 `role_selector` is the exact provider or harness agent-type selector, when that
 surface exists. Preserve opaque selectors byte-for-byte.
 
+Use `selection_source: native-default` for the preferred same-runtime native
+route, `policy-resolved` for a CLI/programmatic or cross-runtime route selected
+by configured project/workflow/gate policy, and `explicit-user` for an
+otherwise agent-proposed alternate route approved for the current run. For
+`policy-resolved`, include the owning configuration in
+`configured_invocation_evidence`. CLI or SDK availability alone is never a
+selection source.
+
 ## Recon Wave
 
 ```yaml

package/assets/skills/oat-pjm-add-backlog-item/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-add-backlog-item
-version: 1.2.0
+version: 1.3.0
 description: Use when the user requests or confirms adding a new repo backlog item — e.g. "add a backlog item for X", "capture that as backlog", "track that follow-up", "file a backlog ticket", or confirms a previously offered backlog capture. Do NOT auto-invoke when a follow-up is mentioned. Creates the item file in the file-per-item backlog structure, regenerates the index, and prompts for curated overview updates.
 disable-model-invocation: false
 user-invocable: true
@@ -98,8 +98,10 @@ ITEM_PATH=".oat/repo/pjm/backlog/items/{id}.md"
    - `labels`
    - `assignee`
    - `associated_issues`
-3. The agent should propose an initial `scope_estimate` based on the described work, then ask the user to confirm or adjust it.
-4. Write the item body with:
+   - `external_plans` (initialize to `[]`; `oat-repo-improve` owns later reverse-link additions)
+3. Keep `external_plans` as a YAML string array of repo-relative paths under `.oat/repo/reference/external-plans/`. Do not pre-populate it from discussion or anticipated work.
+4. The agent should propose an initial `scope_estimate` based on the described work, then ask the user to confirm or adjust it.
+5. Write the item body with:
    - `## Description`
    - `## Acceptance Criteria`
 
@@ -147,6 +149,7 @@ Report:
 
 - New item file exists under `.oat/repo/pjm/backlog/items/` with a `BL-YYMMDD-slug` filename matching its `id`
 - Item includes populated frontmatter and both required body sections
+- Item initializes `external_plans: []` for future reverse links
 - `scope_estimate` was proposed and confirmed
 - `oat backlog regenerate-index` ran successfully
 - `.oat/repo/pjm/backlog/index.md` remains valid, with managed section untouched except by regeneration

package/assets/skills/oat-pjm-review-backlog/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: oat-pjm-review-backlog
-version: 1.4.0
-description: Use when prioritizing the file-backed repo backlog or evaluating roadmap alignment. Produces value-effort ratings, dependency mapping, and execution recommendations.
+version: 1.5.0
+description: Use when prioritizing the file-backed repo backlog or evaluating roadmap alignment. Produces value-effort ratings, dependency mapping, execution recommendations, and an optional external-plan handoff.
 argument-hint: '[backlog-root] [--roadmap=<path>] [--output=<path>]'
 disable-model-invocation: true
 allowed-tools: Read, Write, Glob, Grep, Bash(git:*), AskUserQuestion, Task
@@ -48,13 +48,14 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print short step indicators, e.g.:
-  - `[1/7] Resolving backlog inputs…`
-  - `[2/7] Cataloging backlog items…`
-  - `[3/7] Reading codebase context…`
-  - `[4/7] Writing review document…`
-  - `[5/7] Summarizing recommendations…`
-  - `[6/7] (Optional) Priority-alignment walkthrough…` — only print after the operator accepts the offer in Step 9
-  - `[7/7] (Optional) Refreshing project kickoff handoffs…` — only print after the operator agrees a kickoff stack in Step 10
+  - `[1/8] Resolving backlog inputs…`
+  - `[2/8] Cataloging backlog items…`
+  - `[3/8] Reading codebase context…`
+  - `[4/8] Writing review document…`
+  - `[5/8] Summarizing recommendations…`
+  - `[6/8] (Optional) Priority-alignment walkthrough…` — only print after the operator accepts the offer in Step 9
+  - `[7/8] (Optional) Refreshing project kickoff handoffs…` — only print after the operator agrees a kickoff stack in Step 10
+  - `[8/8] (Optional) Handing selected items to repo improve…` — only print after the operator accepts the offer in Step 11
 
 ## Arguments
 
@@ -207,7 +208,7 @@ After the summary, ask the operator:
 
 If `.oat/repo/pjm/backlog/reviews/priority-alignment.md` already exists, frame it as an **update** to the existing document rather than a fresh create. Read the existing file first so the walkthrough builds on it.
 
-If the operator declines, stop after the summary. Do not silently write or modify `priority-alignment.md`.
+If the operator declines, skip Steps 9–10 and continue to the Step 11 external-plan offer. Do not silently write or modify `priority-alignment.md`.
 
 **If the operator accepts, run the walkthrough:**
 
@@ -246,6 +247,16 @@ This step mirrors the **Project Kickoff Handoffs** section of the pjm instructio
 
 Every backlog item reference in a handoff — like every reference in review output and alignment docs — pairs the ID with its human-readable title per the **Reference Format Convention**. No bare IDs.
 
+### Step 11: Offer External Plan Generation (Optional)
+
+After the review flow concludes, offer:
+
+> Want to turn selected items from this backlog review into self-contained external implementation plans with `oat-repo-improve`?
+
+If the operator accepts, invoke `oat-repo-improve` in `backlog-review` mode with the living review path. Also pass `backlog/reviews/priority-alignment.md` when it exists and was confirmed or refreshed during this run. The improve skill owns candidate selection, bounded live verification, plan generation under `.oat/repo/reference/external-plans/`, and backlog-item reverse links.
+
+Do not generate external plans inside this skill. Do not assume the kickoff stack must become plans; present it as the recommended selection and let the operator adjust it. A generated external plan remains optional input to `oat-project-import-plan`, not a canonical OAT project plan.
+
 ## Success Criteria
 
 - Every active backlog item file has a value-effort rating with rationale
@@ -256,4 +267,5 @@ Every backlog item reference in a handoff — like every reference in review out
 - Living review is written to `.oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review.md` (unless `--output` is explicitly overridden); dated snapshots, when emitted, live in the same `backlog/reviews/` directory and never under `.oat/repo/reviews/`
 - The operator is offered (but never forced into) a collaborative walkthrough that produces or updates `backlog/reviews/priority-alignment.md`; if the operator accepts, the file is written using the priority-alignment template and includes a Changelog entry for this pass; if the operator declines, no file is created or modified
 - When a priority-alignment pass produces an agreed kickoff stack, one handoff per kickoff-stack item is written or refreshed under `.oat/repo/pjm/handoffs/` (with item reference, recommended mode, input pointers, repo conventions/gates, and a close-out requiring the Backlog Lifecycle executed and the handoff deleted in the same shipping PR); handoffs for reprioritized-out items are deleted in the same pass; kickoff-stack membership, lane count, and ordering remain human decisions the skill presents rather than chooses
+- The operator is offered an optional `oat-repo-improve backlog-review <review>` handoff; this skill never writes external plans itself
 - Every user-facing reference to a backlog item pairs the ID with a human-readable title (per the Reference Format Convention)

package/assets/skills/oat-project-dispatch-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-dispatch-subagents
-version: 1.0.0
+version: 1.1.0
 description: Use when an OAT project lifecycle skill needs to translate project state, phase or task scope, gates, and write authority into a provider-neutral subagent dispatch.
 disable-model-invocation: true
 user-invocable: false
@@ -90,6 +90,20 @@ Project policy may cap or select a target. Translate the resolved policy and
 ceiling into the generic request; do not ask the general engine to read
 `state.md` or infer project configuration.
 
+Configured project policy is standing, scope-bound route authorization. When
+the resolver selects a CLI/programmatic or cross-runtime route, pass it to the
+general engine with `selection_source: policy-resolved` and evidence of the
+owning project, phase/task, provider, lifecycle role, policy/ceiling, and exact
+route. Do not ask the user to re-authorize that route for each task.
+
+Prefer native dispatch when it satisfies the resolved contract, but do not
+replace a required policy-resolved route merely because a weaker native surface
+exists. Cursor task subagents are a representative case: project policy may
+route through the Cursor CLI/programmatic surface when native model
+availability cannot satisfy the selected target. Configured cross-family gates
+use the same policy-resolved tier. Ambient CLI availability and stale
+conversational approval are never project policy.
+
 ## Lifecycle Roles
 
 Map each lifecycle role to a generic baseline class and add project policy:
@@ -119,9 +133,11 @@ For every lifecycle dispatch:
    limit, and fallback.
 4. Map the lifecycle role to a generic class.
 5. Add project metadata without replacing neutral request fields.
-6. Invoke `oat-dispatch-subagents` with the complete request.
-7. Preserve its generic dispatch record unchanged.
-8. Add lifecycle outcome metadata and let the calling workflow perform state,
+6. Add `selection_source: policy-resolved` plus owning configuration evidence
+   for every configured non-native route.
+7. Invoke `oat-dispatch-subagents` with the complete request.
+8. Preserve its generic dispatch record unchanged.
+9. Add lifecycle outcome metadata and let the calling workflow perform state,
    plan, implementation-log, commit, or review-table writes.
 
 Example adapter input: