@open-agent-toolkit/cli 0.1.52 → 0.1.54

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

@@ -0,0 +1,109 @@
+# Dispatch Record Schema
+
+Load this reference only when constructing or validating dispatch evidence.
+Use neutral scope, action, role, and authority fields. Calling workflows may
+add namespaced metadata without redefining these fields.
+
+## Request
+
+```yaml
+request_id: dispatch-unique-id
+caller: oat-repo-improve
+scope: repo:packages/cli
+objective: Audit CLI correctness hotspots
+action: analysis
+role:
+  name: repo-audit-scout
+  class: recon
+provider: codex
+dispatch_context: root-native
+dispatch_policy: economy
+dispatch_ceiling: high
+authority: read-only
+expected_output: structured-findings
+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
+escalate_when:
+  - evidence requires cross-package reconciliation
+  - security impact is consequential
+```
+
+`dispatch_policy` and `dispatch_ceiling` are optional resolved inputs. The
+general engine does not resolve their source.
+
+## Record
+
+```yaml
+request_id: dispatch-unique-id
+caller: oat-repo-improve
+scope: repo:packages/cli
+objective: Audit CLI correctness hotspots
+action: analysis
+role_name: repo-audit-scout
+role_class: recon
+provider: codex
+dispatch_context: root-native
+dispatch_policy: economy
+dispatch_ceiling: high
+catalog_snapshot:
+  id: root-native-1
+  source: tool-schema
+  observed_at: 2026-07-12T00:00:00Z
+authority: read-only
+role_selector: oat-recon-worker
+model_selector: opaque-provider-selector
+model_selector_granularity: opaque
+effort_selector: economical
+selection_source: native-default
+candidates_considered:
+  - opaque-provider-selector
+selection_reason: native-catalog
+selected_route: native
+deadline_seconds: 300
+retry_limit: 1
+payload: {}
+launch_status: accepted
+child_outcome: completed
+configured_invocation_evidence: []
+runtime_confirmation: not-reported
+diagnostics: []
+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
+wave_id: repo-audit-wave-1
+scope: repo:packages/cli
+shared_dispatch_record: dispatch-unique-id
+lanes:
+  - lane_id: correctness
+    scope: packages/cli/src
+    launch_status: accepted
+    child_outcome: completed
+  - lane_id: security
+    scope: packages/cli/src
+    launch_status: accepted
+    child_outcome: completed
+```
+
+The wave scope is the aggregate boundary. Lane scope may narrow it. Use one
+shared record only when every dispatch axis listed in the main skill is
+identical.

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

