anvil-dev-framework 0.1.6

package/docs/patterns/README.md

@@ -0,0 +1,419 @@
+# Pattern Catalog
+
+> Detailed explanations of the patterns integrated into Anvil.
+
+---
+
+## Table of Contents
+
+1. [Structural Guardrails (Droid Patterns)](#1-structural-guardrails)
+2. [Task Memory Patterns (Beads)](#2-task-memory-patterns)
+3. [Spec-Driven Patterns](#3-spec-driven-patterns)
+4. [Memory Patterns](#4-memory-patterns)
+5. [Quality Gate Patterns](#5-quality-gate-patterns)
+
+---
+
+## 1. Structural Guardrails
+
+Source: Factory AI Droid system prompt
+
+### 1.1 Environment Validation Checkpoint
+
+**Problem**: AI agents are non-deterministic. Without validation, agents build on unstable foundations.
+
+**Pattern**: Before ANY file changes, verify:
+1. Git status is clean
+2. On feature branch (not main)
+3. Dependencies installed from lockfile
+4. Tests passing (baseline)
+5. Types passing (baseline)
+
+**Implementation**: `/validate` command
+
+**Key Insight**: If ANY step fails, STOP. Do not proceed.
+
+---
+
+### 1.2 Read-Before-Write Protocol
+
+**Problem**: Agents hallucinate code that doesn't exist—inventing API parameters, configuration fields, and function signatures.
+
+**Pattern**:
+1. Before proposing changes → open and read target files
+2. Before claiming understanding → cite actual code with file paths
+3. Before adding new code → review similar existing module
+4. Never say "I assume" about code you can read
+
+**Evidence**: Master of Code research showed separating retrieval from generation reduces hallucination by 60-80%.
+
+---
+
+### 1.3 Living Task Management
+
+**Problem**: Without task tracking, agents lose their place, repeat work, and miss steps.
+
+**Pattern**:
+- Decompose tasks into explicit checklists
+- Update status after each major step
+- Detect stuck states (same action 3+ times)
+- Report blockers immediately
+
+**Implementation**: Linear integration with status updates
+
+---
+
+### 1.4 Evidence-Based PR Completion
+
+**Problem**: Agents claim completion without verification.
+
+**Pattern**: Create PR ONLY when evidence captured:
+- Lint output (0 errors)
+- Type check output (0 errors)
+- Test output (all pass)
+- Git status (only expected files)
+
+**Implementation**: `/evidence` command
+
+---
+
+### 1.5 Convention Discovery Phase
+
+**Problem**: AI generates "technically correct code that feels foreign to your codebase."
+
+**Pattern**:
+1. Find similar existing module
+2. Document observed conventions
+3. Create plan using discovered patterns
+4. Reference example in implementation
+
+**Implementation**: Convention examples in `.claude/examples/`
+
+---
+
+### 1.6 Multi-Stage Verification
+
+**Problem**: Agents cannot reliably verify their own work.
+
+**Pattern**: Three verification stages:
+1. **Smoke Tests**: Compile, lint, existing tests
+2. **Correctness**: New tests, edge cases, integration
+3. **External Review**: CodeRabbit, Semgrep, human review
+
+---
+
+## 2. Task Memory Patterns
+
+Source: Beads issue tracker (Steve Yegge)
+
+### 2.1 Ready Work Calculation
+
+**Problem**: Without dependency awareness, agents pick blocked tasks.
+
+**Pattern**:
+1. Query all active issues
+2. Filter where ALL blockers are Done
+3. Sort by priority, then age
+4. Present ready work list
+
+**Implementation**: `/ready` command
+
+**Key Insight**: Agents can instantly orient when they can query ready work.
+
+---
+
+### 2.2 Discovered-From Linking
+
+**Problem**: Agents file issues but lose discovery context.
+
+**Pattern**: When discovering new work:
+1. File immediately (don't defer)
+2. Link to parent issue
+3. Add discovery context
+4. Add "discovered" label
+
+**Implementation**: `/discover` command
+
+---
+
+### 2.3 Session Handoff Prompts
+
+**Problem**: Sessions end abruptly. Next session starts cold.
+
+**Pattern**: At session end, generate:
+- What was completed
+- What's in progress
+- What was discovered
+- Recommended next task
+- Critical context
+
+**Implementation**: `/handoff` command
+
+---
+
+### 2.4 Memory Decay Reviews
+
+**Problem**: Issue trackers accumulate cruft, wasting context.
+
+**Pattern**: Weekly maintenance:
+- Archive issues closed >30 days
+- Summarize before archiving
+- Target <50 active issues
+
+**Implementation**: `/decay-review` command
+
+---
+
+### 2.5 Quick Agent Orientation
+
+**Problem**: New sessions re-read everything, wasting tokens.
+
+**Pattern**: Session startup:
+1. Check for handoff (<48 hours)
+2. Query in-progress issues
+3. Query ready work
+4. Report and await direction
+
+**Implementation**: `/orient` command
+
+---
+
+## 3. Spec-Driven Patterns
+
+Sources: BMAD, SpecKit, OpenSpec, Agent OS
+
+### 3.1 Phase-Gated Workflows
+
+**Problem**: Agents jump straight to coding without understanding.
+
+**Pattern**: Human checkpoints between phases:
+```
+EXPLORE → [approve] → SPECIFY → [approve] → PLAN → [approve] → TASKS
+```
+
+**Key Insight**: Phase gates prevent disasters.
+
+---
+
+### 3.2 Three-Tier Context Hierarchy
+
+**Problem**: Monolithic context documents exceed windows.
+
+**Pattern**:
+| Tier | Location | Contents | Lifetime |
+|------|----------|----------|----------|
+| Global | ~/.claude/ | Standards, templates | Permanent |
+| Project | .claude/ | CLAUDE.md, constitution | Project |
+| Feature | .claude/specs/ | Specifications | Feature |
+
+---
+
+### 3.3 Document Sharding
+
+**Problem**: Large specs cause context rot.
+
+**Pattern**: Break specs into atomic pieces:
+```
+SPEC-001-auth.md (master)
+SPEC-001-auth/
+├── epic-001-registration.md
+├── epic-002-login.md
+└── epic-003-reset.md
+```
+
+**Benefit**: ~80% token savings by loading only relevant shards.
+
+**Implementation**: `/shard` command
+
+---
+
+### 3.4 Brownfield Change Management
+
+**Problem**: Most work modifies existing code, not greenfield.
+
+**Pattern**: Separate specs (what IS) from changes (what SHOULD change):
+```
+.claude/specs/       → Source of truth
+.claude/changes/     → Delta proposals
+```
+
+Use ADDED/MODIFIED/REMOVED markers for clarity.
+
+**Implementation**: `/change` command
+
+---
+
+### 3.5 Gherkin Acceptance Criteria
+
+**Problem**: Vague requirements are unverifiable.
+
+**Pattern**: GIVEN/WHEN/THEN scenarios:
+```
+GIVEN a registered user
+WHEN they submit valid credentials
+THEN a session is created
+AND they are redirected to dashboard
+```
+
+**Benefits**:
+- Unambiguous
+- Testable
+- Scoped
+- Human-readable
+- AI-parseable
+
+---
+
+### 3.6 Constitution Pattern
+
+**Problem**: Agents make decisions that violate core principles.
+
+**Pattern**: Non-negotiable principles that cannot be overridden:
+- Security principles (5)
+- Code quality principles (5)
+- Architecture principles (4)
+- Process principles (5)
+- What we will NOT do (10)
+
+**Implementation**: `.claude/constitution.md`
+
+---
+
+## 4. Memory Patterns
+
+Sources: Claude-Mem, research
+
+### 4.1 Five-Layer Memory System
+
+| Layer | Purpose | Location | Decay |
+|-------|---------|----------|-------|
+| Spec | What to build | .claude/specs/ | Archive on complete |
+| Task | What to do | Linear | Archive >30 days |
+| Session | What happened | Claude-Mem | Compress |
+| Handoff | Where we left off | .claude/handoffs/ | Keep last 7 |
+| Convention | How to build | CLAUDE.md | Rarely |
+
+---
+
+### 4.2 Progressive Disclosure
+
+**Problem**: Loading all context wastes tokens.
+
+**Pattern**: Three disclosure layers:
+1. **Index**: Just titles and IDs
+2. **Summary**: Key points and status
+3. **Full**: Complete content
+
+Load deeper layers only when needed.
+
+---
+
+### 4.3 Semantic Search Over History
+
+**Problem**: Keyword search misses related content.
+
+**Pattern**: Vector embeddings enable natural language queries:
+- "What did we do about authentication?"
+- "Where was the rate limiting discussion?"
+
+---
+
+## 5. Quality Gate Patterns
+
+### 5.1 Pre-Work Gate
+
+**When**: Before any code changes
+
+**Checks**:
+- [ ] Git status clean
+- [ ] On feature branch
+- [ ] Dependencies installed
+- [ ] Tests passing
+- [ ] Types passing
+
+**Implementation**: `/validate` command
+
+---
+
+### 5.2 During-Work Gate
+
+**When**: Continuous during implementation
+
+**Behaviors**:
+- Read before write
+- Follow conventions
+- File discovered work
+- Update task status
+- Report stuck states
+
+---
+
+### 5.3 Pre-PR Gate
+
+**When**: Before creating pull request
+
+**Checks**:
+- [ ] Lint passes (with output)
+- [ ] Types pass (with output)
+- [ ] Tests pass (with output)
+- [ ] Only expected files changed
+- [ ] Evidence captured
+
+**Implementation**: `/evidence` command
+
+---
+
+### 5.4 Post-PR Gate
+
+**When**: After PR created
+
+**Tools**:
+- CodeRabbit: AI code review
+- Semgrep: Security scanning
+- Trivy: Vulnerability detection
+- Gitleaks: Secret detection
+- Human review: Final approval
+
+---
+
+## Pattern Integration
+
+These patterns work together:
+
+```
+Session Start
+    │
+    ├─► /orient (Quick Orientation)
+    │       │
+    │       └─► /ready (Ready Work Calculation)
+    │               │
+    │               └─► /validate (Environment Validation)
+    │
+Feature Work
+    │
+    ├─► /explore (Discovery + Read-Before-Write)
+    │       │
+    │       └─► /spec (Gherkin Scenarios)
+    │               │
+    │               └─► /plan (Document Sharding)
+    │                       │
+    │                       └─► /tasks (Task Memory)
+    │
+Implementation
+    │
+    ├─► Convention Discovery
+    │       │
+    │       └─► Living Task Management
+    │               │
+    │               └─► /discover (Discovered-From Linking)
+    │                       │
+    │                       └─► /evidence (Evidence-Based PR)
+    │
+Session End
+    │
+    └─► /handoff (Session Handoff)
+```
+
+---
+
+*For command details, see the [Command Reference](command-reference.md).*

package/docs/planning-responsibilities.md

@@ -0,0 +1,139 @@
+# Planning Responsibilities
+
+> Clear ownership of planning functions. No overlap, no gaps.
+
+---
+
+## Principle
+
+**Human orchestrates, Claude executes.**
+
+Claude doesn't decide what to work on. Claude presents options, provides context, and awaits direction. The human makes priority decisions.
+
+---
+
+## Planning Functions
+
+| Function | Owner | Tool/Method |
+|----------|-------|-------------|
+| **What exists** | Linear | Issue backlog |
+| **What's blocked** | Linear + `/ready` | Dependency tracking |
+| **What's ready** | `/ready` command | Filters unblocked work |
+| **What's context** | `/orient` command | Handoffs, git state |
+| **What's priority** | Human | Uses `/sprint` for suggestions |
+| **What's approved** | Human | Explicit approval gates |
+
+---
+
+## Command Responsibilities
+
+### Session Start: `/orient`
+**Answers:** "Where am I? What happened? What's going on?"
+- Reads recent handoff
+- Checks git state
+- Reports in-progress work
+- Shows ready work summary
+- **Does NOT** start working
+
+### Ready Work: `/ready`
+**Answers:** "What CAN I work on?"
+- Queries Linear for active issues
+- Filters to unblocked items
+- Sorts by priority then age
+- **Does NOT** recommend priorities
+
+### Session Focus: `/sprint`
+**Answers:** "What SHOULD I work on?"
+- Summarizes state (blocked, in-progress, review, todo)
+- Suggests top 3 based on simple heuristics
+- Highlights blockers needing human action
+- **Does NOT** decide for you
+
+### Metrics: `/weekly-review`
+**Answers:** "How did we do? What to improve?"
+- Analyzes past week
+- Calculates metrics
+- Identifies patterns
+- **Does NOT** plan upcoming work
+
+---
+
+## What's NOT in Anvil
+
+Deliberately excluded orchestration patterns:
+
+| Pattern | Why Excluded |
+|---------|--------------|
+| Scrum master agent | Over-engineered for solo dev |
+| Automated priority calculation | Human judgment is better |
+| Multi-agent task routing | Research shows performance degradation |
+| Sprint planning meetings | Single person doesn't need ceremonies |
+| Velocity tracking | Irrelevant without team |
+| Story point estimation | Use t-shirt sizes or time estimates directly |
+
+---
+
+## Decision Flow
+
+```
+┌─────────────┐
+│   Human     │  "I want to start a session"
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  /orient    │  Reports state, awaits direction
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│   Human     │  "What should I work on?"
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  /sprint    │  Suggests priorities, awaits selection
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│   Human     │  "Work on ENG-123"
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  /validate  │  Verifies environment, begins work
+└─────────────┘
+```
+
+---
+
+## Anti-Patterns
+
+❌ **Claude deciding priorities**
+- "I'll work on ENG-123 since it's highest priority"
+- Fix: Always await human selection
+
+❌ **Complex priority algorithms**
+- WSJF, weighted scoring, dependency graphs
+- Fix: Simple heuristics + human judgment
+
+❌ **Automated task assignment**
+- "Routing this to backend agent"
+- Fix: Single generalist, human directs
+
+❌ **Skipping human approval gates**
+- Auto-proceeding from spec to implementation
+- Fix: Explicit approval at each phase
+
+---
+
+## Summary
+
+| Stage | Who Decides | Claude's Role |
+|-------|-------------|---------------|
+| What to work on | Human | Present options |
+| Spec approval | Human | Generate, await approval |
+| Plan approval | Human | Generate, await approval |
+| How to implement | Claude | Execute with skill |
+| When to stop | Human | Report progress, await direction |