---
roadcrew_template_name: "autopilot.md"
roadcrew_template_type: "command"
execution_mode: "auto-execute"
roadcrew_template_version: "v2.0"
roadcrew_last_updated: "2025-11-05"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
---

# autopilot

<!-- Usage: /autopilot 231 [--repo https://github.com/org/repo] [--resume] [--yolo] -->

You are running a combined analysis and implementation of Github Epic {{EPIC_NUMBER}} in a single conversation.

> **Execution:** Runs immediately with continuous auto-proceeding. No approval pauses between analysis and implementation.

**Standalone Mode Support:** If --repo flag provided, use that repo for GitHub API calls and look for config in config/repos/org-repo/. If no --repo flag, use current repo (integrated mode).

**Prerequisites:** GitHub authentication required. See `.cursorrules.md` (lines 20-25) for authentication methods and workflow requirements.

**MANDATORY CURSORRULES COMPLIANCE:** Reference @.cursorrules.md throughout this work.

**COST OPTIMIZATION (minimize-cost patterns built-in):**
- Concise analysis summaries (structured bullets, no prose)
- Auto-proceed from analysis to implementation (no approval pause)
- Brief status updates during implementation
- "Done" when complete (no lengthy summaries)
- Close unrelated files throughout workflow
- Expected savings: 65-70% fewer tokens vs verbose mode

**STRICT SCOPE:** Only work on Epic {{EPIC_NUMBER}} and its child issues. Note unrelated issues but don't implement them.

**KEY DIFFERENCE FROM MANUAL WORKFLOW:**
This command combines `/analyze-epic` and `/implement-epic` in a single conversation. It automatically proceeds from analysis to implementation without asking for approval, maintaining full context throughout.

---

## STATE MANAGEMENT (CRITICAL FOR CONTINUATION)

**Autopilot maintains persistent state to survive interruptions and continue mid-epic.**

**State file location:** `.roadcrew/epic-{{EPIC_NUMBER}}-state.json`

**State structure:**
```json
{
  "epicNumber": 231,
  "epicTitle": "Example Epic",
  "startedAt": "2025-11-05T14:30:00Z",
  "phase": "implementation",
  "totalIssues": 5,
  "completedIssues": [],
  "currentIssue": 1180,
  "nextIssueIndex": 1,
  "issueSequence": [1179, 1180, 1181, 1182, 1183],
  "issueDependencies": {
    "1180": ["1179"],
    "1181": ["1179", "1180"],
    "1182": [],
    "1183": ["1182"]
  },
  "issueMetadata": {
    "1179": {"title": "Setup API", "status": "complete", "endedAt": "..."},
    "1180": {"title": "Add routes", "status": "pending", "startedAt": null}
  },
  "testFramework": "jest",
  "tokenBudgetEstimate": 45000,
  "tokensUsedPhase1": 8500,
  "tokensUsedImplementation": 12000,
  "estimatedTokensRemaining": 24500
}
```

**Resume behavior:**
- If state file exists, ask user: "Resume Epic #{{EPIC_NUMBER}} from issue #{{CURRENT_ISSUE}}? (Y/n)"
- If yes: Skip to Phase 2, load coordinator from state file, continue from next pending issue
- If no: Start fresh (WARNING: Will re-analyze, overwriting state)

---

## PHASE 0: STATE INITIALIZATION & RESUME CHECK (CRITICAL)

Before any analysis, check if resuming:

```typescript
import * as fs from 'fs';

const stateFile = `.roadcrew/epic-{{EPIC_NUMBER}}-state.json`;
let resumeMode = false;
let existingState = null;

// Check for existing state file
if (fs.existsSync(stateFile)) {
  try {
    existingState = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
    console.log(`📋 Found existing state for Epic #{{EPIC_NUMBER}}`);
    console.log(`   Completed issues: ${existingState.completedIssues.length}/${existingState.totalIssues}`);
    console.log(`   Last worked on: Issue #${existingState.currentIssue}`);
    console.log(`   Phase: ${existingState.phase}`);
    
    // Ask user if resuming
    const shouldResume = await askUser(`Resume from Issue #${existingState.currentIssue}? (Y/n)`, true);
    
    if (shouldResume) {
      resumeMode = true;
      console.log(`✅ Resuming Epic #{{EPIC_NUMBER}} from Issue #${existingState.currentIssue}`);
      console.log(`   Skipping to Phase 2 (Implementation)...`);
      
      // Jump directly to Phase 2 with loaded state
      // See PHASE 2 RESUME SECTION below
    }
  } catch (error) {
    console.warn(`⚠️  Could not load state file: ${error.message}`);
    console.log(`   Starting fresh analysis...`);
  }
}

