anvil-dev-framework 0.1.6

package/global/commands/cleanup.md

@@ -0,0 +1,292 @@
+# /cleanup - Repository Hygiene Cleanup
+
+> Address accumulated stashes, orphan branches, and stale PRs to maintain repository health.
+
+## When to Use
+- After `/healthcheck` or `/orient` shows hygiene warnings
+- Periodically to prevent cruft accumulation
+- Before starting work on a clean slate
+- After merging a large PR to clean up related artifacts
+
+## Command Options
+
+```text
+/cleanup [--dry-run] [--category=stashes|branches|prs|all] [--force] [--age=DAYS]
+
+Options:
+  --dry-run     Show what would be cleaned without making changes
+  --category    Clean specific category only (default: all)
+  --force       Skip confirmation prompts (use with caution!)
+  --age=DAYS    Override stash age threshold (default: 7 days)
+```
+
+## Execution Steps
+
+### Step 1: Run Hygiene Check
+
+Gather current hygiene status:
+
+```bash
+python3 global/lib/hygiene_service.py --check --json
+```
+
+Parse the JSON output to get:
+- `old_stashes`: Stashes older than threshold
+- `orphan_branches`: Branches with deleted remotes
+- `stale_prs`: PRs for Done Linear issues
+- `conflict_prs`: PRs with merge conflicts
+
+### Step 2: Display Categorized Results
+
+Present findings in categorized tables:
+
+```markdown
+## Repository Cleanup
+
+### Old Stashes (5 items)
+
+| Index | Age | Branch | Message | Issue Refs |
+|-------|-----|--------|---------|------------|
+| stash@{0} | 14d | feature/ANV-50 | WIP: auth flow | ANV-50 |
+| stash@{2} | 10d | feature/ANV-45 | save before rebase | ANV-45 |
+...
+
+### Orphan Branches (3 items)
+
+| Branch | Last Commit | Tracking |
+|--------|-------------|----------|
+| feature/ANV-30-old | abc1234 | origin/feature/ANV-30-old: gone |
+...
+
+### Stale PRs (1 item)
+
+| PR | Title | Issue Status |
+|----|-------|--------------|
+| #55 | ANV-211: Linear cleanup | ANV-211: Done |
+...
+
+### PRs with Conflicts (1 item)
+
+| PR | Title | Conflicts |
+|----|-------|-----------|
+| #60 | ANV-220: Feature X | 3 files |
+...
+```
+
+If any category is empty, show "None found" for that category.
+
+### Step 3: Interactive Cleanup (per category)
+
+**For each category with items, use AskUserQuestion:**
+
+#### Stash Cleanup
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Stashes",
+    question: "5 stashes are older than 7 days. How would you like to handle them?",
+    multiSelect: false,
+    options: [
+      { label: "Drop all old stashes (Recommended)", description: "Remove all 5 old stashes permanently" },
+      { label: "Select individually", description: "Choose which stashes to drop" },
+      { label: "Skip", description: "Leave stashes unchanged" }
+    ]
+  }]
+})
+```
+
+If "Select individually" chosen, present each stash for confirmation.
+
+**Before dropping any stash, show its content preview:**
+```bash
+git stash show -p stash@{N} | head -50
+```
+
+**Drop stash:**
+```bash
+git stash drop stash@{N}
+```
+
+#### Branch Cleanup
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Branches",
+    question: "3 local branches have deleted remotes. Delete them?",
+    multiSelect: false,
+    options: [
+      { label: "Delete all orphan branches (Recommended)", description: "Remove branches: feature/ANV-30, feature/ANV-31, feature/ANV-32" },
+      { label: "Select individually", description: "Choose which branches to delete" },
+      { label: "Skip", description: "Keep all branches" }
+    ]
+  }]
+})
+```
+
+**Delete branch:**
+```bash
+git branch -D [branch-name]
+```
+
+#### Stale PR Cleanup
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Stale PRs",
+    question: "PR #55 is for issue ANV-211 which is already Done. Close it?",
+    multiSelect: false,
+    options: [
+      { label: "Close PR #55 (Recommended)", description: "Issue ANV-211 is Done, PR likely obsolete" },
+      { label: "View PR first", description: "Open PR in browser before deciding" },
+      { label: "Skip", description: "Leave PR open" }
+    ]
+  }]
+})
+```
+
+If "View PR first" chosen:
+```bash
+gh pr view 55 --web
+```
+
+**Close PR:**
+```bash
+gh pr close 55 --comment "Closing: linked issue ANV-211 is already Done."
+```
+
+#### Conflict PR Suggestions
+For PRs with conflicts, only provide suggestions (no automatic actions):
+
+```
+### PRs with Conflicts
+
+PR #60 has merge conflicts with main. Suggested actions:
+1. Rebase: `git checkout feature/ANV-220 && git rebase main`
+2. Close if obsolete: `gh pr close 60`
+
+These require manual intervention.
+```
+
+### Step 4: Execute Cleanup Actions
+
+For each confirmed action:
+1. Show the command being executed
+2. Execute the command
+3. Capture result (success/failure)
+4. Continue to next item
+
+```
+Executing cleanup...
+
+✅ Dropped stash@{0}: WIP: auth flow
+✅ Dropped stash@{2}: save before rebase
+✅ Deleted branch: feature/ANV-30-old
+✅ Closed PR #55
+
+⚠️ Failed to delete branch: feature/locked (branch is currently checked out)
+```
+
+### Step 5: Summary Report
+
+```
+## Cleanup Summary
+
+| Category | Cleaned | Skipped | Failed |
+|----------|---------|---------|--------|
+| Stashes | 5 | 2 | 0 |
+| Branches | 3 | 0 | 1 |
+| PRs | 1 | 0 | 0 |
+
+**Total items cleaned**: 9
+**Total items skipped**: 2
+**Total failures**: 1
+
+### Remaining Issues
+
+- Branch `feature/locked` could not be deleted (currently checked out)
+
+### New Hygiene Status
+
+| Check | Before | After |
+|-------|--------|-------|
+| Stashes | 7 | 2 |
+| Orphan branches | 3 | 1 |
+| Stale PRs | 1 | 0 |
+
+Run `/healthcheck` for full status.
+```
+
+## Dry Run Mode
+
+When `--dry-run` is specified:
+
+```
+## Cleanup Preview (Dry Run)
+
+The following actions WOULD be taken:
+
+### Stashes
+- Would drop stash@{0}: WIP: auth flow (14 days old)
+- Would drop stash@{2}: save before rebase (10 days old)
+
+### Branches
+- Would delete: feature/ANV-30-old
+- Would delete: feature/ANV-31-cleanup
+
+### PRs
+- Would close PR #55 (ANV-211 is Done)
+
+**No changes made.** Run without --dry-run to execute.
+```
+
+## Force Mode
+
+When `--force` is specified:
+1. Skip all AskUserQuestion prompts
+2. Show warning before proceeding
+3. Execute all cleanup actions automatically
+
+```
+⚠️ WARNING: --force mode enabled
+
+This will automatically:
+- Drop 5 old stashes
+- Delete 3 orphan branches
+- Close 1 stale PR
+
+Are you absolutely sure? This cannot be undone.
+[Require explicit "yes" confirmation even in force mode]
+```
+
+## Category Filtering
+
+When `--category=stashes` (or branches, prs):
+- Only run hygiene check for that category
+- Only show and offer cleanup for that category
+- Other categories are skipped entirely
+
+## Safety Measures
+
+1. **Never auto-delete without confirmation** (except --force)
+2. **Show stash content preview** before dropping
+3. **Prevent deletion of current branch**
+4. **Add comment when closing PRs** explaining why
+5. **Track failures** and report at end
+6. **No action on conflict PRs** (suggestions only)
+
+## Key Behaviors
+
+- Always require confirmation before destructive actions
+- Show clear before/after comparison
+- Report all failures with actionable messages
+- Provide dry-run mode for safe preview
+- Keep conflict PRs suggestions-only (manual intervention required)
+- Comment on PRs when closing to maintain audit trail
+
+## Integration Points
+
+- Uses: `global/lib/hygiene_service.py` for hygiene detection
+- Called from: `/healthcheck` recommendations, `/orient` warnings
+- Uses: Git for stash/branch operations
+- Uses: `gh` CLI for PR operations
+- Uses: AskUserQuestion for confirmations

package/global/commands/commit-push-pr.md

@@ -0,0 +1,207 @@
+# /commit-push-pr - Full Commit Workflow
+
+> Commit, push, and create PR in one command.
+
+## When to Use
+- When feature is complete and ready for review
+- For quick iteration on small changes
+- When you want the full workflow in one step
+
+## Why This Matters
+The manual workflow is error-prone:
+1. `git add .`
+2. `git commit -m "..."`
+3. `git push` (might fail)
+4. `gh pr create` (might forget)
+
+This command handles all steps atomically.
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `message` | Yes | Commit message (becomes PR title) |
+| `--draft` | No | Create as draft PR |
+| `--base` | No | Base branch (default: main) |
+
+## Prerequisites
+
+Before using this command:
+- [ ] `gh` CLI installed (`brew install gh`)
+- [ ] `gh` authenticated (`gh auth login`)
+- [ ] Remote repository configured
+- [ ] Git credentials available
+
+## Execution Steps
+
+### Step 1: Verify Preconditions
+```bash
+# Check we're in a git repo
+git rev-parse --git-dir > /dev/null 2>&1 || exit 1
+
+# Check gh is available
+command -v gh > /dev/null 2>&1 || { echo "Error: gh CLI not installed"; exit 1; }
+
+# Check there are changes to commit
+git diff --cached --quiet && git diff --quiet && echo "No changes to commit" && exit 0
+
+# Check we're not on main/master
+BRANCH=$(git branch --show-current)
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+    echo "Error: Cannot create PR from main branch"
+    echo "Create a feature branch first: git checkout -b feature/your-feature"
+    exit 1
+fi
+```
+
+### Step 2: Stage All Changes
+```bash
+git add .
+```
+
+### Step 3: Create Commit
+```bash
+git commit -m "[message]
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+```
+
+### Step 4: Push to Remote
+```bash
+# Try normal push first
+git push origin "$BRANCH" 2>/dev/null
+
+# If no upstream, set it
+if [ $? -ne 0 ]; then
+    git push -u origin "$BRANCH"
+fi
+```
+
+**If push fails** (rejected, conflicts):
+```
+❌ Push failed: [error message]
+
+Suggested fix:
+git pull --rebase origin main
+```
+- Stop execution
+
+### Step 5: Create Pull Request
+```bash
+gh pr create --title "[message]" --body "$(cat <<'EOF'
+## Summary
+[Auto-generated from commit message]
+
+## Changes
+[List of files changed]
+
+## Test Plan
+- [ ] Tests passing
+- [ ] Manual verification
+
+---
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+### Step 6: Report Success
+```
+✅ Committed: [message]
+   [hash] - [N] files changed
+✅ Pushed to origin/[branch]
+✅ PR created: [URL]
+```
+
+## Usage Examples
+
+### Basic Usage
+```
+/commit-push-pr "feat: add OAuth support"
+```
+
+### Draft PR
+```
+/commit-push-pr "wip: initial authentication flow" --draft
+```
+
+### Custom Base Branch
+```
+/commit-push-pr "fix: hotfix for production" --base release/v2.0
+```
+
+## Success Output
+```
+✅ Committed: feat: add OAuth support
+   abc1234 - 5 files changed, 234 insertions(+), 12 deletions(-)
+✅ Pushed to origin/feature/oauth
+✅ PR created: https://github.com/org/repo/pull/42
+```
+
+## Failure Outputs
+
+### No gh CLI
+```
+❌ Error: gh CLI not installed
+
+Install with: brew install gh
+Then authenticate: gh auth login
+```
+
+### On Main Branch
+```
+❌ Error: Cannot create PR from main branch
+
+Create a feature branch first:
+git checkout -b feature/your-feature
+```
+
+### Push Rejected
+```
+❌ Push failed: rejected (non-fast-forward)
+
+Suggested fix:
+git pull --rebase origin main
+git push origin feature/your-feature
+```
+
+### No Remote
+```
+❌ Push failed: No configured remote
+
+Add a remote first:
+git remote add origin https://github.com/org/repo.git
+```
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| Not a git repo | "Error: Not a git repository" |
+| No changes | "No changes to commit" |
+| No gh CLI | Install instructions |
+| On main branch | Create branch instructions |
+| Push rejected | Pull/rebase suggestion |
+| No remote | Add remote instructions |
+| PR creation fails | Show gh error, manual instructions |
+
+## Anti-Patterns
+- ❌ Pushing to protected branches directly
+- ❌ Creating PRs without tests passing (use `/test-and-commit` first)
+- ❌ Using force push
+- ❌ Creating PRs from main branch
+
+## Key Behaviors
+- **Atomic**: All steps succeed or provide clear rollback path
+- **Safe**: Never pushes to main/master directly
+- **Informative**: Shows commit hash, files changed, PR URL
+- **Conventional**: Uses conventional commit format
+- **Traceable**: Adds Claude Code attribution
+
+## Integration Points
+- Combine with: `/test-and-commit` for tested PRs
+- Alternative to: Manual git workflow
+- Follows: Feature development
+- Creates: GitHub Pull Request

