anvil-dev-framework 0.1.6

package/docs/specifications/SPEC-ANV-VRW/component-05-atomic-actions.md

@@ -0,0 +1,311 @@
+---
+shard_id: SPEC-ANV-VRW/component-05
+parent: SPEC-ANV-VRW
+title: Atomic Action Commands
+status: draft
+linear_issue: ANV-146
+priority: P1
+estimated_hours: 3-4
+dependencies:
+  - component-01-verify
+---
+
+# Component 5: Atomic Action Commands
+
+## Overview
+
+Single commands that execute complete workflows for rapid inner-loop execution. These are the "one-liners" that Boris Cherny uses for fast iteration.
+
+> Boris Cherny: "Atomic action commands for inner loops"
+
+---
+
+## Commands
+
+| Command | Purpose | Workflow |
+|---------|---------|----------|
+| `/test-and-commit` | Safe commit with tests | test → commit |
+| `/commit-push-pr` | Full PR workflow | commit → push → PR |
+| `/lint-fix` | Auto-fix lint issues | lint --fix → stage |
+
+---
+
+## Requirements
+
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|-------------|----------|---------------------|
+| REQ-AA-100 | `/test-and-commit` runs tests before committing | P0 | No commit if tests fail |
+| REQ-AA-101 | `/commit-push-pr` handles full workflow | P0 | PR created successfully |
+| REQ-AA-102 | `/lint-fix` auto-fixes lintable issues | P1 | Fixable issues resolved |
+| REQ-AA-103 | All commands have clear success/failure output | P0 | Status visible |
+| REQ-AA-104 | Commands respect git conventions | P0 | Conventional commits |
+| REQ-AA-105 | Atomic execution (all-or-nothing) | P0 | No partial state |
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create /test-and-commit
+**File**: `global/commands/test-and-commit.md`
+**Estimated**: 1 hour
+
+- [ ] Run test suite first
+- [ ] If pass: stage and commit
+- [ ] If fail: report errors, no commit
+- [ ] Accept commit message argument
+- [ ] Support conventional commit format
+
+### Task 2: Create /commit-push-pr
+**File**: `global/commands/commit-push-pr.md`
+**Estimated**: 1.5 hours
+
+- [ ] Stage all changes
+- [ ] Create commit with message
+- [ ] Push to remote
+- [ ] Create PR with `gh pr create`
+- [ ] Return PR URL
+- [ ] Handle push failures
+
+### Task 3: Create /lint-fix
+**File**: `global/commands/lint-fix.md`
+**Estimated**: 0.5 hours
+
+- [ ] Run linter with `--fix` flag
+- [ ] Report remaining unfixable issues
+- [ ] Stage auto-fixed changes
+- [ ] Support multiple linters
+
+### Task 4: Error Handling
+**Estimated**: 1 hour
+
+- [ ] Clear failure messages for each command
+- [ ] No partial state on failure
+- [ ] Rollback on error
+- [ ] Suggest fixes for common issues
+
+---
+
+## Command: `/test-and-commit`
+
+```markdown
+# /test-and-commit - Test Then Commit
+
+> Run tests, and if passing, commit changes.
+
+## Arguments
+- `message` (required) - Commit message
+
+## Execution
+1. Run configured test suite
+2. If pass:
+   - Stage all changes
+   - Create commit with provided message
+   - Report success
+3. If fail:
+   - Report test failures
+   - Do NOT create commit
+   - Suggest fixes
+
+## Usage
+/test-and-commit "feat: add user authentication"
+
+## Success Output
+✅ Tests passed (47 tests)
+✅ Committed: feat: add user authentication
+   abc1234 - 3 files changed, 145 insertions(+), 23 deletions(-)
+
+## Failure Output
+❌ Tests failed (2 failures)
+
+Failing tests:
+- src/auth/login.test.ts:45 - Expected 200, got 401
+- src/auth/login.test.ts:67 - Timeout
+
+No commit created. Fix tests first.
+```
+
+---
+
+## Command: `/commit-push-pr`
+
+```markdown
+# /commit-push-pr - Full Commit Workflow
+
+> Commit, push, and create PR in one command.
+
+## Arguments
+- `message` (required) - Commit message (used for PR title)
+
+## Execution
+1. Stage all changes
+2. Create commit with conventional message
+3. Push to current branch (or create branch)
+4. Create PR with `gh pr create`
+5. Return PR URL
+
+## Usage
+/commit-push-pr "feat: add OAuth support"
+
+## Success Output
+✅ Committed: feat: add OAuth support
+   abc1234 - 5 files changed
+✅ Pushed to origin/feature/oauth
+✅ PR created: https://github.com/org/repo/pull/42
+
+## Failure Output
+❌ Push failed: no upstream branch
+
+Suggested fix:
+git push -u origin $(git branch --show-current)
+
+## Prerequisites
+- `gh` CLI installed and authenticated
+- Remote repository configured
+- Git credentials available
+```
+
+---
+
+## Command: `/lint-fix`
+
+```markdown
+# /lint-fix - Auto-Fix Lint Issues
+
+> Run linter with auto-fix enabled.
+
+## Arguments
+- (none) - Fix all files
+- `path` (optional) - Fix specific path
+
+## Execution
+1. Run linter with --fix flag
+2. Report remaining unfixable issues
+3. Stage auto-fixed changes
+
+## Usage
+/lint-fix
+/lint-fix src/components/
+
+## Success Output
+✅ Lint auto-fix complete
+
+Fixed 12 issues:
+- 5 formatting issues
+- 4 import order issues
+- 3 unused import removals
+
+Remaining (manual fix required):
+- src/utils/api.ts:45 - 'x' is defined but never used
+
+Changes staged for commit.
+
+## Supported Linters
+- ESLint (--fix)
+- Prettier (--write)
+- Ruff (--fix)
+- Biome (--apply)
+```
+
+---
+
+## Skill Implementations
+
+### test-and-commit.md
+
+```markdown
+# /test-and-commit - Test Then Commit
+
+> Run tests, and if passing, commit changes.
+
+## Execution Steps
+
+### Step 1: Run Tests
+Execute the project's test suite:
+- npm test / pytest / cargo test / etc.
+- Capture exit code and output
+
+### Step 2: Evaluate Results
+If tests pass (exit 0):
+- Proceed to commit
+If tests fail (exit non-zero):
+- Report failures
+- Stop execution
+
+### Step 3: Create Commit
+If tests passed:
+- git add .
+- git commit -m "[message]"
+- Report commit details
+
+## Anti-Patterns
+- ❌ Committing without running tests
+- ❌ Ignoring test failures
+- ❌ Using generic commit messages
+```
+
+### commit-push-pr.md
+
+```markdown
+# /commit-push-pr - Full Commit Workflow
+
+> Commit, push, and create PR in one command.
+
+## Execution Steps
+
+### Step 1: Stage Changes
+git add .
+
+### Step 2: Create Commit
+git commit -m "[message]"
+
+### Step 3: Push to Remote
+git push origin [current-branch]
+- If no upstream, use: git push -u origin [branch]
+
+### Step 4: Create PR
+gh pr create --title "[message]" --body "[auto-generated]"
+- Include summary of changes
+- Add conventional commit type
+
+### Step 5: Report Result
+Return PR URL for user reference
+
+## Anti-Patterns
+- ❌ Pushing to protected branches directly
+- ❌ Creating PRs without tests passing
+- ❌ Using force push
+```
+
+---
+
+## Test Cases
+
+| Command | Scenario | Expected |
+|---------|----------|----------|
+| `/test-and-commit` | Tests pass | Commit created |
+| `/test-and-commit` | Tests fail | No commit, errors shown |
+| `/commit-push-pr` | Normal workflow | PR created, URL returned |
+| `/commit-push-pr` | No remote | Error with suggestion |
+| `/lint-fix` | Fixable issues | Issues fixed, staged |
+| `/lint-fix` | Unfixable issues | Report remaining |
+
+---
+
+## Error Handling
+
+| Error | Command | Response |
+|-------|---------|----------|
+| Tests failing | test-and-commit | List failures, no commit |
+| No git repo | all | "Not a git repository" |
+| Push rejected | commit-push-pr | Suggest pull/rebase |
+| gh not installed | commit-push-pr | Install instructions |
+| Nothing to commit | all | "No changes to commit" |
+
+---
+
+## Integration Points
+
+- **Trigger**: User invokes command
+- **Input**: Commit message
+- **Output**: Success/failure with details
+- **Dependencies**: component-01 (verify) for test-and-commit

