anvil-dev-framework 0.1.6

package/global/commands/discover.md

@@ -0,0 +1,158 @@
+# /discover - File Discovered Work
+
+> Immediately capture work discovered during implementation.
+
+## When to Use
+- When you find something that needs fixing while working on something else
+- When you notice technical debt
+- When a bug is discovered during development
+- When scope creep is detected (but shouldn't be addressed now)
+
+## Pre-Flight: Check Linear Configuration
+
+**CRITICAL**: Before creating issues, verify project configuration.
+
+```bash
+if [ -f ".claude/linear.yaml" ]; then
+    TEAM_KEY=$(grep "team_key:" .claude/linear.yaml | cut -d'"' -f2)
+    echo "Filing discovery in team: $TEAM_KEY"
+else
+    echo "⚠️ LINEAR NOT CONFIGURED"
+    echo "Run /linear-setup first"
+    exit 1
+fi
+```
+
+**If no linear.yaml**: Stop and prompt user to run `/linear-setup`. Do NOT create issues.
+
+## Why This Matters
+Discovered work creates a dilemma:
+- **If ignored**: It gets forgotten
+- **If addressed immediately**: Scope creep, context switching
+- **Solution**: File it immediately in the correct team, continue current work
+
+## Execution Steps
+
+### Step 1: Capture Context
+Before you forget, note:
+- What was discovered
+- Where it was found (file, line number)
+- Why it matters
+- How it relates to current work
+
+### Step 2: Create Linear Issue in Configured Team
+
+Use Linear MCP to create the issue in the configured team:
+
+```
+Create issue in team [team_key from linear.yaml]:
+- Title: "[Brief description of discovered work]"
+- Labels: ["discovered"]
+- Description: [formatted below]
+```
+
+**Issue Description:**
+```markdown
+## Discovery Context
+**Discovered while**: Working on [current issue key]
+**Found in**: [file path, line number]
+
+## Description
+[What was discovered and why it matters]
+
+## Recommended Action
+[What should be done about this]
+```
+
+### Step 3: Link to Parent
+Set "discovered from" or "related to" relationship:
+- Links discovered issue to the work where it was found
+- Preserves context for future
+
+### Step 4: Continue Original Work
+After filing:
+- Return focus to original task
+- Don't context switch to fix discovered issue
+- Trust that it's captured and won't be lost
+
+### Step 5: Report Discovery
+
+Output:
+```
+## Discovered Work Filed — [team_key]
+
+**Issue Created**: [TEAM-XXX]
+**Title**: [Title]
+**Priority**: [Priority]
+**Discovered From**: [Parent issue key]
+
+**Link**: [Linear URL]
+
+Continuing with original task: [Current issue key]
+```
+
+## Error: Linear Not Configured
+
+If linear.yaml is missing, output:
+
+```
+## Discover — ⚠️ Linear Not Configured
+
+This project is not mapped to a Linear team.
+
+**To configure:**
+1. Run `/linear-setup` to select or create a team
+2. Then run `/discover` again
+
+Cannot file discovered work without team configuration.
+
+**Workaround**: Note the discovery in a comment or TODO for now.
+```
+
+## Quick Discovery Format
+For rapid capture during flow:
+
+```
+/discover "Brief title" --from [current-issue] --priority P2
+```
+
+Creates issue with minimal friction, full details can be added later.
+
+## What Qualifies as Discovered Work
+
+**File immediately**:
+- Bugs found in unrelated code
+- Missing error handling
+- Security concerns
+- Performance issues
+- Technical debt
+- Missing tests
+- Documentation gaps
+- Accessibility issues
+
+**Don't file** (just fix):
+- Typos in files you're already editing
+- Trivial fixes in your current scope
+- Things that take <5 minutes and are in scope
+
+## Key Behaviors
+- **ALWAYS check linear.yaml first** — file in correct team only
+- File **immediately**—don't say "I'll remember"
+- Include discovery context (where, when, why)
+- Link to parent issue
+- Don't interrupt current work to fix
+- Assess priority independently (discovered P0 bug should be P0)
+
+## Anti-Patterns
+- ❌ Creating issues without checking linear.yaml
+- ❌ "I'll file this later" (you won't)
+- ❌ Fixing discovered issues immediately (scope creep)
+- ❌ Filing without context (future you won't understand)
+- ❌ Not linking to parent (loses discovery trail)
+
+## Integration Points
+- Requires: `.claude/linear.yaml` (team configuration)
+- Uses: Linear MCP (create_issue with team filter)
+- Creates: Linear issue with "discovered" label
+- Used during: Any implementation work
+- References: Current task being worked on

package/global/commands/doc-coverage.md

@@ -0,0 +1,122 @@
+# /doc-coverage - Documentation Coverage Report
+
+> Check documentation coverage and identify gaps.
+
+## When to Use
+- Before creating a PR to check documentation status
+- During `/healthcheck` to assess project health
+- When adding new features to identify missing docs
+- To track documentation debt over time
+
+## Execution Steps
+
+### Step 1: Run Coverage Analysis
+
+```bash
+python3 global/lib/doc_coverage_service.py --report
+```
+
+This generates a full coverage report showing:
+- Overall coverage percentage
+- Coverage by type (API, commands, hooks, skills)
+- List of undocumented exports
+
+### Step 2: Interpret Results
+
+| Coverage | Status | Action |
+|----------|--------|--------|
+| >= 80% | Healthy | Maintain coverage |
+| 60-79% | Warning | Address gaps before they grow |
+| < 60% | Critical | Prioritize documentation work |
+
+### Step 3: Review Gaps
+
+For each undocumented export:
+1. Determine if documentation is truly needed
+2. Check if export should be private (underscore prefix)
+3. Add to documentation backlog if needed
+
+### Step 4: Update State
+
+Coverage snapshot is stored in `anvil-state.json` for tracking over time.
+
+## CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--report` | Full markdown report (default) |
+| `--check` | CI mode - exit 1 if below threshold |
+| `--gaps` | Show only undocumented exports |
+| `--json` | Output in JSON format |
+| `--threshold N` | Set coverage threshold (default: 80) |
+
+## Example Output
+
+```markdown
+## Documentation Coverage Report
+
+### Summary
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Total Exports | 268 | — |
+| Documented | 217 | — |
+| Coverage | 81.0% | Healthy |
+
+### Coverage by Type
+
+| Type | Total | Documented | Coverage |
+|------|-------|------------|----------|
+| api | 45 | 38 | 84.4% |
+| command | 32 | 30 | 93.8% |
+| hook | 12 | 10 | 83.3% |
+
+### Undocumented Exports
+
+| Export | Type | Source | Line |
+|--------|------|--------|------|
+| `new_function` | function | global/lib/service.py | 142 |
+| `/new-cmd` | command | global/commands/new.md | 1 |
+```
+
+## CI Integration
+
+Add to your CI pipeline:
+
+```bash
+python3 global/lib/doc_coverage_service.py --check --threshold 80
+```
+
+Exit codes:
+- `0`: Coverage meets threshold
+- `1`: Coverage below threshold
+
+## State Integration
+
+After running, coverage data is stored:
+
+```json
+{
+  "session": {
+    "docCoverage": {
+      "percent": 81.0,
+      "total": 268,
+      "documented": 217,
+      "status": "healthy",
+      "timestamp": "2026-01-11T12:00:00Z"
+    }
+  }
+}
+```
+
+## Key Behaviors
+- Non-blocking by default (reports status, doesn't fail)
+- Use `--check` for CI enforcement
+- Excludes test files and private exports automatically
+- Tracks coverage trends via state snapshots
+
+## Integration Points
+- Used by: `/healthcheck` command
+- Updates: `.claude/anvil-state.json`
+- Reads: Source files via glob patterns
+- Parses: Python AST, TypeScript regex, Markdown headers

package/global/commands/evidence.md

@@ -0,0 +1,307 @@
+# /evidence - Capture Quality Gate Proof
+
+> Capture evidence that quality gates pass before PR creation.
+
+## When to Use
+- Before creating a pull request
+- After completing implementation
+- When claiming work is "done"
+
+## Why Evidence Matters
+Agents (and humans) claim "it works" without verification. Evidence:
+- Proves quality gates actually passed
+- Provides PR reviewers with confidence
+- Creates accountability
+- Catches "it worked on my machine" issues
+
+## Execution Steps
+
+### Step 1: Run All Quality Checks
+
+Execute each check and capture output:
+
+```bash
+# Lint
+npm run lint 2>&1 | tee lint-output.txt
+
+# TypeScript
+npm run typecheck 2>&1 | tee typecheck-output.txt
+
+# Tests
+npm test 2>&1 | tee test-output.txt
+
+# Git status
+git status
+git diff --stat
+```
+
+### Step 2: Verify Expected File Changes
+
+```bash
+git diff --name-only HEAD
+```
+
+Compare against plan:
+- Are all expected files changed?
+- Are there unexpected changes?
+- Are there missing changes?
+
+### Step 3: Documentation Status
+
+Check if documentation needs updating:
+
+1. Review files changed this branch:
+   ```bash
+   git diff --name-only main...HEAD
+   ```
+
+2. If `src/` or implementation files changed, consider:
+   - Did you update relevant documentation in `docs/`?
+   - Does README need updating?
+   - Are there new APIs that need documenting?
+
+3. Document status:
+   ```markdown
+   ### Documentation Status
+   - [ ] No docs needed (internal/infrastructure change only)
+   - [ ] Docs updated: [list files]
+   - [ ] Docs TODO: [what needs updating]
+   ```
+
+**Note**: This is a soft prompt—use judgment. Internal refactors don't need docs, but new features do.
+
+---
+
+### Step 4: Changelog Entry
+
+Verify changelog was updated for user-facing changes:
+
+1. Check if CHANGELOG.md was modified:
+   ```bash
+   git diff --name-only main...HEAD | grep -c "CHANGELOG.md" || echo "0"
+   ```
+
+2. If no changelog change detected AND work is user-facing:
+   ```markdown
+   ### Changelog Status
+   ⚠️ No CHANGELOG.md entry detected for this branch.
+
+   Did you add an entry to the [Unreleased] section?
+   - [ ] Added changelog entry
+   - [ ] No user-facing changes (internal only)
+   ```
+
+3. If changelog was updated:
+   ```markdown
+   ### Changelog Status
+   ✅ Entry added to [Unreleased] section
+   ```
+
+**Guideline**: Add changelog entries for:
+- New features (### Added)
+- Bug fixes (### Fixed)
+- Breaking changes (### Changed + BREAKING CHANGE note)
+- Removed functionality (### Removed)
+
+Skip for: internal refactors, test-only changes, documentation updates.
+
+---
+
+### Step 5: Code Review (Optional)
+
+If code review is enabled in `.claude/anvil.config.json`:
+
+1. Check configuration:
+   ```bash
+   # Read config if exists
+   if [ -f ".claude/anvil.config.json" ]; then
+       cat .claude/anvil.config.json | grep -A5 '"codeReview"'
+   fi
+   ```
+
+2. Based on `codeReview.enforcement` setting:
+
+   | Enforcement | Behavior |
+   |-------------|----------|
+   | `hard` | Run review automatically. Block PR if critical issues found. |
+   | `soft` | Prompt: "Run code review? (recommended)" Proceed either way. |
+   | `manual` | Skip automatic prompt. User triggers when wanted. |
+
+3. If enabled, run configured tool:
+   ```bash
+   # Default command (configurable)
+   coderabbit --prompt-only
+   ```
+
+4. Include results in evidence:
+   ```markdown
+   ### Code Review
+   **Tool**: CodeRabbit
+   **Status**: ✅ No critical issues / ⚠️ X issues found
+
+   [Summary of findings if any]
+   ```
+
+5. If code review not configured:
+   ```markdown
+   ### Code Review
+   Not configured. Enable with `/anvil-settings codeReview on`
+   ```
+
+---
+
+### Step 6: Compile Evidence Block
+
+Output format:
+```markdown
+## Quality Gate Evidence
+
+### Lint
+```
+✓ No ESLint errors
+```
+
+### TypeScript
+```
+✓ No type errors found
+```
+
+### Tests
+```
+Test Suites: 12 passed, 12 total
+Tests:       47 passed, 47 total
+Snapshots:   0 total
+Time:        3.245s
+```
+
+### Git Status
+```
+On branch feature/ENG-123-new-feature
+Changes staged for commit:
+  modified:   src/components/NewFeature.tsx
+  new file:   src/hooks/useNewFeature.ts
+  modified:   src/services/api.ts
+```
+
+### File Changes Summary
+| File | Status | Expected |
+|------|--------|----------|
+| src/components/NewFeature.tsx | Modified | ✅ Yes |
+| src/hooks/useNewFeature.ts | Added | ✅ Yes |
+| src/services/api.ts | Modified | ✅ Yes |
+| [unexpected files] | | ❌ Investigate |
+
+### Documentation Status
+- [x] Docs updated: docs/feature-guide.md
+- [ ] No docs needed
+- [ ] Docs TODO
+
+### Changelog Status
+✅ Entry added to [Unreleased] section
+
+### Code Review
+Not configured / ✅ No critical issues / ⚠️ X issues to address
+
+### Evidence Collected
+- **Date**: YYYY-MM-DD HH:MM
+- **Branch**: feature/ENG-123-new-feature
+- **Commit**: [hash]
+
+✅ All quality gates passed. Ready for PR.
+```
+
+### Step 7: Include in PR Description
+
+When creating PR, include evidence block:
+
+```markdown
+## Changes
+[Description of changes]
+
+## Quality Evidence
+[Paste evidence block]
+
+## Testing
+- [x] Lint passes
+- [x] Types pass
+- [x] Tests pass
+- [x] Manual testing completed
+
+## Screenshots (if UI changes)
+[Screenshots]
+
+## Linear Issue
+Closes [Issue key]
+```
+
+## Evidence Checklist
+
+| Gate | Must Pass | Evidence |
+|------|-----------|----------|
+| Lint | ✅ 0 errors | Command output |
+| TypeScript | ✅ 0 errors | Command output |
+| Tests | ✅ All pass | Test summary |
+| Git Status | ✅ Only expected | File list |
+| Manual Test | ✅ Works | Description or screenshot |
+| Documentation | ⚪ Soft prompt | Status noted |
+| Changelog | ⚪ Soft prompt | Entry added or justified skip |
+| Code Review | ⚪ If configured | Review results (when enabled) |
+
+**Legend**: ✅ = Required | ⚪ = Soft prompt (use judgment)
+
+## Failure Handling
+
+If any gate fails:
+```
+## Quality Gate Evidence
+
+### ❌ Tests FAILED
+```
+Test Suites: 11 passed, 1 failed
+Tests:       45 passed, 2 failed
+
+FAIL src/hooks/useNewFeature.test.ts
+  ● useNewFeature › should handle error state
+    Expected: "error"
+    Received: undefined
+```
+
+**Action Required**: Fix failing tests before PR.
+```
+
+Do NOT create PR with failing gates.
+
+## Key Behaviors
+- Capture actual command output, not just "it passed"
+- Include timestamps for accountability
+- Verify file changes match plan
+- Surface unexpected changes
+- Never proceed with failures
+
+## State Sync (ANV-176)
+
+After capturing evidence, update the session state:
+
+```bash
+python3 global/lib/state_manager.py evidence
+```
+
+This updates `.claude/anvil-state.json` with:
+- `phase: "verify"`
+- Sets `lastCommand: "/evidence"`
+
+And syncs to the agent registry for statusline visibility.
+
+## Linear Auto-Update Note
+
+When your PR includes a Linear issue key (e.g., `ANV-123`) and is merged, Linear automatically moves the issue to Done. You don't need to manually update the issue status after PR merge.
+
+See [Linear-GitHub Integration Guide](../../docs/linear-github-integration.md) for details.
+
+## Integration Points
+- Follows: Implementation work
+- Precedes: PR creation
+- References: `/validate` baseline
+- Used in: PR description
+- Updates: `.claude/anvil-state.json` via state_manager.py
+- Note: Linear issues auto-update on PR merge (no manual update needed)

package/global/commands/explore.md

@@ -0,0 +1,121 @@
+# /explore - Discovery Phase
+
+> Conduct discovery before implementing a feature. Read existing code, find patterns, understand context.
+
+## When to Use
+- **Always** before implementing a new feature
+- When working in unfamiliar part of codebase
+- Before writing a specification
+- When requirements reference existing functionality
+
+## Execution Steps
+
+### Step 1: Understand the Request
+Clarify:
+- What is being requested?
+- What problem does it solve?
+- Who is affected?
+
+### Step 2: Search Existing Code
+Look for related functionality:
+```bash
+# Search for related files
+find src -name "*[keyword]*" -type f
+
+# Search for related code
+grep -r "[pattern]" src/ --include="*.ts" --include="*.tsx"
+```
+
+### Step 3: Read Similar Modules
+Identify and open the most similar existing implementation:
+- Read the full file(s)
+- Note patterns used
+- Note conventions followed
+- Document any deviations from standards
+
+### Step 4: Check Existing Specs
+Look in `.claude/specs/` for related specifications:
+- Current specs that might be affected
+- Archived specs for historical context
+- Related feature documentation
+
+### Step 5: Document Conventions
+Note observed patterns:
+- File naming conventions
+- Component structure
+- State management approach
+- Error handling patterns
+- Testing patterns
+
+### Step 6: Generate Exploration Report
+
+Output format:
+```markdown
+## Exploration Report: [Feature Name]
+
+### Request Understanding
+[Summary of what's being requested and why]
+
+### Related Existing Code
+| File | Relevance | Key Patterns |
+|------|-----------|--------------|
+| src/components/Similar.tsx | High | Uses [pattern] |
+| src/services/related.ts | Medium | [relevant detail] |
+
+### Observed Conventions
+1. **Components**: [How similar components are structured]
+2. **State**: [How state is managed]
+3. **API**: [How API calls are made]
+4. **Testing**: [How similar features are tested]
+
+### Existing Specs
+- [Spec name]: [Relevance]
+
+### Key Findings
+1. [Important discovery]
+2. [Constraint or consideration]
+3. [Potential reuse opportunity]
+
+### Recommended Approach
+[Brief recommendation based on discovery]
+
+### Open Questions
+- [ ] [Question needing clarification]
+- [ ] [Technical decision needed]
+
+### Ready for Specification: [Yes/No]
+[If no, what's needed first]
+```
+
+## Key Behaviors
+- **Read before writing**—never speculate about code you haven't opened
+- Cite specific files and line numbers
+- Note conventions to follow (not just functionality)
+- Surface conflicts or inconsistencies
+- Ask clarifying questions before proceeding
+
+## Anti-Patterns to Avoid
+- ❌ Assuming code structure without reading it
+- ❌ Skipping this step because it "seems simple"
+- ❌ Not documenting findings
+- ❌ Ignoring existing patterns
+
+## State Sync (ANV-176)
+
+After generating the exploration report, update the session state:
+
+```bash
+python3 global/lib/state_manager.py explore
+```
+
+This updates `.claude/anvil-state.json` with:
+- `phase: "explore"`
+- Sets `lastCommand: "/explore"`
+
+And syncs to the agent registry for statusline visibility.
+
+## Integration Points
+- Precedes: `/spec` command
+- References: `.claude/specs/` directory
+- References: `.claude/examples/` for conventions
+- Updates: `.claude/anvil-state.json` via state_manager.py