@open-agent-toolkit/cli 0.3.13 → 0.3.15

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

@@ -1,184 +0,0 @@
----
-title: Skills
-description: 'User-facing guide to OAT skill families, recommended entry points, and where contributor-facing skill authoring docs live.'
----
-
-# Skills
-
-Use this section when you want to choose the right OAT skill for a task. If you are writing or changing skills, jump to the contributor docs instead.
-
-## Contents
-
-- [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.
-- [Explainer Kit](explainer-kit.md) - Agent-authored generation flow, direct and lifecycle callers, verification ladder, run package, and outcomes.
-- [Repo Improve](repo-improve.md) - Source modes, external-plan boundaries, optional tracking, and OAT import handoff.
-- [Recon Evidence Packets](recon.md) - Approved worker profiles, validated claim states, packet layout, partial outcomes, and directory-only handoff.
-
-## Key Skills by Use Case
-
-- Start a new tracked project: `oat-project-new`, `oat-project-quick-start`, or `oat-project-lite` for a single-sitting change with one batched interview and one approval (quick start accepts a project name plus optional description; if you omit the description it should ask before discovery begins)
-- Resume an existing project: `oat-project-open` and `oat-project-progress`
-- Execute a ready plan: `oat-project-implement`
-- Import an existing plan: `oat-project-import-plan`
-- Split a broad discovery or brainstorm into child projects: `oat-project-split`
-- Retroactively capture existing work: `oat-project-capture`
-- Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
-- Generate an evidence-grounded project retrospective, apply approved repo
-  improvements, or file tracker feedback: `oat-project-retro` and
-  `oat-project-retro-file`. See
-  [Project Retrospectives](../projects/retro.md).
-- 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`
-- Operate an explicit GitHub, Linear, or Jira planning-record binding through a
-  live host capability: `oat-pjm-remote`. The OAT CLI retains policy, preview,
-  approval, journal, and verification authority; the skill discovers and
-  invokes only the exact host action emitted for one durable operation.
-- 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.
-- Choose what to delegate and route bounded work by task class across Codex, Claude, or Cursor: `subagent-orchestration`. It is self-contained and usable without OAT; live catalogs and current instructions take precedence over its dated provider examples.
-- Build visual project explainers and final project recaps: `oat-explainer-kit`, backed by the destination-neutral `explainer-kit` core. See [Explainer Kit](explainer-kit.md).
-- 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`
-- Run a wave program over a corpus of external plans: `oat-wave-program` (durable program artifact: new/refresh/wave-close) and `oat-wave-execute` (one wave as a wrapper project) — see [Wave Workflows](../wave-workflows.md)
-- Research a topic in depth: `deep-research`
-- Acquire and validate bounded evidence for another workflow: `recon`
-- Analyze an artifact, codebase, or document: `analyze`
-- Compare options with domain-aware dimensions: `compare`
-- Verify a claim adversarially: `skeptic`
-- Merge multiple analysis artifacts: `synthesize`
-- Capture or refine ideas: `oat-idea-new` (capture a new idea), `oat-idea-ideate` (resume an existing tracked idea or expand a scratchpad seed — not for blank-slate brainstorms; use `oat-brainstorm` for those), `oat-idea-scratchpad`, `oat-idea-summarize`
-- Run a project-independent brainstorming conversation: `oat-brainstorm` — entry point with an explicit activation contract. Hard Activation fires only on the `brainstorm` verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or `/oat-brainstorm`); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, runs a structured design conversation (one question at a time, 2-3 approaches with a recommendation) and routes to inline / doc-to-path / idea / backlog item / project handoffs based on installed packs. See [Tool Packs](../../cli-utilities/tool-packs.md) for the brainstorm pack details.
-
-## Remote host execution loop
-
-Use `oat-pjm-remote` only for an explicit remote lifecycle request. Its loop is
-deliberately narrow:
-
-1. Before the first provider-contacting command, inspect currently granted MCP
-   or connector descriptions for a semantic and exact-context match.
-2. If no capable connector is available, inspect an already configured
-   provider CLI's live help before the first attempt. Do not install a tool,
-   retain its dialect, or switch execution surfaces mid-attempt.
-3. Construct only bounded provider-neutral capability evidence and pass it to
-   the requested command with `--capability-evidence-stdin`. Treat the CLI's
-   policy, preview, approval, safety, and durable state as authoritative.
-4. When the CLI returns `pending` with `externalAction`, execute that exact
-   semantic action at most once and submit one bounded,
-   sanitized observation with `oat pjm remote operation continue`.
-5. Continue only when the CLI emits another exact action for the same durable
-   operation. Stop on its terminal envelope.
-
-The skill cannot broaden the normalized projection, bypass effective policy,
-binding clamps, purpose field grants, hard approval floors, or caller-owned
-authority evidence, read credential values, persist native provider data, or
-declare remote success. A connector result, process exit, or visible remote
-change is only evidence. Success requires an OAT `ok` envelope after
-authoritative read-back.
-See [Remote Project Management](../../cli-utilities/remote-project-management.md)
-for policy, storage, approval, and recovery details.
-
-## If You Are Trying To...
-
-- choose the right skill for a task, stay in this guide page
-- write or update a skill, use [Writing Skills](../../contributing/skills.md)
-- understand how docs-specific skills fit with docs commands, use [Docs Workflows](../../docs-tooling/workflows.md)
-
-## Full Catalog
-
-=== "Project lifecycle"
-
-    - `oat-project-new`
-    - `oat-project-quick-start`
-    - `oat-project-lite`
-    - `oat-project-import-plan`
-    - `oat-project-promote-spec-driven`
-    - `oat-project-open`
-    - `oat-project-clear-active`
-    - `oat-project-discover`
-    - `oat-project-spec`
-    - `oat-project-design`
-    - `oat-project-plan`
-    - `oat-project-plan-writing`
-    - `oat-project-split`
-    - `oat-project-implement`
-    - `oat-project-progress`
-    - `oat-project-next`
-    - `oat-project-capture`
-    - `oat-project-reconcile`
-    - `oat-project-review-provide`
-    - `oat-project-review-provide-remote`
-    - `oat-project-review-receive`
-    - `oat-project-review-receive-remote`
-    - `oat-project-pr-progress`
-    - `oat-project-pr-final`
-    - `oat-project-document`
-    - `oat-project-retro`
-    - `oat-project-retro-file`
-    - `oat-explainer-kit`
-    - `oat-wrap-up`
-    - `oat-project-complete`
-    - `oat-wave-program`
-    - `oat-wave-execute`
-
-=== "Ideas"
-
-    - `oat-idea-new`
-    - `oat-idea-ideate`
-    - `oat-idea-scratchpad`
-    - `oat-idea-summarize`
-
-=== "Brainstorming"
-
-    - `oat-brainstorm`
-
-=== "Docs and instructions"
-
-    - `authoring-docs`
-    - `oat-docs-authoring`
-    - `oat-docs-bootstrap`
-    - `oat-docs-analyze`
-    - `oat-docs-apply`
-    - `oat-agent-instructions-analyze`
-    - `oat-agent-instructions-apply`
-
-=== "Review, backlog, and maintenance"
-
-    - `oat-review-provide`
-    - `oat-review-provide-remote`
-    - `oat-review-receive`
-    - `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`
-    - `oat-pjm-remote`
-    - `docs-completed-projects-gap-review`
-
-=== "Research"
-
-    - `recon`
-    - `deep-research`
-    - `analyze`
-    - `compare`
-    - `skeptic`
-    - `synthesize`
-
-=== "Scaffolding and utility"
-
-    - `subagent-orchestration`
-    - `explainer-kit`
-    - `oat-worktree-bootstrap`
-    - `oat-worktree-bootstrap-auto`
-    - `create-oat-skill`
-    - `create-agnostic-skill`
-    - `create-pr-description`
-    - `create-ticket`
-    - `codex-skill`
-
-## Discovery Source
-
-`AGENTS.md` is the session-facing registry. It should stay aligned with skill frontmatter and the canonical skill directories under `.agents/skills/`.
-
-Legacy compatibility note: `review-backlog` and `update-repo-reference` may still exist in some environments, but prefer the `oat-pjm-*` family for the current file-backed backlog/reference workflow.

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

