@open-agent-toolkit/cli 0.1.20 → 0.1.22

package/assets/skills/authoring-docs/references/writing-style.md

@@ -0,0 +1,128 @@
+---
+title: Writing Style
+description: Style rules for clear, direct, maintainable technical documentation.
+---
+
+# Writing Style
+
+Technical documentation should be plain, specific, and useful under pressure.
+The reader should not have to decode tone, chase implied context, or guess
+whether a statement is current.
+
+## Voice
+
+Use a direct, practical voice.
+
+Prefer:
+
+```md
+Run the tests before opening a pull request.
+```
+
+Avoid:
+
+```md
+It is recommended that tests are run prior to the opening of a pull request.
+```
+
+## Active Voice and Specific Nouns
+
+Active voice makes responsibility clear. Specific nouns make actions
+verifiable.
+
+Weak:
+
+```md
+The cache is invalidated after the migration is run.
+```
+
+Stronger:
+
+```md
+The deploy workflow invalidates the Fastly cache after the migration finishes.
+```
+
+## Avoid False Ease
+
+Avoid words that make complex tasks sound trivial:
+
+- just
+- simply
+- obviously
+- easy
+- basically
+
+Replace hidden assumptions with exact steps, commands, or links.
+
+## Avoid Tribal Knowledge
+
+Do not write "use the usual process" or "deploy normally." Name the workflow,
+environment, command, approval requirement, and verification path when known.
+
+## Define Acronyms on First Use
+
+Define acronyms the first time they appear. If an acronym is used only once,
+avoid introducing it.
+
+## Prefer Present Tense
+
+Use future tense only for future behavior that is planned and dated. Avoid
+stale words such as `new`, `soon`, `currently`, `temporary`, `eventually`, and
+`recent` without a date or issue link.
+
+## Use Concrete Examples
+
+Show copyable examples with expected output when possible. Expected output helps
+humans verify success and helps agents reason about command behavior.
+
+## Warn Only for Real Risk
+
+Use warnings for production impact, destructive operations, security concerns,
+and irreversible behavior.
+
+```md
+> [!WARNING]
+> This command deletes all pending jobs in the queue. Run it only during an
+> active incident after confirming the queue contents.
+```
+
+Use notes for useful context, not ordinary tips.
+
+## Markdown Rules
+
+- Use one `#` heading per page.
+- Do not skip heading levels.
+- Use fenced code blocks with language identifiers.
+- Use `sh` for shell commands.
+- Use `txt` for command output.
+- Do not include shell prompts unless the prompt itself matters.
+- Use angle brackets for placeholders, such as `<environment>`.
+- Explain every placeholder.
+- Use descriptive link text.
+- Use tables for reference data, not long prose.
+
+## Headings Should Be Descriptive
+
+Weak headings:
+
+```md
+## Stuff
+
+## More
+
+## Notes
+
+## Misc
+```
+
+Stronger headings:
+
+```md
+## Configure environment variables
+
+## Run database migrations
+
+## Verify the deployment
+
+## Roll back a failed deploy
+```

package/assets/skills/oat-agent-instructions-analyze/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: oat-agent-instructions-analyze
-version: 1.10.0
+version: 1.11.0
 description: Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 ---
 
 # Agent Instructions Analysis
@@ -32,6 +32,7 @@ Scan, evaluate, and report on agent instruction file coverage, quality, and drif
 - Reading all instruction files and project configuration.
 - Running helper scripts for discovery.
 - Writing analysis artifact to `.oat/repo/analysis/`.
+- Reviewing and correcting the analysis artifact and companion bundle through the shared Auto Artifact-Review Loop.
 - Updating `.oat/tracking.json`.
 
 ## Analyze vs Apply Boundary
