@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-review-provide/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: oat-review-provide
+version: 1.2.0
+description: Use when you need an ad-hoc review outside an active OAT project lifecycle. Reviews code or artifacts without project phase state, unlike oat-project-review-provide.
+argument-hint: '[unstaged|staged|base_branch=<branch>|base_sha=<sha>|<sha1>..<sha2>|--files <path1,path2,...>] [--output <path>] [--mode auto|local|tracked|inline]'
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Ad-Hoc Review
+
+Request and execute a code/file review that is not tied to an OAT project lifecycle.
+
+## Prerequisites
+
+- Git repository with changes/files to review.
+- User wants a code/diff review without requiring an `activeProject` entry in `.oat/config.local.json` or project artifacts.
+
+## Mode Assertion
+
+**OAT MODE: Ad-Hoc Review**
+
+**Purpose:** Review commit ranges, working-tree diffs, or explicit files and write an optional review artifact even when no project state exists.
+
+**BLOCKED Activities:**
+
+- No implementation/code changes.
+- No project state mutations unless user explicitly requests conversion into an OAT project flow.
+
+**ALLOWED Activities:**
+
+- Range-based code review.
+- Optional review artifact generation (tracked active, local active, or inline).
+- Inline review output when requested.
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- Expecting project artifacts (`state.md`, `plan.md`) for this review → STOP and continue in ad-hoc mode.
+- Auto-committing tracked artifacts without user approval → STOP and ask.
+
+**Recovery:**
+
+1. Re-resolve review range directly from git.
+2. Re-resolve artifact destination policy (tracked active, local active, or inline).
+
+## Progress Indicators (User-Facing)
+
+When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.
+
+- Print a phase banner once at start using horizontal separators, e.g.:
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  OAT ▸ PROVIDE AD-HOC REVIEW
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Before multi-step work, print step indicators, e.g.:
+  - `[1/4] Resolving review scope…`
+  - `[2/4] Gathering files + context…`
+  - `[3/4] Running review analysis…`
+  - `[4/4] Writing review artifact…`
+
+## Process
+
+### Step 0: Resolve Review Scope
+
+Parse `$ARGUMENTS` and resolve one scope mode:
+
+- `--files <path1,path2,...>` → explicit file review (works for old/pre-existing files)
+- `unstaged` → review current unstaged working tree changes
+- `staged` → review staged changes (`--cached`)
+- `base_branch=<branch>` → review current branch against merge-base with branch (e.g., `base_branch=main`)
+- `base_sha=<sha>` → `{sha}..HEAD`
+- `<sha1>..<sha2>` → exact range
+- If omitted, ask user to choose one of the above and recommend `unstaged` for in-progress local review.
+
+Recommended fallback:
+
+```bash
+MERGE_BASE=$(git merge-base origin/main HEAD 2>/dev/null || git merge-base main HEAD 2>/dev/null)
+SCOPE_RANGE="$MERGE_BASE..HEAD"
+```
+
+Branch-based range example:
+
+```bash
+BASE_BRANCH="main"
+MERGE_BASE=$(git merge-base "origin/$BASE_BRANCH" HEAD 2>/dev/null || git merge-base "$BASE_BRANCH" HEAD 2>/dev/null)
+SCOPE_RANGE="$MERGE_BASE..HEAD"
+```
+
+### Step 1: Gather Scope Evidence (Mode-Aware)
+
+For `--files` mode:
+
+- Split comma-separated list
+- Validate each file exists
+- Set `FILES_CHANGED` to explicit files
+- Set `SCOPE_RANGE=""` and `COMMITS=""`
+
+For `unstaged` mode:
+
+```bash
+FILES_CHANGED=$(git diff --name-only 2>/dev/null || true)
+FILE_COUNT=$(echo "$FILES_CHANGED" | sed '/^$/d' | wc -l | awk '{print $1}')
+COMMITS=""
+```
+
+For `staged` mode:
+
+```bash
+FILES_CHANGED=$(git diff --cached --name-only 2>/dev/null || true)
+FILE_COUNT=$(echo "$FILES_CHANGED" | sed '/^$/d' | wc -l | awk '{print $1}')
+COMMITS=""
+```
+
+For commit-range modes:
+
+```bash
+FILES_CHANGED=$(git diff --name-only "$SCOPE_RANGE" 2>/dev/null || true)
+FILE_COUNT=$(echo "$FILES_CHANGED" | sed '/^$/d' | wc -l | awk '{print $1}')
+COMMITS=$(git log --oneline "$SCOPE_RANGE" 2>/dev/null || true)
+```
+
+Show the resolved scope and ask for confirmation before review.
+
+### Step 2: Resolve Artifact Destination Policy
+
+If user requested inline review explicitly, skip file output.
+
+Otherwise resolve destination via helper script:
+
+```bash
+bash .agents/skills/oat-review-provide/scripts/resolve-review-output.sh --mode auto
+```
+
+Policy:
+
+- If `.oat/repo/reviews` exists and is not gitignored, assume user wants tracked active artifacts there.
+- Otherwise default to active local `.oat/projects/local/orphan-reviews`.
+- Do **not** write new review artifacts directly into any `archived/` directory; those are historical locations used after `oat-review-receive` processes a review.
+- If user preference is unclear, ask and recommend local-only.
+
+If user asks for tracked `.oat/repo/reviews` and it is gitignored, warn and ask whether to:
+
+- choose a different tracked destination, or
+- use local-only/inline.
+
+### Step 3: Determine Output Path (File Mode)
+
+Derive a **scope slug** from the resolved scope mode so that the filename indicates what was reviewed:
+
+| Scope mode             | Slug derivation                      | Example filename                              |
+| ---------------------- | ------------------------------------ | --------------------------------------------- |
+| `base_branch=<branch>` | Current branch name                  | `ad-hoc-review-2026-02-16-oat-repo.md`        |
+| `unstaged`             | Literal `unstaged`                   | `ad-hoc-review-2026-02-16-unstaged.md`        |
+| `staged`               | Literal `staged`                     | `ad-hoc-review-2026-02-16-staged.md`          |
+| `--files <paths>`      | First 2–3 basenames, joined with `-` | `ad-hoc-review-2026-02-16-auth-login.md`      |
+| `base_sha=<sha>`       | Short SHA (7 chars)                  | `ad-hoc-review-2026-02-16-abc1234.md`         |
+| `<sha1>..<sha2>`       | Both short SHAs joined with `-`      | `ad-hoc-review-2026-02-16-abc1234-def5678.md` |
+
+```bash
+mkdir -p "$OUTPUT_DIR"
+TODAY=$(date +%Y-%m-%d)
+
+# Derive SCOPE_SLUG based on scope mode (examples):
+# base_branch → SCOPE_SLUG=$(git branch --show-current | tr '/' '-')
+# unstaged    → SCOPE_SLUG="unstaged"
+# staged      → SCOPE_SLUG="staged"
+# --files     → SCOPE_SLUG from first 2-3 basenames, stripped of extensions, joined with '-'
+# sha range   → SCOPE_SLUG from short SHAs
+
+# Sanitize: lowercase, replace non-alphanumeric with '-', collapse runs, trim to 40 chars
+SCOPE_SLUG=$(echo "$SCOPE_SLUG" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g; s/--*/-/g; s/^-//; s/-$//' | cut -c1-40)
+
+OUT_FILE="$OUTPUT_DIR/ad-hoc-review-${TODAY}-${SCOPE_SLUG}.md"
+```
+
+If the file already exists (same scope reviewed twice in one day), suffix with `-v2`, `-v3`, etc.
+
+### Step 4: Run Review
+
+Use the same severity model and checklist as project reviews:
+
+- Critical / Important / Minor findings
+- file:line references
+- actionable fix guidance
+- verification commands
+
+Template source of truth:
+
+- `.agents/skills/oat-review-provide/references/review-artifact-template.md`
+
+### Step 5: Write Artifact or Return Inline
+
+- If file mode: write review artifact to `OUT_FILE`.
+- If inline mode: return the same sections directly in session output.
+
+### Step 6: Commit Bookkeeping (Tracked Destinations Only)
+
+If artifact is in tracked storage (e.g., `.oat/repo/reviews`), ask whether to commit bookkeeping.
+
+Suggested commit (when approved):
+
+```bash
+git add "{artifact-path}"
+git commit -m "chore(oat): record ad-hoc review artifact"
+```
+
+For local-active or inline modes, do not commit unless user explicitly requests.
+
+### Step 7: Output Summary
+
+Report (required):
+
+- scope/range reviewed
+- files reviewed
+- findings counts by severity
+- `Review artifact: {absolute-or-repo-relative path}` (or explicitly `inline-only`)
+- whether bookkeeping commit was created/deferred
+
+## Success Criteria
+
+- ✅ Scope mode resolved and confirmed (`--files`, `unstaged`, `staged`, or commit range).
+- ✅ Files in scope collected.
+- ✅ Output policy resolved (local-only, tracked, or inline).
+- ✅ Review findings produced with severity + file references.
+- ✅ Review artifact written (or inline review returned).
+- ✅ Artifact location explicitly reported after write.
+- ✅ Tracked bookkeeping commit is explicit (created or intentionally deferred).