package/docs/specifications/SPEC-ANV-VRW/component-06-verify-subagent.md

@@ -0,0 +1,264 @@
+---
+shard_id: SPEC-ANV-VRW/component-06
+parent: SPEC-ANV-VRW
+title: Verification Subagent
+status: draft
+linear_issue: ANV-147
+priority: P2
+estimated_hours: 2-3
+dependencies:
+  - component-01-verify
+---
+
+# Component 6: Verification Subagent
+
+## Overview
+
+A dedicated subagent for verification that keeps verification context out of the main session. This prevents context pollution from test output and verification logs.
+
+> Boris Cherny: "Subagents for research... don't pollute main context"
+
+---
+
+## Requirements
+
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|-------------|----------|---------------------|
+| REQ-VS-100 | Subagent runs all verification checks | P0 | Tests, lint, types all execute |
+| REQ-VS-101 | Returns structured pass/fail report | P0 | JSON response format |
+| REQ-VS-102 | Isolates verification context from main session | P0 | No context pollution |
+| REQ-VS-103 | Supports custom verification commands | P1 | Config overrides work |
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create Subagent Configuration
+**File**: `global/agents/verify-app.json`
+**Estimated**: 0.5 hours
+
+- [ ] Define agent name and description
+- [ ] Limit available tools (Bash, Read, Glob)
+- [ ] Create specialized prompt
+- [ ] Set appropriate model
+
+### Task 2: Create Agent Definition
+**Estimated**: 1 hour
+
+- [ ] Register in agent system
+- [ ] Define invocation pattern
+- [ ] Set context limits
+- [ ] Add error handling
+
+### Task 3: Create Invocation Wrapper
+**File**: `global/lib/verify_subagent.py`
+**Estimated**: 1 hour
+
+- [ ] Parse verification config
+- [ ] Spawn subagent with prompt
+- [ ] Collect structured results
+- [ ] Handle timeout and errors
+
+---
+
+## Agent Configuration
+
+```json
+{
+  "name": "verify-app",
+  "description": "Verification subagent for running tests, lint, and type checks",
+  "model": "haiku",
+  "tools": ["Bash", "Read", "Glob"],
+  "max_tokens": 4096,
+  "prompt": "You are a verification agent. Your job is to run all project checks and report results in structured JSON format.\n\nAlways output results as:\n{\n  \"tests\": { \"passed\": true, \"count\": 47, \"failures\": [] },\n  \"lint\": { \"passed\": true, \"errors\": 0 },\n  \"types\": { \"passed\": true, \"errors\": 0 }\n}"
+}
+```
+
+---
+
+## Invocation Pattern
+
+### From Main Agent
+
+```python
+# Using Task tool with verify-app subagent
+Task(
+  subagent_type="verify-app",
+  prompt="Run full verification suite and report results",
+  model="haiku"
+)
+```
+
+### Response Format
+
+```json
+{
+  "overall": "pass",
+  "tests": {
+    "passed": true,
+    "count": 47,
+    "duration_ms": 3200,
+    "failures": []
+  },
+  "lint": {
+    "passed": true,
+    "errors": 0,
+    "warnings": 3
+  },
+  "types": {
+    "passed": true,
+    "errors": 0
+  },
+  "summary": "All 47 tests passed. Lint clean. Types clean."
+}
+```
+
+### Failure Response
+
+```json
+{
+  "overall": "fail",
+  "tests": {
+    "passed": false,
+    "count": 47,
+    "duration_ms": 3200,
+    "failures": [
+      {
+        "file": "src/auth/login.test.ts",
+        "line": 45,
+        "message": "Expected 200, got 401"
+      }
+    ]
+  },
+  "lint": {
+    "passed": true,
+    "errors": 0
+  },
+  "types": {
+    "passed": true,
+    "errors": 0
+  },
+  "summary": "1 test failure. See failures array for details."
+}
+```
+
+---
+
+## Subagent Prompt
+
+```markdown
+# Verification Agent
+
+You are a specialized verification agent. Your sole purpose is to run project checks and report results.
+
+## Your Task
+1. Run the test suite
+2. Run the linter
+3. Run the type checker
+4. Report results in JSON format
+
+## Commands to Run
+- Tests: `npm test` or `pytest` (detect from package.json/pyproject.toml)
+- Lint: `npm run lint` or `ruff check`
+- Types: `npm run typecheck` or `mypy`
+
+## Output Format
+Always respond with a JSON object containing:
+- `overall`: "pass" or "fail"
+- `tests`: test results with count and failures
+- `lint`: lint results with error count
+- `types`: type check results with error count
+- `summary`: human-readable one-line summary
+
+## Rules
+- Run ALL checks, even if one fails
+- Capture full error output for failures
+- Include file and line numbers when available
+- Never attempt to fix issues, only report
+```
+
+---
+
+## Usage Examples
+
+### Basic Verification
+
+```
+Main Agent: I need to check if the code is ready for commit.
+
+[Spawns verify-app subagent]
+
+verify-app: Running verification suite...
+- npm test: 47 passed
+- npm run lint: clean
+- npm run typecheck: clean
+
+{
+  "overall": "pass",
+  "tests": { "passed": true, "count": 47 },
+  "lint": { "passed": true, "errors": 0 },
+  "types": { "passed": true, "errors": 0 },
+  "summary": "All checks passed."
+}
+
+Main Agent: Verification passed. Proceeding with commit.
+```
+
+### Verification with Failures
+
+```
+Main Agent: Run verification before merging.
+
+[Spawns verify-app subagent]
+
+verify-app: Running verification suite...
+- npm test: 2 failures
+- npm run lint: 3 errors
+- npm run typecheck: clean
+
+{
+  "overall": "fail",
+  "tests": {
+    "passed": false,
+    "failures": [
+      { "file": "src/auth.test.ts", "line": 45, "message": "..." }
+    ]
+  },
+  "lint": { "passed": false, "errors": 3 },
+  "summary": "2 test failures, 3 lint errors."
+}
+
+Main Agent: Verification failed. I'll fix the test and lint issues.
+```
+
+---
+
+## Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| Context isolation | Test output doesn't pollute main context |
+| Fast execution | Use haiku model for quick checks |
+| Structured output | JSON format for easy parsing |
+| Parallel execution | Can run while main agent continues |
+
+---
+
+## Test Cases
+
+| Test Case | Input | Expected |
+|-----------|-------|----------|
+| All pass | Clean codebase | `overall: "pass"` |
+| Test failures | Failing tests | `tests.passed: false` with details |
+| Lint errors | ESLint errors | `lint.errors: N` with count |
+| Mixed failures | Multiple issues | All failures reported |
+| Timeout | Hanging tests | Error response with timeout |
+
+---
+
+## Integration Points
+
+- **Trigger**: Main agent needs verification
+- **Input**: Verification config from project
+- **Output**: Structured JSON results
+- **Consumer**: Main agent, stop hook, Ralph mode