@open-agent-toolkit/cli 0.0.10

package/assets/docs/guide/workflow/lifecycle.md

@@ -0,0 +1,207 @@
+---
+title: Lifecycle
+description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, and import paths.'
+---
+
+# Lifecycle
+
+This lifecycle is an optional OAT layer. Interop-only users can skip it.
+
+OAT lifecycle order:
+
+1. Discovery (`oat-project-discover`)
+2. Spec (`oat-project-spec`)
+3. Design (`oat-project-design`)
+4. Plan (`oat-project-plan`)
+5. Implement (`oat-project-implement` or `oat-project-subagent-implement`)
+6. Review loop (`oat-project-review-provide` / `oat-project-review-receive`)
+7. Summary (`oat-project-summary`) — generates `summary.md` as institutional memory; `oat-project-pr-final` and `oat-project-complete` auto-refresh it when missing or stale
+8. PR (`oat-project-pr-progress` / `oat-project-pr-final`) — sets `pr_open` status
+9. Revision loop (`oat-project-revise`) — optional; accepts post-PR feedback
+10. Documentation sync (`oat-project-document`) — optional; reads project artifacts to identify docs needing updates
+11. Complete (`oat-project-complete`)
+
+**Shortcut:** `oat-project-next` reads project state and invokes the correct next skill automatically — use it instead of remembering which skill comes next. Complements `oat-project-progress` (which is read-only diagnostic).
+
+## Lifecycle Map
+
+```mermaid
+flowchart LR
+  D["Discovery"] --> S["Spec"] --> G["Design"] --> P["Plan"]
+  P --> M{"Implementation mode"}
+  M --> I1["Sequential"]
+  M --> I2["Subagent-driven"]
+  I1 --> R["Review loop"]
+  I2 --> R
+  R --> PR["PR flow"]
+  PR --> DOC["Docs sync (optional)"]
+  DOC --> C["Complete"]
+```
+
+## Post-implementation flow
+
+After implementation and final review pass:
+
+1. **Summary** (`oat-project-summary`) — generates `summary.md` as institutional memory from project artifacts; PR-final and completion will auto-refresh it if you have not already run it or if it is stale
+2. **Documentation** (`oat-project-document`) — optional sync of project docs
+3. **PR** (`oat-project-pr-final`) — creates PR description (auto-refreshes `summary.md` first when needed, then uses it as source), sets `oat_phase_status: pr_open`, and tracks actual PR existence with `oat_pr_status` / `oat_pr_url`
+4. **Revision loop** (`oat-project-revise`) — accepts post-PR feedback:
+   - Inline feedback creates `p-revN` revision phases with `prevN-tNN` task IDs
+   - GitHub PR feedback delegates to `oat-project-review-receive-remote`
+   - Review artifacts delegate to `oat-project-review-receive`
+   - After revision tasks complete, state returns to `pr_open`
+5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and always archives the project locally
+
+### Completion archive behavior
+
+On completion, OAT now treats archive handling as part of the closeout lifecycle:
+
+- Local archive is always written to `.oat/projects/archived/<project>/`.
+- If `.oat/config.json` enables `archive.s3SyncOnComplete` and sets `archive.s3Uri`, completion also attempts an S3 upload for a dated snapshot such as `<archive.s3Uri>/<repo-slug>/projects/20260401-<project>/`.
+- If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
+- Missing or unusable AWS CLI configuration produces warnings during completion instead of blocking closeout.
+- `oat project archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
+
+### Phase status: `pr_open`
+
+After `oat-project-pr-final` runs, `state.md` shows `oat_phase_status: pr_open`. This signals:
+
+- The project is in its post-PR review posture
+- The project is NOT done — agents should not start a new project
+- Next steps: `oat-project-revise` (for feedback) or `oat-project-complete` (when approved)
+
+Actual PR existence is tracked separately from `oat_phase_status`:
+
+- `oat_pr_status` records whether the PR is merely ready to create, open, closed, or merged
+- `oat_pr_url` records the tracked PR URL when a PR exists
+
+This distinction matters during completion: `oat-project-complete` can skip the "Open a PR?" prompt when `oat_pr_status: open` is already present.
+
+### Auto-review at checkpoints
+
+When `autoReviewAtCheckpoints` is enabled (via `.oat/config.json` or `plan.md` frontmatter `oat_auto_review_at_checkpoints`), completing a plan phase checkpoint automatically spawns a subagent code review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (minors auto-converted to fix tasks, no user prompts). Disabled by default.
+
+## Implementation modes
+
+- **Sequential (default):** `oat-project-implement`
+- **Parallel/subagent-driven:** `oat-project-subagent-implement`
+- Use `oat project set-mode <single-thread|subagent-driven>` to persist mode in project state.
+- `oat-project-implement` remains the canonical consumer and redirects when mode is `subagent-driven`.
+
+## Review receive behavior
+
+- `oat-project-review-receive` now presents a findings overview before asking for any disposition decisions.
+- Findings are shown with stable IDs by severity (`C*`, `I*`, `M*`, `m*`) so follow-up choices map clearly to specific items.
+- For each finding, the receive step summarizes the reviewer note, adds agent analysis, and gives a recommendation (convert now vs defer with rationale).
+
+## Alternate lifecycle lanes
+
+### Quick lane diagram
+
+1. `oat-project-quick-start` (adaptive discovery — well-understood requests synthesize quickly, exploratory requests invest in solution space exploration)
+2. Decision point: straight to plan, optional lightweight `design.md`, or promote to spec-driven
+3. Implement:
+   - `oat-project-implement` (sequential)
+   - `oat-project-subagent-implement` (parallel/subagent-driven)
+4. `oat-project-review-provide` / `oat-project-pr-final`
+5. Optional `oat-project-promote-spec-driven` to backfill spec-driven lifecycle artifacts in-place
+
+### Import lane diagram
+
+1. `oat-project-import-plan`
+2. Implement:
+   - `oat-project-implement` (sequential)
+   - `oat-project-subagent-implement` (parallel/subagent-driven)
+3. `oat-project-review-provide` / `oat-project-pr-final`
+4. Optional `oat-project-promote-spec-driven` to switch project mode to spec-driven lifecycle
+
+## Lane diagrams
+
+### Spec-Driven workflow lane
+
+```mermaid
+flowchart LR
+  D["Discover"] --> S["Spec"] --> G["Design"] --> P["Plan"]
+  P --> I1["Implement (oat-project-implement)"]
+  P --> I2["Implement (oat-project-subagent-implement)"]
+  I1 --> R["Review"] --> PR["PR"] --> Doc["Docs (optional)"] --> C["Complete"]
+  I2 --> R
+```
+
+### Quick lane
+
+```mermaid
+flowchart LR
+  Q["Quick Start\n(adaptive discovery)"] --> D{"Design depth?"}
+  D -->|Straight to plan| P["Plan"]
+  D -->|Lightweight design| LD["Design (quick)"] --> P
+  D -->|Promote| SD["→ Spec-Driven lane"]
+  P --> QI1["Implement (oat-project-implement)"]
+  P --> QI2["Implement (oat-project-subagent-implement)"]
+  QI1 --> QR["Review / PR"]
+  QI2 --> QR
+```
+
+### Import lane
+
+```mermaid
+flowchart LR
+  I["Import Plan"] --> II1["Implement (oat-project-implement)"]
+  I --> II2["Implement (oat-project-subagent-implement)"]
+  II1 --> IR["Review / PR"]
+  II2 --> IR
+```
+
+### Capture lane
+
+Retroactive project creation for work done outside the OAT project workflow. Common scenario: mobile/cloud sessions where you brainstorm and implement with an agent, then want to open a PR and review from your desktop.
+
+```mermaid
+flowchart LR
+  W["Work on branch\n(no project)"] --> Cap["oat-project-capture"]
+  Cap --> R["Review / PR"]
+```
+
+Entry point: `/oat-project-capture` (skill-only, no CLI command — requires agent conversation context).
+
+Key differences from other lanes:
+
+- **No plan generation** — the work is already done; the scaffold-created `plan.md` template is kept but not authored
+- **Discovery from conversation** — `discovery.md` captures intent and decisions from the agent's conversation context, not from requirements analysis
+- **Implementation from commits** — `implementation.md` is populated from commit history with SHAs, not from executing plan tasks
+- **Lifecycle state is user-chosen** — user decides whether the project is ready for review or still in progress
+
+## Artifact progression
+
+`discovery.md` -> `spec.md` -> `design.md` -> `plan.md` -> `implementation.md` -> `summary.md`
+
+Quick lane progression:
+
+`discovery.md` -> [`design.md` (optional lightweight)] -> `plan.md` -> `implementation.md`
+
+Import lane progression:
+
+`references/imported-plan.md` -> `plan.md` -> `implementation.md` (`spec.md`/`design.md` optional)
+
+Capture lane progression:
+
+`discovery.md` (from conversation) + `implementation.md` (from commits) — no forward-looking artifacts
+
+## Operational rules
+
+- Keep `state.md`, `plan.md`, and `implementation.md` synchronized.
+- Stop at configured HiLL checkpoints.
+- Do not move lifecycle forward when required review gates are unresolved.
+
+## Active project resolution
+
+- Active project state is stored in `.oat/config.local.json` (`activeProject`, repo-relative path).
+- Projects root is stored in `.oat/config.json` (`projects.root`) and can be read via `oat config get projects.root`.
+- Workflow skills prefer `oat config get activeProject` / `oat config get projects.root` rather than reading pointer files directly.
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/spec.md`
+- `.oat/projects/<scope>/<project>/design.md`
+- `.oat/projects/<scope>/<project>/plan.md`
+- `.oat/projects/<scope>/<project>/implementation.md`

