@oxgeneral/orch 1.0.7 → 1.0.9

package/skills/library/browse.md

@@ -0,0 +1,266 @@
+---
+name: browse
+version: 1.1.0
+description: |
+  Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with
+  elements, verify page state, diff before/after actions, take annotated screenshots, check
+  responsive layouts, test forms and uploads, handle dialogs, and assert element states.
+  ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a
+  user flow, or file a bug with evidence. Use when asked to "open in browser", "test the
+  site", "take a screenshot", or "dogfood this".
+---
+
+## 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`
+
+## Core QA Patterns
+
+### 1. Verify a page loads correctly
+```bash
+$B goto https://yourapp.com
+$B text                          # content loads?
+$B console                       # JS errors?
+$B network                       # failed requests?
+$B is visible ".main-content"    # key elements present?
+```
+
+### 2. Test a user flow
+```bash
+$B goto https://app.com/login
+$B snapshot -i                   # see all interactive elements
+$B fill @e3 "user@test.com"
+$B fill @e4 "password"
+$B click @e5                     # submit
+$B snapshot -D                   # diff: what changed after submit?
+$B is visible ".dashboard"       # success state present?
+```
+
+### 3. Verify an action worked
+```bash
+$B snapshot                      # baseline
+$B click @e3                     # do something
+$B snapshot -D                   # unified diff shows exactly what changed
+```
+
+### 4. Visual evidence for bug reports
+```bash
+$B snapshot -i -a -o /tmp/annotated.png   # labeled screenshot
+$B screenshot /tmp/bug.png                # plain screenshot
+$B console                                # error log
+```
+
+### 5. Find all clickable elements (including non-ARIA)
+```bash
+$B snapshot -C                   # finds divs with cursor:pointer, onclick, tabindex
+$B click @c1                     # interact with them
+```
+
+### 6. Assert element states
+```bash
+$B is visible ".modal"
+$B is enabled "#submit-btn"
+$B is disabled "#submit-btn"
+$B is checked "#agree-checkbox"
+$B is editable "#name-field"
+$B is focused "#search-input"
+$B js "document.body.textContent.includes('Success')"
+```
+
+### 7. Test responsive layouts
+```bash
+$B responsive /tmp/layout        # mobile + tablet + desktop screenshots
+$B viewport 375x812              # or set specific viewport
+$B screenshot /tmp/mobile.png
+```
+
+### 8. Test file uploads
+```bash
+$B upload "#file-input" /path/to/file.pdf
+$B is visible ".upload-success"
+```
+
+### 9. Test dialogs
+```bash
+$B dialog-accept "yes"           # set up handler
+$B click "#delete-button"        # trigger dialog
+$B dialog                        # see what appeared
+$B snapshot -D                   # verify deletion happened
+```
+
+### 10. Compare environments
+```bash
+$B diff https://staging.app.com https://prod.app.com
+```
+
+### 11. Show screenshots to the user
+After `$B screenshot`, `$B snapshot -a -o`, or `$B responsive`, always use the Read tool on the output PNG(s) so the user can see them. Without this, screenshots are invisible.
+
+## User Handoff
+
+When you hit something you can't handle in headless mode (CAPTCHA, complex auth, multi-factor
+login), hand off to the user:
+
+```bash
+# 1. Open a visible Chrome at the current page
+$B handoff "Stuck on CAPTCHA at login page"
+
+# 2. Tell the user what happened (via AskUserQuestion)
+#    "I've opened Chrome at the login page. Please solve the CAPTCHA
+#     and let me know when you're done."
+
+# 3. When user says "done", re-snapshot and continue
+$B resume
+```
+
+**When to use handoff:**
+- CAPTCHAs or bot detection
+- Multi-factor authentication (SMS, authenticator app)
+- OAuth flows that require user interaction
+- Complex interactions the AI can't handle after 3 attempts
+
+The browser preserves all state (cookies, localStorage, tabs) across the handoff.
+After `resume`, you get a fresh snapshot of wherever the user left off.
+
+## Snapshot Flags
+
+The snapshot is your primary tool for understanding and interacting with pages.
+
+```
+-i        --interactive           Interactive elements only (buttons, links, inputs) with @e refs
+-c        --compact               Compact (no empty structural nodes)
+-d <N>    --depth                 Limit tree depth (0 = root only, default: unlimited)
+-s <sel>  --selector              Scope to CSS selector
+-D        --diff                  Unified diff against previous snapshot (first call stores baseline)
+-a        --annotate              Annotated screenshot with red overlay boxes and ref labels
+-o <path> --output                Output path for annotated screenshot (default: <temp>/browse-annotated.png)
+-C        --cursor-interactive    Cursor-interactive elements (@c refs — divs with pointer, onclick)
+```
+
+All flags can be combined freely. `-o` only applies when `-a` is also used.
+Example: `$B snapshot -i -a -C -o /tmp/annotated.png`
+
+**Ref numbering:** @e refs are assigned sequentially (@e1, @e2, ...) in tree order.
+@c refs from `-C` are numbered separately (@c1, @c2, ...).
+
+After snapshot, use @refs as selectors in any command:
+```bash
+$B click @e3       $B fill @e4 "value"     $B hover @e1
+$B html @e2        $B css @e5 "color"      $B attrs @e6
+$B click @c1       # cursor-interactive ref (from -C)
+```
+
+**Output format:** indented accessibility tree with @ref IDs, one element per line.
+```
+  @e1 [heading] "Welcome" [level=1]
+  @e2 [textbox] "Email"
+  @e3 [button] "Submit"
+```
+
+Refs are invalidated on navigation — run `snapshot` again after `goto`.
+
+## Full Command List
+
+### Navigation
+| Command | Description |
+|---------|-------------|
+| `back` | History back |
+| `forward` | History forward |
+| `goto <url>` | Navigate to URL |
+| `reload` | Reload page |
+| `url` | Print current URL |
+
+### Reading
+| Command | Description |
+|---------|-------------|
+| `accessibility` | Full ARIA tree |
+| `forms` | Form fields as JSON |
+| `html [selector]` | innerHTML of selector (throws if not found), or full page HTML if no selector given |
+| `links` | All links as "text → href" |
+| `text` | Cleaned page text |
+
+### Interaction
+| Command | Description |
+|---------|-------------|
+| `click <sel>` | Click element |
+| `cookie <name>=<value>` | Set cookie on current page domain |
+| `cookie-import <json>` | Import cookies from JSON file |
+| `cookie-import-browser [browser] [--domain d]` | Import cookies from Comet, Chrome, Arc, Brave, or Edge (opens picker, or use --domain for direct import) |
+| `dialog-accept [text]` | Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response |
+| `dialog-dismiss` | Auto-dismiss next dialog |
+| `fill <sel> <val>` | Fill input |
+| `header <name>:<value>` | Set custom request header (colon-separated, sensitive values auto-redacted) |
+| `hover <sel>` | Hover element |
+| `press <key>` | Press key — Enter, Tab, Escape, ArrowUp/Down/Left/Right, Backspace, Delete, Home, End, PageUp, PageDown, or modifiers like Shift+Enter |
+| `scroll [sel]` | Scroll element into view, or scroll to page bottom if no selector |
+| `select <sel> <val>` | Select dropdown option by value, label, or visible text |
+| `type <text>` | Type into focused element |
+| `upload <sel> <file> [file2...]` | Upload file(s) |
+| `useragent <string>` | Set user agent |
+| `viewport <WxH>` | Set viewport size |
+| `wait <sel|--networkidle|--load>` | Wait for element, network idle, or page load (timeout: 15s) |
+
+### Inspection
+| Command | Description |
+|---------|-------------|
+| `attrs <sel|@ref>` | Element attributes as JSON |
+| `console [--clear|--errors]` | Console messages (--errors filters to error/warning) |
+| `cookies` | All cookies as JSON |
+| `css <sel> <prop>` | Computed CSS value |
+| `dialog [--clear]` | Dialog messages |
+| `eval <file>` | Run JavaScript from file and return result as string (path must be under /tmp or cwd) |
+| `is <prop> <sel>` | State check (visible/hidden/enabled/disabled/checked/editable/focused) |
+| `js <expr>` | Run JavaScript expression and return result as string |
+| `network [--clear]` | Network requests |
+| `perf` | Page load timings |
+| `storage [set k v]` | Read all localStorage + sessionStorage as JSON, or set <key> <value> to write localStorage |
+
+### Visual
+| Command | Description |
+|---------|-------------|
+| `diff <url1> <url2>` | Text diff between pages |
+| `pdf [path]` | Save as PDF |
+| `responsive [prefix]` | Screenshots at mobile (375x812), tablet (768x1024), desktop (1280x720). Saves as {prefix}-mobile.png etc. |
+| `screenshot [--viewport] [--clip x,y,w,h] [selector|@ref] [path]` | Save screenshot (supports element crop via CSS/@ref, --clip region, --viewport) |
+
+### Snapshot
+| Command | Description |
+|---------|-------------|
+| `snapshot [flags]` | Accessibility tree with @e refs for element selection. Flags: -i interactive only, -c compact, -d N depth limit, -s sel scope, -D diff vs previous, -a annotated screenshot, -o path output, -C cursor-interactive @c refs |
+
+### Meta
+| Command | Description |
+|---------|-------------|
+| `chain` | Run commands from JSON stdin. Format: [["cmd","arg1",...],...] |
+
+### Tabs
+| Command | Description |
+|---------|-------------|
+| `closetab [id]` | Close tab |
+| `newtab [url]` | Open new tab |
+| `tab <id>` | Switch to tab |
+| `tabs` | List open tabs |
+
+### Server
+| Command | Description |
+|---------|-------------|
+| `handoff [message]` | Open visible Chrome at current page for user takeover |
+| `restart` | Restart server |
+| `resume` | Re-snapshot after user takeover, return control to AI |
+| `status` | Health check |
+| `stop` | Shutdown server |

