anvil-dev-framework 0.1.6

package/global/commands/orient.md

@@ -0,0 +1,510 @@
+# /orient - Session Startup Orientation
+
+> Quickly orient at session start by checking handoffs, git state, and ready work.
+
+## When to Use
+- **Always** at the start of a new session
+- After returning from a break
+- When context feels unclear
+
+## Fast-Path Execution (Recommended)
+
+First, check if the fast-path script exists:
+
+```bash
+if [ -f "global/lib/orient_fast.py" ]; then
+    python3 global/lib/orient_fast.py
+else
+    echo "Fast-path script not available, using manual steps"
+fi
+```
+
+If the script exists, it runs all checks in parallel (~500ms) and outputs structured results.
+
+Options:
+- `--fast`: Skip Linear API calls (local checks only, ~200ms)
+- `--json`: Output raw JSON for programmatic use
+
+**After running orient_fast.py**, proceed to Step 7 (Interactive Session Mode Selection).
+
+**If script doesn't exist**: Continue with Manual Execution Steps below.
+
+---
+
+## Manual Execution Steps (Fallback)
+
+Use these if orient_fast.py is unavailable (e.g., on main before PR merge).
+
+### Step 0: Check Linear Configuration
+
+**CRITICAL**: Before querying Linear, verify this project has a Linear team configured.
+
+```bash
+# Check for linear.yaml
+if [ -f ".claude/linear.yaml" ]; then
+    echo "Linear configuration found:"
+    cat .claude/linear.yaml
+else
+    echo "⚠️ NO LINEAR CONFIGURATION"
+    echo "This project is not mapped to a Linear team."
+    echo "Run /linear-setup to configure."
+fi
+```
+
+**If no linear.yaml exists**:
+- WARN the user prominently
+- Offer to run `/linear-setup`
+- Do NOT query Linear (would show wrong project's issues)
+- Continue with git state and handoff checks only
+
+**If linear.yaml exists**:
+- Read the `team_key` and `team_id`
+- Use these to filter ALL subsequent Linear queries
+- Mention the configured team in output
+
+### Step 1: Check for Active Agents and Claims (ANV-224)
+
+Check the agent registry and claims service for active agents and their claimed issues:
+
+```bash
+# Check agent registry for active agents
+python3 -c "
+import sys
+sys.path.insert(0, 'global/lib')
+from agent_registry import get_registry
+import json
+agents = get_registry().get_all()
+print(json.dumps(agents, indent=2))
+"
+
+# Check claims registry for claimed issues
+python3 -c "
+import sys
+sys.path.insert(0, 'global/lib')
+from claim_service import get_claims_summary
+import json
+print(json.dumps(get_claims_summary(), indent=2))
+"
+```
+
+Parse active agents from the agent registry at `~/.anvil/agents.json`:
+- Filter to agents with recent activity (within 1 minute)
+- Extract: codename (A1, A2), project, phase, model
+- Cross-reference with claims to show what each is working on
+
+If active agents exist:
+- List them in the orientation report with their claimed issues
+- Show codenames (A1, A2) instead of UUIDs for readability
+
+If no active agents:
+- Report "No other active agents" and continue
+
+### Step 2: Check for Recent Handoff
+```bash
+# Look for handoffs from last 48 hours
+find .claude/handoffs -name "*.md" -mtime -2 -type f | head -5
+```
+
+If handoff exists and is recent (<48 hours):
+1. Read the handoff file
+2. Note: completed work, in-progress items, recommended next task
+3. Report key context to user
+
+If no recent handoff:
+- Note this and proceed to next steps
+
+### Step 2.5: Post-Compaction Recovery Check (ANV-230)
+
+**CRITICAL**: If the session is resuming after context compaction, verify state hasn't drifted.
+
+**Detection signals** (any of these suggest post-compaction):
+- Session context mentions "continued from previous conversation"
+- Session context mentions "ran out of context" or "summarized"
+- Handoff file exists with timestamp close to current time
+- `.claude/anvil-state.json` shows work in progress but no recent activity
+
+**If post-compaction is detected, run the Triple-Check:**
+
+```bash
+# Triple-Check: Verify actual state matches expected state
+echo "=== POST-COMPACTION STATE VERIFICATION ==="
+
+# 1. Current branch
+echo "Branch: $(git branch --show-current)"
+
+# 2. Working directory status
+echo "Status:"
+git status --short
+
+# 3. Last commit (verify we're where we think we are)
+echo "Last commit: $(git log -1 --oneline)"
+```
+
+**Determining expected state** (check in this order):
+1. **Session summary**: If compacted, read the summary provided at session start for branch/task info
+2. **Handoff file**: Check `.claude/handoffs/` for recent handoff with branch and task details
+3. **anvil-state.json**: Check `.claude/anvil-state.json` for `activeIssue` and `phase`
+4. **Linear**: Query for issues in "In Progress" state assigned to this branch
+
+**Report format for post-compaction:**
+```
+## ⚠️ Post-Compaction State Check
+
+**Expected** (from handoff/context):
+- Branch: feature/ANV-XX-something
+- Working on: [task description]
+- Source: [handoff file / session summary / anvil-state.json]
+
+**Actual**:
+- Branch: [actual branch]
+- Status: [clean/dirty]
+- Last commit: [commit message]
+
+**Match**: ✅ State consistent / ❌ State mismatch detected
+```
+
+**If state mismatch detected:**
+1. STOP and report the discrepancy prominently
+2. Show what was expected vs what was found
+3. Suggest recovery actions:
+   - If wrong branch: `git checkout [expected-branch]`
+   - If uncommitted changes exist: Review with `git diff`
+   - If commits missing: Check `git reflog`
+4. Do NOT proceed with work until user confirms state is correct
+
+**If state matches:**
+- Note "Post-compaction check passed" and continue normally
+
+### Step 2.6: PR State Verification (ANV-230)
+
+**When to check**: If handoff or context mentions working on PR review feedback.
+
+Before committing any code related to PR feedback:
+
+```bash
+# Check if PR is still open
+gh pr view [PR_NUMBER] --json state,mergedAt,title
+```
+
+**If PR state is MERGED:**
+```
+## ⚠️ PR Already Merged
+
+PR #[NUMBER] "[title]" was merged at [mergedAt].
+
+**Do NOT commit to the feature branch.**
+
+**Recovery options:**
+1. Create follow-up PR from main with your changes
+2. Cherry-pick commits to a new branch
+3. Discard changes if they were already included in merge
+
+Recommended: `git checkout main && git pull && git checkout -b fix/[description]`
+```
+
+**If PR state is OPEN:**
+- Continue normally with feedback implementation
+
+**If PR state is CLOSED (not merged):**
+- Warn that PR was closed without merging
+- Suggest reopening or creating new PR
+
+### Step 3: Check Git State
+```bash
+git status
+git branch --show-current
+git log --oneline -3
+```
+
+Report:
+- Current branch
+- Whether there are uncommitted changes
+- Last few commits for context
+
+### Step 4: Check Linear for In-Progress Work
+
+**Only if linear.yaml exists and has team_key configured.**
+
+Use Linear MCP or CLI filtered to the configured team:
+
+```
+Query Linear for issues where:
+- Team key = [team_key from linear.yaml]
+- Status = "In Progress"
+- Limit to 10 results
+```
+
+If the team is not configured, skip this step and note "Linear not configured for this project."
+
+Report any work already marked as in-progress.
+
+### Step 5: Calculate Ready Work
+
+**Only if linear.yaml exists.**
+
+Run the `/ready` command logic, filtered to configured team:
+- Query active issues for THIS team only
+- Filter to those with no blocking dependencies
+- Sort by priority, then age
+- Report top 3-5 ready items
+
+### Step 6: Report Context Summary
+
+First, output a summary of the gathered context:
+
+```
+## Session Context
+
+**Linear Team**: [team_key] - [team_name]
+
+**Active Agents**: [count or "None"]
+**Handoff**: [Found / None]
+**Git**: [branch] ([clean/uncommitted])
+**Ready Work**: [count] items
+```
+
+### Step 7: Interactive Session Mode Selection (AskUserQuestion)
+
+**Use AskUserQuestion to let the user choose their session mode:**
+
+If a recent handoff exists, first confirm acknowledgment:
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Handoff",
+    question: "A handoff from [date] recommends: '[recommended task]'. How do you want to proceed?",
+    multiSelect: false,
+    options: [
+      { label: "Continue recommended (Recommended)", description: "Pick up where last session left off" },
+      { label: "New task", description: "Choose a different task from backlog" },
+      { label: "Explore first", description: "Review codebase before deciding" }
+    ]
+  }]
+})
+```
+
+If NO handoff exists:
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Session",
+    question: "What would you like to work on this session?",
+    multiSelect: false,
+    options: [
+      { label: "Pick from backlog (Recommended)", description: "Select a ready task from Linear" },
+      { label: "Continue in-progress", description: "Resume existing work" },
+      { label: "Explore codebase", description: "Discovery before committing to work" },
+      { label: "Custom task", description: "Describe what you want to work on" }
+    ]
+  }]
+})
+```
+
+### Step 8: Contextual Follow-up Based on Selection
+
+**If "Pick from backlog" or "New task" selected:**
+
+Present a task picker from ready work:
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Task",
+    question: "Which task would you like to work on?",
+    multiSelect: false,
+    options: [
+      // Dynamically populate from ready work (top 3-4)
+      { label: "[ANV-XX]: [Short title]", description: "Priority: P1 | [brief context]" },
+      { label: "[ANV-YY]: [Short title]", description: "Priority: P2 | [brief context]" },
+      { label: "[ANV-ZZ]: [Short title]", description: "Priority: P2 | [brief context]" }
+      // "Other" option automatically available for custom selection
+    ]
+  }]
+})
+```
+
+**If "Continue in-progress" selected:**
+
+If multiple in-progress items, present picker:
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Resume",
+    question: "Which in-progress work do you want to continue?",
+    multiSelect: false,
+    options: [
+      // Dynamically populate from in-progress work
+      { label: "[ANV-XX]: [Title]", description: "Branch: [branch] | Last: [time ago]" }
+    ]
+  }]
+})
+```
+
+**If "Explore codebase" selected:**
+- Output: "Ready for exploration. What would you like to explore?"
+- Don't use AskUserQuestion here—let user describe freely
+
+**If "Custom task" selected:**
+- Output: "Describe the task you'd like to work on."
+- Don't use AskUserQuestion—user provides description
+
+### Step 9: Branch Selection (Contextual)
+
+After task is selected, determine branch action:
+
+**If selected task has existing branch:**
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Branch",
+    question: "Task [ANV-XX] has existing branch 'feature/ANV-XX-[slug]'. What would you like to do?",
+    multiSelect: false,
+    options: [
+      { label: "Switch to it (Recommended)", description: "Checkout existing feature branch" },
+      { label: "Stay on current", description: "Stay on [current branch]" },
+      { label: "Create new branch", description: "Start fresh with new branch" }
+    ]
+  }]
+})
+```
+
+**If selected task has NO existing branch:**
+```typescript
+AskUserQuestion({
+  questions: [{
+    header: "Branch",
+    question: "Create a new branch for [ANV-XX]?",
+    multiSelect: false,
+    options: [
+      { label: "Yes, create branch (Recommended)", description: "Create feature/ANV-XX-[slug]" },
+      { label: "No, stay on current", description: "Work on [current branch]" }
+    ]
+  }]
+})
+```
+
+### Step 10: Execute and Confirm
+
+Based on selections:
+1. Switch/create branch if requested
+2. Update Linear issue status to "In Progress" if applicable
+3. Output final confirmation:
+
+```
+## Session Ready
+
+**Task**: [ANV-XX]: [Title]
+**Branch**: feature/ANV-XX-[slug]
+**Status**: In Progress
+
+Ready to begin. Run `/explore` if this is a new feature, or describe what you'd like to do first.
+```
+
+---
+
+## Output Format (Legacy - for non-interactive fallback)
+
+If AskUserQuestion is unavailable or user prefers text-based interaction:
+
+Output format (WITH Linear configured):
+```
+## Session Orientation
+
+**Linear Team**: [team_key] - [team_name]
+
+**Active Agents** (ANV-224):
+| Agent | Project | Claimed Issues | Phase |
+|-------|---------|----------------|-------|
+| A1 | anvil-dev-framework | ANV-22 | implement |
+| A2 | anvil-dev-framework | ANV-30, ANV-31 | plan |
+
+[Or if no other agents: "No other active agents detected."]
+
+**Handoff Status**: [Found recent handoff / No recent handoff]
+[If found: Key context summary]
+
+**Git State**:
+- Branch: [branch name]
+- Status: [clean / uncommitted changes]
+
+**In-Progress Work** ([team_key]):
+[List any in-progress Linear issues for THIS team]
+
+**Ready Work** (top 5 from [team_key]):
+1. [Issue key]: [Title] (Priority: [P0-P3]) [Claimed by A1 / Available]
+2. ...
+
+**Recommended Next Action**: [Based on handoff or highest priority UNCLAIMED ready work]
+[If issues are claimed: Recommend unclaimed issues to avoid conflicts]
+
+Awaiting your direction.
+```
+
+Output format (WITHOUT Linear configured):
+```
+## Session Orientation
+
+**⚠️ Linear Not Configured**
+This project is not mapped to a Linear team.
+Run `/linear-setup` to associate with a team.
+
+**Active Agents** (ANV-224):
+| Agent | Project | Claimed Issues | Phase |
+|-------|---------|----------------|-------|
+| A1 | anvil-dev-framework | (ad-hoc work) | implement |
+
+[Or if no other agents: "No other active agents detected."]
+
+**Handoff Status**: [Found recent handoff / No recent handoff]
+[If found: Key context summary]
+
+**Git State**:
+- Branch: [branch name]
+- Status: [clean / uncommitted changes]
+
+**Linear**: Skipped (not configured)
+
+**Recommended Next Action**: Run `/linear-setup` to configure Linear integration.
+[If other agents active: Check claims before starting work]
+
+Awaiting your direction.
+```
+
+## Key Behaviors
+- **ALWAYS** check agent registry and claims first (ANV-224)
+- **ALWAYS** check linear.yaml before querying Linear
+- **ALWAYS** run post-compaction triple-check if session is resuming from compaction (ANV-230)
+- **ALWAYS** verify PR state before committing review feedback (ANV-230)
+- Do NOT show issues from other teams/projects
+- Do NOT start working without explicit direction
+- Do NOT proceed after compaction if state mismatch detected
+- Report findings clearly and concisely
+- Surface any blockers or concerns
+- If handoff recommends specific task, highlight it
+- If issues are claimed, recommend unclaimed alternatives
+
+## State Sync (ANV-176)
+
+After completing orientation, update the session state:
+
+```bash
+python3 global/lib/state_manager.py orient
+```
+
+This updates `.claude/anvil-state.json` with:
+- `phase: "orient"`
+- Clears `activeIssue` (starting fresh)
+- Sets `lastCommand: "/orient"`
+
+And syncs to the agent registry for statusline visibility.
+
+## Integration Points
+- Uses: `global/lib/agent_registry.py` for active agent detection (ANV-222/223)
+- Uses: `global/lib/claim_service.py` for issue claims (ANV-224)
+- Uses: `~/.anvil/agents.json` (agent registry)
+- Uses: `~/.anvil/claims.json` (claims registry)
+- Uses: `.claude/linear.yaml` for team configuration
+- Uses: `.claude/handoffs/` directory
+- Uses: Linear MCP (filtered by team)
+- Uses: Git for repository state
+- Calls: `/ready` logic internally
+- Updates: `.claude/anvil-state.json` via state_manager.py