@open-agent-toolkit/cli 0.3.13 → 0.3.15

package/README.md

@@ -72,7 +72,7 @@ Use these commands when you want structured runtime/project state out of the CLI
 ## Docs
 
 - [Docs Home](https://voxmedia.github.io/open-agent-toolkit/)
-- [CLI Utilities](https://voxmedia.github.io/open-agent-toolkit/cli-utilities)
+- [CLI Utilities](https://voxmedia.github.io/open-agent-toolkit/reference#general-cli-adoption-guidance)
 - [Provider Sync](https://voxmedia.github.io/open-agent-toolkit/provider-sync)
 - [Instruction Sync](https://voxmedia.github.io/open-agent-toolkit/provider-sync/instruction-sync)
 - [Reference](https://voxmedia.github.io/open-agent-toolkit/reference)

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.13"
+  "oatVersion": "0.3.15"
 }

package/assets/docs/contributing/index.md

@@ -10,7 +10,7 @@ Use this section when you are changing OAT itself rather than consuming it as a
 ## Contents
 
 - [Contributing Code](code.md) - Repo setup, monorepo structure, quality gates, and PR expectations.
-- [Contributing Docs](documentation.md) - Docs contract, local docs workflow, and docs-specific authoring guidance.
+- [Contributing to OAT Docs](documentation.md) - Docs contract, local docs workflow, and docs-specific authoring guidance.
 - [Markdown Features](markdown-features.md) - Supported docs syntax for callouts, tabs, Mermaid, and code blocks.
 - [Writing Skills](skills.md) - Skill authoring guidance, runtime contracts, and governance.
 - [CLI Design Principles](design-principles.md) - Cross-cutting CLI architecture and UX principles.
@@ -19,3 +19,16 @@ Use this section when you are changing OAT itself rather than consuming it as a
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
 - [Updating Model Guidance](updating-model-guidance.md) - Source map and verification checklist for provider model refreshes.
 - [Verifying Cursor Pins](verifying-cursor-pins.md) - Runbook for probe-verifying a Cursor model pin before shipping it.
+
+## Source-of-truth hierarchy
+
+When you document OAT behavior, check it against these sources, highest
+first:
+
+1. Runtime behavior: `packages/cli/src/**`
+2. Skill behavior contracts: `.agents/skills/*/SKILL.md`
+3. OAT templates and runtime state: `.oat/templates/**`, `.oat/sync/**`, `.oat/config.json`, `.oat/config.local.json`
+4. Repo reference records: `.oat/repo/**`
+
+New pages belong in one of the top-level sections listed on the
+[docs home page](../index.md); the older `guide/` section no longer exists.

package/assets/docs/contributing/markdown-features.md

@@ -62,6 +62,44 @@ Fenced code blocks with `mermaid` are rendered as diagrams.
       A[Read docs tree] --> B[Generate index]
     ```
 
+Rendered Mermaid diagrams use the site palette. Click or tap one to open it
+full screen at a legible size; on a phone, pan to see the rest. Press Escape,
+the close button, or click again to close it.
+
+## Images and Diagram SVGs
+
+Every Markdown image opens in a zoom view when clicked. SVG images open full
+screen at a legible size, like Mermaid diagrams. Put images under
+`public/` and link them with a root-relative path such as
+`/diagrams/name.svg`; the site adds its base path.
+
+Name a pair of files `<name>-light.<ext>` and `<name>-dark.<ext>` to show one
+image per site theme. Place both images together; each is shown only in its
+theme.
+
+A diagram that needs to read well, especially on a phone, gets a hand-drawn SVG
+pair next to its Mermaid source. Mermaid stays the source of truth: when you
+change the Mermaid, update both SVGs in the same change.
+
+=== "Syntax"
+
+    ````text
+    === "Diagram"
+
+        ![What the diagram shows](/diagrams/name-light.svg)
+        ![What the diagram shows](/diagrams/name-dark.svg)
+
+    === "Mermaid source"
+
+        ```mermaid
+        flowchart LR
+          A[Read docs tree] --> B[Generate index]
+        ```
+    ````
+
+The alt text describes what the diagram shows and claims nothing the Mermaid
+does not.
+
 ## Tabs
 
 Tab groups use the existing tab transform syntax:

package/assets/docs/contributing/skills.md

@@ -363,7 +363,7 @@ The Gate Execution step should:
 
    A null, missing, malformed, or unrecognized result is an operational failure
    that fails closed as unresolved. Never treat it as "no gate configured." See
-   [Per-project gate overrides](../cli-utilities/workflow-gates.md#per-project-gate-overrides).
+   [Per-project gate overrides](../workflows/advanced/workflow-gates.md#per-project-gate-overrides).
 
 3. Export the resolved path with `export PROJECT_PATH` before launching the
    command shell.
@@ -387,7 +387,7 @@ that should report only the child process status, not review findings.
 Reusable lifecycle gate commands must omit `--target <id>` so the
 dispatcher can avoid the current runtime; reserve explicit targets for
 manual/debug commands or deliberate local/user-specific overrides. See
-[Workflow Gates](../cli-utilities/workflow-gates.md) for the config and command
+[Workflow Gates](../workflows/advanced/workflow-gates.md) for the config and command
 surface.
 
 ## Reading project state
@@ -438,3 +438,65 @@ The JSON output is a stable contract: the field set consumed by migrated skills
 - `.agents/skills/oat-project-implement/SKILL.md`
 - `.agents/skills/oat-project-complete/SKILL.md`
 - `.agents/skills/oat-project-review-receive/SKILL.md`
+
+## create-agnostic-skill
+
+**Invocation:** `/create-agnostic-skill verify-migration` (or
+`$create-agnostic-skill verify-migration` in Codex). The skill is
+explicit-invocation only, so use the slash or `$` form rather than asking the
+agent to pick it. These are agent instructions, not terminal commands. Supply
+a kebab-case skill name, or answer the naming question when prompted.
+
+**Prerequisites:** A repeatable workflow with a stable enough trigger,
+sequence, and outcome to be reusable, plus permission to create files in the
+repository's canonical `.agents/skills/` directory. Needs an active OAT
+project: no. Before creating another skill, check whether composition of
+existing skills would meet the need. For a new `oat-*` skill, use
+`/create-oat-skill` instead; it builds on this workflow and adds OAT
+conventions such as `{PROJECTS_ROOT}` resolution and progress banners.
+
+**Example scenario:** Your team repeatedly reviews database migrations for
+rollback assumptions, compatibility with the previous application version,
+and operator handoff. Turn that recurring review into a portable skill that
+asks for the migration and constraints, produces a review, and stops before
+running database commands. The skill is not a place to hide production
+execution behind a convenient trigger.
+
+The authoring conversation establishes when the skill should run, what it
+accepts, what it produces, which tools it needs, and what remains outside its
+authority. The agent presents a bounded file plan and asks for approval
+before creating anything. Expanding the approved file set requires another
+confirmation; approval of a `SKILL.md` does not implicitly authorize an
+unplanned collection of scripts or assets.
+
+**What it does without asking:** Before your approval it only asks questions
+and presents the file plan; if you decline, it creates nothing. After you
+approve the plan once, it creates the skill directory, its `SKILL.md`, and the
+planned supporting files without asking again, then, in a repository that
+uses OAT sync, runs `oat sync --scope project` to refresh this repository's provider views (the
+provider-specific copies such as `.claude/skills/`). For a skill whose name
+starts with `oat-`, it also runs `pnpm oat:validate-skills`. It does not
+commit, push, or install the skill at user scope.
+
+Use progressive disclosure to keep the result useful. The frontmatter's
+trigger-oriented description helps an agent choose the skill. The body
+contains the actual ordered workflow and stop conditions. Put detailed
+references, deterministic helpers, and templates in supporting directories
+only when the workflow needs them. Include both a direct invocation and a
+conversational example so users can recognize the intended trigger without
+memorizing provider-specific syntax.
+
+**Expected output:** An approved canonical skill at
+`.agents/skills/verify-migration/SKILL.md`, with its name matching the
+directory, an initial `metadata.version` of `1.0.0`, workflow steps, examples, and any
+approved support files. The authoring workflow synchronizes the project
+scope and checks tool/provider discoverability; it does not install the
+skill into the user's global scope. Canonical content remains the editable
+owner rather than being duplicated into provider views.
+
+**Next step:** Exercise the skill with a representative migration and verify
+that its instructions produce the intended review without crossing the
+execution boundary. Adjust the canonical workflow if the trigger or outcome
+is unclear, then resynchronize project views. Pack distribution, public
+publication, and user-scope installation are separate decisions, not an
+automatic consequence of local authoring.

package/assets/docs/contributing/smoke-testing.md

@@ -22,19 +22,26 @@ outcome of any particular run.
 
 ## Data flow
 
-```mermaid
-flowchart TD
-  F["Fixture template\ntools/smoke/fixture/"] --> PRE["Preflight\ninstall + auth + fixture + local oat"]
-  PRE -->|blocked| STOP["Exit before provisioning"]
-  PRE -->|ready| PREP["Prepare / provision\ndisposable worktree + isolated config + manifest"]
-  PREP --> DRIVE["Drive\nper-harness protocol"]
-  DRIVE --> AUTO["Automated: runner launches provider"]
-  DRIVE --> OP["Operator: printed command + prompt"]
-  AUTO --> COLLECT["Collect\nevidence bundle + report"]
-  OP --> COLLECT
-  COLLECT --> CLEAN["Cleanup\nmanifest-scoped"]
-  COLLECT -.->|--keep| SKIP["Cleanup skipped"]
-```
+=== "Diagram"
+
+    ![Smoke-test flow: fixture template, preflight (exit before provisioning if blocked), prepare and provision, drive automatically or by an operator, collect evidence, then manifest-scoped cleanup, skipped with --keep](/diagrams/smoke-testing-light.svg)
+    ![Smoke-test flow: fixture template, preflight (exit before provisioning if blocked), prepare and provision, drive automatically or by an operator, collect evidence, then manifest-scoped cleanup, skipped with --keep](/diagrams/smoke-testing-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      F["Fixture template\ntools/smoke/fixture/"] --> PRE["Preflight\ninstall + auth + fixture + local oat"]
+      PRE -->|blocked| STOP["Exit before provisioning"]
+      PRE -->|ready| PREP["Prepare / provision\ndisposable worktree + isolated config + manifest"]
+      PREP --> DRIVE["Drive\nper-harness protocol"]
+      DRIVE --> AUTO["Automated: runner launches provider"]
+      DRIVE --> OP["Operator: printed command + prompt"]
+      AUTO --> COLLECT["Collect\nevidence bundle + report"]
+      OP --> COLLECT
+      COLLECT --> CLEAN["Cleanup\nmanifest-scoped"]
+      COLLECT -.->|--keep| SKIP["Cleanup skipped"]
+    ```
 
 Collection runs even when the drive stage fails, so a broken run still produces
 an evidence bundle before cleanup reclaims its resources.
@@ -224,7 +231,7 @@ Reading the output:
 The evidence is organized as three layers — launcher-owned production records,
 independent durable corroboration from Git and the fixture, and the normalized
 bundle and assertion report. See
-[Evidence Layers](../workflows/projects/evidence-layers.md) for the model.
+[Evidence Layers](../workflows/advanced/evidence-layers.md) for the model.
 
 ## Cleanup and recovery
 
@@ -324,5 +331,5 @@ fixture does not pass, the workflow change is not accepted.
 ## Related
 
 - [Contributing Code](code.md)
-- [Implementation Execution](../workflows/projects/implementation-execution.md)
-- [Dispatch Ceiling](../workflows/projects/dispatch-ceiling.md)
+- [Implementation Execution](../workflows/projects/execution/implementation-execution.md)
+- [Dispatch Ceiling](../workflows/advanced/dispatch-ceiling.md)

package/assets/docs/contributing/updating-model-guidance.md

@@ -81,7 +81,7 @@ or GPT-6.1 Cursor targets until that runtime lists and verifies them.
 A 2026-09-25 desktop 3.21.18 probe added Grok 4.6 and Fable 5.1 mappings
 and moved the bundled Cursor ladder to them. The same probe showed Grok 4.7
 resolves only bare flat IDs, never bracket selectors. It still needs its own
-approved registry entry and complete per-pin evidence before admission; see [Verifying Cursor Pins](verifying-cursor-pins.md). See [Dispatch Policy](../workflows/projects/dispatch-ceiling.md#cursor-evidence-authority)
+approved registry entry and complete per-pin evidence before admission; see [Verifying Cursor Pins](verifying-cursor-pins.md). See [Dispatch Policy](../workflows/advanced/dispatch-ceiling.md#cursor-evidence-authority)
 for the distinction between catalog, configured mapping, and runtime identity.
 
 The October 1 refresh migrates Codex Sol defaults and examples to
@@ -142,5 +142,5 @@ bundled cells in the chosen scope, with a warning and a `--dry-run` preview;
 extra custom cells remain. Add `--keep-existing` to fill only missing cells.
 The active project's named ceiling is a separate policy in its `state.md`;
 a model update must not silently change it.
-See [Dispatch Policy](../workflows/projects/dispatch-ceiling.md#ownership-and-adoption)
+See [Dispatch Policy](../workflows/advanced/dispatch-ceiling.md#ownership-and-adoption)
 for config precedence and examples.

package/assets/docs/contributing/verifying-cursor-pins.md

@@ -339,5 +339,5 @@ oat sync --scope project
 ## Related
 
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner.
-- [Dispatch Policy](../workflows/projects/dispatch-ceiling.md) - How pins reach the recommendation and role files.
+- [Dispatch Policy](../workflows/advanced/dispatch-ceiling.md) - How pins reach the recommendation and role files.
 - [Provider Sync](../provider-sync/providers.md) - Provider-specific sync behavior.

package/assets/docs/docs-tooling/add-docs-to-a-repo.md

@@ -289,3 +289,35 @@ Important:
 - [`commands.md`](commands.md)
 - [`workflows.md`](workflows.md)
 - [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)
+
+## Choosing Markdown or a site framework
+
+`oat docs init --framework` (and the `oat-docs-bootstrap` skill) sets up one of
+three kinds of documentation. In all three, each folder's `index.md` has a
+`## Contents` list of its pages.
+
+| Framework      | Choose it when                                                       | What you give up                                                                                                       |
+| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Plain Markdown | People and agents read the docs in the repository; no site is needed | A rendered site and search. You keep each `## Contents` list up to date by hand                                        |
+| Fumadocs       | A Node/pnpm repository wants a hosted docs site                      | An app with dependencies and a build. A page missing from its folder's `## Contents` list is hidden from the sidebar   |
+| MkDocs         | The team already uses Python and MkDocs Material                     | Python setup (`setup-docs.sh` runs `pip install`). `oat docs nav sync` rewrites the whole `nav:` block of `mkdocs.yml` |
+
+When nothing chooses for it (a non-interactive run or `--yes`), `oat docs init`
+uses Fumadocs. That is only a default; pick the smallest option your readers
+need.
+
+- If you are a solo developer or a team that only needs guides readable in the
+  repository, choose plain Markdown. It adds no app, dependencies, or build.
+- If a Node/pnpm team wants a hosted site, choose Fumadocs. Its build hooks
+  regenerate the app-root `index.md` inventory but not the sidebar files, so run
+  `oat docs nav sync` after adding, moving, or renaming pages, commit the
+  `meta.json` files it writes, and add `oat docs nav sync --check` to your build
+  or CI yourself, because the scaffold does not.
+- If your team uses Python and MkDocs Material, choose MkDocs. Run
+  `oat docs nav sync --check` to see what would change before letting nav sync
+  rewrite `nav:`.
+- If the repository already has docs, do not initialize over them. Adopt
+  existing plain Markdown with `--adopt` (try `--dry-run` first), and record an
+  existing MkDocs site with `oat init --setup` instead of `oat docs init`. When
+  moving an MkDocs site to Fumadocs, `oat docs migrate` converts MkDocs syntax
+  and frontmatter; it only previews changes until you pass `--apply`.

package/assets/docs/docs-tooling/agent-instructions.md

@@ -0,0 +1,131 @@
+---
+title: Improve Agent Instructions
+description: Audit instruction coverage and accuracy, then apply approved recommendations without inventing repository conventions.
+---
+
+# Improve Agent Instructions
+
+Keep analysis and application separate. The analysis report establishes what
+is supported by repository evidence; apply translates selected recommendations
+into canonical instructions and provider views. Canonical instructions are
+the provider-neutral source files OAT treats as the source of truth, such as
+`AGENTS.md` and rule files under `.agents/rules/`. Provider views are the
+per-tool files, such as Cursor rule files, that `oat sync` generates from
+them. Neither skill needs an active OAT project.
+
+The analysis report is an analysis artifact: a timestamped Markdown report
+that analyze writes under `.oat/repo/analysis/` and that apply later reads.
+
+The invocations below are agent instructions, not terminal commands. Use
+slash names where supported, `$name` in Codex, or ask for the skill by name.
+
+## oat-agent-instructions-analyze
+
+**Invocation:** `/oat-agent-instructions-analyze` in the repository you want
+to evaluate. Confirm the provider scope when prompted so the audit covers
+the instruction formats your team actually uses.
+
+**Prerequisites:** A Git repository with at least one instruction file (root
+`AGENTS.md` is the baseline), accessible configuration/documentation evidence,
+and `jq` for the helper scripts. OAT documentation configuration is useful when present but not
+required for discovering the repository's documentation surfaces. No active
+project is required.
+
+**Example scenario:** Claude, Cursor, and Codex users receive inconsistent
+test instructions, and a nested package has no clear ownership guidance.
+Audit the canonical instructions and relevant provider views against actual
+package scripts and local documentation before copying another provider's
+rules into every directory.
+
+The audit checks quality, coverage, existing-rule accuracy, progressive
+disclosure, file-type opportunities, and cross-format consistency. Full or
+delta analysis follows valid tracking evidence. Claims about exhaustive
+consistency need exhaustive evidence, not a convenient sample. Formatting
+tools and canonical documentation are often better linked than restated as
+large always-loaded instruction blocks.
+
+Provider recommendations follow configured policy. For example, a Claude
+shim (a `CLAUDE.md` file whose job is to import `AGENTS.md` with
+`@AGENTS.md`) is not universally required. The setting
+`instructions.claude.shims` chooses the strategy. Under the default, `none`,
+Claude Code reads `AGENTS.md` itself, so analysis recommends no `CLAUDE.md`.
+Under `pointer`, `symlink`, or `copy`, it checks for the matching shim next
+to each `AGENTS.md`.
+
+Some `CLAUDE.md` files hold the only copy of instructions that an
+`AGENTS.md` links to. For those files, the recommended fix is to move the
+content into each linking `AGENTS.md` first and only then remove the file.
+A duplication finding is never permission to discard the sole copy of
+useful guidance.
+
+**Expected output:** A human-readable
+`.oat/repo/analysis/agent-instructions-<timestamp>.md` report and its
+companion bundle. The companion bundle is a folder next to the report
+(`agent-instructions-<timestamp>.bundle/`) that holds `summary.md`,
+`recommendations.yaml`, and one recommendation pack file per recommendation
+under `packs/`. The bundle is what apply generates from; the Markdown report
+provides review context. The default bounded artifact-review loop can
+correct these outputs but cannot edit downstream instruction files. Skipped
+review and residual findings remain visible in the handoff.
+
+**What it does without asking:** It writes the report and companion bundle
+under `.oat/repo/analysis/`, lets its review loop correct them, and updates
+its tracking record in `.oat/tracking.json`. It does not create or modify
+instruction files or repository configuration.
+
+**Next step:** Review the recommendations and use
+[oat-agent-instructions-apply](#oat-agent-instructions-apply) for approved
+changes. Resolve missing evidence in analysis rather than making apply guess
+which convention new files should follow.
+
+## oat-agent-instructions-apply
+
+**Invocation:** `/oat-agent-instructions-apply` after reviewing an analysis
+artifact. Choose batch approval, recommendation-by-recommendation review,
+discussion, or cancellation when the skill presents the plan.
+
+**Prerequisites:** A Git repository, `jq`, the installed
+`oat-agent-instructions-analyze` skill (apply reuses its scripts and stops if
+it cannot find them), and a recent analysis artifact. Apply always reads the
+newest `.oat/repo/analysis/agent-instructions-*.md` report. Each
+recommendation needs evidence, confidence, a disclosure decision (whether
+the item is written inline, added only as a link, omitted, or left for you
+to decide), and concrete link targets for link-only recommendations. When a
+companion bundle exists, it is the primary generation contract; older
+Markdown-only artifacts remain supported. `gh` is needed only if you want
+apply to open the pull request. No active OAT project is required.
+
+**Example scenario:** The audit recommends fixing one inaccurate test command
+and adding scoped guidance to a package. Approve those two changes, but
+decline a proposed always-loaded architecture summary in favor of its
+documentation link. The resulting instructions should preserve that
+disclosure choice rather than copying the full summary into every provider.
+
+Apply may reopen cited sources to verify them and generate instruction text,
+but cannot add new recommendations or infer a formatting rule from tool
+defaults. Missing preferred patterns, evidence, or link targets are reasons
+to stop for clarification. Provider baselines must already be explicit in
+the analysis, including which shim strategy applies.
+
+**Expected output:** Approved canonical instruction and rule changes
+committed on a new `oat/agent-instructions-<timestamp>` branch, with
+regenerated provider views where needed. The plan and source-backed
+rationale remain aligned with the analysis bundle.
+
+**What it does without asking:** Nothing changes until you approve the plan
+(choosing `cancel`, or skipping every item, exits without changes). After
+approval, apply continues without asking again. It creates branch
+`oat/agent-instructions-<timestamp>` and writes the approved files. Items
+whose disclosure is `ask_user` are confirmed with you once more before they
+are written. When it writes canonical rule files, it runs
+`oat sync --scope project` to regenerate the provider views. It then commits
+the generated and updated files as `chore: update agent instruction files`.
+If the branch cannot be created (for example because of uncommitted
+changes), it asks you to resolve that first. After committing, it asks
+whether to push and open a pull request; only a yes pushes. The PR targets
+`main`, and its body includes the applied plan and the full analysis
+report. Finally it updates `.oat/tracking.json`.
+
+**Next step:** Review the committed diff and provider scope before you agree
+to push or open a pull request. Reanalyze when you need to evaluate new
+conventions or gaps; apply is not a second independent audit.

package/assets/docs/docs-tooling/index.md

@@ -14,6 +14,7 @@ Use this section when you are adopting the docs app workflow in a repo, maintain
 - [Add or Adopt Docs in a Repo](add-docs-to-a-repo.md) - Set up Markdown or a docs app and safely adopt existing Markdown.
 - [Documentation Commands](commands.md) - Docs CLI surface for init, migration, index generation, and nav sync.
 - [Docs Workflows](workflows.md) - How the docs CLI helpers pair with analyze/apply workflows.
+- [Improve Agent Instructions](agent-instructions.md) - Analyze instruction gaps and apply approved evidence-backed changes.
 
 ## What This Section Is
 

package/assets/docs/docs-tooling/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Docs Tooling",
-  "pages": ["add-docs-to-a-repo", "commands", "workflows"]
+  "pages": ["add-docs-to-a-repo", "commands", "workflows", "agent-instructions"]
 }