package/global/commands/decay-review.md

@@ -0,0 +1,127 @@
+# /decay-review - Archive Old Work
+
+> Review and archive old issues and specs to keep context lean.
+
+## When to Use
+- Weekly maintenance (recommended: Friday)
+- When active issue count exceeds 50
+- When old specs clutter the current directory
+- Quarterly cleanup
+
+## Why Decay Management Matters
+Without cleanup:
+- Issue trackers accumulate cruft
+- Old specs pollute context
+- Signal-to-noise ratio degrades
+- "What's actually active?" becomes unclear
+
+Target: **<50 active issues** in Linear
+
+## Execution Steps
+
+### Step 1: Query Closed Issues
+
+Use the Linear CLI to find old closed issues:
+```bash
+# Get completed issues (will need to filter by date manually)
+python3 ~/.claude/skills/linear-skill/scripts/linear.py list-issues --status "Done" --limit 50
+```
+
+Filter results for issues where `updatedAt` is >30 days ago.
+
+### Step 2: Archive Candidates Review
+For each old closed issue:
+- Was it significant? (Keep summary)
+- Any learnings? (Capture in retrospective)
+- Related to active work? (Keep reference)
+
+### Step 3: Archive in Linear
+Move old issues to archive:
+- Mark as archived in Linear
+- Or move to "Archive" project
+
+### Step 4: Archive Old Specs
+Move completed specs:
+```bash
+# Move completed specs to archive
+mv .claude/specs/current/SPEC-*-completed.md .claude/specs/archive/
+
+# Or specs older than 90 days that are done
+find .claude/specs/current -name "*.md" -mtime +90 -exec grep -l "status: implemented" {} \;
+```
+
+### Step 5: Archive Old Handoffs
+Keep only last 7 handoffs:
+```bash
+# List handoffs older than 7 days
+find .claude/handoffs -name "*.md" -mtime +7 -type f
+
+# Archive old ones
+mkdir -p .claude/handoffs/archive
+mv .claude/handoffs/2024-*.md .claude/handoffs/archive/
+```
+
+### Step 6: Generate Decay Report
+
+Output:
+```markdown
+## Decay Review: [Date]
+
+### Linear Issues
+| Action | Count | Details |
+|--------|-------|---------|
+| Archived | 12 | Closed >30 days |
+| Kept | 3 | Still relevant |
+| Active | 34 | Current work |
+
+**Active issue count**: 34 (target: <50) ✅
+
+### Specifications
+| Action | Count |
+|--------|-------|
+| Archived | 5 |
+| Current | 8 |
+
+### Handoffs
+| Action | Count |
+|--------|-------|
+| Archived | 15 |
+| Kept | 7 |
+
+### Summary
+- Archived 12 issues, 5 specs, 15 handoffs
+- Context is now lean and current
+- Next decay review: [Date + 7 days]
+```
+
+## Archive vs Delete
+
+**Archive** (preserve but hide):
+- Completed features (might need reference)
+- Historical decisions
+- Significant milestones
+
+**Delete** (truly remove):
+- Duplicate issues
+- Abandoned experiments (with note)
+- Outdated drafts never implemented
+
+## Decay Schedule
+
+| Item | Review Frequency | Archive After |
+|------|-----------------|---------------|
+| Linear issues | Weekly | 30 days closed |
+| Specs | Monthly | 90 days implemented |
+| Handoffs | Weekly | 7 days |
+| Change docs | Monthly | 60 days implemented |
+
+## Key Behaviors
+- Regular cadence prevents buildup
+- Archive, don't delete (usually)
+- Capture learnings before archiving
+- Keep context lean for AI efficiency
+
+## Integration Points
+- Scheduled: Weekly (Friday recommended)
+- Affects: Linear, .claude/specs/, .claude/handoffs/
+- Follows: `/weekly-review` for full maintenance