package/assets/docs/guide/workflow/pr-flow.md

@@ -0,0 +1,55 @@
+---
+title: PR Flow
+description: 'PR generation inputs, outputs, artifact expectations, and frontmatter handling.'
+---
+
+# PR Flow
+
+Two PR paths:
+
+- `oat-project-pr-progress`: progress PR for one phase or partial scope
+- `oat-project-pr-final`: final project PR into `main`
+
+## Inputs
+
+Expected artifacts:
+
+- Required (all modes): `plan.md`
+- Required (spec-driven mode): `spec.md`, `design.md`
+- Optional (quick/import): `spec.md`, `design.md`
+- Recommended (quick mode): `discovery.md`
+- Recommended (import mode): `references/imported-plan.md`
+- Recommended: `implementation.md` final summary
+- Recommended: `summary.md` — pr-final treats it as the primary source for the PR Summary section and automatically refreshes it first when missing or stale
+- Required gate for final PR: review table final row should be `passed`
+
+## Output
+
+Local artifact path:
+
+- `.oat/projects/<scope>/<project>/pr/*.md`
+
+GitHub PR body policy:
+
+- Keep YAML frontmatter in local artifact
+- Strip frontmatter from submitted PR body
+
+## Post-PR state
+
+After `oat-project-pr-final` creates the PR, `state.md` transitions to `oat_phase_status: pr_open`. This signals "awaiting human review" rather than "done."
+
+`pr_open` is the routing/review posture. Actual PR existence is tracked separately in:
+
+- `oat_pr_status` — lifecycle state for the PR itself (`ready`, `open`, etc.)
+- `oat_pr_url` — the tracked PR URL when a PR exists
+
+From `pr_open`:
+
+- **Feedback received:** run `oat-project-revise` to create revision tasks and re-enter implementation
+- **Approved:** run `oat-project-complete` to finalize and archive the project. If `oat_pr_status: open` is already tracked, completion skips asking whether to open a PR again and can show the tracked `oat_pr_url` in its summary.
+
+## Reference artifacts
+
+- `.agents/skills/oat-project-pr-progress/SKILL.md`
+- `.agents/skills/oat-project-pr-final/SKILL.md`
+- `.oat/projects/<scope>/<project>/pr/`

