anvil-dev-framework 0.1.6

package/README.md

@@ -0,0 +1,719 @@
+```
+     ___    _   ___     _____ _
+    /   \  | \ | \ \   / /_ _| |
+   / /_\ \ |  \| |\ \ / / | || |      v0.1.6.0 (alpha)
+  / _____ \| |\  | \ V /  | || |___
+ /_/     \_\_| \_|  \_/  |___|_____|
+
+   ══════════════════════════════════════════════════════════
+     Where raw specs are forged into production code.
+   ══════════════════════════════════════════════════════════
+```
+
+# Anvil Development Framework <sup>v0.1.6.0</sup>
+
+> **A structured AI development system for solo builders who demand production-quality output.**
+
+Anvil is a comprehensive framework for AI-assisted software development that combines phase-gated workflows, persistent memory systems, and automated quality gates to transform how you build software with AI coding assistants.
+
+---
+
+## 📦 Latest Changes in v0.1.6.0
+
+*Released: 2026-01-07*
+
+- **Ralph Wiggum Autonomous Execution** — Long-running unattended AI execution mode
+  - `/ralph start` — Initialize autonomous loop with task breakdown
+  - Circuit breaker safety (stops stuck loops automatically)
+  - Progress tracking to prevent repeated mistakes
+  - Git checkpointing before each restart
+- **PostToolUse Formatting Hook** — Auto-format files after Edit/Write operations
+- **Usage Guidelines** — Clear guidance on when Ralph is appropriate vs standard workflow
+
+See [CHANGELOG.md](CHANGELOG.md) for complete history.
+
+> **Note**: Version numbers were reset in January 2026 from `1.x` to `0.1.x` to accurately reflect alpha status. See [Versioning Strategy](#versioning-strategy) for details.
+
+---
+
+## 🔥 The Problem
+
+AI coding assistants are powerful but chaotic:
+
+```
+❌ Context lost between sessions
+❌ No memory of what was decided or why
+❌ Agents run off in wrong directions
+❌ Quality varies wildly
+❌ No structured workflow
+❌ Duplicate work, missed patterns
+❌ "It works on my machine" PRs
+```
+
+## ⚒️ The Anvil Solution
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                                                                         │
+│    📋 SPECS          🧠 MEMORY           🚦 GATES          🔄 FLOW      │
+│    ────────          ────────           ───────          ──────        │
+│    What to build     What happened      Quality checks   How to work   │
+│                                                                         │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                                                                 │   │
+│  │   EXPLORE → SPECIFY → PLAN → TASKS → IMPLEMENT → VERIFY → ✓   │   │
+│  │      │         │        │       │         │          │         │   │
+│  │      └─────────┴────────┴───────┴─────────┴──────────┘         │   │
+│  │                    Human gates at each phase                    │   │
+│  │                                                                 │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                         │
+│  ✅ Context preserved across sessions                                   │
+│  ✅ Structured specs prevent scope creep                                │
+│  ✅ Phase gates catch problems early                                    │
+│  ✅ Evidence-based PR completion                                        │
+│  ✅ Memory that actually persists                                       │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🎯 When to Use Anvil
+
+**Anvil is for you if:**
+- Solo developer or small team (1-3 people)
+- Building production software with AI assistance
+- Want structured workflows, not just chat
+- Value quality gates and evidence-based PRs
+- Need context to persist across sessions
+
+**Anvil is NOT for:**
+- Large teams with existing robust processes
+- Quick prototypes / throwaway code
+- Those who prefer unstructured AI interaction
+
+**Architecture Philosophy:**
+- **Single generalist agent** with on-demand skills (not multi-agent)
+- **Skills** = Domain knowledge loaded when needed
+- **Sub-agents** = Focused multi-step workflows
+- **Coordination** = For parallel Claude terminals, not agent roles
+
+---
+
+## 📊 Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         ANVIL ARCHITECTURE                              │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │                     SINGLE GENERALIST AGENT                      │   │
+│  │                                                                  │   │
+│  │   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │   │
+│  │   │    Skills    │  │  Sub-Agents  │  │   Context    │         │   │
+│  │   │  (on-demand) │  │ (read-only)  │  │   (tiers)    │         │   │
+│  │   └──────────────┘  └──────────────┘  └──────────────┘         │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                              │                                          │
+│  ┌───────────────────────────┼───────────────────────────────────────┐ │
+│  │                    MEMORY SYSTEM                                   │ │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐    │ │
+│  │  │  Spec   │ │  Task   │ │ Session │ │ Handoff │ │Convention│    │ │
+│  │  │ Memory  │ │ Memory  │ │ Memory  │ │ Memory  │ │ Memory  │    │ │
+│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘    │ │
+│  └───────────────────────────────────────────────────────────────────┘ │
+│                              │                                          │
+│  ┌───────────────────────────┼───────────────────────────────────────┐ │
+│  │                   QUALITY GATES                                    │ │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐                 │ │
+│  │  │Pre-Work │ │ During  │ │ Pre-PR  │ │ Post-PR │                 │ │
+│  │  │  Gate   │ │  Gate   │ │  Gate   │ │  Gate   │                 │ │
+│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘                 │ │
+│  └───────────────────────────────────────────────────────────────────┘ │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+**Option 1: Bun (Recommended for Claude Code users)**
+```bash
+bun install -g anvil-dev-framework
+anvil init
+```
+
+**Option 2: npm**
+```bash
+npm install -g anvil-dev-framework
+anvil init
+```
+
+**Option 3: Homebrew (macOS)**
+```bash
+brew tap alexandercahiz/anvil
+brew install anvil
+anvil init
+```
+
+**Option 4: From Source**
+```bash
+git clone https://github.com/alexandercahiz/anvil-dev-framework.git
+cd anvil-dev-framework
+./scripts/install.sh  # Auto-configures PATH
+anvil init
+```
+
+See [docs/INSTALLATION.md](docs/INSTALLATION.md) for complete installation guide.
+
+**Templates available:**
+```bash
+anvil init                          # Generic project
+anvil init --template saas          # SaaS project
+anvil init --template api-python    # Python API project
+anvil init --with-linear            # With Linear integration
+anvil init --dry-run                # Preview changes
+```
+
+See [docs/anvil-init.md](docs/anvil-init.md) for complete `anvil init` documentation.
+
+### Keeping Updated
+
+After making changes to the framework, sync to your projects:
+
+```bash
+# Sync global config
+./scripts/sync.sh --global
+
+# Sync a specific project
+./scripts/sync.sh --project /path/to/your/project
+
+# Preview changes first
+./scripts/sync.sh --project . --dry-run
+
+# Or use the Claude Code command
+/anvil-sync target:both
+```
+
+See [docs/sync.md](docs/sync.md) for complete sync documentation.
+
+### First Skill
+
+After installation, create your first skill:
+See [docs/FIRST-SKILL-TUTORIAL.md](docs/FIRST-SKILL-TUTORIAL.md)
+
+### Daily Workflow
+
+```
+/orient → /sprint → /validate → [work] → /evidence → /handoff
+```
+
+**For new features, add:**
+```
+/explore → /spec → /plan → /tasks → [implement]
+```
+
+See [Session Workflow Guide](docs/session-workflow.md) for the complete step-by-step walkthrough.
+
+---
+
+## 📁 Framework Structure
+
+```
+anvil-dev-framework/
+│
+├── global/                        # → Installs to ~/.claude/
+│   ├── CLAUDE.md                  # Personal defaults & preferences
+│   ├── standards/                 # Universal coding standards
+│   │   ├── typescript.md
+│   │   ├── react.md
+│   │   ├── testing.md
+│   │   └── security.md
+│   ├── templates/                 # Reusable spec templates
+│   │   ├── feature-spec.md
+│   │   ├── bug-fix-spec.md
+│   │   └── refactor-spec.md
+│   ├── commands/                  # Global slash commands
+│   │   ├── orient.md
+│   │   ├── ready.md
+│   │   ├── validate.md
+│   │   ├── evidence.md
+│   │   ├── shard.md
+│   │   └── decay-review.md
+│   ├── skills/                    # Claude Code skills
+│   └── analytics/                 # Metrics & reports
+│
+├── project/                       # → Installs to .claude/
+│   ├── CLAUDE.md.template         # Project context (customize)
+│   ├── constitution.md.template   # Non-negotiable principles
+│   ├── product.md.template        # Mission & roadmap
+│   ├── commands/                  # Project-specific commands
+│   │   ├── explore.md
+│   │   ├── spec.md
+│   │   ├── plan.md
+│   │   ├── tasks.md
+│   │   ├── discover.md
+│   │   ├── change.md
+│   │   └── handoff.md
+│   ├── specs/                     # Specifications
+│   │   ├── current/
+│   │   └── archive/
+│   ├── changes/                   # Brownfield change proposals
+│   ├── handoffs/                  # Session continuity docs
+│   └── examples/                  # Convention examples
+│
+├── quality-gates/                 # → Installs to project root
+│   ├── .coderabbit.yaml           # AI code review config
+│   ├── .semgrep/                  # SAST rules
+│   ├── .pre-commit-config.yaml    # Pre-commit hooks
+│   └── .github/workflows/ci.yaml  # CI pipeline
+│
+├── docs/                          # Documentation
+│   ├── research/                  # Research reports
+│   │   └── v5-research-report.md
+│   ├── patterns/                  # Pattern explanations
+│   ├── implementation-guide.md    # Step-by-step setup
+│   └── command-reference.md       # All commands documented
+│
+├── scripts/                       # Automation
+│   ├── install.sh                 # Fresh install to ~/.claude/
+│   ├── init-project.sh            # Initialize in project
+│   ├── sync.sh                    # Sync framework updates
+│   └── rollback.sh                # Rollback changes
+│
+└── examples/                      # Reference implementations
+    └── baby-gift-garden/
+```
+
+---
+
+## 🧠 Core Concepts
+
+### 1. Phase-Gated Workflow
+
+Every feature flows through structured phases with human checkpoints:
+
+```
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+│ EXPLORE  │───▶│ SPECIFY  │───▶│   PLAN   │───▶│  TASKS   │
+│          │    │          │    │          │    │          │
+│ /explore │    │  /spec   │    │  /plan   │    │  /tasks  │
+└──────────┘    └────┬─────┘    └────┬─────┘    └──────────┘
+                     │               │                 │
+                     ▼               ▼                 ▼
+                [APPROVE]       [APPROVE]         [IMPLEMENT]
+                     │               │                 │
+                     │               │                 ▼
+                     │               │          ┌──────────┐
+                     │               │          │  VERIFY  │
+                     │               │          │          │
+                     │               │          │/evidence │
+                     │               │          └────┬─────┘
+                     │               │               │
+                     │               │               ▼
+                     │               │          ┌──────────┐
+                     │               │          │ ARCHIVE  │
+                     │               │          │          │
+                     │               │          │  Done!   │
+                     │               │          └──────────┘
+```
+
+### 2. Five-Layer Memory System
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        MEMORY ARCHITECTURE                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Layer 1: SPECIFICATION MEMORY                                      │
+│  ─────────────────────────────                                      │
+│  Location: .claude/specs/                                           │
+│  Purpose:  What SHOULD be built                                     │
+│  Decay:    Archive when feature complete                            │
+│                                                                     │
+│  Layer 2: TASK MEMORY                                               │
+│  ────────────────────                                               │
+│  Location: Linear (via MCP or CLI)                                  │
+│  Purpose:  What needs to be DONE                                    │
+│  Decay:    Archive closed >30 days                                  │
+│                                                                     │
+│  Layer 3: SESSION MEMORY                                            │
+│  ───────────────────────                                            │
+│  Location: Claude-Mem observations                                  │
+│  Purpose:  What HAPPENED in past sessions                           │
+│  Decay:    Auto-compress to ~500 tokens/observation                 │
+│                                                                     │
+│  Layer 4: HANDOFF MEMORY                                            │
+│  ──────────────────────                                             │
+│  Location: .claude/handoffs/                                        │
+│  Purpose:  Where we LEFT OFF                                        │
+│  Decay:    Keep last 5-7, archive older                             │
+│                                                                     │
+│  Layer 5: CONVENTION MEMORY                                         │
+│  ─────────────────────────                                          │
+│  Location: CLAUDE.md + Skills                                       │
+│  Purpose:  HOW to build                                             │
+│  Decay:    Rarely (evolve instead)                                  │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 3. Three-Tier Context Hierarchy
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                      CONTEXT HIERARCHY                              │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  TIER 1: GLOBAL (~/.claude/)                                        │
+│  ───────────────────────────                                        │
+│  • Personal preferences                                             │
+│  • Universal standards                                              │
+│  • Reusable templates                                               │
+│  Lifetime: Permanent                                                │
+│                                                                     │
+│  TIER 2: PROJECT (.claude/)                                         │
+│  ──────────────────────────                                         │
+│  • Project-specific CLAUDE.md                                       │
+│  • Constitution (non-negotiables)                                   │
+│  • Product definition                                               │
+│  Lifetime: Project duration                                         │
+│                                                                     │
+│  TIER 3: FEATURE (.claude/specs/)                                   │
+│  ─────────────────────────────────                                  │
+│  • Feature specifications                                           │
+│  • Implementation plans                                             │
+│  • Change proposals                                                 │
+│  Lifetime: Feature duration → archive                               │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 4. Quality Gate System
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                       QUALITY GATES                                 │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  PRE-WORK GATE (/validate)                                          │
+│  ─────────────────────────                                          │
+│  ✓ Git status clean                                                 │
+│  ✓ On feature branch (not main)                                     │
+│  ✓ Dependencies installed (npm ci)                                  │
+│  ✓ Tests passing (baseline)                                         │
+│  ✓ Types passing (no errors)                                        │
+│                                                                     │
+│  DURING-WORK GATE                                                   │
+│  ────────────────                                                   │
+│  ✓ Read before write (cite files)                                   │
+│  ✓ Follow conventions (check examples)                              │
+│  ✓ File discovered work immediately                                 │
+│  ✓ Update Linear status                                             │
+│                                                                     │
+│  PRE-PR GATE (/evidence)                                            │
+│  ───────────────────────                                            │
+│  ✓ Lint passes (full output)                                        │
+│  ✓ Types pass (full output)                                         │
+│  ✓ Tests pass (full output)                                         │
+│  ✓ Only expected files changed                                      │
+│  ✓ Evidence captured in PR                                          │
+│                                                                     │
+│  POST-PR GATE                                                       │
+│  ────────────                                                       │
+│  ✓ CodeRabbit review                                                │
+│  ✓ Semgrep security scan                                            │
+│  ✓ Human review                                                     │
+│  ✓ CI pipeline passes                                               │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📋 Command Reference
+
+### Session Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/orient` | Session startup orientation | Start of every session |
+| `/ready` | Calculate ready work (no blockers) | Before selecting a task |
+| `/handoff` | Generate session continuity doc | End of every session |
+
+### Workflow Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/explore` | Discovery phase | Before any new feature |
+| `/spec` | Generate specification | After exploration approved |
+| `/plan` | Create implementation plan | After spec approved |
+| `/tasks` | Break plan into Linear issues | After plan approved |
+| `/change` | Create brownfield change proposal | Modifying existing features |
+
+### Quality Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/validate` | Environment validation | Before any code changes |
+| `/evidence` | Capture quality gate proof | Before creating PR |
+| `/discover` | File discovered work | During implementation |
+
+### Maintenance Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/anvil-sync` | Sync framework updates | After pulling framework changes |
+| `/shard` | Break large specs into pieces | When specs exceed 2000 tokens |
+| `/decay-review` | Archive old issues/handoffs | Weekly maintenance |
+| `/weekly-review` | Generate analytics report | Weekly review |
+
+### Power Mode Commands
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/ralph start` | Initialize autonomous execution | Large refactoring, overnight runs |
+| `/ralph status` | Check iteration progress | Monitor unattended execution |
+| `/ralph stop` | Gracefully terminate loop | End autonomous session early |
+
+> **Note**: Ralph Wiggum mode is a specialized power tool for specific scenarios (large refactoring, framework migrations, TDD with clear specs). It is NOT part of the standard daily workflow. See [When to Use Ralph](#when-to-use-ralph-wiggum-mode) below.
+
+---
+
+## 🤖 When to Use Ralph Wiggum Mode
+
+Ralph Wiggum is a **specialized power tool** for autonomous, long-running AI execution — NOT a replacement for the standard workflow.
+
+### Standard Workflow (Daily Use)
+```
+/orient → /sprint → /validate → [work] → /evidence → /handoff
+```
+
+This remains your **default approach** for all normal development work.
+
+### Ralph Mode (Special Scenarios Only)
+
+```
+/ralph start "Migrate all tests from Jest to Vitest" --max-iterations 50
+```
+
+| Good For | Not Good For |
+|----------|--------------|
+| ✅ Large-scale refactoring with clear completion criteria | ❌ Exploratory work (figuring things out) |
+| ✅ Framework migrations (Jest→Vitest, CJS→ESM) | ❌ Ambiguous requirements |
+| ✅ TDD with clear failing tests to pass | ❌ Security-sensitive code |
+| ✅ Greenfield projects with detailed specs | ❌ Architecture decisions needing judgment |
+| ✅ Test coverage expansion across many files | ❌ Quick fixes (overkill) |
+| ✅ Overnight/unattended execution (8+ hours) | ❌ Interactive debugging |
+
+### Cost Awareness
+
+| Scenario | Estimated Cost |
+|----------|----------------|
+| 10 iterations, small codebase | $5-15 |
+| 50 iterations, medium codebase | $50-100+ |
+| 100+ iterations, large codebase | $200+ |
+
+**Recommendation**: Start with `--max-iterations 10` to understand costs before running overnight.
+
+### Decision Flowchart
+
+```
+Is this task...
+├── Quick fix or bug? → Standard workflow
+├── Exploratory / unclear? → Standard workflow
+├── Needs human decisions? → Standard workflow
+├── Large with clear spec? → Consider Ralph
+├── Migration / refactoring? → Consider Ralph
+└── Overnight / unattended? → Ralph is ideal
+```
+
+---
+
+## 🔬 Research Foundation
+
+Anvil is built on extensive research across 15+ systems with 200k+ combined GitHub stars:
+
+| Source | Key Pattern Extracted |
+|--------|----------------------|
+| **Factory Droid** | 6 structural guardrails (58.8% Terminal-Bench vs 43.2% baseline) |
+| **Beads** (4.2k ⭐) | Task memory patterns, ready work calculation |
+| **BMAD** (25.2k ⭐) | Document sharding, phase gates |
+| **SpecKit** (55.6k ⭐) | Constitution pattern, structured specs |
+| **OpenSpec** (12k ⭐) | Brownfield change tracking, Gherkin scenarios |
+| **Agent OS** (2.7k ⭐) | Three-tier context hierarchy |
+| **Claude-Mem** | Session compression, semantic search |
+| **Prompt Coach** | Prompt analytics, time-lost calculations |
+
+### Key Research Findings
+
+1. **Agent design matters more than model choice** — Droid achieved 58.8% vs Claude Code's 43.2% on Terminal-Bench using the same model
+2. **Single agent with skills beats multi-agent** — Coordination overhead typically 40-60% of cycles
+3. **Phase gates prevent disasters** — Universal across all production systems studied
+4. **Identity claims hurt performance** — "Idiot" persona outperformed "Genius" by 2.2% on MMLU
+
+See [docs/research/v5-research-report.md](docs/research/v5-research-report.md) for the complete analysis.
+
+---
+
+## 💰 Cost Structure
+
+| Component | Cost | Purpose |
+|-----------|------|---------|
+| Claude Code Max | $200/mo | AI coding assistant |
+| CodeRabbit | $25/mo | AI code review |
+| Semgrep OSS | Free | Security scanning |
+| Trivy | Free | Vulnerability scanning |
+| Gitleaks | Free | Secrets detection |
+| Pre-commit | Free | Git hooks |
+| **Total** | **$225/mo** | |
+
+---
+
+## 📈 Success Metrics
+
+### Leading Indicators (Weekly)
+
+| Metric | Target |
+|--------|--------|
+| Orientation time | < 2 minutes |
+| Ready work accuracy | > 95% |
+| Phase gate compliance | 100% |
+| Handoff coverage | 100% |
+
+### Lagging Indicators (Monthly)
+
+| Metric | Target |
+|--------|--------|
+| First-pass PR approval | > 70% |
+| Clarification rate | < 15% |
+| Security findings per PR | < 2 high |
+| Discovery completion | > 80% within 2 weeks |
+
+---
+
+## 🗺️ Roadmap
+
+### Versioning Strategy
+
+Anvil uses **four-part versioning**: `MILESTONE.MAJOR.MINOR.PATCH`
+
+| Component | Meaning |
+|-----------|---------|
+| **MILESTONE** | 0 = Alpha (pre-1.0), 1 = Production-ready |
+| **MAJOR** | Significant feature sets or breaking changes |
+| **MINOR** | New features |
+| **PATCH** | Bug fixes |
+
+---
+
+### Road to 1.0.0.0 (Production-Ready)
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| HUD/TUI fully implemented | ✅ Complete | Multi-agent terminal dashboard with 6 panels |
+| External user testing | ⏳ Not Started | Beta testers outside core team |
+| One-command installation | ✅ Complete | `anvil init` with templates |
+| All core commands documented | ✅ Complete | 13 commands with examples |
+| No known critical bugs | 🔄 Ongoing | Continuous improvement |
+| Cross-platform testing | ⏳ Not Started | macOS, Linux, WSL |
+| Monetization/licensing defined | ⏳ Not Started | Pricing and distribution model |
+
+---
+
+### In Progress (v0.1.5.0)
+- [x] HUD v2 Multi-Agent Command Center (ANV-78)
+- [x] HUD Kanban Panel (ANV-76)
+- [x] Provider Pattern for issue tracking (Linear + Local)
+- [x] Local JSON issue tracker for non-Linear users
+- [x] Cost Tracker, Context Health, Task Status panels
+- [x] Quality Gates, Coordination panels
+- [x] GitHub/CI and CodeRabbit integration
+- [x] HUD Configuration system
+- [x] Documentation for Local Issue Tracking System (ANV-109)
+- [ ] Unified `/orient`, `/sprint`, `/ready` commands
+
+### Completed Milestones
+
+#### v0.1.4.0 (Current)
+- [x] Statusline configuration (full/minimal/off variants)
+- [x] `/release` command for version coordination
+- [x] Enhanced `/evidence` and `/handoff` commands
+- [x] Code review config integration
+
+#### v0.1.3.0
+- [x] Framework Healthcheck System (ANV-17)
+
+#### v0.1.2.0
+- [x] Use-case based templates (`saas`, `api-python`, `generic`)
+- [x] Next.js + Supabase + Vercel template
+- [x] FastAPI + PostgreSQL + pytest template
+
+#### v0.1.1.0
+- [x] CLI tool (`anvil init` command)
+- [x] Project initialization with templates
+- [x] Granular hook control (`--no-tts`, `--no-memory`)
+- [x] Linear sub-issue support
+
+#### v0.1.0.0
+- [x] Core framework structure
+- [x] Phase-gated workflow commands
+- [x] Memory system architecture
+- [x] Quality gate configurations
+- [x] Documentation
+
+---
+
+### Future (Post-1.0)
+- [ ] Additional templates (mobile, Rails, Go)
+- [ ] VS Code extension
+- [ ] Dashboard for metrics
+- [ ] Team collaboration features
+
+---
+
+## 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Session Workflow](docs/session-workflow.md) | **START HERE** — Daily coding workflow |
+| [Local Issue Tracking](docs/local-issues.md) | File-based issues without Linear |
+| [Sync Guide](docs/sync.md) | Keep projects updated with framework changes |
+| [Installation Guide](docs/INSTALLATION.md) | Initial framework setup |
+| [Implementation Guide](docs/implementation-guide.md) | How to set up Anvil |
+| [Command Reference](docs/command-reference.md) | All commands detailed |
+| [Planning Responsibilities](docs/planning-responsibilities.md) | Who decides what |
+| [Simplification Principles](docs/simplification-principles.md) | Framework simplicity guidance |
+| [Simplification Plan Template](docs/simplification-plan-template.md) | Audit and simplify checklist |
+| [Research Report](docs/research/v5-research-report.md) | Full research analysis |
+| [Pattern Catalog](docs/patterns/) | Pattern explanations |
+
+---
+
+## ⚖️ License
+
+**Proprietary** — All rights reserved.
+
+This framework is not open source. Contact for licensing inquiries.
+
+---
+
+## 🤝 Contact
+
+For licensing, questions, or collaboration:
+
+- **Author**: Alex Cahiz
+- **Project**: Anvil Development Framework
+
+---
+
+```
+   ══════════════════════════════════════════════════════════
+     Built with 🔥 for developers who refuse to compromise.
+   ══════════════════════════════════════════════════════════
+```