@caddis/cli 0.3.0 → 0.4.1

package/bundles/codex/.codex/skills/devops/git-commit/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: git-commit
+description: Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs.
+---
+
+# Git Commit Skill
+
+Create meaningful, conventional commit messages that follow team standards.
+
+## Trigger
+
+Activate when:
+- User asks to commit changes
+- User needs help writing a commit message
+- User asks "what should I commit this as?"
+
+---
+
+## Conventional Commit Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `feat` | New feature | `feat(complaints): add priority filtering` |
+| `fix` | Bug fix | `fix(auth): resolve session timeout issue` |
+| `docs` | Documentation | `docs: update API documentation` |
+| `style` | Formatting (no code change) | `style: fix indentation in models` |
+| `refactor` | Code restructuring | `refactor(db): extract query builder` |
+| `perf` | Performance improvement | `perf: add caching to dashboard` |
+| `test` | Adding/fixing tests | `test: add complaint service tests` |
+| `chore` | Maintenance | `chore: update dependencies` |
+| `ci` | CI/CD changes | `ci: add pytest to GitHub Actions` |
+| `build` | Build system/dependencies | `build: update webpack to v5` |
+| `revert` | Revert a previous commit | `revert: revert feat(api) endpoint` |
+
+### Scope
+
+Optional area of change:
+- `api` - Backend API changes
+- `ui` - Frontend/Streamlit changes
+- `db` - Database changes
+- `auth` - Authentication
+- `complaints` - Complaints feature
+- `analytics` - Analytics feature
+
+---
+
+## Phase 1: Analyze Changes
+
+### Actions
+
+0. **Run a pre-commit quality gate (blocking)**
+   ```bash
+   # Python repos
+   ruff check .
+
+   # TypeScript/React repos
+   npm run lint
+
+   # If both stacks exist, run both.
+   ```
+
+   If lint fails, do not proceed to commit generation until fixed.
+
+1. **Review staged changes**
+   ```bash
+   # If files are staged, use staged diff
+   git diff --staged --stat
+   git diff --staged
+
+   # If nothing staged, check working tree
+   git diff
+   git status --porcelain
+   ```
+
+2. **Stage files if needed**
+   ```bash
+   # Stage specific files
+   git add path/to/file1 path/to/file2
+
+   # Stage by pattern
+   git add *.test.*
+   git add src/components/*
+   ```
+
+   **Never stage secrets** (`.env`, `credentials.json`, private keys).
+
+3. **Categorize the changes**
+   - What files were modified?
+   - What was the primary purpose?
+   - Are there multiple logical changes?
+
+3. **Identify the commit type**
+   - New functionality → `feat`
+   - Bug fix → `fix`
+   - Code improvement without behavior change → `refactor`
+   - Tests → `test`
+   - Documentation → `docs`
+
+---
+
+## Phase 2: Craft the Message
+
+### Subject Line Rules
+
+1. **Use imperative mood**: "add" not "added" or "adds"
+2. **No period** at the end
+3. **50 characters or less** (hard limit: 72)
+4. **Lowercase** after the colon
+
+```
+# ✅ Good
+feat(complaints): add priority filter to dashboard
+fix(api): handle null customer_id in query
+refactor(db): extract database adapter class
+
+# ❌ Bad
+feat(complaints): Added priority filter to dashboard.  # Past tense, period
+FEAT: ADD PRIORITY FILTER  # Uppercase, no scope
+fix: various bug fixes  # Too vague
+```
+
+### Body (When Needed)
+
+Include body when:
+- Change needs explanation
+- There's context that isn't obvious
+- Breaking changes exist
+
+```
+feat(api): add complaint analytics endpoint
+
+Add new endpoint for retrieving complaint statistics
+including resolution times, category distribution, and
+trend analysis.
+
+This endpoint powers the new analytics dashboard.
+```
+
+### Footer (When Needed)
+
+```
+# Breaking change
+feat(api)!: change complaint response format
+
+BREAKING CHANGE: complaint.created_at now returns ISO format
+
+# Issue reference
+fix(ui): resolve dashboard loading error
+
+Fixes #123
+```
+
+---
+
+## Phase 3: Generate Message
+
+### Template
+
+Based on the changes, generate:
+
+```markdown
+## Suggested Commit Message
+
+```
+<type>(<scope>): <subject>
+
+<body if needed>
+```
+
+### Reasoning
+- Type: [Why this type was chosen]
+- Scope: [Area of the codebase affected]
+- Subject: [What the change does]
+```
+
+---
+
+## Examples
+
+### Simple Feature
+
+**Changes**: Added a new filter dropdown to the complaints dashboard
+
+```
+feat(ui): add status filter to complaints dashboard
+```
+
+### Bug Fix with Context
+
+**Changes**: Fixed issue where queries with special characters caused errors
+
+```
+fix(db): escape special characters in search queries
+
+The search function was failing when users entered characters
+like quotes or semicolons. Added proper escaping using
+parameterized queries.
+
+Fixes #42
+```
+
+### Refactoring
+
+**Changes**: Moved database logic from routes to repository classes
+
+```
+refactor(api): extract database operations to repository layer
+
+Move direct database calls from route handlers to dedicated
+repository classes. This improves testability and follows
+the separation of concerns principle.
+```
+
+### Multiple Files, Single Purpose
+
+**Changes**: Updated multiple files to add logging
+
+```
+feat: add structured logging throughout application
+
+- Add loguru configuration in config.py
+- Replace print statements with logger calls
+- Add request logging middleware
+```
+
+### Breaking Change
+
+**Changes**: Changed API response format
+
+```
+feat(api)!: standardize API response envelope
+
+BREAKING CHANGE: All API responses now wrapped in
+{ "data": ..., "meta": { "timestamp": ... } } format.
+
+Clients need to update response parsing logic.
+```
+
+---
+
+## Quick Reference
+
+When in doubt, ask yourself:
+
+1. **What type of change is this?** → Choose type
+2. **What area does it affect?** → Choose scope
+3. **What does it do?** (in imperative) → Write subject
+4. **Why was this done?** → Write body if needed
+5. **Does it break anything?** → Add BREAKING CHANGE if yes
+
+---
+
+## Git Safety Protocol
+
+- NEVER update git config
+- NEVER run destructive commands (`--force`, hard reset) without explicit user request
+- NEVER skip hooks (`--no-verify`) unless user asks
+- NEVER force push to main/master
+- ALWAYS verify lint gate status before creating a commit message
+- If a commit fails due to pre-commit hooks, fix the issue and create a NEW commit (don't amend the failed one)
+- One logical change per commit
+- Reference issues in footers: `Closes #123`, `Refs #456`
+
+---
+
+## Commit Message Checklist
+
+- [ ] Type is appropriate for the change
+- [ ] Scope identifies the affected area
+- [ ] Subject uses imperative mood
+- [ ] Subject is under 50 characters
+- [ ] Body explains "why" if not obvious
+- [ ] Breaking changes are marked with `!` and footer
+- [ ] Related issues are referenced
+- [ ] No secrets or credentials in staged files

package/bundles/codex/.codex/skills/devops/safe-cleanup/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: safe-cleanup
+description: Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment.
+---
+
+# Safe Cleanup
+
+## Overview
+
+Cleanup looks like the safest thing you do all day. It is the most destructive.
+
+This skill exists because of a real incident: an agent created 31 directory
+junctions from throwaway worktrees into live repositories, unlinked them, saw
+"31 unlinked, 0 failed", then recursively deleted the parent. A junction it had
+never seen survived the scan, the delete followed it, and **five repositories'
+development environments were destroyed**. Every verification afterwards said
+"intact", because the verification was wrong too.
+
+Two hours of repair. None of it would have happened with the rules below.
+
+## The one-paragraph version
+
+On Windows, `Remove-Item -Recurse` **follows junctions and deletes their
+targets**. Enumerating with `-ErrorAction SilentlyContinue` hides the ones you
+cannot read. And after the damage, `pip check`, `pip list` and file counts all
+report success, because metadata survives while package files do not. So: never
+link into somewhere real, never recurse through a link, prefer rename over
+delete, and verify by *using* the thing rather than counting it.
+
+---
+
+## RULE 1 - Prefer rename over delete
+
+Rename is atomic. Recursive delete is not: it can fail half way and leave a
+directory that looks present and is unusable.
+
+```powershell
+Rename-Item -Path $target -NewName ".broken-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+```
+
+In the incident, a venv holding `_greenlet.cp314-win_amd64.pyd` open **refused to
+delete** but **renamed fine**. Had the delete been retried or forced, it would
+have half-emptied the directory.
+
+Rename first, build fresh alongside, delete the old copy later when nothing holds
+it. Disk is cheap. An environment nobody can recover is not.
+
+## RULE 2 - Never recurse a delete through a reparse point
+
+Junctions and symlinks are transparent to `Remove-Item -Recurse`. Deleting a
+folder that contains a link to `C:\live\thing` deletes **the contents of
+`C:\live\thing`**.
+
+Check first, and **fail if the check itself cannot complete**:
+
+```powershell
+$links = @(Get-ChildItem $path -Recurse -Force -Directory -ErrorAction Stop |
+           Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) {
+    $links | ForEach-Object { Write-Host "  $($_.FullName) -> $($_.Target)" }
+    throw "refusing: $($links.Count) link(s) inside $path"
+}
+```
+
+`-ErrorAction SilentlyContinue` on that scan is precisely what caused the
+incident. A link inside a directory the scanner could not read was skipped in
+silence and never appeared in the count. **A scan that cannot see everything must
+fail, not shrug.**
+
+To remove a link itself, unlink it - never delete through it:
+
+```powershell
+[System.IO.Directory]::Delete($linkPath, $false)   # link only, never the target
+cmd /c rmdir "$linkPath"                            # same effect
+```
+
+## RULE 3 - Do not create links into live directories
+
+The safest delete is the one with nothing to follow.
+
+If a throwaway workspace needs dependencies, **build them there**, or point the
+tool at an absolute interpreter path. Do not junction `<scratch>\.venv` to
+`<live-repo>\.venv` for convenience - that is a loaded gun aimed at the repo, and
+any cleanup above the link can fire it.
+
+If you must link, remove the link the moment you are done, and never leave one
+inside a directory that something else will clean up.
+
+## RULE 4 - Verify by using, not by counting
+
+After any cleanup near an environment, prove it still works. These all LIE on a
+half-deleted Python venv, because dist-info metadata survives while package files
+are removed:
+
+| Check | Why it lies |
+|---|---|
+| `Test-Path .venv\Scripts\python.exe` | Proves the interpreter exists. Says nothing about packages. |
+| file or directory counts | Metadata directories inflate the count. |
+| `pip list` | Reads metadata. |
+| `pip check` | Reads metadata. Reported "No broken requirements found" on a venv that could not import fastapi. |
+| `pip install -e .` | Reads metadata, calls the package satisfied, **skips it, and reports success**. |
+
+The honest check is whether the interpreter can import what the project declares:
+
+```python
+import importlib.util
+importlib.util.find_spec("fastapi") is None   # -> True means genuinely missing
+```
+
+For node, check that a real entry point resolves, not that `node_modules` exists.
+
+**Map distribution names to import names.** `pyjwt` imports as `jwt`,
+`python-ulid` as `ulid`, `python-dotenv` as `dotenv`. A naive audit produces false
+positives and will have you rebuilding healthy environments - which is its own way
+of causing an outage.
+
+## RULE 5 - Stop what holds the files, or refuse
+
+A running service turns a delete into a **partial** delete - the worst outcome.
+
+Stop named services first. Then check for surviving processes and **refuse rather
+than force**:
+
+```powershell
+$held = @(Get-CimInstance Win32_Process -Filter "Name='python.exe'" |
+          Where-Object { $_.ExecutablePath -like "$venv\*" })
+if ($held.Count) { throw "refusing: still held by PID $($held[0].ProcessId)" }
+```
+
+In the incident's repair, this refused on one repo because a **VS Code language
+server** had held that venv since the previous day. Not a service, not safe to
+kill, not the script's business. That repo was fixed a different way. **Refusing
+was correct.**
+
+## RULE 6 - One agent at a time on a shared resource
+
+Two agents installing into the same environment concurrently can produce exactly
+this partial state. Three sessions were live in one repository during the
+incident. Whoever is repairing says so; everyone else keeps out.
+
+## RULE 7 - Verify against the source of truth, not the working copy
+
+Checkouts go stale. During the same incident a subagent reported a file as absent
+from a configuration, contradicting a change made hours earlier. The file was
+present on `origin/main`; the working copy was **10 commits behind**.
+
+Before asserting something is missing, check `git show origin/main:<path>`, not
+the file on disk.
+
+---
+
+## Before you delete anything - the checklist
+
+1. Can I **rename** instead? Do that.
+2. Does the tree contain **reparse points**? Scan with `-ErrorAction Stop`. Refuse if any, or if the scan fails.
+3. Does anything **hold files open**? Stop services; refuse on surviving processes.
+4. Did I create any **links into live directories** earlier in this session? Unlink them explicitly, by name.
+5. After: **verify by using**, not by counting.
+6. If something looks wrong: check `origin/main`, not the working copy.
+
+## What good verification output looks like
+
+Not this:
+
+```
+.venv intact: True          <- only proves python.exe exists
+31 unlinked, 0 failed       <- says nothing about what the scan missed
+No broken requirements found <- reads metadata, not reality
+```
+
+This:
+
+```
+service-a      OK   declared=24  missing=0     <- every declared dep imported
+service-b      OK   declared=19  missing=0
+```
+
+## Reference implementation
+
+The estate this skill came from keeps working tools at `.caddis/tools/`:
+
+- `venv-audit.py` - imports every dependency each `pyproject.toml` declares
+- `rebuild-venv.ps1` - renames aside, rebuilds, restarts services, refuses on links or live processes
+- `README-venv-safety.md` - the incident record
+
+Adapt rather than copy: the rules matter more than the scripts.

package/bundles/codex/.codex/skills/devops/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