anvil-dev-framework 0.1.6

package/global/commands/insights.md

@@ -0,0 +1,319 @@
+# /insights - Synthesize Recent Learnings
+
+> Deep analysis of retrospectives to identify patterns, root causes, and actionable improvements.
+
+## When to Use
+- Weekly (Monday morning suggested)
+- Before starting new similar work
+- When noticing repeated issues
+- After multiple sessions on complex features
+
+## Philosophy
+
+Shallow pattern detection creates false confidence. This command performs **deep analysis** to surface:
+- Frequency-ranked patterns (not just "mentioned 2+ times")
+- Root causes (not just symptoms)
+- Prioritized recommendations with implementation steps
+- Concrete actions ready for CLAUDE.md or Linear
+
+## Data Sources
+
+| Source | Path | Contains |
+|--------|------|----------|
+| Retrospectives | `.claude/retros/` | Session learnings, process insights |
+| Healthchecks | `.claude/healthchecks/` | Framework diagnostics, hook/tool metrics |
+| Handoffs | `.claude/handoffs/` | Session context, implicit learnings |
+
+---
+
+## Execution Steps
+
+### Step 1: Gather Recent Data
+
+Find retrospectives from the last 2 weeks:
+```bash
+find .claude/retros -name "*.md" -mtime -14 -type f
+```
+
+Find healthchecks from the last 2 weeks:
+```bash
+find .claude/healthchecks -name "*.md" -mtime -14 -type f
+```
+
+**If no retros exist**: Check handoffs for implicit learnings, or suggest running `/retro` first.
+
+### Step 2: Read Every Retro Fully
+
+Do NOT skim. For each retrospective:
+1. Read the entire "What Happened" narrative
+2. Extract the "Key Learning"
+3. Extract the "For Next Time" action
+4. Note any issues, blockers, or friction mentioned
+
+Create a working extraction table:
+
+| Retro | Key Learning | For Next Time | Issues Mentioned |
+|-------|--------------|---------------|------------------|
+| ANV-78 | Verify branch before read | Run git status at session start | Wrong branch, file mismatch |
+| ANV-67 | Diff after edits | Run git diff after modifications | Linter reverted changes |
+| ... | ... | ... | ... |
+
+### Step 3: Identify Patterns with Frequency Analysis
+
+Group similar issues and count occurrences:
+
+| Pattern | Occurrences | Retros | Severity |
+|---------|-------------|--------|----------|
+| Branch context issues | 6 | ANV-78, ANV-76, ANV-47, ANV-44/45, ANV-30 | CRITICAL |
+| Uncommitted work loss | 3 | ANV-67, ANV-30, ANV-44/45 | HIGH |
+| Multi-location confusion | 3 | ANV-47, TTS-fix, ANV-68 | MEDIUM |
+
+**Severity Rating**:
+- **CRITICAL** (5+ occurrences OR data loss/major rework)
+- **HIGH** (3-4 occurrences OR significant time waste)
+- **MEDIUM** (2 occurrences OR moderate friction)
+- **LOW** (1 occurrence, minor issue)
+
+### Step 4: Root Cause Analysis
+
+For each pattern with 2+ occurrences, identify the **systemic root cause** (not just the symptom):
+
+| Pattern (Symptom) | Root Cause | Why It Keeps Happening |
+|-------------------|------------|------------------------|
+| Reading wrong file version | Session compaction loses branch awareness | No automated verification at session resume |
+| Uncommitted work lost | No checkpoint commit discipline | Compaction happens unexpectedly |
+| Edited wrong file location | Dual-location pattern unclear | No pre-check of file locations |
+
+**Key distinction**:
+- Symptom: "I was on the wrong branch"
+- Root cause: "Session compaction removes branch context and there's no automated verification"
+
+### Step 5: Categorize by Type
+
+Group patterns into actionable categories:
+
+**Process Gaps** (behavioral/workflow issues)
+- Example: "No checkpoint commits before compaction"
+
+**Tooling Limitations** (tool behavior that causes friction)
+- Example: "Session compaction loses branch state"
+
+**Knowledge Gaps** (things that need to be learned/documented)
+- Example: "jq // operator treats false as falsey"
+
+**Codebase Issues** (code structure causing problems)
+- Example: "Dual-location hook pattern is confusing"
+
+**Positive Patterns** (successes to reinforce)
+- Example: "Service-first architecture made integration predictable"
+
+### Step 6: Create Implementation Recommendations
+
+For each pattern, propose a **specific fix** with effort estimate:
+
+| Priority | Pattern | Recommended Fix | Effort | Type |
+|----------|---------|-----------------|--------|------|
+| P1 | Branch context | Add `git branch --show-current` check to /orient, add anti-pattern | Low | Documentation |
+| P2 | Uncommitted work | Add "30-minute commit reminder" anti-pattern | Low | Documentation |
+| P2 | Post-edit verification | Add `git diff` verification step after edits | Low | Behavioral |
+| P3 | Branch logging | Enhance pre_tool_use hook to log branch on Read | Medium | Code change |
+
+**Effort Estimates**:
+- **Low**: Documentation or behavioral change only
+- **Medium**: Small code change or new script
+- **High**: Significant implementation work
+
+**Priority Formula**: Impact x Frequency / Effort
+- P1: CRITICAL patterns or HIGH with low effort
+- P2: HIGH patterns or MEDIUM with low effort
+- P3: MEDIUM patterns or anything requiring significant effort
+
+### Step 7: Check Framework Health (if healthchecks exist)
+
+From healthcheck files, extract:
+- Hook success rates
+- Tool invocation patterns
+- Safety rule triggers
+- Any errors or warnings
+
+Note any framework issues that correlate with retro patterns.
+
+---
+
+## Output Format
+
+Generate a comprehensive report with ALL of the following sections:
+
+```markdown
+## Insights Report: [Date Range]
+
+### Executive Summary
+
+**Analyzed**: [X] retrospectives, [Y] healthchecks from [date range]
+**Critical Patterns**: [count]
+**High Patterns**: [count]
+**Recommended Actions**: [count]
+
+### Pattern Analysis
+
+#### Category 1: [Pattern Name] ([X] occurrences) - [SEVERITY]
+
+| Retro | Issue Description |
+|-------|-------------------|
+| [ID] | [What happened] |
+| [ID] | [What happened] |
+
+**Root Cause**: [Systemic cause, not symptom]
+
+**Impact**: [Time wasted, data lost, rework required]
+
+---
+
+#### Category 2: [Pattern Name] ([X] occurrences) - [SEVERITY]
+[Same structure]
+
+---
+
+### Positive Patterns (Reinforce These)
+
+| Pattern | Evidence | Why It Works |
+|---------|----------|--------------|
+| [Pattern] | [Retros] | [Explanation] |
+
+---
+
+### Framework Health
+
+**Status**: [Healthy / Warning / Issues]
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Hook success rate | X% | [OK/Warning] |
+| Safety blocks | X | [OK/Warning] |
+| Tool errors | X | [OK/Warning] |
+
+[Any correlations between framework issues and retro patterns]
+
+---
+
+### Recommended Actions
+
+#### Priority 1 (Do Now)
+
+**1. [Action Name]**
+- **Pattern**: [Which pattern this fixes]
+- **Fix**: [Specific implementation]
+- **Effort**: [Low/Medium/High]
+- **Implementation**:
+  ```
+  [Specific commands, file edits, or steps]
+  ```
+
+#### Priority 2 (This Week)
+
+**2. [Action Name]**
+[Same structure]
+
+#### Priority 3 (Backlog)
+
+**3. [Action Name]**
+[Same structure]
+
+---
+
+### CLAUDE.md Patch
+
+**New Anti-Patterns to Add**:
+
+| Anti-Pattern | Check |
+|--------------|-------|
+| [Pattern] | [Verification question] |
+
+**New Learned Patterns to Add**:
+
+| Pattern | Evidence | Added |
+|---------|----------|-------|
+| [Name] | [Retro IDs] | [Today] |
+
+---
+
+### Suggested Linear Issues
+
+For patterns requiring code changes:
+
+| Title | Description | Priority | Estimate |
+|-------|-------------|----------|----------|
+| [Issue title] | [Brief description] | P[X] | [X]h |
+
+---
+
+### No Action Needed
+
+- [Observation that's interesting but one-off or not actionable]
+```
+
+---
+
+## Post-Report Actions
+
+After generating the report, offer:
+
+1. **"apply patch"** - Update CLAUDE.md with new patterns and anti-patterns
+2. **"create issues"** - Create Linear issues for code-change recommendations
+3. **"save report"** - Save to `.claude/insights/YYYY-MM-DD.md`
+
+---
+
+## Key Behaviors
+
+- **Read every retro fully** - do not skim for keywords
+- **Count frequencies** - patterns with 6 occurrences are more urgent than 2
+- **Identify root causes** - "wrong branch" is a symptom, "compaction loses context" is the cause
+- **Be specific** - include file paths, commands, implementation steps
+- **Prioritize by impact** - not all patterns are equally important
+- **Include positive patterns** - reinforce what is working
+
+## Anti-Patterns to Avoid
+
+- One-liner pattern summaries without evidence
+- Vague recommendations ("be more careful")
+- Missing frequency counts
+- Confusing symptoms with root causes
+- Equal treatment of all patterns regardless of severity
+- Skipping implementation details
+
+## What This Command Does NOT Do
+
+- Replace writing individual retros (that is `/retro`)
+- Automatically apply changes without confirmation
+- Create issues without user approval
+- Analyze code (that is `/explore`)
+
+## Integration Points
+
+- **Reads**: `.claude/retros/`, `.claude/healthchecks/`, `.claude/handoffs/`
+- **Modifies**: `CLAUDE.md` (when "apply patch" requested)
+- **Creates**: Linear issues (when "create issues" requested)
+- **Saves**: `.claude/insights/` (when "save report" requested)
+
+## Handling Edge Cases
+
+| Scenario | Action |
+|----------|--------|
+| No retros in date range | Expand to 30 days, or suggest `/retro` |
+| Only 1-2 retros | Still analyze, note limited data |
+| No patterns found | Report "no recurring patterns" with individual learnings |
+| All patterns are positive | Focus on reinforcement, no fixes needed |
+| Conflicting learnings | Note the conflict, ask for clarification |
+
+---
+
+## Quick Mode (Optional)
+
+If user runs `/insights --quick`:
+- Skip root cause analysis
+- Skip implementation details
+- Output summary table only
+- Suggest full analysis if patterns detected
+
+Default behavior is **full deep analysis**.

