anvil-dev-framework 0.1.6

package/docs/simplification-plan-template.md

@@ -0,0 +1,297 @@
+# Anvil Simplification Plan Template
+
+> Template for auditing and simplifying Anvil installations that have accumulated complexity.
+
+---
+
+## Pre-Audit Checklist
+
+Before simplifying, gather baseline metrics:
+
+- [ ] Count total sub-agents
+- [ ] Count total skills
+- [ ] Count total commands
+- [ ] Check retro utilization (retros written in last 30 days)
+- [ ] Check session management usage
+- [ ] Review comms.md last activity date
+
+---
+
+## Phase 1: Remove Unused Infrastructure
+
+**Estimated effort:** 30 minutes
+**Risk:** Low
+
+### 1.1 Session Management
+
+Check for session-*.md files. If session management isn't actively used:
+
+- [ ] Archive session-start.md
+- [ ] Archive session-end.md
+- [ ] Archive session-current.md
+- [ ] Archive session-help.md
+- [ ] Archive session-list.md
+- [ ] Archive session-update.md
+
+**Action:** Move to `commands/archived/`
+
+### 1.2 Coordination Files
+
+If not running parallel agents:
+
+- [ ] Archive comms.md
+- [ ] Archive comms.template.md
+
+### 1.3 Heavy Orchestration
+
+If scrum master or similar heavy orchestration isn't used:
+
+- [ ] Archive scrum-master.md or equivalent
+- [ ] Create lightweight replacement (see `/sprint` command)
+
+### 1.4 Create Simple Handoff
+
+If handoff doesn't exist or is overly complex:
+
+- [ ] Create/update `/handoff` command
+- [ ] Create `.claude/handoffs/` directory
+
+---
+
+## Phase 2: Sub-Agent Consolidation
+
+**Estimated effort:** 2-3 hours
+**Risk:** Medium
+
+### 2.1 Audit Sub-Agents
+
+For each sub-agent, evaluate:
+
+| Sub-Agent | Used? | Value? | Alternative |
+|-----------|-------|--------|-------------|
+| [name] | Y/N | H/M/L | Skill / Delete |
+
+### 2.2 Decision Criteria
+
+**KEEP** a sub-agent if:
+- Task benefits from adversarial/fresh perspective (security review)
+- Task has bounded scope with specific methodology (debugging)
+- Context isolation is genuinely valuable
+
+**CONVERT to skill** if:
+- It's mainly a checklist or methodology
+- Same context as main work is fine
+- Doesn't need "fresh eyes"
+
+**DELETE** if:
+- Redundant with other sub-agents
+- One-off use case (do manually when needed)
+- Not actually used
+
+### 2.3 Recommended Keeps (Typical)
+
+- `security-code-reviewer` — Adversarial review benefits from fresh perspective
+- `cross-layer-debugger` — Bounded methodology, context isolation helps
+
+### 2.4 Conversion Template
+
+When converting sub-agent to skill:
+
+```markdown
+## [Process Name] (from [sub-agent-name])
+
+### When to Apply
+- [Trigger condition 1]
+- [Trigger condition 2]
+
+### Process
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### Checklist
+- [ ] [Verification 1]
+- [ ] [Verification 2]
+```
+
+---
+
+## Phase 3: Simplify Planning & Orchestration
+
+**Estimated effort:** 1.5 hours
+**Risk:** Low
+
+### 3.1 Clarify Planning Responsibilities
+
+| Function | Tool | When |
+|----------|------|------|
+| Task breakdown | Claude Code native `/plan` | During implementation |
+| Work prioritization | `/sprint` command | Start of session |
+| Learning synthesis | `/insights` command | End of session / weekly |
+
+### 3.2 Create Lightweight /sprint Command
+
+Replace heavy scrum master with:
+
+```markdown
+# /sprint - Session Planning
+
+Query Linear state and suggest priorities.
+
+## Process
+1. Query blocked, in-progress, in-review, todo issues
+2. Present state summary table
+3. Suggest top 3 priorities (blocked first, then age)
+4. Show blockers requiring attention
+
+## What This Is NOT
+- No WSJF calculations
+- No agent routing
+- No dependency graphs
+```
+
+---
+
+## Phase 4: Fix Retrospective System
+
+**Estimated effort:** 1.5 hours
+**Risk:** Low
+
+### 4.1 Simplify Retro Format
+
+Replace YAML frontmatter with narrative:
+
+```markdown
+# [ISSUE-ID]: [Brief Title]
+
+**Outcome:** success | partial | failed
+**Date:** YYYY-MM-DD
+
+## What Happened
+[Narrative - what you tried, what worked, what didn't]
+
+## Learnings
+- [Concrete thing learned]
+
+## For Next Time
+- [Specific actionable improvement]
+```
+
+### 4.2 Create /insights Command
+
+For periodic synthesis instead of per-retro structure:
+
+- Read retros from last 2 weeks
+- Identify patterns (3+ occurrences)
+- Categorize (process, tooling, knowledge, codebase)
+- Output actionable insights
+
+### 4.3 Archive Complex Scripts
+
+- Archive aggregate_retros.py if replaced by /insights
+- Archive structured INSIGHTS.md (regenerate from command)
+
+---
+
+## Phase 5: Add Quality Gates Guidance
+
+**Estimated effort:** 1 hour
+**Risk:** Low
+
+### 5.1 Create Quality Gates Skill
+
+Framework-agnostic patterns for:
+- Pre-commit (fast, staged files)
+- Pre-push (thorough, changed files)
+- CI (comprehensive, full suite)
+
+### 5.2 Project-Specific Implementation
+
+Quality gates skill provides patterns. Projects implement:
+- Git hooks tooling (husky, pre-commit, etc.)
+- CI configuration
+- Project CONTRIBUTING.md docs
+
+---
+
+## Phase 6: Enhance Generalist Prompt
+
+**Estimated effort:** 30 minutes
+**Risk:** Low
+
+### 6.1 Add Anti-Patterns Section
+
+```markdown
+## Anti-Patterns to Avoid
+
+Before implementing, verify you're NOT doing:
+
+- [ ] Premature abstraction (Rule of Three)
+- [ ] Adding files without need (prefer editing)
+- [ ] Over-engineering (simplest solution)
+- [ ] Ignoring existing patterns (check first)
+- [ ] Large PRs (break into chunks)
+- [ ] Skipping exploration (always EXPLORE first)
+```
+
+### 6.2 Add Confidence Checkpoints
+
+```markdown
+## Confidence Checkpoints
+
+Rate confidence at each stage (1-10):
+
+| Confidence | Action |
+|------------|--------|
+| 8-10 | Proceed |
+| 5-7 | Document uncertainty, proceed cautiously |
+| 1-4 | STOP. Explain. Ask for guidance. |
+
+After 2 failed attempts: Stop. Reassess. Escalate.
+```
+
+---
+
+## Validation Checklist
+
+After implementation:
+
+### Structure
+- [ ] Sub-agents: ≤ 2 (security + debugging typical)
+- [ ] Commands: Core workflow only (no unused)
+- [ ] Session management: Archived if unused
+- [ ] Orchestration: Lightweight or removed
+
+### Skills
+- [ ] Converted sub-agent methodology added
+- [ ] Quality gates skill exists
+- [ ] No orphan references to deleted sub-agents
+
+### Documentation
+- [ ] SKILLS-INVENTORY.md updated
+- [ ] Command references current
+- [ ] Archived items clearly marked
+
+---
+
+## Success Metrics
+
+### Quantitative
+- Sub-agents reduced to 2 or fewer
+- Command files reduced by ~50-70%
+- Retro utilization improved (target: 1+/week)
+
+### Qualitative
+- Framework matches actual usage pattern
+- Lower cognitive overhead
+- Retros actually get written
+- Skills contain actionable methodology
+
+---
+
+## Notes
+
+- Archive rather than delete when uncertain
+- Framework stays project-agnostic
+- Project-specific tooling belongs in projects
+- Run real task after simplification to validate