if (!resumeMode) {
  console.log(`🚀 Starting new analysis for Epic #{{EPIC_NUMBER}}...`);
  // Continue to Phase 1
}
```

---

## PHASE 1: ANALYSIS (from /analyze-epic)

Only runs if NOT resuming. Use the epic-orchestrator to handle all analysis in a single call:

```typescript
import { analyzeEpic, checkCriticalQuestions } from '../scripts/utils/roadcrew/epic-orchestrator.js';
import * as fs from 'fs';

const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;

try {
  console.log(`📊 Phase 1: Analyzing Epic #{{EPIC_NUMBER}}...`);
  
  // Complete epic analysis (includes validation, child issues, dependencies, sequencing, risk assessment)
  const analysis = await analyzeEpic({{EPIC_NUMBER}}, token);
  
  // Check for unanswered critical questions
  const questions = checkCriticalQuestions(analysis.epic);
  if (questions.hasUnanswered) {
    console.error(`❌ Epic has ${questions.unanswered} unanswered critical questions`);
    process.exit(1);
  }
  
  console.log(`✅ Epic #{{EPIC_NUMBER}} analysis complete`);
  console.log(`   Child Issues: ${analysis.totalIssues}`);
  console.log(`   Estimated Effort: ${analysis.estimatedHours} hours`);
  
  // **Initialize state file path early** (needed for warning messages below)
  const stateFile = `.roadcrew/epic-{{EPIC_NUMBER}}-state.json`;
  
  // **CRITICAL: Calculate token budget for ALL remaining issues**
  // Estimate: ~2000-3000 tokens per issue (analysis + implementation + testing)
  // Add 5000 tokens for overhead (summaries, coordination, etc.)
  const estimatedTokensPerIssue = 2500;
  const estimatedTotalTokens = (analysis.totalIssues * estimatedTokensPerIssue) + 5000;
  const estimatedTokensPhase1 = Math.round(estimatedTotalTokens * 0.15); // Phase 1 = ~15%
  const estimatedTokensPhase2 = estimatedTotalTokens - estimatedTokensPhase1;
  
  console.log(`\n💾 Token Budget Estimate:`);
  console.log(`   Phase 1 (Analysis): ~${estimatedTokensPhase1} tokens`);
  console.log(`   Phase 2 (Implementation): ~${estimatedTokensPhase2} tokens`);
  console.log(`   **Total: ~${estimatedTotalTokens} tokens**`);
  
  // If >60,000 tokens, warn and suggest splitting epic
  if (estimatedTotalTokens > 60000) {
    console.warn(`\n⚠️  WARNING: This epic will consume ~${estimatedTotalTokens} tokens`);
    console.warn(`   Typical session budget: 100,000-200,000 tokens`);
    console.warn(`   Recommendation: Consider splitting into smaller epics (max 3-4 issues each)`);
    
    const shouldContinue = await askUser(`Continue anyway? (Y/n)`, false);
    if (!shouldContinue) {
      console.log(`📌 Epic analysis saved to: ${stateFile}`);
      console.log(`   You can resume later with: /autopilot {{EPIC_NUMBER}} --resume`);
      process.exit(0);
    }
  }
  
  // **Initialize state file for this epic**
  const epicState = {
    epicNumber: {{EPIC_NUMBER}},
    epicTitle: analysis.epic.title,
    startedAt: new Date().toISOString(),
    phase: 'implementation',
    totalIssues: analysis.totalIssues,
    completedIssues: [],
    currentIssue: analysis.orderedIssues[0]?.number || null,
    nextIssueIndex: 0,
    issueSequence: analysis.orderedIssues.map(i => i.number),
    issueDependencies: Object.fromEntries(analysis.dependencyMap),
    issueMetadata: analysis.orderedIssues.reduce((acc, issue) => {
      acc[issue.number] = {
        title: issue.title,
        dependencies: issue.dependencies || [],
        status: 'pending',
        startedAt: null,
        endedAt: null,
        riskLevel: analysis.risks.get(issue.number.toString())?.level || 'low'
      };
      return acc;
    }, {}),
    testFramework: 'jest', // Will be detected in Phase 2
    tokenBudgetEstimate: estimatedTotalTokens,
    tokensUsedPhase1: 0,
    tokensUsedImplementation: 0,
    estimatedTokensRemaining: estimatedTotalTokens
  };
  
  // Save state
  const stateDir = '.roadcrew';
  if (!fs.existsSync(stateDir)) {
    fs.mkdirSync(stateDir, { recursive: true });
  }
  fs.writeFileSync(stateFile, JSON.stringify(epicState, null, 2));
  
  console.log(`\n✅ Analysis phase complete. State saved to: ${stateFile}`);
  console.log(`\n⏭️  Auto-proceeding to Phase 2 (Implementation)...`);
  
} catch (error) {
  console.error('❌ Analysis failed:', error.message);
  process.exit(1);
}
```

---

## PHASE 2: IMPLEMENTATION (from /implement-epic)

**CRITICAL: This phase MUST loop through ALL issues without pausing between them.**

Use ImplementationCoordinator + epic-orchestrator + testing-harness for complete automation:

```typescript
import { ImplementationCoordinator } from '../scripts/utils/roadcrew/implementation-coordinator.js';
import { analyzeEpic } from '../scripts/utils/roadcrew/epic-orchestrator.js';
import { detectTestFramework, initializeTestFramework } from '../scripts/utils/roadcrew/testing-harness.js';
import * as fs from 'fs';