package/global/commands/linear-setup.md

@@ -0,0 +1,184 @@
+---
+description: Configure Linear integration for this project
+arguments: []
+---
+
+# Linear Setup
+
+Configure which Linear team this local project maps to.
+
+## Overview
+
+This command establishes the connection between your local project directory and a Linear team. Once configured, all Anvil commands (`/orient`, `/sprint`, `/tasks`, etc.) will only show issues from the configured team.
+
+### Linear Team Structure
+
+Linear supports hierarchical team structures:
+
+```
+Workspace
+├── Parent Team (optional) ← Cross-cutting work, unified view
+│   ├── Sub-Team A ← Project/product 1
+│   └── Sub-Team B ← Project/product 2
+└── Standalone Team ← Independent project
+```
+
+**Recommendation**: 
+- One team (or sub-team) per product/project
+- Use parent teams for unified backlog view across projects
+- Each local project directory should map to one specific team
+
+## Pre-Flight Check
+
+First, verify Linear MCP is available:
+
+```bash
+# Check if Linear MCP is configured
+claude mcp list | grep -i linear || echo "Linear MCP not found"
+```
+
+## Step 1: Check Current Configuration
+
+```bash
+# Check if linear.yaml exists
+if [ -f ".claude/linear.yaml" ]; then
+    echo "Current Linear configuration:"
+    cat .claude/linear.yaml
+else
+    echo "No Linear configuration found for this project."
+fi
+```
+
+## Step 2: List Available Teams
+
+Query Linear for available teams. Present them in a selection format:
+
+**Action**: Use Linear MCP to list teams
+
+```
+List all Linear teams I have access to. Show:
+- Team name
+- Team key (e.g., "ENG", "PROD", "API")
+- Whether it's a sub-team (and parent name)
+- Number of active issues
+```
+
+Present as numbered list for selection:
+```
+Available Linear Teams:
+1. Engineering (ENG) - 23 active issues
+2. Product (PROD) - 5 active issues [sub-team of Platform]
+3. API Team (API) - 12 active issues [sub-team of Platform]
+
+Enter number to select, or 'new' to create a new team:
+```
+
+## Step 3: Team Selection
+
+Based on user selection:
+
+### If existing team selected:
+1. Get team details (key, ID)
+2. Ask if they want to filter to a specific project within that team
+3. If yes, list projects in that team and let them select
+
+### If 'new' selected:
+1. Ask for team name
+2. Ask for team key (2-4 uppercase letters)
+3. Ask if this should be a sub-team of an existing team
+4. Create the team in Linear
+5. Confirm creation
+
+## Step 4: Save Configuration
+
+Write the configuration to `.claude/linear.yaml`:
+
+```yaml
+# Linear Integration Configuration
+# Generated by /linear-setup on [DATE]
+
+team_key: "ENG"
+team_name: "Engineering"
+team_id: "uuid-here"
+project_name: ""  # Empty = all team issues
+project_id: ""
+issue_prefix: "ENG"
+```
+
+## Step 5: Verification
+
+After saving, verify the configuration works:
+
+```
+Verifying Linear configuration...
+
+✓ Team found: Engineering (ENG)
+✓ Issue prefix: ENG-
+✓ Active issues in team: 5
+
+Configuration saved to .claude/linear.yaml
+
+Next steps:
+- Run /orient to see issues from this team
+- Run /sprint to plan work
+- Issues created will use prefix: ENG-XXX
+```
+
+## Troubleshooting
+
+### "No teams found"
+- Check Linear MCP is properly configured
+- Verify you have access to at least one Linear workspace
+
+### "Team key already exists"
+- Each team key must be unique in your Linear workspace
+- Choose a different key or use the existing team
+
+### "Permission denied"
+- You may not have permission to create teams
+- Contact your Linear workspace admin
+
+## Configuration Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `team_key` | Yes | 2-4 letter team identifier (e.g., "ENG") |
+| `team_name` | Yes | Human-readable team name |
+| `team_id` | Yes | Linear UUID for the team |
+| `project_name` | No | Filter to specific Linear project |
+| `project_id` | No | Linear UUID for the project |
+| `issue_prefix` | Yes | Prefix for issue IDs (usually = team_key) |
+
+## Manual Configuration
+
+If you prefer to configure manually:
+
+1. Go to Linear → Settings → Teams
+2. Find or create your team
+3. Copy the team key and ID
+4. Create `.claude/linear.yaml`:
+
+```yaml
+team_key: "YOUR_KEY"
+team_name: "Your Team Name"
+team_id: "your-team-uuid"
+project_name: ""
+project_id: ""
+issue_prefix: "YOUR_KEY"
+```
+
+## Multi-Project Setup
+
+If you have multiple local projects mapping to different Linear teams:
+
+```
+~/projects/
+├── frontend-app/
+│   └── .claude/linear.yaml  → team_key: "FE"
+├── backend-api/
+│   └── .claude/linear.yaml  → team_key: "BE"
+└── shared-lib/
+    └── .claude/linear.yaml  → team_key: "CORE"
+```
+
+Each project's `/orient`, `/sprint`, `/tasks` commands will only show issues from its configured team.