@@ -58,16 +59,17 @@ or fill in missing evidence gaps on its own.
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Step indicators:
-  - `[1/10] Resolving providers + mode…`
-  - `[2/10] Discovering instruction files…`
-  - `[3/10] Discovering documentation surfaces…`
-  - `[4/10] Evaluating quality + validating existing rules…`
-  - `[5/10] Assessing directory coverage gaps…`
-  - `[6/10] Discovering file-type patterns…`
-  - `[7/10] Checking for drift…`
-  - `[8/10] Checking cross-format consistency…`
-  - `[9/10] Writing analysis artifact…`
-  - `[10/10] Updating tracking + summary…`
+  - `[1/11] Resolving providers + mode…`
+  - `[2/11] Discovering instruction files…`
+  - `[3/11] Discovering documentation surfaces…`
+  - `[4/11] Evaluating quality + validating existing rules…`
+  - `[5/11] Assessing directory coverage gaps…`
+  - `[6/11] Discovering file-type patterns…`
+  - `[7/11] Checking for drift…`
+  - `[8/11] Checking cross-format consistency…`
+  - `[9/11] Writing analysis artifact…`
+  - `[10/11] Reviewing artifact accuracy…`
+  - `[11/11] Updating verified tracking + summary…`
 
 ## Process
 
@@ -435,7 +437,32 @@ The markdown artifact and companion bundle together are the contract for apply.
   recommendation that requires judgment during generation
 - stable recommendation IDs and pack references for any recommendation that apply may execute
 
-### Step 9: Update Tracking and Output Summary
+### Step 9: Review Analysis Artifact Accuracy
+
+Run the shared **Auto Artifact-Review Loop** from `oat-project-plan-writing` after `$ARTIFACT_PATH` and `$BUNDLE_DIR` are written and before tracking is updated or `oat-agent-instructions-apply` is recommended.
+
+Use the `analysis` target:
+
+- `type: analysis`
+- `scope: agent-instructions`
+- `analysis_artifact: $ARTIFACT_PATH`
+- `oat_output_mode: structured`
+
+Follow the canonical loop exactly:
+
+1. Resolve `workflow.autoArtifactReview.analysis`; missing config means enabled, and only explicit `false` skips the loop.
+2. Resolve `oat_orchestration_retry_limit`; default to `2` if unavailable.
+3. Dispatch `oat-reviewer` in structured mode via Tier 1 subagent when available, falling back to the same reviewer prompt inline when needed.
+4. Apply Critical and Important fixes when they are local to the analysis artifact, companion bundle, and unambiguous.
+5. Offer Medium and Minor fixes rather than applying them silently.
+6. Rewrite `$ARTIFACT_PATH` and any affected bundle files after applied fixes, then re-dispatch while retries remain.
+7. Stop when the reviewer is clean or the retry bound is exhausted.
+
+The review loop may only edit the markdown analysis artifact and its companion bundle. It must not modify or create instruction files, provider rules, repo configuration, or any other downstream apply target. If a finding cannot be fixed inside the analysis artifact or bundle, preserve it as a residual review finding and surface it in the summary before handoff.
+
+If the loop is disabled, note `Auto artifact review: skipped (workflow.autoArtifactReview.analysis=false)` in the summary and do not describe the artifact as verified.
+
+### Step 10: Update Verified Tracking and Output Summary
 
 **Update tracking:**
 
@@ -454,6 +481,8 @@ bash "$TRACKING_SCRIPT" write \
   {providers...}
 ```
 
+Only run this tracking write after Step 9 finishes. A tracked agent-instructions analysis artifact is therefore reviewed/verified unless the summary explicitly says the auto artifact-review loop was skipped.
+
 **Output summary to the user:**
 
 ```
@@ -472,6 +501,7 @@ Analysis complete.
 
   Artifact: {artifact_path}
   Bundle:   {bundle_dir}