package/assets/skills/oat-review-provide/references/review-artifact-template.md

@@ -0,0 +1,55 @@
+# Ad-Hoc Review Artifact Template
+
+Use this template for non-project commit-range reviews.
+
+````markdown
+---
+oat_generated: true
+oat_generated_at: YYYY-MM-DD
+oat_review_type: code
+oat_review_scope: { scope }
+oat_review_scope_mode: { files|unstaged|staged|range }
+oat_project: null
+oat_review_mode: ad_hoc
+---
+
+# Code Review: {scope}
+
+**Reviewed:** YYYY-MM-DD
+**Range:** {SCOPE_RANGE}
+**Files reviewed:** {N}
+
+## Summary
+
+{2-3 sentence summary}
+
+## Findings
+
+### Critical
+
+{None or list}
+
+### Important
+
+{None or list}
+
+### Minor
+
+{None or list}
+
+## Verification Commands
+
+```bash
+{command 1}
+{command 2}
+```
+````
+
+## Next Step
+
+- If this review should feed an OAT project lifecycle, import/attach it to that project and run `oat-project-review-receive`.
+- Otherwise, apply fixes directly and re-run `oat-review-provide` for a follow-up pass.
+
+```
+
+```

package/assets/skills/oat-review-provide/scripts/resolve-review-output.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# resolve-review-output.sh - resolve default output destination for non-project reviews
+# Usage:
+#   resolve-review-output.sh [--mode auto|local|tracked|inline] [--output <path>]
+
+set -eu
+
+MODE="auto"
+OUTPUT=""
+
+usage() {
+  cat <<USAGE
+Usage: resolve-review-output.sh [--mode auto|local|tracked|inline] [--output <path>]
+
+Resolves output destination for ad-hoc (non-project) review artifacts.
+
+Policy:
+- If --output is provided, use it directly.
+- If mode=inline, no artifact file is written.
+- In auto mode:
+  - If .oat/repo/reviews exists and is NOT gitignored, use it (tracked convention).
+  - Otherwise, use .oat/projects/local/orphan-reviews (local-only default).
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode)
+      MODE="$2"
+      shift 2
+      ;;
+    --output)
+      OUTPUT="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+case "$MODE" in
+  auto|local|tracked|inline) ;;
+  *)
+    echo "Invalid --mode: $MODE" >&2
+    exit 1
+    ;;
+esac
+
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "Error: Must be run from a git repository" >&2
+  exit 1
+fi
+
+is_gitignored() {
+  local path="$1"
+  if git check-ignore -q "$path" 2>/dev/null; then
+    echo "true"
+  else
+    echo "false"
+  fi
+}
+
+# Resolve explicit output first
+if [[ -n "$OUTPUT" ]]; then
+  echo "review_mode=file"
+  echo "output_dir=$OUTPUT"
+  echo "output_kind=custom"
+  echo "output_gitignored=$(is_gitignored "$OUTPUT")"
+  echo "reason=explicit_output"
+  exit 0
+fi
+
+if [[ "$MODE" == "inline" ]]; then
+  echo "review_mode=inline"
+  echo "output_dir="
+  echo "output_kind=inline"
+  echo "output_gitignored=n/a"
+  echo "reason=inline_mode"
+  exit 0
+fi
+
+TRACKED_DIR=".oat/repo/reviews"
+LOCAL_DIR=".oat/projects/local/orphan-reviews"
+
+if [[ "$MODE" == "tracked" ]]; then
+  echo "review_mode=file"
+  echo "output_dir=$TRACKED_DIR"
+  echo "output_kind=tracked"
+  echo "output_gitignored=$(is_gitignored "$TRACKED_DIR")"
+  echo "reason=forced_tracked"
+  exit 0
+fi
+
+if [[ "$MODE" == "local" ]]; then
+  echo "review_mode=file"
+  echo "output_dir=$LOCAL_DIR"
+  echo "output_kind=local"
+  echo "output_gitignored=$(is_gitignored "$LOCAL_DIR")"
+  echo "reason=forced_local"
+  exit 0
+fi
+
+# auto mode
+if [[ -d "$TRACKED_DIR" ]] && [[ "$(is_gitignored "$TRACKED_DIR")" == "false" ]]; then
+  echo "review_mode=file"
+  echo "output_dir=$TRACKED_DIR"
+  echo "output_kind=tracked"
+  echo "output_gitignored=false"
+  echo "reason=existing_tracked_dir"
+  exit 0
+fi
+
+echo "review_mode=file"
+echo "output_dir=$LOCAL_DIR"
+echo "output_kind=local"
+echo "output_gitignored=$(is_gitignored "$LOCAL_DIR")"
+echo "reason=default_local_only"

package/assets/skills/oat-review-receive/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: oat-review-receive
+version: 1.2.0
+description: Use when processing review findings outside project context. Converts local review artifacts into actionable task lists.
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Review Receive (Ad-hoc Local)
+
+Process local review artifacts into a normalized findings register and generate actionable standalone tasks.
+
+## Prerequisites
+
+- A review artifact exists locally (`.md`).
+- User wants ad-hoc triage without mutating OAT project lifecycle artifacts.
+
+## Mode Assertion
+
+**OAT MODE: Review Receive**
+
+**Purpose:** Parse local review findings, classify severity consistently, triage disposition with user input, and generate a task list.
+
+**BLOCKED Activities:**
+
+- No implementation/code changes.
+- No `plan.md`, `state.md`, or `implementation.md` lifecycle mutations.
+- No silent dismissal/defer decisions.
+
+**ALLOWED Activities:**
+
+- Locating review artifacts.
+- Parsing markdown findings into normalized records.
+- Presenting findings counts and summaries.
+- Interactive triage (`convert`, `defer`, `dismiss`).
+- Writing standalone task-list output.
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- Editing project lifecycle docs in ad-hoc mode -> STOP and revert to task-list output only.
+- Triaging without presenting a findings overview first -> STOP and show overview before disposition prompts.
+- Skipping Medium finding rationale when proposing deferral -> STOP and collect explicit rationale.
+
+**Recovery:**
+
+1. Re-locate review artifact from the path provided or last known location.
+2. Re-parse findings from the artifact (idempotent — no state mutation in ad-hoc mode).
+3. Resume triage from the first un-dispositioned finding.
+
+## Progress Indicators (User-Facing)
+
+Print this banner once at start:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ REVIEW RECEIVE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Use these step indicators:
+
+- `[1/4] Locating review artifact...`
+- `[2/4] Parsing findings...`
+- `[3/4] Triaging findings...`
+- `[4/4] Generating task list...`
+
+## Findings Model
+
+Normalize every finding to this shape:
+
+```yaml
+finding:
+  id: "C1" | "I1" | "M1" | "m1"
+  severity: critical | important | medium | minor
+  title: string
+  file: string | null
+  line: number | null
+  body: string
+  fix_guidance: string | null
+  source: local_artifact
+  source_ref: string
+```
+
+Severity conventions:
+
+- `critical`: Missing P0 requirements, security vulnerabilities, broken behavior.
+- `important`: Missing P1 requirements, major error-handling or maintainability gaps.
+- `medium`: P2 issues with meaningful impact.
+- `minor`: Low-impact polish/documentation/style issues.
+
+ID conventions:
+
+- Critical: `C1`, `C2`, ...
+- Important: `I1`, `I2`, ...
+- Medium: `M1`, `M2`, ...
+- Minor: `m1`, `m2`, ...
+
+## Process
+
+### Step 1: Locate Active Review Artifact
+
+Artifact source priority:
+
+1. Explicit path from `$ARGUMENTS`
+2. Most recent top-level file under `.oat/repo/reviews/`
+3. Most recent top-level file under `.oat/projects/local/orphan-reviews/`
+
+Discovery command example:
+
+```bash
+ls -t .oat/repo/reviews/*.md .oat/projects/local/orphan-reviews/*.md 2>/dev/null | head -20
+```
+
+Selection rules:
+
+- Ignore `.oat/repo/reviews/archived/` and `.oat/projects/local/orphan-reviews/archived/`.
+- Treat archived review artifacts as history; do not re-triage them by default.
+- If an explicit path points into an `archived/` directory, stop and ask for an active review artifact instead.
+
+If multiple candidates exist, auto-select the most recent by `oat_generated_at` frontmatter date (not filesystem mtime, which is unreliable across branches). Inform the user which artifact was selected and list any others for awareness. Do not prompt for selection.
+
+Validation:
+
+- File exists and is readable.
+- Extension is `.md` (or confirm nonstandard markdown extension).
+- Content is non-empty.
+
+### Step 2: Parse Findings
+
+Parse by severity sections/headings using case-insensitive matching:
+
+- `Critical`
+- `Important`
+- `Medium`
+- `Minor`
+
+Compatibility rule:
+
+- If artifact uses a 3-tier model (no Medium section), treat Medium as zero findings.
+
+Extraction guidance per finding item:
+
+- Derive `title` from first concise clause/line.
+- Extract `file` + `line` if present in common patterns (`path:line`, fenced diff context, inline references).
+- Populate `body` with the finding detail.
+- Populate `fix_guidance` when explicit fix direction exists.
+- Set `source: local_artifact`.
+- Set `source_ref` to the artifact path.
+
+### Step 3: Present Findings Overview
+
+Before asking for dispositions, print:
+
+- Total counts per severity.
+- A compact finding register grouped by severity, each showing:
+  - `id`
+  - `title`
+  - `file:line` (or `-`)
+
+Example summary:
+
+```text
+Critical: 1
+Important: 2
+Medium: 1
+Minor: 3
+```
+
+If there are zero findings across all severities, output a clean result and stop.
+
+### Step 4: Interactive Triage
+
+For each finding, ask for disposition:
+
+- `convert` -> create standalone task entry
+- `defer` -> keep out of current task list, record reason
+- `dismiss` -> close without task, record reason
+
+Default suggestions:
+
+- Critical -> `convert`
+- Important -> `convert`
+- Medium -> `convert` (propose `defer` only with concrete rationale)
+- Minor -> `defer`
+
+Rules:
+
+- Require explicit rationale for `defer` or `dismiss`.
+- Do not silently skip findings.
+
+### Step 5: Generate Task List Output
+
+Generate standalone markdown tasks (no plan task IDs):
+
+```markdown
+- [ ] [critical] Fix auth bypass in token validator (`src/auth/token.ts:91`) - Enforce issuer/audience validation.
+```
+
+Output modes:
+
+- Inline (default)
+- File output path (if user requests), for example:
+  - `.oat/projects/local/orphan-reviews/review-tasks-YYYY-MM-DD.md`
+
+Also output deferred and dismissed findings with reasons.
+
+### Step 6: Archive the Consumed Review Artifact
+
+After triage is complete, move the processed review artifact into a sibling `archived/` directory and report the archived path:
+
+- `.oat/repo/reviews/{file}.md` -> `.oat/repo/reviews/archived/{file}.md`
+- `.oat/projects/local/orphan-reviews/{file}.md` -> `.oat/projects/local/orphan-reviews/archived/{file}.md`
+
+Rules:
+
+- Create the `archived/` directory if needed.
+- If the archive target already exists, append a timestamp suffix before moving so prior history is not overwritten.
+- Keep the archived path in the final output contract.
+
+## Output Contract
+
+At completion, report:
+
+- Artifact path used
+- Archived artifact path
+- Counts by severity
+- Number converted/deferred/dismissed
+- Task list location (`inline` or file path)
+
+## Success Criteria
+
+- Local artifact resolved and validated.
+- Findings parsed into 4-tier normalized structure.
+- Findings overview displayed before triage.
+- Every finding dispositioned with rationale where needed.
+- Standalone task list generated in requested output mode.
+- Consumed review artifact archived in the matching `archived/` directory.
+- Skill remains within content budget (`<=500` lines).