@open-agent-toolkit/cli 0.0.10

package/assets/skills/oat-repo-maintainability-review/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: oat-repo-maintainability-review
+version: 1.2.0
+description: Use when you need a structured maintainability analysis for a repository or directory target with actionable findings.
+argument-hint: '[--scope repo|directory] [--target <path>] [--mode auto|tracked|local|inline] [--output <path>] [--focus <areas>] [--analysis-mode full] [--fan-out]'
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Repo Maintainability Review
+
+Analyze repository maintainability and developer experience using a deterministic rubric and output contract.
+
+## Prerequisites
+
+- Active git repository with readable source files.
+- Scope resolved as `repo` or `directory`.
+- When using `directory`, target path must be inside repository root.
+
+## Mode Assertion
+
+**OAT MODE: Repo Maintainability Review**
+
+**Purpose:** Produce evidence-backed maintainability findings and a prioritized execution plan.
+
+**BLOCKED Activities:**
+
+- No code modification tasks.
+- No issue/ticket automation.
+
+**ALLOWED Activities:**
+
+- Repository evidence collection.
+- Structured scoring and synthesis.
+- Artifact generation in tracked/local/inline modes.
+
+## Progress Indicators (User-Facing)
+
+- Print a phase banner once at start:
+  - `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`
+  - ` OAT ▸ REPO MAINTAINABILITY REVIEW`
+  - `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`
+- Print step indicators before major work:
+  - `[1/5] Resolving scope, arguments, and output policy...`
+  - `[2/5] Collecting repository evidence...`
+  - `[3/5] Running dimension analysis (single-agent or multi-agent)...`
+  - `[4/5] Synthesizing findings and scoring...`
+  - `[5/5] Rendering artifact and summary...`
+- For long-running fan-out or large scans, print start + completion lines.
+- Print a resolved run-options summary before evidence collection begins.
+
+## Process
+
+1. Resolve invocation args and validate scope/target.
+2. Resolve missing/ambiguous required args using provider-aware clarification.
+3. Resolve output policy.
+4. Gather evidence across required dimensions.
+5. Synthesize findings into prioritized recommendations.
+6. Render artifact or return inline output.
+
+### Output Policy Resolution
+
+Use the helper script to resolve destination policy:
+
+```bash
+bash .agents/skills/oat-repo-maintainability-review/scripts/resolve-analysis-output.sh --mode auto
+```
+
+Rules:
+
+- `--output` takes precedence over mode-derived destination.
+- `inline` emits no file artifact.
+- Tracked naming contract: `.oat/repo/analysis/<YYYY-MM-DD>-repo-review-analysis.md`.
+- If the same-day filename already exists, append `-2`, `-3`, etc.
+
+### Required Analysis Dimensions
+
+Every run must cover all required dimensions:
+
+- `Architecture` - module boundaries, coupling, and system organization.
+- `Conventions` - coding patterns, consistency, and repository standards.
+- `Documentation` - onboarding quality, runbooks, and operational docs.
+- `DX` - developer workflows, tooling friction, and feedback loops.
+- `Testing` - test strategy depth, reliability signals, and failure clarity.
+- `Maintainability` - ownership clarity, change safety, and delivery risk.
+
+### Evidence and Confidence Rules
+
+- Every finding must include at least one concrete evidence bullet.
+- Evidence should reference specific files, commands, or repository structures.
+- Confidence must align with evidence depth:
+  - `High` when multiple strong signals agree.
+  - `Medium` when evidence is sufficient but incomplete.
+  - `Low` when evidence is directional and requires validation.
+- If no issue is found for a dimension, provide a concise "no critical issues observed" note with supporting context.
+
+### Synthesis and Dedupe Rules
+
+- Dedupe overlap key:
+  - same `category`
+  - same normalized path token (file path, package, or module)
+  - semantically equivalent finding title
+- Concern precedence during merge:
+  - `Critical > High > Medium > Low`
+  - merged finding keeps the strongest Concern
+- Material disagreement threshold:
+  - Concern differs by 2+ levels, or
+  - Value differs by 2+ levels
+- When material disagreement is detected, add a `merge note` evidence bullet explaining the reconciliation decision.
+
+### Prioritization Output Requirements
+
+- Split findings into:
+  - `Quick Wins (XS/S)`
+  - `Strategic Initiatives (M/L/XL)`
+- Build an execution sequence using `Now / Next / Later`.
+- Ensure prioritization appears in both artifact sections and final summary guidance.
+
+### Automatic Delegation (When Supported)
+
+- If runtime supports subagents or multi-agent execution, delegate automatically.
+- Delegation is orchestrator-selected behavior, not a user-selected execution mode.
+- Do not require a custom subagent role; use generic spawned workers with explicit prompts.
+- Spawn one worker per analysis track:
+  - `Architecture`
+  - `Conventions`
+  - `Documentation`
+  - `DX`
+  - `Testing`
+  - `Maintainability`
+- Worker prompt must include:
+  - scope and target path
+  - required finding schema
+  - evidence and confidence requirements
+- Wait for all workers to complete, then synthesize using dedupe/merge rules.
+- Summarize one result block per analysis track before final merged summary.
+- Enforce schema parity between delegated outputs and single-agent baseline outputs.
+- If delegation is unavailable, run the same tracks sequentially without behavior loss.
+
+Provider notes:
+
+- Claude Code: use Task/subagent dispatch when available.
+- Codex: spawn a worker per track (generic multi-agent worker), wait for all, then merge.
+- Cursor: invoke available subagent capability (`/name` or natural mention) per track when supported.
+
+### Required-Argument Clarification
+
+- Required arguments must be resolved before analysis starts.
+- Clarification channel priority:
+  1. Use `AskUserQuestion` when running in Claude with tool availability.
+  2. Use Codex structured user-input tooling when available in the current Codex host/runtime.
+  3. Fall back to direct plain-language prompts when structured tools are unavailable.
+- Clarification remains blocking in all modes: do not continue until answers are explicit.
+- After clarification, print run options:
+  - `scope`
+  - `target`
+  - `mode`
+  - `analysis-mode`
+  - delegation state (`multi-agent` or `single-agent`)
+  - `focus` selection (or `none`)
+- Clarification channel details are for internal logging only; do not expose channel identifiers in the end-user summary.
+
+### Invalid Target Handling
+
+- If target path is invalid, stop execution and return actionable guidance.
+- Invalid target conditions:
+  - target does not exist
+  - target resolves outside the repository root
+  - target type is incompatible with requested scope
+- Error output must include:
+  - resolved target path
+  - why it is invalid
+  - valid target examples
+- Do not continue analysis until a corrected target is provided.
+
+### Completion Summary Contract
+
+Final user-facing summary must include:
+
+- Findings by Concern
+  - `Critical`
+  - `High`
+  - `Medium`
+  - `Low`
+- Findings by Value
+  - `High`
+  - `Medium`
+  - `Low`
+- Artifact path (`inline-only` when no file is emitted)
+- Execution mode (`single-agent` or `multi-agent`)
+
+## Success Criteria
+
+- Output includes required sections and metadata.
+- Findings include scoring fields and evidence.
+- Result includes now/next/later execution guidance.
+- Required arguments are explicitly resolved before analysis execution.

