anvil-dev-framework 0.1.6

package/docs/session-workflow.md

@@ -0,0 +1,573 @@
+# Anvil Session Workflow
+
+> What to do from the moment you start coding to when you stop.
+
+---
+
+## Table of Contents
+
+- [Quick Reference](#quick-reference)
+- [Step-by-Step](#step-by-step)
+  - [1. Start Your Session](#1-start-your-session-2-min)
+  - [2. Pick What to Work On](#2-pick-what-to-work-on-1-min)
+  - [3. Validate Environment](#3-validate-environment-30-sec)
+  - [4. Do the Work](#4-do-the-work)
+  - [5. During Work](#5-during-work)
+  - [6. Before Creating PR](#6-before-creating-pr-1-min)
+  - [7. End Your Session](#7-end-your-session-2-min)
+- [Common Scenarios](#common-scenarios)
+- [What NOT to Do](#what-not-to-do)
+- [Time Budget](#time-budget)
+- [Commands Reference](#commands-reference)
+  - [Session Commands](#session-commands)
+  - [Workflow Commands](#workflow-commands)
+  - [Quality Commands](#quality-commands)
+  - [Multi-Agent Commands](#multi-agent-commands)
+  - [Maintenance Commands](#maintenance-commands)
+  - [Power Mode Commands (Ralph Wiggum)](#power-mode-commands-ralph-wiggum)
+  - [Setup Commands](#setup-commands)
+- [Issue Providers](#issue-providers)
+- [Ralph Wiggum Mode (Special Scenarios)](#ralph-wiggum-mode-special-scenarios)
+
+---
+
+## Quick Reference
+
+```
+START SESSION
+    │
+    ▼
+/orient ──────────────► Check handoffs, git state, in-progress work
+    │
+    ▼
+/ready ───────────────► See unblocked issues from your team
+    │
+    ▼
+/sprint ──────────────► Decide what to work on (await selection)
+    │
+    ▼
+/validate ────────────► Verify environment is clean before changes
+    │
+    ▼
+┌───────────────────────────────────────────────────────────────┐
+│                        DO THE WORK                            │
+│                                                               │
+│  New Feature?             Brownfield?          Quick Task?    │
+│  ─────────────           ────────────         ────────────    │
+│  /explore first          /change first        Just do it      │
+│  /spec if complex        Light proposal                       │
+│  /plan if multi-day                                           │
+│  /shard if large spec                                         │
+│  /tasks for Linear                                            │
+│                                                               │
+│  DURING WORK:                                                 │
+│  • Read existing code before writing                          │
+│  • /discover if you find unrelated issues                     │
+│  • Stop if stuck >5 min, ask for help                         │
+│                                                               │
+└───────────────────────────────────────────────────────────────┘
+    │
+    ▼
+/evidence ────────────► Run tests, lint, typecheck — capture proof
+    │
+    ▼
+Create PR ────────────► Include evidence in PR description
+    │
+    ▼
+/handoff ─────────────► Document where you left off
+    │
+    ▼
+END SESSION
+```
+
+---
+
+## Step-by-Step
+
+### 1. Start Your Session (2 min)
+
+```
+You: /orient
+```
+
+Claude will:
+- Check for recent handoff (what you did last time)
+- Show git state (branch, uncommitted changes)
+- List in-progress work from Linear
+- Show ready work (unblocked tasks)
+
+**Wait for this info before doing anything.**
+
+---
+
+### 2. Pick What to Work On (1 min)
+
+**Option A: Just see what's available**
+```
+You: /ready
+```
+
+Claude shows unblocked Todo/Backlog issues from your configured team, sorted by priority. Includes agent conflict detection for multi-agent environments (warns if another agent is working on an issue).
+
+**Option B: Get prioritization help (recommended)**
+```
+You: /sprint
+```
+
+Claude applies `/ready`'s logic internally, then adds:
+- In Progress, In Review, and Blocked issues for full context
+- Top 3 recommendations with reasoning
+- Agent conflict awareness (prefers available issues in recommendations)
+
+**Priority heuristics**:
+1. Things blocking other work (unblock them = high value)
+2. PRs with feedback (quick to finish)
+3. In-progress work (momentum)
+4. High priority ready work (P0/P1) — available over conflicting
+
+**You decide.** Tell Claude: "Let's work on ENG-123"
+
+---
+
+### 3. Validate Environment (30 sec)
+
+```
+You: /validate
+```
+
+Claude checks:
+- Git status clean? (no uncommitted changes)
+- On feature branch? (not main)
+- Tests passing?
+- Types passing?
+
+**If anything fails → fix it before proceeding.**
+
+---
+
+### 4. Do the Work
+
+#### For New Features:
+
+```
+You: /explore
+```
+Claude investigates existing code, patterns, related files.
+**Wait for exploration report before writing code.**
+
+If it's complex (multi-day, unclear):
+```
+You: /spec
+```
+Claude creates formal specification. You approve before continuing.
+
+If the spec is large (>500 lines):
+```
+You: /shard
+```
+Claude breaks spec into focused, independent pieces for parallel work.
+
+```
+You: /plan
+```
+Claude breaks it into phases. You approve before continuing.
+
+```
+You: /tasks
+```
+Claude creates Linear **sub-issues** from the plan, nested under the parent feature issue.
+
+Then implement.
+
+#### For Brownfield Changes (modifying existing features):
+
+```
+You: /change
+```
+Claude creates a lightweight change proposal analyzing impact on existing code.
+
+Then implement.
+
+#### For Bug Fixes:
+
+1. Reproduce the bug
+2. Diagnose (check logs, add debugging)
+3. Fix
+4. Test the fix
+5. Verify related code isn't affected
+
+#### For Quick Tasks:
+
+Just do it. Not everything needs ceremony.
+
+---
+
+### 5. During Work
+
+**Always:**
+- Read existing code before writing new code
+- Follow patterns you see in the codebase
+- Check `.claude/examples/` for conventions
+
+**If you find unrelated issues:**
+```
+You: /discover [brief title]
+```
+Claude files a Linear issue immediately. Stay focused on current task.
+
+**If stuck more than 5 minutes:**
+Stop. Explain what you've tried. Ask for guidance.
+
+**Confidence check:**
+- 8-10: Proceed
+- 5-7: Note your uncertainty, proceed carefully
+- 1-4: **STOP.** Ask for help.
+
+---
+
+### 6. Before Creating PR (1 min)
+
+```
+You: /evidence
+```
+
+Claude runs and captures output of:
+- Lint
+- Type check
+- Tests
+- Git status (files changed)
+- Code review (if enabled via `/anvil-settings`)
+
+Copy this evidence into your PR description.
+
+---
+
+### 7. End Your Session (2 min)
+
+```
+You: /handoff
+```
+
+Claude creates a handoff document with:
+- What you completed
+- What's in progress
+- What to do next
+- Important context
+
+**This is how future-you (or Claude) knows where you left off.**
+
+Optional session analysis:
+```
+You: /healthcheck
+```
+Claude analyzes your session for hook failures, tool errors, and framework issues.
+
+---
+
+## Common Scenarios
+
+### "I just want to fix a small bug"
+
+```
+/orient          → See context
+/validate        → Check environment
+[fix the bug]
+[run tests]
+/evidence        → Capture proof
+[create PR]
+/handoff         → Document
+```
+
+### "I'm starting a new feature"
+
+```
+/orient          → See context
+/ready           → See unblocked work
+/sprint          → Pick task
+/validate        → Check environment
+/explore         → Investigate first
+/spec            → Write specification (if complex)
+/shard           → Break into pieces (if spec is large)
+/plan            → Break into phases
+/tasks           → Create Linear issues
+[implement]
+/evidence        → Capture proof
+[create PR]
+/handoff         → Document
+```
+
+### "I'm modifying existing code"
+
+```
+/orient          → See context
+/sprint          → Confirm priority
+/validate        → Check environment
+/change          → Create change proposal
+[implement]
+/evidence        → Capture proof
+[create PR]
+/handoff         → Document
+```
+
+### "I'm continuing from yesterday"
+
+```
+/orient          → Read yesterday's handoff
+/sprint          → Confirm priority (or continue)
+/validate        → Check environment
+[continue work]
+/evidence        → When done
+/handoff         → End of day
+```
+
+### "I found a bug while working on something else"
+
+```
+/discover Fix login redirect on mobile
+```
+Then keep working on your original task.
+
+### "I'm running multiple Claude agents"
+
+```
+/hud             → Launch dashboard in separate terminal
+```
+Monitor all agents' context, cost, and work in real-time.
+
+### "It's Friday / end of sprint"
+
+```
+/weekly-review   → Generate analytics and recommendations
+/decay-review    → Archive old issues/specs
+/release         → Version and tag (if releasing)
+/insights        → Synthesize learnings from retros
+```
+
+### "I want to run Claude overnight" (Ralph Wiggum Mode)
+
+> **Important**: Ralph is a specialized power tool for specific scenarios, NOT a replacement for the standard workflow. See [When to Use Ralph](#ralph-wiggum-mode-special-scenarios) below.
+
+```
+/ralph start "Migrate all tests from Jest to Vitest" --max-iterations 50
+```
+
+Claude will:
+1. Break task into atomic TODO items
+2. Create PROMPT.md, fix_plan.md, progress.txt
+3. Start autonomous loop
+4. Execute ONE item per iteration
+5. Update progress.txt each iteration
+6. Stop when complete or circuit breaker triggers
+
+Monitor progress:
+```
+/ralph status    → See current iteration and progress
+```
+
+Stop early:
+```
+/ralph stop      → Gracefully terminate with summary
+```
+
+---
+
+## What NOT to Do
+
+| Don't | Instead |
+|-------|---------|
+| Start coding immediately | Run `/orient` first |
+| Work on main branch | Create feature branch |
+| Skip `/validate` | Always validate before changes |
+| Write code before reading existing code | Explore first |
+| Try to fix everything you find | `/discover` and stay focused |
+| End session without handoff | Always `/handoff` |
+| Push without evidence | Always `/evidence` first |
+| Query wrong issue source | Run `/linear-setup` or use local issues |
+
+---
+
+## Time Budget
+
+| Activity | Time |
+|----------|------|
+| /orient (fast-path) | ~1 sec |
+| /ready + /sprint | 1-2 min |
+| /validate | 30 sec |
+| /explore (if needed) | 5-10 min |
+| Actual work | Most of your time |
+| /evidence | 1 min |
+| /handoff | 2 min |
+
+**Overhead: ~5-10 minutes per session** for dramatically better continuity and quality.
+
+> **Tip**: Run `python3 global/lib/orient_fast.py` for 10-20x faster orientation startup.
+
+---
+
+## Commands Reference
+
+### Session Commands
+
+| Command | When | What It Does |
+|---------|------|--------------|
+| `/orient` | Session start | Shows context, handoffs, git state, ready work |
+| `/ready` | After orient | Shows unblocked issues sorted by priority |
+| `/sprint` | After ready | Suggests top priorities for the session |
+| `/validate` | Before any code | Checks environment is clean |
+| `/handoff` | Session end | Documents state for next time |
+
+### Workflow Commands
+
+| Command | When | What It Does |
+|---------|------|--------------|
+| `/explore` | New features | Discovery and investigation |
+| `/spec` | Complex features | Creates formal specification |
+| `/shard` | Large specs | Breaks spec into focused pieces |
+| `/plan` | After spec | Creates implementation phases |
+| `/tasks` | After plan | Creates Linear sub-issues |
+| `/change` | Brownfield work | Lightweight change proposal |
+| `/discover` | Find unrelated issue | Files it immediately in Linear |
+
+### Quality Commands
+
+| Command | When | What It Does |
+|---------|------|--------------|
+| `/evidence` | Before PR | Captures lint, types, tests, git status |
+| `/healthcheck` | Session end | Analyzes session for issues |
+| `/retro` | After completion | Captures learnings |
+
+### Multi-Agent Commands
+
+| Command | When | What It Does |
+|---------|------|--------------|
+| `/hud` | Multi-agent work | Launches terminal dashboard |
+
+### Maintenance Commands
+
+| Command | When | What It Does |
+|---------|------|--------------|
+| `/release` | End of sprint | Versions changelog, creates git tag |
+| `/weekly-review` | Friday | Generates analytics and recommendations |
+| `/decay-review` | Weekly | Archives old issues, specs, handoffs |
+| `/insights` | Weekly | Synthesizes patterns from retros |
+
+### Power Mode Commands (Ralph Wiggum)
+
+| Command | When | What It Does |
+|---------|------|--------------|
+| `/ralph start` | Large refactoring, overnight runs | Initializes autonomous execution loop |
+| `/ralph status` | During autonomous execution | Shows iteration count and progress |
+| `/ralph stop` | Early termination | Gracefully stops with summary |
+
+> **Note**: Ralph is a specialized tool for specific scenarios. See [Ralph Wiggum Mode](#ralph-wiggum-mode-special-scenarios).
+
+### Setup Commands
+
+| Command | When | What It Does |
+|---------|------|--------------|
+| `/linear-setup` | First use | Configures Linear team for project |
+| `/anvil-settings` | Configuration | Manages framework settings |
+| `/anvil-sync` | Updates | Syncs framework updates to project |
+
+---
+
+## Issue Providers
+
+Anvil supports two issue tracking providers that work interchangeably with all workflow commands.
+
+### Automatic Provider Detection
+
+Anvil automatically selects the issue provider based on your project configuration:
+
+| Configuration | Provider | Storage |
+|---------------|----------|---------|
+| `.claude/linear.yaml` exists | Linear | Linear API |
+| No Linear config | Local | `~/.anvil/issues/index.json` |
+
+### Linear Integration
+
+For teams using Linear:
+
+```bash
+/linear-setup    # Configure team and project
+```
+
+Once configured, all commands (`/orient`, `/ready`, `/sprint`, `/tasks`, `/discover`) query and create issues in Linear.
+
+### Local Issues
+
+For offline work, personal projects, or teams without Linear:
+
+```bash
+anvil-issue create --title "Add feature X"    # Create issue
+anvil-issue list --status todo                # View issues
+anvil-issue move LOCAL-001 --to in-progress   # Update status
+anvil-issue ready                             # See prioritized work
+```
+
+All workflow commands work identically with local issues:
+- `/orient` shows local issues in "Ready Work" section
+- `/ready` calculates ready work from local storage
+- `/sprint` prioritizes local issues
+- `/tasks` creates local issues from plans
+- `/discover` files discoveries as local issues
+
+### Switching Providers
+
+**To use Linear**: Run `/linear-setup` to create `.claude/linear.yaml`
+
+**To use Local**: Remove or rename `.claude/linear.yaml`
+
+**See Also**: [Local Issue Tracking Guide](local-issues.md) | [Command Reference](command-reference.md#local-issue-cli)
+
+---
+
+## Ralph Wiggum Mode (Special Scenarios)
+
+Ralph Wiggum is a **specialized power tool** for autonomous, long-running AI execution. It is NOT part of the standard daily workflow.
+
+### When to Use Ralph
+
+| Good For | Not Good For |
+|----------|--------------|
+| ✅ Large-scale refactoring with clear completion criteria | ❌ Exploratory work |
+| ✅ Framework migrations (Jest→Vitest, CJS→ESM) | ❌ Ambiguous requirements |
+| ✅ TDD with clear failing tests to pass | ❌ Security-sensitive code |
+| ✅ Greenfield projects with detailed specs | ❌ Architecture decisions |
+| ✅ Test coverage expansion | ❌ Quick fixes (overkill) |
+| ✅ Overnight/unattended execution | ❌ Interactive debugging |
+
+### Cost Awareness
+
+| Scenario | Estimated Cost |
+|----------|----------------|
+| 10 iterations, small codebase | $5-15 |
+| 50 iterations, medium codebase | $50-100+ |
+| 100+ iterations, large codebase | $200+ |
+
+**Start small**: Use `--max-iterations 10` to understand costs before overnight runs.
+
+### Decision Guide
+
+```
+Is this task...
+├── Quick fix or bug? → Use standard workflow
+├── Exploratory / unclear? → Use standard workflow
+├── Needs human decisions? → Use standard workflow
+├── Large with clear spec? → Consider Ralph
+├── Migration / refactoring? → Consider Ralph
+└── Overnight / unattended? → Ralph is ideal
+```
+
+### Safety Features
+
+Ralph includes automatic circuit breakers:
+- **No-change detection**: Stops after 3 iterations with no file changes
+- **Error detection**: Stops after 5 repeated identical errors
+- **Max iterations**: Configurable limit (default: 50)
+- **Fatal signal**: Immediate stop on `<fatal>...</fatal>` output
+- **Git checkpoints**: Auto-commits before each restart
+
+---
+
+*Print this. Keep it next to your keyboard. After a week, you won't need it.*