package/assets/docs/guide/workflow/repo-analysis.md

@@ -0,0 +1,96 @@
+---
+title: Repository Analysis
+description: 'Repository-level analysis commands for collecting and triaging PR review comments.'
+---
+
+# Repository Analysis (`oat repo`)
+
+The `oat repo` command group provides repository-level analysis and insight tools. These commands operate across merged pull requests rather than on individual PRs.
+
+## Commands
+
+| Command                                  | Purpose                                                              |
+| ---------------------------------------- | -------------------------------------------------------------------- |
+| `oat repo pr-comments collect`           | Collect PR review comments from merged PRs via GitHub GraphQL API.   |
+| `oat repo pr-comments triage-collection` | Interactively triage collected comments with keep/discard decisions. |
+
+## `oat repo pr-comments collect`
+
+Fetches review comments from merged pull requests using the GitHub GraphQL API (`gh api graphql`), filters noise, assigns stable IDs, and outputs monthly JSON + Markdown chunks.
+
+### Options
+
+| Option                | Required | Default                | Description                                                  |
+| --------------------- | -------- | ---------------------- | ------------------------------------------------------------ |
+| `--since <date>`      | Yes      | —                      | Start date for merged PRs (YYYY-MM-DD).                      |
+| `--until <date>`      | No       | Today                  | End date for merged PRs (YYYY-MM-DD).                        |
+| `--out-dir <path>`    | No       | `.oat/review-comments` | Output directory for collected comments.                     |
+| `--repo <owner/name>` | No       | Current git remote     | GitHub repository. Resolved from `origin` remote if omitted. |
+| `--no-ignore-bots`    | No       | Bots filtered          | Include bot comments in output.                              |
+
+### Behavior
+
+**GraphQL collection:** Uses `gh api graphql` to search merged PRs within the date range. Fetches PR metadata (title, author, merge date) alongside review comments in a single query. Handles nested pagination for PRs with more than 100 review comments.
+
+**Repository resolution:** When `--repo` is omitted, parses `owner/name` from `git remote get-url origin` (supports both SSH and HTTPS URLs, including repo names with dots).
+
+**Bot filtering** (enabled by default, disable with `--no-ignore-bots`):
+
+- GitHub API author type (`Bot`)
+- Login suffix (`[bot]`)
+- Known service logins (CodeRabbit, Copilot, Sourcery, Vercel, Supabase, Codacy, SonarCloud, Codecov, Netlify, Linear, Changeset Bot, Renovate, Dependabot, Snyk)
+
+**Trivial comment filtering:**
+
+- Known phrase patterns (LGTM, nit, +1, looks good, ship it, nice, great, thanks, emoji-only)
+- Short comments under 5 words — unless they contain code references (backticks, file paths, line numbers)
+
+**Output:**
+
+- Comments are assigned stable sequential IDs (`RC-001`, `RC-002`, ...) that correlate across JSON and Markdown.
+- Grouped by PR merge month (not comment creation date) in reverse-chronological order.
+- Each month produces a paired `{YYYY-MM}.json` and `{YYYY-MM}.md` file in the output directory.
+
+### Example
+
+```bash
+oat repo pr-comments collect --since 2025-01-01
+oat repo pr-comments collect --since 2025-06-01 --until 2025-12-31 --repo myorg/myrepo
+```
+
+## `oat repo pr-comments triage-collection`
+
+Interactive keep/discard triage of previously collected review comments. Reads a monthly JSON chunk and presents each comment for disposition.
+
+### Options
+
+| Option                | Required | Default                | Description                           |
+| --------------------- | -------- | ---------------------- | ------------------------------------- |
+| `--month <YYYY-MM>`   | Yes      | —                      | Month chunk to triage.                |
+| `--input-dir <path>`  | No       | `.oat/review-comments` | Directory containing collected JSON.  |
+| `--output-dir <path>` | No       | `.oat/review-comments` | Output directory for triaged results. |
+
+### Behavior
+
+- Requires an interactive terminal (TTY). Fails with a clear error in non-interactive mode.
+- For each comment, displays a summary (PR number/title, file path, author, date, body preview) and prompts `[k]eep` or `[d]iscard` (default: keep).
+- Writes kept comments to `{YYYY-MM}.triaged.json` in the output directory.
+
+### Example
+
+```bash
+oat repo pr-comments triage-collection --month 2025-03
+oat repo pr-comments triage-collection --month 2025-03 --input-dir ./collected --output-dir ./triaged
+```
+
+## Dependency Injection
+
+Both commands accept dependency injection for testability:
+
+- `collect`: `CollectDependencies` interface — injectable `ghGraphQL` (GraphQL executor) and `resolveCurrentRepo` (git remote parser)
+- `triage-collection`: `TriageDependencies` interface — injectable `readJsonFile` (JSON reader)
+
+## Related
+
+- Source: `packages/cli/src/commands/repo/pr-comments/`
+- Types: `packages/cli/src/commands/repo/pr-comments/collect/pr-comments.types.ts`

