anvil-dev-framework 0.1.6

package/docs/implementation-guide.md

@@ -0,0 +1,810 @@
+# Anvil Implementation Guide
+
+> Complete step-by-step guide to implementing the Anvil Development Framework.
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Prerequisites](#2-prerequisites)
+3. [Phase 0: Preparation](#3-phase-0-preparation)
+4. [Phase 1: Foundation Layer](#4-phase-1-foundation-layer)
+5. [Phase 2: Memory & Continuity](#5-phase-2-memory--continuity)
+6. [Phase 3: Spec-Driven Workflow](#6-phase-3-spec-driven-workflow)
+7. [Phase 4: Quality Gates](#7-phase-4-quality-gates)
+8. [Phase 5: Feedback Loops](#8-phase-5-feedback-loops)
+9. [Phase 6: Optimization](#9-phase-6-optimization)
+10. [Troubleshooting](#10-troubleshooting)
+
+---
+
+## 1. Overview
+
+### Implementation Timeline
+
+| Phase | Focus | Duration | Effort |
+|-------|-------|----------|--------|
+| 0 | Preparation | 1 day | 2-3 hours |
+| 1 | Foundation | 1 week | 8-10 hours |
+| 2 | Memory & Continuity | 1 week | 6-8 hours |
+| 3 | Spec-Driven Workflow | 1 week | 10-12 hours |
+| 4 | Quality Gates | 1 week | 4-6 hours |
+| 5 | Feedback Loops | 1 week | 4-6 hours |
+| 6 | Optimization | Ongoing | 2-3 hours/week |
+
+**Total Initial Investment**: 35-45 hours over 6 weeks
+
+### Guiding Principles
+
+1. **Incremental Value**: Each phase delivers standalone value
+2. **Backward Compatible**: Existing workflows continue working
+3. **Measurable Progress**: Clear success criteria per phase
+4. **Reversible Changes**: Can roll back any phase
+5. **Documentation-First**: Write docs/templates, then implement
+
+---
+
+## 2. Prerequisites
+
+### Required Tools
+
+| Tool | Purpose | Installation |
+|------|---------|--------------|
+| Claude Code | AI coding assistant | Anthropic subscription |
+| Node.js 18+ | Runtime | `brew install node` |
+| Git | Version control | Pre-installed on macOS |
+| Linear | Task management | linear.app account |
+
+### Quality Gate Tools
+
+| Tool | Purpose | Installation |
+|------|---------|--------------|
+| Semgrep | SAST scanning | `brew install semgrep` |
+| Trivy | Vulnerability scanning | `brew install trivy` |
+| Gitleaks | Secrets detection | `brew install gitleaks` |
+| Pre-commit | Git hooks | `brew install pre-commit` |
+
+### Optional Tools
+
+| Tool | Purpose | Cost |
+|------|---------|------|
+| CodeRabbit | AI code review | $25/mo |
+| Claude-Mem | Session memory | Free (plugin) |
+| Prompt Coach | Analytics | Free (skill) |
+
+---
+
+## 3. Phase 0: Preparation
+
+**Objective**: Create safe environment, install prerequisites, create backup.
+
+### 3.1 Backup Existing Configuration
+
+```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/project/.claude/ $BACKUP_DIR/project-claude/
+
+echo "Backup created at: $BACKUP_DIR"
+```
+
+### 3.2 Install Prerequisites
+
+```bash
+# Quality gate tools
+brew install semgrep trivy gitleaks pre-commit
+
+# Verify installations
+semgrep --version
+trivy --version
+gitleaks version
+pre-commit --version
+```
+
+### 3.3 Create Implementation Branch
+
+```bash
+cd /path/to/your/project
+git stash  # if needed
+git checkout -b feature/anvil-implementation
+git push -u origin feature/anvil-implementation
+```
+
+### 3.4 Verify Linear Connection
+
+For Claude Desktop (MCP):
+- Check Claude settings for Linear MCP connection
+- Test: "List my Linear issues"
+
+For Claude Code (CLI skill):
+- Ensure `LINEAR_API_KEY` is set in `~/.zshenv`
+- Test: `python3 .claude/skills/linear-skill/scripts/linear.py whoami`
+
+### 3.5 Phase 0 Checklist
+
+- [ ] Backup created at `~/.claude-backups/[DATE]/`
+- [ ] Semgrep installed and working
+- [ ] Trivy installed and working
+- [ ] Gitleaks installed and working
+- [ ] Pre-commit installed and working
+- [ ] Implementation branch created
+- [ ] Linear connection verified
+
+---
+
+## 4. Phase 1: Foundation Layer
+
+**Objective**: Establish directory structure, core documentation, and basic commands.
+
+### 4.1 Global Directory Structure
+
+Create in `~/.claude/`:
+
+```bash
+mkdir -p ~/.claude/{standards,templates,commands,skills,handoffs,analytics}
+```
+
+Final structure:
+```
+~/.claude/
+├── CLAUDE.md              # Personal defaults
+├── standards/             # Universal coding standards
+├── templates/             # Reusable spec templates
+├── commands/              # Global slash commands
+├── skills/                # Claude Code skills
+├── handoffs/              # Session handoff archive
+│   └── archive/
+└── analytics/             # Metrics and reports
+```
+
+### 4.2 Project Directory Structure
+
+Create in your project's `.claude/`:
+
+```bash
+mkdir -p .claude/{specs/{current,archive},changes,handoffs,examples}
+```
+
+Final structure:
+```
+.claude/
+├── CLAUDE.md              # Project context
+├── constitution.md        # Non-negotiable principles
+├── product.md             # Mission & roadmap
+├── specs/
+│   ├── current/           # Active specs
+│   └── archive/           # Completed specs
+├── changes/               # Brownfield proposals
+├── handoffs/              # Project handoffs
+├── examples/              # Convention examples
+└── commands/              # Project commands
+```
+
+### 4.3 Core Documentation Files
+
+#### 4.3.1 Project CLAUDE.md
+
+See `project/CLAUDE.md.template` for the full template. Key sections:
+
+- Project Overview
+- Tech Stack
+- Agent Approach (startup, validation, implementation)
+- Slash Commands reference
+- Linear Workflow
+- File Conventions
+- Error Handling Pattern
+- Key Files Reference
+
+#### 4.3.2 Constitution
+
+See `project/constitution.md.template`. Must include:
+
+- Security Principles (5)
+- Code Quality Principles (5)
+- Architecture Principles (4)
+- Process Principles (5)
+- What We Will NOT Do
+
+#### 4.3.3 Product Definition
+
+See `project/product.md.template`. Must include:
+
+- Mission statement
+- Core Value Propositions
+- Target Users
+- Tech Stack Rationale
+- Current Roadmap
+- Success Metrics
+
+### 4.4 Basic Commands
+
+#### /validate Command
+
+Purpose: Environment validation checkpoint before any code changes.
+
+Steps:
+1. Check git status (must be clean)
+2. Check branch (must not be main)
+3. Run `npm ci` (dependencies)
+4. Run `npm test` (baseline)
+5. Run `npm run typecheck` (types)
+
+If ANY step fails → STOP and report.
+
+#### /evidence Command
+
+Purpose: Capture quality gate proof before creating PR.
+
+Steps:
+1. Run lint, capture full output
+2. Run typecheck, capture full output
+3. Run tests, capture full output
+4. Run git status, list changed files
+
+Include evidence block in PR description.
+
+### 4.5 Convention Examples
+
+Create example files in `.claude/examples/`:
+
+- `component.tsx` — React component patterns
+- `api-route.ts` — API route patterns
+- `hook.ts` — Custom hook patterns
+- `test.test.ts` — Test patterns
+
+### 4.6 Phase 1 Checklist
+
+- [ ] Global directory structure created
+- [ ] Project directory structure created
+- [ ] CLAUDE.md (v5) created
+- [ ] constitution.md created
+- [ ] product.md created
+- [ ] /validate command created
+- [ ] /evidence command created
+- [ ] Convention examples created
+- [ ] All changes committed
+
+---
+
+## 5. Phase 2: Memory & Continuity
+
+**Objective**: Install session memory, handoff system, and orientation protocols.
+
+### 5.1 Claude-Mem Installation
+
+```bash
+# If available via Claude Code marketplace
+# OR manual installation:
+cd ~/.claude/tools
+git clone https://github.com/thedotmack/claude-mem.git
+cd claude-mem && npm install && npm run init
+```
+
+### 5.2 Handoff System
+
+#### /handoff Command
+
+Purpose: Generate session continuity document.
+
+Output structure:
+```markdown
+---
+session_date: YYYY-MM-DD
+session_time: HH:MM - HH:MM
+branch: [branch name]
+---
+
+# Session Handoff: [Date]
+
+## Session Summary
+## Completed This Session
+## In Progress
+## Discovered Work Filed
+## Recommended Next Task
+## Critical Context for Next Session
+## Environment State
+## Files Modified This Session
+```
+
+Save to: `.claude/handoffs/[YYYY-MM-DD]-[topic].md`
+
+#### /orient Command
+
+Purpose: Session startup orientation.
+
+Steps:
+1. Check for recent handoff (< 48 hours)
+2. Check git state
+3. Query Linear for ready work
+4. Calculate ready work (no blockers)
+5. Present options, await direction
+
+#### /ready Command
+
+Purpose: Calculate ready work from Linear.
+
+Algorithm:
+1. Fetch all active issues
+2. Filter issues where all blockers are Done
+3. Sort by priority (P0 first), then age (oldest first)
+4. Present ready work list
+
+### 5.3 Memory Decay Protocol
+
+#### /decay-review Command
+
+Purpose: Weekly maintenance to archive old work.
+
+Steps:
+1. Find issues: status=Done, completed >30 days ago
+2. Add archive summary comment
+3. Archive the issue
+4. Clean handoff directory (keep last 7)
+
+Target metrics:
+- Active issues: < 50
+- Active handoffs: ≤ 7
+
+### 5.4 Phase 2 Checklist
+
+- [ ] Claude-Mem installed (optional)
+- [ ] /handoff command created
+- [ ] /orient command created
+- [ ] /ready command created
+- [ ] /decay-review command created
+- [ ] Handoff template tested
+- [ ] Orientation workflow tested
+
+---
+
+## 6. Phase 3: Spec-Driven Workflow
+
+**Objective**: Implement phase gates, document sharding, brownfield changes.
+
+### 6.1 Phase Gate Commands
+
+#### /explore Command
+
+Purpose: Discovery phase before any new feature.
+
+Steps:
+1. Clarify request with user
+2. Search for existing related code
+3. Read related files, note patterns
+4. Check existing specs
+5. Review architecture constraints
+
+Output: Exploration Report with recommendations
+
+**Gate**: Wait for user confirmation before /spec
+
+#### /spec Command
+
+Purpose: Generate formal specification.
+
+Output structure:
+```markdown
+---
+spec_id: SPEC-YYYYMMDD-XXX
+title: [Title]
+status: draft | review | approved | implemented | archived
+---
+
+# [Feature Title]
+
+## Overview
+## Requirements (Functional & Non-Functional)
+## User Scenarios (Gherkin format)
+## Technical Considerations
+## Out of Scope
+## Open Questions
+```
+
+**Gate**: All open questions must be answered, status must be 'approved'
+
+#### /plan Command
+
+Purpose: Create implementation plan from approved spec.
+
+Output structure:
+```markdown
+---
+plan_id: PLAN-YYYYMMDD-XXX
+spec_id: [reference]
+estimated_hours: X
+---
+
+## Approach
+## Implementation Phases
+## File Changes
+## Testing Strategy
+## Risks and Mitigations
+## Rollback Plan
+```
+
+**Gate**: Plan must be approved before /tasks
+
+#### /tasks Command
+
+Purpose: Create Linear issues from approved plan.
+
+Rules:
+- Each task completable in 1-4 hours
+- Each task has clear acceptance criteria
+- Each task independently verifiable
+- Set dependencies (blocked by)
+
+### 6.2 Document Sharding
+
+#### /shard Command
+
+Purpose: Break large specs (>2000 tokens) into atomic pieces.
+
+Strategy:
+```
+.claude/specs/current/
+├── SPEC-001-user-auth.md           # Master spec
+├── SPEC-001-user-auth/
+│   ├── epic-001-registration.md    # Shard 1
+│   ├── epic-002-login.md           # Shard 2
+│   └── epic-003-password-reset.md  # Shard 3
+```
+
+Benefits:
+- ~80% token savings per task
+- Load only what's needed
+
+### 6.3 Brownfield Change Tracking
+
+#### /change Command
+
+Purpose: Create change proposal for modifying existing features.
+
+Output structure:
+```markdown
+---
+change_id: CHANGE-YYYYMMDD-XXX
+affects_specs: [list]
+---
+
+## Summary
+## Motivation
+## Proposed Changes
+  - MODIFIED: [requirement]
+  - ADDED: [requirement]
+  - REMOVED: [requirement]
+## Impact Analysis
+## Migration Required
+## Rollback Plan
+```
+
+### 6.4 Discovery Pattern
+
+#### /discover Command
+
+Purpose: File discovered work during implementation.
+
+Usage: `/discover [title]`
+
+Creates Linear issue with:
+- Parent issue reference
+- Discovery context
+- Recommended priority
+- `discovered` label
+
+### 6.5 Gherkin Scenarios
+
+Use GIVEN/WHEN/THEN format for all acceptance criteria:
+
+```gherkin
+#### Scenario: Successful user login
+
+**Context**:
+- **GIVEN** a registered user with email "user@example.com"
+- **AND** the user has valid password
+
+**Action**:
+- **WHEN** the user submits login form with correct credentials
+
+**Outcome**:
+- **THEN** a new session is created
+- **AND** user is redirected to dashboard
+```
+
+### 6.6 Phase 3 Checklist
+
+- [ ] /explore command created
+- [ ] /spec command created
+- [ ] /plan command created
+- [ ] /tasks command created
+- [ ] /shard command created
+- [ ] /change command created
+- [ ] /discover command created
+- [ ] Gherkin scenario template created
+- [ ] Full workflow tested (explore → spec → plan → tasks)
+
+---
+
+## 7. Phase 4: Quality Gates
+
+**Objective**: Configure automated quality gates and CI pipeline.
+
+### 7.1 CodeRabbit Configuration
+
+Create `.coderabbit.yaml`:
+
+```yaml
+reviews:
+  auto_review:
+    enabled: true
+    drafts: false
+  profile: assertive
+  path_instructions:
+    - path: "src/app/api/**"
+      instructions: |
+        Review for: input validation, auth checks, error handling,
+        rate limiting, response consistency, SQL injection prevention
+    - path: "src/components/**"
+      instructions: |
+        Review for: accessibility, performance, type safety,
+        error boundaries, loading/error states
+```
+
+### 7.2 Semgrep Configuration
+
+Create `.semgrep.yaml` and custom rules in `.semgrep/rules/`:
+
+Key rules:
+- `api-route-missing-auth` — Detect routes without auth checks
+- `no-console-log` — Remove console.log before production
+- `no-any-type` — Avoid `any` type usage
+- `unhandled-promise` — Detect unhandled promise rejections
+- `hardcoded-secret` — Detect potential secrets
+
+### 7.3 Pre-commit Configuration
+
+Create `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: lint
+        name: ESLint
+        entry: npm run lint
+        language: system
+        pass_filenames: false
+      - id: typecheck
+        name: TypeScript Check
+        entry: npm run typecheck
+        language: system
+        pass_filenames: false
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.0
+    hooks:
+      - id: gitleaks
+```
+
+Install hooks:
+```bash
+pre-commit install
+```
+
+### 7.4 GitHub Actions CI
+
+Create `.github/workflows/ci.yaml` with jobs:
+- `lint-and-type` — ESLint + TypeScript
+- `test` — Run tests with coverage
+- `security` — Semgrep + Trivy + Gitleaks
+- `build` — Verify build succeeds
+
+### 7.5 Phase 4 Checklist
+
+- [ ] CodeRabbit configuration created
+- [ ] Semgrep configuration and rules created
+- [ ] Pre-commit configuration created
+- [ ] Pre-commit hooks installed
+- [ ] GitHub Actions CI workflow created
+- [ ] All quality gates tested
+
+---
+
+## 8. Phase 5: Feedback Loops
+
+**Objective**: Install analytics and establish continuous improvement.
+
+### 8.1 Prompt Coach Installation
+
+```bash
+cd ~/.claude/skills
+git clone https://github.com/hancengiz/claude-code-prompt-coach-skill.git prompt-coach
+```
+
+### 8.2 Analytics Dashboard
+
+Create `~/.claude/analytics/` structure:
+```
+analytics/
+├── weekly/           # Weekly reports
+├── monthly/          # Monthly summaries
+├── prompts/          # Prompt improvements
+└── metrics.json      # Raw metrics
+```
+
+### 8.3 Weekly Review Process
+
+#### /weekly-review Command
+
+Steps:
+1. Run Prompt Coach analysis
+2. Gather metrics from Linear, GitHub, CodeRabbit
+3. Generate weekly report
+4. Apply improvements to CLAUDE.md
+5. Document learnings
+
+### 8.4 Improvement Documentation
+
+Track in `~/.claude/analytics/prompts/improvements.md`:
+
+```markdown
+### [Date] - [Category]
+
+**Before**: [Original prompt pattern]
+**After**: [Improved prompt pattern]
+**Improvement**: [What changed]
+**Impact**: [Measured improvement]
+```
+
+### 8.5 Phase 5 Checklist
+
+- [ ] Prompt Coach installed
+- [ ] Analytics directory structure created
+- [ ] /weekly-review command created
+- [ ] Improvement log started
+- [ ] First weekly review completed
+
+---
+
+## 9. Phase 6: Optimization
+
+**Objective**: Measure effectiveness, tune processes, establish maintenance.
+
+### 9.1 Maintenance Schedule
+
+**Daily**:
+- /orient at session start
+- /handoff at session end
+- File discovered work immediately
+
+**Weekly**:
+- /weekly-review
+- /decay-review
+- Update metrics dashboard
+
+**Monthly**:
+- Generate monthly summary
+- Review and update CLAUDE.md
+- Archive old specs/handoffs
+
+**Quarterly**:
+- Full framework review
+- Assess new tools/patterns
+- Major documentation revision
+
+### 9.2 Metrics Collection
+
+Track:
+- Orientation time (target: <2 min)
+- Ready work accuracy (target: >95%)
+- Phase gate compliance (target: 100%)
+- First-pass PR rate (target: >70%)
+- Clarification rate (target: <15%)
+
+### 9.3 Framework Evolution
+
+Document changes in `~/.claude/docs/framework-evolution.md`:
+
+1. Identify improvement
+2. Document proposal
+3. Test in isolation
+4. Roll out or reject
+5. Update documentation
+
+---
+
+## 10. Troubleshooting
+
+### Common Issues
+
+#### Linear API Key Not Working
+
+```bash
+# Check if set
+echo $LINEAR_API_KEY
+
+# If not set, add to ~/.zshenv
+echo 'export LINEAR_API_KEY="your_key"' >> ~/.zshenv
+source ~/.zshenv
+```
+
+#### Pre-commit Hooks Failing
+
+```bash
+# Skip hooks temporarily
+git commit --no-verify
+
+# Fix hooks
+pre-commit run --all-files
+
+# Reinstall
+pre-commit uninstall && pre-commit install
+```
+
+#### Semgrep Rules Not Running
+
+```bash
+# Test rules directly
+semgrep --config .semgrep.yaml src/
+
+# Check for syntax errors
+semgrep --validate --config .semgrep.yaml
+```
+
+### Rollback Procedures
+
+#### Full Rollback
+
+```bash
+BACKUP_DIR=~/.claude-backups/[DATE]
+
+# Restore global
+rm -rf ~/.claude/
+cp -r $BACKUP_DIR/global-claude ~/.claude/
+
+# Restore project
+rm -rf .claude/
+cp -r $BACKUP_DIR/project-claude .claude/
+```
+
+#### Phase-Specific Rollback
+
+See individual phase sections for targeted rollback instructions.
+
+---
+
+## Quick Reference
+
+### Essential Commands
+
+| Command | Purpose | When |
+|---------|---------|------|
+| `/orient` | Session startup | Start of session |
+| `/ready` | Find work | Before selecting task |
+| `/validate` | Check environment | Before changes |
+| `/explore` | Discovery | Before new feature |
+| `/spec` | Create spec | After exploration |
+| `/plan` | Create plan | After spec approved |
+| `/tasks` | Create issues | After plan approved |
+| `/discover` | File found work | During implementation |
+| `/evidence` | Capture proof | Before PR |
+| `/handoff` | End session | End of session |
+
+### Daily Workflow
+
+```
+/orient → /ready → /validate → [work] → /discover → /evidence → /handoff
+```
+
+### Phase Gate Flow
+
+```
+/explore → /spec → [approve] → /plan → [approve] → /tasks → [implement]
+```
+
+---
+
+*For additional help, consult the pattern documentation in `docs/patterns/`.*