package/assets/skills/oat-repo-maintainability-review/references/dx-checklist.md

@@ -0,0 +1,33 @@
+# DX Checklist
+
+Use this checklist during analysis. Include relevant checks in repo and directory scopes.
+
+## Setup and Tooling
+
+- Are setup steps documented and reproducible?
+- Are required runtime/tool versions explicit?
+- Are onboarding commands current and verifiable?
+
+## Feedback Loops
+
+- Is lint/type/test feedback fast enough for iterative work?
+- Are failures actionable and clear?
+- Are common workflows scriptable and discoverable?
+
+## Developer Friction
+
+- Are repetitive manual steps still required?
+- Are local/dev workflows consistent across packages?
+- Are debugging and tracing paths documented?
+
+## Reliability of DX Signals
+
+- Do tests/lint/type-check cover common change paths?
+- Are flaky or non-deterministic workflows identified?
+- Are confidence notes included when evidence is weak?
+
+## Verification Runbook
+
+- Validate repo scope run includes all required sections and scoring summary.
+- Validate directory scope run remains constrained to the requested target.
+- Validate inline mode returns complete summary fields without file writes.

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

@@ -0,0 +1,72 @@
+# Repo Review Artifact Template
+
+Use this template for tracked/local file output and for structuring inline responses.
+
+## Required Frontmatter
+
+```yaml
+---
+oat_generated: true
+oat_generated_at: YYYY-MM-DD
+oat_analysis_type: repo-review
+oat_analysis_scope: repo|directory
+oat_analysis_target: <path>
+oat_analysis_mode: full
+oat_output_mode: auto|tracked|local|inline
+oat_analysis_commit: <sha>
+---
+```
+
+## Required Sections
+
+1. Executive Summary
+2. Scoring Summary
+3. Prioritized Findings
+4. Quick Wins (XS/S)
+5. Strategic Initiatives (M/L/XL)
+6. Suggested Execution Plan (Now / Next / Later)
+7. Appendix (inventory metrics + assumptions)
+
+## Finding Schema
+
+Each finding entry should include:
+
+- `id`
+- `title`
+- `category`
+- `Concern`
+- `Value`
+- `Scope`
+- `Confidence`
+- `Evidence`
+- `Why this matters`
+- `Recommended action`
+- `Suggested owner`
+- `Dependencies`
+- `Success criteria`
+
+## Completion Summary (User-Facing)
+
+Include a concise completion summary after analysis:
+
+- `findings by Concern` (`Critical`, `High`, `Medium`, `Low`)
+- `findings by Value` (`High`, `Medium`, `Low`)
+- `artifact path` (or `inline-only`)
+- `execution mode` (`single-agent` or `fan-out`)
+
+Do not include the clarification channel in this summary.
+
+## Verification Commands
+
+Use these checks before declaring completion:
+
+```bash
+# Repo scope dry check
+rg -n "Executive Summary|Scoring Summary|Prioritized Findings|Quick Wins|Strategic Initiatives|Now / Next / Later" <artifact-or-inline-draft>
+
+# Directory-scope dry check
+echo "<resolved-target>" | rg -n "^[^/]|."
+
+# Inline-mode contract check
+rg -n "findings by Concern|findings by Value|artifact path|execution mode" <artifact-or-inline-draft>
+```