package/assets/docs/guide/workflow/reviews.md

@@ -0,0 +1,98 @@
+---
+title: Reviews
+description: 'Review request/receive loop, status progression, severity policy, and quality gates.'
+---
+
+# Reviews
+
+Review loop:
+
+1. Request review (`oat-project-review-provide`)
+2. Receive review and convert findings into tasks (`oat-project-review-receive`)
+3. Implement fixes (`oat-project-implement`)
+4. Re-review until passing status
+
+## Storage contract
+
+- New project review artifacts are written to tracked `reviews/` directories.
+- `oat-project-review-receive` consumes the active top-level review artifact, updates project bookkeeping, then archives that artifact to `reviews/archived/`.
+- `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/`.
+
+## Project vs ad-hoc
+
+**Provide** (request a review):
+
+- `oat-project-review-provide` is project-scoped and requires active project state (resolved via `oat config get activeProject` / `.oat/config.local.json`) plus project `state.md`.
+- `oat-review-provide` is for non-project commit-range reviews (ad-hoc, no project state required).
+
+**Receive** (process review findings):
+
+- `oat-project-review-receive` processes local review artifacts within a project context (converts findings to plan tasks).
+- `oat-project-review-receive-remote` processes GitHub PR comment feedback within a project context (converts findings to plan tasks with stable `pNN-tNN` IDs).
+- `oat-review-receive` processes local review artifacts in ad-hoc mode (standalone task-list output, no project state mutation).
+- `oat-review-receive-remote` processes GitHub PR comment feedback in ad-hoc mode (standalone task-list output, optional reply posting).
+
+## Status model
+
+Status progression in `plan.md` Reviews table:
+
+- `pending`
+- `received`
+- `fixes_added`
+- `fixes_completed`
+- `passed`
+
+## Current policy
+
+- Critical/Important: address before pass.
+- Medium: address by default; defer only with explicit approval and recorded rationale/disposition.
+- Minor (non-final scopes): auto-deferred by default with rationale; do not block review completion.
+- Minor (final scope): not auto-deferred; require explicit user disposition (defer vs convert), and explain each minor in plain language before asking.
+
+## Auto-review at checkpoints
+
+When `autoReviewAtCheckpoints` is enabled (via `oat config set autoReviewAtCheckpoints true` or per-project in `plan.md` frontmatter), completing a plan phase checkpoint automatically spawns a subagent review. The review scope covers every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase checkpoint reviews use inclusive phase-range scopes such as `p02-p03`. The final phase checkpoint triggers a `code final` review.
+
+Auto-triggered reviews use `oat_review_invocation: auto` in the review artifact frontmatter. In auto mode, `oat-project-review-receive` auto-converts all findings to fix tasks without user prompts (Minor findings that are clearly out of scope are deferred with a note).
+
+This feature is opt-in and disabled by default. When disabled, the manual `oat-project-review-provide` workflow applies.
+
+## Phase and final review
+
+Use phase-scoped review artifacts during implementation (`p01`, `p02`, etc), then run final review before project closeout.
+
+Final review `passed` gate requires:
+
+- No unresolved Critical/Important/Medium findings.
+- Deferred Medium findings resurfaced and explicitly dispositioned.
+- Minor findings explicitly dispositioned (after plain-language explanation).
+
+## Subagent Compatibility
+
+`oat-project-review-provide` uses provider-aware subagent dispatch when available:
+
+- Claude Code: dispatch `oat-reviewer` with `subagent_type` (resolved from `.claude/agents/oat-reviewer.md`).
+- Cursor: dispatch `oat-reviewer` via explicit `/oat-reviewer` invocation or natural mention (resolved from `.cursor/agents/oat-reviewer.md`; `.claude/agents/oat-reviewer.md` is also supported for compatibility).
+- Codex multi-agent runtimes: Codex can auto-decide when to spawn agents, or you can explicitly request agent spawning (optionally with `agent_type`).
+  - Requires Codex config prerequisites:
+    - `[features] multi_agent = true`
+    - If explicit role pinning is used, role must be built-in (`default`/`worker`/`explorer`) or configured under `[agents.<name>]`.
+  - Project-scope Codex role files are generated from canonical `.agents/agents/*.md` during `oat sync --scope project`.
+  - User-scope Codex role generation (`~/.codex`) is intentionally deferred.
+  - Some Codex hosts require explicit user authorization before the skill may call `spawn_agent`. In those hosts, `oat-project-review-provide` should ask whether to delegate to `oat-reviewer` instead of reporting the reviewer as unresolved.
+- If subagent dispatch is unavailable, follow the existing fallback path (fresh session preferred, inline reset as fallback).
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/plan.md` (`## Reviews`)
+- `.oat/projects/<scope>/<project>/reviews/` (active tracked review artifacts)
+- `.oat/projects/<scope>/<project>/reviews/archived/` (local-only historical review artifacts)
+- `.oat/projects/local/orphan-reviews/` (default local-only storage for ad-hoc review artifacts)
+- `.oat/repo/reviews/` (tracked storage convention when explicitly desired)
+- `.agents/skills/oat-review-provide/SKILL.md`
+- `.agents/skills/oat-review-receive/SKILL.md`
+- `.agents/skills/oat-review-receive-remote/SKILL.md`
+- `.agents/skills/oat-project-review-provide/SKILL.md`
+- `.agents/skills/oat-project-review-receive/SKILL.md`
+- `.agents/skills/oat-project-review-receive-remote/SKILL.md`

