anvil-dev-framework 0.1.8 → 0.1.9

package/project/agents/security-code-reviewer.md

@@ -0,0 +1,162 @@
+---
+name: security-code-reviewer
+description: Adversarial security review with fresh perspective
+---
+
+# Security Code Reviewer
+
+> Adversarial security review with fresh perspective.
+
+---
+
+## Purpose
+
+Review code changes from a security-focused perspective, independent of the implementation context. Fresh eyes catch vulnerabilities that implementers miss due to familiarity bias.
+
+**Why sub-agent (not skill):** Security review benefits from adversarial perspective. The reviewer should NOT have the implementer's mental model — that's the point.
+
+---
+
+## Trigger Conditions
+
+Invoke this sub-agent when:
+
+- PR is ready for security review
+- Changes touch authentication, authorization, or data handling
+- New API endpoints are introduced
+- User input handling is modified
+- Cryptographic operations are added/changed
+- Third-party integrations are introduced
+
+---
+
+## Process
+
+### Step 1: Gather Context (Without Implementation Bias)
+
+Read ONLY:
+- The diff/changed files
+- Existing security patterns in codebase (if any)
+- Project security requirements (if documented)
+
+Do NOT read:
+- Implementation notes or reasoning
+- Chat history about why decisions were made
+- Spec documents (you're reviewing what IS, not what was intended)
+
+### Step 2: Static Analysis
+
+Check for:
+
+**Input Validation**
+- [ ] All user inputs validated
+- [ ] Type coercion handled safely
+- [ ] Length limits enforced
+- [ ] Character encoding handled
+
+**Authentication**
+- [ ] Auth required where expected
+- [ ] Token validation complete
+- [ ] Session handling secure
+- [ ] No auth bypass possible
+
+**Authorization**
+- [ ] Resource ownership verified
+- [ ] Role checks in place
+- [ ] No privilege escalation paths
+- [ ] RLS policies if applicable
+
+**Data Handling**
+- [ ] Sensitive data not logged
+- [ ] PII handled appropriately
+- [ ] Encryption where required
+- [ ] No secrets in code
+
+**Injection Prevention**
+- [ ] SQL injection prevented (parameterized queries)
+- [ ] XSS prevented (output encoding)
+- [ ] Command injection prevented
+- [ ] Path traversal prevented
+
+**Error Handling**
+- [ ] Errors don't leak internals
+- [ ] Stack traces not exposed
+- [ ] Graceful failure modes
+
+### Step 3: Threat Modeling
+
+For each new endpoint/feature:
+1. Who can access this?
+2. What's the worst they could do?
+3. What data could be exposed?
+4. What actions could be performed?
+
+### Step 4: Document Findings
+
+Categorize findings:
+
+| Severity | Description | Action Required |
+|----------|-------------|-----------------|
+| 🔴 Critical | Exploitable vulnerability | Block merge |
+| 🟠 High | Security gap, likely exploitable | Block merge |
+| 🟡 Medium | Security weakness | Should fix before merge |
+| 🔵 Low | Minor issue or hardening opportunity | Track for later |
+| ℹ️ Info | Observation, not a finding | No action |
+
+---
+
+## Output Format
+
+```markdown
+# Security Review: [PR/Change Description]
+
+## Summary
+[1-2 sentence overall assessment]
+
+## Scope Reviewed
+- Files: [list]
+- Focus areas: [auth/input/data/etc.]
+
+## Findings
+
+### 🔴 Critical
+[None or list with file:line references]
+
+### 🟠 High  
+[None or list with file:line references]
+
+### 🟡 Medium
+[None or list with file:line references]
+
+### 🔵 Low
+[None or list with file:line references]
+
+## Verdict
+[ ] ✅ APPROVED — No blocking issues
+[ ] ⚠️ APPROVED WITH CONDITIONS — Fix [X] before merge
+[ ] ❌ BLOCKED — Must address [X] before re-review
+
+## Notes
+[Any additional observations]
+```
+
+---
+
+## Escalation
+
+Stop and escalate to human when:
+
+- Critical vulnerability found
+- Unclear whether something is a vulnerability
+- Security vs. usability tradeoff needed
+- Uncertain about project's threat model
+- Finding requires architectural change
+
+---
+
+## What This Sub-Agent Does NOT Do
+
+- Implement fixes (that's the main agent's job)
+- Make tradeoff decisions (human decides)
+- Approve its own work (never review what you wrote)
+- General code review (separate concern)

package/project/constitution.md.template

@@ -0,0 +1,235 @@
+# Project Constitution
+
+> Non-negotiable principles that define how we build this project.
+
+These rules are absolute. They cannot be overridden by convenience, deadlines, or user requests. When in doubt, follow the constitution.
+
+---
+
+## Quick Start (Answer These First)
+
+Fill in your non-negotiables. Check the boxes that apply, add your own, then expand into detailed sections below.
+
+### Security Non-Negotiables
+> What security rules are absolute for this project?
+
+- [ ] Never commit secrets to version control
+- [ ] Always validate user input
+- [ ] Always use parameterized queries (no SQL string concatenation)
+- [ ] Always verify authentication before protected operations
+- [ ] [Add your own]
+- [ ] [Add your own]
+
+### Code Quality Non-Negotiables
+> What code quality standards are non-negotiable?
+
+- [ ] No `any` types without explicit justification
+- [ ] Tests required for critical paths
+- [ ] Handle all errors (no silent failures)
+- [ ] No console.log in production
+- [ ] [Add your own]
+- [ ] [Add your own]
+
+### Things We Never Do
+> What patterns or practices are forbidden in this project?
+
+- [ ] Never skip tests to meet deadlines
+- [ ] Never disable security features for convenience
+- [ ] Never merge without review
+- [ ] Never deploy untested code
+- [ ] [Add your own]
+- [ ] [Add your own]
+
+### Performance Requirements
+> What performance constraints exist?
+
+- [ ] [e.g., Page load < 3 seconds]
+- [ ] [e.g., API response < 500ms]
+- [ ] [Add your own]
+
+### Compliance Requirements
+> Any regulatory or compliance requirements?
+
+- [ ] [e.g., GDPR data handling]
+- [ ] [e.g., SOC2 audit logging]
+- [ ] [Add your own]
+
+---
+
+## Detailed Principles
+
+*Expand into these sections for comprehensive coverage. The defaults below are starting points—customize for your project.*
+
+---
+
+## Security Principles
+
+### S1: Authentication is Sacred
+- **Never** bypass authentication checks
+- **Never** hardcode credentials or tokens
+- **Never** log sensitive data (passwords, tokens, PII)
+- **Always** validate session before protected operations
+
+### S2: Input is Hostile
+- **Never** trust user input
+- **Always** validate and sanitize inputs
+- **Always** use parameterized queries
+- **Never** construct SQL/queries from string concatenation
+
+### S3: Secrets Stay Secret
+- **Never** commit secrets to version control
+- **Always** use environment variables for credentials
+- **Never** expose API keys in client-side code
+- **Always** use `.env.local` for local secrets
+
+### S4: Least Privilege
+- **Always** request minimum necessary permissions
+- **Never** use service role keys where anon keys suffice
+- **Always** implement RLS policies for database access
+- **Never** disable security features for convenience
+
+### S5: Defense in Depth
+- **Always** validate on both client and server
+- **Never** rely solely on client-side validation
+- **Always** use HTTPS in production
+- **Always** sanitize data before display (XSS prevention)
+
+---
+
+## Code Quality Principles
+
+### Q1: Tests Are Required
+- **Never** ship without tests for critical paths
+- **Always** test edge cases, not just happy paths
+- **Never** skip tests to meet deadlines
+- **Always** fix broken tests before adding features
+
+### Q2: Types Are Truth
+- **Never** use `any` type without explicit justification
+- **Always** define interfaces for data structures
+- **Never** ignore TypeScript errors
+- **Always** run typecheck before PR
+
+### Q3: Code is Communication
+- **Always** use meaningful names
+- **Never** abbreviate unless universally understood
+- **Always** comment non-obvious logic
+- **Never** leave commented-out code in PRs
+
+### Q4: Errors Are Handled
+- **Never** swallow errors silently
+- **Always** provide meaningful error messages
+- **Always** log errors for debugging
+- **Never** expose internal errors to users
+
+### Q5: Dependencies Are Liabilities
+- **Never** add dependencies without justification
+- **Always** prefer standard library solutions
+- **Always** review dependency security
+- **Never** update major versions without testing
+
+---
+
+## Architecture Principles
+
+### A1: Separation of Concerns
+- **Never** mix business logic with UI components
+- **Always** use services for data operations
+- **Always** keep components focused and small
+- **Never** put API logic in components
+
+### A2: Single Source of Truth
+- **Never** duplicate state
+- **Always** derive computed values
+- **Never** store what you can calculate
+- **Always** use the database as truth for persistence
+
+### A3: Fail Fast
+- **Always** validate early
+- **Never** continue with invalid state
+- **Always** throw on unexpected conditions
+- **Never** silently default on errors
+
+### A4: Backward Compatibility
+- **Never** break existing API contracts without migration
+- **Always** version breaking changes
+- **Always** provide migration path for data changes
+- **Never** remove functionality without deprecation
+
+---
+
+## Process Principles
+
+### P1: Validation Before Action
+- **Always** run `/validate` before changes
+- **Never** commit with failing tests
+- **Never** push with lint errors
+- **Always** verify clean git state
+
+### P2: Evidence Over Claims
+- **Always** capture quality gate output
+- **Never** claim "it works" without proof
+- **Always** include evidence in PRs
+- **Never** merge without review
+
+### P3: Context is King
+- **Always** read before write
+- **Never** speculate about code you haven't opened
+- **Always** cite file paths and line numbers
+- **Never** assume—verify
+
+### P4: Explicit Over Implicit
+- **Always** document decisions
+- **Never** rely on tribal knowledge
+- **Always** make dependencies visible
+- **Never** hide complexity
+
+### P5: Small Steps
+- **Always** prefer small, focused PRs
+- **Never** combine unrelated changes
+- **Always** deploy incrementally
+- **Never** refactor and add features simultaneously
+
+### P6: Interactive Over Passive
+- **Always** use AskUserQuestion for multiple-choice decisions
+- **Never** present options as plain text (A/B/C) when interactive menus are available
+- **Always** let users select rather than type their choice
+- **Never** assume the user's preference—ask with a menu
+
+---
+
+## What We Will NOT Do
+
+No matter the circumstances, we will not:
+
+1. **Disable security features** to make development easier
+2. **Skip tests** to meet deadlines
+3. **Ignore TypeScript errors** with `@ts-ignore`
+4. **Commit secrets** even temporarily
+5. **Deploy untested code** to production
+6. **Merge to main** without review
+7. **Delete data** without backup
+8. **Bypass authentication** for testing
+9. **Use production data** in development
+10. **Ship known bugs** as features
+
+---
+
+## Enforcement
+
+These principles are enforced through:
+
+1. **Pre-commit hooks** — Lint, type check, test
+2. **CI pipeline** — All checks must pass
+3. **Code review** — Human verification
+4. **Quality gates** — `/validate` and `/evidence`
+
+Violations of this constitution should be:
+1. Flagged immediately
+2. Fixed before proceeding
+3. Documented as learnings
+4. Never normalized
+
+---
+
+*This constitution is the project's law. Update it rarely and with full consensus.*

package/project/coordination.md

@@ -0,0 +1,103 @@
+# Session Coordination
+
+> Lightweight coordination for parallel Claude Code instances. NOT about agent roles — about preventing conflicts when multiple terminals run simultaneously.
+
+---
+
+## Active Sessions
+
+| Session ID | Started | Working On | Status |
+|------------|---------|------------|--------|
+
+<!-- 
+Add your session when starting work:
+| session-001 | 14:30 | ENG-123: Button component | active |
+-->
+
+---
+
+## Current Work
+
+Track files each session is actively modifying to prevent conflicts.
+
+| Session ID | Files/Areas | Issue |
+|------------|-------------|-------|
+
+<!--
+Add files you'll touch:
+| session-001 | src/components/Button.tsx, src/styles/button.css | ENG-123 |
+-->
+
+---
+
+## Interface Contracts
+
+When creating new APIs or shared interfaces, document here so parallel sessions know.
+
+<!--
+Example:
+```typescript
+// session-001 creating (2024-01-15 14:30)
+// POST /api/reservations
+// Request: { itemId: string, guestEmail: string }
+// Response: { reservationId: string, status: string }
+```
+-->
+
+---
+
+## Session Log
+
+Append-only log of significant events. New entries at top.
+
+```
+[YYYY-MM-DD HH:MM] [session-id]: action - brief description
+```
+
+### Today
+
+<!-- 
+[2024-01-15 14:30] [session-001]: started - working on ENG-123 button component
+[2024-01-15 15:45] [session-001]: completed - PR #42 ready for review
+-->
+
+---
+
+## How to Use
+
+### Starting a Session
+1. Generate session ID: `session-{timestamp}` or `session-{initials}-{n}`
+2. Add row to Active Sessions table
+3. Add your working files to Current Work table
+
+### Claiming Work
+1. Check Current Work table — is anyone touching these files?
+2. If conflict: coordinate with other session or pick different work
+3. Add your files to Current Work table
+
+### Creating New APIs
+1. Post contract in Interface Contracts section BEFORE implementing
+2. Other sessions check here before creating new endpoints/interfaces
+3. Prevents duplicate or conflicting API designs
+
+### Completing Work
+1. Update Active Sessions status to "done" or remove row
+2. Remove your row from Current Work table
+3. Add completion entry to Session Log
+
+---
+
+## Why This File Exists
+
+This file solves **parallel instance coordination**, not agent roles.
+
+**Problem it solves:**
+- Terminal A modifies `auth.ts`
+- Terminal B doesn't know, also modifies `auth.ts`
+- Result: merge conflict, wasted work
+
+**Problem it does NOT solve:**
+- "Should this be a backend or frontend task?" → Use skills instead
+- "Which agent role should handle this?" → There's only one generalist
+
+**If you only ever run one Claude Code terminal at a time, you can ignore this file.**