const stateFile = `.roadcrew/epic-{{EPIC_NUMBER}}-state.json`;

// Load state (either from Phase 1 or resume)
let epicState;
if (fs.existsSync(stateFile)) {
  epicState = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
  console.log(`📋 Loaded state: ${epicState.completedIssues.length}/${epicState.totalIssues} issues complete`);
} else {
  console.error('❌ No state file found. Run Phase 1 first.');
  process.exit(1);
}

// Initialize coordinator from state
const coordinator = new ImplementationCoordinator({{EPIC_NUMBER}});
coordinator.loadState();

// Set analysis output in coordinator
coordinator.setAnalysisOutput({
  issues: epicState.issueSequence.map(issueNum => ({
    number: issueNum,
    title: epicState.issueMetadata[issueNum].title,
    dependencies: epicState.issueDependencies[issueNum] || [],
    classification: 5,
    status: epicState.completedIssues.includes(issueNum) ? 'complete' : 'pending'
  })),
  dependencies: epicState.issueDependencies,
  sequenceOrder: epicState.issueSequence
});

// Detect test framework for project
const packageJson = fs.readFileSync('package.json', 'utf-8');
const framework = detectTestFramework(packageJson);
initializeTestFramework(framework);
epicState.testFramework = framework;

console.log(`\n🔧 Phase 2: Implementation Loop`);
console.log(`   Issues to implement: ${epicState.issueSequence.length}`);
console.log(`   Already complete: ${epicState.completedIssues.length}`);
console.log(`   Remaining: ${epicState.issueSequence.length - epicState.completedIssues.length}`);

// **CRITICAL: CONTINUOUS IMPLEMENTATION MODE**
// - Implement ALL issues in the epic without pausing for approval between issues
// - DO NOT ask "Ready to continue?" or "Pause for review?" between issues
// - DO NOT recommend "Continue in next session" - keep going until all issues complete
// - Complex/time-consuming work is EXPECTED in epics - continue regardless of complexity
// - Only pause at critical human checkpoints (authentication failures, blocking issues, scope creep)

