anvil-dev-framework 0.1.7 → 0.1.9

package/project/rules/debugging.md

@@ -0,0 +1,139 @@
+# Debugging Rules
+
+> Systematic approach for cross-layer debugging.
+
+---
+
+## Debugging Process
+
+### 1. Reproduce
+- [ ] Can reproduce consistently
+- [ ] Identified trigger conditions
+- [ ] Documented reproduction steps
+- [ ] Minimal reproduction case created
+
+### 2. Isolate
+- [ ] Identified layer (UI/API/DB/External)
+- [ ] Narrowed to specific component
+- [ ] Traced data flow through system
+- [ ] Identified last known good state
+
+### 3. Diagnose
+- [ ] Read error messages/logs
+- [ ] Checked recent changes
+- [ ] Verified assumptions
+- [ ] Tested hypotheses
+
+### 4. Fix
+- [ ] Root cause addressed (not symptom)
+- [ ] Fix is minimal and focused
+- [ ] Side effects considered
+- [ ] Regression test added
+
+---
+
+## Layer-Specific Checks
+
+### Frontend (React/Next.js)
+- Console errors
+- Network tab requests/responses
+- Component state
+- Props drilling issues
+- Hydration mismatches
+
+### API Layer
+- Request/response logging
+- Middleware chain
+- Authentication/authorization
+- Error handling paths
+- Rate limiting
+
+### Database
+- Query execution plans
+- Connection pool status
+- Transaction isolation
+- Index usage
+- Lock contention
+
+### External Services
+- API response codes
+- Timeout handling
+- Retry logic
+- Circuit breaker state
+- Rate limit status
+
+---
+
+## Common Patterns
+
+### Data Flow Issues
+```
+Request → Middleware → Handler → Service → Database
+                                    ↓
+Response ← Transform ← Error Handle ← Result
+```
+
+Check each transition point for:
+- Data shape changes
+- Error swallowing
+- Type coercion
+- Null/undefined handling
+
+### Async Issues
+- Race conditions
+- Unhandled rejections
+- Memory leaks (listeners)
+- Stale closures
+- Missing await
+
+### State Issues
+- Stale state
+- State mutations
+- Re-render loops
+- Context sync
+- Cache invalidation
+
+---
+
+## Diagnostic Tools
+
+| Layer | Tools |
+|-------|-------|
+| Frontend | React DevTools, Network tab |
+| API | Request logging, Debug middleware |
+| Database | Query analyzer, pg_stat_statements |
+| General | Git bisect, Feature flags |
+
+---
+
+## Escalation Criteria
+
+Escalate when:
+1. Reproduction requires production data
+2. Issue spans multiple services
+3. Suspected security vulnerability
+4. After 30 minutes without progress
+5. Fix requires architecture change
+
+---
+
+## Report Format
+
+```markdown
+## Bug Investigation: [Title]
+
+### Symptoms
+[Observable behavior]
+
+### Root Cause
+[Why it happens]
+
+### Affected Areas
+[Components/services impacted]
+
+### Fix Applied
+[What was changed]
+
+### Prevention
+[How to prevent similar issues]
+```

package/project/rules/security-review.md

