anvil-dev-framework 0.1.6

package/global/commands/ready.md

@@ -0,0 +1,182 @@
+# /ready - Calculate Ready Work
+
+> Query Linear and return issues that are unblocked and ready to start.
+
+## When to Use
+- After `/orient` to see available work
+- When deciding what to work on next
+- To check if blockers have been resolved
+
+## Pre-Flight: Check Linear Configuration
+
+**CRITICAL**: Before querying Linear, verify project configuration.
+
+```bash
+if [ -f ".claude/linear.yaml" ]; then
+    TEAM_KEY=$(grep "team_key:" .claude/linear.yaml | cut -d'"' -f2)
+    echo "Checking ready work for 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 query Linear.
+
+## Execution Steps
+
+### Step 1: Query Active Issues (Filtered by Team)
+
+Query Linear for issues where:
+- Team = [team_key from linear.yaml]
+- Status in (Todo, Backlog)
+- Limit 50
+
+### Step 2: Filter for Unblocked
+For each issue, check:
+- `blockedBy` relationships
+- If any blocking issue is NOT in "Done" state → issue is blocked
+- If ALL blocking issues are "Done" (or no blockers) → issue is ready
+
+### Step 3: Check for Claimed Issues (ANV-224)
+
+Check if any ready issues have been claimed by other agents using the claim_service:
+
+```bash
+# Query claims using the claim service
+python3 -c "
+import sys
+sys.path.insert(0, 'global/lib')
+from claim_service import get_all_claims
+import json
+print(json.dumps(get_all_claims()))
+"
+```
+
+Or use the CLI directly:
+```bash
+python3 global/lib/claim_service.py list
+```
+
+For each ready issue:
+- Check if issue_id exists in claims registry
+- If claimed by another agent → mark as claimed
+- If claimed by current agent → mark as "Your claim"
+
+The claims registry at `~/.anvil/claims.json` contains:
+- `claimed_by`: Agent UUID holding the claim
+- `codename`: Agent display name (A1, A2, etc.)
+- `claimed_at`: When the claim was made
+- `scope`: "global" for Linear issues, "project" for ad-hoc
+
+### Step 4: Sort Results
+Sort ready issues by:
+1. Priority (P0 first, then P1, P2, P3)
+2. Age (older issues first within same priority)
+
+### Step 5: Present Ready Work
+
+Output format:
+```
+## Ready Work — [team_key]
+
+| Priority | Issue | Title | Age | Status |
+|----------|-------|-------|-----|--------|
+| P0 | [TEAM]-123 | [Title] | 3d | Available |
+| P1 | [TEAM]-124 | [Title] | 5d | Claimed by A1 |
+| P2 | [TEAM]-125 | [Title] | 1d | Available |
+
+**Total ready**: X issues
+**Blocked**: Y issues waiting on dependencies
+**Claimed**: Z issues claimed by other agents
+
+Recommend starting with: [Highest priority UNCLAIMED issue]
+```
+
+### Claim Warning Format (ANV-224)
+
+When an issue is claimed by another agent:
+- **Status column**: `Claimed by [codename]` (e.g., "Claimed by A1")
+- **Recommendation**: Skip claimed issues, recommend next unclaimed
+- **Not blocking**: User can still choose to work on claimed issue (collaboration)
+
+Example with claims:
+```markdown
+## Ready Work — ANV
+
+| Priority | Issue | Title | Age | Status |
+|----------|-------|-------|-----|--------|
+| P1 | ANV-22 | Statusline feature | 2d | Claimed by A1 |
+| P1 | ANV-30 | Quality gates | 3d | Claimed by A2 |
+| P2 | ANV-11 | Init command | 5d | Available |
+| P2 | ANV-15 | Documentation | 4d | Available |
+
+**Total ready**: 4 issues
+**Blocked**: 2 issues waiting on dependencies
+**Claimed**: 2 issues claimed by other agents
+
+ANV-22 and ANV-30 are claimed. Recommend starting with: ANV-11 (Init command)
+```
+
+## Error: Linear Not Configured
+
+If linear.yaml is missing, output:
+
+```
+## Ready Work — ⚠️ 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 `/ready` again
+
+Cannot calculate ready work without team configuration.
+```
+
+## Key Behaviors
+- **ALWAYS check linear.yaml first** — never query wrong team
+- **Check claims registry for claimed issues** — warn about claims (ANV-224)
+- Only show truly unblocked work from configured team
+- Highlight if nothing is ready (all blocked)
+- Include enough context for decision-making
+- Don't start work—just report what's available
+- Recommend unclaimed issues over claimed ones
+- Claims are warnings, not blockers—user can override for collaboration
+
+## Blocked Issues Report (Optional)
+If requested or if many issues are blocked:
+```
+## Blocked Issues — [team_key]
+
+| Issue | Blocked By | Blocker Status |
+|-------|------------|----------------|
+| [TEAM]-126 | [TEAM]-120 | In Progress |
+| [TEAM]-127 | [TEAM]-121, [TEAM]-122 | Todo, In Review |
+```
+
+## Relationship to /sprint
+
+| Command | Purpose | Output |
+|---------|---------|--------|
+| `/ready` | List unblocked work | Data report (what's available) |
+| `/sprint` | Prioritize session | Recommendations (what to work on) |
+
+**How they relate:**
+- `/ready` is the **foundation** — pure data query for unblocked work
+- `/sprint` **builds on** `/ready` — adds broader context + recommendations
+- Use `/ready` for quick "what's available?" checks
+- Use `/sprint` for full session planning with reasoning
+
+```
+/orient → /ready (quick check) → /sprint (full planning) → /validate → work
+```
+
+## Integration Points
+- Requires: `.claude/linear.yaml` (team configuration)
+- Uses: `global/lib/claim_service.py` (issue claiming - ANV-224)
+- Uses: `~/.anvil/claims.json` (claims registry)
+- Uses: Linear MCP (filtered by team)
+- Used by: `/orient` command
+- Used by: `/sprint` command (inherits unblocked detection + agent conflicts)

package/global/commands/release.md

@@ -0,0 +1,305 @@
+# /release - Version Coordination
+
+> Consolidate [Unreleased] changes into a versioned release.
+
+## When to Use
+- At end of sprint (batch all work)
+- After major feature merges
+- When ready to cut a release
+- As coordination point for multi-agent work
+
+## Why This Command Exists
+
+In multi-agent environments, version assignment is dangerous:
+- Multiple agents working simultaneously can create version conflicts
+- Agents assigning versions during development causes drift
+- No single source of truth for "what's released"
+
+**Solution**: Agents NEVER assign versions during development. All agents add entries to [Unreleased]. One agent or human runs `/release` at the coordination point.
+
+## Versioning Strategy
+
+Anvil uses **four-part versioning**: `MILESTONE.MAJOR.MINOR.PATCH`
+
+| Component | Meaning | Bump When |
+|-----------|---------|-----------|
+| **MILESTONE** | Production readiness | 0 = Alpha, 1 = Production-ready (manual decision only) |
+| **MAJOR** | Significant feature sets | Breaking changes or major additions |
+| **MINOR** | New features | New commands, integrations |
+| **PATCH** | Bug fixes | Bug fixes, docs, small improvements |
+
+**Current status**: `0.x.x.x` (Alpha — building toward 1.0.0.0)
+
+**Important**: The MILESTONE component (0 → 1) is NEVER auto-bumped. Moving to 1.0.0.0 is a manual decision when all production-readiness criteria are met.
+
+## Execution Steps
+
+### Step 1: Parse Changelog
+
+Read CHANGELOG.md and extract [Unreleased] section content:
+
+```bash
+# Check for [Unreleased] section
+grep -A 1000 "## \[Unreleased\]" CHANGELOG.md | grep -B 1000 -m 1 "^## \[" | head -n -1
+```
+
+If [Unreleased] is empty or missing:
+```
+## Release Check
+
+**Status**: Nothing to release
+
+The [Unreleased] section is empty or contains no changes.
+
+Add entries to [Unreleased] before running /release:
+- ### Added — New features
+- ### Changed — Changes to existing functionality
+- ### Fixed — Bug fixes
+- ### Removed — Removed features
+```
+
+### Step 2: Calculate Version Bump
+
+Based on change types in [Unreleased]:
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| `BREAKING CHANGE` anywhere | MAJOR | 0.1.4.0 → 0.2.0.0 |
+| `### Added` (new features) | MINOR | 0.1.4.0 → 0.1.5.0 |
+| `### Changed/Fixed/Removed` only | PATCH | 0.1.4.0 → 0.1.4.1 |
+
+**Note**: MILESTONE (first digit) is NEVER auto-bumped. Going from 0.x to 1.0 requires explicit user decision.
+
+```bash
+# Read current version
+CURRENT_VERSION=$(cat VERSION 2>/dev/null || echo "0.1.0.0")
+
+# Parse version components (4-part: MILESTONE.MAJOR.MINOR.PATCH)
+IFS='.' read -r MILESTONE MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+
+# Check for breaking changes (bumps MAJOR, not MILESTONE)
+if grep -qi "BREAKING CHANGE" CHANGELOG.md; then
+    BUMP="major"
+    NEW_VERSION="$MILESTONE.$((MAJOR + 1)).0.0"
+elif grep -q "### Added" CHANGELOG.md; then
+    BUMP="minor"
+    NEW_VERSION="$MILESTONE.$MAJOR.$((MINOR + 1)).0"
+else
+    BUMP="patch"
+    NEW_VERSION="$MILESTONE.$MAJOR.$MINOR.$((PATCH + 1))"
+fi
+```
+
+### Step 3: Preview Release
+
+Show what will be released and require confirmation:
+
+```markdown
+## Release Preview
+
+**Current version**: 0.1.4.0
+**New version**: 0.1.5.0 (MINOR bump)
+**Reason**: New features added (### Added section present)
+
+### Changes to include:
+
+#### Added
+- Enhanced `/evidence` Command — Additional quality gate checks
+- Enhanced `/handoff` Command — Changelog confirmation
+
+#### Fixed
+- [Any fixed items]
+
+### Actions that will be performed:
+1. Transform CHANGELOG.md: [Unreleased] → [0.1.5.0] - 2026-01-02
+2. Add empty [Unreleased] section at top
+3. Update VERSION file to 0.1.5.0
+4. Update README.md: version in banner, title, and "Latest Changes" section
+5. Create commit: "chore(release): v0.1.5.0"
+6. Create annotated git tag: v0.1.5.0
+
+**Proceed with release?** [Requires explicit confirmation]
+```
+
+### Step 4: Execute Release (After Confirmation)
+
+Only proceed if user explicitly confirms.
+
+#### 4.1: Transform CHANGELOG.md
+
+```bash
+# Get today's date
+TODAY=$(date +%Y-%m-%d)
+
+# Replace [Unreleased] with version and date
+sed -i '' "s/## \[Unreleased\]/## [Unreleased]\n\n---\n\n## [$NEW_VERSION] - $TODAY/" CHANGELOG.md
+```
+
+The transformation:
+- `## [Unreleased]` → `## [Unreleased]` (empty, at top)
+- Previous unreleased content → `## [1.4.0] - 2026-01-02`
+
+#### 4.2: Update VERSION File
+
+```bash
+echo "$NEW_VERSION" > VERSION
+```
+
+#### 4.3: Update README.md
+
+Update three locations in README.md:
+
+1. **ASCII Banner Version** (line ~4):
+   ```bash
+   # Update version in ASCII art banner
+   sed -i '' "s/v[0-9]*\.[0-9]*\.[0-9]*/v$NEW_VERSION/" README.md
+   ```
+
+2. **Title Version** (line ~13):
+   ```bash
+   # Update <sup>vX.Y.Z</sup> in title
+   sed -i '' "s/<sup>v[0-9]*\.[0-9]*\.[0-9]*<\/sup>/<sup>v$NEW_VERSION<\/sup>/" README.md
+   ```
+
+3. **Latest Changes Section**:
+   Replace the existing "Latest Changes in vX.Y.Z" section with content from the new version's changelog entry:
+
+   ```markdown
+   ## 📦 Latest Changes in v[NEW_VERSION]
+
+   *Released: [TODAY]*
+
+   - **[Feature 1]** — [Description]
+   - **[Feature 2]** — [Description]
+   ...
+
+   See [CHANGELOG.md](CHANGELOG.md) for complete history.
+   ```
+
+   Extract bullet points from the versioned CHANGELOG section (Added, Changed, Fixed, Removed).
+   Keep entries concise—one line per major change.
+
+4. **Roadmap Section** (if applicable):
+   Add the new version to the roadmap as complete:
+   ```markdown
+   ### v[NEW_VERSION] (Complete)
+   - [x] [Major feature 1]
+   - [x] [Major feature 2]
+   ```
+
+#### 4.4: Create Release Commit
+
+```bash
+git add CHANGELOG.md VERSION README.md
+git commit -m "chore(release): v$NEW_VERSION"
+```
+
+#### 4.5: Create Annotated Tag
+
+```bash
+git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION
+
+Changes in this release:
+[Summary of changes from changelog]"
+```
+
+### Step 5: Output Summary
+
+```markdown
+## Release Complete
+
+**Version**: 0.1.5.0
+**Tag**: v0.1.5.0
+**Commit**: abc1234
+
+### Included Changes
+- Enhanced `/evidence` Command — Additional quality gate checks
+- Enhanced `/handoff` Command — Changelog confirmation
+
+### Next Steps
+1. Push to remote: `git push origin main --tags`
+2. Create GitHub release (optional): `gh release create v0.1.5.0`
+3. Deploy if applicable
+
+### Verification
+- [ ] CHANGELOG.md has new version section
+- [ ] VERSION file updated
+- [ ] README.md version updated (banner, title, Latest Changes)
+- [ ] Git tag created
+- [ ] [Unreleased] section is empty
+```
+
+## Multi-Agent Protocol
+
+**Critical Rule**: Agents NEVER assign versions during development.
+
+| Action | Allowed? | Why |
+|--------|----------|-----|
+| Add to [Unreleased] | ✅ Yes | Safe, no version conflicts |
+| Run `/release` | ✅ Yes | Single coordination point |
+| Edit version in CHANGELOG | ❌ No | Creates conflicts |
+| Update VERSION file directly | ❌ No | Creates drift |
+| Create version tags | ❌ No | Use `/release` only |
+
+**Workflow**:
+1. Agent A adds feature → adds to [Unreleased]
+2. Agent B fixes bug → adds to [Unreleased]
+3. Agent C adds feature → adds to [Unreleased]
+4. Coordinator runs `/release` → versions all changes atomically
+
+## Edge Cases
+
+### Breaking Change Confirmation
+
+If BREAKING CHANGE detected:
+```markdown
+⚠️ **BREAKING CHANGE Detected**
+
+This release contains breaking changes and will bump the MAJOR version.
+
+Current: 0.1.3.0 → New: 0.2.0.0
+
+Breaking changes found:
+- [List of breaking changes]
+
+Are you sure you want to release a major version? [y/N]
+```
+
+### Empty [Unreleased]
+
+```markdown
+## Release Check
+
+**Status**: Nothing to release
+
+The [Unreleased] section contains no changes.
+Run `/evidence` and `/handoff` to ensure work is documented.
+```
+
+### No VERSION File
+
+If VERSION file doesn't exist:
+```markdown
+## Release Check
+
+**Note**: No VERSION file found. Starting from 0.0.0.
+
+Create VERSION file with initial version? [y/N]
+```
+
+## Key Behaviors
+
+- Always require explicit confirmation before release
+- Parse changelog strictly—don't guess at changes
+- Create annotated tags with changelog summary
+- Leave clean [Unreleased] section for next cycle
+- Output clear next steps for deployment
+
+## Integration Points
+
+- Requires: CHANGELOG.md with [Unreleased] section
+- Requires: VERSION file (or creates one)
+- Updates: README.md (version in banner, title, Latest Changes section, roadmap)
+- Creates: Git commit and annotated tag
+- Follows: `/evidence` quality gates
+- Precedes: Deployment / `git push --tags`