let issuesCompleted = 0;
let issuesFailed = 0;

// Track pending issues (not yet complete or failed)
let pendingIssues = epicState.issueSequence.filter(n => !epicState.completedIssues.includes(n));
let consecutiveSkips = 0;
const maxConsecutiveSkips = pendingIssues.length; // Detect when all pending issues are blocked

while (pendingIssues.length > 0) {
  const issueNumber = pendingIssues[0]; // Always work on first pending issue
  
  // Check dependencies
  const deps = epicState.issueDependencies[issueNumber] || [];
  const unmetDeps = deps.filter(dep => !epicState.completedIssues.includes(dep));
  
  if (unmetDeps.length > 0) {
    // **Unmet dependencies: Move to end of queue for retry after other issues**
    pendingIssues.shift(); // Remove from front
    pendingIssues.push(issueNumber); // Add to back for retry
    consecutiveSkips++;
    
    // If we've cycled through all pending issues without progress, we have a circular dependency
    if (consecutiveSkips > maxConsecutiveSkips) {
      console.error(`\n❌ CIRCULAR DEPENDENCY DETECTED`);
      console.error(`   Issues stuck in loop: ${pendingIssues.slice(0, 3).join(', ')}${pendingIssues.length > 3 ? '...' : ''}`);
      console.error(`   Unmet dependencies: ${unmetDeps.join(', ')}`);
      
      const shouldContinue = await askUser(`Skip these blocked issues and continue? (Y/n)`, false);
      if (!shouldContinue) {
        console.log(`\n📌 Epic state saved. You can resume later with: /autopilot {{EPIC_NUMBER}} --resume`);
        process.exit(1);
      }
      
      // Skip the entire circular dependency chain
      const blockedIssues = pendingIssues.slice(0, maxConsecutiveSkips);
      pendingIssues = pendingIssues.filter(i => !blockedIssues.includes(i));
      blockedIssues.forEach(i => {
        epicState.issueMetadata[i].status = 'blocked';
        epicState.issueMetadata[i].error = 'Circular dependency detected';
      });
      consecutiveSkips = 0;
      continue;
    }
    
    console.warn(`⚠️  Issue #${issueNumber} waiting on: ${unmetDeps.join(', ')}`);
    console.warn(`   Moving to end of queue (${pendingIssues.length} issues ahead)`);
    continue;
  }
  
  // **Dependencies met: Reset skip counter and process issue**
  consecutiveSkips = 0;
  pendingIssues.shift(); // Remove from queue
  
  // **UPDATE STATE: Mark issue as starting**
  epicState.currentIssue = issueNumber;
  epicState.issueMetadata[issueNumber].status = 'implementing';
  epicState.issueMetadata[issueNumber].startedAt = new Date().toISOString();
  fs.writeFileSync(stateFile, JSON.stringify(epicState, null, 2));
  
  // Get issue details
  const issueTitle = epicState.issueMetadata[issueNumber].title;
  const issueRisk = epicState.issueMetadata[issueNumber].riskLevel;
  
  console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
  console.log(`📌 [${issuesCompleted + issuesFailed + 1}/${epicState.issueSequence.length}] Issue #${issueNumber}: ${issueTitle}`);
  console.log(`   Risk Level: ${issueRisk}`);
  console.log(`   Pending: ${pendingIssues.length}`);
  console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
  
  // Implement this issue (delegates to /implement-issue pattern)
  try {
    const nextIssue = {
      number: issueNumber,
      title: issueTitle,
      dependencies: deps,
      classification: 5
    };
    
    await implementIssue(nextIssue, framework, coordinator);
    
    // **UPDATE STATE: Mark issue as complete**
    epicState.completedIssues.push(issueNumber);
    epicState.issueMetadata[issueNumber].status = 'complete';
    epicState.issueMetadata[issueNumber].endedAt = new Date().toISOString();
    epicState.phase = 'implementation';
    fs.writeFileSync(stateFile, JSON.stringify(epicState, null, 2));
    
    console.log(`✅ Issue #${issueNumber} complete`);
    issuesCompleted++;
    
  } catch (error) {
    // **UPDATE STATE: Mark issue as failed**
    epicState.issueMetadata[issueNumber].status = 'failed';
    epicState.issueMetadata[issueNumber].error = error instanceof Error ? error.message : String(error);
    fs.writeFileSync(stateFile, JSON.stringify(epicState, null, 2));
    
    console.error(`❌ Issue #${issueNumber} failed: ${error instanceof Error ? error.message : String(error)}`);
    issuesFailed++;
    
    // Check if this is a blocking issue (stop continuation?)
    if (issueRisk === 'high') {
      console.error(`\n⚠️  HIGH RISK issue failed. This may block dependent issues.`);
      const dependentIssues = epicState.issueSequence.filter(i => (epicState.issueDependencies[i] || []).includes(issueNumber));
      if (dependentIssues.length > 0) {
        console.error(`   Dependent issues: ${dependentIssues.join(', ')}`);
      }
      
      const shouldContinue = await askUser(`Skip this issue and continue with remaining? (Y/n)`, false);
      if (!shouldContinue) {
        console.log(`\n📌 Epic state saved. You can resume later with: /autopilot {{EPIC_NUMBER}} --resume`);
        process.exit(1);
      }
      
      // Mark dependent issues as blocked too
      dependentIssues.forEach(depIssue => {
        if (pendingIssues.includes(depIssue)) {
          pendingIssues = pendingIssues.filter(i => i !== depIssue);
          epicState.issueMetadata[depIssue].status = 'blocked';
          epicState.issueMetadata[depIssue].error = `Blocked by failed dependency #${issueNumber}`;
        }
      });
    }
  }
  
  // **CRITICAL: IMMEDIATELY continue to next issue** (no pause, no approval needed)
  
  // After every 3 issues, log progress
  if ((issuesCompleted + issuesFailed) % 3 === 0) {
    console.log(`\n📊 Progress: ${issuesCompleted} complete, ${issuesFailed} failed, ${pendingIssues.length} pending`);
    console.log(`   State saved to: ${stateFile}`);
  }
}