package/assets/skills/oat-repo-maintainability-review/references/repo-review-rubric.md

@@ -0,0 +1,66 @@
+# Repo Review Rubric
+
+## Scoring Labels
+
+### Concern
+
+- `Critical`: Immediate risk; likely production, security, or severe delivery impact.
+- `High`: Significant quality or delivery risk that should be addressed soon.
+- `Medium`: Meaningful issue with moderate impact.
+- `Low`: Minor issue with limited near-term impact.
+
+### Value
+
+- `High`: Fix unlocks major reliability, velocity, or clarity gains.
+- `Medium`: Fix delivers noticeable but bounded improvement.
+- `Low`: Fix is incremental.
+
+### Scope
+
+- `XS`: Single-file or very small localized change.
+- `S`: Small bounded change with minimal coordination.
+- `M`: Multi-file change in one subsystem.
+- `L`: Cross-subsystem change with broader testing needs.
+- `XL`: Program-level initiative across teams/modules.
+
+### Confidence
+
+- `High`: Strong evidence from multiple direct signals.
+- `Medium`: Good evidence with some assumptions.
+- `Low`: Limited evidence; requires targeted validation.
+
+## Required Categories
+
+- `Architecture`
+- `Conventions`
+- `Documentation`
+- `DX`
+- `Testing` (include reliability observations in this category)
+- `Maintainability`
+
+## Evidence Quality Rules
+
+- Every finding must include at least one concrete evidence bullet.
+- Evidence should reference files, commands, or repository structures.
+- Confidence should match evidence depth.
+
+## Actionability Rules
+
+- Recommended actions should be specific and executable.
+- Success criteria should be testable or observable.
+- Suggested owners should map to realistic team boundaries.
+
+## Merge and Dedupe Policy
+
+Use this policy whenever findings from multiple dimensions overlap:
+
+- Overlap detection key:
+  - same `category`
+  - same normalized path token (file, package, or module)
+  - equivalent title intent
+- Concern precedence:
+  - `Critical > High > Medium > Low`
+- Material disagreement threshold:
+  - Concern differs by 2+ levels, or
+  - Value differs by 2+ levels
+- If material disagreement exists, preserve strongest Concern and add a required `merge note` under evidence explaining the normalization decision.

