anvil-dev-framework 0.1.6

package/global/commands/shard.md

@@ -0,0 +1,166 @@
+# /shard - Break Large Specs into Atomic Pieces
+
+> Split large specifications into smaller, focused documents.
+
+## When to Use
+- When a spec exceeds ~500 lines
+- When a feature has multiple distinct epics
+- When context window efficiency is needed
+- To enable parallel work streams
+
+## Why Sharding Matters
+Large specs cause problems:
+- Exceed useful context window
+- Mix unrelated concerns
+- Make progress tracking difficult
+- Prevent parallel work
+
+Sharding provides:
+- ~80% token savings (load only relevant shard)
+- Clear ownership boundaries
+- Independent progress tracking
+- Parallel implementation paths
+
+## Execution Steps
+
+### Step 1: Identify Shard Boundaries
+Review the spec and identify natural divisions:
+- By user story / epic
+- By technical domain
+- By implementation phase
+- By team/assignee
+
+### Step 2: Create Shard Structure
+
+Directory structure:
+```
+.claude/specs/current/
+├── SPEC-001-auth.md           # Master spec (index)
+└── SPEC-001-auth/             # Shard directory
+    ├── epic-001-registration.md
+    ├── epic-002-login.md
+    ├── epic-003-password-reset.md
+    └── epic-004-session-mgmt.md
+```
+
+### Step 3: Create Master Spec (Index)
+
+The master spec becomes an index:
+```markdown
+---
+spec_id: SPEC-001
+title: Authentication System
+status: in-progress
+sharded: true
+---
+
+# Authentication System Specification
+
+## Overview
+[High-level description]
+
+## Shards
+
+| Shard | Title | Status | Owner |
+|-------|-------|--------|-------|
+| epic-001 | User Registration | In Progress | - |
+| epic-002 | Login Flow | Todo | - |
+| epic-003 | Password Reset | Todo | - |
+| epic-004 | Session Management | Todo | - |
+
+## Cross-Cutting Concerns
+[Things that affect all shards]
+
+## Dependencies
+[Dependencies between shards]
+
+## Shared Decisions
+[Decisions that apply to all shards]
+```
+
+### Step 4: Create Individual Shards
+
+Each shard is a complete mini-spec:
+```markdown
+---
+shard_id: SPEC-001/epic-001
+parent: SPEC-001
+title: User Registration
+status: draft
+---
+
+# User Registration
+
+## Overview
+[Specific to this shard]
+
+## Requirements
+[Just this shard's requirements]
+
+## Acceptance Criteria
+[Just this shard's criteria]
+
+## Technical Notes
+[Specific technical considerations]
+```
+
+### Step 5: Report Sharding
+
+Output:
+```
+## Specification Sharded
+
+**Master Spec**: SPEC-001-auth.md
+**Shards Created**: 4
+
+| Shard | File | Lines | Status |
+|-------|------|-------|--------|
+| epic-001 | epic-001-registration.md | 85 | Ready |
+| epic-002 | epic-002-login.md | 72 | Ready |
+| epic-003 | epic-003-password-reset.md | 64 | Ready |
+| epic-004 | epic-004-session-mgmt.md | 91 | Ready |
+
+**Original**: 450 lines → **Per shard**: ~78 lines avg
+
+### Token Savings
+- Loading master only: ~200 tokens
+- Loading one shard: ~300 tokens
+- Loading all (old way): ~1,800 tokens
+- **Savings**: ~83% when working on single epic
+
+**Next**: Each shard can now be planned and implemented independently.
+```
+
+## Sharding Guidelines
+
+| Original Size | Recommendation |
+|--------------|----------------|
+| <200 lines | Don't shard |
+| 200-500 lines | Consider sharding if distinct parts |
+| >500 lines | Should shard |
+
+## Shard Naming Convention
+```
+SPEC-[number]-[slug]/
+├── epic-[number]-[slug].md
+├── story-[number]-[slug].md
+└── technical-[topic].md
+```
+
+## Key Behaviors
+- Master spec becomes lightweight index
+- Each shard is self-contained
+- Cross-cutting concerns stay in master
+- Shards can be worked on independently
+- Update master status as shards complete
+
+## Anti-Patterns
+- ❌ Shards that reference each other heavily
+- ❌ Master spec that's still too detailed
+- ❌ Shards with unclear boundaries
+- ❌ Orphaned shards (no master)
+
+## Integration Points
+- Applied to: Large specifications
+- Enables: Parallel work streams
+- Improves: Context efficiency

