@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-project-import-plan/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: oat-project-import-plan
+version: 1.2.0
+description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
+argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Import External Plan
+
+Import a markdown plan from an external coding provider and normalize it into OAT project artifacts.
+
+## Prerequisites
+
+- External plan exists as a local markdown file.
+- OAT repository scaffolding is available.
+
+## Mode Assertion
+
+**OAT MODE: Plan Import**
+
+**Purpose:** Preserve the original plan and generate a runnable canonical `plan.md` for OAT execution.
+
+**BLOCKED Activities:**
+
+- No destructive edits to the imported source file.
+- No implementation code changes.
+
+**ALLOWED Activities:**
+
+- Creating/updating project artifacts.
+- Plan normalization into OAT task structure.
+- Updating project state metadata for import mode.
+
+**Self-Correction Protocol:**
+If you catch yourself:
+
+- Mutating source plan content in-place → STOP; copy source first.
+- Producing prose-only plan without runnable tasks → STOP and normalize to `pNN-tNN` tasks.
+
+**Recovery:**
+
+1. Preserve source in `references/imported-plan.md`.
+2. Regenerate canonical `plan.md` in OAT structure.
+
+## 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 ▸ IMPORT PLAN
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Before multi-step work, print step indicators, e.g.:
+  - `[1/5] Resolving project + source plan…`
+  - `[2/5] Preserving imported source…`
+  - `[3/5] Normalizing plan to OAT task structure…`
+  - `[4/5] Updating project metadata + state…`
+  - `[5/5] Refreshing dashboard…`
+
+## Process
+
+### Step 0: Resolve Active Project
+
+```bash
+PROJECT_PATH=$(oat config get activeProject 2>/dev/null || true)
+PROJECTS_ROOT="${OAT_PROJECTS_ROOT:-$(oat config get projects.root 2>/dev/null || echo ".oat/projects/shared")}"
+PROJECTS_ROOT="${PROJECTS_ROOT%/}"
+```
+
+If no valid active project exists:
+
+- Use `--project` if provided, else ask user.
+- Resolve `TARGET_PROJECT_PATH="${PROJECTS_ROOT}/{project-name}"`.
+- If `TARGET_PROJECT_PATH/state.md` exists, set:
+  ```bash
+  oat config set activeProject "$TARGET_PROJECT_PATH"
+  PROJECT_PATH="$TARGET_PROJECT_PATH"
+  ```
+- Otherwise create an import-mode scaffold (which sets active project by default):
+  ```bash
+  oat project new "{project-name}" --mode import
+  PROJECT_PATH="$TARGET_PROJECT_PATH"
+  ```
+
+### Step 1: Resolve and Validate Source Plan Path
+
+Inputs:
+
+- source path from `$ARGUMENTS`
+- optional provider hint from `--provider`
+
+If source path is not provided, discover likely recent plans first. The discovery script checks both provider plan directories and this repository's external plan directory by default:
+
+- `.oat/repo/reference/external-plans/`
+
+```bash
+bash .agents/skills/oat-project-import-plan/scripts/find-recent-provider-plans.sh --hours 24
+```
+
+Optional: extend discovery roots via `OAT_PROVIDER_PLAN_DIRS` (colon-separated):
+
+```bash
+export OAT_PROVIDER_PLAN_DIRS="$HOME/custom-plans:$HOME/tmp/provider-plans"
+```
+
+Then ask user to either:
+
+- choose one of the listed files (by number), or
+- provide a manual file path.
+
+Validation rules:
+
+- File must exist.
+- File extension must be `.md` (or user explicitly confirms nonstandard markdown extension).
+- File must contain non-empty content.
+
+### Step 2: Preserve Imported Source
+
+Create references directory if missing:
+
+```bash
+mkdir -p "$PROJECT_PATH/references"
+cp "{source-path}" "$PROJECT_PATH/references/imported-plan.md"
+```
+
+Never overwrite an existing source snapshot without user confirmation.
+If already present, write timestamped copy:
+
+- `references/imported-plan-YYYY-MM-DD-HHMM.md`
+
+### Step 3: Normalize Into Canonical OAT plan.md
+
+Create/update `"$PROJECT_PATH/plan.md"` using `.oat/templates/plan.md` and map imported content into the canonical structure. Apply `oat-project-plan-writing` invariants after mapping:
+
+- `## Phase N`
+- `### Task pNN-tNN` (stable task IDs)
+- Step structure (RED/GREEN/Refactor/Verify/Commit)
+- Required sections: `## Reviews`, `## Implementation Complete`, `## References`
+- Review table preservation rules (never delete existing rows)
+
+Normalization rules:
+
+- Preserve original intent and ordering from source.
+- Generate stable task IDs per `oat-project-plan-writing` format (`pNN-tNN`).
+- Where source lacks test/verify details, add explicit TODO-style placeholders with clear expected output.
+- Keep tasks executable and atomic.
+
+### Step 4: Update Plan Metadata
+
+Set frontmatter in `"$PROJECT_PATH/plan.md"`:
+
+- `oat_status: complete`
+- `oat_ready_for: oat-project-implement`
+- `oat_phase: plan`
+- `oat_phase_status: complete`
+- `oat_plan_source: imported`
+- `oat_import_reference: references/imported-plan.md`
+- `oat_import_source_path: {source-path}`
+- `oat_import_provider: {codex|cursor|claude|null}`
+
+### Step 5: Update Project State
+
+Set `"$PROJECT_PATH/state.md"` frontmatter:
+
+- `oat_workflow_mode: import`
+- `oat_workflow_origin: imported`
+- `oat_phase: plan`
+- `oat_phase_status: complete`
+- `oat_current_task: null`
+- `oat_project_state_updated: "{ISO 8601 UTC timestamp, e.g. 2026-03-10T14:30:00Z}"`
+
+### Step 5.5: Ensure Active Project Pointer
+
+Import mode must leave the imported project as active for immediate execution.
+
+Validate target project before writing pointer:
+
+```bash
+if [[ ! -f "$PROJECT_PATH/state.md" ]]; then
+  echo "Error: Project missing state.md: $PROJECT_PATH/state.md" >&2
+  exit 1
+fi
+```
+
+```bash
+oat config set activeProject "$PROJECT_PATH"
+oat state refresh
+```
+
+If `activeProject` in local config already exists with a different path, treat this as a project switch and note it in output.
+
+### Step 6: Ensure Implementation Artifact Exists
+
+If missing, scaffold from template:
+
+- `.oat/templates/implementation.md` → `"$PROJECT_PATH/implementation.md"`
+
+Initialize pointer to first plan task ID.
+
+### Step 7: Output Next Action
+
+Report:
+
+- source imported path
+- normalized phases/tasks count
+- first task ID
+- active project pointer path
+- dashboard refresh status
+- next options:
+  - `oat-project-implement` (sequential, default)
+  - `oat-project-subagent-implement` (parallel with autonomous review gates)
+
+## Success Criteria
+
+- ✅ Imported markdown preserved at `references/imported-plan.md`.
+- ✅ Canonical `plan.md` generated with OAT task structure.
+- ✅ `plan.md` metadata marks `oat_plan_source: imported`.
+- ✅ `state.md` marks `oat_workflow_mode: import`.
+- ✅ `implementation.md` is present and resumable.
+- ✅ `oat_plan_hill_phases` left unset in frontmatter (deferred to `oat-project-implement` Step 2.5).
+- ✅ `## Planning Checklist` items left unchecked (HiLL configuration deferred to implementation).
+- ✅ `activeProject` in `.oat/config.local.json` points to the imported project.
+- ✅ `.oat/state.md` has been refreshed after pointer update.

