anvil-dev-framework 0.1.6

package/global/commands/anvil-settings.md

@@ -0,0 +1,527 @@
+# /anvil-settings - Framework Configuration
+
+> Manage Anvil framework settings for the current project.
+
+## When to Use
+- Configure auto-trigger behavior (auto-retro, auto-healthcheck)
+- Configure statusline display (full, minimal, or off)
+- Configure code review integration
+- View current framework settings
+- Reset settings to defaults
+
+## Usage
+
+```bash
+# View all settings
+/anvil-settings
+
+# Toggle a boolean setting
+/anvil-settings <setting> <on|off>
+
+# Set statusline variant
+/anvil-settings statusline <full|minimal|off>
+
+# Configure code review
+/anvil-settings codeReview <on|off>
+/anvil-settings codeReview.enforcement <soft|hard>
+
+# Reset to defaults
+/anvil-settings reset
+```
+
+## Available Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `autoRetro` | `off` | Prompt for `/retro` at session end |
+| `autoHealthcheck` | `off` | Run `/healthcheck` at session end |
+| `statusline` | `full` | Statusline display variant (`full`, `minimal`, `off`) |
+| `codeReview` | `off` | Enable code review integration |
+| `codeReview.tool` | `coderabbit` | Code review tool to use |
+| `codeReview.enforcement` | `soft` | Enforcement level (`soft` = prompt, `hard` = block) |
+| `hud` | `on` | Enable HUD features (agent registry, dashboard) |
+| `hud.mode` | `sidebar` | HUD mode (`sidebar` for TUI, `statusline-only` for minimal) |
+| `hud.showAgentCount` | `on` | Show agent count in statusline |
+| `hud.refreshRate` | `2000` | Dashboard refresh rate in milliseconds |
+| `hud.staleTimeout` | `30` | Minutes before stale agent cleanup |
+
+### Statusline Variants
+
+| Variant | Description |
+|---------|-------------|
+| `full` | Complete context: model, context%, dir, branch, issue, phase, cost |
+| `minimal` | Compact display: model, issue, phase only |
+| `off` | Disable statusline entirely |
+
+### Code Review Enforcement Levels
+
+| Level | Behavior |
+|-------|----------|
+| `soft` | Prompts user during `/evidence` but allows continuation |
+| `hard` | Blocks PR creation until code review is completed |
+
+### Code Review Tools
+
+The `codeReview.tool` setting determines which tool to use:
+- `coderabbit` — AI-powered code review via CodeRabbit
+- Custom tools can be configured via `codeReview.command`
+
+### HUD Modes
+
+| Mode | Description |
+|------|-------------|
+| `sidebar` | Full TUI dashboard via `anvil-hud` command |
+| `statusline-only` | Just show agent count in statusline, no TUI |
+
+## Execution Steps
+
+### Display Mode (no arguments)
+
+When user runs `/anvil-settings` with no arguments:
+
+1. **Read Config File**
+   ```bash
+   # Config location
+   cat .claude/anvil.config.json
+   ```
+
+2. **Display Settings Table**
+   ```markdown
+   ## Anvil Settings
+
+   | Setting | Value | Description |
+   |---------|-------|-------------|
+   | autoRetro | off | Prompt for /retro at session end |
+   | autoHealthcheck | off | Run /healthcheck at session end |
+   | statusline | full | Statusline display variant |
+   | codeReview | off | Code review integration |
+   | codeReview.enforcement | soft | Enforcement level |
+
+   **Config file**: `.claude/anvil.config.json`
+
+   Usage:
+   - `/anvil-settings autoRetro on` - Enable auto-retro prompts
+   - `/anvil-settings statusline minimal` - Use compact statusline
+   - `/anvil-settings codeReview on` - Enable code review
+   - `/anvil-settings reset` - Reset all settings to defaults
+   ```
+
+3. **Handle Missing Config**
+   If config file doesn't exist, create with defaults:
+   ```json
+   {
+     "version": "1.2",
+     "autoRetro": false,
+     "autoHealthcheck": false,
+     "statusline": {
+       "enabled": true,
+       "variant": "full"
+     },
+     "codeReview": {
+       "enabled": false,
+       "tool": "coderabbit",
+       "command": "coderabbit --prompt-only",
+       "enforcement": "soft"
+     },
+     "hud": {
+       "enabled": true,
+       "mode": "sidebar",
+       "showAgentCount": true,
+       "refreshRate": 2000,
+       "staleTimeout": 30
+     }
+   }
+   ```
+
+### Toggle Mode (`/anvil-settings <setting> <value>`)
+
+1. **Validate Setting Name**
+   Valid settings: `autoRetro`, `autoHealthcheck`, `statusline`, `codeReview`, `codeReview.enforcement`
+
+   If invalid:
+   ```markdown
+   **Error**: Unknown setting `<name>`
+
+   Valid settings:
+   - `autoRetro` - Prompt for /retro at session end
+   - `autoHealthcheck` - Run /healthcheck at session end
+   - `statusline` - Statusline variant (full/minimal/off)
+   - `codeReview` - Code review integration (on/off)
+   - `codeReview.enforcement` - Enforcement level (soft/hard)
+   ```
+
+2. **Validate Value**
+
+   For boolean settings (`autoRetro`, `autoHealthcheck`):
+   - Valid values: `on`, `off`, `true`, `false`, `1`, `0`
+   - Normalize: `on`, `true`, `1` → `true`; `off`, `false`, `0` → `false`
+
+   For `statusline`:
+   - Valid values: `full`, `minimal`, `off`
+   - `off` sets `statusline.enabled: false`
+   - `full`/`minimal` sets `statusline.enabled: true` and `statusline.variant`
+
+   For `codeReview`:
+   - Valid values: `on`, `off`
+   - `on` sets `codeReview.enabled: true`
+   - `off` sets `codeReview.enabled: false`
+
+   For `codeReview.enforcement`:
+   - Valid values: `soft`, `hard`
+   - `soft` = prompts but allows continuation
+   - `hard` = blocks until code review completed
+
+3. **Update Config**
+   Read existing config, update setting, write back.
+
+4. **Confirm Change**
+   ```markdown
+   ✅ Updated `autoRetro` → **on**
+
+   Current settings:
+   | Setting | Value |
+   |---------|-------|
+   | autoRetro | on |
+   | autoHealthcheck | off |
+   | statusline | full |
+   | codeReview | off |
+   | codeReview.enforcement | soft |
+   ```
+
+### Reset Mode (`/anvil-settings reset`)
+
+1. **Confirm Reset**
+   ```markdown
+   Resetting all settings to defaults...
+   ```
+
+2. **Write Default Config**
+   ```json
+   {
+     "version": "1.2",
+     "autoRetro": false,
+     "autoHealthcheck": false,
+     "statusline": {
+       "enabled": true,
+       "variant": "full"
+     },
+     "codeReview": {
+       "enabled": false,
+       "tool": "coderabbit",
+       "command": "coderabbit --prompt-only",
+       "enforcement": "soft"
+     },
+     "hud": {
+       "enabled": true,
+       "mode": "sidebar",
+       "showAgentCount": true,
+       "refreshRate": 2000,
+       "staleTimeout": 30
+     }
+   }
+   ```
+
+3. **Confirm**
+   ```markdown
+   ✅ Settings reset to defaults
+
+   | Setting | Value |
+   |---------|-------|
+   | autoRetro | off |
+   | autoHealthcheck | off |
+   | statusline | full |
+   | codeReview | off |
+   | codeReview.enforcement | soft |
+   ```
+
+## Config File Schema
+
+**Location**: `.claude/anvil.config.json`
+
+```json
+{
+  "version": "1.2",
+  "autoRetro": false,
+  "autoHealthcheck": false,
+  "statusline": {
+    "enabled": true,
+    "variant": "full"
+  },
+  "codeReview": {
+    "enabled": false,
+    "tool": "coderabbit",
+    "command": "coderabbit --prompt-only",
+    "enforcement": "soft"
+  },
+  "hud": {
+    "enabled": true,
+    "mode": "sidebar",
+    "showAgentCount": true,
+    "refreshRate": 2000,
+    "staleTimeout": 30
+  }
+}
+```
+
+### Schema Details
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `version` | string | `"1.2"` | Config schema version |
+| `autoRetro` | boolean | `false` | Enable auto-retro prompt at session end |
+| `autoHealthcheck` | boolean | `false` | Enable auto-healthcheck at session end |
+| `statusline.enabled` | boolean | `true` | Enable/disable statusline display |
+| `statusline.variant` | string | `"full"` | Display variant: `full`, `minimal` |
+| `codeReview.enabled` | boolean | `false` | Enable code review integration |
+| `codeReview.tool` | string | `"coderabbit"` | Code review tool name |
+| `codeReview.command` | string | `"coderabbit --prompt-only"` | Command to run for code review |
+| `codeReview.enforcement` | string | `"soft"` | Enforcement level: `soft`, `hard` |
+| `hud.enabled` | boolean | `true` | Enable/disable HUD features |
+| `hud.mode` | string | `"sidebar"` | HUD mode: `sidebar`, `statusline-only` |
+| `hud.showAgentCount` | boolean | `true` | Show agent count in statusline |
+| `hud.refreshRate` | number | `2000` | Dashboard refresh rate in ms |
+| `hud.staleTimeout` | number | `30` | Minutes before stale agent cleanup |
+
+## Integration with Hooks
+
+### Stop Hook
+When settings are enabled, the stop hook (`hooks/stop.py`) reads this config and:
+
+- **autoRetro: true** → Outputs reminder to run `/retro`
+- **autoHealthcheck: true** → Outputs reminder to run `/healthcheck`
+
+### Statusline Hook
+The statusline hook (`hooks/statusline.sh`) reads this config to determine display:
+
+- **statusline.enabled: false** → Statusline is completely disabled
+- **statusline.variant: "full"** → Shows model, context%, dir, branch, issue, phase, cost
+- **statusline.variant: "minimal"** → Shows only model, issue, phase
+
+### HUD Integration
+The HUD system uses this config across multiple hooks:
+
+- **Session Start** (`hooks/session_start.py --register-agent`)
+  - If `hud.enabled: true`, registers agent in `~/.anvil/agents.json`
+
+- **Post Tool Use** (`hooks/post_tool_use.py --update-agent`)
+  - If `hud.enabled: true`, updates agent context/cost in registry
+
+- **Stop** (`hooks/stop.py --cleanup-agent`)
+  - If `hud.enabled: true`, deregisters agent from registry
+
+- **Statusline** (`hooks/statusline.sh`)
+  - If `hud.showAgentCount: true`, shows "👥 N agents" when multiple active
+
+- **anvil-hud** TUI dashboard
+  - Uses `hud.refreshRate` for polling interval
+  - Uses `hud.staleTimeout` for automatic cleanup
+
+## Integration with /evidence
+
+When `codeReview.enabled: true`, the `/evidence` command includes Step 5: Code Review:
+
+- **enforcement: "soft"** → Prompts user to confirm code review status, allows skip
+- **enforcement: "hard"** → Blocks PR creation until code review is completed
+
+The `/evidence` command reads `codeReview.command` to determine which tool to run or suggest.
+
+## Examples
+
+### View Settings
+```
+User: /anvil-settings
+
+Claude: ## Anvil Settings
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| autoRetro | off | Prompt for /retro at session end |
+| autoHealthcheck | off | Run /healthcheck at session end |
+| statusline | full | Statusline display variant |
+| codeReview | off | Code review integration |
+| codeReview.enforcement | soft | Enforcement level |
+
+**Config file**: `.claude/anvil.config.json`
+```
+
+### Enable Auto-Retro
+```
+User: /anvil-settings autoRetro on
+
+Claude: ✅ Updated `autoRetro` → **on**
+
+Current settings:
+| Setting | Value |
+|---------|-------|
+| autoRetro | on |
+| autoHealthcheck | off |
+| statusline | full |
+```
+
+### Set Statusline to Minimal
+```
+User: /anvil-settings statusline minimal
+
+Claude: ✅ Updated `statusline` → **minimal**
+
+Current settings:
+| Setting | Value |
+|---------|-------|
+| autoRetro | off |
+| autoHealthcheck | off |
+| statusline | minimal |
+```
+
+### Disable Statusline
+```
+User: /anvil-settings statusline off
+
+Claude: ✅ Updated `statusline` → **off**
+
+Current settings:
+| Setting | Value |
+|---------|-------|
+| autoRetro | off |
+| autoHealthcheck | off |
+| statusline | off |
+```
+
+### Reset Settings
+```
+User: /anvil-settings reset
+
+Claude: ✅ Settings reset to defaults
+
+| Setting | Value |
+|---------|-------|
+| autoRetro | off |
+| autoHealthcheck | off |
+| statusline | full |
+| codeReview | off |
+| codeReview.enforcement | soft |
+```
+
+### Enable Code Review
+```
+User: /anvil-settings codeReview on
+
+Claude: ✅ Updated `codeReview` → **on**
+
+Current settings:
+| Setting | Value |
+|---------|-------|
+| autoRetro | off |
+| autoHealthcheck | off |
+| statusline | full |
+| codeReview | on |
+| codeReview.enforcement | soft |
+```
+
+### Set Code Review Enforcement to Hard
+```
+User: /anvil-settings codeReview.enforcement hard
+
+Claude: ✅ Updated `codeReview.enforcement` → **hard**
+
+Current settings:
+| Setting | Value |
+|---------|-------|
+| autoRetro | off |
+| autoHealthcheck | off |
+| statusline | full |
+| codeReview | on |
+| codeReview.enforcement | hard |
+```
+
+### Enable HUD
+```
+User: /anvil-settings hud on
+
+Claude: ✅ Updated `hud` → **on**
+
+Current settings:
+| Setting | Value |
+|---------|-------|
+| autoRetro | off |
+| autoHealthcheck | off |
+| statusline | full |
+| codeReview | off |
+| hud | on |
+| hud.showAgentCount | on |
+```
+
+### Disable Agent Count in Statusline
+```
+User: /anvil-settings hud.showAgentCount off
+
+Claude: ✅ Updated `hud.showAgentCount` → **off**
+
+The statusline will no longer show "👥 N agents" when multiple agents are active.
+```
+
+### Set HUD Mode to Statusline-Only
+```
+User: /anvil-settings hud.mode statusline-only
+
+Claude: ✅ Updated `hud.mode` → **statusline-only**
+
+HUD will only show agent count in statusline. Run `anvil-hud` for full dashboard.
+```
+
+### Invalid Setting
+```
+User: /anvil-settings verbose on
+
+Claude: **Error**: Unknown setting `verbose`
+
+Valid settings:
+- `autoRetro` - Prompt for /retro at session end
+- `autoHealthcheck` - Run /healthcheck at session end
+- `statusline` - Statusline variant (full/minimal/off)
+- `codeReview` - Code review integration (on/off)
+- `codeReview.enforcement` - Enforcement level (soft/hard)
+- `hud` - HUD features (on/off)
+- `hud.mode` - HUD mode (sidebar/statusline-only)
+- `hud.showAgentCount` - Show agent count in statusline (on/off)
+```
+
+### Invalid Statusline Variant
+```
+User: /anvil-settings statusline compact
+
+Claude: **Error**: Invalid statusline variant `compact`
+
+Valid variants:
+- `full` - Complete context display
+- `minimal` - Compact display (model, issue, phase only)
+- `off` - Disable statusline
+```
+
+### Invalid Code Review Enforcement
+```
+User: /anvil-settings codeReview.enforcement strict
+
+Claude: **Error**: Invalid enforcement level `strict`
+
+Valid enforcement levels:
+- `soft` - Prompts but allows continuation
+- `hard` - Blocks until code review completed
+```
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| Invalid setting name | Show valid options |
+| Invalid value for boolean setting | Show valid values (on/off) |
+| Invalid statusline variant | Show valid variants (full/minimal/off) |
+| Invalid enforcement level | Show valid levels (soft/hard) |
+| Corrupted config | Reset to defaults, warn user |
+| Permission denied | Show error, suggest fix |
+
+## Related Commands
+
+- `/healthcheck` - Manual framework diagnostics
+- `/retro` - Manual retrospective
+- `/validate` - Environment validation
+- `/evidence` - Quality gate checks (uses codeReview settings)