package/skills/library/canary.md

@@ -0,0 +1,248 @@
+---
+name: canary
+version: 1.0.0
+description: |
+  Post-deploy canary monitoring. Watches the live app for console errors,
+  performance regressions, and page failures using the browse daemon. Takes
+  periodic screenshots, compares against pre-deploy baselines, and alerts
+  on anomalies. Use when: "monitor deploy", "canary", "post-deploy check",
+  "watch production", "verify deploy".
+---
+
+## SETUP (run this check BEFORE any browse command)
+
+```bash
+_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+B=""
+[ -n "$_ROOT" ] && [ -x "# browse binary (project-local)" ] && B="# browse binary (project-local)"
+[ -z "$B" ] && B=# browse binary path (adapt to your browse tool setup)
+if [ -x "$B" ]; then
+  echo "READY: $B"
+else
+  echo "NEEDS_SETUP"
+fi
+```
+
+If `NEEDS_SETUP`:
+1. Tell the user: "the browse tool 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`
+
+## 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."
+
+---
+
+# /canary — Post-Deploy Visual Monitor
+
+You are a **Release Reliability Engineer** watching production after a deploy. You've seen deploys that pass CI but break in production — a missing environment variable, a CDN cache serving stale assets, a database migration that's slower than expected on real data. Your job is to catch these in the first 10 minutes, not 10 hours.
+
+You use the browse daemon to watch the live app, take screenshots, check console errors, and compare against baselines. You are the safety net between "shipped" and "verified."
+
+## User-invocable
+When the user types `/canary`, run this skill.
+
+## Arguments
+- `/canary <url>` — monitor a URL for 10 minutes after deploy
+- `/canary <url> --duration 5m` — custom monitoring duration (1m to 30m)
+- `/canary <url> --baseline` — capture baseline screenshots (run BEFORE deploying)
+- `/canary <url> --pages /,/dashboard,/settings` — specify pages to monitor
+- `/canary <url> --quick` — single-pass health check (no continuous monitoring)
+
+## Instructions
+
+### Phase 1: Setup
+
+```bash
+# Project slug detection
+SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")
+mkdir -p .orch/canary-reports
+mkdir -p .orch/canary-reports/baselines
+mkdir -p .orch/canary-reports/screenshots
+```
+
+Parse the user's arguments. Default duration is 10 minutes. Default pages: auto-discover from the app's navigation.
+
+### Phase 2: Baseline Capture (--baseline mode)
+
+If the user passed `--baseline`, capture the current state BEFORE deploying.
+
+For each page (either from `--pages` or the homepage):
+
+```bash
+$B goto <page-url>
+$B snapshot -i -a -o ".orch/canary-reports/baselines/<page-name>.png"
+$B console --errors
+$B perf
+$B text
+```
+
+Collect for each page: screenshot path, console error count, page load time from `perf`, and a text content snapshot.
+
+Save the baseline manifest to `.orch/canary-reports/baseline.json`:
+
+```json
+{
+  "url": "<url>",
+  "timestamp": "<ISO>",
+  "branch": "<current branch>",
+  "pages": {
+    "/": {
+      "screenshot": "baselines/home.png",
+      "console_errors": 0,
+      "load_time_ms": 450
+    }
+  }
+}
+```
+
+Then STOP and tell the user: "Baseline captured. Deploy your changes, then run `/canary <url>` to monitor."
+
+### Phase 3: Page Discovery
+
+If no `--pages` were specified, auto-discover pages to monitor:
+
+```bash
+$B goto <url>
+$B links
+$B snapshot -i
+```
+
+Extract the top 5 internal navigation links from the `links` output. Always include the homepage. Present the page list via AskUserQuestion:
+
+- **Context:** Monitoring the production site at the given URL after a deploy.
+- **Question:** Which pages should the canary monitor?
+- **RECOMMENDATION:** Choose A — these are the main navigation targets.
+- A) Monitor these pages: [list the discovered pages]
+- B) Add more pages (user specifies)
+- C) Monitor homepage only (quick check)
+
+### Phase 4: Pre-Deploy Snapshot (if no baseline exists)
+
+If no `baseline.json` exists, take a quick snapshot now as a reference point.
+
+For each page to monitor:
+
+```bash
+$B goto <page-url>
+$B snapshot -i -a -o ".orch/canary-reports/screenshots/pre-<page-name>.png"
+$B console --errors
+$B perf
+```
+
+Record the console error count and load time for each page. These become the reference for detecting regressions during monitoring.
+
+### Phase 5: Continuous Monitoring Loop
+
+Monitor for the specified duration. Every 60 seconds, check each page:
+
+```bash
+$B goto <page-url>
+$B snapshot -i -a -o ".orch/canary-reports/screenshots/<page-name>-<check-number>.png"
+$B console --errors
+$B perf
+```
+
+After each check, compare results against the baseline (or pre-deploy snapshot):
+
+1. **Page load failure** — `goto` returns error or timeout → CRITICAL ALERT
+2. **New console errors** — errors not present in baseline → HIGH ALERT
+3. **Performance regression** — load time exceeds 2x baseline → MEDIUM ALERT
+4. **Broken links** — new 404s not in baseline → LOW ALERT
+
+**Alert on changes, not absolutes.** A page with 3 console errors in the baseline is fine if it still has 3. One NEW error is an alert.
+
+**Don't cry wolf.** Only alert on patterns that persist across 2 or more consecutive checks. A single transient network blip is not an alert.
+
+**If a CRITICAL or HIGH alert is detected**, immediately notify the user via AskUserQuestion:
+
+```
+CANARY ALERT
+════════════
+Time:     [timestamp, e.g., check #3 at 180s]
+Page:     [page URL]
+Type:     [CRITICAL / HIGH / MEDIUM]
+Finding:  [what changed — be specific]
+Evidence: [screenshot path]
+Baseline: [baseline value]
+Current:  [current value]
+```
+
+- **Context:** Canary monitoring detected an issue on [page] after [duration].
+- **RECOMMENDATION:** Choose based on severity — A for critical, B for transient.
+- A) Investigate now — stop monitoring, focus on this issue
+- B) Continue monitoring — this might be transient (wait for next check)
+- C) Rollback — revert the deploy immediately
+- D) Dismiss — false positive, continue monitoring
+
+### Phase 6: Health Report
+
+After monitoring completes (or if the user stops early), produce a summary:
+
+```
+CANARY REPORT — [url]
+═════════════════════
+Duration:     [X minutes]
+Pages:        [N pages monitored]
+Checks:       [N total checks performed]
+Status:       [HEALTHY / DEGRADED / BROKEN]
+
+Per-Page Results:
+─────────────────────────────────────────────────────
+  Page            Status      Errors    Avg Load
+  /               HEALTHY     0         450ms
+  /dashboard      DEGRADED    2 new     1200ms (was 400ms)
+  /settings       HEALTHY     0         380ms
+
+Alerts Fired:  [N] (X critical, Y high, Z medium)
+Screenshots:   .orch/canary-reports/screenshots/
+
+VERDICT: [DEPLOY IS HEALTHY / DEPLOY HAS ISSUES — details above]
+```
+
+Save report to `.orch/canary-reports/{date}-canary.md` and `.orch/canary-reports/{date}-canary.json`.
+
+Log the result for the review dashboard:
+
+```bash
+# Project slug detection (adapt to your project structure)
+mkdir -p .orch/reports
+```
+
+Write a JSONL entry: `{"skill":"canary","timestamp":"<ISO>","status":"<HEALTHY/DEGRADED/BROKEN>","url":"<url>","duration_min":<N>,"alerts":<N>}`
+
+### Phase 7: Baseline Update
+
+If the deploy is healthy, offer to update the baseline:
+
+- **Context:** Canary monitoring completed. The deploy is healthy.
+- **RECOMMENDATION:** Choose A — deploy is healthy, new baseline reflects current production.
+- A) Update baseline with current screenshots
+- B) Keep old baseline
+
+If the user chooses A, copy the latest screenshots to the baselines directory and update `baseline.json`.
+
+## Important Rules
+
+- **Speed matters.** Start monitoring within 30 seconds of invocation. Don't over-analyze before monitoring.
+- **Alert on changes, not absolutes.** Compare against baseline, not industry standards.
+- **Screenshots are evidence.** Every alert includes a screenshot path. No exceptions.
+- **Transient tolerance.** Only alert on patterns that persist across 2+ consecutive checks.
+- **Baseline is king.** Without a baseline, canary is a health check. Encourage `--baseline` before deploying.
+- **Performance thresholds are relative.** 2x baseline is a regression. 1.5x might be normal variance.
+- **Read-only.** Observe and report. Don't modify code unless the user explicitly asks to investigate and fix.
+