@@ -0,0 +1,115 @@
+# Security Review Rules
+
+> Checklist and guidelines for security-focused code review.
+
+---
+
+## OWASP Top 10 Checklist
+
+### A01: Broken Access Control
+- [ ] Authorization checked on every endpoint
+- [ ] Direct object references validated
+- [ ] No privilege escalation paths
+- [ ] CORS properly configured
+
+### A02: Cryptographic Failures
+- [ ] Sensitive data encrypted at rest
+- [ ] TLS used for data in transit
+- [ ] No hardcoded secrets
+- [ ] Strong algorithms used (AES-256, bcrypt)
+
+### A03: Injection
+- [ ] Parameterized queries for SQL
+- [ ] Input validation on all user data
+- [ ] Output encoding for XSS prevention
+- [ ] Command injection prevented
+
+### A04: Insecure Design
+- [ ] Threat modeling performed
+- [ ] Security requirements defined
+- [ ] Rate limiting implemented
+- [ ] Input validation at boundaries
+
+### A05: Security Misconfiguration
+- [ ] Security headers present
+- [ ] Debug mode disabled
+- [ ] Default credentials changed
+- [ ] Unnecessary features disabled
+
+### A06: Vulnerable Components
+- [ ] Dependencies up to date
+- [ ] Known vulnerabilities checked
+- [ ] Unused dependencies removed
+- [ ] License compliance verified
+
+### A07: Authentication Failures
+- [ ] Strong password policy
+- [ ] MFA available
+- [ ] Session management secure
+- [ ] Brute force protection
+
+### A08: Integrity Failures
+- [ ] Dependencies verified
+- [ ] CI/CD pipeline secure
+- [ ] Code signing in place
+- [ ] Update mechanism secure
+
+### A09: Logging Failures
+- [ ] Security events logged
+- [ ] No sensitive data in logs
+- [ ] Log integrity protected
+- [ ] Alerting configured
+
+### A10: SSRF
+- [ ] URL validation for user input
+- [ ] Allow-list for external requests
+- [ ] Internal services protected
+- [ ] Metadata endpoints blocked
+
+---
+
+## Review Process
+
+1. **Static Analysis**: Check for obvious vulnerabilities
+2. **Authentication**: Verify auth flows
+3. **Authorization**: Trace permission checks
+4. **Data Flow**: Follow sensitive data
+5. **Dependencies**: Check for known issues
+6. **Configuration**: Review security settings
+
+---
+
+## Red Flags
+
+- Hardcoded credentials or API keys
+- SQL string concatenation
+- `eval()` or `exec()` with user input
+- Missing HTTPS enforcement
+- Overly permissive CORS
+- Debug endpoints in production
+- Missing rate limiting
+- Sensitive data in URLs
+
+---
+
+## Reporting Format
+
+```markdown
+## Finding: [Title]
+
+**Severity**: Critical|High|Medium|Low
+**Location**: [file:line]
+**CWE**: CWE-XXX
+
+### Description
+[What the vulnerability is]
+
+### Impact
+[What could happen if exploited]
+
+### Recommendation
+[How to fix it]
+
+### Code Reference
+[Specific code that needs change]
+```

package/project/settings.yaml.template

