@open-agent-toolkit/cli 0.1.53 → 0.1.55

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,59 @@
+---
+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.
+
+## Set repo-audit boundaries
+
+Fresh repo audits exclude agent-configuration directories from findings and plan candidates by default. The canonical default directory names are `.agents/`, `.claude/`, `.codex/`, and `.cursor/` at any depth. These locations commonly contain provider configuration, generated views, or externally sourced skills rather than the product surfaces being reviewed.
+
+Before reconnaissance, improve shows that default and asks whether to:
+
+- Keep all four exclusions.
+- Include selected directory names.
+- Include all four directory names.
+
+It then asks whether any other repo-relative directories should be excluded and suggests other recognizable provider directories when present. The resolved scope is shown before work begins and is applied consistently to direct searches and delegated audit lanes.
+
+These are findings exclusions, not absolute read prohibitions. Improve may read bounded instruction, convention, or intent files inside an excluded directory to understand the repository, but it does not turn those files into findings or plan candidates unless the user includes or explicitly targets that directory. A file cited by an artifact-backed source can still be verified after scope confirmation; symlinked provider views are never followed outside the repository.
+
+## 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.55",
+  "docs-config": "0.1.55",
+  "docs-theme": "0.1.55",
+  "docs-transforms": "0.1.55"
 }

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: