@open-agent-toolkit/cli 0.0.10

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

@@ -0,0 +1,250 @@
+---
+name: oat-review-receive-remote
+version: 1.2.0
+description: Use when processing GitHub PR review comments outside project context. Fetches PR comments via agent-reviews and converts them into actionable task lists.
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Remote Review Receive (Ad-hoc GitHub PR)
+
+Process unresolved GitHub PR review feedback into normalized findings and standalone tasks without requiring an active OAT project.
+
+## Prerequisites
+
+- `npx agent-reviews` is available.
+- GitHub authentication is configured (`GITHUB_TOKEN`, `.env.local`, or `gh` auth context).
+- User wants ad-hoc triage outside project lifecycle artifact mutation.
+
+## Mode Assertion
+
+**OAT MODE: Review Receive**
+
+**Purpose:** Fetch unresolved PR comments, classify findings into standard severities, triage dispositions, and produce standalone tasks.
+
+**BLOCKED Activities:**
+
+- No `plan.md`, `state.md`, or `implementation.md` lifecycle mutations.
+- No auto-replies on GitHub without explicit user confirmation.
+- No implementing fixes without explicit user confirmation.
+
+**ALLOWED Activities:**
+
+- Resolve PR scope.
+- Fetch unresolved PR comments via `agent-reviews`.
+- Normalize and classify findings.
+- Interactive triage and task-list generation.
+- Implementing fixes, committing, and pushing (only with explicit user confirmation).
+- Optional explicit replies to processed comments.
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- Replying on GitHub without explicit user confirmation -> STOP and present reply content for approval first.
+- Editing project lifecycle artifacts (`plan.md`, `state.md`, `implementation.md`) in ad-hoc mode -> STOP and revert to task-list output only.
+- Skipping the findings overview before triage prompts -> STOP and show overview first.
+- Implementing fixes without user confirmation -> STOP and ask first.
+
+## Progress Indicators (User-Facing)
+
+Print this banner once at start:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ REMOTE REVIEW RECEIVE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Use step indicators:
+
+- `[1/7] Resolving PR...`
+- `[2/7] Fetching comments...`
+- `[3/7] Classifying findings...`
+- `[4/7] Triaging findings...`
+- `[5/7] Generating task list...`
+- `[6/7] Applying fixes (optional)...`
+- `[7/7] Posting replies (optional)...`
+
+## 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: github_pr
+  source_ref: string
+  comment_id: string | number
+```
+
+Severity conventions:
+
+- `critical`: Broken behavior, security risk, or missing P0 requirement.
+- `important`: Missing P1 requirement, major robustness issue.
+- `medium`: Meaningful but non-blocking quality/maintainability issue.
+- `minor`: Cosmetic/style/documentation issue.
+
+## Process
+
+### Step 1: Resolve PR Number
+
+PR resolution order:
+
+1. `--pr <N>` from `$ARGUMENTS`
+2. Auto-detect via `agent-reviews` current-branch resolution
+
+Ask user to confirm resolved PR number before fetching comments.
+
+### Step 2: Fetch Unresolved Comments
+
+Run:
+
+```bash
+npx agent-reviews --json --unresolved --pr <N>
+```
+
+Expected: JSON payload with unresolved review comments and metadata.
+
+If command fails:
+
+- Capture error details.
+- Route user through troubleshooting (auth, network, permissions, invalid PR).
+
+If no unresolved comments are returned:
+
+- Report clean status and stop.
+
+### Step 3: Classify and Normalize Findings
+
+For each item in JSON:
+
+- Capture `type` (`review_comment`, `issue_comment`, `review`).
+- Map location fields (`path`, `line`) when present.
+- Use comment body + context to assign severity (`critical`, `important`, `medium`, `minor`).
+- Treat `CHANGES_REQUESTED` review state as a strong hint toward `important+`, not an automatic override.
+- Normalize into the shared findings model.
+
+ID assignment per severity bucket:
+
+- Critical: `C1`, `C2`, ...
+- Important: `I1`, `I2`, ...
+- Medium: `M1`, `M2`, ...
+- Minor: `m1`, `m2`, ...
+
+### Step 4: Present Findings Overview and Triage
+
+Before triage prompts, output:
+
+- Counts per severity
+- Compact register: `id`, `title`, `file:line`, `source_ref`
+
+Disposition options per finding:
+
+- `convert` (default for critical/important/medium)
+- `defer` (default for minor)
+- `dismiss`
+
+Rules:
+
+- Require rationale for `defer`/`dismiss`.
+- For medium deferral, require concrete rationale (duplicate, dependency, explicit out-of-scope follow-up, risky churn).
+
+### Step 5: Generate Standalone Task List
+
+Task entry format:
+
+```markdown
+- [ ] [important] Add null-guard in OAuth callback parser (`packages/auth/src/callback.ts:142`) - Validate provider payload before dereference.
+```
+
+Output modes:
+
+- Inline (default)
+- File output path (if user requests)
+
+Also output deferred and dismissed lists with reasons.
+
+### Step 6: Optional Fix Implementation
+
+After the task list is confirmed, ask:
+
+`Would you like me to address these fixes, commit, and push the changes? [yes/no]`
+
+If yes:
+
+1. Implement each converted task in the order listed.
+2. After all fixes are applied, run verification (lint, type-check, tests as appropriate).
+3. Stage and commit with a descriptive message referencing the PR:
+
+   ```bash
+   git add {changed-files}
+   git commit -m "fix: address PR #<N> review feedback
+
+   Resolved findings: {list of finding IDs and titles}"
+   ```
+
+4. Push to the current branch:
+   ```bash
+   git push
+   ```
+5. Capture the commit hash for use in Step 7 replies:
+   ```bash
+   FIX_COMMIT=$(git rev-parse --short HEAD)
+   ```
+
+If no: skip to Step 7.
+
+### Step 7: Optional GitHub Reply Posting
+
+After fix implementation (or after task generation if fixes were skipped), ask:
+
+`Reply to processed comments on GitHub? [yes/no]`
+
+If yes, reply per finding disposition:
+
+**When fixes were applied (Step 6 completed):**
+
+- Convert: `npx agent-reviews --reply <id> "Fixed in <FIX_COMMIT>"`
+- Defer: `npx agent-reviews --reply <id> "Deferred: <reason>"`
+- Dismiss: `npx agent-reviews --reply <id> "Won't fix: <reason>"`
+
+**When fixes were not applied:**
+
+- Convert: `npx agent-reviews --reply <id> "Acknowledged - tracking as task"`
+- Defer: `npx agent-reviews --reply <id> "Deferred: <reason>"`
+- Dismiss: `npx agent-reviews --reply <id> "Won't fix: <reason>"`
+
+Never send replies without explicit user approval.
+
+## Troubleshooting
+
+- Auth failure: verify `GITHUB_TOKEN` and repository access.
+- No PR detected: pass explicit `--pr <N>`.
+- No unresolved comments found: confirm you are targeting the correct PR and unresolved filter.
+- Network/rate limit errors: retry after backoff and report blocked state if persistent.
+
+## Output Contract
+
+At completion, report:
+
+- PR number
+- Severity counts
+- Converted/deferred/dismissed counts
+- Task list output location (`inline` or file path)
+- Whether fixes were applied (and commit hash if so)
+- Whether replies were posted
+
+## Success Criteria
+
+- PR scope resolved and confirmed.
+- Unresolved comments fetched from GitHub.
+- Findings normalized with consistent 4-tier severities.
+- Triage completed with explicit rationale capture for deferred/dismissed findings.
+- Standalone task list generated.
+- Fixes applied, committed, and pushed only with user approval.
+- Optional replies posted only with user approval (with commit hash when fixes were applied).

package/assets/skills/oat-worktree-bootstrap/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: oat-worktree-bootstrap
+version: 1.2.0
+description: Use when creating or resuming a git worktree for OAT implementation. Creates or validates a worktree and runs OAT bootstrap checks.
+argument-hint: '<branch-name> [--base <ref>] [--path <root>] [--existing]'
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Worktree Bootstrap
+
+Create or resume a git worktree and prepare it for OAT development.
+
+## Prerequisites
+
+- Git repository is clean enough to create/switch worktrees.
+- Node.js and pnpm are available in the target environment.
+- OAT project files exist (`.oat/`, `.agents/`).
+
+## Mode Assertion
+
+**OAT MODE: Worktree Bootstrap**
+
+**Purpose:** Establish an isolated workspace and run standard OAT readiness checks before implementation work.
+
+**BLOCKED Activities:**
+
+- No implementation code changes unrelated to worktree setup.
+- No destructive rewrite of existing project artifacts.
+
+**ALLOWED Activities:**
+
+- Create/reuse worktree paths.
+- Run bootstrap and readiness checks.
+- Update related state/docs for workspace readiness.
+
+## Progress Indicators (User-Facing)
+
+- Print a phase banner once at start:
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  OAT ▸ WORKTREE BOOTSTRAP
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Before multi-step operations, print step indicators, e.g.:
+  - `[1/4] Resolving worktree target…`
+  - `[2/4] Creating/validating worktree…`
+  - `[3/4] Running OAT bootstrap checks…`
+  - `[4/4] Reporting ready state…`
+
+## Inputs
+
+- Required for creation mode: `<branch-name>`
+- Optional:
+  - `--base <ref>` (default: `origin/main`)
+  - `--path <root>` (explicit worktree root override)
+  - `--existing` (bootstrap/validate existing worktree instead of creating one)
+
+## Process
+
+### Step 0: Resolve Repository Context
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+REPO_NAME=$(basename "$REPO_ROOT")
+```
+
+### Step 0.5: Validate Active Project Config
+
+Resolve active project from local config:
+
+```bash
+ACTIVE_PROJECT=$(oat config get activeProject 2>/dev/null || true)
+```
+
+If `ACTIVE_PROJECT` is set:
+
+- verify the pointed path exists and contains `state.md`
+- if invalid, do **not** silently rewrite it
+- prompt user to run one of:
+  - `oat-project-clear-active`
+  - `oat-project-open`
+- require explicit confirmation before continuing with worktree bootstrap
+
+If `ACTIVE_PROJECT` is missing:
+
+- continue (active project is optional for worktree bootstrap)
+- use console-only baseline-failure logging in Step 3 if needed
+
+### Step 1: Resolve Target Worktree Context
+
+If `--existing`:
+
+- validate the current directory appears in `git worktree list --porcelain`
+- set `TARGET_WORKTREE` to the current directory
+- set `WORKTREE_ROOT` to the parent directory of `TARGET_WORKTREE` (informational)
+- skip root-path convention checks; externally managed paths are allowed (for example Codex-managed worktrees under `~/.codex/worktrees/...`)
+
+Otherwise, resolve `WORKTREE_ROOT` using this strict precedence (stop at the **first match**):
+
+1. Explicit `--path <root>` (CLI flag — highest priority)
+2. `OAT_WORKTREES_ROOT` (environment variable)
+3. `.oat/config.json` -> `worktrees.root` (persisted project config)
+4. First existing directory in this order (check each, use the first that exists):
+   a. `${REPO_ROOT}/.worktrees`
+   b. `${REPO_ROOT}/worktrees`
+   c. `../${REPO_NAME}-worktrees`
+5. Fallback default (nothing matched above): `../${REPO_NAME}-worktrees`
+
+**IMPORTANT:** Precedence level 4 is an ordered list, not a set. Check `.worktrees` first. If it exists, use it — do NOT continue scanning for `../<repo>-worktrees` even if that also exists. Only fall through to the next candidate if the current one does not exist.
+
+For repo-relative values (levels 3–4a–4b), resolve from `REPO_ROOT`.
+Treat `.oat/config.json` as phase-A non-sync settings ownership (do not mix with `.oat/sync/config.json`).
+
+If the resolved root is project-local (`.worktrees` or `worktrees`), verify it is ignored by git before creating a new worktree.
+Set `TARGET_WORKTREE` to `{WORKTREE_ROOT}/{branch-name}`.
+
+### Step 2: Create or Reuse Worktree
+
+- If `--existing`, validate the current directory is a git worktree and continue.
+- Otherwise:
+  - validate branch name format (`^[a-zA-Z0-9._/-]+$`)
+  - resolve target path as `TARGET_WORKTREE`
+  - if branch already exists locally:
+    - `git worktree add "{TARGET_WORKTREE}" "{branch-name}"`
+  - if branch does not exist:
+    - `git worktree add "{TARGET_WORKTREE}" -b "{branch-name}" "{base-ref}"`
+
+`{base-ref}` defaults to `origin/main` unless `--base` is provided.
+
+If worktree creation fails, stop and report the exact git error with remediation guidance.
+
+### Step 2.5: Propagate Local-Only Config + Local Paths
+
+After the worktree is created (or validated with `--existing`), copy gitignored local-only context files from the source repo into the new worktree so downstream skills (e.g., `oat-project-implement`) can resolve context without re-prompting.
+
+**Config propagation:**
+
+Copy `.oat/config.local.json` if it exists in the source repo:
+
+```bash
+SRC="$REPO_ROOT/.oat/config.local.json"
+DST="{target-path}/.oat/config.local.json"
+if [[ -f "$SRC" && ! -f "$DST" ]]; then
+  cp "$SRC" "$DST"
+fi
+```
+
+Rules:
+
+- Only copy if the source file exists **and** the destination does not (never overwrite).
+- `config.local.json` uses repo-relative paths, so copied values remain valid across sibling worktrees.
+- `activeIdea` is stored in `config.local.json`, so it propagates automatically with the config copy.
+- After copying, validate `activeProject` (if present in `config.local.json`) resolves to a real project path in the worktree. If not, print a warning but do not block bootstrap.
+
+**Local paths sync:**
+
+After config propagation, sync configured `localPaths` into the worktree:
+
+```bash
+oat local sync "{target-path}" 2>/dev/null || true
+```
+
+- Uses the `localPaths` array from `.oat/config.json` to copy local-only directories (e.g., `.oat/ideas/`, `.oat/projects/local/`) into the worktree.
+- Non-blocking: if sync fails or no `localPaths` are configured, bootstrap continues.
+- Does not overwrite existing paths in the target (use `--force` to override).
+
+### Step 3: Run OAT Bootstrap
+
+Run bootstrap and readiness checks in the target worktree:
+
+```bash
+pnpm run worktree:init
+oat status --scope project
+pnpm test
+git status --porcelain
+```
+
+Required behavior:
+
+- Stop immediately if `worktree:init` or `status` fails.
+- If `pnpm test` fails:
+  - show a concise failure summary
+  - ask the user whether to `abort` or `proceed anyway`
+  - if user proceeds:
+    - when a valid active project with `implementation.md` exists, append a timestamped baseline-failure note there
+    - otherwise print the same note to console output only (do not create a fallback file)
+- If `git status --porcelain` is not clean after bootstrap/tests, stop and require cleanup before reporting ready.
+
+### Step 4: Output Ready State
+
+Report:
+
+- resolved worktree path
+- active branch
+- bootstrap/verification status
+- next command: `oat-project-implement`
+
+## References
+
+- `references/worktree-conventions.md`
+
+## Success Criteria
+
+- ✅ Worktree exists (or existing worktree validated).
+- ✅ OAT bootstrap completed without blocking errors.
+- ✅ User receives a clear next action for implementation.