@@ -0,0 +1,234 @@
+---
+name: oat-project-dispatch-subagents
+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
+allowed-tools: Read, Bash
+---
+
+# Dispatching OAT Project Subagents
+
+Use this internal adapter for OAT project lifecycle delegation. It resolves
+project policy and lifecycle authority, then invokes `oat-dispatch-subagents`
+for provider selection, launch, recovery, and generic evidence.
+
+## Progress Indicators (User-Facing)
+
+This skill is an internal dependency; the calling project lifecycle skill owns
+progress indicators and decides whether a sub-banner is useful. When surfacing
+a distinct project dispatch wave, use:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ PROJECT SUBAGENT DISPATCH
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Do not repeat the banner for every task. Return a compact project-scope and
+dispatch summary for the caller to incorporate.
+
+## Required Loading
+
+Resolve and read `oat-dispatch-subagents` from the active skill catalog before
+every lifecycle dispatch. Follow its provider-reference loading rule and
+request/record contract. Do not copy provider mechanics into this adapter.
+
+If the engine skill is unavailable, stop before project mutation or child
+launch and tell the user to install the utility pack at the matching scope:
+
+```bash
+oat tools install utility --scope project
+```
+
+Use `--scope user` when workflows are intentionally user-scoped. Do not fall
+back to duplicated inline dispatch logic.
+
+## Ownership Boundary
+
+This adapter owns:
+
+- active project, workflow mode, phase, and task scope resolution;
+- project and phase dispatch policy and named ceiling resolution;
+- lifecycle role policy, gates, task IDs, write roots, commits, and worktrees;
+- translation into a generic dispatch request;
+- project-specific outcome bookkeeping layered on the generic record.
+
+The general dispatch skill owns capability, authorization, catalogs,
+candidate intersection, route selection, launch acceptance, continuation, and
+recovery. Calling lifecycle skills still own sequencing, plan mutation,
+cross-task synthesis, user checkpoints, and final artifact writes.
+
+## Resolve Project Context
+
+Resolve a user-supplied project path first. Otherwise use the active project.
+Read state through the OAT CLI source of truth rather than ad-hoc YAML parsing:
+
+```bash
+oat project status --project-path "$PROJECT_PATH" --json
+```
+
+Before dispatch, establish:
+
+- project path, workflow mode, current phase, and phase status;
+- lifecycle scope such as phase ID or `pNN-tNN` task ID;
+- declared dependencies and parallel group, when applicable;
+- task file boundary, required verification, and write authority;
+- worktree and commit expectations;
+- configured HiLL, phase-review, and lifecycle-gate requirements;
+- effective dispatch policy and named ceiling.
+
+If project state cannot be resolved or conflicts with the requested lifecycle
+scope, block before invoking the general engine.
+
+## Resolve Dispatch Policy
+
+Use the current OAT CLI resolver contract for the active provider and
+lifecycle role. Do not duplicate dispatch matrices or parse configuration
+layers directly. Preserve the resolver's exact candidate selectors and
+provider arguments.
+
+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:
+
+| Lifecycle role             | Generic class | Project-specific contract                                                                                                                |
+| -------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Phase coordinator          | `coordinator` | Own one phase dossier. Prefer an explicit suitable native target; inherit only when the root/session target is deliberately suitable.    |
+| Task worker                | `worker`      | Own one task and bounded files. Use an explicit native or pre-selected alternate target; never silently inherit an expensive root model. |
+| Fix worker                 | `worker`      | Own listed findings and bounded files. Preserve retry/fix-loop limits and original task context.                                         |
+| Planning self-review       | `reviewer`    | Inherit the planning parent by default unless the plan-writing contract requires an exact independent reviewer.                          |
+| Implementation self-review | `reviewer`    | Target the resolved reviewer ceiling; inherit only when the review-owning dispatcher is known to satisfy it.                             |
+| Phase gate                 | `reviewer`    | Use the configured independent target and fail closed when unavailable.                                                                  |
+| Lifecycle gate             | `reviewer`    | Stay independent of producer context and fail closed rather than substituting same-context self-review.                                  |
+
+The calling lifecycle skill remains authoritative when its reviewed contract
+is stricter than this table.
+
+## Adapt the Request
+
+For every lifecycle dispatch:
+
+1. Validate project state and requested phase/task scope.
+2. Resolve lifecycle role policy, provider, named ceiling, and exact
+   configuration through current CLI interfaces.
+3. Define objective, bounded files or read scope, expected output,
+   verification evidence, escalation conditions, authority, deadline, retry
+   limit, and fallback.
+4. Map the lifecycle role to a generic class.
+5. Add project metadata without replacing neutral request fields.
+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:
+
+```yaml
+project_path: .oat/projects/shared/example
+project_mode: quick
+project_phase: implement
+scope: p01-t02
+lifecycle_role: task-worker
+file_boundary:
+  - packages/cli/src/example.ts
+verification:
+  - pnpm --filter @open-agent-toolkit/cli test
+commit_policy: one-commit-per-task
+worktree: root
+```
+
+Example namespaced metadata added to the generic request:
+
+```yaml
+project:
+  path: .oat/projects/shared/example
+  mode: quick
+  phase: implement
+  phase_id: p01
+  task_id: p01-t02
+  file_boundary:
+    - packages/cli/src/example.ts
+  commit_policy: one-commit-per-task
+  worktree: root
+```
+
+## Coordinator and Worker Topology
+
+Use a phase coordinator only when the lifecycle workflow declares that
+topology. A coordinator may dispatch task workers when nesting and authority
+permit it, but it must not widen task boundaries, alter plan sequencing, or
+take over user checkpoints.
+
+For parallel groups, preserve plan-declared isolation. Each worktree receives
+only its assigned phase/task boundaries and must not mutate sibling worktrees.
+The root lifecycle workflow retains merge ordering and conflict resolution.
+
+## Gates and Independence
+
+Gate independence is project policy layered on the generic reviewer class.
+Resolve the configured gate target before launch and pass it as exact selection
+input. If the required independent target cannot be enforced, block the gate;
+do not silently downgrade to producer-context review.
+
+Treat gate artifacts, receive eligibility, and lifecycle disposition as caller
+concerns. The dispatch engine returns evidence and output but does not mutate
+review tables or project state.
+
+## Lifecycle Record Extension
+
+Preserve the generic record and attach project metadata separately:
+
+```yaml
+project_dispatch:
+  project_path: .oat/projects/shared/example
+  workflow_mode: quick
+  phase: implement
+  phase_id: p01
+  task_id: p01-t02
+  lifecycle_role: task-worker
+  file_boundary:
+    - packages/cli/src/example.ts
+  worktree: root
+  commit_policy: one-commit-per-task
+  gate_requirement: none
+generic_dispatch_record: dispatch-unique-id
+lifecycle_outcome:
+  task_status: complete
+  verification_status: passed
+  commit: abc1234
+```
+
+Do not rewrite generic route, selector, acceptance, outcome, or diagnostic
+fields inside the lifecycle extension.
+
+## Failure Boundaries
+
+- Invalid or stale project state: block before generic dispatch.
+- Scope outside the plan or assigned worktree: block and return to the caller.
+- Incomplete resolver result: do not invent a target; surface the diagnostic.
+- Generic pre-start rejection: apply caller retry policy through the general
+  engine.
+- Accepted child failure: return the terminal outcome to the lifecycle caller;
+  do not select a replacement automatically.
+- Required gate target unavailable: fail closed.
+- Verification or commit failure after worker completion: lifecycle caller owns
+  repair and bookkeeping; do not falsify the child outcome.