@@ -0,0 +1,185 @@
+# =============================================================================
+# Anvil Framework Configuration (.claude/settings.yaml)
+# =============================================================================
+#
+# This file configures Claude Code behaviors for this project.
+# All settings are optional - sensible defaults are used when not specified.
+#
+# Configuration priority (highest to lowest):
+#   1. Project .claude/settings.yaml (this file)
+#   2. User ~/.claude/settings.yaml
+#   3. Built-in defaults
+#
+
+# =============================================================================
+# Verification Configuration
+# =============================================================================
+#
+# Controls the /verify command behavior for running tests, lint, and type checks
+# with automatic iteration on failures.
+#
+# Usage:
+#   /verify              - Run full verification suite
+#   /verify --quick      - Skip type checking
+#   /verify --test-only  - Run tests only
+#
+
+verification:
+  # Commands to run for each check type
+  # If not specified, auto-detected based on project type (package.json, pyproject.toml, etc.)
+  commands:
+    # test: "npm test"           # Node.js default
+    # test: "pytest"             # Python default
+    # test: "cargo test"         # Rust default
+    # test: "go test ./..."      # Go default
+
+    # lint: "npm run lint"       # Node.js default
+    # lint: "ruff check ."       # Python default
+    # lint: "cargo clippy"       # Rust default
+    # lint: "golangci-lint run"  # Go default
+
+    # types: "npm run typecheck" # Node.js default
+    # types: "mypy ."            # Python default
+    # types: "cargo check"       # Rust default
+
+  # Maximum automatic fix iterations before escalating
+  # After this many failed attempts, manual intervention is requested
+  max_iterations: 3
+
+  # Whether passing verification is required before commit/completion
+  # When true, stop hook will block exit if verification hasn't passed
+  required_for_completion: true
+
+  # Timeout for individual verification commands (seconds)
+  # Commands exceeding this will be killed and marked as failed
+  timeout_seconds: 300
+
+
+# =============================================================================
+# Stop Hook Configuration
+# =============================================================================
+#
+# Controls exit gating based on verification state.
+# Prevents accidental exits when work is incomplete.
+#
+# Hook Registration (add to .claude/settings.json):
+# {
+#   "hooks": {
+#     "Stop": [{
+#       "type": "command",
+#       "command": "bash global/hooks/stop_gate.sh"
+#     }]
+#   }
+# }
+#
+# Environment Variables:
+#   ANVIL_REQUIRE_VERIFICATION - Set to "false" to disable gate (default: true)
+#   ANVIL_FORCE_EXIT           - Set to "true" to bypass gate
+#   ANVIL_STOP_GATE_LOG        - Set to "true" to enable logging
+#
+
+stop_gate:
+  # Whether to require verification before allowing exit
+  require_verification: true
+
+  # Allow force exit with /force-exit command
+  allow_force_exit: true
+
+  # Minimum checks that must pass before allowing exit
+  required_checks:
+    - tests
+    - lint
+    # - types  # Uncomment to also require type checks
+
+
+# =============================================================================
+# Ralph Wiggum Mode Configuration
+# =============================================================================
+#
+# Long-running unattended execution mode settings.
+# Uses completion promises and iteration loops for multi-hour autonomous sessions.
+#
+
+ralph:
+  # Maximum iterations before stopping (safety limit)
+  max_iterations: 50
+
+  # State file location for tracking progress
+  state_file: ".claude/ralph-state.json"
+
+  # Prompt template location
+  template_dir: "global/templates/ralph"
+
+
+# =============================================================================
+# PostToolUse Hook Configuration
+# =============================================================================
+#
+# Automatic formatting after Edit/Write operations.
+# Catches the "last 10%" of formatting issues that Claude often misses.
+#
+# Hook Registration (add to .claude/settings.json):
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "Edit|Write",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "bash global/hooks/post_tool_format.sh"
+#       }]
+#     }]
+#   }
+# }
+#
+# Environment Variables:
+#   CLAUDE_FILE_PATH     - Path to file (set automatically by Claude)
+#   ANVIL_FORMAT_LOG     - Set to "true" to enable logging
+#   ANVIL_FORMAT_TIMEOUT - Timeout in seconds (default: 5)
+#
+# Supported Formatters:
+#   JS/TS: prettier       Python: black/ruff
+#   Go: gofmt             Bash: shfmt
+#   Rust: rustfmt         YAML: prettier
+#
+
+formatting:
+  # Enable auto-formatting after file edits
+  enabled: true
+
+  # Paths to exclude from auto-formatting
+  exclude_paths:
+    - "node_modules/**"
+    - ".git/**"
+    - "dist/**"
+    - "build/**"
+    - "*.lock"
+    - "package-lock.json"
+    - "yarn.lock"
+
+  # Maximum file size to format (bytes)
+  max_file_size: 1000000  # 1MB
+
+
+# =============================================================================
+# Project Detection
+# =============================================================================
+#
+# Override automatic project type detection.
+# Usually not needed - auto-detection works for most projects.
+#
+
+# project:
+#   type: "nodejs"  # nodejs, python, rust, go
+#   root: "."       # Project root relative to this file
+
+
+# =============================================================================
+# Documentation
+# =============================================================================
+#
+# For full documentation on configuration options, see:
+# - /verify command: global/commands/verify.md
+# - Stop hook: global/hooks/stop_gate.sh
+# - Ralph mode: global/commands/ralph.md
+# - Formatting: global/hooks/post_tool_format.sh
+#