@open-agent-toolkit/cli 0.0.10

package/assets/agents/skeptical-evaluator.md

@@ -0,0 +1,126 @@
+---
+name: skeptical-evaluator
+version: 1.0.0
+description: Adversarial claim evaluator — receives a context package and gathers evidence to disprove then support a claim. Returns structured findings with citations.
+tools: Read, Bash, Grep, Glob, WebSearch, WebFetch
+color: red
+---
+
+## Role
+
+You are an adversarial evidence gatherer. You operate in a separate context from the original reasoning that produced the claim. Your job is to find evidence that DISPROVES the claim first. Only after exhausting contradicting evidence should you note supporting evidence.
+
+## Inputs
+
+You receive a structured context package:
+
+```
+CLAIM: [The exact claim being evaluated]
+BASIS: [Why the original agent made this claim — its reasoning, sources, assumptions]
+CLAIM_TYPE: [code_behavior | library_specific | documentation | factual | architectural]
+AVAILABLE_SOURCES: [Evidence sources accessible in the current environment]
+INSTRUCTION: Adversarial. Disprove first, then note supporting evidence.
+```
+
+## Process
+
+### Step 1: Parse Context Package
+
+Extract and internalize the claim, basis, claim type, and available sources. Identify the specific assertions within the claim that can be tested.
+
+### Step 2: Identify Assumptions to Challenge
+
+From the BASIS, extract the key assumptions the original agent relied on. These are your primary targets for disproof. Do NOT let the basis bias your investigation — it tells you what to challenge, not what to believe.
+
+### Step 3: Search for Contradicting Evidence
+
+Use the evidence gathering strategy appropriate to the claim type:
+
+| Claim Type       | Priority Sources                                              | Search Strategy                                         |
+| ---------------- | ------------------------------------------------------------- | ------------------------------------------------------- |
+| code_behavior    | tests, type signatures, implementation, git history           | Run tests, read source code, check git blame/log        |
+| library_specific | lockfile, package.json, installed module source, npm registry | Check installed versions, read module code, verify docs |
+| documentation    | docs pages, official docs URLs, web search                    | Fetch docs, search for contradictions                   |
+| factual          | web search, cited references                                  | Search multiple sources, cross-reference                |
+| architectural    | web search, authoritative references, first principles        | Research patterns, check real-world usage               |
+
+Exhaust all reasonable avenues for contradiction before proceeding.
+
+### Step 4: Search for Supporting Evidence
+
+Only after Step 3 is complete, search for evidence that supports the claim. Use the same source types but look for confirmation rather than contradiction.
+
+### Step 5: Assess Evidence Quality
+
+For each piece of evidence (contradicting and supporting), evaluate:
+
+- **Direct vs indirect** — Does it address the claim directly, or only tangentially?
+- **Authoritative vs anecdotal** — Official docs/source code vs blog posts/forum answers
+- **Current vs stale** — Is it from the relevant version/timeframe?
+- **Completeness** — Does it cover the full claim or only part of it?
+
+### Step 6: Form Preliminary Assessment
+
+Based on the evidence gathered, lean toward one of:
+
+- **holds_up** — Evidence predominantly supports the claim; no meaningful contradictions found
+- **skepticism_warranted** — Contradicting evidence raises real concerns about the claim's validity
+- **nuanced** — The claim is partially correct but needs qualification or refinement
+- **inconclusive** — Insufficient evidence to lean either way
+
+Provide a confidence estimate as a percentage.
+
+### Step 7: Return Findings Inline
+
+Return findings to the orchestrator using the output structure below. Do NOT write findings to disk.
+
+## Output Contract
+
+Return inline findings to the orchestrator in this structure:
+
+```
+## Evidence
+
+### Contradicting Evidence
+{Each piece with specific citation — file:line, URL, version, etc.}
+{Or "None found after searching: [list of sources checked]"}
+
+### Supporting Evidence
+{Each piece with specific citation}
+{Or "None found"}
+
+### Evidence Quality Assessment
+{How reliable the evidence is — direct vs indirect, authoritative vs anecdotal}
+
+## Preliminary Assessment
+{Lean toward one of: holds_up | skepticism_warranted | nuanced | inconclusive}
+{Brief reasoning for the lean}
+{Confidence estimate: X%}
+```
+
+**Why inline, not to disk:** Unlike dedicated review agents which write review artifacts to disk, the skeptical-evaluator returns findings to the /skeptic orchestrator. The orchestrator synthesizes the final verdict from the evaluator's findings. /skeptic's output is always inline — there is no artifact to write.
+
+## Critical Rules
+
+**ADVERSARIAL FIRST.** Your primary mission is to DISPROVE the claim. Do not look for supporting evidence until you have thoroughly searched for contradictions.
+
+**CITE SPECIFICALLY.** Every piece of evidence must include a specific reference: file path and line number, URL, package version, or documentation section. Never make vague references like "the docs say..."
+
+**NEVER HALLUCINATE SOURCES.** If you cannot find evidence, say so. Do not fabricate URLs, file paths, or citations. "No contradicting evidence found" is a valid and valuable finding.
+
+**SOURCE-APPROPRIATE.** Only use sources verifiably accessible in the current environment. If web search is not available, do not claim web-sourced evidence.
+
+**NOTE THE ABSENCE.** If expected evidence sources are unavailable or missing, note that explicitly. The absence of expected evidence is itself evidence.
+
+**INDEPENDENCE.** Do not be influenced by the BASIS provided. It tells you what the original agent thought, but your job is to verify independently. The basis exists so you can identify what assumptions to challenge.
+
+## Success Criteria
+
+- [ ] Context package received and parsed
+- [ ] Claim type correctly identified
+- [ ] Contradicting evidence search completed BEFORE supporting evidence search
+- [ ] All evidence cited with specific references
+- [ ] Evidence quality honestly assessed
+- [ ] Preliminary assessment provided with confidence estimate
+- [ ] Findings returned inline (not written to disk)
+- [ ] No hallucinated sources

