anvil-dev-framework 0.1.6

package/global/commands/tasks.md

@@ -0,0 +1,228 @@
+# /tasks - Create Linear Sub-Issues from Plan
+
+> Generate Linear sub-issues from an approved implementation plan, nested under a parent feature issue.
+
+## When to Use
+- After implementation plan is approved
+- To break work into trackable sub-issues under a parent feature
+- Before starting implementation
+
+## 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)
+    TEAM_ID=$(grep "team_id:" .claude/linear.yaml | cut -d'"' -f2)
+    echo "Creating issues 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.
+
+## Prerequisites
+- Implementation plan created and approved (`/plan`)
+- **Parent feature issue exists in Linear** (e.g., ANV-5)
+- Linear team configured in `.claude/linear.yaml`
+- Clear understanding of task scope
+
+## Execution Steps
+
+### Step 1: Identify Parent Issue
+Check if the plan references a parent Linear issue:
+- Look for `linear_issue:` in spec frontmatter
+- Or ask user which issue should be the parent
+
+**Example Spec Reference:**
+```yaml
+---
+spec_id: SPEC-001
+linear_issue: ANV-5  # Parent issue for sub-tasks
+---
+```
+
+### Step 2: Review Implementation Plan
+Read the approved plan:
+- Identify all phases
+- Note task dependencies
+- Understand acceptance criteria per phase
+
+### Step 3: Create Sub-Issues Under Parent
+
+For each phase, create a Linear **sub-issue** using the CLI with `--parent`:
+
+**Linear CLI Reference (IMPORTANT):**
+
+| Command | Option | Note |
+|---------|--------|------|
+| `create-issue` | `--team` | Team UUID (required) |
+| | `--title` | Issue title (required) |
+| | `--description` | Issue description |
+| | `--parent` | Parent issue UUID (for sub-issues) |
+| `update-issue` | `--id` | Issue ID like "ANV-12" (required) |
+| | `--state` | State UUID (not state name!) |
+| | `--parent` | Parent issue UUID |
+
+> **Common Mistakes:**
+> - Use `list-issues` not `list_issues` (hyphens, not underscores)
+> - Use `--team` not `--team-id`
+> - Use `--status` to filter by state name, `--state` for state UUID
+
+**Create sub-issue:**
+```bash
+python3 scripts/linear.py create-issue \
+  --team "TEAM_UUID" \
+  --title "[PARENT-ID] Phase 1: Core Implementation" \
+  --description "..." \
+  --parent "PARENT_ISSUE_UUID"
+```
+
+**Update existing issue to become sub-issue:**
+```bash
+python3 scripts/linear.py update-issue \
+  --id "ANV-12" \
+  --parent "parent-issue-uuid"
+```
+
+**Issue Title Convention:**
+```
+[PARENT-ID] Phase N: [Brief description]
+```
+Example: `[ANV-5] Phase 1: Core Script & Directory Structure`
+
+**Issue Description Template:**
+```markdown
+## Goal
+[What this phase accomplishes]
+
+## Tasks
+- [ ] [Task 1]
+- [ ] [Task 2]
+
+## Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+## References
+- Parent: [PARENT-ID]
+- Spec: .claude/specs/current/SPEC-[id].md
+- Plan: .claude/specs/current/PLAN-[id].md
+```
+
+### Step 4: Set Dependencies
+Use Linear's "blocked by" relationships:
+- Phase 2 blocked by Phase 1
+- Phase 3 blocked by Phase 2
+- Testing blocked by implementation phases
+
+### Step 5: Report Created Sub-Issues
+
+Output:
+```
+## Linear Sub-Issues Created — [team_key]
+
+### Parent Issue: [TEAM]-XX ([Title])
+
+### From Plan: PLAN-[id]
+
+| Sub-Issue | Title | Priority | Estimate | Blocked By |
+|-----------|-------|----------|----------|------------|
+| [TEAM]-101 | [PARENT] Phase 1: [Name] | P1 | 2h | - |
+| [TEAM]-102 | [PARENT] Phase 2: [Name] | P2 | 3h | [TEAM]-101 |
+| [TEAM]-103 | [PARENT] Testing & Polish | P2 | 2h | [TEAM]-102 |
+
+**Total estimated**: X hours
+**Ready to start**: [TEAM]-101 (unblocked)
+
+### Issue Links
+- Parent: [TEAM]-XX: [Linear URL]
+- [TEAM]-101: [Linear URL] (sub-issue)
+- [TEAM]-102: [Linear URL] (sub-issue)
+- [TEAM]-103: [Linear URL] (sub-issue)
+
+**Next Step**: Run `/validate` then begin work on [TEAM]-101.
+```
+
+## Error: Linear Not Configured
+
+If linear.yaml is missing, output:
+
+```
+## Create Tasks — ⚠️ 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 `/tasks` again
+
+Cannot create issues without team configuration.
+```
+
+## Task Sizing Guidelines
+
+| Size | Hours | Description |
+|------|-------|-------------|
+| XS | <1h | Trivial change, single file |
+| S | 1-2h | Small feature, few files |
+| M | 2-4h | Standard feature, multiple files |
+| L | 4-8h | Complex feature, consider splitting |
+| XL | >8h | **Must split** into smaller tasks |
+
+If a task is XL, return to `/plan` and break it down further.
+
+## Key Behaviors
+- **ALWAYS check linear.yaml first** — create issues in correct team only
+- **ALWAYS create as sub-issues** — nest under parent feature issue for clean board organization
+- Each task should be 1-4 hours of work
+- Always set blocking dependencies
+- Include acceptance criteria in description
+- Link back to parent issue, spec, and plan
+- Set appropriate priority based on sequence
+- Use `--parent` flag when creating issues via CLI
+
+## Anti-Patterns
+- ❌ Creating top-level issues instead of sub-issues (clutters board)
+- ❌ Creating issues without checking linear.yaml
+- ❌ Tasks larger than 8 hours
+- ❌ Missing dependencies (creates confusion)
+- ❌ Vague acceptance criteria
+- ❌ No reference to parent/spec/plan
+
+## State Sync (ANV-176)
+
+After creating the Linear issues, update the session state:
+
+```bash
+python3 global/lib/state_manager.py tasks
+```
+
+This updates `.claude/anvil-state.json` with:
+- `phase: "tasks"`
+- Sets `lastCommand: "/tasks"`
+
+And syncs to the agent registry for statusline visibility.
+
+## GitHub Auto-Update Note
+
+Issues created via `/tasks` will **automatically move to Done** when their associated PR is merged, thanks to Linear's GitHub integration. You don't need to manually update issue status after PR merge.
+
+**How it works:**
+- Include the issue key in your PR title: `feat(api): add endpoint (ANV-123)`
+- When the PR is merged, Linear detects the issue key and moves the issue to Done
+
+See [Linear-GitHub Integration Guide](../../docs/linear-github-integration.md) for details.
+
+## Integration Points
+- Requires: `.claude/linear.yaml` (team configuration)
+- Requires: Parent issue ID from spec's `linear_issue:` field
+- Follows: `/plan` implementation planning
+- Uses: Linear CLI (`create-issue --parent` or `update-issue --parent`)
+- Precedes: Implementation work
+- References: `.claude/specs/current/PLAN-*.md`
+- Note: Issues auto-update to Done on PR merge (via GitHub integration)

