@open-agent-toolkit/cli 0.1.20 → 0.1.22

package/assets/skills/oat-docs-authoring/references/oat-fumadocs-contract.md

@@ -0,0 +1,77 @@
+---
+title: OAT Fumadocs authoring contract
+description: Authored source, navigation, link, file-type, generated-index, and exception rules for OAT/Fumadocs docs apps.
+---
+
+# OAT Fumadocs Authoring Contract
+
+The OAT/Fumadocs contract is tooling-critical. It is not just style.
+
+## Authored Source of Truth
+
+- Author content under the authored docs root, usually `docs/` inside the docs
+  app.
+- Every Markdown-bearing content directory has an authored `index.md`.
+- Every authored `index.md` that represents a content directory has a
+  `## Contents` section.
+- `## Contents` lists sibling pages and immediate child directories for that
+  directory.
+- If you create a child directory, create `child/index.md` and link it from the
+  parent as `child/index.md`.
+
+## Links in `## Contents`
+
+Use file-path-friendly relative Markdown links:
+
+- leaf page: `[Title](page.md)`;
+- child directory: `[Section](section/index.md)`;
+- avoid extensionless local docs links for new authored navigation entries;
+- preserve anchors only when the target heading exists and the local renderer
+  supports the anchor.
+
+Existing extensionless links are drift, not precedent. Normalize them only when
+the task scope or an approved recommendation covers that change.
+
+## File Types
+
+- Prefer `.md` for plain content pages.
+- Use `.mdx` only for pages that need JSX, imports, custom components, or other
+  MDX-only behavior.
+- Do not create `overview.md` as a directory entrypoint. Use `index.md` with
+  `## Contents`.
+- Add or preserve at least `title` and `description` frontmatter on touched
+  pages unless local guidance defines a stricter schema.
+
+## Generated Root Indexes
+
+Many OAT/Fumadocs apps have an app-root generated `index.md` that rolls up the
+authored docs tree. Treat it as generated output.
+
+- Do not hand-edit generated root indexes.
+- Regenerate or freshness-check them through local scripts when navigation
+  changes.
+- Do not treat a generated-root entry as proof that the nearest parent
+  `## Contents` is healthy.
+- If generated output is intentionally gitignored or locally absent, record that
+  in the handoff instead of inventing a manual replacement.
+
+## Exceptions and Local Extensions
+
+- Asset-only directories do not need `index.md` unless local guidance says so.
+- Build output, hidden tool directories, and generated artifacts are not content
+  directories.
+- Optional Fumadocs metadata files, such as `meta.json`, may refine sidebar
+  presentation when local style uses them. They do not replace `## Contents`.
+- Preserve local audience routers, ownership notes, and app-shell
+  customizations.
+
+## Quick Check
+
+For every touched directory or page, confirm:
+
+- content directory has `index.md`;
+- local `index.md` has useful `## Contents`;
+- new links include `.md` or `subdir/index.md`;
+- generated root index was not hand-edited;
+- `.mdx` has a real reason;
+- no new `overview.md` entrypoint was introduced.

package/assets/skills/oat-docs-authoring/references/targeted-authoring-workflow.md

@@ -0,0 +1,61 @@
+---
+title: Targeted OAT docs authoring workflow
+description: Focused edit loop for small OAT/Fumadocs documentation authoring and restructuring tasks.
+---
+
+# Targeted OAT Docs Authoring Workflow
+
+Use this workflow when the user asks for a focused docs addition, repair, move,
+or review inside an existing OAT/Fumadocs docs app.
+
+## 1. Bound the Change
+
+- Restate the requested target in terms of pages or directories.
+- Identify whether the work is content authoring, local restructuring, link
+  repair, or review.
+- If the task becomes setup, repo-wide audit, recommendation-driven apply,
+  project-derived documentation, or full migration work, stop and route through
+  `references/lifecycle-boundaries.md`.
+
+## 2. Gather Evidence
+
+- Read local instructions before editing.
+- Inspect current docs pages in the target area.
+- Inspect source code, package scripts, CLI help, schemas, tests, or deployment
+  files needed to support factual claims.
+- Use `authoring-docs` for page type, evidence quality, writing style,
+  templates, and review rubric.
+
+## 3. Preserve Local Navigation
+
+- Read the nearest authored map before changing a page.
+- For moves or renames, update links to the old path in the same change.
+- Preserve local audience routers, area ownership notes, and sidebar metadata
+  when present.
+
+For page moves and renames:
+
+- update both the old parent and new parent `## Contents` sections;
+- search for links to the old path before finishing;
+- preserve optional local sidebar metadata, such as `meta.json`, when present;
+- regenerate or freshness-check the generated root index after authored maps
+  change;
+- do not treat a generated-root entry as proof that the nearest parent map is
+  correct.
+
+## 4. Validate Locally
+
+- Read package scripts before choosing validation commands.
+- Run generation or validation scripts that are relevant to the touched files.
+- For render-sensitive Markdown, inspect the rendered result when practical.
+
+## 5. Report Clearly
+
+Handoff with:
+
+- files changed;
+- source evidence inspected;
+- maps and links updated;
+- generated artifacts checked or regenerated;
+- validation command results;
+- unresolved facts or owner-review items.

