@open-agent-toolkit/cli 0.1.20 → 0.1.22

package/assets/docs/workflows/projects/reviews.md

@@ -19,6 +19,19 @@ Review loop:
 - `reviews/archived/` is the local-only historical surface. Active `reviews/` content is not gitignored by default.
 - Ad-hoc review artifacts still default to local-only orphan storage under `.oat/projects/local/orphan-reviews/`.
 
+## Latest review resolver
+
+Use `oat review latest` when a skill or operator needs to resolve "the most recent review" without hand-selecting a file.
+
+```bash
+oat review latest --json
+oat review latest --project .oat/projects/shared/example --json
+```
+
+The resolver orders candidates by `oat_generated_at` frontmatter, not filesystem mtime. With an active or explicit project, it scans the project's `reviews/` directory first, then `reviews/archived/`, then ad-hoc review locations (`.oat/repo/reviews/` and `.oat/projects/local/orphan-reviews/`). When candidates share the same generated time, active project reviews outrank archived and ad-hoc reviews, then lifecycle recency breaks remaining ties (`final` > higher phase/task scope > lower phase/task scope). The JSON response contains `path`, `scope`, `generatedAt`, and `kind` (`project` or `adhoc`). If no review exists, those fields are `null`.
+
+`oat-project-review-receive` uses this resolver when it is invoked from natural language and needs to offer the latest project review, or route an ad-hoc result to `oat-review-receive`.
+
 ## Bookkeeping commits (required)
 
 Both `oat-project-review-receive` and `oat-project-review-receive-remote` conclude with a required atomic commit of `plan.md`, `implementation.md`, `state.md`, and the archived review artifact (when tracked). This is the safety net that prevents cross-agent bookkeeping drift: when a subagent runs a receive skill in isolation, the commit ensures the original agent sees a clean checkout on return.
@@ -43,6 +56,17 @@ The commit is scoped and explicit — it stages only the project's tracking file
 
 The `*-provide-remote` and `*-receive-remote` skills are the two halves of the cross-machine loop: one agent posts a review to a PR; an agent on the PR's own machine receives it and turns it into fix tasks.
 
+## Model-invokable review skills
+
+The project review skills are model-invokable only for explicit user asks and confirmation flows. They are not auto-invoked just because a phase completed, a review artifact exists, or a checkout looks ready for review.
+
+- `oat-project-review-provide` handles explicit asks such as "review project" after resolving an active project and summarizing the inferred scope for confirmation.
+- `oat-project-review-receive` handles explicit asks such as "receive review" or "process review" after resolving the latest review target. If the latest target is ad-hoc, it offers to route to `oat-review-receive`.
+- `oat-project-progress` is also model-invokable for read-only status asks such as "check progress" or "what's next"; it reports before offering any next-step routing.
+- `oat-project-discover` is model-invokable only when an active spec-driven project exists. Otherwise it declines and points to `oat-project-new`, `oat-project-quick-start`, or `oat-project-open`.
+
+The common rule is offer-and-confirm: the model may recognize the request and propose the matching workflow skill, but must ask before mutating project artifacts or starting a review.
+
 ## Remote provide
 
 `oat-review-provide-remote` (ad-hoc) and `oat-project-review-provide-remote` (project-scoped) let an agent on one machine review a GitHub PR opened from another machine and post the review back to GitHub. They mirror the existing `*-receive-remote` skills, closing the local-vs-remote × provide-vs-receive matrix.
@@ -83,6 +107,23 @@ Auto-triggered reviews use `oat_review_invocation: auto` in the review artifact
 
 This feature is opt-in and disabled by default. When disabled, the manual `oat-project-review-provide` workflow applies.
 
