anvil-dev-framework 0.1.6

package/docs/INSTALLATION.md

@@ -0,0 +1,984 @@
+# Anvil Installation Plan
+
+> Complete guide to installing the Anvil Development Framework for Claude Code.
+
+---
+
+## Executive Summary
+
+**What is Anvil?**
+A context engineering framework that transforms Claude Code from a reactive assistant into a proactive development partner through structured workflows, quality gates, and skill-based specialization.
+
+**Key Insight**: Production AI coding systems (Devin, Factory, Cursor) converge on a single generalist agent with on-demand skills — not multi-agent orchestration. Anvil implements this pattern.
+
+**Installation Time**: 6-8 hours total
+**Prerequisites**: Claude Code, Linear account, Node.js 18+
+
+---
+
+## Background: Research Foundation
+
+This framework synthesizes patterns from 15+ production systems:
+
+### Source Systems Analyzed
+
+| System | Key Extraction | Stars |
+|--------|---------------|-------|
+| Factory Droid | 6 structural guardrails | Production |
+| Beads | Task memory & ready work | 2.1k |
+| BMAD Method | 19-agent architecture → skill patterns | 3.7k |
+| SpecKit | 4-phase spec workflow | GitHub Official |
+| Claude-Mem | Session persistence | - |
+| Prompt Coach | Agent analytics | - |
+| Cursor | Rules for AI | Production |
+| Devin | Autonomous workflow | Production |
+
+### Convergent Patterns (Present in 3+ Systems)
+
+1. **Environment Validation Before Changes** — Never code on dirty state
+2. **Read Before Write** — Explore existing code before implementing
+3. **Spec-First Development** — Document before code
+4. **Evidence-Based Quality Gates** — Prove tests pass, don't just claim
+5. **Session Continuity** — Handoffs preserve context across sessions
+6. **Ready Work Calculation** — Know what's unblocked before starting
+7. **Discovered Work Capture** — File new issues immediately, don't forget
+8. **Convention Following** — Match existing patterns, not preferences
+9. **Memory Decay Management** — Archive old work, keep context lean
+
+### Architecture Decision: Single Agent + Skills
+
+**Why NOT multi-agent:**
+- Coordination overhead exceeds benefits for solo/small teams
+- Context fragmentation across agents
+- Debugging complexity
+- Production systems abandoned multi-agent
+
+**Why single agent + skills:**
+- Full context in one agent
+- Skills loaded on-demand (efficient)
+- Simpler debugging
+- Matches production patterns (Cursor, Devin)
+
+### Understanding Coordination Types
+
+**What We Removed: Role-Based Agents**
+
+Traditional multi-agent systems assign roles: Backend Agent handles database/API, Frontend Agent handles UI/components, etc.
+
+Problems with this approach:
+- Overhead deciding "is this backend or frontend?"
+- Artificial boundaries between modules
+- Complexity without proportional value for solo developers
+
+**Anvil approach**: Single generalist agent with domain skills loaded on-demand.
+
+**What We Kept: Parallel Instance Coordination**
+
+When running multiple Claude Code terminals simultaneously, you need:
+- Know what each terminal is working on
+- Prevent two terminals editing the same file
+- Share new API contracts before implementation
+- Record what each session accomplished
+
+**This is NOT about agent roles — it's about multiple instances.**
+
+Use `.claude/coordination.md` when running multiple terminals:
+
+```markdown
+## Active Sessions
+| Session ID | Started | Working On | Status |
+
+## Current Work
+| Session ID | Files/Areas | Issue |
+
+## Interface Contracts
+[New APIs posted here before implementation]
+
+## Session Log
+[Append-only activity record]
+```
+
+**When to use coordination.md:**
+- Multiple Claude Code terminals open
+- Pair programming with AI
+- Parallel feature development
+
+**When NOT needed:**
+- Single terminal workflow
+- Sequential work sessions
+
+---
+
+## What Anvil Provides
+
+### Pre-Built Components
+
+| Category | Count | Purpose |
+|----------|-------|---------|
+| Commands | 14 | Workflow orchestration (/orient, /spec, /plan, etc.) |
+| Templates | 4 | Structured documents (SPEC, PLAN, CHANGE, HANDOFF) |
+| Hooks | 5 | Session lifecycle automation |
+| Quality Gates | 4 | CodeRabbit, Pre-commit, Semgrep, CI |
+| Convention Examples | 5 | Component, hook, API, service, test patterns |
+| Skill Template | 1 | Structure for creating project-specific skills |
+
+### What You Create
+
+| Category | Purpose |
+|----------|---------|
+| Skills | Convert your specialized agents into on-demand skills |
+| product.md | Your project's mission, roadmap, success metrics |
+| constitution.md | Non-negotiable principles for your project |
+| Convention examples | Your project's actual patterns |
+
+---
+
+## Installation Paths
+
+Choose your path based on your starting point:
+
+### Path A: Fresh Install (No Existing AI Setup)
+
+| Phase | Focus | Duration |
+|-------|-------|----------|
+| 0 | Prerequisites & Backup | 30 min |
+| 1 | Global Installation | 30 min |
+| 2 | Project Installation | 1 hour |
+| 3A | Create Your First Skill | 1 hour |
+| 4 | Quality Gates Setup | 1 hour |
+| 5 | Validation & Testing | 30 min |
+
+**Total: ~4 hours**
+
+### Path B: Migration (From Multi-Agent System)
+
+| Phase | Focus | Duration |
+|-------|-------|----------|
+| 0 | Prerequisites & Backup | 30 min |
+| 1 | Global Installation | 30 min |
+| 2 | Project Installation | 1 hour |
+| 3B | Agent → Skill Conversion | 2-3 hours |
+| 4 | Quality Gates Setup | 1 hour |
+| 5 | Validation & Testing | 1 hour |
+
+**Total: 6-8 hours**
+
+> **Note**: Phases 0, 1, 2, 4, and 5 are identical for both paths. Only Phase 3 differs.
+
+---
+
+## Phase 0: Backup & Prerequisites
+
+### 0.1 Create Backup
+
+```bash
+BACKUP_DATE=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR=~/.claude-backups/$BACKUP_DATE
+
+mkdir -p $BACKUP_DIR
+cp -r ~/.claude/ $BACKUP_DIR/global-claude/
+cp -r /path/to/your/project/.claude/ $BACKUP_DIR/project-claude/
+
+echo "Backup created at: $BACKUP_DIR"
+```
+
+### 0.2 Verify Prerequisites
+
+**Required:**
+```bash
+# Check Claude Code
+claude --version  # Should work
+
+# Check Node.js
+node --version    # Should be 18+
+
+# Check Git
+git --version     # Should work
+```
+
+**Quality Gate Tools:**
+```bash
+# Install if not present
+brew install semgrep trivy gitleaks pre-commit
+
+# Verify
+semgrep --version
+trivy --version
+gitleaks version
+pre-commit --version
+```
+
+### 0.3 Verify Linear Connection
+
+**Discover your team name first** (required for commands):
+
+```bash
+# Using Linear CLI (if installed)
+python3 ~/.claude/skills/linear-skill/scripts/linear.py list-teams
+
+# Or via Linear MCP (in Claude.ai)
+# Use Linear:list_teams tool
+```
+
+Note your team name (e.g., "MyTeam") — you'll need it for `/tasks` and `/discover` commands.
+
+**Verify connection:**
+
+For Claude Desktop (MCP):
+- Settings → Connections → Linear should be connected
+- Test: Ask Claude "List my Linear issues"
+
+For Claude Code (CLI):
+```bash
+# Verify API key is set
+echo $LINEAR_API_KEY  # Should show key
+
+# Test connection
+python3 ~/.claude/skills/linear-skill/scripts/linear.py whoami
+```
+
+### 0.4 Phase 0 Checklist
+
+- [ ] Backup created at `~/.claude-backups/[DATE]/`
+- [ ] Node.js 18+ installed
+- [ ] Semgrep installed
+- [ ] Trivy installed
+- [ ] Gitleaks installed
+- [ ] Pre-commit installed
+- [ ] Linear connection verified
+
+---
+
+## Phase 1: Global Installation
+
+Install Anvil components that apply to ALL your projects.
+
+### 1.1 Create Directory Structure
+
+```bash
+# Ensure directories exist
+mkdir -p ~/.claude/{commands,templates,skills,standards,handoffs/archive,analytics}
+```
+
+### 1.2 Install Commands
+
+```bash
+# From Anvil repo
+ANVIL_REPO=/path/to/anvil-dev-framework
+
+# Copy commands (won't overwrite existing)
+cp -n $ANVIL_REPO/global/commands/*.md ~/.claude/commands/
+```
+
+**Commands Installed:**
+| Command | Purpose |
+|---------|---------|
+| `/orient` | Session startup orientation |
+| `/ready` | Calculate unblocked work |
+| `/handoff` | Generate session continuity doc |
+| `/explore` | Discovery before implementation |
+| `/spec` | Generate formal specification |
+| `/plan` | Create implementation plan |
+| `/tasks` | Create Linear issues from plan |
+| `/change` | Brownfield change proposal |
+| `/discover` | File discovered work immediately |
+| `/validate` | Environment validation checkpoint |
+| `/evidence` | Capture quality gate proof |
+| `/shard` | Break large specs into pieces |
+| `/decay-review` | Archive old work |
+| `/weekly-review` | Generate analytics report |
+
+### 1.3 Install Templates
+
+```bash
+cp -n $ANVIL_REPO/global/templates/*.md ~/.claude/templates/
+```
+
+**Templates Installed:**
+- `SPEC-template.md` — Feature specification
+- `PLAN-template.md` — Implementation plan
+- `CHANGE-template.md` — Brownfield change proposal
+- `HANDOFF-template.md` — Session continuity
+
+### 1.4 Install Skills Structure
+
+```bash
+cp -n $ANVIL_REPO/global/skills/README.md ~/.claude/skills/
+cp -rn $ANVIL_REPO/global/skills/skill-template ~/.claude/skills/
+```
+
+### 1.5 Phase 1 Checklist
+
+- [ ] Commands copied to `~/.claude/commands/`
+- [ ] Templates copied to `~/.claude/templates/`
+- [ ] Skills README and template in place
+- [ ] Verify: `ls ~/.claude/commands/*.md | wc -l` shows 14+ commands
+
+---
+
+## Phase 2: Project Installation
+
+Install Anvil components specific to your project.
+
+### 2.1 Create Project Directory Structure
+
+```bash
+cd /path/to/your/project
+
+mkdir -p .claude/{specs/current,specs/archive,changes,handoffs,examples,skills}
+```
+
+### 2.2 Install Hooks
+
+**If your project already has `.claude/hooks/`:**
+1. Compare existing hooks with Anvil's defaults
+2. Keep whichever is more complete
+3. Anvil hooks are minimal starting points — your custom hooks likely have more functionality
+4. Merge specific features you want from Anvil into your existing hooks
+
+**If no existing hooks:**
+```bash
+cp -r $ANVIL_REPO/project/hooks/* .claude/hooks/
+chmod +x .claude/hooks/*.py
+```
+
+**TTS (Text-to-Speech) Setup:**
+
+Anvil hooks include audio notifications via TTS. On Apple Silicon Macs, install espeak for best quality:
+
+```bash
+brew install espeak
+```
+
+This enables MLX Audio with Kokoro (~300ms latency, natural voice). See [docs/hooks-tts.md](hooks-tts.md) for full TTS configuration options.
+
+### 2.3 Configure Hooks
+
+Edit `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "session_start": [".claude/hooks/session_start.py --load-context"],
+    "stop": [".claude/hooks/stop.py"],
+    "pre_compact": [".claude/hooks/pre_compact.py --backup"],
+    "post_tool_use": [".claude/hooks/post_tool_use.py"],
+    "subagent_stop": [".claude/hooks/subagent_stop.py"]
+  }
+}
+```
+
+### 2.4 Install Convention Examples
+
+```bash
+cp $ANVIL_REPO/project/examples/*.tsx .claude/examples/
+cp $ANVIL_REPO/project/examples/*.ts .claude/examples/
+```
+
+Then **customize** these to match YOUR project's actual patterns.
+
+### 2.5 Create product.md
+
+Create `.claude/product.md`:
+
+```markdown
+# [Your Project Name]
+
+## Mission
+[One sentence describing what this project does and why it matters]
+
+## Core Value Propositions
+1. [Value 1]
+2. [Value 2]
+3. [Value 3]
+
+## Target Users
+- **Primary**: [Who]
+- **Secondary**: [Who]
+
+## Tech Stack
+| Layer | Technology | Rationale |
+|-------|------------|-----------|
+| Frontend | [e.g., Next.js 14] | [Why] |
+| Backend | [e.g., Supabase] | [Why] |
+| Styling | [e.g., Tailwind + shadcn] | [Why] |
+
+## Current Roadmap
+### Now (This Sprint)
+- [ ] [Current focus]
+
+### Next (Next Sprint)
+- [ ] [Upcoming work]
+
+### Later (Backlog)
+- [ ] [Future considerations]
+
+## Success Metrics
+| Metric | Current | Target |
+|--------|---------|--------|
+| [Metric 1] | [Value] | [Goal] |
+
+## Non-Goals
+- [What this project explicitly does NOT do]
+```
+
+### 2.6 Create constitution.md
+
+Create `.claude/constitution.md`:
+
+```markdown
+# [Project] Constitution
+
+> Non-negotiable principles. If Claude's actions would violate these, STOP.
+
+## Security Principles
+
+1. **Never commit secrets** — API keys, passwords, tokens must use environment variables
+2. **Always authenticate** — Protected routes must verify session
+3. **Always authorize** — Check permissions before operations
+4. **Sanitize input** — Never trust user input
+5. **Use parameterized queries** — No string concatenation in SQL
+
+## Code Quality Principles
+
+1. **Type everything** — No `any`, no implicit types
+2. **Handle all errors** — No silent failures
+3. **Test critical paths** — Auth, payments, data mutations
+4. **No console.log in production** — Use proper logging
+5. **Keep functions focused** — Single responsibility
+
+## Architecture Principles
+
+1. **Don't duplicate** — Extract shared code
+2. **Match conventions** — Follow existing patterns
+3. **Minimize dependencies** — Prefer standard library
+4. **Document decisions** — Explain non-obvious choices
+
+## Process Principles
+
+1. **Validate before coding** — Run /validate first
+2. **Spec before building** — Complex features need specs
+3. **Evidence before PRs** — Prove quality gates pass
+4. **File discovered work** — Don't forget, file it immediately
+5. **Handoff before stopping** — Preserve context for next session
+```
+
+### 2.7 Phase 2 Checklist
+
+- [ ] Directory structure created
+- [ ] Hooks installed and configured
+- [ ] Convention examples installed
+- [ ] product.md created with YOUR project details
+- [ ] constitution.md created with YOUR principles
+- [ ] settings.local.json configured for hooks
+
+---
+
+## Phase 3A: Create Your First Skill (Fresh Install)
+
+> **Skip to Phase 3B** if you're migrating from a multi-agent system.
+
+Skills are domain knowledge loaded on-demand. For a fresh install, start with one skill to understand the pattern.
+
+### 3A.1 Understand Skill Structure
+
+```
+.claude/skills/
+└── my-skill/
+    ├── SKILL.md          # Overview, triggers, when to use
+    ├── conventions.md    # Patterns and standards
+    ├── references/       # Reference documentation
+    └── examples/         # Code examples
+```
+
+### 3A.2 Create a Simple Skill
+
+Create `.claude/skills/testing-patterns/SKILL.md`:
+
+```markdown
+---
+name: Testing Patterns
+description: Vitest + React Testing Library patterns for this project
+triggers:
+  - test
+  - spec
+  - vitest
+  - testing library
+version: 1.0.0
+---
+
+# Testing Patterns
+
+## When to Use
+Load this skill when writing or reviewing tests.
+
+## Test Structure
+[Your project's test conventions]
+
+## Mocking Patterns
+[How you handle mocks]
+
+## Common Assertions
+[Frequently used assertions]
+
+## Checklist
+- [ ] Tests isolated (no shared state)
+- [ ] Descriptive test names
+- [ ] Edge cases covered
+- [ ] Mocks cleaned up
+```
+
+### 3A.3 Test Skill Loading
+
+Ask Claude: "Help me write tests for my user authentication flow"
+
+Verify it references your testing-patterns skill.
+
+### 3A.4 Phase 3A Checklist
+
+- [ ] First skill created
+- [ ] Skill loads when triggered
+- [ ] Understand pattern for future skills
+
+---
+
+## Phase 3B: Agent → Skill Conversion (Migration)
+
+> **Skip to Phase 4** if you did Phase 3A (fresh install).
+
+Convert your specialized agents into on-demand skills.
+
+### 3B.1 Why Convert?
+
+| Agents (Old) | Skills (New) |
+|--------------|--------------|
+| Always in context | Loaded on-demand |
+| Fixed prompts | Flexible activation |
+| Coordination overhead | Direct execution |
+| Context fragmentation | Full context available |
+
+### 3B.2 Conversion Process
+
+For each agent (Backend, Frontend, Core, Infra, etc.):
+
+**Step 1: Identify Core Knowledge**
+- What domain expertise does this agent have?
+- What patterns/conventions does it enforce?
+- What decisions does it make?
+
+**Step 2: Extract into Skill**
+
+Create `.claude/skills/[domain]-patterns/SKILL.md`:
+
+```markdown
+---
+name: [Domain] Patterns
+description: [What this skill provides]
+triggers:
+  - [keyword1]
+  - [keyword2]
+version: 1.0.0
+---
+
+# [Domain] Patterns
+
+## When to Use
+[When Claude should load this skill]
+
+## Key Concepts
+[Domain knowledge extracted from agent]
+
+## Patterns
+[Specific patterns the agent enforced]
+
+## Decision Framework
+[How to make decisions in this domain]
+
+## Anti-Patterns
+[What the agent avoided]
+
+## Checklist
+[Verification steps from agent]
+```
+
+**Step 3: Move Reference Files**
+
+If your agent referenced specific files, move them to the skill:
+
+```
+.claude/skills/backend-patterns/
+├── SKILL.md
+├── examples/
+│   ├── api-route.ts
+│   └── service.ts
+└── references/
+    └── security-checklist.md
+```
+
+### 3B.3 Example: Backend Agent → Skill
+
+**Before (Agent):**
+```markdown
+# Backend Agent
+You are a senior backend engineer...
+Always check authentication...
+Use parameterized queries...
+```
+
+**After (Skill):**
+```markdown
+---
+name: Backend Security Patterns
+triggers: [api, route, database, auth, security]
+---
+
+# Backend Security Patterns
+
+## Authentication Patterns
+- Verify session at route entry
+- Use httpOnly cookies
+- Implement CSRF protection
+
+## Database Patterns
+- Parameterized queries only
+- Row Level Security enabled
+- Connection pooling
+
+## API Design
+- RESTful conventions
+- Consistent error responses
+- Rate limiting on sensitive endpoints
+
+## Checklist
+- [ ] Auth check at route entry
+- [ ] Input validation complete
+- [ ] Error handling in place
+- [ ] Audit logging for mutations
+```
+
+### 3B.4 Conversion Checklist
+
+- [ ] Backend agent → backend-patterns skill
+- [ ] Frontend agent → frontend-patterns skill
+- [ ] Core agent → utility-patterns skill
+- [ ] Infra agent → devops-patterns skill
+- [ ] Original agents archived (not deleted)
+- [ ] Skills tested with sample queries
+
+---
+
+## Phase 4: Quality Gates Setup
+
+### 4.1 Install CodeRabbit
+
+Create `.coderabbit.yaml` in project root:
+
+```bash
+cp $ANVIL_REPO/quality-gates/.coderabbit.yaml .
+```
+
+Customize path instructions for your project structure.
+
+### 4.2 Install Pre-commit
+
+Create `.pre-commit-config.yaml`:
+
+```bash
+cp $ANVIL_REPO/quality-gates/.pre-commit-config.yaml .
+pre-commit install
+```
+
+> **Note on JSON Check**: The `check-json` pre-commit hook will fail on TypeScript config files (tsconfig.json) because they use JSONC (JSON with Comments). This is expected. The Anvil config excludes these files:
+> ```yaml
+> - id: check-json
+>   exclude: '(tsconfig.*\.json$|COPY_.*\.json$)'
+> ```
+
+### 4.3 Install Semgrep Rules
+
+```bash
+mkdir -p .semgrep/rules
+cp $ANVIL_REPO/quality-gates/.semgrep/rules/*.yaml .semgrep/rules/
+```
+
+### 4.4 Install CI Pipeline
+
+```bash
+mkdir -p .github/workflows
+cp $ANVIL_REPO/quality-gates/.github/workflows/ci.yaml .github/workflows/
+```
+
+Customize for your project's test commands.
+
+### 4.5 Phase 4 Checklist
+
+- [ ] CodeRabbit configured
+- [ ] Pre-commit hooks installed
+- [ ] Semgrep rules in place
+- [ ] CI pipeline configured
+- [ ] Test: `pre-commit run --all-files`
+
+---
+
+## Phase 5: Validation & Testing
+
+### 5.0 Quick Validation
+
+Run these commands to verify installation:
+
+```bash
+# Global commands (should be 14+)
+ls ~/.claude/commands/*.md | wc -l
+
+# Templates (should be 4)
+ls ~/.claude/templates/*-template.md | wc -l
+
+# Project structure
+ls .claude/{specs,changes,handoffs,examples,skills}
+
+# Quality gates
+pre-commit run --all-files
+
+# Linear CLI
+python3 ~/.claude/skills/linear-skill/scripts/linear.py whoami
+```
+
+If any fail, check the relevant phase above.
+
+### 5.1 Test Session Workflow
+
+1. Start new Claude Code session
+2. Run `/orient` — Should show git state, ready work
+3. Pick a task from ready work
+4. Run `/validate` — Should pass all checks
+5. Run `/explore` — Should analyze related code
+6. Create small change
+7. Run `/evidence` — Should capture quality proof
+8. Run `/handoff` — Should generate continuity doc
+
+### 5.2 Test Skill Loading
+
+1. Ask Claude about a backend security question
+2. Verify it references backend-patterns skill
+3. Ask about frontend component structure
+4. Verify it references frontend-patterns skill
+
+### 5.3 Test Quality Gates
+
+```bash
+# Pre-commit
+pre-commit run --all-files
+
+# Semgrep
+semgrep --config .semgrep/rules/
+
+# Full CI (if GitHub Actions)
+# Push to branch and verify pipeline runs
+```
+
+### 5.4 Validate Linear Integration
+
+1. Run `/tasks` on a simple plan
+2. Verify issues created with correct:
+   - Labels
+   - Priority
+   - Dependencies (blocked-by)
+   - Description format
+
+### 5.5 Phase 5 Checklist
+
+- [ ] /orient works correctly
+- [ ] /validate passes
+- [ ] /explore reads files properly
+- [ ] /evidence captures output
+- [ ] /handoff generates document
+- [ ] Skills load on relevant queries
+- [ ] Pre-commit hooks work
+- [ ] Linear integration works
+
+---
+
+## Post-Installation: Daily Workflow
+
+### Session Start
+```
+/orient
+```
+→ See git state, ready work, handoff context
+
+### Before Any Code
+```
+/validate
+```
+→ Ensure clean environment
+
+### New Feature
+```
+/explore → /spec → /plan → /tasks → implement → /evidence
+```
+
+### Brownfield Change
+```
+/explore → /change → /plan → /tasks → implement → /evidence
+```
+
+### Discovered Work
+```
+/discover "Brief description of what was found"
+```
+→ Creates Linear issue, continue original task
+
+### Session End
+```
+/handoff
+```
+→ Preserves context for next session
+
+### Weekly Maintenance
+```
+/weekly-review
+/decay-review
+```
+→ Analytics and archive cleanup
+
+---
+
+## Troubleshooting
+
+### Commands Not Found
+Verify commands are in `~/.claude/commands/`:
+```bash
+ls ~/.claude/commands/*.md
+```
+
+### Hooks Not Running
+Check `.claude/settings.local.json` syntax and paths.
+
+### Skills Not Loading
+Verify skill triggers match your queries. Add more trigger keywords.
+
+### Linear Issues Not Creating
+Check Linear MCP connection or API key. Test with simple query first.
+
+### Pre-commit Failing
+Run `pre-commit run --all-files` to see specific failures.
+
+---
+
+## File Structure Reference
+
+### Global (~/.claude/)
+```
+~/.claude/
+├── commands/           # 14 Anvil commands
+│   ├── orient.md
+│   ├── ready.md
+│   ├── handoff.md
+│   ├── explore.md
+│   ├── spec.md
+│   ├── plan.md
+│   ├── tasks.md
+│   ├── change.md
+│   ├── discover.md
+│   ├── validate.md
+│   ├── evidence.md
+│   ├── shard.md
+│   ├── decay-review.md
+│   └── weekly-review.md
+├── templates/          # 4 document templates
+│   ├── SPEC-template.md
+│   ├── PLAN-template.md
+│   ├── CHANGE-template.md
+│   └── HANDOFF-template.md
+├── skills/
+│   ├── README.md
+│   └── skill-template/
+└── handoffs/
+    └── archive/
+```
+
+### Project (.claude/)
+```
+.claude/
+├── product.md          # Mission, roadmap, metrics
+├── constitution.md     # Non-negotiable principles
+├── settings.local.json # Hook configuration
+├── hooks/              # Session lifecycle
+│   ├── session_start.py
+│   ├── stop.py
+│   ├── pre_compact.py
+│   ├── post_tool_use.py
+│   └── subagent_stop.py
+├── skills/             # Project-specific skills
+│   ├── backend-patterns/
+│   ├── frontend-patterns/
+│   └── ...
+├── examples/           # Convention files
+│   ├── component-template.tsx
+│   ├── hook-template.ts
+│   └── ...
+├── specs/
+│   ├── current/        # Active specs
+│   └── archive/        # Completed specs
+├── changes/            # Change proposals
+└── handoffs/           # Session handoffs
+```
+
+### Project Root
+```
+project/
+├── .coderabbit.yaml    # CodeRabbit config
+├── .pre-commit-config.yaml
+├── .semgrep/
+│   └── rules/
+└── .github/
+    └── workflows/
+        └── ci.yaml
+```
+
+---
+
+## Success Criteria
+
+After installation, you should be able to:
+
+1. ✅ Start sessions with full context via `/orient`
+2. ✅ Validate environment before changes via `/validate`
+3. ✅ Follow spec-driven workflow for new features
+4. ✅ Capture discovered work without losing focus
+5. ✅ Preserve context across sessions via `/handoff`
+6. ✅ Load domain skills on-demand
+7. ✅ Pass quality gates before PR creation
+8. ✅ Track work in Linear with proper structure
+
+---
+
+## Appendix: Pattern Reference
+
+### Droid Patterns (Factory)
+1. Environment validation before changes
+2. Read before write
+3. Living task management
+4. Evidence-based PR gates
+5. Convention following
+6. Multi-stage verification
+
+### Beads Patterns
+1. Ready work calculation
+2. Discovered-from linking
+3. Session handoffs
+4. Memory decay
+5. Quick orientation
+
+### Spec-Driven Patterns (BMAD/SpecKit)
+1. Explore → Spec → Plan → Tasks
+2. Document sharding for large specs
+3. Phase gates between stages
+4. Gherkin acceptance criteria
+5. Brownfield change proposals
+
+### Memory Patterns
+1. 5-layer memory hierarchy
+2. Handoff continuity
+3. Decay management
+4. Context-aware loading