@caddis/cli 0.3.0 → 0.4.0

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/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