+## Auto artifact-review loops
+
+Generated planning and analysis artifacts have a separate review loop from code/phase reviews.
+
+For plans, `oat-project-plan`, `oat-project-quick-start`, and `oat-project-import-plan` run a bounded `plan.md` artifact review before marking the plan ready for implementation. The loop dispatches `oat-reviewer` in structured-output artifact mode with `scope: plan`, applies unambiguous Critical and Important artifact-local fixes, offers Medium and Minor fixes, and re-runs until clean or the retry bound is exhausted. A clean result records the `plan` row in the plan's `## Reviews` table as `passed`.
+
+For analysis artifacts, `oat-docs-analyze` and `oat-agent-instructions-analyze` run a bounded accuracy review after writing their severity-rated artifacts. The reviewer checks cited evidence, severity, and recommendations before the matching apply workflow consumes the artifact. The analysis loop updates tracking metadata to mark the artifact verified.
+
+Both loops are default-on and controlled through:
+
+```bash
+oat config set workflow.autoArtifactReview.plan false
+oat config set workflow.autoArtifactReview.analysis false
+```
+
+Only an explicit `false` skips a loop. The retry bound comes from `oat_orchestration_retry_limit` and defaults to `2`.
+
 ## Re-review scope narrowing
 
 When re-reviewing after fix tasks have been applied, `oat-project-review-provide` detects completed `(review)` fix tasks and offers to narrow the re-review scope to just the fix-task commits. This avoids re-examining already-approved code.

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