package/assets/skills/oat-docs-authoring/references/validation.md

@@ -0,0 +1,61 @@
+---
+title: OAT docs authoring validation
+description: Local validation, generated-index checks, and render spot-check guidance for targeted OAT/Fumadocs docs changes.
+---
+
+# OAT Docs Authoring Validation
+
+Validation is local to the docs app. Read scripts and instructions before
+choosing commands.
+
+## Script Discovery
+
+Inspect the docs app `package.json` and local instructions for:
+
+- `predev` or `prebuild` generation steps;
+- `fumadocs-mdx`;
+- `oat docs generate-index`;
+- docs lint, format, type-check, test, or build scripts;
+- intentionally disabled or no-op scripts.
+
+Use the local script names and package manager style already present in the
+repo. Do not invent universal docs commands.
+
+## Generated Index Checks
+
+When navigation, file placement, or `## Contents` changes:
+
+- regenerate the generated root index through the local command when available;
+- if generation is tied to `predev` or `prebuild`, run the smallest local
+  command that updates or checks the generated output;
+- inspect the generated diff for stale paths, missing pages, unexpected
+  ordering drift, or missing generated-file warning banners;
+- leave generated output unedited by hand.
+
+If generated output is ignored, absent by policy, or cannot be produced in the
+current environment, record the exact reason in the handoff.
+
+## Local Contract Checks
+
+Before finishing:
+
+- every touched content directory has `index.md`;
+- every touched authored `index.md` has a meaningful `## Contents`;
+- parent maps include new or moved immediate children;
+- links to moved files were updated;
+- new local navigation links use `.md` or `subdir/index.md`;
+- no new `overview.md` or unnecessary `.mdx` page was introduced.
+
+## Render Spot Checks
+
+Build success is not always enough for render-sensitive content. Spot-check the
+rendered result when changes include:
+
+- migrated MkDocs syntax;
+- callouts, tabs, Mermaid, images, iframes, or custom MDX components;
+- large link rewrites or directory moves;
+- frontmatter or metadata behavior;
+- app-shell or layout changes.
+
+Use the app's local dev or build workflow when practical. If rendering cannot
+be checked, state that explicitly.

package/assets/skills/oat-docs-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-docs-bootstrap
-version: 1.0.1
+version: 1.1.0
 description: Use when bootstrapping a new OAT docs app in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with labeled post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports Fumadocs (full path) and MkDocs (lean path with defined minimum contract).
 argument-hint: '<optional-target-dir>'
 disable-model-invocation: true
@@ -646,7 +646,7 @@ Four sub-findings, each with its own gate, target, and idempotency check. All su
 
     ## Generated files
 
-    The root-level `index.md` at `<appRoot>/index.md` is regenerated from `docs/index.md` and its `## Contents` sections on every `predev` / `prebuild`. Do not hand-edit it; edit the authored source under `docs/` instead.
+    For Fumadocs apps, the root-level generated manifest at `<appRoot>/index.md` is regenerated from the Markdown file tree under `docs/` on every `predev` / `prebuild`. Do not hand-edit it; edit the authored source under `docs/` instead, and compare the generated manifest against authored `## Contents` when checking freshness. For MkDocs apps, the derived navigation artifact is the `nav:` section of `mkdocs.yml`, not a root manifest.
 
     <!-- /FP-13 patch -->
     ```
@@ -844,7 +844,7 @@ If the `documentation` section is missing or malformed after a successful CLI in
 For each field in `documentation`, check that the referenced path exists and has the expected type:
 
 - `root`: must be a directory that exists on disk (absolute or resolved-relative to `$REPO_ROOT`).
-- `index`: must be a file that exists on disk (Fumadocs: `<appRoot>/index.md`; MkDocs: `<appRoot>/docs/index.md`). The generated root `index.md` is part of the contract even though it's regenerated every build.
+- `index`: must be a file that exists on disk. For Fumadocs, this is the generated app-root manifest at `<appRoot>/index.md`, regenerated from the Markdown file tree under `docs/`. For MkDocs, this is the authored source root at `<appRoot>/docs/index.md`; generated navigation lives in `mkdocs.yml` `nav:`.
 - `config`: MkDocs only — must be a file that exists on disk (`<appRoot>/mkdocs.yml`). For Fumadocs, this field is absent; no check needed.
 - `tooling.framework`: must match the Input Result `framework`. Mismatch is surprising and indicates drift.
 - `tooling.lint` / `tooling.format`: must match Input Result values.
@@ -928,7 +928,10 @@ Narrate each field actually present in their config (skip fields that are absent
 
 - **`documentation.root`** — the scaffolded app directory. Downstream tools (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`) use this to find "the docs" without the user having to tell them.
 - **`documentation.tooling`** — framework + lint + format. `oat-docs-analyze` uses `framework` to pick the right rule set; the tooling values also get echoed into the `## Documentation` section the CLI wrote into root `AGENTS.md`.