package/assets/docs/contributing/code.md

@@ -0,0 +1,95 @@
+---
+title: Contributing Code
+description: 'Contributor setup, repo structure, quality gates, and pull request expectations for OAT changes.'
+---
+
+# Contributing Code
+
+Use this page when you are changing the OAT codebase itself rather than only editing docs content.
+
+## Environment Setup
+
+Install and verify the workspace from the repo root:
+
+```bash
+pnpm install
+pnpm build
+pnpm run cli -- help
+```
+
+For worktree-based implementation, initialize the worktree before starting the CLI workflow:
+
+```bash
+pnpm run worktree:init
+```
+
+## Monorepo Structure
+
+OAT is organized as a pnpm workspace with Turborepo orchestration.
+
+- `packages/cli` - provider sync, docs tooling, and workflow-supporting CLI commands
+- `packages/docs-*` - shared docs app config, transforms, and theme components
+- `apps/oat-docs` - the docs app used in this repo
+- `.agents/skills` - workflow and utility skills
+- `.oat/projects` - project lifecycle artifacts
+
+## Quality Gates
+
+Run the workspace checks that match your change surface:
+
+```bash
+pnpm test
+pnpm lint
+pnpm format
+pnpm type-check
+pnpm build          # excludes docs for speed
+pnpm build:docs     # builds docs site and its dependencies
+```
+
+For narrower changes, use package-specific checks when possible, but do not merge without passing the relevant workspace gates.
+
+## CLI and Docs-Specific Verification
+
+Common targeted checks:
+
+```bash
+pnpm --filter @open-agent-toolkit/cli test
+pnpm --filter @open-agent-toolkit/cli lint
+pnpm --filter @open-agent-toolkit/cli type-check
+pnpm --filter oat-docs docs:lint
+pnpm build:docs
+```
+
+## Release Bootstrap
+
+The first publish under `@open-agent-toolkit/*` is a maintainer bootstrap step,
+not the steady-state path.
+
+- Run `pnpm release:validate` before any release attempt.
+- Publish the four public packages manually the first time under the new npm
+  org scope.
+- After those packages exist in npm, configure npm trusted publishing for this
+  repository so `.github/workflows/release.yml` can become the steady-state
+  release path without an npm token.
+- Use `.github/workflows/release-dry-run.yml` to validate the GitHub path after
+  the npm trust relationship is configured.
+
+## Implementation Expectations
+
+- Follow the import-path rules and architectural guidance documented in [CLI Design Principles](design-principles.md).
+- Keep changes traceable to plan tasks, implementation records, and review artifacts when you are working inside an OAT project.
+- Prefer editing canonical sources and letting sync/generation flows update derived files.
+- Preserve the repo’s current behavior unless the plan or review explicitly calls for a change.
+
+## Pull Request Expectations
+
+- Use task- or scope-linked commit messages that stay traceable to project artifacts.
+- Keep implementation notes current in the active project's `implementation.md` and `state.md`.
+- Make verification explicit in commit-adjacent notes or review artifacts.
+- If docs behavior changes, update the docs surface in the same change window.
+
+## Related Guides
+
+- [Contributing Docs](documentation.md)
+- [Commit Conventions](commit-conventions.md)
+- [Writing Skills](skills.md)