@@ -23,7 +23,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
 - 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`
-- Work on docs surfaces: `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
+- 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`
 - Research a topic in depth: `deep-research`
 - Analyze an artifact, codebase, or document: `analyze`
@@ -83,6 +83,8 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 === "Docs and instructions"
 
+    - `authoring-docs`
+    - `oat-docs-authoring`
     - `oat-docs-bootstrap`
     - `oat-docs-analyze`
     - `oat-docs-apply`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.20",
-  "docs-config": "0.1.20",
-  "docs-theme": "0.1.20",
-  "docs-transforms": "0.1.20"
+  "cli": "0.1.22",
+  "docs-config": "0.1.22",
+  "docs-theme": "0.1.22",
+  "docs-transforms": "0.1.22"
 }

package/assets/skills/authoring-docs/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: authoring-docs
+version: 1.0.0
+description: Use when creating, restructuring, migrating, auditing, or reviewing technical documentation for software projects. Provides evidence-first, provider-portable Markdown authoring standards.
+argument-hint: '[docs task or target path]'
+disable-model-invocation: false
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+user-invocable: true
+---
+
+# Authoring Docs
+
+Use this skill to produce technical documentation that is grounded in the
+repository, useful to humans, and explicit enough for future agents.
+
+The prime directive is simple: do not write plausible docs. Extract truth from
+code, configuration, schemas, tests, CI, deployment files, and existing docs;
+then organize that truth around reader tasks.
+
+## When to Use
+
+Use when:
+
+- Creating or improving docs for a software repository.
+- Migrating existing docs into a clearer Markdown structure.
+- Auditing docs for missing, stale, duplicated, or risky content.
+- Writing API, CLI, app, service, library, framework, architecture, operations,
+  or internal/public docs.
+- Reviewing a documentation change for accuracy, usefulness, or safety.
+
+## When NOT to Use
+
+Do not use by itself when:
+
+- The user only asks for copy editing that does not require repository evidence.
+- A repository-specific docs framework contract is the main problem; load the
+  local skill or instruction set alongside this baseline.
+- Generated reference output must be regenerated from a tool; run the generator
+  first and use this skill for review and surrounding prose.
+- Legal, policy, marketing, or brand copy needs domain-specific approval outside
+  the repository.
+
+## Workflow
+
+### Step 1: Resolve Scope and Evidence
+
+Identify the docs target, intended reader, and source of truth before editing.
+Inspect local instructions, existing docs, source files, config, schemas, tests,
+CI, deployment files, and scripts that support the claims you plan to make.
+
+Never invent commands, environment variables, endpoints, fields, deployment
+steps, ownership, escalation paths, compatibility promises, or security
+behavior. Mark useful but unverified facts as needing confirmation.
+
+### Step 2: Classify the Project and Reader Task
+
+Classify the project type and docs category: API, CLI, frontend app, backend
+service, worker, library, framework, monorepo, architecture, operations, or
+mixed. Identify the reader's job: first success, task completion, exact lookup,
+system understanding, safe operation, or review. Load
+`references/categories.md` when category-specific coverage matters.
+
+### Step 3: Choose the Right Page Type
+
+Use one primary page type per page:
+
+- Tutorial: first successful path.
+- How-to guide: complete one task.
+- Reference: exact facts and contracts.
+- Explanation: mental model, design, and tradeoffs.
+- Runbook: operational recovery with checks, mitigation, and verification.
+
+Small supporting sections are fine, but keep the page's primary job clear.
+
+### Step 4: Structure the Docs
+
+Prefer predictable information architecture: landing page, getting started,
+how-to guides, reference, concepts, and operations. Preserve useful existing
+intent, remove duplication, and avoid creating parallel docs when an existing
+page can be improved.
+
+### Step 5: Write Direct, Verifiable Markdown
+
+Use plain language, active voice, specific nouns, exact file paths, exact
+commands, code block language identifiers, expected output, and useful links.
+Document prerequisites, verification, rollback for risky operations, and
+uncertainty.
+
+### Step 6: Verify and Handoff
+
+Run relevant validation commands when available: docs build, link check, tests
+for generated examples, formatters, or local preview. In the final handoff,
+summarize files changed, sources inspected, verification run, unresolved facts,
+and recommended follow-ups.
+
+## Reference Map
+
+Load only the references needed for the current task:
+
+- `references/principles.md`: core documentation principles.
+- `references/workflow.md`: evidence gathering and writing workflow.
+- `references/information-architecture.md`: docs structure, naming, and links.
+- `references/page-types.md`: tutorial, how-to, reference, explanation, and
+  runbook guidance.
+- `references/categories.md`: API, CLI, app, service, library, framework,
+  monorepo, architecture, operations, and audience-specific guidance.
+- `references/writing-style.md`: plain technical writing and Markdown rules.
+- `references/templates.md`: reusable page and handoff templates.
+- `references/review-rubric.md`: readiness checklist and review rubric.
+
+## Examples
+
+Basic usage:
+
+```txt
+/authoring-docs docs/
+```
+
+Conversational triggers:
+
+```txt
+Audit this repo's docs and identify missing pages.
+Create a getting-started guide grounded in the package scripts.
+Improve the CLI reference without inventing flags or exit codes.
+Review this runbook for operational safety.
+```
+
+## Success Criteria
+
+- Claims are grounded in repository evidence or marked as uncertain.
+- The reader can complete the intended task without tribal knowledge.
+- Page type, location, and navigation are clear.
+- Commands, examples, paths, options, and references are accurate.
+- Risky operations include verification and rollback.
+- Internal-only or sensitive information is handled appropriately.

package/assets/skills/authoring-docs/references/categories.md

@@ -0,0 +1,251 @@
+---
+title: Documentation Categories
+description: Category-specific guidance for APIs, CLIs, apps, services, libraries, frameworks, monorepos, architecture, operations, and audience boundaries.
+---
+
+# Documentation Categories
+
+Use category guidance after classifying the project. A repository can belong to
+multiple categories; document the dominant reader path first, then add focused
+reference, operational, or conceptual pages where the evidence supports them.
+
+## APIs
+
+API docs must help consumers integrate correctly without reading implementation
+code.
+
+Document:
+
+- overview and use cases
+- base URL, service location, or schema source
+- environments
+- authentication and authorization
+- request and response formats
+- status codes and error shape
+- pagination, filtering, sorting, and limits
+- idempotency, retries, and timeouts
+- versioning, deprecation, and compatibility behavior
+- webhooks, events, SDKs, or generated clients when applicable
+- examples grounded in real routes, schemas, or tests
+- support, ownership, or escalation when known
+
+For REST or HTTP APIs, document method, path, side effects, auth requirement,
+path and query parameters, request headers, request body, response body, status
+codes, error codes, example request, example response, retry behavior,
+idempotency, pagination, and deprecation notes.
+
+For GraphQL, include endpoint, auth, schema source, common queries and
+mutations, variables, fragments, pagination, errors, nullability, query cost or
+depth limits, and deprecation policy.
+
+For event-driven APIs, document event name, producer, known consumers,
+transport, topic or stream, schema, example payload, ordering guarantees,
+delivery guarantees, retry behavior, dead-letter behavior, idempotency
+requirements, versioning, and backward compatibility.
+
+For webhooks, document event types, endpoint expectations, signing and
+verification, retry schedule, timeout, payload schema, idempotency, ordering,
+testing tools, replay behavior, and security considerations.
+
+Prefer machine-readable schemas where the repo has them: OpenAPI, GraphQL,
+AsyncAPI, JSON Schema, Protocol Buffers, or generated types. Pair generated
+reference with hand-written onboarding and workflow guides.
+
+## CLIs
+
+CLI docs must help readers run the right command safely. A CLI is both a human
+interface and an automation interface.
+
+Document:
+
+- installation
+- authentication
+- configuration and precedence
+- quick start
+- common workflows
+- command reference
+- arguments, flags, inherited flags, aliases, and defaults
+- environment variables and config files
+- output formats and machine-readable output
+- exit codes
+- prompts and non-interactive behavior
+- CI and scripting behavior
+- logging, verbosity, retries, and timeouts
+- dry-run behavior when supported
+- production safety notes
+- troubleshooting
+
+For each command, include purpose, usage syntax, examples, side effects, output
+shape, JSON shape if supported, exit codes, related commands, and any
+environment or config keys it reads.
+
+Do not invent exit codes. If exit codes are not explicit in source or docs, say
+they are not documented.
+
+## Apps and Services
+
+Application and service docs should help people understand, run, change,
+deploy, operate, and recover the system.
+
+All apps and services should document:
+
+- purpose, audience, and users
+- local development
+- testing
+- configuration
+- dependencies
+- deployment
+- observability
+- ownership
+- troubleshooting
+- architecture summary
+- operational risks
+
+Frontend app docs should include routes, rendering model, data fetching, state
+management, design system usage, feature flags, analytics, accessibility,
+performance constraints, error boundaries, testing, local development, and
+deployment.
+
+Backend service docs should include service purpose, runtime, APIs, jobs,
+queues, databases, caches, external services, configuration, auth, local
+development, testing, deployment, observability, failure modes, and runbooks.
+
+Worker and job docs should include trigger, input payload, output or side
+effect, queue or scheduler, retry policy, timeout, concurrency, idempotency,
+dead-letter behavior, observability, replay process, and failure modes.
+
+Deployment docs should include where the system runs, deployment trigger,
+environments, required permissions, pre-deploy checks, deployment steps,
+post-deploy verification, rollback, and known risks.
+
+Troubleshooting pages should be symptom-first and map symptoms to likely cause,
+check, fix, and escalation.
+
+## Libraries, Packages, SDKs, and Frameworks
+
+Library and framework docs should help users decide whether to use the tool,
+install it, learn the mental model, apply it correctly, and avoid misuse.
+
+Document:
+
+- purpose
+- when to use it
+- when not to use it
+- installation
+- version compatibility and peer dependencies
+- quick start
+- core concepts
+- supported public API
+- examples and recipes
+- configuration
+- extension points
+- errors and side effects
+- testing guidance
+- migration guides
+- release policy
+- ownership and support model
+
+Document only supported public API unless the repository explicitly treats an
+internal surface as supported. For functions, classes, components, hooks, or
+types, include purpose, signature, parameters, return value, errors, examples,
+side effects, stability, and deprecation notes.
+
+Frameworks need stronger conceptual docs than small libraries: design goals,
+mental model, conventions, lifecycle, plugin model, file structure,
+configuration model, defaults, escape hatches, anti-patterns, migrations, and
+examples.
+
+Component libraries should document import path, props, examples, states,
+accessibility, design tokens, composition patterns, and when not to use a
+component.
+
+SDK docs should cover install, auth, client creation, common workflows, errors,
+retries, pagination, async behavior, type generation, version compatibility,
+and parity with the underlying service.
+
+## Monorepos
+
+Monorepo docs should help readers find the right package, app, service, or
+workflow without already knowing the source tree.
+
+Document:
+
+- repo purpose and major workspaces
+- package manager and workspace commands
+- build, test, lint, and type-check strategy
+- dependency graph or ownership map when available
+- shared config and conventions
+- release or deployment boundaries
+- how to run one package or app
+- how to add a new package or app
+- generated artifacts and source-of-truth boundaries
+- cross-package compatibility requirements
+
+Avoid organizing docs only by implementation directory. Prefer audience,
+product area, or workflow groupings, then link to package-level reference.
+
+## Architecture and Operations
+
+Architecture docs explain how the system works and why it is designed that way.
+Operations docs explain how to run, observe, debug, recover, and safely change
+the system.
+
+Architecture docs should answer:
+
+- What problem does this system solve?
+- What are the main components?
+- How does data flow through the system?
+- What are the boundaries?
+- What depends on this system, and what does it depend on?
+- What tradeoffs and decisions shaped the design?
+- What failure modes exist?
+- What should future maintainers avoid breaking?
+
+Use diagrams to clarify relationships, not to decorate. Every diagram should
+have a title, purpose, scope, explanation, caveats, and last verified date when
+it is highly operational.
+
+Use architecture decision records for significant decisions such as database
+choice, queueing model, API versioning, cache invalidation, auth model,
+deployment topology, framework choice, migration strategy, or deprecation
+strategy.
+
+Operations docs should answer:
+
+- Where does this run?
+- How is it deployed and rolled back?
+- How do I know it is healthy?
+- Where are logs, metrics, traces, dashboards, and alerts?
+- What are common failure modes?
+- How do I recover from them?
+- Who owns escalation?
+
+Runbooks should include symptoms, impact, checks, mitigation, verification,
+rollback, escalation, and known false positives. Alert docs should make every
+alert actionable. Rollback docs must include exact steps or explicitly say the
+rollback process is not documented.
+
+## Internal and Public Docs
+
+Internal and public docs share the same quality bar. The differences are
+audience, assumptions, security, and support model.
+
+Internal docs can include internal service names, environments, dashboards,
+alerts, runbooks, deployment workflows, known consumers, support channels, and
+escalation paths. They must not include secrets, credentials, tokens, private
+keys, sensitive customer data, personal data, or private incident details that
+do not belong in durable docs.
+
+Public docs should include purpose, onboarding, installation, authentication
+setup, permissions, examples, API or CLI reference, version compatibility,
+migration guides, deprecation policy, support path, security guidance, and
+accessibility or privacy notes when relevant.
+
+Public docs should avoid internal URLs, private dashboards, Slack links,
+deployment internals, customer-specific data, unapproved roadmap statements,
+and implementation details that are not part of the public contract.
+
+When converting internal docs to public docs, identify internal-only content,
+remove or rewrite sensitive details, replace examples with public-safe values,
+ensure links are public, remove private operational links, preserve user-facing
+behavior, and add a public support path.

package/assets/skills/authoring-docs/references/information-architecture.md

@@ -0,0 +1,156 @@
+---
+title: Information Architecture
+description: Standard documentation structure, naming, navigation, and cross-linking.
+---
+
+# Information Architecture
+
+Documentation structure should feel predictable across repositories even when
+the systems differ. Consistency makes docs easier to browse, review, migrate,
+and use as agent context.
+
+## Standard Top-Level Model
+
+Use this conceptual model:
+
+```txt
+Start here
+How-to guides
+Reference
+Concepts
+Operations
+```
+
+These labels map to reader needs:
+
+| Product Label | Documentation Type       | Reader Question                              |
+| ------------- | ------------------------ | -------------------------------------------- |
+| Start here    | Tutorial and orientation | What is this and how do I begin?             |
+| How-to guides | How-to                   | How do I complete this task?                 |
+| Reference     | Reference                | What are the exact facts?                    |
+| Concepts      | Explanation              | How does this work and why?                  |
+| Operations    | How-to plus reference    | How do I run, observe, fix, or recover this? |
+
+## Default Repo Structure
+
+```txt
+docs/
+├── index.md
+├── getting-started.md
+├── how-to/
+│   ├── local-development.md
+│   ├── testing.md
+│   ├── deployment.md
+│   └── troubleshooting.md
+├── reference/
+│   ├── configuration.md
+│   ├── environment-variables.md
+│   ├── commands.md
+│   ├── api.md
+│   └── errors.md
+├── concepts/
+│   ├── architecture.md
+│   ├── data-flow.md
+│   ├── auth.md
+│   └── caching.md
+└── operations/
+    ├── runbook.md
+    ├── observability.md
+    ├── alerts.md
+    └── rollback.md
+```
+
+Do not create empty pages for symmetry. Use the structure as a guide, not
+theater.
+
+## Scale the Structure to the Repo
+
+Tiny repos can use a single `README.md` if it covers purpose, install or setup,
+usage, configuration, testing, and ownership.
+
+Small repos should separate overview, usage, and reference.
+
+Medium repos should use the standard structure.
+
+Large repos or platforms can group by product area or audience, but should keep
+the same doc types recognizable. Avoid organizing only by implementation
+directory; readers usually do not arrive knowing the source tree.
+
+## Landing Page Contract
+
+Every docs entry point should answer:
+
+1. What is this?
+2. Why does it exist?
+3. Who is it for?
+4. What are the main capabilities?
+5. What are the boundaries and non-goals?
+6. How do I get started?
+7. What are the common tasks?
+8. Where is the reference material?
+9. How is it operated?
+10. Who owns it?
+
+## Navigation Principles
+
+Use predictable labels:
+
+- Getting started
+- Local development
+- Testing
+- Deployment
+- Configuration
+- Environment variables
+- API reference
+- CLI reference
+- Architecture
+- Data flow
+- Authentication
+- Observability
+- Troubleshooting
+- Runbook
+- Rollback
+
+Avoid clever labels such as `Misc`, `Magic`, `Deep cuts`, or `Everything else`.
+
+## Page Naming
+
+Use task names for how-to guides:
+
+```txt
+how-to/add-a-new-route.md
+how-to/deploy-to-production.md
+how-to/rotate-api-credentials.md
+```
+
+Use topic names for concepts:
+
+```txt
+concepts/authentication.md
+concepts/event-delivery.md
+concepts/caching.md
+```
+
+Use noun names for reference:
+
+```txt
+reference/environment-variables.md
+reference/cli.md
+reference/api.md
+reference/errors.md
+```
+
+## Cross-Linking Rules
+
+Link between doc types intentionally.
+
+A tutorial should link to related how-to guides, relevant reference pages, and
+conceptual background for later learning.
+
+A how-to guide should link to reference pages for options, concepts for why the
+task works, and operations pages for production safety.
+
+A reference page should link to tutorials or how-to guides that show common use.
+
+An explanation page should link to runbooks, deployment guides, API or CLI
+reference, and ADRs when available.