package/global/commands/test-and-commit.md

@@ -0,0 +1,151 @@
+# /test-and-commit - Test Then Commit
+
+> Run tests, and if passing, commit changes.
+
+## When to Use
+- When you've made changes and want to commit safely
+- Before pushing to ensure tests pass
+- For quick inner-loop development
+
+## Why This Matters
+Committing without testing leads to:
+- Broken builds on CI
+- Wasted PR review cycles
+- Teammates pulling broken code
+
+**Rule**: Never commit untested code.
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `message` | Yes | Commit message (conventional format) |
+
+## Execution Steps
+
+### Step 1: Verify Preconditions
+```bash
+# Check we're in a git repo
+git rev-parse --git-dir > /dev/null 2>&1 || exit 1
+
+# Check there are changes to commit
+git diff --cached --quiet && git diff --quiet && echo "No changes to commit" && exit 0
+```
+
+**If not a git repo**: Stop with error
+**If no changes**: Report "No changes to commit" and exit
+
+### Step 2: Run Test Suite
+
+Detect and run the appropriate test command:
+```bash
+# Detect test runner
+if [ -f "package.json" ]; then
+    npm test
+elif [ -f "pytest.ini" ] || [ -f "pyproject.toml" ]; then
+    pytest
+elif [ -f "Cargo.toml" ]; then
+    cargo test
+elif [ -f "go.mod" ]; then
+    go test ./...
+else
+    echo "No test runner detected"
+    exit 1
+fi
+```
+
+**Capture**: Exit code and output
+
+### Step 3: Evaluate Results
+
+**If tests pass** (exit 0):
+- Proceed to Step 4
+
+**If tests fail** (exit non-zero):
+```
+❌ Tests failed
+
+Failing tests:
+- [file:line] - [error description]
+- [file:line] - [error description]
+
+No commit created. Fix tests first.
+```
+- Stop execution, do NOT commit
+
+### Step 4: Create Commit
+
+```bash
+# Stage all changes
+git add .
+
+# Create commit with provided message
+git commit -m "[message]"
+```
+
+### Step 5: Report Success
+
+```
+✅ Tests passed ([N] tests)
+✅ Committed: [message]
+   [hash] - [N] files changed, [+] insertions(+), [-] deletions(-)
+```
+
+## Usage Examples
+
+### Basic Usage
+```
+/test-and-commit "feat: add user authentication"
+```
+
+### With Conventional Commit Types
+```
+/test-and-commit "fix: resolve null pointer in login flow"
+/test-and-commit "chore: update dependencies"
+/test-and-commit "refactor: extract validation logic"
+```
+
+## 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 after 5000ms
+
+No commit created. Fix tests first.
+```
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| Not a git repo | "Error: Not a git repository" |
+| No changes | "No changes to commit" |
+| Tests fail | List failures, no commit |
+| No test runner | "Error: No test runner detected" |
+
+## Anti-Patterns
+- ❌ Committing without running tests
+- ❌ Ignoring test failures ("I'll fix it later")
+- ❌ Using generic commit messages ("fix stuff")
+- ❌ Skipping tests with `--skip-tests` flag (there isn't one)
+
+## Key Behaviors
+- **Atomic**: Either both test AND commit succeed, or neither happens
+- **Informative**: Always show test count and commit details
+- **Conventional**: Enforce conventional commit format
+- **Safe**: Never leave partial state
+
+## Integration Points
+- Used with: `/commit-push-pr` for full workflow
+- Alternative to: Manual `npm test && git commit`
+- Follows: Development work
+- Precedes: Push to remote

package/global/commands/validate.md

@@ -0,0 +1,132 @@
+# /validate - Environment Validation Checkpoint
+
+> Verify environment is ready before making any code changes.
+
+## When to Use
+- **Always** before starting implementation
+- After pulling changes from remote
+- After switching branches
+- When something feels "off"
+
+## Why This is Non-Negotiable
+Agents are non-deterministic. Without validation:
+- You might build on a dirty working directory
+- Dependencies might be out of sync
+- Tests might already be failing
+- You might be on the wrong branch
+
+**If ANY check fails, STOP. Do not proceed.**
+
+## Execution Steps
+
+### Step 1: Check Git Status
+```bash
+git status
+```
+
+**Expected**: Working directory clean, or only expected changes
+**If dirty**: Either commit, stash, or understand why before proceeding
+
+### Step 2: Check Branch
+```bash
+git branch --show-current
+```
+
+**Expected**: On feature branch, not `main`
+**If on main**: Create feature branch before making changes
+
+### Step 3: Sync Dependencies
+```bash
+npm ci
+```
+
+**Expected**: Clean install from lockfile
+**If fails**: Resolve dependency issues before proceeding
+
+### Step 4: Run Type Check
+```bash
+npm run typecheck
+```
+
+**Expected**: 0 errors
+**If fails**: Fix type errors before adding more code
+
+### Step 5: Run Tests
+```bash
+npm test
+```
+
+**Expected**: All tests pass
+**If fails**: Understand why—are these pre-existing failures or did something break?
+
+### Step 6: Run Lint
+```bash
+npm run lint
+```
+
+**Expected**: 0 errors (warnings acceptable)
+**If fails**: Fix lint errors before proceeding
+
+### Step 7: Report Validation Results
+
+Output format:
+```
+## Environment Validation
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Git Status | ✅ | Clean |
+| Branch | ✅ | feature/ENG-123-new-feature |
+| Dependencies | ✅ | Installed from lockfile |
+| TypeScript | ✅ | 0 errors |
+| Tests | ✅ | 47 passed |
+| Lint | ✅ | 0 errors |
+
+**Result**: ✅ Environment validated. Ready to proceed.
+```
+
+Or if failures:
+```
+## Environment Validation
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Git Status | ✅ | Clean |
+| Branch | ❌ | On main (should be feature branch) |
+| Dependencies | ✅ | Installed |
+| TypeScript | ❌ | 3 errors |
+| Tests | ⚠️ | 45 passed, 2 failed |
+| Lint | ✅ | 0 errors |
+
+**Result**: ❌ Validation failed. Must resolve before proceeding.
+
+### Issues to Resolve
+1. **Branch**: Create feature branch from main
+2. **TypeScript**: Fix errors in src/components/X.tsx (lines 23, 45, 67)
+3. **Tests**: Investigate failures in useAuth.test.ts
+
+Do not proceed with implementation until all checks pass.
+```
+
+## Validation Matrix
+
+| Check | Pass Criteria | Failure Action |
+|-------|--------------|----------------|
+| Git Status | Clean or understood | Commit, stash, or investigate |
+| Branch | On feature branch | Create branch |
+| Dependencies | npm ci succeeds | Resolve conflicts |
+| TypeScript | 0 errors | Fix errors |
+| Tests | All pass | Fix or understand failures |
+| Lint | 0 errors | Fix errors |
+
+## Key Behaviors
+- **Never skip validation**
+- If checks fail, fix before proceeding
+- Document any known/accepted failures
+- Re-run validation after fixes
+
+## Integration Points
+- Used before: Any implementation work
+- Follows: `/orient` session start
+- Precedes: Code changes
+- Referenced by: `/evidence` for baseline comparison