package/skills/library/careful.md

@@ -0,0 +1,42 @@
+---
+name: careful
+version: 0.1.0
+description: |
+  Safety guardrails for destructive commands. Warns before rm -rf, DROP TABLE,
+  force-push, git reset --hard, kubectl delete, and similar destructive operations.
+  User can override each warning. Use when touching prod, debugging live systems,
+  or working in a shared environment. Use when asked to "be careful", "safety mode",
+  "prod mode", or "careful mode".
+---
+
+# /careful — Destructive Command Guardrails
+
+Safety mode is now **active**. Every bash command will be checked for destructive
+patterns before running. If a destructive command is detected, you'll be warned
+and can choose to proceed or cancel.
+
+## What's protected
+
+| Pattern | Example | Risk |
+|---------|---------|------|
+| `rm -rf` / `rm -r` / `rm --recursive` | `rm -rf /var/data` | Recursive delete |
+| `DROP TABLE` / `DROP DATABASE` | `DROP TABLE users;` | Data loss |
+| `TRUNCATE` | `TRUNCATE orders;` | Data loss |
+| `git push --force` / `-f` | `git push -f origin main` | History rewrite |
+| `git reset --hard` | `git reset --hard HEAD~3` | Uncommitted work loss |
+| `git checkout .` / `git restore .` | `git checkout .` | Uncommitted work loss |
+| `kubectl delete` | `kubectl delete pod` | Production impact |
+| `docker rm -f` / `docker system prune` | `docker system prune -a` | Container/image loss |
+
+## Safe exceptions
+
+These patterns are allowed without warning:
+- `rm -rf node_modules` / `.next` / `dist` / `__pycache__` / `.cache` / `build` / `.turbo` / `coverage`
+
+## How it works
+
+The hook reads the command from the tool input JSON, checks it against the
+patterns above, and returns `permissionDecision: "ask"` with a warning message
+if a match is found. You can always override the warning and proceed.
+
+To deactivate, end the conversation or start a new one. Hooks are session-scoped.