package/global/commands/spec.md

@@ -0,0 +1,227 @@
+# /spec - Generate Formal Specification
+
+> Create a detailed specification document for a feature or change.
+
+## When to Use
+- After `/explore` discovery phase
+- Before implementation of non-trivial features
+- When requirements need formal documentation
+- For features that will span multiple sessions
+
+## Prerequisites
+- Discovery completed (`/explore`)
+- Requirements understood
+- Stakeholder alignment on scope
+
+## Execution Steps
+
+### Step 1: Gather Scope Decisions (Interactive)
+
+Before writing, use AskUserQuestion to confirm key scope decisions:
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      header: "Scope",
+      question: "How comprehensive should this specification be?",
+      multiSelect: false,
+      options: [
+        { label: "MVP - Core only (Recommended)", description: "Minimal requirements, fastest to ship" },
+        { label: "Standard", description: "Expected features, reasonable coverage" },
+        { label: "Comprehensive", description: "Full feature set, all edge cases" }
+      ]
+    },
+    {
+      header: "Timeline",
+      question: "What's the expected implementation timeline?",
+      multiSelect: false,
+      options: [
+        { label: "Single session", description: "Can complete in one work session" },
+        { label: "Multi-session", description: "Spans multiple sessions, needs handoffs" },
+        { label: "Multi-sprint", description: "Large effort, needs decomposition" }
+      ]
+    }
+  ]
+})
+```
+
+If requirements have open questions, run `/clarify` first to resolve ambiguities before proceeding
+
+### Step 2: Write Specification
+
+Create file at: `.claude/specs/current/SPEC-[issue-key]-[slug].md`
+
+Template:
+```markdown
+---
+spec_id: SPEC-[number]
+title: [Feature Name]
+status: draft | approved | implemented | archived
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+linear_issue: [Issue key]
+---
+
+# [Feature Name] Specification
+
+## Overview
+[2-3 sentence description of what this feature does and why]
+
+## Problem Statement
+[What problem does this solve? What's the current pain point?]
+
+## Requirements
+
+### Functional Requirements
+1. **[REQ-001]**: [Requirement description]
+2. **[REQ-002]**: [Requirement description]
+3. **[REQ-003]**: [Requirement description]
+
+### Non-Functional Requirements
+- **Performance**: [Any performance requirements]
+- **Security**: [Any security considerations]
+- **Accessibility**: [Any a11y requirements]
+
+## User Stories
+
+### [Story 1 Title]
+**As a** [user type]
+**I want** [goal]
+**So that** [benefit]
+
+### [Story 2 Title]
+...
+
+## Acceptance Criteria (Gherkin)
+
+### Scenario: [Scenario Name]
+```gherkin
+GIVEN [precondition]
+AND [additional precondition]
+WHEN [action]
+THEN [expected result]
+AND [additional result]
+```
+
+### Scenario: [Edge Case]
+```gherkin
+GIVEN [precondition]
+WHEN [action]
+THEN [expected behavior]
+```
+
+## Technical Considerations
+
+### Affected Components
+| Component | Change Type | Notes |
+|-----------|-------------|-------|
+| [Component] | New/Modified | [Details] |
+
+### Data Model Changes
+[Any database or state changes needed]
+
+### API Changes
+[Any API endpoints added or modified]
+
+### Dependencies
+- [Dependency on other features/systems]
+
+## Out of Scope
+- [Explicitly excluded item]
+- [Future consideration, not this iteration]
+
+## Open Questions
+- [ ] [Question needing resolution]
+- [ ] [Decision needed]
+
+## Risks and Mitigations
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk] | High/Med/Low | [Mitigation strategy] |
+
+## References
+- [Link to related documentation]
+- [Link to design mocks]
+- [Link to exploration report]
+```
+
+### Step 3: Request Approval (Interactive)
+
+After presenting the specification summary, use AskUserQuestion for approval:
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      header: "Approval",
+      question: "Do you approve this specification to proceed?",
+      multiSelect: false,
+      options: [
+        { label: "Approve - proceed to /plan", description: "Spec is complete, create implementation plan" },
+        { label: "Needs revision", description: "Identify specific changes needed" },
+        { label: "Needs clarification", description: "Run /clarify to resolve open questions" },
+        { label: "Reject - start over", description: "Requirements significantly wrong" }
+      ]
+    }
+  ]
+})
+```
+
+**If approved**: Proceed to `/plan` to create implementation plan.
+**If needs revision**: Ask what specific changes are needed.
+**If needs clarification**: Run `/clarify` with identified questions.
+
+Output:
+```
+## Specification Created
+
+**File**: .claude/specs/current/SPEC-[key]-[slug].md
+**Status**: Draft → [Approved/Needs Revision]
+
+### Summary
+[Brief summary of what was specified]
+
+### Key Decisions Captured
+1. [Decision 1]
+2. [Decision 2]
+
+### Open Questions (if any)
+1. [Question 1]
+2. [Question 2]
+```
+
+## Key Behaviors
+- Specifications must be **approved** before implementation
+- Use Gherkin scenarios for testable criteria
+- Be explicit about what's out of scope
+- Surface risks and open questions
+- Keep specs focused—one feature per spec
+
+## State Sync (ANV-176)
+
+After creating the specification, update the session state:
+
+```bash
+python3 global/lib/state_manager.py spec ".claude/specs/current/SPEC-XXX.md"
+```
+
+This updates `.claude/anvil-state.json` with:
+- `phase: "spec"`
+- `activeSpec: [path to spec file]`
+- Sets `lastCommand: "/spec"`
+
+And syncs to the agent registry for statusline visibility.
+
+## Integration Points
+- Follows: `/explore` discovery
+- Uses: `/clarify` for open questions (via AskUserQuestion)
+- Precedes: `/plan` implementation planning
+- Creates: `.claude/specs/current/SPEC-*.md`
+- References: Exploration report
+
+## Anti-Patterns
+- ❌ Writing spec without scope confirmation
+- ❌ Proceeding with unresolved open questions
+- ❌ Skipping approval step
+- ❌ Using text options instead of AskUserQuestion menus