package/docs/simplification-principles.md

@@ -0,0 +1,129 @@
+# Anvil Simplification Principles
+
+> Guidance for maintaining framework simplicity based on research and practical experience.
+
+---
+
+## Research Foundation
+
+Based on Google/MIT multi-agent research (December 2025, "Towards a Science of Scaling Agent Systems"):
+
+| Metric | Single Agent | Multi-Agent |
+|--------|--------------|-------------|
+| Tasks per 1000 tokens | 67 | 14-21 |
+| Sequential task performance | baseline | -39% to -70% |
+| Error amplification | 1x | 4.4x - 17.2x |
+
+**Key finding**: Once single-agent success exceeds 45%, adding agents produces diminishing or negative returns.
+
+**Implication**: Coding is sequential. A single enhanced agent outperforms multi-agent coordination.
+
+---
+
+## Core Architecture Principles
+
+### 1. Single Agent, Enhanced Context
+
+**Do**: Enhance one agent with skills (just-in-time knowledge loading)
+**Don't**: Create multiple specialized agents that coordinate
+
+The generalist agent with on-demand skills is the pattern. Sub-agents should be rare exceptions for truly adversarial tasks (security review, debugging from fresh perspective).
+
+### 2. Commands Over Agents
+
+**Do**: Create commands that structure workflow phases
+**Don't**: Create agents that spawn other agents
+
+Commands are instructions the human triggers. They guide behavior without adding coordination overhead.
+
+### 3. Skills Over Sub-Agents
+
+When you think you need a sub-agent, ask: "Could this be a skill instead?"
+
+| Sub-Agent Need | Skill Alternative |
+|----------------|-------------------|
+| API designer | API design patterns skill |
+| Test writer | Testing strategies skill |
+| Code reviewer | Code review checklist in skill |
+| Documentation | Documentation standards skill |
+
+**Exception criteria for sub-agents**:
+- Task benefits from adversarial/fresh perspective (security review)
+- Task has bounded scope with specific methodology (cross-layer debugging)
+- Context isolation is genuinely valuable
+
+### 4. Minimal Orchestration
+
+**Do**: Let the human orchestrate (select task, approve work)
+**Don't**: Build automated orchestration layers
+
+Session management, scrum master agents, and coordination protocols add complexity without proportional benefit for single-developer workflows.
+
+---
+
+## What Belongs in Anvil vs. Projects
+
+### Framework (Anvil)
+- Command definitions and workflows
+- Skill templates
+- Quality gate patterns
+- Documentation standards
+
+### Project-Specific
+- Project constitution (constraints, patterns)
+- Product context
+- Project-specific examples
+- Applied skills with project context
+
+---
+
+## Anti-Patterns to Avoid
+
+### 1. Premature Abstraction
+Wait for the Rule of Three before abstracting. Three instances of similar code/patterns before creating a shared abstraction.
+
+### 2. Sub-Agent Proliferation
+More agents ≠ better outcomes. Each sub-agent adds:
+- Context switching cost
+- Coordination overhead
+- Error amplification risk
+
+### 3. Over-Structured Retrospectives
+Complex YAML frontmatter and rigid structures create friction → retros don't get written.
+
+**Better**: Narrative-first format, periodic synthesis.
+
+### 4. Unused Infrastructure
+If a feature isn't being used (e.g., session management with 0 active sessions), remove it. Dead code and dead processes add cognitive overhead.
+
+---
+
+## Decision Framework
+
+When considering adding complexity, ask:
+
+1. **Is this solving a real problem?** (Not hypothetical future needs)
+2. **Is the simplest solution insufficient?** (Could a checklist work instead of automation?)
+3. **Will this be used regularly?** (If weekly or less, maybe don't automate)
+4. **Does this match the actual usage pattern?** (Single developer? Don't build for teams)
+
+---
+
+## Recommended Simplification Checklist
+
+When inheriting or auditing an Anvil installation:
+
+- [ ] Count active sub-agents — should be 0-2
+- [ ] Check session management — if unused, archive it
+- [ ] Review skills — are they being triggered? Remove unused ones
+- [ ] Check retrospective utilization — simplify format if low adoption
+- [ ] Verify command usage — archive unused commands
+- [ ] Audit orchestration layers — remove coordination without value
+
+---
+
+## References
+
+- Google/MIT: "Towards a Science of Scaling Agent Systems" (Dec 2025)
+- Anthropic: Claude prompting best practices
+- Anvil command reference: `docs/command-reference.md`