package/global/commands/anvil-sync.md

@@ -0,0 +1,121 @@
+---
+description: Sync Anvil framework updates to this project or global config
+arguments:
+  - name: target
+    description: "Where to sync: 'project' (default), 'global', or 'both'"
+    default: "project"
+  - name: force
+    description: "Overwrite protected files (CLAUDE.md, product.md, etc.)"
+    default: "false"
+  - name: dry-run
+    description: "Preview changes without applying"
+    default: "false"
+---
+
+# Anvil Sync
+
+Sync the latest Anvil framework updates to this project and/or global config.
+
+## What Gets Synced
+
+### Always Updated (framework functionality)
+- `hooks/` - All hook scripts (session_start, stop, notification, etc.)
+- `examples/` - Reference implementation templates
+- `agents/` - Sub-agent definitions
+- `retros/templates/` - Retrospective templates
+- `commands/` - Slash commands from global config
+
+### Protected Files (not overwritten without --force)
+- `CLAUDE.md` - Project-specific AI instructions
+- `product.md` - Product definition
+- `constitution.md` - Project principles
+- `settings.local.json` - Local permissions and hook config
+
+## Execution
+
+<thinking>
+1. Determine Anvil source directory
+2. Determine sync target(s)
+3. Run sync with appropriate flags
+4. Report what was updated
+</thinking>
+
+### Step 1: Locate Anvil Framework
+
+```bash
+# Check common locations
+ANVIL_DIR=""
+if [ -d "$HOME/Projects/anvil-dev-framework" ]; then
+    ANVIL_DIR="$HOME/Projects/anvil-dev-framework"
+elif [ -n "$ANVIL_HOME" ]; then
+    ANVIL_DIR="$ANVIL_HOME"
+fi
+
+if [ -z "$ANVIL_DIR" ]; then
+    echo "ERROR: Could not find anvil-dev-framework"
+    echo "Set ANVIL_HOME or ensure it's in ~/Projects/"
+    exit 1
+fi
+
+echo "Anvil source: $ANVIL_DIR"
+echo "Current version: $(cat $ANVIL_DIR/VERSION)"
+```
+
+### Step 2: Build Sync Command
+
+```bash
+SYNC_CMD="$ANVIL_DIR/scripts/sync.sh"
+
+# Add target flag
+TARGET="${target:-project}"
+case "$TARGET" in
+    project)
+        SYNC_CMD="$SYNC_CMD --project ."
+        ;;
+    global)
+        SYNC_CMD="$SYNC_CMD --global"
+        ;;
+    both)
+        SYNC_CMD="$SYNC_CMD --global --project ."
+        ;;
+esac
+
+# Add optional flags
+if [ "${force}" = "true" ]; then
+    SYNC_CMD="$SYNC_CMD --force"
+fi
+
+if [ "${dry-run}" = "true" ]; then
+    SYNC_CMD="$SYNC_CMD --dry-run"
+fi
+
+echo "Running: $SYNC_CMD"
+```
+
+### Step 3: Execute Sync
+
+```bash
+$SYNC_CMD
+```
+
+### Step 4: Summary
+
+After sync completes, report:
+- Number of files updated
+- Any protected files that were skipped
+- New version marker
+
+## Post-Sync Checklist
+
+- [ ] Review any updated hooks for breaking changes
+- [ ] Check if new commands are available (`/help`)
+- [ ] Verify settings.local.json hook paths are correct
+- [ ] Run `/orient` to confirm everything works
+
+## Troubleshooting
+
+If sync fails:
+1. Ensure anvil-dev-framework repo is up to date: `cd $ANVIL_DIR && git pull`
+2. Check file permissions in .claude/
+3. Run with `--dry-run` first to preview changes
+4. Use `--force` only if you want to reset customized files