console.log(`\n✅ All issues implemented`);
console.log(`   Completed: ${issuesCompleted}`);
console.log(`   Failed: ${issuesFailed}`);
console.log(`   Total: ${issuesCompleted + issuesFailed}`);
```

---

## PHASE 3: WRAP-UP & STATE CLEANUP

After all issues are complete:

```typescript
import * as fs from 'fs';

const stateFile = `.roadcrew/epic-{{EPIC_NUMBER}}-state.json`;
const epicState = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));

console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
console.log(`✨ Epic #{{EPIC_NUMBER}} Complete!`);
console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
console.log(`\n📈 Final Metrics:`);
console.log(`   Issues Completed: ${epicState.completedIssues.length}/${epicState.totalIssues}`);
console.log(`   Duration: ${calculateDuration(epicState.startedAt)}`);
console.log(`   Status: ${epicState.completedIssues.length === epicState.totalIssues ? '🎉 SUCCESS' : '⚠️  PARTIAL'}`);

// Update state to mark complete
epicState.phase = 'complete';
epicState.completedAt = new Date().toISOString();
fs.writeFileSync(stateFile, JSON.stringify(epicState, null, 2));

console.log(`\n📌 State file saved (for reference): ${stateFile}`);
console.log(`   You can view final metrics with: cat ${stateFile}`);