package/assets/skills/oat-project-import-plan/scripts/find-recent-provider-plans.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# find-recent-provider-plans.sh - list recent provider plan files in reverse chronology
+# Usage: find-recent-provider-plans.sh [--hours N] [--limit N]
+
+set -eu
+
+HOURS=24
+LIMIT=25
+
+usage() {
+  cat <<USAGE
+Usage: find-recent-provider-plans.sh [--hours N] [--limit N]
+
+Searches common provider plan directories and prints recent markdown files
+sorted by modified time (newest first).
+
+Options:
+  --hours N   Lookback window in hours (default: 24)
+  --limit N   Maximum number of results to print (default: 25)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --hours)
+      HOURS="$2"
+      shift 2
+      ;;
+    --limit)
+      LIMIT="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+case "$HOURS" in
+  ''|*[!0-9]*)
+    echo "--hours must be a non-negative integer" >&2
+    exit 1
+    ;;
+esac
+
+case "$LIMIT" in
+  ''|*[!0-9]*)
+    echo "--limit must be a non-negative integer" >&2
+    exit 1
+    ;;
+esac
+
+now_epoch=$(date +%s)
+window_seconds=$((HOURS * 3600))
+
+mtime_epoch() {
+  local path="$1"
+  if stat -f %m "$path" >/dev/null 2>&1; then
+    stat -f %m "$path"
+  else
+    stat -c %Y "$path"
+  fi
+}
+
+format_epoch() {
+  local epoch="$1"
+  if date -r "$epoch" "+%Y-%m-%d %H:%M:%S %Z" >/dev/null 2>&1; then
+    date -r "$epoch" "+%Y-%m-%d %H:%M:%S %Z"
+  else
+    date -d "@$epoch" "+%Y-%m-%d %H:%M:%S %Z"
+  fi
+}
+
+provider_from_path() {
+  local path="$1"
+  case "$path" in
+    *"/.claude/"*) echo "claude" ;;
+    *"/.cursor/"*) echo "cursor" ;;
+    *"/.codex/"*) echo "codex" ;;
+    *"/.oat/repo/reference/external-plans/"*) echo "external" ;;
+    *) echo "unknown" ;;
+  esac
+}
+
+recent_rows=""
+add_dir() {
+  local dir="$1"
+  [[ -d "$dir" ]] || return 0
+
+  while IFS= read -r -d '' file_path; do
+    local epoch age provider
+    epoch=$(mtime_epoch "$file_path" 2>/dev/null || echo "")
+    [[ -n "$epoch" ]] || continue
+
+    age=$((now_epoch - epoch))
+    (( age <= window_seconds )) || continue
+
+    provider=$(provider_from_path "$file_path")
+    recent_rows+="${epoch}"$'\t'"${provider}"$'\t'"${file_path}"$'\n'
+  done < <(find "$dir" -type f \( -name "*.md" -o -name "*.markdown" \) -print0 2>/dev/null)
+}
+
+# Common provider directories plus local repo external-plan directory.
+# Add extra directories with OAT_PROVIDER_PLAN_DIRS (colon-separated).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+SEARCH_DIRS=(
+  "$HOME/.claude/plans"
+  "$HOME/.codex/plans"
+  "$HOME/.cursor/plans"
+  "$REPO_ROOT/.oat/repo/reference/external-plans"
+)
+
+if [[ -n "${OAT_PROVIDER_PLAN_DIRS:-}" ]]; then
+  OLDIFS="$IFS"
+  IFS=':'
+  # shellcheck disable=SC2206
+  EXTRA_DIRS=(${OAT_PROVIDER_PLAN_DIRS})
+  IFS="$OLDIFS"
+  SEARCH_DIRS+=("${EXTRA_DIRS[@]}")
+fi
+
+for search_dir in "${SEARCH_DIRS[@]}"; do
+  add_dir "$search_dir"
+done
+
+if [[ -z "$recent_rows" ]]; then
+  echo "No recent provider plan files found in the last ${HOURS}h."
+  exit 0
+fi
+
+echo "Recent provider plans (last ${HOURS}h, newest first):"
+
+index=0
+# sort by epoch descending and print up to LIMIT rows
+while IFS=$'\t' read -r epoch provider path; do
+  (( index += 1 ))
+  if (( LIMIT > 0 && index > LIMIT )); then
+    break
+  fi
+
+  printf "%2d) [%s] (%s) %s\n" "$index" "$(format_epoch "$epoch")" "$provider" "$path"
+done < <(printf "%s" "$recent_rows" | sort -rn -k1,1)

