anvil-dev-framework 0.1.6

package/VERSION

@@ -0,0 +1 @@
+0.1.6.0

package/docs/ANVIL-REPO-IMPLEMENTATION-PLAN.md

@@ -0,0 +1,441 @@
+# Anvil Repo Implementation Plan
+
+> Based on INSTALLATION-RETRO-NOTES.md from 2025-12-17 installation
+
+---
+
+## Overview
+
+This plan addresses all findings from the baby-gift-garden installation. Work is prioritized by impact and organized into logical commits.
+
+**Repo location**: `/Users/alexandercahiz/Projects/anvil-dev-framework/`
+
+---
+
+## Phase 1: Commit Current Fixes (Already Done)
+
+These fixes were made during installation. Just need to commit.
+
+### Files to commit:
+```
+global/commands/orient.md
+global/commands/ready.md
+global/commands/discover.md
+global/commands/tasks.md
+global/commands/decay-review.md
+quality-gates/.pre-commit-config.yaml
+quality-gates/.semgrep/rules/anvil-rules.yaml
+project/coordination.md
+docs/INSTALLATION-RETRO-NOTES.md
+```
+
+### Commit message:
+```
+fix: apply learnings from baby-gift-garden installation
+
+- Linear CLI: Use explicit bash syntax in commands (list-issues --status)
+- Pre-commit: Fix deprecated stage names (commit → pre-commit)
+- Semgrep: Simplify rules to reduce false positives (187 → 99 lines)
+- Add coordination.md template for parallel instance tracking
+- Add comprehensive installation retro notes
+```
+
+---
+
+## Phase 2: Update INSTALLATION.md (High Priority)
+
+### 2.1 Split Installation Paths
+
+**Current**: Single linear path assumes migration from multi-agent
+**New**: Two paths based on starting point
+
+```markdown
+## Installation Paths
+
+### Path A: Fresh Install (No Existing Setup)
+- Phase 0: Prerequisites
+- Phase 1: Global Installation
+- Phase 2: Project Installation
+- Phase 3: Create Your First Skill (NEW)
+- Phase 4: Quality Gates
+- Phase 5: Validation
+
+### Path B: Migration (From Multi-Agent System)
+- Phase 0: Prerequisites  
+- Phase 1: Global Installation
+- Phase 2: Project Installation
+- Phase 3: Archive Multi-Agent System (RENAMED)
+- Phase 4: Quality Gates
+- Phase 5: Validation
+```
+
+### 2.2 Add Linear Team Discovery Step
+
+**Location**: Phase 0, Prerequisites
+
+```markdown
+### Verify Linear Connection
+
+1. First, discover your team name:
+   ```bash
+   # Using Linear CLI
+   python3 ~/.claude/skills/linear-skill/scripts/linear.py list-teams
+   
+   # Or via Linear MCP (in Claude.ai)
+   # Use Linear:list_teams tool
+   ```
+
+2. Note your team name (e.g., "MyTeam") — you'll need it for commands
+
+3. Verify connection:
+   ```bash
+   python3 ~/.claude/skills/linear-skill/scripts/linear.py whoami
+   ```
+```
+
+### 2.3 Add Hooks Merge Strategy
+
+**Location**: Phase 2, Project Installation
+
+```markdown
+### Hooks Installation
+
+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
+
+If no existing hooks:
+1. Copy Anvil hooks to `.claude/hooks/`
+2. Customize as needed for your project
+```
+
+### 2.4 Add Validation Checklist
+
+**Location**: Phase 5
+
+```markdown
+### 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
+```
+```
+
+### 2.5 Add JSONC Note
+
+**Location**: Phase 4, Quality Gates
+
+```markdown
+### 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$)'
+```
+```
+
+---
+
+## Phase 3: Add Role vs Parallel Coordination Section (High Priority)
+
+### Location: New section in INSTALLATION.md or separate ARCHITECTURE.md
+
+### Content:
+
+```markdown
+## Understanding Coordination Types
+
+### What We Removed: Role-Based Agents
+
+Traditional multi-agent systems assign roles:
+- Backend Agent handles database/API work
+- Frontend Agent handles UI/components
+- etc.
+
+**Problems:**
+- 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.**
+
+### coordination.md
+
+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:**
+- Multiple Claude Code terminals open
+- Pair programming with AI
+- Parallel feature development
+
+**When NOT needed:**
+- Single terminal workflow
+- Sequential work sessions
+```
+
+---
+
+## Phase 4: Create Phase 3A - First Skill Tutorial (Medium Priority)
+
+### Location: New file `docs/FIRST-SKILL-TUTORIAL.md`
+
+### Content outline:
+
+```markdown
+# Creating Your First Skill
+
+## When to Create a Skill vs Sub-Agent
+
+**Create a SKILL when:**
+- Domain knowledge needs to be referenced repeatedly
+- Information is relatively static (conventions, patterns, references)
+- Multiple sub-agents might need this knowledge
+
+**Create a SUB-AGENT when:**
+- Task requires multi-step execution
+- Work involves tool calls and decisions
+- Task is self-contained with clear completion
+
+## Skill Structure
+
+```
+.claude/skills/
+└── my-first-skill/
+    ├── SKILL.md          # Overview and when to use
+    ├── conventions.md    # Patterns and standards
+    ├── references/       # Reference documentation
+    └── examples/         # Code examples
+```
+
+## Example: Creating a "Testing Patterns" Skill
+
+[Step-by-step walkthrough]
+
+## Triggering Skills
+
+Skills are triggered from the generalist agent when keywords match:
+- "write tests" → testing-strategies skill
+- "API endpoint" → api-contract-design skill
+
+Update SKILLS-INVENTORY.md with your new skill's triggers.
+```
+
+---
+
+## Phase 5: Enhance Templates (Medium Priority)
+
+### 5.1 product.md Questionnaire
+
+**Location**: `project/product.md`
+
+Add guided questions:
+
+```markdown
+# Product Context
+
+## Mission
+> What does this project do in one sentence?
+
+[Your answer]
+
+## Users
+> Who are the primary users? What problems do they have?
+
+[Your answer]
+
+## Tech Stack
+> What technologies and why? What constraints drove these choices?
+
+[Your answer]
+
+## Current Focus
+> What are you working on RIGHT NOW?
+
+[Your answer]
+
+## Future Roadmap
+> What comes after current focus? What's explicitly out of scope?
+
+[Your answer]
+
+## Success Metrics
+> How do you know if this project is successful?
+
+[Your answer]
+```
+
+### 5.2 constitution.md Questionnaire
+
+**Location**: `project/constitution.md`
+
+Add guided questions:
+
+```markdown
+# Project Constitution
+
+## Security Non-Negotiables
+> What security rules are absolute? (e.g., "Never store plaintext passwords")
+
+- [ ] 
+- [ ]
+
+## Code Quality Rules
+> What code quality standards matter most?
+
+- [ ]
+- [ ]
+
+## Things We Never Do
+> What patterns or practices are forbidden?
+
+- [ ]
+- [ ]
+
+## Performance Requirements
+> What performance constraints exist?
+
+- [ ]
+
+## Compliance Requirements
+> Any regulatory or compliance requirements?
+
+- [ ]
+```
+
+---
+
+## Phase 6: Update README.md (Medium Priority)
+
+### Add sections:
+
+1. **Architecture Overview** — Single agent + skills model
+2. **When to Use Anvil** — Solo developers, small teams, AI-assisted development
+3. **Key Concepts** — Skills vs Sub-agents vs Coordination
+4. **Quick Start** — Link to installation paths
+
+---
+
+## Phase 7: Nice-to-Have Scripts (Low Priority)
+
+### 7.1 install.sh
+
+Single command installation script that:
+- Detects fresh install vs migration
+- Runs appropriate phases
+- Provides progress feedback
+
+### 7.2 verify.sh
+
+Validation script that:
+- Runs Phase 5 checklist
+- Reports pass/fail for each item
+- Suggests fixes for failures
+
+### 7.3 rollback.sh
+
+Restoration script that:
+- Takes backup path as argument
+- Restores global and project configs
+- Verifies restoration
+
+---
+
+## Commit Strategy
+
+```bash
+# Commit 1: Current fixes (Phase 1)
+git add global/commands/*.md quality-gates/ project/coordination.md docs/
+git commit -m "fix: apply learnings from installation"
+
+# Commit 2: Installation doc updates (Phases 2-3)
+git add docs/INSTALLATION.md
+git commit -m "docs: split installation paths, add validation checklist"
+
+# Commit 3: First skill tutorial (Phase 4)
+git add docs/FIRST-SKILL-TUTORIAL.md
+git commit -m "docs: add first skill creation tutorial"
+
+# Commit 4: Template enhancements (Phase 5)
+git add project/product.md project/constitution.md
+git commit -m "feat: add questionnaire format to templates"
+
+# Commit 5: README updates (Phase 6)
+git add README.md
+git commit -m "docs: update README with architecture overview"
+```
+
+---
+
+## Verification
+
+After all changes, test by:
+1. Creating a fresh test project
+2. Following "Path A: Fresh Install"
+3. Verifying all phases complete without errors
+4. Testing `/orient` command
+
+---
+
+## Files Summary
+
+| File | Action | Priority |
+|------|--------|----------|
+| `global/commands/*.md` (5) | Already fixed, commit | High |
+| `quality-gates/.pre-commit-config.yaml` | Already fixed, commit | High |
+| `quality-gates/.semgrep/rules/anvil-rules.yaml` | Already fixed, commit | High |
+| `project/coordination.md` | Already created, commit | High |
+| `docs/INSTALLATION-RETRO-NOTES.md` | Already created, commit | High |
+| `docs/INSTALLATION.md` | Update per Phase 2 | High |
+| `docs/ARCHITECTURE.md` or section | Create per Phase 3 | High |
+| `docs/FIRST-SKILL-TUTORIAL.md` | Create per Phase 4 | Medium |
+| `project/product.md` | Enhance per Phase 5 | Medium |
+| `project/constitution.md` | Enhance per Phase 5 | Medium |
+| `README.md` | Update per Phase 6 | Medium |
+| `scripts/install.sh` | Create per Phase 7 | Low |
+| `scripts/verify.sh` | Create per Phase 7 | Low |
+| `scripts/rollback.sh` | Create per Phase 7 | Low |