@caddis/cli 0.0.0 → 0.1.0

package/bundles/antigravity-plugin/skills/ui-review/references/visual-checklist.md

@@ -0,0 +1,236 @@
+# Visual Inspection Checklist
+
+This document is a comprehensive checklist of items to verify during web design visual inspection.
+
+---
+
+## 1. Layout Verification
+
+### Structural Integrity
+
+- [ ] Header is correctly fixed/positioned at the top of the screen
+- [ ] Footer is positioned at the bottom of the screen or end of content
+- [ ] Main content area is center-aligned with appropriate width
+- [ ] Sidebar (if present) is positioned correctly
+- [ ] Navigation is displayed in the intended position
+
+### Overflow
+
+- [ ] Horizontal scrollbar is not unintentionally displayed
+- [ ] Content does not overflow from parent elements
+- [ ] Images fit within parent containers
+- [ ] Tables do not exceed container width
+- [ ] Code blocks wrap or scroll appropriately
+
+### Alignment
+
+- [ ] Grid items are evenly distributed
+- [ ] Flex item alignment is correct
+- [ ] Text alignment (left/center/right) is consistent
+- [ ] Icons and text are vertically aligned
+- [ ] Form labels and input fields are correctly positioned
+
+---
+
+## 2. Typography Verification
+
+### Readability
+
+- [ ] Body text font size is sufficient (minimum 16px recommended)
+- [ ] Line height is appropriate (1.5-1.8 recommended)
+- [ ] Characters per line is appropriate (40-80 characters recommended)
+- [ ] Spacing between paragraphs is sufficient
+- [ ] Heading size hierarchy is clear
+
+### Text Handling
+
+- [ ] Long words wrap appropriately
+- [ ] URLs and code are handled properly
+- [ ] No text clipping occurs
+- [ ] Ellipsis (...) displays correctly
+- [ ] Language-specific line breaking rules work correctly
+
+### Fonts
+
+- [ ] Web fonts load correctly
+- [ ] Fallback fonts are appropriate
+- [ ] Font weights are as intended
+- [ ] Special characters and emoji display correctly
+
+---
+
+## 3. Color & Contrast Verification
+
+### Accessibility (WCAG Standards)
+
+- [ ] Body text: Contrast ratio 4.5:1 or higher (AA)
+- [ ] Large text (18px+ bold or 24px+): 3:1 or higher
+- [ ] Interactive element borders: 3:1 or higher
+- [ ] Focus indicators: Sufficient contrast with background
+
+### Color Consistency
+
+- [ ] Brand colors are unified
+- [ ] Link colors are consistent
+- [ ] Error state red is unified
+- [ ] Success state green is unified
+- [ ] Hover/active state colors are appropriate
+
+### Color Vision Diversity
+
+- [ ] Information conveyed by shape and text, not just color
+- [ ] Charts and diagrams consider color vision diversity
+- [ ] Error messages don't rely solely on color
+
+---
+
+## 4. Responsive Verification
+
+### Mobile (~640px)
+
+- [ ] Content fits within screen width
+- [ ] Touch targets are 44x44px or larger
+- [ ] Text is readable size
+- [ ] No horizontal scrolling occurs
+- [ ] Navigation is mobile-friendly (hamburger menu, etc.)
+- [ ] Form inputs are easy to use
+
+### Tablet (641px~1024px)
+
+- [ ] Layout is optimized for tablet
+- [ ] Two-column layouts display appropriately
+- [ ] Image sizes are appropriate
+- [ ] Sidebar show/hide is appropriate
+
+### Desktop (1025px~)
+
+- [ ] Maximum width is set and doesn't break on extra-large screens
+- [ ] Spacing is sufficient
+- [ ] Multi-column layouts function correctly
+- [ ] Hover states are implemented
+
+### Breakpoint Transitions
+
+- [ ] Layout transitions smoothly when screen size changes
+- [ ] Layout doesn't break at intermediate sizes
+- [ ] No content disappears or duplicates
+
+---
+
+## 5. Interactive Element Verification
+
+### Buttons
+
+- [ ] Default state is clear
+- [ ] Hover state exists (desktop)
+- [ ] Focus state is visually clear
+- [ ] Active (pressed) state exists
+- [ ] Disabled state is distinguishable
+- [ ] Loading state (if applicable)
+
+### Links
+
+- [ ] Links are visually identifiable
+- [ ] Visited links are distinguishable (if needed)
+- [ ] Hover state exists
+- [ ] Focus state is clear
+
+### Form Elements
+
+- [ ] Input field boundaries are clear
+- [ ] Placeholder text contrast is appropriate
+- [ ] Visual feedback on focus
+- [ ] Error state display
+- [ ] Required field indication
+- [ ] Dropdowns function correctly
+
+---
+
+## 6. Images & Media Verification
+
+### Images
+
+- [ ] Images display at appropriate size
+- [ ] Aspect ratio is maintained
+- [ ] High resolution display support (@2x)
+- [ ] Display when image fails to load
+- [ ] Lazy loading behavior works
+
+### Video & Embeds
+
+- [ ] Videos fit within containers
+- [ ] Aspect ratio is maintained
+- [ ] Embedded content is responsive
+- [ ] iframes don't overflow
+
+---
+
+## 7. Accessibility Verification
+
+### Keyboard Navigation
+
+- [ ] All interactive elements accessible via Tab key
+- [ ] Focus order is logical
+- [ ] Focus traps are appropriate (modals, etc.)
+- [ ] Skip to content link exists
+
+### Screen Reader Support
+
+- [ ] Images have alt text
+- [ ] Forms have labels
+- [ ] ARIA labels are appropriately set
+- [ ] Heading hierarchy is correct (h1→h2→h3...)
+
+### Motion
+
+- [ ] Animations are not excessive
+- [ ] prefers-reduced-motion is supported (if possible)
+
+---
+
+## 8. Performance-related Visual Issues
+
+### Loading
+
+- [ ] Font FOUT/FOIT is minimal
+- [ ] No layout shift (CLS) occurs
+- [ ] No jumping when images load
+- [ ] Skeleton screens are appropriate (if applicable)
+
+### Animation
+
+- [ ] Animations are smooth (60fps)
+- [ ] No performance issues when scrolling
+- [ ] Transitions are natural
+
+---
+
+## Priority Matrix
+
+| Priority | Category | Examples |
+|----------|----------|----------|
+| P0 (Critical) | Functionality breaking | Complete element overlap, content disappearance |
+| P1 (High) | Serious UX issues | Unreadable text, inoperable buttons |
+| P2 (Medium) | Moderate issues | Alignment issues, spacing inconsistencies |
+| P3 (Low) | Minor issues | Slight positioning differences, minor color variations |
+
+---
+
+## Verification Tools
+
+### Browser DevTools
+
+- Elements panel: DOM and style inspection
+- Lighthouse: Performance and accessibility audits
+- Device toolbar: Responsive testing
+
+### Accessibility Tools
+
+- axe DevTools
+- WAVE
+- Color Contrast Analyzer
+
+### Automation Tools
+
+- Playwright (screenshot comparison)
+- Percy / Chromatic (Visual Regression Testing)