package/assets/skills/oat-repo-maintainability-review/scripts/resolve-analysis-output.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# resolve-analysis-output.sh - resolve output destination for repo review analysis artifacts
+# Usage:
+#   resolve-analysis-output.sh [--mode auto|local|tracked|inline] [--output <path>]
+
+set -eu
+
+MODE="auto"
+OUTPUT=""
+TRACKED_DIR=".oat/repo/analysis"
+LOCAL_DIR=".oat/projects/local/analysis"
+
+usage() {
+  cat <<USAGE
+Usage: resolve-analysis-output.sh [--mode auto|local|tracked|inline] [--output <path>]
+
+Resolves output destination for repo review analysis artifacts.
+
+Policy:
+- If --output is provided, it overrides mode-derived destination.
+- If mode=inline, no file artifact is written.
+- In auto mode:
+  - If .oat/repo/analysis exists and is NOT gitignored, use tracked output.
+  - Otherwise, use local-only output under .oat/projects/local/analysis.
+- Default filename contract:
+  <YYYY-MM-DD>-repo-review-analysis.md
+  with same-day suffixes -2, -3, ... when needed.
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode)
+      if [[ $# -lt 2 ]]; then
+        echo "Missing value for --mode" >&2
+        exit 1
+      fi
+      MODE="$2"
+      shift 2
+      ;;
+    --output)
+      if [[ $# -lt 2 ]]; then
+        echo "Missing value for --output" >&2
+        exit 1
+      fi
+      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"
+  # Best-effort for non-existent paths: gitignore evaluation may be incomplete.
+  if git check-ignore -q "$path" 2>/dev/null; then
+    echo "true"
+  else
+    echo "false"
+  fi
+}
+
+next_default_output_path() {
+  local dir="$1"
+  local today base candidate n
+  today=$(date +%Y-%m-%d)
+  base="${today}-repo-review-analysis.md"
+  candidate="$dir/$base"
+
+  if [[ ! -e "$candidate" ]]; then
+    printf '%s\n' "$candidate"
+    return
+  fi
+
+  n=2
+  while [[ -e "$dir/${today}-repo-review-analysis-${n}.md" ]]; do
+    n=$((n + 1))
+  done
+  printf '%s\n' "$dir/${today}-repo-review-analysis-${n}.md"
+}
+
+emit_file_result() {
+  local kind="$1"
+  local output_path="$2"
+  local reason="$3"
+
+  echo "analysis_mode=file"
+  echo "output_path=$output_path"
+  echo "output_kind=$kind"
+  echo "output_gitignored=$(is_gitignored "$output_path")"
+  echo "reason=$reason"
+}
+
+if [[ -n "$OUTPUT" ]]; then
+  if [[ "$MODE" == "inline" ]]; then
+    echo "warning: --output overrides --mode inline; artifact will be written to file." >&2
+  fi
+
+  if [[ -d "$OUTPUT" ]]; then
+    if [[ ! -w "$OUTPUT" ]]; then
+      echo "warning: advisory: output directory is not writable: $OUTPUT" >&2
+    fi
+    emit_file_result "custom" "$(next_default_output_path "$OUTPUT")" "explicit_output_dir"
+  else
+    parent_dir=$(dirname "$OUTPUT")
+    if [[ ! -d "$parent_dir" ]]; then
+      echo "warning: advisory: parent directory does not exist: $parent_dir" >&2
+    elif [[ ! -w "$parent_dir" ]]; then
+      echo "warning: advisory: parent directory is not writable: $parent_dir" >&2
+    fi
+    emit_file_result "custom" "$OUTPUT" "explicit_output_path"
+  fi
+  exit 0
+fi
+
+if [[ "$MODE" == "inline" ]]; then
+  echo "analysis_mode=inline"
+  echo "output_path="
+  echo "output_kind=inline"
+  echo "output_gitignored=n/a"
+  echo "reason=inline_mode"
+  exit 0
+fi
+
+if [[ "$MODE" == "tracked" ]]; then
+  emit_file_result "tracked" "$(next_default_output_path "$TRACKED_DIR")" "forced_tracked"
+  exit 0
+fi
+
+if [[ "$MODE" == "local" ]]; then
+  emit_file_result "local" "$(next_default_output_path "$LOCAL_DIR")" "forced_local"
+  exit 0
+fi
+
+# auto mode
+if [[ -d "$TRACKED_DIR" ]] && [[ "$(is_gitignored "$TRACKED_DIR")" == "false" ]]; then
+  emit_file_result "tracked" "$(next_default_output_path "$TRACKED_DIR")" "existing_tracked_dir"
+  exit 0
+fi
+
+emit_file_result "local" "$(next_default_output_path "$LOCAL_DIR")" "default_local_only"