package/assets/docs/guide/workflow/state-machine.md

@@ -0,0 +1,74 @@
+---
+title: State Machine
+description: 'Workflow and review state transitions across lifecycle phases and checkpoints.'
+---
+
+# State Machine
+
+## State Transition Map
+
+```mermaid
+flowchart TD
+  D["Discovery in progress"] --> RS["Ready for spec"]
+  RS --> S["Spec in progress"] --> RD["Ready for design"]
+  RD --> G["Design in progress"] --> RP["Ready for plan"]
+  RP --> P["Plan in progress"] --> RI["Ready for implement"]
+  RI --> I["Implement in progress"] --> IC["Implement complete"]
+  IC --> PRO["PR open (pr_open)"]
+  PRO --> REV["Revise (in_progress)"]
+  REV --> PRO
+  PRO --> C["Complete"]
+
+  I --> RV["Review received"]
+  RV --> FA["Fixes added"]
+  FA --> FC["Fixes completed"]
+  FC --> PASSED["Review passed"]
+  PASSED --> I
+```
+
+## Phase status values
+
+`oat_phase_status` in `state.md`:
+
+- `in_progress` — phase is actively being worked on
+- `complete` — phase is finished
+- `pr_open` — post-PR review posture. Set by `oat-project-pr-final`. Agents should route to `oat-project-revise` (for feedback) or `oat-project-complete` (when approved).
+
+`pr_open` is not the source of truth for actual PR existence. That is tracked separately in `state.md` via:
+
+- `oat_pr_status` — PR lifecycle state (`ready`, `open`, `closed`, `merged`)
+- `oat_pr_url` — tracked PR URL when a PR exists
+
+## Lifecycle progression
+
+Typical progression:
+
+1. Discovery in progress
+2. Ready for spec
+3. Spec in progress
+4. Ready for design
+5. Design in progress
+6. Ready for plan
+7. Plan in progress
+8. Ready for implement
+9. Implement in progress
+10. Implement complete (final review passed)
+11. PR open (`pr_open`) — post-PR review posture; actual PR existence is tracked via `oat_pr_status` / `oat_pr_url`
+12. Revision loop (optional): `pr_open` → revise → `in_progress` → implement → `pr_open`
+13. Complete
+
+## Review progression
+
+In `plan.md` Reviews table:
+
+- `pending` -> `received` -> `fixes_added` -> `fixes_completed` -> `passed`
+
+## Guardrail
+
+Do not move to the next lifecycle state if review/state artifacts indicate unresolved gates.
+
+## Reference artifacts
+
+- `.oat/projects/<scope>/<project>/state.md`
+- `.oat/projects/<scope>/<project>/plan.md` (`## Reviews`)
+- `.oat/projects/<scope>/<project>/implementation.md`

