anvil-dev-framework 0.1.7 → 0.1.9

package/project/CLAUDE.md.template

@@ -0,0 +1,343 @@
+# [Project Name]
+
+> [One-line description of the project]
+
+---
+
+## Project Overview
+
+[2-3 sentences describing what this project is and who it's for]
+
+**Status**: [Active Development / Maintenance / Beta / etc.]
+**Repository**: [URL]
+**Live URL**: [URL if applicable]
+
+---
+
+## Tech Stack
+
+| Layer | Technology | Version |
+|-------|------------|---------|
+| Framework | Next.js | 14.x |
+| Language | TypeScript | 5.x |
+| Database | Supabase (PostgreSQL) | — |
+| Auth | Supabase Auth | — |
+| Styling | Tailwind CSS | 3.x |
+| Testing | Vitest | 1.x |
+| Deployment | Vercel | — |
+
+---
+
+## Architecture
+
+### Directory Structure
+```
+src/
+├── app/                    # Next.js App Router pages
+│   ├── api/               # API routes
+│   └── (routes)/          # Page routes
+├── components/            # React components
+│   ├── ui/               # Base UI components
+│   └── [feature]/        # Feature-specific components
+├── lib/                   # Shared utilities
+├── services/              # Business logic
+├── hooks/                 # Custom React hooks
+└── types/                 # TypeScript types
+```
+
+### Key Patterns
+- **API Routes**: Next.js App Router with route handlers
+- **Database**: Supabase client with RLS policies
+- **Auth**: Supabase Auth with middleware protection
+- **State**: React Query for server state, Zustand for client state
+- **Error Handling**: Custom AppError class with error boundaries
+
+---
+
+## Agent Approach
+
+### Session Startup
+```
+1. /orient           → Check handoffs, understand context
+2. /ready            → See unblocked work
+3. /validate         → Ensure clean environment
+4. Await direction   → Don't start work without confirmation
+```
+
+### Implementation Flow
+```
+1. /explore          → Discovery before any new feature
+2. /spec             → Formal specification (if needed)
+3. /plan             → Implementation plan
+4. /tasks            → Linear issues from plan
+5. [implement]       → Do the work
+6. /evidence         → Capture quality proof
+7. /handoff          → Session continuity
+```
+
+### During Work
+- Read existing code before writing new code
+- Cite file paths and line numbers as evidence
+- File discovered work immediately with `/discover`
+- Update Linear status at phase transitions
+- Stop and report if stuck >5 minutes
+
+### Anti-Patterns to Avoid
+
+Before implementing, verify you're NOT doing:
+
+| Anti-Pattern | Check |
+|--------------|-------|
+| Premature abstraction | Is this the 3rd instance? (Rule of Three) |
+| Adding files without need | Can this be added to existing file? |
+| Over-engineering | Is this the simplest solution? |
+| Ignoring existing patterns | Did I check examples first? |
+| Large PRs | Can I break this into smaller chunks? |
+| Skipping exploration | Did I run `/explore` first? |
+| Editing gitignored files | Is this path in `.gitignore`? (check `project/` vs `.claude/`) |
+| Uncommitted work before compaction | Did I commit a WIP checkpoint? |
+| Reading files on wrong branch | Did I run `git branch --show-current` first? |
+| Post-edit without git diff | Did I run `git diff` to verify edits persisted? |
+| Starting exploration without WIP | Is current work committed before `/explore`? |
+| Stash operation without verification | Did I run `git diff --name-only main..HEAD` after stash pop? |
+| Importing from `global.*` in Python | Use `sys.path.insert(0, project_root)` first - `global` is reserved |
+| Guessing object attributes | Read class definition or use `dir(obj)` first |
+
+### Code Patterns
+
+Patterns for specific coding scenarios:
+
+| Pattern | When to Use | Example |
+|---------|-------------|---------|
+| Python Null Handling | JSON with possible null values | `dict.get(key) or default` not `dict.get(key, default)` for falsy values |
+| Try-Finally for Resources | File handles, DB connections, temp files | `try: conn = open() ... finally: conn.close()` |
+| Fast-Path Scripts | 3+ independent queries >100ms each | Create `_fast.py` companion with ThreadPoolExecutor |
+| Script Existence Check | New script added in PR | `[ -f script.py ] && python3 script.py` in commands |
+
+### Code Patterns
+
+Patterns for specific coding scenarios (Evidence: ANV-135, ANV-203, ANV-250, coderabbit-fixes):
+
+| Pattern | When to Use | Example |
+|---------|-------------|---------|
+| Python Null Handling | JSON with possible null/falsy values | Use `dict.get(key) or default` when None means missing; use `dict.get(key, default)` when 0 or "" are valid values |
+| Try-Finally for Resources | File handles, DB connections, temp files | `try: conn = open() ... finally: conn.close()` |
+| Fast-Path Scripts | 3+ independent queries >100ms each | Create `_fast.py` companion with ThreadPoolExecutor |
+| Script Existence Check | New script added in PR | `[ -f script.py ] && python3 script.py` in commands |
+
+### Confidence Checkpoints
+
+Rate your confidence at each stage (1-10):
+
+| Confidence | Action |
+|------------|--------|
+| 8-10 | Proceed normally |
+| 5-7 | Document uncertainty, proceed cautiously, note assumptions |
+| 1-4 | **STOP**. Explain the uncertainty. Ask for guidance. |
+
+**Escalation rule**: After 2 failed attempts at the same task → Stop. Reassess. Ask for help.
+
+---
+
+## Interactive Questions (AskUserQuestion)
+
+When requirements are ambiguous, use the AskUserQuestion tool to gather explicit decisions interactively.
+
+### When to Use
+- Requirements contain alternatives ("X or Y")
+- Multiple valid approaches exist
+- Scope is negotiable
+- Technical choices need user input
+
+### Best Practices
+
+| Guideline | Example |
+|-----------|---------|
+| **header**: Max 12 chars, noun-like | "Provider", "Scope", "Priority" |
+| **question**: Full sentence with "?" | "Which auth provider should we use?" |
+| **multiSelect**: true if multiple valid | Scope selections, feature toggles |
+| **options**: 2-4 choices, best first | Add "(Recommended)" to suggested option |
+| **descriptions**: Explain implications | "Fastest setup, widest adoption" |
+
+### Pattern: Interview-Then-Execute
+```
+1. /clarify [topic]     → Gather decisions via AskUserQuestion
+2. /spec [feature]      → Write spec with decisions captured
+3. /plan [spec]         → Plan implementation
+4. [implement]          → Execute with clarity
+```
+
+### Example
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Provider",
+    question: "Which authentication provider should we implement?",
+    multiSelect: false,
+    options: [
+      { label: "Google OAuth (Recommended)", description: "Widest adoption" },
+      { label: "GitHub OAuth", description: "Developer-focused" },
+      { label: "Email/Password", description: "No external dependency" }
+    ]
+  }]
+})
+```
+
+**Note**: User can always select "Other" to provide custom input.
+
+---
+
+## Slash Commands
+
+### Session Commands
+| Command | Purpose |
+|---------|---------|
+| `/orient` | Session startup orientation (with interactive task picker) |
+| `/ready` | Calculate ready work |
+| `/sprint` | Quick session prioritization |
+| `/handoff` | Generate session continuity doc |
+
+### Workflow Commands
+| Command | Purpose |
+|---------|---------|
+| `/explore` | Discovery phase |
+| `/clarify` | Interactive requirement disambiguation |
+| `/spec` | Generate specification |
+| `/plan` | Create implementation plan |
+| `/tasks` | Create Linear issues |
+| `/change` | Brownfield change proposal |
+| `/discover` | File discovered work |
+
+### Quality Commands
+| Command | Purpose |
+|---------|---------|
+| `/validate` | Environment validation |
+| `/evidence` | Capture quality proof |
+
+### Maintenance Commands
+| Command | Purpose |
+|---------|---------|
+| `/retro` | Write retrospective |
+| `/insights` | Synthesize learnings |
+
+---
+
+## Linear Workflow
+
+### Issue States
+| State | Meaning |
+|-------|---------|
+| Backlog | Not yet prioritized |
+| Todo | Prioritized, ready to start |
+| In Progress | Actively being worked on |
+| In Review | PR created, awaiting review |
+| Done | Merged and deployed |
+
+### Labels
+- `bug` — Something isn't working
+- `feature` — New functionality
+- `chore` — Maintenance task
+- `discovered` — Found during other work
+- `blocked` — Cannot proceed
+
+### Priorities
+- **P0 (Urgent)**: Drop everything, fix now
+- **P1 (High)**: Next up after current task
+- **P2 (Medium)**: This sprint
+- **P3 (Low)**: Backlog
+
+---
+
+## File Conventions
+
+### Naming
+- **Components**: PascalCase (`UserProfile.tsx`)
+- **Hooks**: camelCase with `use` prefix (`useAuth.ts`)
+- **Utilities**: camelCase (`formatDate.ts`)
+- **Types**: PascalCase (`User.ts`)
+- **API Routes**: lowercase (`route.ts`)
+
+### Component Structure
+```typescript
+// Imports (external, then internal)
+import { useState } from 'react'
+import { Button } from '@/components/ui'
+
+// Types
+interface Props {
+  // ...
+}
+
+// Component
+export function ComponentName({ prop }: Props) {
+  // Hooks first
+  // State second
+  // Effects third
+  // Handlers fourth
+  // Render last
+}
+```
+
+---
+
+## Error Handling
+
+### Pattern
+```typescript
+import { AppError } from '@/lib/errors'
+
+try {
+  // operation
+} catch (error) {
+  if (error instanceof AppError) {
+    // Handle known errors
+  }
+  throw new AppError('OPERATION_FAILED', 'Description', { cause: error })
+}
+```
+
+### Error Codes
+| Code | Meaning |
+|------|---------|
+| `AUTH_REQUIRED` | User must be logged in |
+| `NOT_FOUND` | Resource doesn't exist |
+| `VALIDATION_ERROR` | Invalid input |
+| `PERMISSION_DENIED` | User lacks permission |
+
+---
+
+## Key Files Reference
+
+| Purpose | Location |
+|---------|----------|
+| Project config | `CLAUDE.md` (this file) |
+| Non-negotiables | `.claude/constitution.md` |
+| Product definition | `.claude/product.md` |
+| Active specs | `.claude/specs/current/` |
+| Handoffs | `.claude/handoffs/` |
+| Convention examples | `.claude/examples/` |
+
+---
+
+## Environment Setup
+
+### Required Environment Variables
+```bash
+# .env.local
+NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_ANON_KEY=
+SUPABASE_SERVICE_ROLE_KEY=
+```
+
+### Local Development
+```bash
+npm install          # Install dependencies
+npm run dev          # Start dev server
+npm run test         # Run tests
+npm run typecheck    # Check types
+npm run lint         # Run linter
+```
+
+---
+
+*Update this file as the project evolves. This is your project's source of truth for AI assistance.*

package/project/agents/README.md

@@ -0,0 +1,119 @@
+# Sub-Agents
+
+> Focused task executors for specific bounded workflows. Use sparingly.
+
+---
+
+## Philosophy
+
+**Single agent with skills beats multi-agent coordination.**
+
+Research shows multi-agent architectures degrade sequential task performance by 39-70%. Coding is inherently sequential. Therefore, Anvil uses a single generalist agent enhanced with on-demand skills.
+
+Sub-agents are the **exception**, not the rule.
+
+---
+
+## When to Use Sub-Agents
+
+Sub-agents are appropriate when:
+
+1. **Adversarial perspective helps** — Task benefits from "fresh eyes" that haven't seen the code being reviewed
+2. **Bounded scope** — Task has clear start/end with specific methodology
+3. **Context isolation valuable** — Separate context prevents bias from implementation work
+
+### Recommended Sub-Agents (2)
+
+| Sub-Agent | Purpose | Why It's Needed |
+|-----------|---------|-----------------|
+| `security-code-reviewer` | Adversarial security review | Fresh perspective catches what implementer missed |
+| `cross-layer-debugger` | Debug issues spanning layers | Bounded methodology, isolation prevents tunnel vision |
+
+---
+
+## When NOT to Use Sub-Agents
+
+**Use skills instead when:**
+
+- It's mainly a checklist or methodology → Skill
+- Same context as main work is fine → Skill  
+- Doesn't need "fresh eyes" → Skill
+- One-off task → Do manually
+
+**Common anti-patterns:**
+
+| Anti-Pattern | Better Alternative |
+|--------------|-------------------|
+| api-designer sub-agent | API design patterns skill |
+| test-writer sub-agent | Testing strategies skill |
+| docs-writer sub-agent | Documentation standards skill |
+| component-designer sub-agent | Component architecture skill |
+
+---
+
+## Sub-Agent Structure
+
+Each sub-agent file uses YAML frontmatter followed by the agent definition:
+
+```yaml
+---
+name: <agent-name>
+description: <brief description>
+tools: [Read, Grep, Glob]           # Available tools
+skills: [skill-1, skill-2]          # Auto-loaded skills (optional)
+permissionMode: default             # default|inherit|strict (optional)
+---
+
+# [Sub-Agent Name]
+
+> One-line description
+
+## Purpose
+Why this sub-agent exists (not a skill)
+
+## Trigger Conditions
+When to invoke this sub-agent
+
+## Process
+Step-by-step methodology
+
+## Output Format
+What the sub-agent produces
+
+## Escalation
+When to stop and escalate to human
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Agent identifier |
+| `description` | Yes | Brief purpose description |
+| `tools` | Yes | List of available tools |
+| `skills` | No | Skills to auto-load at start |
+| `permissionMode` | No | Permission handling: `default`, `inherit`, `strict` |
+
+See [Skills Frontmatter](../docs/skills-frontmatter.md) for detailed documentation.
+
+---
+
+## Available Sub-Agents
+
+- [security-code-reviewer.md](security-code-reviewer.md) — Adversarial security review
+- [cross-layer-debugger.md](cross-layer-debugger.md) — Cross-layer debugging methodology
+
+---
+
+## Adding New Sub-Agents
+
+Before adding a sub-agent, ask:
+
+1. Could this be a skill instead? (Usually yes)
+2. Does it genuinely benefit from fresh context?
+3. Is the scope bounded with clear methodology?
+4. Will it be used regularly? (If not, do manually)
+
+If all answers support a sub-agent, use the template structure above.
+
+**Default answer: Use a skill instead.**