package/bundles/antigravity-plugin/skills/usage-review/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: usage-review
+description: Review local caddis usage over a window, surface prioritised recommendations, and apply config changes in one step
+---
+
+# /usage-review — harness self-tuning
+
+Review your actual local usage patterns, surface caddis-specific improvements, and optionally
+apply config changes in one step. Data stays on-machine — no telemetry, no server.
+
+## Step 1 — run the analysis script
+
+Resolve the script path:
+- Plugin install: `${CLAUDE_PLUGIN_ROOT}/scripts/usage_review.py`
+- harness (caddis) checkout: `scripts/usage_review.py`
+
+Run it:
+```
+python "<resolved-path>" [--days $ARGUMENTS]
+```
+
+- Default window is **7 days**. If the user passed a number (e.g. `/usage-review 14`), use it.
+- Run from the project root so `.claude/usage-log.jsonl` is found correctly.
+- If the script exits with "No sessions found", tell the user and stop — no further steps.
+- The script prints a markdown report to stdout and writes `.claude/usage-review.html`.
+
+## Step 2 — present the report
+
+Display the markdown output. Then add a single interpretive sentence identifying the **one most
+impactful finding** — the one most likely to reduce rate-limit consumption or right-size the harness.
+
+Do NOT paraphrase every finding in prose — the report is already the output.
+
+## Step 3 — offer to apply
+
+For each finding marked **[apply]** in the report, ask the user whether to apply it.
+Show the diff before making the change. Never apply silently.
+
+Two paths:
+- **"Apply [R1]"** (or whichever ID) — apply that single finding.
+- **"Apply all safe ones"** — apply every finding whose `apply_target.type` is `agent_frontmatter`
+  (config-only, reversible). Show the full change list first, confirm, then apply.
+
+For `agent_frontmatter` apply targets: find the `model:` line in the frontmatter block (between
+the two `---` delimiters) of the named agent file and change its value. Show a diff-style preview
+(`- model: old` / `+ model: new`) before writing.
+
+## Step 4 — report outcome
+
+After any applies, tell the user which files changed and suggest:
+"Run `/usage-review` again after a few sessions to see the effect."
+
+## Step 5 — offer to schedule a recurring review (optional)
+
+After reporting the outcome, ask once:
+
+> "Want me to schedule this to run automatically every Wednesday? I can set it up with `/schedule`."
+
+If the user says yes, use the `schedule` skill to create a weekly routine:
+
+```
+Schedule a recurring cloud routine: every Wednesday, run /usage-review
+```
+
+The routine should fire mid-week so findings are fresh for the next work sprint. If the user
+declines, skip silently — the SessionStart nudge in `inject_relay.py` already covers the
+"you haven't reviewed in 7 days" case.
+
+## Notes
+
+- HTML dashboard written to `.caddis/reviews/usage-review.html`. Override the directory with
+  `--output-dir <dir>` if needed. The usage log is read from `.caddis/usage-log.jsonl`, falling
+  back to the legacy `.claude/usage-log.jsonl` during the migration.
+- `.caddis/.last-usage-review` is updated on each run — the SessionStart hook uses it to nudge
+  users who haven't reviewed in 7+ days.
+- `est_cost_usd` is an estimate from token counts, not actual billing. The Max plan is rate-limited,
+  not charged per token — treat it as a relative signal, not an invoice.