package/assets/skills/oat-project-new/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: oat-project-new
+version: 1.2.0
+description: Use when starting a spec-driven OAT project from scratch. Scaffolds a new project under PROJECTS_ROOT and sets it active.
+argument-hint: '<project-name> [--force]'
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash(pnpm:*), Glob, Grep, AskUserQuestion
+---
+
+# New OAT Project
+
+Create a new OAT project directory, scaffold standard artifacts from `.oat/templates/`, and set `activeProject` in local config.
+
+## Progress Indicators (User-Facing)
+
+- Print a phase banner once at start using horizontal separators, e.g.:
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  OAT ▸ NEW PROJECT
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+- Before multi-step work, print step indicators, e.g.:
+  - `[1/3] Validating project name…`
+  - `[2/3] Scaffolding project artifacts…`
+  - `[3/3] Refreshing dashboard…`
+
+## Process
+
+### Step 0: Resolve Projects Root
+
+Resolve `{PROJECTS_ROOT}` (same order as other OAT skills):
+
+```bash
+PROJECTS_ROOT="${OAT_PROJECTS_ROOT:-$(oat config get projects.root 2>/dev/null || echo \".oat/projects/shared\")}"
+PROJECTS_ROOT="${PROJECTS_ROOT%/}"
+```
+
+### Step 1: Get Project Name
+
+If not provided in `$ARGUMENTS`, ask the user for `{project-name}` (slug format: alphanumeric/dash/underscore only).
+
+### Step 2: Scaffold Project (Deterministic)
+
+Use the CLI scaffolder:
+
+```bash
+oat project new "{project-name}" --mode spec-driven
+```
+
+Optional flags:
+
+- `--force` (non-destructive; only fills missing files/dirs, does not overwrite)
+- `--no-set-active`
+- `--no-dashboard`
+
+### Step 3: Confirm + Next Step
+
+Confirm to the user:
+
+- Project path created: `{PROJECTS_ROOT}/{project-name}`
+- Active project set in local config: `.oat/config.local.json` (`activeProject`)
+- Repo State Dashboard refreshed: `.oat/state.md` (if enabled)
+
+Then explicitly instruct the user to run discovery next:
+
+- Next command: `oat-project-discover`
+
+## Success Criteria
+
+- ✅ `{PROJECTS_ROOT}/{project-name}/` exists
+- ✅ Standard artifacts exist in the project dir (copied from `.oat/templates/*.md`)
+- ✅ `activeProject` in `.oat/config.local.json` points at the project path
+- ✅ `.oat/state.md` is refreshed (unless disabled)