package/assets/skills/oat-worktree-bootstrap/references/worktree-conventions.md

@@ -0,0 +1,58 @@
+# Worktree Conventions
+
+## Root Selection Priority
+
+If bootstrapping an existing worktree (`--existing`), use the current directory as the target worktree and treat its parent as informational root only.
+
+For creation mode:
+
+1. Explicit `--path <root>` argument
+2. `OAT_WORKTREES_ROOT` environment variable
+3. `.oat/config.json` -> `worktrees.root`
+4. Existing roots (`.worktrees`, `worktrees`, `../<repo>-worktrees`)
+5. Fallback default (`../<repo>-worktrees`)
+
+For relative paths, resolve from repository root.
+
+## Safety Rules
+
+- Validate branch names before creation.
+- Never create nested worktrees inside tracked source directories.
+- For repo-local roots (`.worktrees`, `worktrees`), ensure the root is ignored by git.
+- Default base reference for new branches is `origin/main`.
+- If `git worktree add` fails, stop and present remediation rather than retrying silently.
+
+## Baseline Readiness
+
+Run baseline commands before reporting ready:
+
+```bash
+pnpm run worktree:init
+oat status --scope project
+pnpm test
+git status --porcelain
+```
+
+If checks fail, stop and report exact remediation.
+
+If baseline tests fail, require explicit user override before proceeding.
+
+If user proceeds with failing baseline tests:
+
+- Prefer appending a note to active project `implementation.md` when a valid active project is set.
+- If no valid active project exists yet, print the same note to console output only (non-blocking fallback).
+
+Include:
+
+- timestamp
+- failing command
+- short failure summary
+- explicit statement that failures were pre-existing at worktree bootstrap time
+
+## Typical Paths
+
+- Local hidden root: `.worktrees/<branch>`
+- Local visible root: `worktrees/<branch>`
+- Sibling root: `../<repo>-worktrees/<branch>`
+- Global root (explicit): `~/.oat/worktrees/<repo>/<branch>`
+- Tool-managed existing worktree: `~/.codex/worktrees/<id>/<repo>`