package/project/agents/cross-layer-debugger.md

@@ -0,0 +1,217 @@
+---
+name: cross-layer-debugger
+description: Systematic debugging for issues spanning multiple system layers
+---
+
+# Cross-Layer Debugger
+
+> Systematic debugging for issues spanning multiple system layers.
+
+---
+
+## Purpose
+
+Debug issues that cross boundaries between frontend, API, database, and external services. Uses structured methodology to isolate which layer contains the bug.
+
+**Why sub-agent (not skill):** Debugging benefits from fresh context without preconceptions about where the bug "should" be. Isolation prevents tunnel vision from implementation work.
+
+---
+
+## Trigger Conditions
+
+Invoke this sub-agent when:
+
+- Bug symptoms appear in one layer but cause may be elsewhere
+- Issue involves data flow across multiple boundaries
+- Previous debugging attempts haven't isolated the problem
+- "It works locally but not in production" scenarios
+- Intermittent failures that are hard to reproduce
+
+---
+
+## Process
+
+### Step 1: Symptom Documentation
+
+Before investigating, document exactly what's observed:
+
+```markdown
+## Symptom Report
+- **What happens**: [Exact error/behavior]
+- **What should happen**: [Expected behavior]
+- **Where observed**: [UI/console/logs/etc.]
+- **Reproducible**: [Always/Sometimes/Rarely]
+- **Steps to reproduce**: [Minimal steps]
+```
+
+### Step 2: Layer Identification
+
+Identify all layers involved in the data flow:
+
+```
+┌─────────────┐
+│   Frontend  │  ← UI components, state, event handlers
+├─────────────┤
+│   API Layer │  ← Routes, controllers, middleware
+├─────────────┤
+│   Services  │  ← Business logic, validation
+├─────────────┤
+│   Database  │  ← Queries, RLS, triggers
+├─────────────┤
+│   External  │  ← Third-party APIs, services
+└─────────────┘
+```
+
+For the bug, trace which layers are involved in the operation.
+
+### Step 3: Boundary Testing
+
+Test at each layer boundary systematically:
+
+**Frontend → API**
+```bash
+# Verify request is correct
+curl -X POST http://localhost:3000/api/endpoint \
+  -H "Content-Type: application/json" \
+  -d '{"test": "data"}'
+```
+- Is the request payload correct?
+- Are headers correct (auth, content-type)?
+- Does the API receive what frontend sends?
+
+**API → Service**
+- Add logging at service entry point
+- Verify parameters passed correctly
+- Check for transformation errors
+
+**Service → Database**
+- Log the actual query being executed
+- Run query directly in database client
+- Check RLS policies if applicable
+
+**Database → External**
+- Verify external service is reachable
+- Check credentials/tokens
+- Test external API independently
+
+### Step 4: Isolation
+
+Use binary search to isolate:
+
+1. Find the middle boundary
+2. Verify data is correct at that point
+3. If correct: bug is downstream
+4. If incorrect: bug is upstream
+5. Repeat until layer identified
+
+### Step 5: Root Cause Analysis
+
+Once layer is identified:
+
+- What's the exact line/function?
+- Why does it fail?
+- What assumption was wrong?
+- Is this the only occurrence?
+
+---
+
+## Debugging Toolkit
+
+### Logging Strategy
+
+```typescript
+// Boundary logging pattern
+console.log('[LAYER:BOUNDARY] input:', JSON.stringify(input));
+// ... operation ...
+console.log('[LAYER:BOUNDARY] output:', JSON.stringify(output));
+```
+
+### Database Debugging
+
+```sql
+-- Check RLS is the issue
+SET LOCAL row_level_security = off;
+SELECT * FROM table WHERE id = 'xxx';
+
+-- Check what policies exist
+SELECT * FROM pg_policies WHERE tablename = 'table_name';
+```
+
+### Network Debugging
+
+```bash
+# See actual request/response
+curl -v -X POST url -d 'data'
+
+# Check if service is reachable
+nc -zv hostname port
+```
+
+### State Debugging
+
+```typescript
+// React state debugging
+useEffect(() => {
+  console.log('[STATE] value changed:', value);
+}, [value]);
+```
+
+---
+
+## Output Format
+
+```markdown
+# Debug Report: [Issue Description]
+
+## Symptom
+[What was observed]
+
+## Layers Investigated
+- [ ] Frontend
+- [ ] API
+- [ ] Services
+- [ ] Database
+- [ ] External
+
+## Boundary Test Results
+
+| Boundary | Input Correct? | Output Correct? | Notes |
+|----------|---------------|-----------------|-------|
+| FE → API | ✅/❌ | ✅/❌ | [notes] |
+| API → Service | ✅/❌ | ✅/❌ | [notes] |
+| Service → DB | ✅/❌ | ✅/❌ | [notes] |
+
+## Root Cause
+**Layer**: [Where bug exists]
+**Component**: [Specific file/function]
+**Issue**: [What's wrong]
+**Why**: [Root cause explanation]
+
+## Fix Recommendation
+[Suggested fix with code snippet if applicable]
+
+## Verification
+[How to verify the fix works]
+```
+
+---
+
+## Escalation
+
+Stop and escalate to human when:
+
+- Issue requires production access you don't have
+- Bug appears to be in third-party code
+- Multiple possible root causes, unclear which
+- Fix requires architectural decision
+- Unable to reproduce after 3 attempts
+- Debugging has taken >30 minutes without progress
+
+---
+
+## What This Sub-Agent Does NOT Do
+
+- Implement fixes (report findings, main agent fixes)
+- Make architectural decisions
+- Debug without systematic approach (no random changes)
+- Continue indefinitely (escalate if stuck)