package/assets/docs/contributing/commit-conventions.md

@@ -0,0 +1,41 @@
+---
+title: Commit Conventions
+description: 'Commit message patterns and traceability rules for cross-artifact linkage.'
+---
+
+# Commit Conventions
+
+## Phase/task commits
+
+Implementation work commonly uses phase/task ids:
+
+- `pNN-tNN`
+- review-fix and review bookkeeping commits
+
+Examples:
+
+- `feat(p04-t03): implement oat init command`
+- `fix(p03-t08): harden stray filtering semantics`
+- `test(p05-t04): add help snapshot tests`
+
+## Project-level docs/chore commits
+
+Examples:
+
+- `docs(oat): ...`
+- `chore(oat): ...`
+
+## Traceability rules
+
+Keep explicit trace links among:
+
+- `plan.md` task ids
+- `implementation.md` execution entries
+- `reviews/*.md` artifacts
+- PR artifacts under `pr/*.md`
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/plan.md`
+- `.oat/projects/<scope>/<project>/implementation.md`
+- `.oat/projects/<scope>/<project>/reviews/`

package/assets/docs/contributing/design-principles.md

@@ -0,0 +1,124 @@
+---
+title: CLI Design Principles
+description: 'Cross-cutting design rules for CLI commands, UX, logging, safety, and verification.'
+---
+
+# CLI Design Principles
+
+This page captures cross-cutting design and implementation principles for OAT CLI features.
+
+Use this as the default contract for new CLI commands and modules. Provider- or domain-specific behavior should be layered on top in sub-docs (for example, provider interop docs).
+
+## Scope
+
+These principles apply to `packages/cli/src/**`:
+
+- Command architecture and boundaries
+- User interaction and output behavior
+- Safety and mutation contracts
+- Error semantics and exit codes
+- Verification expectations
+
+## Architectural Principles
+
+- Keep commands thin: parse args, validate inputs, orchestrate services.
+- Keep business logic in modules (`engine/`, `drift/`, `manifest/`, `providers/`), not in command handlers.
+- Use explicit type contracts for command inputs/outputs and adapter behavior.
+- Prefer deterministic pure planning stages before execution (compute plan first, then optionally apply).
+- Use command-factory exports for top-level commands (`createXCommand(): Command`).
+
+## Module Placement Rules
+
+- If a command needs dedicated prompts/types/utils, use a command directory (`commands/<name>/`).
+- Keep single-file commands only for trivial read-only behavior.
+- Prefer named command files for findability (`sync.ts`, `sync.test.ts`, `list.ts`, `list.test.ts`) over generic `index.ts`/`index.test.ts`.
+- Reserve `index.ts` for command registration boundaries and optional re-export wrappers.
+- Keep command-specific prompts in the command module; reserve `commands/shared/shared.prompts.ts` for reusable command-level prompt primitives.
+- Keep domain validation close to the owning domain (`*.types.ts` near command/provider modules).
+- Keep shared utilities generic; move domain-specific utilities into the owning command/provider area (for top-level command helpers, use `commands/shared/shared.utils.ts`).
+
+Example command structure pattern (for findability):
+
+```text
+packages/cli/src/
+  commands/
+    <top-level-command>/
+      index.ts
+      <top-level-command>.types.ts
+      <top-level-command>.utils.ts
+      <subcommand>/
+        <subcommand>.ts
+        <subcommand>.test.ts
+        <subcommand>.types.ts
+        <subcommand>.utils.ts
+        <nested-subcommand>/
+          <nested-subcommand>.ts
+          <nested-subcommand>.test.ts
+    shared/
+      shared.prompts.ts
+      shared.utils.ts
+```
+
+## Import Path Rules
+
+- Allow only same-directory relative imports: `./...`
+- Disallow parent-directory relative imports: `../...`
+- For anything outside the current directory, use explicit TypeScript aliases.
+- Do not use `src/...` imports.
+- Do not use a catch-all alias like `@/*`.
+- CLI alias set: `@app/*`, `@commands/*`, `@config/*`, `@drift/*`, `@engine/*`, `@errors/*`, `@fs/*`, `@manifest/*`, `@providers/*`, `@shared/*`, `@ui/*`, `@validation/*`.
+
+## Runtime Bootstrap and Flags
+
+- Startup order: load runtime config -> validate env/input -> build command context -> register commands.
+- Register global flags early and consistently (`--json`, `--verbose`, `--scope`, `--cwd`).
+
+## UX and Output Principles
+
+- Mutating commands apply by default; use `--dry-run` to preview changes safely.
+- Never require interaction in non-TTY or `--json` mode.
+- In interactive mode, prompts should be explicit, reversible where possible, and scoped to actionable choices.
+- JSON output must be machine-consumable and stable in structure for automation paths.
+- Human output should prioritize actionable state (`what changed`, `what failed`, `what to do next`).
+
+## Logging and Console Rules
+
+- Use the centralized CLI logger for user-facing output and JSON payloads.
+- Do not use direct `console.log`/`console.error` in command handlers (except bootstrap-level fatal fallback).
+- Keep spinner usage limited to longer operations and auto-disable in non-interactive/`--json` mode.
+
+## Safety Principles
+
+- Treat canonical `.agents/**` as source of truth for provider sync workflows.
+- Destructive operations must be scoped and traceable to known managed state.
+- Do not mutate unmanaged filesystem state implicitly.
+- Prefer idempotent operations; re-running a command should converge, not compound side effects.
+- Keep manifest updates aligned with executed operations only.
+
+## Error and Exit Semantics
+
+- `0`: success
+- `1`: user/actionable error (invalid input, unmet preconditions, declined required action)
+- `2`: system/runtime error (I/O, unexpected failures, corrupted state)
+
+Error messages should include concrete remediation where possible.
+
+## Verification Expectations
+
+For CLI behavior changes:
+
+- Add or update focused unit tests near touched modules.
+- Add integration/e2e coverage when behavior spans command -> engine -> filesystem boundaries.
+- Verify command wiring and help surfaces for changed command trees.
+- Keep adapter contract coverage for provider interface behavior.
+- Keep logger/spinner behavior tests aligned with human vs JSON mode behavior.
+- Run package checks before merge:
+  - `pnpm --filter @open-agent-toolkit/cli test`
+  - `pnpm --filter @open-agent-toolkit/cli lint`
+  - `pnpm --filter @open-agent-toolkit/cli type-check`
+
+## Related Docs
+
+- CLI Reference: [`../guide/cli-reference.md`](../guide/cli-reference.md)
+- Provider sync commands: [`../guide/provider-sync/commands.md`](../guide/provider-sync/commands.md)
+- Provider sync manifest and drift: [`../guide/provider-sync/manifest-and-drift.md`](../guide/provider-sync/manifest-and-drift.md)

package/assets/docs/contributing/documentation.md

@@ -0,0 +1,69 @@
+---
+title: Contributing to OAT Docs
+description: 'Docs authoring contract for OAT: navigation, local workflow, and contributor guidance.'
+---
+
+# Contributing to OAT Docs
+
+Documentation should ship with the code it explains. This page covers the core docs contract and local workflow; the syntax reference now lives in [Markdown Features](markdown-features.md).
+
+## Navigation contract
+
+- Every documentation directory must contain an `index.md`.
+- Each `index.md` must include a `## Contents` section.
+- The `## Contents` section is the machine-readable local map for sibling pages and child directories.
+
+## Local workflow
+
+1. Start the dev server from the repo root:
+
+   ```bash
+   pnpm dev:docs
+   ```
+
+2. Build the docs site locally (verifies the static export succeeds):
+
+   ```bash
+   pnpm build:docs
+   ```
+
+3. Run Markdown linting:
+
+   ```bash
+   pnpm --filter oat-docs docs:lint
+   ```
+
+4. Run Markdown formatting:
+
+   ```bash
+   pnpm --filter oat-docs docs:format
+   ```
+
+## Authoring Expectations
+
+- Keep docs aligned with the current repo behavior and current command surface.
+- Prefer cross-links over duplicated conceptual content.
+- When you add, remove, or rename docs pages, refresh the generated docs surface:
+
+  ```bash
+  pnpm -w run cli -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
+  ```
+
+- Use [Markdown Features](markdown-features.md) for supported syntax and examples.
+
+## Agent guidance
+
+- Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
+- Prefer linking to source files and commands explicitly when documenting behavior.
+- Regenerate the docs surface index after adding or removing pages.
+
+## Related Guides
+
+- [Markdown Features](markdown-features.md)
+- [Documentation User Guide](../guide/documentation/index.md)
+
+## If You Are Trying To...
+
+- use docs commands or bootstrap a docs app, start with [Documentation User Guide](../guide/documentation/index.md)
+- follow the authoring contract for `index.md` and navigation, stay on this page and then read [Docs Index Contract](../reference/docs-index-contract.md)
+- understand supported markdown patterns, use [Markdown Features](markdown-features.md)

package/assets/docs/contributing/hooks-and-safety.md

@@ -0,0 +1,31 @@
+---
+title: Hooks and Safety
+description: 'Pre-commit hooks and safety contracts for provider sync mutations.'
+---
+
+# Hooks and Safety
+
+## Optional pre-commit drift warning hook
+
+`oat init` can install a pre-commit hook that warns when project provider views appear out of sync.
+
+OAT installs that hook into Git's currently active hook directory. When a consumer repo keeps hooks in a repo-managed folder such as `.githooks/`, Git must be configured to use that path before install, or OAT must configure it during the hook prompt flow.
+
+## Safety contracts
+
+- `sync` mutates by default; use `--dry-run` to preview.
+- All mutation commands write immediately unless `--dry-run` is passed.
+- Removals are limited to manifest-managed entries.
+- JSON/non-interactive paths avoid interactive prompts.
+- Hook warnings are non-blocking by default.
+
+## User consent expectations
+
+- Adoption and migration operations should ask before mutation in interactive mode.
+- Lifecycle completion/archival transitions should require explicit user confirmation.
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/implementation.md` (hook + safety hardening)
+- `packages/cli/src/engine/hook.ts`
+- `packages/cli/src/commands/init/index.ts`

package/assets/docs/contributing/index.md

@@ -0,0 +1,18 @@
+---
+title: Contributing
+description: Contributor-facing guide for working on OAT code, docs, markdown patterns, and skill authoring.
+---
+
+# Contributing
+
+Use this section when you are changing OAT itself rather than consuming it as a user. It routes you to the right contributor contract for code changes, docs updates, markdown authoring patterns, and skill development.
+
+## Contents
+
+- [Contributing Code](code.md) - Repo setup, monorepo structure, quality gates, and PR expectations.
+- [Contributing Docs](documentation.md) - Docs contract, local docs workflow, and docs-specific authoring guidance.
+- [Markdown Features](markdown-features.md) - Supported docs syntax for callouts, tabs, Mermaid, and code blocks.
+- [Writing Skills](skills.md) - Skill authoring guidance, runtime contracts, and governance.
+- [CLI Design Principles](design-principles.md) - Cross-cutting CLI architecture and UX principles.
+- [Commit Conventions](commit-conventions.md) - Traceable commit patterns for project and docs work.
+- [Hooks and Safety](hooks-and-safety.md) - Safety and mutation contracts for provider-sync behavior.

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

@@ -0,0 +1,117 @@
+---
+title: Markdown Features
+description: 'Supported markdown patterns for OAT docs, including frontmatter, callouts, Mermaid, tabs, and code blocks.'
+---
+
+# Markdown Features
+
+This page is the syntax reference for the markdown patterns supported by the current OAT docs app.
+
+## Frontmatter
+
+Every page should include `title` and `description` in YAML frontmatter.
+
+=== "Syntax"
+
+    ```yaml
+    ---
+    title: Page Title
+    description: A short summary of the page.
+    ---
+    ```
+
+## Callouts
+
+GitHub-style blockquote callouts are supported.
+
+=== "Syntax"
+
+    ```text
+    > [!NOTE]
+    > Useful supporting context.
+
+    > [!WARNING]
+    > Important caution for the reader.
+    ```
+
+=== "Rendered"
+
+    > [!NOTE]
+    > Useful supporting context.
+
+    > [!WARNING]
+    > Important caution for the reader.
+
+## Mermaid Diagrams
+
+Fenced code blocks with `mermaid` are rendered as diagrams.
+
+=== "Syntax"
+
+    ````text
+    ```mermaid
+    flowchart LR
+      A[Read docs tree] --> B[Generate index]
+    ```
+    ````
+
+=== "Rendered"
+
+    ```mermaid
+    flowchart LR
+      A[Read docs tree] --> B[Generate index]
+    ```
+
+## Tabs
+
+Tab groups use the existing tab transform syntax:
+
+=== "Syntax"
+
+    ```text
+    === "pnpm"
+
+        pnpm install
+
+    === "npm"
+
+        npm install
+    ```
+
+=== "Rendered"
+
+    === "pnpm"
+
+        pnpm install
+
+    === "npm"
+
+        npm install
+
+## Code Blocks
+
+Standard fenced code blocks support syntax highlighting and optional file-title metadata.
+
+=== "Syntax"
+
+    ````text
+    ```typescript title="src/example.ts"
+    const greeting = 'hello world';
+    console.log(greeting);
+    ```
+    ````
+
+=== "Rendered"
+
+    ```typescript title="src/example.ts"
+    const greeting = 'hello world';
+    console.log(greeting);
+    ```
+
+## Authoring Reminder
+
+After adding or reorganizing docs pages, refresh the generated docs surface:
+
+```bash
+pnpm -w run cli -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
+```