package/bundles/antigravity-plugin/skills/use-model/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: use-model
+description: Explain (or apply) the model lanes — claude / claude-glm / cross-review — key resolution, and how to add a provider
+---
+
+# /caddis:use-model — switch which model backs your session
+
+Explain the model-switching lanes so the user (or you, on their behalf) can move a session onto an
+OSS provider (GLM, DeepSeek, OpenRouter, or a custom endpoint) in one command, with no hardcoded key
+path. Full detail lives in the **Providers & keys** guide (`docs/guide/providers-and-keys.md`) — this
+command is the quick-reference + do-it-now version.
+
+## The lanes
+
+| Lane | Command | Billing |
+|---|---|---|
+| **Primary** | `claude` | your Anthropic plan |
+| **OSS lane** | `claude-oss <provider> [claude args…]` | the provider's plan/pay-per-token |
+| **Convenience alias** | `claude-glm [claude args…]` | same as `claude-oss glm` |
+| **Cross-vendor review** | `/caddis:cross-review` (`oss_review.py`) | the reviewer's plan |
+
+`claude-oss` / `claude-glm` are launchers at `claude-harness/scripts/claude-oss.{sh,ps1}`. Each
+resolves the endpoint/model/key, sets `ANTHROPIC_BASE_URL` / `ANTHROPIC_MODEL` / `ANTHROPIC_AUTH_TOKEN`
+for **that process only**, and hands off to the real `claude` — your default session is untouched.
+
+## Run it
+```powershell
+claude-oss glm -p "refactor X"        # or interactive: claude-oss glm
+claude-glm -p "refactor X"            # convenience alias for provider=glm
+claude-oss deepseek                   # any preset provider
+```
+```bash
+claude-oss glm -p "refactor X"
+claude-glm -p "refactor X"
+```
+$ARGUMENTS, if given, names the provider directly (`glm`, `deepseek`, `openrouter`, or any custom name
+paired with `OSS_BASE_URL`/`OSS_MODEL`).
+
+## Key resolution (never hardcoded)
+Precedence, highest wins:
+1. the provider's env var (`GLM_API_KEY` / `DEEPSEEK_API_KEY` / `OPENROUTER_API_KEY`) or generic `OSS_API_KEY`;
+2. a keys file at `$CADDIS_KEYS_FILE` (default `~/.claudster/keys.env`, `KEY=VALUE` lines, `#` comments);
+3. missing → the launcher exits non-zero with an actionable message naming the exact env var to set.
+
+The resolver is `claude-harness/scripts/oss_model.py` (`resolve(provider, env)`) — the one place a
+renamed model id or moved endpoint is edited (mirrors `oss_review.py`'s `PROVIDERS` table).
+
+## Adding a provider (or overriding one)
+No code change needed for a model-id bump — set env directly:
+```powershell
+$env:OSS_MODEL = "glm-5"              # override the preset's model
+$env:OSS_BASE_URL = "https://..."     # override the preset's endpoint
+```
+A wholly new provider: add a row to `PROVIDERS` in `oss_model.py` (base_url, model, key_env), or just
+pass an unknown provider name with `OSS_BASE_URL`+`OSS_MODEL` set — no table edit required.
+
+## First-time install
+Put `claude-harness/scripts/` (or your plugin's `scripts/` dir) on `PATH`, or add a shell profile
+function. `/setup-project-ai` documents the one-liner for your platform (PowerShell profile function /
+bash alias) — it does not silently edit your shell profile.
+
+## Exit codes
+`claude-oss`/`claude-glm` propagate the wrapped `claude` process's exit code, except a resolver failure
+(unknown provider without an override, or no key) which exits **3** with the message on stderr.

package/bundles/antigravity-plugin/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check AGENTS.md (the canonical rules file; CLAUDE.md is an @import shim)
+
+```bash
+grep -i "worktree.*director" AGENTS.md CLAUDE.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask User
+
+If no directory exists and no AGENTS.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+# Check if directory is ignored (respects local, global, and system gitignore)
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:**
+
+Per Jesse's rule "Fix broken things immediately":
+1. Add appropriate line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For Global Directory (~/.config/superpowers/worktrees)
+
+No .gitignore verification needed - outside project entirely.
+
+## Creation Steps
+
+### 1. Detect Project Name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. Create Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/superpowers/worktrees/*)
+    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. Run Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify Clean Baseline
+
+Run tests to ensure worktree starts clean:
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report Location
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check AGENTS.md → Ask user |
+| Directory not ignored | Add to .gitignore + commit |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Mistakes
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > AGENTS.md > ask
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+### Hardcoding setup commands
+
+- **Problem:** Breaks on projects using different tools
+- **Fix:** Auto-detect from project files (package.json, etc.)
+
+## Example Workflow
+
+```
+You: I'm using the using-git-worktrees skill to set up an isolated workspace.
+
+[Check .worktrees/ - exists]
+[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
+[Create worktree: git worktree add .worktrees/auth -b feature/auth]
+[Run npm install]
+[Run npm test - 47 passing]
+
+Worktree ready at /Users/jesse/myproject/.worktrees/auth
+Tests passing (47 tests, 0 failures)
+Ready to implement auth feature
+```
+
+## Red Flags
+
+**Never:**
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Assume directory location when ambiguous
+- Skip AGENTS.md check
+
+**Always:**
+- Follow directory priority: existing > AGENTS.md > ask
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+
+## Integration
+
+**Called by:**
+- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- Any skill needing isolated workspace
+
+**Pairs with:**
+- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
+- **executing-plans** or **subagent-driven-development** - Work happens in this worktree

package/bundles/antigravity-plugin/skills/version/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: version
+description: Report the installed caddis version
+---
+
+# /version — what caddis am I running?
+
+Report the caddis toolchain version to the user as **caddis <version>**.
+
+Get the version by reading the `version` field of the `plugin.json` manifest that ships in THIS install —
+do NOT guess or infer it from anything else. Read whichever path exists:
+
+- **Claude Code:** `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`
+- **agy (Antigravity):** the caddis plugin install dir — `~/.gemini/config/plugins/caddis/plugin.json`
+- **Otherwise:** the nearest `plugin.json` at/above this skill whose `name` is `caddis`.
+
+Read that file, take its `version`, and report `caddis <version>`. This reads the manifest live, so it is
+always the exact installed version. If no manifest is found, say so plainly rather than reporting a guess.