anvil-dev-framework 0.1.6

package/global/lib/verify_subagent.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""
+verify_subagent.py - Invocation wrapper for the verify-app subagent.
+
+This module provides functions to invoke the verification subagent and
+parse its structured JSON response.
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+# Verification result structure
+class VerificationResult:
+    """Structured verification result."""
+
+    def __init__(self, data: dict):
+        self.overall = data.get("overall", "fail")
+        self.tests = data.get("tests", {"passed": False, "count": 0, "failures": []})
+        self.lint = data.get("lint", {"passed": False, "errors": 0})
+        self.types = data.get("types", {"passed": False, "errors": 0})
+        self.summary = data.get("summary", "Verification failed")
+        self._raw = data
+
+    @property
+    def passed(self) -> bool:
+        """Overall pass/fail status."""
+        return self.overall == "pass"
+
+    @property
+    def test_count(self) -> int:
+        """Number of tests run."""
+        return self.tests.get("count", 0)
+
+    @property
+    def test_failures(self) -> list:
+        """List of test failures."""
+        return self.tests.get("failures", [])
+
+    @property
+    def lint_errors(self) -> int:
+        """Number of lint errors."""
+        return self.lint.get("errors", 0)
+
+    @property
+    def type_errors(self) -> int:
+        """Number of type errors."""
+        return self.types.get("errors", 0)
+
+    def to_dict(self) -> dict:
+        """Return raw dictionary."""
+        return self._raw
+
+    def __repr__(self) -> str:
+        return f"VerificationResult(overall={self.overall}, summary={self.summary!r})"
+
+
+def detect_project_type(project_path: Optional[Path] = None) -> str:
+    """Detect project type from config files."""
+    path = project_path or Path.cwd()
+
+    if (path / "package.json").exists():
+        return "node"
+    elif (path / "pyproject.toml").exists() or (path / "setup.py").exists():
+        return "python"
+    elif (path / "Cargo.toml").exists():
+        return "rust"
+    elif (path / "go.mod").exists():
+        return "go"
+    else:
+        return "unknown"
+
+
+def get_verification_commands(project_type: str) -> dict:
+    """Get verification commands for project type."""
+    commands = {
+        "node": {
+            "test": "npm test",
+            "lint": "npm run lint",
+            "typecheck": "npm run typecheck"
+        },
+        "python": {
+            "test": "pytest",
+            "lint": "ruff check .",
+            "typecheck": "mypy ."
+        },
+        "rust": {
+            "test": "cargo test",
+            "lint": "cargo clippy -- -D warnings",
+            "typecheck": None  # Included in clippy
+        },
+        "go": {
+            "test": "go test ./...",
+            "lint": "golangci-lint run",
+            "typecheck": None  # Included in build
+        }
+    }
+    return commands.get(project_type, {})
+
+
+def run_verification_local(project_path: Optional[Path] = None) -> VerificationResult:
+    """
+    Run verification locally without subagent.
+
+    This is a fallback when the subagent is not available.
+    """
+    path = project_path or Path.cwd()
+    project_type = detect_project_type(path)
+    commands = get_verification_commands(project_type)
+
+    result = {
+        "overall": "pass",
+        "tests": {"passed": True, "count": 0, "failures": []},
+        "lint": {"passed": True, "errors": 0, "warnings": 0},
+        "types": {"passed": True, "errors": 0},
+        "summary": ""
+    }
+
+    issues = []
+
+    # Run tests
+    if commands.get("test"):
+        try:
+            proc = subprocess.run(
+                commands["test"],
+                shell=True,
+                cwd=path,
+                capture_output=True,
+                text=True,
+                timeout=300
+            )
+            if proc.returncode != 0:
+                result["tests"]["passed"] = False
+                result["overall"] = "fail"
+                issues.append("tests failed")
+        except subprocess.TimeoutExpired:
+            result["tests"]["passed"] = False
+            result["overall"] = "fail"
+            issues.append("tests timed out")
+        except Exception as e:
+            result["tests"]["passed"] = False
+            issues.append(f"test error: {e}")
+
+    # Run lint
+    if commands.get("lint"):
+        try:
+            proc = subprocess.run(
+                commands["lint"],
+                shell=True,
+                cwd=path,
+                capture_output=True,
+                text=True,
+                timeout=120
+            )
+            if proc.returncode != 0:
+                result["lint"]["passed"] = False
+                result["lint"]["errors"] = 1  # At least one
+                result["overall"] = "fail"
+                issues.append("lint errors")
+        except Exception:
+            pass  # Lint failure is non-fatal
+
+    # Run typecheck
+    if commands.get("typecheck"):
+        try:
+            proc = subprocess.run(
+                commands["typecheck"],
+                shell=True,
+                cwd=path,
+                capture_output=True,
+                text=True,
+                timeout=120
+            )
+            if proc.returncode != 0:
+                result["types"]["passed"] = False
+                result["types"]["errors"] = 1
+                result["overall"] = "fail"
+                issues.append("type errors")
+        except Exception:
+            pass  # Type check failure is non-fatal
+
+    # Build summary
+    if result["overall"] == "pass":
+        result["summary"] = "All checks passed."
+    else:
+        result["summary"] = f"Verification failed: {', '.join(issues)}"
+
+    return VerificationResult(result)
+
+
+def invoke_verify_subagent(
+    prompt: str = "Run full verification suite and report results as JSON",
+    timeout: int = 300,
+    project_path: Optional[Path] = None
+) -> VerificationResult:
+    """
+    Invoke the verify-app subagent.
+
+    This function spawns a Claude Code subagent to run verification.
+    If the subagent is not available, falls back to local verification.
+
+    Args:
+        prompt: The prompt to send to the subagent
+        timeout: Timeout in seconds
+        project_path: Path to the project to verify
+
+    Returns:
+        VerificationResult with structured results
+    """
+    # For now, use local verification as the subagent invocation
+    # requires the Task tool which is only available in Claude Code context
+    return run_verification_local(project_path)
+
+
+def main():
+    """CLI interface for verification."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Run project verification")
+    parser.add_argument("--path", type=Path, help="Project path")
+    parser.add_argument("--json", action="store_true", help="Output JSON")
+    args = parser.parse_args()
+
+    result = run_verification_local(args.path)
+
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        status = "✅ PASS" if result.passed else "❌ FAIL"
+        print(f"\n{status}: {result.summary}\n")
+
+        if not result.tests.get("passed", True):
+            print("Test Failures:")
+            for failure in result.test_failures:
+                print(f"  - {failure.get('file', 'unknown')}:{failure.get('line', '?')} - {failure.get('message', 'failed')}")
+
+        if result.lint_errors > 0:
+            print(f"Lint Errors: {result.lint_errors}")
+
+        if result.type_errors > 0:
+            print(f"Type Errors: {result.type_errors}")
+
+    sys.exit(0 if result.passed else 1)
+
+
+if __name__ == "__main__":
+    main()

package/global/skills/README.md

@@ -0,0 +1,155 @@
+# Skills
+
+Skills are domain-specific knowledge modules that Claude loads on-demand to enhance its capabilities in specialized areas.
+
+## Why Skills?
+
+Skills solve the context window problem:
+- **Without skills**: All knowledge must fit in system prompt (limited)
+- **With skills**: Load only relevant knowledge when needed (efficient)
+
+## Skill Structure
+
+Each skill is a directory containing:
+
+```
+skills/
+└── my-skill/
+    ├── SKILL.md           # Main skill file (required)
+    ├── README.md          # Human documentation (optional)
+    └── examples/          # Reference examples (optional)
+        ├── example-1.ts
+        └── example-2.ts
+```
+
+### SKILL.md Format
+
+```markdown
+---
+name: My Skill
+description: Brief description of what this skill provides
+triggers:
+  - keyword1
+  - keyword2
+version: 1.0.0
+---
+
+# My Skill
+
+## When to Use
+[Describe when Claude should load this skill]
+
+## Key Concepts
+[Domain knowledge Claude needs]
+
+## Patterns
+[Specific patterns to follow]
+
+## Examples
+[Code examples or references to examples/ directory]
+
+## Anti-Patterns
+[What to avoid]
+
+## References
+[Links to external documentation]
+```
+
+## How Skills Work
+
+1. **Trigger**: User request mentions skill keywords
+2. **Load**: Claude reads SKILL.md into context
+3. **Apply**: Claude uses skill knowledge for the task
+4. **Unload**: Skill naturally leaves context after task
+
+## Creating a New Skill
+
+1. Copy `skill-template/` to `skills/your-skill-name/`
+2. Edit `SKILL.md` with your domain knowledge
+3. Add examples if helpful
+4. Test by asking Claude to use the skill
+
+## Built-in vs Custom Skills
+
+**Built-in** (from Anvil):
+- None included by default
+- Framework provides structure, not content
+
+**Custom** (you create):
+- Project-specific patterns
+- Tech stack conventions
+- Domain knowledge
+
+## Skill Categories
+
+Consider organizing skills by domain:
+
+```
+skills/
+├── frontend/
+│   ├── component-patterns/
+│   ├── state-management/
+│   └── accessibility/
+├── backend/
+│   ├── api-design/
+│   ├── database-patterns/
+│   └── security/
+├── testing/
+│   ├── unit-testing/
+│   └── integration-testing/
+└── devops/
+    ├── ci-cd/
+    └── deployment/
+```
+
+## Best Practices
+
+1. **Keep skills focused** — One skill = one domain
+2. **Include examples** — Show, don't just tell
+3. **Document triggers** — Help Claude know when to load
+4. **Version skills** — Track changes over time
+5. **Test skills** — Verify they improve output quality
+
+## Skill Size Guidelines
+
+| Size | Lines | Use Case |
+|------|-------|----------|
+| Small | <100 | Single pattern or concept |
+| Medium | 100-300 | Domain with multiple patterns |
+| Large | 300-500 | Complex domain (consider splitting) |
+| Too Large | >500 | Split into multiple skills |
+
+## Example: Security Patterns Skill
+
+```markdown
+---
+name: Backend Security Patterns
+description: Security patterns for API routes and data handling
+triggers:
+  - security
+  - authentication
+  - authorization
+  - api route
+version: 1.0.0
+---
+
+# Backend Security Patterns
+
+## Authentication
+- Always verify session on protected routes
+- Use httpOnly cookies for tokens
+- Implement CSRF protection
+
+## Authorization
+- Check permissions before operations
+- Use Row Level Security in database
+- Validate ownership of resources
+
+## Input Validation
+- Sanitize all user input
+- Use parameterized queries
+- Validate types and ranges
+
+## Examples
+See examples/auth-middleware.ts
+```

package/global/skills/quality-gates/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: Quality Gates
+description: Layered quality gate patterns for catching issues at the right time
+triggers:
+  - quality gates
+  - pre-commit
+  - pre-push
+  - ci pipeline
+  - git hooks
+  - lint
+  - typecheck
+version: 1.0.0
+---
+
+# Quality Gates
+
+Framework-agnostic patterns for layered quality validation.
+
+## Philosophy
+
+**Catch issues at the right time, not all at once.**
+
+Running full validation on every keystroke is slow. Running nothing until CI is too late. Layer your gates by speed and scope.
+
+---
+
+## Layer Model
+
+| Layer | When | Speed Target | Scope |
+|-------|------|--------------|-------|
+| Pre-commit | Before each commit | <5 seconds | Staged files only |
+| Pre-push | Before pushing | <30 seconds | Changed files |
+| CI | After push | Minutes | Full codebase |
+
+---
+
+## Pre-Commit Layer (Fast, Staged Files)
+
+**Purpose:** Catch obvious issues immediately. Must be fast or developers bypass.
+
+### Typical Checks
+- Linting (staged files only)
+- Formatting (auto-fix)
+- No debug statements (console.log, print, debugger)
+- No secrets (quick pattern match)
+- Commit message format
+
+### Implementation Patterns
+
+**Node/TypeScript (husky + lint-staged):**
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{json,md}": ["prettier --write"]
+  }
+}
+```
+
+**Python (pre-commit):**
+```yaml
+repos:
+  - repo: https://github.com/psf/black
+    hooks:
+      - id: black
+  - repo: https://github.com/pycqa/flake8
+    hooks:
+      - id: flake8
+```
+
+### What NOT to Include
+- Type checking (too slow for staged files)
+- Full test suite
+- Build verification
+- Anything >5 seconds
+
+---
+
+## Pre-Push Layer (Thorough, Changed Files)
+
+**Purpose:** Catch type errors and test failures before remote.
+
+### Typical Checks
+- Type checking
+- Unit tests (affected by changes)
+- Build verification (if fast)
+- Security scanning (quick)
+
+### Implementation Pattern
+
+```bash
+# .git/hooks/pre-push or via husky
+npm run typecheck
+npm run test -- --changedSince=origin/main
+```
+
+### Tradeoff
+Can be skipped with `--no-verify` for WIP pushes. CI catches what slips through.
+
+---
+
+## CI Layer (Comprehensive, Full Suite)
+
+**Purpose:** Canonical quality verification. Never skip.
+
+### Typical Checks
+- Full lint
+- Full type check
+- Full test suite (unit + integration)
+- Build verification
+- Security scanning (dependencies, SAST)
+- Coverage thresholds
+
+### AI-Specific Additions
+
+Checks particularly relevant for AI-generated code:
+
+```yaml
+# Check for common AI mistakes
+- name: Check for 'any' types
+  run: grep -r "any" src/ && exit 1 || exit 0
+  
+- name: Check for console.log
+  run: grep -r "console.log" src/ && exit 1 || exit 0
+  
+- name: Check TODO without issue
+  run: grep -rn "TODO" src/ | grep -v "TODO(#" && exit 1 || exit 0
+```
+
+### Security Scanning Tools
+
+| Tool | Purpose | Speed |
+|------|---------|-------|
+| gitleaks/trufflehog | Secrets in commits | Fast |
+| npm audit / pip audit | Dependency vulnerabilities | Fast |
+| Semgrep | SAST (code patterns) | Medium |
+| Trivy | Container scanning | Medium |
+
+---
+
+## Configuration by Ecosystem
+
+### Node.js / TypeScript
+
+```json
+// package.json
+{
+  "scripts": {
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:staged": "eslint --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:ci": "vitest run --coverage",
+    "precommit": "lint-staged",
+    "prepush": "npm run typecheck && npm test"
+  }
+}
+```
+
+### Python
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: pytest
+        language: system
+        pass_filenames: false
+        stages: [push]
+```
+
+### Go
+
+```bash
+# Makefile
+lint:
+	golangci-lint run
+
+test:
+	go test ./...
+
+pre-commit:
+	gofmt -w .
+	golangci-lint run --fast
+
+pre-push:
+	go test ./...
+```
+
+---
+
+## Anti-Patterns
+
+❌ **Running full suite on pre-commit**
+- Too slow → gets bypassed
+- Fix: Staged files only, defer heavy checks
+
+❌ **No pre-push checks**
+- CI feedback too slow (minutes vs seconds)
+- Fix: Add quick type/test check before push
+
+❌ **Skippable CI checks**
+- Defeats the purpose
+- Fix: Required status checks on main
+
+❌ **Notifications without blocking**
+- Gets ignored
+- Fix: Block merge, not just notify
+
+❌ **Same checks at every layer**
+- Redundant, slow
+- Fix: Layer by speed and scope
+
+---
+
+## Quality Gate Checklist
+
+Before committing:
+- [ ] Pre-commit hooks installed and running
+- [ ] Lint passes on staged files
+- [ ] No debug statements
+
+Before pushing:
+- [ ] Types pass
+- [ ] Tests pass (affected files)
+- [ ] No secrets in diff
+
+Before merge (CI):
+- [ ] Full test suite passes
+- [ ] Coverage threshold met
+- [ ] Security scan clean
+- [ ] Build succeeds
+
+---
+
+## Implementation Notes
+
+This skill provides **patterns**, not project-specific configuration.
+
+**Project implements:**
+- Install git hooks tooling (husky, pre-commit, etc.)
+- Configure hooks for project's tech stack
+- Set up CI pipeline
+- Document in CONTRIBUTING.md
+
+**Framework provides:**
+- Principles (layer by speed/scope)
+- Common patterns per ecosystem
+- Anti-patterns to avoid