anvil-dev-framework 0.1.6

package/docs/sync.md

@@ -0,0 +1,122 @@
+# Anvil Sync
+
+Keep your projects and global config up-to-date with the latest Anvil framework.
+
+## Quick Start
+
+```bash
+# From the anvil-dev-framework directory:
+
+# Sync global config (~/.claude/)
+./scripts/sync.sh --global
+
+# Sync a specific project
+./scripts/sync.sh --project /path/to/myproject
+
+# Sync both
+./scripts/sync.sh --global --project /path/to/myproject
+
+# Preview changes without applying
+./scripts/sync.sh --project . --dry-run
+
+# Force overwrite protected files
+./scripts/sync.sh --project . --force
+```
+
+## Setting Up Easy Access
+
+Add to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+# Anvil framework location
+export ANVIL_HOME="$HOME/Projects/anvil-dev-framework"
+
+# Anvil sync alias
+alias anvil-sync="$ANVIL_HOME/scripts/sync.sh"
+
+# Quick sync current project
+alias anvil-sync-here="$ANVIL_HOME/scripts/sync.sh --project ."
+```
+
+Then reload: `source ~/.zshrc`
+
+## Usage
+
+```
+anvil-sync [OPTIONS]
+
+Targets:
+  --global              Sync to ~/.claude/ (global config)
+  --project PATH        Sync to a specific project
+  --all                 Sync global + all registered projects
+
+Options:
+  --force, -f           Overwrite protected files
+  --dry-run, -n         Preview changes without applying
+  --verbose, -v         Show detailed output
+  --help, -h            Show help message
+```
+
+## What Gets Synced
+
+### Always Updated
+| Directory/File | Description |
+|----------------|-------------|
+| `hooks/` | All hook scripts |
+| `examples/` | Reference templates |
+| `agents/` | Sub-agent definitions |
+| `retros/templates/` | Retro templates |
+| `commands/` | Slash commands |
+
+### Protected Files (require `--force`)
+| File | Reason |
+|------|--------|
+| `CLAUDE.md` | Project-specific AI instructions |
+| `product.md` | Product definition |
+| `constitution.md` | Project principles |
+| `settings.local.json` | Local permissions |
+| `coordination.md` | Team coordination |
+
+## Claude Code Integration
+
+Use the `/anvil-sync` command within Claude Code:
+
+```
+/anvil-sync                    # Sync current project
+/anvil-sync target:global      # Sync global config
+/anvil-sync target:both        # Sync both
+/anvil-sync dry-run:true       # Preview changes
+/anvil-sync force:true         # Overwrite protected files
+```
+
+## Version Tracking
+
+After sync, a `.anvil-version` file is created/updated:
+- `~/.claude/.anvil-version` - Global config version
+- `project/.claude/.anvil-version` - Project version
+
+Check versions:
+```bash
+cat ~/.claude/.anvil-version
+cat .claude/.anvil-version
+```
+
+## Troubleshooting
+
+### "Could not find Anvil installation"
+Set the `ANVIL_HOME` environment variable:
+```bash
+export ANVIL_HOME="$HOME/Projects/anvil-dev-framework"
+```
+
+### Hooks not working after sync
+1. Check `settings.local.json` hook paths
+2. Ensure `uv` is installed: `pip install uv`
+3. Verify hook permissions: `chmod +x .claude/hooks/*.py`
+
+### Want to reset a customized file
+Use `--force` flag, but backup first:
+```bash
+cp .claude/CLAUDE.md .claude/CLAUDE.md.backup
+./scripts/sync.sh --project . --force
+```

package/global/CLAUDE.md

@@ -0,0 +1,140 @@
+# Global Claude Configuration
+
+> Personal defaults and preferences that apply across all projects.
+
+This file is loaded by Claude Code for every project. Keep it focused on universal preferences, not project-specific details.
+
+---
+
+## Identity
+
+- **Name**: [Your name]
+- **Role**: Solo developer / Technical founder / etc.
+- **Timezone**: [Your timezone]
+
+---
+
+## Communication Preferences
+
+### Response Style
+- Be direct and concise
+- Skip preambles and unnecessary caveats
+- When uncertain, say so clearly
+- Challenge my assumptions when they seem wrong
+
+### Code Style
+- Prefer readability over cleverness
+- Include comments for non-obvious logic
+- Follow existing patterns in the codebase
+- Suggest improvements, don't just implement requests
+
+### When I Say...
+- "LGTM" → Proceed with the approach
+- "Try it" → Implement and show results
+- "Think about it" → Analyze but don't implement yet
+- "Ship it" → Finalize and prepare for merge
+
+---
+
+## Session Protocols
+
+### Session Start
+1. Run `/orient` to check for handoffs
+2. Run `/ready` to see available work
+3. Run `/validate` before any changes
+4. Wait for direction before proceeding
+
+### During Work
+- File discovered work immediately with `/discover`
+- Update Linear status at phase transitions
+- Stop and report if stuck for >5 minutes
+- Cite file paths and line numbers as evidence
+
+### Session End
+- Run `/evidence` before PR creation
+- Run `/handoff` to preserve context
+- Ensure Linear issues reflect true state
+
+---
+
+## Quality Standards
+
+### Before Any Code Change
+- [ ] Git status is clean
+- [ ] On feature branch (not main)
+- [ ] Dependencies installed (`npm ci`)
+- [ ] Tests passing (baseline)
+- [ ] Types passing (baseline)
+
+### Before PR Creation
+- [ ] Lint passes (capture output)
+- [ ] Types pass (capture output)
+- [ ] Tests pass (capture output)
+- [ ] Only expected files changed
+- [ ] Evidence included in PR
+
+### Code Principles
+1. Read existing code before writing new code
+2. Never speculate about code you haven't opened
+3. Prefer simple solutions over clever abstractions
+4. Match existing patterns in the codebase
+5. Test edge cases, not just happy paths
+
+---
+
+## Tool Preferences
+
+### Task Tracking
+- Primary: Linear
+- Status flow: Backlog → Todo → In Progress → In Review → Done
+- Always set "blocked by" relationships
+- File discovered work immediately
+
+### Version Control
+- Branching: `feature/[issue-key]-[slug]`
+- Commits: Conventional commits (feat:, fix:, chore:, etc.)
+- PRs: Include evidence block, link to Linear issue
+
+### Code Quality
+- Linting: ESLint with project config
+- Formatting: Prettier with project config
+- Types: Strict TypeScript
+- Testing: Vitest / Jest per project
+
+---
+
+## Escalation Criteria
+
+### Stop and Ask When:
+- Requirements are ambiguous
+- Multiple valid approaches exist
+- Change affects security or authentication
+- Scope seems to be expanding
+- You've tried the same fix 3+ times
+
+### Never Do Without Asking:
+- Delete files or data
+- Modify environment variables
+- Change authentication logic
+- Update dependencies to major versions
+- Merge to main branch
+
+---
+
+## Learning Preferences
+
+### When I Make Mistakes
+- Point them out directly
+- Explain why it's a mistake
+- Suggest the correct approach
+- Don't apologize excessively
+
+### When You Make Mistakes
+- Acknowledge clearly
+- Explain what went wrong
+- Fix without over-explaining
+- Learn and don't repeat
+
+---
+
+*This file should be customized to your personal preferences. Project-specific settings go in the project's `.claude/CLAUDE.md`.*

package/global/agents/verify-app.md

@@ -0,0 +1,164 @@
+# verify-app - Verification Subagent
+
+> Specialized subagent for running project verification checks.
+
+## Purpose
+
+Isolates verification context (test output, lint errors, type check results) from the main session to prevent context pollution.
+
+## When to Use
+
+- Before committing code
+- Before creating PRs
+- During stop hook verification
+- In Ralph Wiggum mode iteration checks
+
+## Configuration
+
+This agent is invoked via the Task tool:
+
+```
+Task(
+  subagent_type="verify-app",
+  prompt="Run full verification suite and report results as JSON",
+  model="haiku"
+)
+```
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| Bash | Run test/lint/type commands |
+| Read | Read config files |
+| Glob | Find project files |
+
+## Expected Behavior
+
+The agent will:
+1. Detect the project type (npm, python, cargo, go)
+2. Run the test suite
+3. Run the linter
+4. Run the type checker
+5. Return structured JSON results
+
+## Output Format
+
+```json
+{
+  "overall": "pass",
+  "tests": {
+    "passed": true,
+    "count": 47,
+    "duration_ms": 3200,
+    "failures": []
+  },
+  "lint": {
+    "passed": true,
+    "errors": 0,
+    "warnings": 3
+  },
+  "types": {
+    "passed": true,
+    "errors": 0
+  },
+  "summary": "All 47 tests passed. Lint clean. Types clean."
+}
+```
+
+## Failure Output
+
+```json
+{
+  "overall": "fail",
+  "tests": {
+    "passed": false,
+    "count": 47,
+    "failures": [
+      {
+        "file": "src/auth/login.test.ts",
+        "line": 45,
+        "message": "Expected 200, got 401"
+      }
+    ]
+  },
+  "lint": {
+    "passed": true,
+    "errors": 0
+  },
+  "types": {
+    "passed": true,
+    "errors": 0
+  },
+  "summary": "1 test failure. See failures array for details."
+}
+```
+
+## Prompt
+
+The agent uses this specialized prompt:
+
+```
+You are a verification agent. Your sole purpose is to run project checks and report results.
+
+## Your Task
+1. Detect project type from package.json, pyproject.toml, Cargo.toml, or go.mod
+2. Run the test suite
+3. Run the linter
+4. Run the type checker
+5. Report results in JSON format
+
+## Commands by Project Type
+
+### Node.js (package.json)
+- Tests: npm test
+- Lint: npm run lint
+- Types: npm run typecheck
+
+### Python (pyproject.toml)
+- Tests: pytest
+- Lint: ruff check .
+- Types: mypy .
+
+### Rust (Cargo.toml)
+- Tests: cargo test
+- Lint: cargo clippy
+- Types: (included in clippy)
+
+### Go (go.mod)
+- Tests: go test ./...
+- Lint: golangci-lint run
+- Types: (included in build)
+
+## Rules
+- Run ALL checks, even if one fails
+- Capture full error output for failures
+- Include file and line numbers when available
+- Never attempt to fix issues, only report
+- Always output valid JSON
+
+## Output Format
+Always respond with ONLY a JSON object:
+{
+  "overall": "pass" | "fail",
+  "tests": { "passed": bool, "count": int, "failures": array },
+  "lint": { "passed": bool, "errors": int, "warnings": int },
+  "types": { "passed": bool, "errors": int },
+  "summary": "one-line human summary"
+}
+```
+
+## Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| Context isolation | Test output doesn't pollute main session |
+| Fast execution | Uses haiku model for quick checks |
+| Structured output | JSON format for easy parsing |
+| Comprehensive | Runs all checks, not just one |
+
+## Integration Points
+
+- Used by: `/test-and-commit`, stop hooks, Ralph mode
+- Invoked via: Task tool with `subagent_type="verify-app"`
+- Returns: Structured JSON for programmatic handling