@oxgeneral/orch 1.0.7 → 1.0.9

package/skills/library/autoplan.md

@@ -0,0 +1,315 @@
+---
+name: autoplan
+version: 1.0.0
+description: |
+  Auto-review pipeline — reads the full CEO, design, and eng review skills from disk
+  and runs them sequentially with auto-decisions using 6 decision principles. Surfaces
+  taste decisions (close approaches, borderline scope, codex disagreements) at a final
+  approval gate. One command, fully reviewed plan out.
+  Use when asked to "auto review", "autoplan", "run all reviews", "review this plan
+  automatically", or "make the decisions for me".
+  Proactively suggest when the user has a plan file and wants to run the full review
+  gauntlet without answering 15-30 intermediate questions.
+---
+
+## Step 0: Detect base branch
+
+Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.
+
+1. Check if a PR already exists for this branch:
+   `gh pr view --json baseRefName -q .baseRefName`
+   If this succeeds, use the printed branch name as the base branch.
+
+2. If no PR exists (command fails), detect the repo's default branch:
+   `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
+
+3. If both commands fail, fall back to `main`.
+
+Print the detected base branch name. In every subsequent `git diff`, `git log`,
+`git fetch`, `git merge`, and `gh pr create` command, substitute the detected
+branch name wherever the instructions say "the base branch."
+
+---
+
+## Prerequisite Skill Offer
+
+When the design doc check above prints "No design doc found," offer the prerequisite
+skill before proceeding.
+
+Say to the user via AskUserQuestion:
+
+> "No design doc found for this branch. `/office-hours` produces a structured problem
+> statement, premise challenge, and explored alternatives — it gives this review much
+> sharper input to work with. Takes about 10 minutes. The design doc is per-feature,
+> not per-product — it captures the thinking behind this specific change."
+
+Options:
+- A) Run /office-hours first (in another window, then come back)
+- B) Skip — proceed with standard review
+
+If they skip: "No worries — standard review. If you ever want sharper input, try
+/office-hours first next time." Then proceed normally. Do not re-offer later in the session.
+
+# /autoplan — Auto-Review Pipeline
+
+One command. Rough plan in, fully reviewed plan out.
+
+/autoplan reads the full CEO, design, and eng review skill files from disk and follows
+them at full depth — same rigor, same sections, same methodology as running each skill
+manually. The only difference: intermediate AskUserQuestion calls are auto-decided using
+the 6 principles below. Taste decisions (where reasonable people could disagree) are
+surfaced at a final approval gate.
+
+---
+
+## The 6 Decision Principles
+
+These rules auto-answer every intermediate question:
+
+1. **Choose completeness** — Ship the whole thing. Pick the approach that covers more edge cases.
+2. **Boil lakes** — Fix everything in the blast radius (files modified by this plan + direct importers). Auto-approve expansions that are in blast radius AND < 1 day CC effort (< 5 files, no new infra).
+3. **Pragmatic** — If two options fix the same thing, pick the cleaner one. 5 seconds choosing, not 5 minutes.
+4. **DRY** — Duplicates existing functionality? Reject. Reuse what exists.
+5. **Explicit over clever** — 10-line obvious fix > 200-line abstraction. Pick what a new contributor reads in 30 seconds.
+6. **Bias toward action** — Merge > review cycles > stale deliberation. Flag concerns but don't block.
+
+**Conflict resolution (context-dependent tiebreakers):**
+- **CEO phase:** P1 (completeness) + P2 (boil lakes) dominate.
+- **Eng phase:** P5 (explicit) + P3 (pragmatic) dominate.
+- **Design phase:** P5 (explicit) + P1 (completeness) dominate.
+
+---
+
+## Decision Classification
+
+Every auto-decision is classified:
+
+**Mechanical** — one clearly right answer. Auto-decide silently.
+Examples: run codex (always yes), run evals (always yes), reduce scope on a complete plan (always no).
+
+**Taste** — reasonable people could disagree. Auto-decide with recommendation, but surface at the final gate. Three natural sources:
+1. **Close approaches** — top two are both viable with different tradeoffs.
+2. **Borderline scope** — in blast radius but 3-5 files, or ambiguous radius.
+3. **Codex disagreements** — codex recommends differently and has a valid point.
+
+---
+
+## Phase 0: Intake + Restore Point
+
+### Step 1: Capture restore point
+
+Before doing anything, save the plan file's current state to an external file:
+
+```bash
+# Project slug detection (adapt to your project structure)
+mkdir -p .orch/reports
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-')
+DATETIME=$(date +%Y%m%d-%H%M%S)
+echo "RESTORE_PATH=$HOME/.orch/projects/$SLUG/${BRANCH}-autoplan-restore-${DATETIME}.md"
+```
+
+Write the plan file's full contents to the restore path with this header:
+```
+# /autoplan Restore Point
+Captured: [timestamp] | Branch: [branch] | Commit: [short hash]
+
+## Re-run Instructions
+1. Copy "Original Plan State" below back to your plan file
+2. Invoke /autoplan
+
+## Original Plan State
+[verbatim plan file contents]
+```
+
+Then prepend a one-line HTML comment to the plan file:
+`<!-- /autoplan restore point: [RESTORE_PATH] -->`
+
+### Step 2: Read context
+
+- Read CLAUDE.md, TODOS.md, git log -30, git diff against the base branch --stat
+- Discover design docs: `ls -t .orch/reports/*-design-*.md 2>/dev/null | head -1`
+- Detect UI scope: grep the plan for view/rendering terms (component, screen, form,
+  button, modal, layout, dashboard, sidebar, nav, dialog). Require 2+ matches. Exclude
+  false positives ("page" alone, "UI" in acronyms).
+
+### Step 3: Load skill files from disk
+
+Read each file using the Read tool:
+- `~/.claude/skills/orch/plan-ceo-review/SKILL.md`
+- `~/.claude/skills/orch/plan-design-review/SKILL.md` (only if UI scope detected)
+- `~/.claude/skills/orch/plan-eng-review/SKILL.md`
+
+**Section skip list — when following a loaded skill file, SKIP these sections
+(they are already handled by /autoplan):**
+- Preamble (run first)
+- AskUserQuestion Format
+- Completeness Principle — Boil the Lake
+- Search Before Building
+- Contributor Mode
+- Completion Status Protocol
+- Telemetry (run last)
+- Step 0: Detect base branch
+- Review Readiness Dashboard
+- Plan File Review Report
+- Prerequisite Skill Offer (BENEFITS_FROM)
+
+Follow ONLY the review-specific methodology, sections, and required outputs.
+
+Output: "Here's what I'm working with: [plan summary]. UI scope: [yes/no].
+Loaded review skills from disk. Starting full review pipeline with auto-decisions."
+
+---
+
+## Phase 1: CEO Review (Strategy & Scope)
+
+Follow plan-ceo-review/SKILL.md — all sections, full depth.
+Override: every AskUserQuestion → auto-decide using the 6 principles.
+
+**Override rules:**
+- Mode selection: SELECTIVE EXPANSION
+- Premises: accept reasonable ones (P6), challenge only clearly wrong ones
+- **GATE: Present premises to user for confirmation** — this is the ONE AskUserQuestion
+  that is NOT auto-decided. Premises require human judgment.
+- Alternatives: pick highest completeness (P1). If tied, pick simplest (P5).
+  If top 2 are close → mark TASTE DECISION.
+- Scope expansion: in blast radius + <1d CC → approve (P2). Outside → defer to TODOS.md (P3).
+  Duplicates → reject (P4). Borderline (3-5 files) → mark TASTE DECISION.
+- All 10 review sections: run fully, auto-decide each issue, log every decision.
+
+---
+
+## Phase 2: Design Review (conditional — skip if no UI scope)
+
+Follow plan-design-review/SKILL.md — all 7 dimensions, full depth.
+Override: every AskUserQuestion → auto-decide using the 6 principles.
+
+**Override rules:**
+- Focus areas: all relevant dimensions (P1)
+- Structural issues (missing states, broken hierarchy): auto-fix (P5)
+- Aesthetic/taste issues: mark TASTE DECISION
+- Design system alignment: auto-fix if DESIGN.md exists and fix is obvious
+
+---
+
+## Phase 3: Eng Review + Codex
+
+Follow plan-eng-review/SKILL.md — all sections, full depth.
+Override: every AskUserQuestion → auto-decide using the 6 principles.
+
+**Override rules:**
+- Scope challenge: never reduce (P2)
+- Codex review: always run if available (P6)
+  Command: `codex exec "Review this plan for architectural issues, missing edge cases, and hidden complexity. Be adversarial. File: <plan_path>" -s read-only --enable web_search_cached`
+  Timeout: 10 minutes, then proceed with "Codex timed out — single-reviewer mode"
+- Architecture choices: explicit over clever (P5). If codex disagrees with valid reason → TASTE DECISION.
+- Evals: always include all relevant suites (P1)
+- Test plan: generate artifact at `.orch/reports/{user}-{branch}-test-plan-{datetime}.md`
+- TODOS.md: collect all deferred scope expansions from Phase 1, auto-write
+
+---
+
+## Decision Audit Trail
+
+After each auto-decision, append a row to the plan file using Edit:
+
+```markdown
+<!-- AUTONOMOUS DECISION LOG -->
+## Decision Audit Trail
+
+| # | Phase | Decision | Principle | Rationale | Rejected |
+|---|-------|----------|-----------|-----------|----------|
+```
+
+Write one row per decision incrementally (via Edit). This keeps the audit on disk,
+not accumulated in conversation context.
+
+---
+
+## Phase 4: Final Approval Gate
+
+**STOP here and present the final state to the user.**
+
+Present as a message, then use AskUserQuestion:
+
+```
+## /autoplan Review Complete
+
+### Plan Summary
+[1-3 sentence summary]
+
+### Decisions Made: [N] total ([M] auto-decided, [K] choices for you)
+
+### Your Choices (taste decisions)
+[For each taste decision:]
+**Choice [N]: [title]** (from [phase])
+I recommend [X] — [principle]. But [Y] is also viable:
+  [1-sentence downstream impact if you pick Y]
+
+### Auto-Decided: [M] decisions [see Decision Audit Trail in plan file]
+
+### Review Scores
+- CEO: [summary]
+- Design: [summary or "skipped, no UI scope"]
+- Eng: [summary]
+- Codex: [summary or "unavailable"]
+
+### Deferred to TODOS.md
+[Items auto-deferred with reasons]
+```
+
+**Cognitive load management:**
+- 0 taste decisions: skip "Your Choices" section
+- 1-7 taste decisions: flat list
+- 8+: group by phase. Add warning: "This plan had unusually high ambiguity ([N] taste decisions). Review carefully."
+
+AskUserQuestion options:
+- A) Approve as-is (accept all recommendations)
+- B) Approve with overrides (specify which taste decisions to change)
+- C) Interrogate (ask about any specific decision)
+- D) Revise (the plan itself needs changes)
+- E) Reject (start over)
+
+**Option handling:**
+- A: mark APPROVED, write review logs, suggest /ship
+- B: ask which overrides, apply, re-present gate
+- C: answer freeform, re-present gate
+- D: make changes, re-run affected phases (scope→1B, design→2, test plan→3, arch→3). Max 3 cycles.
+- E: start over
+
+---
+
+## Completion: Write Review Logs
+
+On approval, write 3 separate review log entries so /ship's dashboard recognizes them:
+
+```bash
+COMMIT=$(git rev-parse --short HEAD 2>/dev/null)
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Review log (adapt to your review tracking system)
+#  '{"skill":"plan-ceo-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"critical_gaps":0,"mode":"SELECTIVE_EXPANSION","via":"autoplan","commit":"'"$COMMIT"'"}'
+
+# Review log (adapt to your review tracking system)
+#  '{"skill":"plan-eng-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"critical_gaps":0,"issues_found":0,"mode":"FULL_REVIEW","via":"autoplan","commit":"'"$COMMIT"'"}'
+```
+
+If Phase 2 ran (UI scope):
+```bash
+# Review log (adapt to your review tracking system)
+#  '{"skill":"plan-design-review","timestamp":"'"$TIMESTAMP"'","status":"clean","unresolved":0,"via":"autoplan","commit":"'"$COMMIT"'"}'
+```
+
+Replace field values with actual counts from the review.
+
+Suggest next step: `/ship` when ready to create the PR.
+
+---
+
+## Important Rules
+
+- **Never abort.** The user chose /autoplan. Respect that choice. Surface all taste decisions, never redirect to interactive review.
+- **Premises are the one gate.** The only non-auto-decided AskUserQuestion is the premise confirmation in Phase 1.
+- **Log every decision.** No silent auto-decisions. Every choice gets a row in the audit trail.
+- **Full depth.** Do not compress or skip sections from the loaded skill files (except the skip list in Phase 0).
+- **Sequential order.** CEO → Design → Eng. Each phase builds on the last.
+

package/skills/library/benchmark.md

@@ -0,0 +1,242 @@
+---
+name: benchmark
+version: 1.0.0
+description: |
+  Performance regression detection using the browse daemon. Establishes
+  baselines for page load times, Core Web Vitals, and resource sizes.
+  Compares before/after on every PR. Tracks performance trends over time.
+  Use when: "performance", "benchmark", "page speed", "lighthouse", "web vitals",
+  "bundle size", "load time".
+---
+
+## SETUP (run this check BEFORE any browse command)
+
+```bash
+_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+B=""
+[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/orch/browse/dist/browse" ] && B="$_ROOT/.claude/skills/orch/browse/dist/browse"
+[ -z "$B" ] && B=~/.claude/skills/orch/browse/dist/browse
+if [ -x "$B" ]; then
+  echo "READY: $B"
+else
+  echo "NEEDS_SETUP"
+fi
+```
+
+If `NEEDS_SETUP`:
+1. Tell the user: "orch browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
+2. Run: `cd <SKILL_DIR> && ./setup`
+3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
+
+# /benchmark — Performance Regression Detection
+
+You are a **Performance Engineer** who has optimized apps serving millions of requests. You know that performance doesn't degrade in one big regression — it dies by a thousand paper cuts. Each PR adds 50ms here, 20KB there, and one day the app takes 8 seconds to load and nobody knows when it got slow.
+
+Your job is to measure, baseline, compare, and alert. You use the browse daemon's `perf` command and JavaScript evaluation to gather real performance data from running pages.
+
+## User-invocable
+When the user types `/benchmark`, run this skill.
+
+## Arguments
+- `/benchmark <url>` — full performance audit with baseline comparison
+- `/benchmark <url> --baseline` — capture baseline (run before making changes)
+- `/benchmark <url> --quick` — single-pass timing check (no baseline needed)
+- `/benchmark <url> --pages /,/dashboard,/api/health` — specify pages
+- `/benchmark --diff` — benchmark only pages affected by current branch
+- `/benchmark --trend` — show performance trends from historical data
+
+## Instructions
+
+### Phase 1: Setup
+
+```bash
+eval $(~/.claude/skills/orch/bin/orch-slug 2>/dev/null || echo "SLUG=unknown")
+mkdir -p .orch/benchmark-reports
+mkdir -p .orch/benchmark-reports/baselines
+```
+
+### Phase 2: Page Discovery
+
+Same as /canary — auto-discover from navigation or use `--pages`.
+
+If `--diff` mode:
+```bash
+git diff $(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null || echo main)...HEAD --name-only
+```
+
+### Phase 3: Performance Data Collection
+
+For each page, collect comprehensive performance metrics:
+
+```bash
+$B goto <page-url>
+$B perf
+```
+
+Then gather detailed metrics via JavaScript:
+
+```bash
+$B eval "JSON.stringify(performance.getEntriesByType('navigation')[0])"
+```
+
+Extract key metrics:
+- **TTFB** (Time to First Byte): `responseStart - requestStart`
+- **FCP** (First Contentful Paint): from PerformanceObserver or `paint` entries
+- **LCP** (Largest Contentful Paint): from PerformanceObserver
+- **DOM Interactive**: `domInteractive - navigationStart`
+- **DOM Complete**: `domComplete - navigationStart`
+- **Full Load**: `loadEventEnd - navigationStart`
+
+Resource analysis:
+```bash
+$B eval "JSON.stringify(performance.getEntriesByType('resource').map(r => ({name: r.name.split('/').pop().split('?')[0], type: r.initiatorType, size: r.transferSize, duration: Math.round(r.duration)})).sort((a,b) => b.duration - a.duration).slice(0,15))"
+```
+
+Bundle size check:
+```bash
+$B eval "JSON.stringify(performance.getEntriesByType('resource').filter(r => r.initiatorType === 'script').map(r => ({name: r.name.split('/').pop().split('?')[0], size: r.transferSize})))"
+$B eval "JSON.stringify(performance.getEntriesByType('resource').filter(r => r.initiatorType === 'css').map(r => ({name: r.name.split('/').pop().split('?')[0], size: r.transferSize})))"
+```
+
+Network summary:
+```bash
+$B eval "(() => { const r = performance.getEntriesByType('resource'); return JSON.stringify({total_requests: r.length, total_transfer: r.reduce((s,e) => s + (e.transferSize||0), 0), by_type: Object.entries(r.reduce((a,e) => { a[e.initiatorType] = (a[e.initiatorType]||0) + 1; return a; }, {})).sort((a,b) => b[1]-a[1])})})()"
+```
+
+### Phase 4: Baseline Capture (--baseline mode)
+
+Save metrics to baseline file:
+
+```json
+{
+  "url": "<url>",
+  "timestamp": "<ISO>",
+  "branch": "<branch>",
+  "pages": {
+    "/": {
+      "ttfb_ms": 120,
+      "fcp_ms": 450,
+      "lcp_ms": 800,
+      "dom_interactive_ms": 600,
+      "dom_complete_ms": 1200,
+      "full_load_ms": 1400,
+      "total_requests": 42,
+      "total_transfer_bytes": 1250000,
+      "js_bundle_bytes": 450000,
+      "css_bundle_bytes": 85000,
+      "largest_resources": [
+        {"name": "main.js", "size": 320000, "duration": 180},
+        {"name": "vendor.js", "size": 130000, "duration": 90}
+      ]
+    }
+  }
+}
+```
+
+Write to `.orch/benchmark-reports/baselines/baseline.json`.
+
+### Phase 5: Comparison
+
+If baseline exists, compare current metrics against it:
+
+```
+PERFORMANCE REPORT — [url]
+══════════════════════════
+Branch: [current-branch] vs baseline ([baseline-branch])
+
+Page: /
+─────────────────────────────────────────────────────
+Metric              Baseline    Current     Delta    Status
+────────            ────────    ───────     ─────    ──────
+TTFB                120ms       135ms       +15ms    OK
+FCP                 450ms       480ms       +30ms    OK
+LCP                 800ms       1600ms      +800ms   REGRESSION
+DOM Interactive     600ms       650ms       +50ms    OK
+DOM Complete        1200ms      1350ms      +150ms   WARNING
+Full Load           1400ms      2100ms      +700ms   REGRESSION
+Total Requests      42          58          +16      WARNING
+Transfer Size       1.2MB       1.8MB       +0.6MB   REGRESSION
+JS Bundle           450KB       720KB       +270KB   REGRESSION
+CSS Bundle          85KB        88KB        +3KB     OK
+
+REGRESSIONS DETECTED: 3
+  [1] LCP doubled (800ms → 1600ms) — likely a large new image or blocking resource
+  [2] Total transfer +50% (1.2MB → 1.8MB) — check new JS bundles
+  [3] JS bundle +60% (450KB → 720KB) — new dependency or missing tree-shaking
+```
+
+**Regression thresholds:**
+- Timing metrics: >50% increase OR >500ms absolute increase = REGRESSION
+- Timing metrics: >20% increase = WARNING
+- Bundle size: >25% increase = REGRESSION
+- Bundle size: >10% increase = WARNING
+- Request count: >30% increase = WARNING
+
+### Phase 6: Slowest Resources
+
+```
+TOP 10 SLOWEST RESOURCES
+═════════════════════════
+#   Resource                  Type      Size      Duration
+1   vendor.chunk.js          script    320KB     480ms
+2   main.js                  script    250KB     320ms
+3   hero-image.webp          img       180KB     280ms
+4   analytics.js             script    45KB      250ms    ← third-party
+5   fonts/inter-var.woff2    font      95KB      180ms
+...
+
+RECOMMENDATIONS:
+- vendor.chunk.js: Consider code-splitting — 320KB is large for initial load
+- analytics.js: Load async/defer — blocks rendering for 250ms
+- hero-image.webp: Add width/height to prevent CLS, consider lazy loading
+```
+
+### Phase 7: Performance Budget
+
+Check against industry budgets:
+
+```
+PERFORMANCE BUDGET CHECK
+════════════════════════
+Metric              Budget      Actual      Status
+────────            ──────      ──────      ──────
+FCP                 < 1.8s      0.48s       PASS
+LCP                 < 2.5s      1.6s        PASS
+Total JS            < 500KB     720KB       FAIL
+Total CSS           < 100KB     88KB        PASS
+Total Transfer      < 2MB       1.8MB       WARNING (90%)
+HTTP Requests       < 50        58          FAIL
+
+Grade: B (4/6 passing)
+```
+
+### Phase 8: Trend Analysis (--trend mode)
+
+Load historical baseline files and show trends:
+
+```
+PERFORMANCE TRENDS (last 5 benchmarks)
+══════════════════════════════════════
+Date        FCP     LCP     Bundle    Requests    Grade
+2026-03-10  420ms   750ms   380KB     38          A
+2026-03-12  440ms   780ms   410KB     40          A
+2026-03-14  450ms   800ms   450KB     42          A
+2026-03-16  460ms   850ms   520KB     48          B
+2026-03-18  480ms   1600ms  720KB     58          B
+
+TREND: Performance degrading. LCP doubled in 8 days.
+       JS bundle growing 50KB/week. Investigate.
+```
+
+### Phase 9: Save Report
+
+Write to `.orch/benchmark-reports/{date}-benchmark.md` and `.orch/benchmark-reports/{date}-benchmark.json`.
+
+## Important Rules
+
+- **Measure, don't guess.** Use actual performance.getEntries() data, not estimates.
+- **Baseline is essential.** Without a baseline, you can report absolute numbers but can't detect regressions. Always encourage baseline capture.
+- **Relative thresholds, not absolute.** 2000ms load time is fine for a complex dashboard, terrible for a landing page. Compare against YOUR baseline.
+- **Third-party scripts are context.** Flag them, but the user can't fix Google Analytics being slow. Focus recommendations on first-party resources.
+- **Bundle size is the leading indicator.** Load time varies with network. Bundle size is deterministic. Track it religiously.
+- **Read-only.** Produce the report. Don't modify code unless explicitly asked.