// Create PR
console.log(`\n🔄 Creating PR...`);
// ... PR creation logic follows /implement-epic pattern
```

---

## NO SEPARATE STEPS NEEDED

Epic-orchestrator + ImplementationCoordinator + testing-harness consolidate:
- Template validation
- Critical question checks
- Child issue fetching
- Dependency sequencing with TOC
- Risk assessment
- Project context detection
- Test framework detection
- **State persistence** ← NEW
- **Resume capability** ← NEW
- **Token budgeting** ← NEW
- Implementation sequencing
- Metrics tracking

Everything is orchestrated into clean, reusable components.

---

## GUARDRAILS

1. **Scope Control**
   - Max 7 issues per epic
   - If >7 issues: propose epic split with dependencies
   - Flag if issues are loosely coupled (suggest parallel implementation)

2. **Checkpoint Commits**
   - One commit per issue (easy to bisect if problems)
   - Clear commit messages: "feat(epic-{{EPIC_NUMBER}}): [Issue #N] description"
   - Rebase from base branch before each issue if epic is multi-day
   - Mark breaking changes in commit message if applicable

3. **Critical Validation Points**
   - Identify 2-3 critical checkpoints upfront
   - Schema changes: validate migrations work before continuing
   - Breaking changes: verify upgrade path before continuing
   - Optional: --validate flag for mid-epic testing
   - Always test at epic completion (automated + manual)

4. **Escape Hatches**
   - If issue blocked: document, skip, continue
   - If major issue discovered: pause, get approval
   - If scope creep detected: flag immediately

5. **Authentication Failures**
   - If auth fails mid-epic: commit WIP, document state
   - Prompt user to re-authenticate:
     * See `.cursorrules.md` (lines 20-25) for authentication setup instructions
     * Create a personal access token at https://github.com/settings/tokens if needed
   - User re-runs `/autopilot {{EPIC_NUMBER}} --resume` to resume

---

## BEST USE CASES

✅ Tightly coupled issues (shared files/functions)
✅ Sequential dependencies (Issue B needs Issue A)
✅ Feature development (coherent user story)
✅ Refactoring epics (architectural changes)
✅ **When you want analysis + implementation in one go**
✅ **When epic may take multiple sessions** (state persists)

## AVOID FOR

❌ Epics with >10 issues (split into smaller epics)
❌ Issues with no dependencies (use implement-issue in parallel)
❌ Hotfixes (use implement-issue)
❌ Exploratory work (unknown scope)
❌ **When you want to review analysis before implementing** (use /analyze-epic + /implement-epic separately)

---

## EFFICIENCY GAINS

- **40% time reduction** vs separate analyze-epic + implement-epic workflow
- **No context loss** between analysis and implementation
- Single conversation maintains full context
- **Multi-session capability** with state persistence
- Reduced context switching (analysis context flows to implementation)
- Single deployment cycle
- Batch testing (better integration coverage)
- Single PR review cycle

---

## COMPARISON WITH MANUAL WORKFLOW

|| Aspect | Manual (/analyze-epic + /implement-epic) | /autopilot |
||--------|------------------------------------------|------------|
|| Commands to run | 2 | 1 |
|| Context retained | ✅ (if same conversation) | ✅ |
|| Approval between phases | Yes (manual Y/N) | No (automatic) |
|| Multi-session support | ❌ (context lost) | ✅ (state persists) |
|| Best for | When you want to review analysis first | When analysis → implementation should be seamless |
|| Total time | 100% | ~60% |

---

## 📌 ISSUE CLOSURE WORKFLOW

The issue closure workflow is identical to `/implement-epic`:

1. `/autopilot {{EPIC_NUMBER}}` creates PR: epic-{{EPIC_NUMBER}} → dev
   - Issues listed but NOT closed yet
   - Adds 'pending-closure' label to epic #{{EPIC_NUMBER}} and all child issues

2. Review and merge epic PR to dev
   - Issues remain open with 'pending-closure' label

3. `/create-release-pr` creates PR: dev → main
   - Automatically includes "Closes #N" for all pending issues (epic + children)
   - Epic issue #{{EPIC_NUMBER}} and all child issues auto-close when merged to main ✅

4. Release issue automatically updated:
   - Epic marked complete in checklist
   - Progress metrics recalculated
   - Status changes to "Ready for Release" when all epics done

Alternative: Manually create dev → main PR with "Closes #N" keywords for ALL issues

---

## ⚠️ WHEN TO PAUSE (Escape Hatches Only - Issue #1182)

**The only legitimate pauses during autopilot execution:**

1. **GitHub Authentication Failure**
   - If GITHUB_TOKEN/GH_TOKEN auth fails mid-epic
   - Prompt user to re-authenticate
   - Commit WIP and document state
   - User re-runs `/autopilot {{EPIC_NUMBER}} --resume` to resume

2. **Circular Dependency Detected**
   - If issue dependencies form a loop
   - Display circular dependency chain
   - Ask user: Continue with numeric order fallback? (Y/n)
   - Document the issue for post-epic review

3. **Blocking Issue Discovered** 
   - If an issue cannot be implemented due to external blocker
   - Document the blocker reason
   - Ask: Skip this issue and continue with remaining? (Y/n)
   - Mark as blocked in metrics

4. **Scope Creep Detected**
   - If new requirements emerge during implementation
   - Ask: Accept scope change and include? (Y/n)
   - If yes: Add to epic, continue
   - If no: Document for future epic, continue

5. **Major Breaking Change Risk**
   - If a change will break production or existing users
   - Display risk assessment and mitigation strategy
   - Ask: Proceed with risk mitigation in place? (Y/n)
   - Document risk and mitigation in commit message

6. **Token Budget Exceeded**
   - Calculate estimated tokens at start of Phase 1
   - If >60,000 tokens: warn and ask to split epic
   - Track token usage through implementation
   - If approaching budget limit: warn before starting new issue

**Cumulative Pause Logic (Issue #1182):**

- **FREE tier**: Pauses at beginning AND after every issue OR 3 minutes (maximum supervision)
- **STARTER tier**: Pauses at beginning AND after every 3 issues OR 5 minutes (moderate autonomy)
- **ENTERPRISE tier**: No pause at beginning, immediate execution. Only pauses for critical issues or after all 10+ issues complete (full autonomy)

**DO NOT PAUSE FOR:**
- ❌ Token budget/cost concerns (included in pre-flight checks)
- ❌ "Just checking if you want to review this" (user approved epic scope already)
- ❌ Complexity or time concerns (expected and pre-assessed)
- ❌ Asking for permission between issues (defeats the purpose of autopilot)
- ❌ Resuming after PR creation (wait for CI, then auto-continue or notify user)

**--yolo Flag (Issue #1182):**

Use `--yolo` to skip regular tier-based pauses. Only pauses for critical issues or when all issues are complete:

```bash
/autopilot 231 --yolo
```

- Skips beginning pause (all tiers)
- Skips per-issue pauses (all tiers)
- Skips time-based pauses (all tiers)
- Still pauses for critical issues (breaking changes, security, blocked issues)
- Perfect for trusted developers or fully-tested epics

Note: `--force` flag deprecated in favor of `--yolo` (kept for backwards compatibility)

---

## RESUME WORKFLOW

**If autopilot is interrupted (token limit, connection lost, intentional pause):**

1. **Inspect state file:**
   ```bash
   cat .roadcrew/epic-{{EPIC_NUMBER}}-state.json
   ```

2. **Check progress:**
   - `completedIssues`: Which issues are done
   - `currentIssue`: Which issue was being worked on
   - `phase`: Current phase (analysis/implementation/complete)

3. **Resume autopilot:**
   ```bash
   /autopilot {{EPIC_NUMBER}} --resume
   ```
   - Skips Phase 1 (analysis already done)
   - Loads state from file
   - Continues from next pending issue
   - Asks confirmation before proceeding

4. **Or start fresh:**
   ```bash
   /autopilot {{EPIC_NUMBER}}
   ```
   - WARNING: Will re-analyze (overwrites state file)
   - Use this only if analysis changed (new dependencies, updated epic)

---

Behavior:

- If invoked with trailing text (e.g., "/autopilot 231"), interpret that text as {{EPIC_NUMBER}} and proceed.
- If {{EPIC_NUMBER}} is missing, ask me once for it before proceeding.
- **ALWAYS create and maintain the TODO list throughout the entire workflow**
- **NO APPROVAL REQUIRED between analysis and implementation phases** - auto-proceed automatically
- **ALWAYS save state after each issue completes** - enables resumption on interruption
- **ALWAYS show progress after every 3 issues** - keeps user informed