@@ -1,89 +0,0 @@
----
-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 canonical OAT phase/task IDs or lifecycle bookkeeping. External execution-readiness metadata is a separate thing and is carried deliberately: it describes whether the plan's own prerequisites have merged, not how an OAT project is moving through phases.
-
-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.
-
-## Plan readiness and execution readiness
-
-Improve scores candidates on two independent axes. A candidate is plan-ready when it is understood well enough to write a self-contained executable plan, and execution-ready when every hard dependency it names has already merged.
-
-A blocked candidate is still planned. Rather than dropping work whose prerequisite has not landed, improve writes the plan and records the block:
-
-- `oat_execution_status` is `READY` or `BLOCKED` in plan frontmatter.
-- A typed `## Dependencies` table marks each row `Hard`, `Soft`, or `Satisfied`, and every `Hard` row names the state that would unblock it.
-- `## Landing-event impact` records what to re-anchor when a named PR or project lands, and `## Revalidation Before Execution` records when the plan must be re-checked against live state.
-
-Plan provenance is recorded as two separate SHAs: `oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected, and `oat_external_plan_main_commit` is the fetched `origin/main` or merge-base used only for comparison. They may differ, and normally do when planning happens on a branch.
-
-Plans written before this contract landed are read in legacy mode: a short SHA, a missing comparison SHA, missing sections, and a missing status (read as `READY`) are all accepted, and those plans are never rewritten.
-
-## 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 bounded read-only reconnaissance while the root
-agent retains classification, vetting, prioritization, cross-lane synthesis,
-and plan writing. Plan writes never move below the caller's model class — a
-parallelized author runs on the caller's model and every plan is
-caller-reviewed before publication or wave composition; the
-`keeps external-plan writes on the caller's model class` case in
-`skills-bundled-docs-contract.test.ts` is the backstop. Before launch, the
-caller loads the durable task classes and model-selection principles from
-`subagent-orchestration` plus exactly one active-provider selection reference.
-
-The internal `oat-dispatch-subagents` skill then owns capability checks, live
-catalog intersection, exact route selection, launch acceptance, recovery, and
-dispatch records. It loads exactly one matching provider mechanics reference;
-selection and mechanics references are not merged into one universal provider
-contract. 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/docs/workflows/wave-workflows.md

@@ -1,77 +0,0 @@
----
-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.
-
-## The Two Wave Skills
-
-The workflow pack provides two complementary skills:
-
-- `oat-wave-program` 1.1.0 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.5.0 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. Contract work is deferred in **BL-260718-document-execution-program — Document execution-program artifact as stable OAT contract**, grouped with **BL-260718-add-oat-wave-lifecycle-cli — Add oat wave lifecycle CLI command family**.
-
-Until that grouped work ships, consumers should follow the bundled skill and template rather than depending on an independently versioned schema.
-
-## Related
-
-- [Project lifecycle](projects/lifecycle.md)
-- [Implementation execution](projects/implementation-execution.md)
-- [Project artifacts](projects/artifacts.md)