package/global/commands/lint-fix.md

@@ -0,0 +1,198 @@
+# /lint-fix - Auto-Fix Lint Issues
+
+> Run linter with auto-fix enabled.
+
+## When to Use
+- Before committing to clean up code style
+- After large refactors
+- When lint errors are blocking CI
+- To quickly fix formatting issues
+
+## Why This Matters
+Manual lint fixing is tedious and error-prone:
+- Easy to miss issues
+- Inconsistent formatting
+- Time wasted on style debates
+
+Auto-fix handles the mechanical work, leaving only semantic issues for human review.
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `path` | No | Specific path to fix (default: all files) |
+
+## Execution Steps
+
+### Step 1: Detect Linter
+
+Detect the project's linter configuration:
+```bash
+# Check for linter config files
+if [ -f ".eslintrc.js" ] || [ -f ".eslintrc.json" ] || [ -f "eslint.config.js" ]; then
+    LINTER="eslint"
+elif [ -f "biome.json" ]; then
+    LINTER="biome"
+elif [ -f "ruff.toml" ] || [ -f "pyproject.toml" ]; then
+    LINTER="ruff"
+elif [ -f ".prettierrc" ] || [ -f "prettier.config.js" ]; then
+    LINTER="prettier"
+else
+    echo "No linter configuration detected"
+    exit 1
+fi
+```
+
+### Step 2: Run Linter with Fix
+
+Execute the appropriate fix command:
+
+| Linter | Command |
+|--------|---------|
+| ESLint | `npx eslint --fix [path]` |
+| Prettier | `npx prettier --write [path]` |
+| Biome | `npx biome check --apply [path]` |
+| Ruff | `ruff check --fix [path]` |
+| Black | `black [path]` |
+| gofmt | `gofmt -w [path]` |
+| rustfmt | `cargo fmt` |
+
+### Step 3: Capture Results
+
+Parse linter output to identify:
+- Number of issues fixed
+- Types of fixes applied
+- Remaining unfixable issues
+
+### Step 4: Stage Fixed Files
+```bash
+git add .
+```
+
+### Step 5: Report Results
+
+**If all issues fixed**:
+```
+✅ Lint auto-fix complete
+
+Fixed 12 issues:
+- 5 formatting issues
+- 4 import order issues
+- 3 unused import removals
+
+All issues resolved. Changes staged for commit.
+```
+
+**If some issues remain**:
+```
+✅ Lint auto-fix complete
+
+Fixed 8 issues:
+- 3 formatting issues
+- 5 import order issues
+
+⚠️ Remaining (manual fix required):
+- src/utils/api.ts:45 - 'x' is defined but never used
+- src/utils/api.ts:67 - Unexpected 'any' type
+
+Changes staged for commit.
+```
+
+## Usage Examples
+
+### Fix All Files
+```
+/lint-fix
+```
+
+### Fix Specific Directory
+```
+/lint-fix src/components/
+```
+
+### Fix Single File
+```
+/lint-fix src/utils/api.ts
+```
+
+## Success Output (All Fixed)
+```
+✅ Lint auto-fix complete
+
+Fixed 12 issues:
+- 5 formatting issues
+- 4 import order issues
+- 3 unused import removals
+
+All issues resolved. Changes staged for commit.
+```
+
+## Partial Success Output
+```
+✅ Lint auto-fix complete
+
+Fixed 8 issues:
+- 3 formatting issues
+- 5 import order issues
+
+⚠️ Remaining (manual fix required):
+- src/utils/api.ts:45 - 'x' is defined but never used (no-unused-vars)
+- src/components/Form.tsx:23 - Missing return type (explicit-function-return-type)
+
+Changes staged for commit. Address remaining issues manually.
+```
+
+## Failure Output
+```
+❌ Lint auto-fix failed
+
+No linter configuration detected.
+
+Supported linters:
+- ESLint (.eslintrc.js, eslint.config.js)
+- Prettier (.prettierrc)
+- Biome (biome.json)
+- Ruff (ruff.toml, pyproject.toml)
+
+Add a linter configuration to use this command.
+```
+
+## Supported Linters
+
+| Language | Linter | Fix Flag |
+|----------|--------|----------|
+| JavaScript/TypeScript | ESLint | `--fix` |
+| JavaScript/TypeScript | Prettier | `--write` |
+| JavaScript/TypeScript | Biome | `--apply` |
+| Python | Ruff | `--fix` |
+| Python | Black | (default) |
+| Go | gofmt | `-w` |
+| Rust | rustfmt | (default) |
+| Shell | shfmt | `-w` |
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| No linter config | List supported linters |
+| Linter not installed | Installation instructions |
+| Parse error | Show file and line |
+| No files to fix | "No matching files found" |
+
+## Anti-Patterns
+- ❌ Running lint-fix without reviewing changes
+- ❌ Ignoring remaining unfixable issues
+- ❌ Committing without verifying auto-fixes are correct
+
+## Key Behaviors
+- **Automatic**: Detects linter from project config
+- **Safe**: Only fixes auto-fixable issues
+- **Staged**: Changes are staged but not committed
+- **Transparent**: Shows what was fixed and what remains
+- **Composable**: Use with `/test-and-commit` for full workflow
+
+## Integration Points
+- Use before: `/test-and-commit` to ensure clean code
+- Combine with: `/commit-push-pr` for full workflow
+- Alternative to: Manual `npm run lint -- --fix`
+- Triggers: After code changes, before commits