-- **`documentation.index`** — the authored `docs/index.md`. This is the content map (not the generated root `index.md` — that's Section B). Tools read this to understand top-level navigation intent.
+- **`documentation.index`** — branch this narration on the inspected `documentation.tooling` and path; do not describe one meaning for every framework:
+  - **Fumadocs:** this should be the generated app-root manifest, usually `<appRoot>/index.md`, after the successful build ran `oat docs generate-index`. Explain that this machine-shaped file is how tools inspect the full Markdown file tree, and that the authored source map the user edits is a separate file at `<appRoot>/docs/index.md` with its own `## Contents`.
+  - **Fumadocs stale path warning:** if the inspected path still points inside `<appRoot>/docs/` after build verification, do not teach that as normal. Surface it as a warning that `oat docs generate-index` did not update `documentation.index` as expected, then point the user to Section B for the generated/authored split.
+  - **MkDocs:** this should point at the configured MkDocs nav/config surface, usually `<appRoot>/mkdocs.yml` and matching `documentation.config`. Explain that the YAML file contains the generated/derived `nav:` block when `oat docs nav sync` is used, while authored `docs/index.md` and nested `## Contents` sections remain the source maps the user edits.
 - **`documentation.config`** (MkDocs only) — path to `mkdocs.yml`. Present for MkDocs because its chrome/nav is YAML-configured; absent for Fumadocs because chrome is code.
 - **`documentation.requireForProjectCompletion`** — the opt-in collected in Step 5e. If `true`, `oat-project-complete` will block project completion until `oat-docs-analyze` reports no open recommendations. Explain whichever value is set on this project.
 
@@ -941,17 +944,18 @@ If `Scaffold Result.rootBuildPatch` is present, narrate it here before moving on
 
 End with: "This config is how every OAT docs tool finds your docs. Editing it by hand is supported — but changes to `root` or `config` paths need to match reality on disk."
 
-#### Section B (both frameworks) — The two `index.md` files
+#### Section B (both frameworks) — Authored source and generated navigation
 
-This section prevents the footgun from FP-13 sub-finding D: users silently hand-edit the generated `index.md` and wonder why their edits vanish on the next build.
+This section prevents the footgun from FP-13 sub-finding D: users silently hand-edit the Fumadocs generated root `index.md` and wonder why their edits vanish on the next build.
 
 Narrate:
 
 - **The authored source** at `<appRoot>/docs/index.md`. This is the file the user edits. It has frontmatter (`title`, `description`) and a `## Contents` section listing direct children of the docs root. It is the top of a fractal: every directory has its own `index.md`, each with its own `## Contents`.
-- **The generated map** at `<appRoot>/index.md` (when Fumadocs — the path differs for MkDocs; use the `documentation.index` path resolved by the Inspector if it differs). Regenerated on every `predev` / `prebuild` by the `oat docs generate-index` command. Machine-shaped: rolls up every `## Contents` section in the tree into a single searchable map that tools consume. **Hand-edits are silently clobbered.**
-- **How to tell them apart when opening a file.** If the file sits inside `docs/`, it's authored. If it sits at `<appRoot>/index.md` (outside `docs/`), it's generated — and when the CLI or Scaffold-integrity FP-13/D.2 wrote the warning correctly, the first line is `<!-- AUTOGENERATED by \`oat docs generate-index\`... -->`.
+- **The Fumadocs generated map** at `<appRoot>/index.md`. Regenerated on every `predev` / `prebuild` by the `oat docs generate-index` command. Machine-shaped: inventories Markdown files with titles and descriptions so tools have a single searchable map. **Hand-edits are silently clobbered.**
+- **The MkDocs derived nav** in `mkdocs.yml` `nav:`. MkDocs does not use a Fumadocs-style generated app-root manifest; its generated/derived navigation boundary is the YAML nav block.
+- **How to tell them apart when opening a file.** If the file sits inside `docs/`, it's authored. If it sits at `<appRoot>/index.md` (outside `docs/`), it's the Fumadocs generated manifest — and when the CLI or Scaffold-integrity FP-13/D.2 wrote the warning correctly, the first line is `<!-- AUTOGENERATED by \`oat docs generate-index\`... -->`.
 
-End with: "Always edit `docs/index.md` and the `## Contents` sections. Never edit the root-level `index.md` — your edits will disappear next build."
+End with: "Always edit `docs/index.md` and the `## Contents` sections. In Fumadocs, never edit the root-level `index.md` — your edits will disappear next build. In MkDocs, treat `mkdocs.yml` `nav:` as derived from authored Contents unless the local workflow says otherwise."
 
 #### Section C (both frameworks) — The `## Contents` contract
 
@@ -962,7 +966,7 @@ Narrate:
 - **Every directory under `docs/` has an `index.md`.** No exceptions, no `overview.md`, no README-as-index. Missing `index.md`s are the first thing `oat-docs-analyze` flags.
 - **Every `index.md` has a `## Contents` section.** The section is a plain Markdown bulleted list of links to the direct children of that directory — both subdirectory `index.md`s and leaf pages.
 - **Link targets use `.md` extensions.** Leaf pages link as `[Title](page.md)`; subdirectories link as `[Section](subdir/index.md)`. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these at build time for Fumadocs routing (`.md` stripped; `dir/index.md` collapsed to `dir`). `.md`-suffixed authored links render correctly **and** let agents follow each link to the target file without path inference — the best of both worlds.
-- **The `## Contents` section is the machine-readable local map.** It's what `oat docs nav sync` reads to regenerate framework nav, what `oat docs generate-index` reads to roll up the tree, and what `oat-docs-analyze` reads to find orphaned pages.
+- **The `## Contents` section is the machine-readable local map.** For Fumadocs, it remains the authored navigation intent that agents maintain and compare against the generated app-root manifest. For MkDocs, `oat docs nav sync` reads it to update `mkdocs.yml` `nav:`. `oat-docs-analyze` reads the same authored source to find orphaned pages and stale generated artifacts.
 - **Anything not listed in `## Contents` is invisible to the tooling.** Adding a Markdown file is not enough — it must also appear under the parent `index.md`'s `## Contents`.
 
 Show the user their own `docs/index.md` `## Contents` as a concrete example (read the file and paste the relevant 5–15 lines). If `patchesApplied` includes an `FP-16` entry with `status: 'applied'`, mention it — the skill rewrote the scaffold's extension-less links to `.md`-suffixed form so agents can follow them. Then note: "That's the pattern. Every directory you create from now on follows the same shape — `.md`-suffixed links, bulleted list, dash-separated summary per entry."
@@ -1007,7 +1011,7 @@ In scope (required — share these):
 - **Material theme provides the default UI.** Light/dark toggle, responsive sidebar, search UI. Config lives under `theme:` in `mkdocs.yml`.
 - **Plugins are pip-installed and named in `mkdocs.yml`.** The scaffold's `requirements.txt` pins the plugins currently wired in. Adding a new plugin = add to both files.
 - **Python environment via `requirements.txt` + `setup-docs.sh`.** The scaffold provides a `setup-docs.sh` that creates a venv, installs `requirements.txt`, and is idempotent on re-run. Use it; the skill assumes you will.
-- **The shared concepts still apply.** The `## Contents` contract (Section C), the two `index.md` model (Section B — note for MkDocs the generated artifact is the `nav:` section of `mkdocs.yml`, not a root `index.md`), and the three agent-instruction surfaces (Section D) all transfer directly.
+- **The shared concepts still apply.** The `## Contents` contract (Section C), the authored-source/generated-navigation model (Section B), and the three agent-instruction surfaces (Section D) all transfer directly.
 
 Deferred (out of scope for this skill — point, don't teach):
 

package/assets/skills/oat-docs-bootstrap/assets/AGENTS.md.template

@@ -12,13 +12,13 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 2. Add frontmatter with at minimum `title:` and `description:`. The title drives nav display and page `<title>`; the description drives search previews, social cards, and sibling summaries. Empty descriptions hurt all three.
 3. Update the nearest `index.md`'s `## Contents` section to include a link to the new page. Use `.md`-suffixed relative links: `[Title](page.md)` for leaf pages, `[Section](subdir/index.md)` for subdirectories. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these for Fumadocs routing at build time (strips `.md`, collapses `dir/index.md` → `dir`), so the suffixed form renders correctly **and** lets agents follow links to the target file without path inference. The `## Contents` section is the machine-readable local map — anything not listed there is effectively invisible to the navigation tooling.
 4. If the new page introduces a new subdirectory, create an `index.md` in that subdirectory with its own `## Contents` section. Every content directory must have an `index.md`.
-5. Run `oat docs nav sync` (or equivalent for this framework) to regenerate any derived navigation artifacts. Derived artifacts never replace the authored `## Contents`; they're generated from it.
+5. Regenerate the derived navigation artifact for this framework. For Fumadocs, run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. For MkDocs, run `oat docs nav sync` or the local equivalent so `mkdocs.yml` `nav:` reflects authored `## Contents`. Derived artifacts never replace the authored `## Contents`; keep authored maps current and compare generated output against them when checking freshness.
 
 ## When you need to restructure navigation
 
 1. Make changes in the authored `## Contents` sections of each affected `index.md`. That is the authoritative local map.
-2. Do **not** hand-edit generated navigation artifacts. The root-level `index.md` (if present for this framework), `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten on every build.
-3. After editing `## Contents`, run the framework's nav sync command to regenerate derived artifacts.
+2. Do **not** hand-edit generated navigation artifacts. The Fumadocs app-root `index.md` manifest, `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten by the local generation workflow.
+3. After editing `## Contents`, run the framework's generation command to refresh derived artifacts.
 4. If you're moving pages between directories, update both source and destination `index.md` `## Contents` entries in the same commit so the site isn't broken mid-way through history.
 5. If you're reparenting an entire subtree, consider whether the moved directory's own `index.md` needs a revised "scope" paragraph.
 
@@ -44,7 +44,7 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 
 ## What not to do
 
-- **Don't hand-edit generated files.** The root-level `index.md` generated by `{{GENERATE_INDEX_CMD}}` is rewritten on every build. Edits to it are silently clobbered. Edit the authored source (`docs/index.md` and its `## Contents`), not the generated copy.
+- **Don't hand-edit generated files.** For Fumadocs, the root-level `index.md` generated by `{{GENERATE_INDEX_CMD}}` is rewritten on every build. For MkDocs, generated or synchronized navigation lives in `mkdocs.yml` `nav:`. Edits to derived artifacts are silently clobbered. Edit the authored source (`docs/index.md` and its `## Contents`), then regenerate.
 - **Don't default to `.mdx` when `.md` would do.** MDX adds JSX-in-Markdown capability (embedded components), which breaks simple link rewrites, confuses agent tooling, and requires imports that plain `.md` doesn't. Reach for `.mdx` only when a page actually needs a component it can't express in plain Markdown.
 - **Don't author `## Contents` links without `.md` extensions.** Extension-less links (`[Title](page)` instead of `[Title](page.md)`) force agents to infer the target file type, break simple grep-based navigation, and diverge from the convention used throughout `{{REPO_NAME}}`. The build pipeline (`@open-agent-toolkit/docs-transforms` remark-links) strips `.md` for Fumadocs routing — so suffixed authored links render correctly and stay agent-friendly.
 - **Don't invent new navigation conventions outside `## Contents`.** A sidebar config in a framework file, a hand-rolled TOC, a separate nav YAML — all of these diverge from the contract and break the tooling. Extend via `## Contents`.
@@ -60,4 +60,4 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 - `oat-docs-analyze` — read-only audit command.
 - `oat-docs-apply` — apply approved audit recommendations.
 - `oat-project-document` skill — propose evidence-backed doc updates from project artifacts.
-- `{{GENERATE_INDEX_CMD}}` — regenerates the machine-readable root `index.md` from `docs/`. Runs automatically on `predev` / `prebuild`; don't hand-edit its output.
+- `{{GENERATE_INDEX_CMD}}` — for Fumadocs, regenerates the machine-readable root `index.md` from `docs/`. Runs automatically on `predev` / `prebuild`; don't hand-edit its output.

package/assets/skills/oat-project-discover/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: oat-project-discover
-version: 2.0.2
-description: Use when starting a project or when requirements are still unclear. Runs structured discovery to gather requirements, constraints, and context.
-disable-model-invocation: true
+version: 2.0.3
+description: Use when the user explicitly asks to continue discovery for an active spec-driven OAT project — e.g. "continue discovery", "run discovery", or confirms a previously offered discovery step. Do NOT auto-invoke for new ideas or quick-mode projects. Gathers requirements and context before spec/design.
+disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Glob, Grep, AskUserQuestion
 ---
@@ -15,6 +15,20 @@ Gather requirements and understand the problem space through natural collaborati
 
 **Required:** Knowledge base must exist. If missing, run the `oat-repo-knowledge-index` skill first.
 
+**Required for model invocation:** An active spec-driven OAT project must already exist. If no active project exists, route to `oat-project-new` for spec-driven setup or `oat-project-quick-start` for quick workflow. If the active project is quick or import mode, decline this skill and route to the current mode's next step instead.
+
+## Model Invocation Gate
+
+This skill is model-invokable only for explicit discovery-continuation asks on an active spec-driven project. Do NOT auto-invoke when the user mentions a new idea, asks for a quick workflow, or has an active quick/import project.
+
+Before acting:
+
+1. Resolve `activeProject`.
+2. Confirm `{PROJECT_PATH}/state.md` exists.
+3. Confirm `oat_workflow_mode` is `spec-driven` or absent only in a legacy spec-driven project.
+
+If any check fails, decline this skill. Offer `oat-project-new` for a new spec-driven project, `oat-project-quick-start` for a quick project, or `oat-project-open` for switching to an existing project. When the gate passes, summarize the active project and ask before continuing discovery.
+
 ## Mode Assertion
 
 **OAT MODE: Discovery**
@@ -68,7 +82,7 @@ If you catch yourself:
 
 ## Process
 
-### Step 1: Resolve Active Project (or Create a New One)
+### Step 1: Resolve Active Spec-Driven Project
 
 OAT stores active project context in `.oat/config.local.json` (`activeProject`, local-only).
 
@@ -84,6 +98,10 @@ PROJECTS_ROOT="${PROJECTS_ROOT%/}"
 
 - Derive `project-name` from the directory name (basename of the path)
 - Read `{PROJECT_PATH}/state.md` (if it exists) and show current status
+- Read `oat_workflow_mode` from `{PROJECT_PATH}/state.md`
+- If `oat_workflow_mode` is present and not `spec-driven`, stop and route:
+  - quick project: continue with `oat-project-quick-start` / `oat-project-progress`
+  - import project: continue with `oat-project-import-plan` / `oat-project-progress`
 - Ask user:
   - **Continue** with active project, or
   - **Switch projects**:

package/assets/skills/oat-project-import-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-import-plan
-version: 1.3.2
+version: 1.3.3
 description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
 argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
 disable-model-invocation: true
@@ -56,13 +56,14 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print step indicators, e.g.:
-  - `[0/6] Checking inherited git state...`
-  - `[1/6] Resolving project + source plan…`
-  - `[2/6] Preserving imported source…`
-  - `[3/6] Normalizing plan to OAT task structure…`
-  - `[4/6] Updating project metadata + state…`
-  - `[5/6] Refreshing dashboard…`
-  - `[6/6] Ensuring implementation tracker…`
+  - `[0/7] Checking inherited git state...`
+  - `[1/7] Resolving project + source plan…`
+  - `[2/7] Preserving imported source…`
+  - `[3/7] Normalizing plan to OAT task structure…`
+  - `[4/7] Updating plan metadata…`
+  - `[5/7] Running import-aware plan review…`
+  - `[6/7] Updating project state + dashboard…`
+  - `[7/7] Ensuring implementation tracker…`
 
 ## Process
 
@@ -180,7 +181,7 @@ Dispatch Profile import handling:
 Set frontmatter in `"$PROJECT_PATH/plan.md"`:
 
 - `oat_status: complete`
-- `oat_ready_for: oat-project-implement`
+- `oat_ready_for: null` (Step 4.5 sets this after the import-aware plan review)
 - `oat_phase: plan`
 - `oat_phase_status: complete`
 - `oat_plan_source: imported`
@@ -188,6 +189,33 @@ Set frontmatter in `"$PROJECT_PATH/plan.md"`:
 - `oat_import_source_path: {source-path}`
 - `oat_import_provider: {codex|cursor|claude|null}`
 
+### Step 4.5: Run Import-Aware Plan Artifact Review Loop
+
+Invoke the shared `Auto Artifact-Review Loop` from `oat-project-plan-writing` with target `plan` before advancing project state or handing off to implementation.
+
+Required payload:
+
+- `target: plan`
+- `type: artifact`
+- `scope: plan`
+- `artifact_path: "$PROJECT_PATH/plan.md"`
+- `oat_output_mode: structured`
+- `import_aware: true`
+- `review_note: "Review for canonical OAT plan conformance, executable completeness, stable task IDs, required sections, review-row preservation, and verification clarity. Preserve the imported source's intent and ordering; do not rewrite the author's plan goals or product decisions unless required for OAT conformance or completeness."`
+
+Apply the shared loop exactly:
+
+- Resolve `workflow.autoArtifactReview.plan`; only an explicit `false` skips the loop.
+- Resolve `oat_orchestration_retry_limit` from project state, defaulting to `2`.
+- Dispatch `oat-reviewer` in structured mode using Tier 1 subagent when available and Tier 2 inline fallback otherwise.
+- Apply Critical and Important artifact-local fixes when unambiguous and limited to canonical conformance/completeness; offer Medium and Minor fixes instead of silently applying them.
+- Re-dispatch after rewrites until clean or the retry bound is exhausted.
+- Update the `plan` artifact row in the `## Reviews` table to `passed` when clean. If residual findings remain, preserve the row and surface the residual findings before downstream handoff.
+
+After the loop completes or is explicitly skipped, set `"$PROJECT_PATH/plan.md"` frontmatter:
+
+- `oat_ready_for: oat-project-implement`
+
 ### Step 5: Update Project State
 
 Set `"$PROJECT_PATH/state.md"` frontmatter:
@@ -245,6 +273,7 @@ Report:
 - ✅ Imported markdown preserved at `references/imported-plan.md`.
 - ✅ Canonical `plan.md` generated with OAT task structure.
 - ✅ `plan.md` metadata marks `oat_plan_source: imported`.
+- ✅ `plan.md` records the import-aware plan artifact review row unless `workflow.autoArtifactReview.plan` was explicitly disabled.
 - ✅ `state.md` marks `oat_workflow_mode: import`.
 - ✅ `implementation.md` is present and resumable.
 - ✅ `oat_plan_hill_phases` left unset in frontmatter (deferred to `oat-project-implement` Step 2.5).

package/assets/skills/oat-project-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.3.4
+version: 1.3.5
 description: Use when design.md is complete and executable implementation tasks are needed. Breaks design into bite-sized TDD tasks in canonical plan.md format.
 disable-model-invocation: true
 user-invocable: true
@@ -41,11 +41,12 @@ When executing this skill, provide lightweight progress feedback so the user can
   OAT ▸ PLAN
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-- Before multi-step work (drafting/finalizing/committing), print 2–5 short step indicators, e.g.:
-  - `[1/4] Reading design + context…`
-  - `[2/4] Drafting phases + tasks…`
-  - `[3/4] Finalizing plan + rollups…`
-  - `[4/4] Updating state + committing…`
+- Before multi-step work (drafting/finalizing/reviewing/committing), print 2–5 short step indicators, e.g.:
+  - `[1/5] Reading design + context…`
+  - `[2/5] Drafting phases + tasks…`
+  - `[3/5] Finalizing plan + rollups…`
+  - `[4/5] Running plan artifact review…`
+  - `[5/5] Updating state + committing…`
 - For any operation that may take noticeable time (e.g., reading large artifacts), print a start line and a completion line (duration optional).
 - Keep it concise; don’t print a line for every shell command.
 
@@ -293,7 +294,7 @@ This creates traceability: Requirement → Tasks → Implementation
 ### Step 10.1: Keep Reviews Table Rows
 
 Follow the review table preservation rules from `oat-project-plan-writing`:
-- Include both **code** rows (p01/p02/…/final) and **artifact** rows (`spec`, `design`)
+- Include both **code** rows (p01/p02/…/final) and **artifact** rows (`spec`, `design`, `plan`)
 - Add additional rows as needed (e.g., p03), but never delete existing rows
 
 **Why stable IDs:** Using `p01-t03` instead of "Task 3" prevents broken references when tasks are inserted or reordered.
@@ -381,12 +382,34 @@ Ask: "Does this breakdown make sense? Any tasks missing?"
 
 Iterate until user confirms.
 
+### Step 12.5: Run Plan Artifact Review Loop
+
+Invoke the shared `Auto Artifact-Review Loop` from `oat-project-plan-writing` with target `plan` before setting `plan.md` to implementation-ready.
+
+Required payload:
+
+- `target: plan`
+- `type: artifact`
+- `scope: plan`
+- `artifact_path: "$PROJECT_PATH/plan.md"`
+- `oat_output_mode: structured`
+
+Apply the shared loop exactly:
+
+- Resolve `workflow.autoArtifactReview.plan`; only an explicit `false` skips the loop.
+- Resolve `oat_orchestration_retry_limit` from project state, defaulting to `2`.
+- Dispatch `oat-reviewer` in structured mode using Tier 1 subagent when available and Tier 2 inline fallback otherwise.
+- Apply Critical and Important artifact-local fixes when unambiguous; offer Medium and Minor fixes instead of silently applying them.
+- Re-dispatch after rewrites until clean or the retry bound is exhausted.
+- Update the `plan` artifact row in the `## Reviews` table to `passed` when clean. If residual findings remain, preserve the row and surface the residual findings before downstream handoff.
+
 ### Step 13: Mark Plan Complete
 
 Before setting `oat_status: complete`, verify:
 - `## Planning Checklist` exists
 - the checklist records that checkpoint confirmation is deferred to implementation
 - if `oat_plan_hill_phases` is already present, it is intentionally preserved and valid
+- the `plan` artifact review row has been recorded by Step 12.5, unless `workflow.autoArtifactReview.plan` was explicitly disabled
 
 Update frontmatter:
 ```yaml

package/assets/skills/oat-project-plan-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan-writing
-version: 1.2.4
+version: 1.2.5
 description: Use when authoring or mutating plan.md in any OAT workflow. Defines canonical format invariants — stable task IDs, required sections, review table rules, and resume guardrails.
 disable-model-invocation: true
 user-invocable: false
@@ -23,6 +23,49 @@ This is a sub-phase indicator; the calling skill owns the top-level banner.
 
 - When invoked by a calling skill, print the sub-banner immediately before plan authoring begins.
 
+## Auto Artifact-Review Loop
+
+This is the canonical contract for bounded automated reviews of generated OAT artifacts. Calling skills own the concrete edits, progress indicators, and commits; this section defines the shared loop they must follow.
+
+Use this loop after an artifact has been written and before the calling skill hands off to the downstream consumer. Current targets:
+
+- `plan`: dispatch `oat-reviewer` with `type: artifact`, `scope: plan`, and `oat_output_mode: structured`.
+- `analysis`: dispatch `oat-reviewer` with `type: analysis`, `scope: docs` or `agent-instructions`, `analysis_artifact`, and `oat_output_mode: structured`.
+
+### Canonical Procedure
+
+1. **Resolve the gate**
+   - Read `workflow.autoArtifactReview.<target>` using the same config-resolution path as other `workflow.*` keys.
+   - Missing config means enabled. Only an explicit `false` disables the loop.
+   - If disabled, skip the review loop, note the skip in the calling skill's handoff/status output, and continue without pretending the artifact was reviewed.
+
+2. **Resolve the retry bound**
+   - Read `oat_orchestration_retry_limit` from the active project state.
+   - If absent, invalid, or unavailable, use default `2`.
+   - The bound controls rewrite/re-dispatch cycles after the initial review. A bound of `0` still permits the initial structured review, then surfaces residual findings without retrying.
+
+3. **Dispatch `oat-reviewer` in structured mode**
+   - Tier 1: use the configured `oat-reviewer` subagent when available and authorized.
+   - Tier 2: if Tier 1 is unavailable or declined, run the same reviewer prompt inline with the same payload and checklist.
+   - Always set `oat_output_mode: structured`; the loop consumes `StructuredFindings` in-memory and the reviewer writes no artifact.
+   - Do not downgrade the checklist when falling back inline. The fallback changes only execution tier, not review requirements.
+
+4. **Apply or offer fixes by severity**
+   - If the structured review is clean, proceed to outcome recording.
+   - Apply Critical and Important fixes by default when they are local to the reviewed artifact and the fix is unambiguous.
+   - Offer Medium and Minor fixes to the user instead of applying them silently.
+   - If a finding cannot be fixed within the artifact boundary, preserve it as residual and surface it before handoff.
+
+5. **Rewrite and re-dispatch within the bound**
+   - After applying fixes, rewrite the artifact and re-dispatch `oat-reviewer` with the same target payload.
+   - Each rewrite/re-dispatch cycle consumes one retry.
+   - Stop when the reviewer returns no findings or when the retry bound is exhausted.
+
+6. **Record the outcome**
+   - Record a clean pass or residual findings in the calling skill's lifecycle output before handoff.
+   - For `plan`, update the `plan` artifact row in the Reviews table without deleting any existing rows. Use `passed` when clean; if residual findings remain, preserve enough detail in the handoff for the next skill/user to act.
+   - For `analysis`, mark the analysis artifact as reviewed/verified using the calling skill's analysis-tracking convention, and surface any residual findings before the corresponding apply skill consumes it.
+
 ## Canonical Plan Format
 
 Every `plan.md` produced or edited by any OAT skill **must** satisfy these invariants.
@@ -98,7 +141,7 @@ If any required section is missing when a skill edits `plan.md`, it must be rest
 
 ### Review Table Preservation Rules
 
-- The `## Reviews` table includes both **code** rows (`p01`, `p02`, …, `final`) and **artifact** rows (`spec`, `design`).
+- The `## Reviews` table includes both **code** rows (`p01`, `p02`, …, `final`) and **artifact** rows (`spec`, `design`, `plan`).
 - Skills must **never delete** existing review rows.
 - New rows may be appended (e.g., `p03` for a newly added phase).
 - Status semantics: `pending` → `received` → `fixes_added` → `fixes_completed` → `passed`.

package/assets/skills/oat-project-progress/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: oat-project-progress
-version: 1.2.4
-description: Use when resuming work, checking status, or unsure which OAT skill to run next. Evaluates project progress and routes to the appropriate next step.
-disable-model-invocation: true
+version: 1.2.5
+description: Use when the user explicitly asks to check OAT project progress — e.g. "check progress", "what's next", "where are we", or confirms a previously offered progress check. Do NOT auto-invoke just because a workflow step completed. Reads project status and offers the next route.
+disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash(git:*), AskUserQuestion
 ---
@@ -35,6 +35,12 @@ Run `oat-project-progress` at any time to:
 - See current project status
 - Get recommended next skill
 
+## Model Invocation Routing
+
+This skill is model-invokable for explicit read-only status and routing asks such as "check progress" or "what's next". It has no active-project gate because it can safely report that no project is active.
+
+Do NOT auto-invoke only because another workflow step finished. If model-invoked, offer to check progress first when the user's intent is ambiguous. After reporting status, offer the recommended next skill before routing to it.
+
 ## Process
 
 ### Step 1: Check Knowledge Base Exists