+  Auto artifact review: {passed|passed with residual findings|skipped}
 
 Next step: Run oat-agent-instructions-apply to act on these findings.
 ```

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

@@ -1,10 +1,10 @@
 ---
 name: oat-docs-analyze
-version: 1.2.0
+version: 1.4.0
 description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT docs app contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 ---
 
 # Docs Analysis
@@ -13,7 +13,8 @@ Scan a repository's documentation surface, evaluate it against the OAT docs cont
 
 ## Prerequisites
 
-- Git repository with either an MkDocs app, a `docs/` tree, or root-level Markdown docs.
+- Git repository with either an OAT/Fumadocs docs app, an MkDocs app, a
+  `docs/` tree, or root-level Markdown docs.
 - `jq` available in PATH for tracking updates.
 
 ## Mode Assertion
@@ -32,6 +33,7 @@ Scan a repository's documentation surface, evaluate it against the OAT docs cont
 
 - Reading docs trees, MkDocs config, and related repository metadata.
 - Writing a docs analysis artifact to `.oat/repo/analysis/`.
+- Reviewing and correcting the docs analysis artifact itself through the shared Auto Artifact-Review Loop.
 - Updating docs analysis tracking metadata.
 
 ## Analyze vs Apply Boundary
@@ -49,6 +51,9 @@ If you catch yourself:
 
 - Editing docs content directly -> STOP and move that recommendation to the artifact.
 - Rewriting navigation while analyzing -> STOP and record the required fix instead.
+- Hand-editing or regenerating generated root indexes -> STOP and record a
+  generated-artifact finding with the exact evidence that proves freshness or
+  source-contract drift.
 
 **Recovery:**
 
@@ -66,28 +71,42 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Use step indicators:
-  - `[1/9] Resolving docs target + mode…`
-  - `[2/9] Inventorying docs files…`
-  - `[3/9] Evaluating index contract…`
-  - `[4/9] Assessing quality + coverage…`
-  - `[5/9] Verifying substantive claims…`
-  - `[6/9] Finding content opportunities…`
-  - `[7/9] Checking nav and drift…`
-  - `[8/9] Writing analysis artifact…`
-  - `[9/9] Updating tracking + summary…`
+  - `[1/10] Resolving docs target + mode…`
+  - `[2/10] Inventorying docs files…`
+  - `[3/10] Evaluating index contract…`
+  - `[4/10] Assessing quality + coverage…`
+  - `[5/10] Verifying substantive claims…`
+  - `[6/10] Finding content opportunities…`
+  - `[7/10] Checking generated indexes, nav and drift…`
+  - `[8/10] Writing analysis artifact…`
+  - `[9/10] Reviewing artifact accuracy…`
+  - `[10/10] Updating verified tracking + summary…`
 
 ## Process
 
 ### Step 0: Resolve Docs Target and Analysis Mode
 
-Determine the documentation root using the first matching surface:
-
-1. `apps/*/mkdocs.yml`
-2. `mkdocs.yml` at repo root
-3. `docs/`
-4. Root-level Markdown docs (`README.md`, `CONTRIBUTING.md`, etc.) when no docs app exists
-
-Prefer the OAT docs app when multiple MkDocs apps exist and one is clearly the active repo docs surface.
+Determine the documentation root using explicit docs-app evidence before generic
+repo fallbacks:
+
+1. `.oat/config.json` `documentation.root` / `documentation.tooling`.
+   - When `documentation.tooling` is `fumadocs`, record the surface type as
+     `oat-fumadocs-app`.
+   - Treat `documentation.root` as the docs app root. Resolve the authored docs
+     source root and generated index path from `documentation.index`, app config,
+     package scripts, generator scripts, or local guidance.
+2. OAT/Fumadocs app candidates under `apps/*`, before root `docs/` fallback:
+   - `apps/*/source.config.*`
+   - `apps/*/next.config.*` with `apps/*/docs`
+   - `apps/*/docs` plus docs-app package scripts or local guidance evidence
+3. `apps/*/mkdocs.yml`
+4. `mkdocs.yml` at repo root
+5. generic root `docs/`
+6. Root-level Markdown docs (`README.md`, `CONTRIBUTING.md`, etc.) when no docs app exists
+
+Do not select generic root `docs/` or root Markdown docs while `.oat/config.json`
+or `apps/*` Fumadocs evidence identifies an active OAT/Fumadocs docs app. Prefer
+the app declared in `.oat/config.json` when multiple app candidates exist.
 
 Resolve tracking and analysis mode using the shared helper:
 
@@ -107,6 +126,8 @@ Build a complete inventory of:
 - All directories containing Markdown files
 - All `index.md` files
 - Any `overview.md` files
+- Generated root indexes or manifests, including warning banners such as "do not edit"
+- Local guidance that identifies generated index paths or regeneration commands
 - `mkdocs.yml` nav entries when present
 
 Record the docs surface type:
@@ -114,11 +135,16 @@ Record the docs surface type:
 - `mkdocs-app`
 - `docs-tree`
 - `root-markdown`
+- `oat-fumadocs-app`
 
 Capture the evidence sources that will justify later findings and recommendations. Prefer:
 
 - `mkdocs.yml` and generated nav structure
+- `.oat/config.json`, package scripts, generator scripts, and local `AGENTS.md`
+  files that identify authored docs roots or generated root indexes
 - `docs/contributing.md`, contributor guides, and setup docs
+- docs-app `AGENTS.md`, contributing pages, or authoring guides that tell
+  agents how to edit, analyze, apply, and validate docs
 - `package.json` scripts, `requirements.txt`, and docs bootstrap scripts
 - existing `index.md` trees and repeated directory patterns
 - exact missing or stale paths, commands, and page references
@@ -126,6 +152,21 @@ Capture the evidence sources that will justify later findings and recommendation
 Do **not** infer docs structure conventions from a tiny sample of pages when the broader
 tree or config disagrees.
 
+For OAT/Fumadocs docs apps, check whether local guidance covers:
+
+- authored docs source location
+- generated root indexes or manifests and their no-hand-edit boundary
+- every content directory needing `index.md`
+- useful `## Contents` maps
+- `.md`-suffixed relative links, including `subdir/index.md`
+- `.md` as the default format and `.mdx` only for JSX/component needs
+- read-only audit routing to `oat-docs-analyze`
+- approved bulk edits routing to `oat-docs-apply`
+- generated artifact regeneration or freshness checks after source docs changes
+
+Flag stale local guidance that references older aliases without mapping them to
+the current analyze/apply flow.
+
 ### Step 2: Evaluate the `index.md` Contract
 
 Use `references/quality-checklist.md` and `references/directory-assessment-criteria.md`.
@@ -134,9 +175,41 @@ For every documentation directory:
 
 1. Verify `index.md` exists.
 2. Verify `index.md` includes a `## Contents` section.
-3. Verify the `## Contents` section maps sibling pages and immediate child directories.
-4. Flag `overview.md` usage as a migration finding.
-5. Verify single-file directories still expose an `index.md` entrypoint.
+3. Flag placeholder-only `## Contents` sections, including comments, generic
+   "add links here" copy, or empty lists.
+4. Verify the `## Contents` section maps sibling pages and immediate child directories.
+5. Verify parent `## Contents` maps include child directories that contain docs.
+6. Flag `overview.md` usage as a migration finding.
+7. Flag unexpected `.mdx` for plain content unless JSX/components or local
+   guidance justify it.
+8. Verify single-file directories still expose a useful `index.md` entrypoint
+   or local section map.
+9. Exempt asset-only directories that contain no Markdown content and are not
+   linked as navigable docs sections.
+
+For OAT/Fumadocs docs apps, also distinguish authored source maps from generated
+root indexes:
+
+1. Resolve the authored docs source root and generated root index path from
+   `.oat/config.json`, package scripts, generator scripts, or local guidance.
+2. Confirm the generated root index exists when local configuration says it is
+   produced, and record whether it appears tracked, ignored, or local-only.
+3. Confirm generated warning banners are present when the repo's generator emits
+   them or local guidance requires them.
+4. Compare generated entries against the authored `## Contents` graph.
+5. Flag stale generated entries that point to deleted or moved docs paths.
+6. Flag missing generated entries for authored pages or child directories that
+   are reachable from source `## Contents` maps.
+7. Flag generated entries that are not reachable from any authored parent
+   `## Contents` map unless local generator semantics explicitly explain them.
+8. Classify ordering drift separately from missing or stale entries.
+9. If source maps and generated output disagree but generator behavior is not
+   documented well enough to judge, classify the finding as unclear generator
+   semantics instead of guessing.
+
+Generated index checks are read-only. Recommend regeneration, source-map fixes,
+or tool investigation in the analysis artifact; do not hand-edit generated
+files from this skill.
 
 ### Step 3: Assess Quality and Coverage
 
@@ -163,13 +236,28 @@ Evidence standard:
 For each evaluated page or directory:
 
 1. Read the docs file plus the local evidence needed to validate its claims.
-2. Record findings with severity, exact source refs, and confidence.
-3. Decide a disclosure mode for each recommendation:
+2. Resolve every local relative Markdown link from the page where it appears.
+   Flag broken targets. In OAT/Fumadocs docs apps, flag extensionless local
+   Markdown links and prefer `.md`-suffixed targets, including
+   `subdir/index.md`.
+3. Accept anchors on `.md` links, such as `page.md#section`, and do not flag
+   anchors-only, external URLs, `mailto:` links, image/asset links, or link
+   syntax intentionally shown inside inline code, fenced examples, or template
+   snippets.
+4. Check Markdown hygiene: opening code fences need language identifiers; shell
+   examples should follow local fence conventions, defaulting to `sh` unless
+   local guidance uses `bash` or the block needs Bash-only syntax.
+5. Flag empty headings, multiple document-level H1s outside intentional imported
+   README contexts, overlong frontmatter descriptions when local guidance
+   defines a limit, ellipsis-truncated descriptions, and README-copy metadata
+   signals that make search/navigation output look stale.
+6. Record findings with severity, exact source refs, and confidence.
+7. Decide a disclosure mode for each recommendation:
    - `inline`
    - `link_only`
    - `omit`
    - `ask_user`
-4. Record canonical link targets whenever a `link_only` recommendation is used.
+8. Record canonical link targets whenever a `link_only` recommendation is used.
 
 In `delta` mode, always evaluate changed docs files plus the nearest parent `index.md` pages.
 In `full` mode, evaluate the whole docs surface.
@@ -225,9 +313,32 @@ sources only. Prefer:
 - `app/services/`, `src/services/`, or equivalent business-logic modules
 - the main application entrypoint and route registration files
 - key models, schemas, and config surfaces that define user-facing behavior
+- command definitions, CLI parsers, flag schemas, and command tests
+- deployment, release, monitoring, runbook, rollback, and support/escalation
+  files that define operational behavior
 
 Do not speculate about future roadmap items or undocumented external integrations.
 
+Classify coverage by the surfaces proven in the repo:
+
+- For app/service docs, check purpose, audience, local setup, testing,
+  configuration, deployment/release, observability, runbooks, rollback,
+  ownership, support/escalation, troubleshooting, and common failure modes.
+- For API docs, check whether broad API surfaces have navigable
+  contract-grade reference pages with routes/endpoints, request/response
+  shapes, authentication, error modes, examples, and versioning where those
+  concepts exist in repo sources.
+- For CLI docs, check command groups, flags, output modes, destructive
+  behavior, dry-run/force options, scripting contracts, exit-code behavior when
+  sourced, and examples for common workflows.
+- For operations docs, flag "Future Topics" placeholders, empty runbook
+  outlines, unsupported deploy/monitoring claims, and missing owner-reviewed
+  gaps for unverifiable operations knowledge.
+
+When a claim affects ownership, support, deployment, observability, rollback, or
+external integration behavior and repo evidence cannot verify it, mark it as an
+owner-review gap rather than guessing.
+
 For each significant feature or API capability found in the codebase:
 
 1. Capture the capability area and the evidence that proves it exists.
@@ -259,6 +370,19 @@ where the docs should live, and what specific subtopics the codebase shows shoul
 
 ### Step 6: Check Navigation and Drift
 
+If a generated root index or manifest exists:
+
+1. Compare generated entries with the authored `## Contents` graph.
+2. Flag generated output that is missing, ignored/local-only when local guidance
+   expects a tracked artifact, stale, ordered differently from authored maps, or
+   unclear because generator semantics are undocumented.
+3. Flag generated entries that are not reachable from authored maps as either
+   authored-source contract drift or generator-semantics uncertainty, depending
+   on the evidence.
+4. Cite exact generated paths, authored source paths, package scripts, config
+   files, and representative links for each finding.
+5. Prefer source-of-truth fixes over generated-file edits.
+
 If `mkdocs.yml` exists:
 
 1. Compare nav entries with the docs tree.
@@ -293,6 +417,9 @@ Populate the artifact with:
 - Inventory summary
 - Severity-rated findings
 - Directory coverage and contract gaps
+- Generated index and authored local-map findings
+- Authored link, `## Contents`, and Markdown hygiene findings
+- Local docs-app guidance gaps
 - Accuracy verification verdicts for repo-checkable claims
 - Content opportunities for missing or thin docs coverage
 - Navigation/drift findings
@@ -302,7 +429,32 @@ Populate the artifact with:
 - Progressive disclosure decisions (`inline`, `link_only`, `omit`, `ask_user`)
 - Canonical link targets when deeper detail should stay out of always-on docs pages
 
-### Step 9: Update Tracking and Output Summary
+### Step 9: Review Analysis Artifact Accuracy
+
+Run the shared **Auto Artifact-Review Loop** from `oat-project-plan-writing` after `$ARTIFACT_PATH` is written and before tracking is updated or `oat-docs-apply` is recommended.
+
+Use the `analysis` target:
+
+- `type: analysis`
+- `scope: docs`
+- `analysis_artifact: $ARTIFACT_PATH`
+- `oat_output_mode: structured`
+
+Follow the canonical loop exactly:
+
+1. Resolve `workflow.autoArtifactReview.analysis`; missing config means enabled, and only explicit `false` skips the loop.
+2. Resolve `oat_orchestration_retry_limit`; default to `2` if unavailable.
+3. Dispatch `oat-reviewer` in structured mode via Tier 1 subagent when available, falling back to the same reviewer prompt inline when needed.
+4. Apply Critical and Important fixes when they are local to the analysis artifact and unambiguous.
+5. Offer Medium and Minor fixes rather than applying them silently.
+6. Rewrite `$ARTIFACT_PATH` after applied fixes and re-dispatch while retries remain.
+7. Stop when the reviewer is clean or the retry bound is exhausted.
+
+The review loop may only edit the analysis artifact. It must not edit docs content, `mkdocs.yml`, navigation files, or any other downstream apply target. If a finding cannot be fixed inside the analysis artifact, preserve it as a residual review finding and surface it in the summary before handoff.
+
+If the loop is disabled, note `Auto artifact review: skipped (workflow.autoArtifactReview.analysis=false)` in the summary and do not describe the artifact as verified.
+
+### Step 10: Update Verified Tracking and Output Summary
 
 Update docs tracking using the shared helper:
 
@@ -320,13 +472,15 @@ bash "$TRACKING_SCRIPT" write \
   --artifact-path "$ARTIFACT_PATH"
 ```
 
+Only run this tracking write after Step 9 finishes. A tracked docs analysis artifact is therefore reviewed/verified unless the summary explicitly says the auto artifact-review loop was skipped.
+
 Output a summary:
 
 ```text
 Analysis complete.
 
   Docs target:      {path}
-  Surface type:     {mkdocs-app|docs-tree|root-markdown}
+  Surface type:     {mkdocs-app|oat-fumadocs-app|docs-tree|root-markdown}
   Files evaluated:  {N}
   Mode:             {full|delta}
 
@@ -337,6 +491,7 @@ Analysis complete.
     Low:       {N}
 
   Artifact: {artifact_path}
+  Auto artifact review: {passed|passed with residual findings|skipped}
 
 Next step: Run oat-docs-apply to act on these findings.
 ```