package/global/commands/sprint.md

@@ -0,0 +1,184 @@
+# /sprint - Quick Session Planning
+
+> Fast prioritization for what to work on this session. Builds on `/ready` output with broader context and recommendations.
+
+## When to Use
+- After `/orient` when multiple options exist
+- When unsure what to prioritize
+- Before starting a work session
+
+## 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 "Linear 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: Get Ready Work (from /ready logic)
+
+**Internally apply /ready's unblocked work calculation:**
+
+1. Query Linear for issues where:
+   - Team = [team_key from linear.yaml]
+   - Status in (Todo, Backlog)
+
+2. Filter for unblocked:
+   - Check `blockedBy` relationships
+   - If any blocking issue is NOT in "Done" → blocked
+   - If ALL blockers are "Done" (or none) → ready
+
+3. Check agent conflicts via `.claude/coordination.md`:
+   - Parse Active Sessions table
+   - Match issue keys to active agent work
+   - Mark conflicts (warn, don't block)
+
+This gives you the **ready work pool** with conflict awareness.
+
+### Step 2: Get Broader State Context
+
+Query additional issues from Linear **for this team**:
+
+```
+Query Linear for issues where:
+- Team = [team_key from linear.yaml]
+- Status in (Blocked, In Progress, In Review)
+- Limit 20 per status
+```
+
+This provides context beyond just ready work.
+
+### Step 3: Build State Summary
+
+```markdown
+## Sprint State — [team_key]
+
+| Status | Count | Attention Needed |
+|--------|-------|------------------|
+| Blocked | X | [Can you unblock something?] |
+| In Progress | X | [Finish or continue] |
+| In Review | X | [Address feedback] |
+| Ready (unblocked) | X | [From /ready - available to start] |
+
+**Agent Conflicts**: Y ready issues have active agents working on them
+```
+
+### Step 4: Identify Priorities
+
+Apply this priority framework:
+
+1. **Blocked items you can unblock** — Huge value, multiplier effect
+2. **In Review with feedback** — Address quickly to unblock merge
+3. **In Progress items** — Finish what's started (momentum)
+4. **High priority Ready work** — P0/P1 items without agent conflicts
+5. **Lower priority Ready work** — P2/P3 available items
+
+**Agent conflict handling:**
+- Prefer recommending items WITHOUT active agents
+- If all high-priority items have conflicts, warn but still show them
+- User ultimately decides whether to work on conflicting items
+
+### Step 5: Suggest Top 3
+
+```markdown
+## Suggested Focus
+
+1. **[TEAM-XXX]**: [Title]
+   - Why: [Reason - e.g., "unblocks 2 other issues"]
+   - Effort: [Estimate if known]
+   - Status: Available | ⚠️ [agent-id] active
+
+2. **[TEAM-XXX]**: [Title]
+   - Why: [Reason]
+   - Effort: [Estimate]
+   - Status: Available | ⚠️ conflict
+
+3. **[TEAM-XXX]**: [Title]
+   - Why: [Reason]
+   - Effort: [Estimate]
+   - Status: Available
+
+## Blockers Requiring Attention
+- [TEAM-XXX] blocked by [external dependency / decision needed]
+
+## Agent Conflicts (Informational)
+- [TEAM-YYY] has active agent: swift-falcon-a3f2
+  (You can still work on this, but coordinate to avoid conflicts)
+```
+
+### Step 6: Await Selection
+
+```
+Which would you like to work on? (Or specify different task)
+```
+
+## Key Behaviors
+- **ALWAYS check linear.yaml first** — never show issues from wrong team
+- **Use /ready logic** for unblocked work detection
+- **Check coordination.md** for agent conflicts (inherited from /ready)
+- Fast — should complete in <30 seconds
+- Suggest, don't decide — highlight reasoning
+- Prefer available items over conflicting ones in recommendations
+
+## What This Command Does NOT Do
+- Query issues from other teams
+- Assign work automatically
+- Calculate weighted priorities (WSJF)
+- Create new issues
+- Replace human judgment
+- Block work on conflicting issues (warns only)
+
+## Error: Linear Not Configured
+
+If linear.yaml is missing, output:
+
+```
+## Sprint — ⚠️ 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 `/sprint` again
+
+Cannot show sprint state without team configuration.
+```
+
+## Relationship to Other Commands
+
+| Command | Purpose | Scope | Output |
+|---------|---------|-------|--------|
+| `/ready` | List unblocked work | Todo/Backlog only | Data report |
+| `/sprint` | Prioritize session | All active states | Top 3 recommendations |
+
+**How they relate:**
+- `/sprint` **builds on** `/ready` — uses same unblocked detection + agent conflicts
+- `/sprint` **adds** broader state view (In Progress, In Review, Blocked)
+- `/sprint` **adds** prioritization reasoning and recommendations
+- `/ready` is useful standalone for quick "what's available?" checks
+- `/sprint` is the full planning experience
+
+```
+/orient → /ready (optional quick check) → /sprint (full planning) → /validate → work
+         ↑                                    ↑
+         Quick data query                     Decision assistance with context
+```
+
+## Integration Points
+- Requires: `.claude/linear.yaml` (team configuration)
+- Uses: `.claude/coordination.md` (active agent detection - shared with /ready)
+- Uses: Linear MCP (filtered by team)
+- Builds on: `/ready` logic (unblocked detection, agent conflicts)
+- After: `/orient`
+- Before: `/validate` → work