package/global/commands/retro.md

@@ -0,0 +1,96 @@
+# /retro - Write a Retrospective
+
+> Capture learnings from completed work. Keep it simple.
+
+## When to Use
+- After completing a significant feature
+- After a bug that took >1 hour to diagnose  
+- After discovering unexpected complexity
+- After any "I wish I had known..." moment
+
+## Execution Steps
+
+### Step 1: Identify the Topic
+
+Usually the issue you just completed:
+- Issue key (e.g., ENG-42)
+- Brief descriptive title
+
+If not tied to an issue, use descriptive title only.
+
+### Step 2: Assess Outcome
+
+- **success** — Completed as expected
+- **partial** — Completed with caveats or issues
+- **failed** — Did not achieve goal
+
+### Step 3: Write the Narrative
+
+Answer these questions in prose (not bullet points):
+- What did you try?
+- What worked?
+- What didn't work?
+- Why?
+
+Be specific. Include file names, error messages, wrong assumptions.
+
+### Step 4: Extract Key Learning
+
+One concrete, actionable thing you learned.
+
+Not vague ("be more careful") but specific ("check RLS policies before INSERT").
+
+### Step 5: Define Next Time Action
+
+One specific thing to do differently next time you encounter similar work.
+
+### Step 6: Save Retro
+
+Create file: `.claude/retros/YYYY-MM/[ISSUE-ID]-[slug].md`
+
+```markdown
+# [Issue ID]: [Brief descriptive title]
+
+**Outcome:** success | partial | failed
+**Date:** YYYY-MM-DD
+
+## What Happened
+[Narrative]
+
+## Key Learning
+[One concrete thing]
+
+## For Next Time
+[One specific action]
+```
+
+### Step 7: Confirm
+
+```
+## Retro Saved
+
+**File**: .claude/retros/2025-12/ENG-42-password-reset.md
+**Outcome**: success
+**Key learning**: [brief summary]
+
+Run /insights weekly to synthesize patterns across retros.
+```
+
+## Key Behaviors
+
+- Keep it narrative, not structured
+- One learning, one action (not a list)
+- Specific > generic
+- Short is fine (3-5 paragraphs typical)
+
+## What This Command Does NOT Do
+
+- Generate retros automatically
+- Require complex metadata
+- Create Linear issues from learnings
+- Force a template
+
+## Integration Points
+
+- Creates: `.claude/retros/YYYY-MM/*.md`
+- Synthesized by: `/insights` command