package/assets/docs/index.md

@@ -0,0 +1,45 @@
+---
+title: OAT Documentation
+description: 'An open-source toolkit for portable, provider-agnostic agent tooling and workflows.'
+---
+
+# OAT Documentation
+
+Open Agent Toolkit (OAT) is an open-source toolkit for portable, provider-agnostic agent tooling and workflows. It lets teams define canonical agent capabilities once, sync them across providers, and optionally run tracked human-in-the-loop workflows on top.
+
+OAT is organized as three distinct capabilities that can be used together or independently:
+
+1. Provider interoperability CLI (canonical skills/agents + provider sync/drift tooling)
+2. Reusable skills, CLI commands, and tooling for provider-agnostic development workflows
+3. Optional workflow system (discovery/spec/design/plan/implement/review/PR lifecycle)
+
+## Contents
+
+- [Quickstart](quickstart.md) - Shared entry point for interop-only, tooling, and workflow adoption.
+- [User Guide](guide/index.md) - User-facing guide for provider sync, docs tooling, workflow execution, skills, and ideas.
+- [Contributing](contributing/index.md) - Contributor-facing guide for code, docs, markdown features, and skill authoring.
+- [Reference](reference/index.md) - Durable reference material for operating and maintaining OAT.
+
+## Choose a usage path
+
+- Provider sync and CLI users:
+  - Start with [`quickstart.md`](quickstart.md)
+  - Then [`guide/provider-sync/index.md`](guide/provider-sync/index.md) and [`guide/cli-reference.md`](guide/cli-reference.md)
+- Docs-tooling users:
+  - Start with [`guide/documentation/index.md`](guide/documentation/index.md)
+  - Then [`guide/documentation/commands.md`](guide/documentation/commands.md)
+- Workflow users:
+  - Start with [`quickstart.md`](quickstart.md)
+  - Then [`guide/workflow/index.md`](guide/workflow/index.md), [`guide/skills/index.md`](guide/skills/index.md), and [`reference/index.md`](reference/index.md)
+- Contributors:
+  - Start with [`contributing/index.md`](contributing/index.md)
+  - Then route into code, docs, markdown features, or skill authoring guidance
+- Idea and backlog users:
+  - Start with [`guide/ideas/index.md`](guide/ideas/index.md)
+
+## Source-of-truth hierarchy
+
+1. Runtime behavior: `packages/cli/src/**`
+2. Skill behavior contracts: `.agents/skills/*/SKILL.md`
+3. OAT templates and runtime state: `.oat/templates/**`, `.oat/sync/**`, `.oat/config.json`, `.oat/config.local.json`
+4. Repo reference records: `.oat/repo/**`