Auto Mode - Autonomous Execution

The Flagship Feature

Auto mode is SpecWeave's most powerful feature - it can execute tasks, run tests, fix failures, and sync to GitHub/JIRA completely autonomously for hours.

Quick Start

# Start autonomous execution
/sw:auto

# Check progress (in another session)
/sw:auto-status

# Emergency stop (rarely needed - just close session)
/sw:cancel-auto

What is Auto Mode?

Auto mode executes your tasks autonomously in a continuous loop:

Reads next task from tasks.md
Implements the task (writes code, runs commands)
Runs tests automatically (unit + integration + E2E if present)
Self-heals failures (up to 3 retry attempts with fixes)
Syncs to living docs (updates documentation)
Moves to next task (repeats until all done)

Real-world proven: Tested with increments taking 2-3 hours, mobile app generation, multi-repo coordination.

NEW in v2.9: Label Visibility

You can now SEE what auto mode is doing! Labels appear in your conversation showing real-time progress.

During Execution

When auto mode continues working, you see:

╔══════════════════════════════════════════════════════════════╗
║  🔄 AUTO SESSION CONTINUING                                  ║
║  🤖 Main Orchestrator                                        ║
╠══════════════════════════════════════════════════════════════╣
║  Why: Work incomplete, continuing...                         ║
║  Iteration: 42/2500                                         ║
║  Increment: 0001-user-auth                                  ║
║  Subagents used: 3                                          ║
╠══════════════════════════════════════════════════════════════╣
║  🎯 WHEN WILL SESSION STOP?                                  ║
║  ├─ Mode: STANDARD MODE                                     ║
║  └─ Criteria: ALL tasks [x] completed + tests passing       ║
║  ✅ Tests: 42 passed, 0 failed                              ║
╚══════════════════════════════════════════════════════════════╝

What this tells you:

Current iteration: 42 out of 2500 max (safety limit)
Active increment: 0001-user-auth
Subagents spawned: 3 specialized agents used
Stop criteria: Mode and what needs to happen to complete
Test status: 42 tests passing, 0 failures

On Completion

When auto mode finishes successfully:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃  ✅ AUTO SESSION COMPLETE                                   ┃
┃  🤖 Main Orchestrator                                       ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃  Status: SUCCESS - All work completed                       ┃
┃  Reason: All tasks completed, all tests passed             ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃  📊 SESSION SUMMARY                                         ┃
┃  ├─ Iterations: 47/100                                      ┃
┃  ├─ Increment: 0001-user-auth                              ┃
┃  ├─ Subagents spawned: 3                                   ┃
┃  └─ Tests: 42 passed, 0 failed                             ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Before v2.9

These labels existed but were hidden in STDERR. Now they appear directly in your conversation, giving you complete visibility into auto mode's progress!

How It Works

Auto mode implements the Ralph Wiggum pattern - it continuously asks "Am I done yet?" after each task.

The Execution Loop

Key Mechanisms

1. Self-Healing (NEW in v2.0)

Analyzes test failures
Extracts specific error details
Applies targeted fixes
Retries automatically (max 3 attempts)

2. Test Validation (MANDATORY)

Runs npm test after every task
Runs E2E tests if Playwright detected
Blocks completion on ANY test failure
TDD strict mode: 0 failures required

3. Safety Nets

Max iterations (default: 2500)
Max hours (default: none)
Circuit breakers (external APIs)
Human gates (dangerous operations)

Stop Conditions

Auto mode stops when ANY of these conditions are met:

✅ Success Conditions

Condition	Description
All tasks complete	Every task in `tasks.md` marked `[x] completed`
All tests passing	`npm test` returns 0 failures
E2E tests passed	Playwright tests pass (if detected)
Multiple increments	Transitions to next increment in queue

🛑 Stop Conditions

Condition	Description	Action
Max iterations	Reached 2500 iterations	Session ends
Max hours	Time limit exceeded (if configured)	Session ends
Test failures (3x)	Tests failed 3 times in a row	Pause for human
Low confidence	Self-assessment score < 0.50	Pause for review
Credential errors	Multiple auth/deployment failures	Pause for config
Human gate	Dangerous operation detected	Wait for approval
Circuit breaker	External API failing repeatedly	Queue and continue

⏸️ Pause Conditions

These pause the session but don't end it:

External configuration needed (env vars, credentials)
Structural issues (architecture decisions required)
Unfixable errors (but more work in queue - skips to next)

Advanced Usage

Check Progress

While auto mode is running, check status from another session:

/sw:auto-status

Output:

📊 AUTO SESSION STATUS

Session ID: auto-2026-01-06-a8b012
Status: RUNNING
Started: 2 hours ago
Iteration: 847/2500

Current Increment: 0023-payment-integration
Completed: 12/25 tasks
Tests: 156 passed, 0 failed

Circuit Breakers:
├─ GitHub: CLOSED (healthy)
├─ JIRA: CLOSED (healthy)
└─ ADO: CLOSED (healthy)

Human Gates: None pending

Emergency Stop

If you need to manually cancel (rarely needed):

/sw:cancel-auto

Emergency Use Only

Prefer closing the Claude Code session naturally. /sw:cancel-auto is for emergencies where the session is stuck or unresponsive.

TDD Strict Mode

Enable stricter test requirements:

// .specweave/config.json
{
  "auto": {
    "tddStrictMode": true
  }
}

Changes behavior:

Tests MUST be written before implementation
0 test failures required (not just "most passing")
Blocks completion if 0 tests passed (suspicious)

Configuration Options

Session Limits

// .specweave/config.json
{
  "auto": {
    "maxIterations": 2500,    // Max loop iterations (safety)
    "maxHours": 8,             // Max duration in hours (optional)
    "tddStrictMode": false     // Require TDD discipline
  }
}

Circuit Breakers

Prevent external API failures from blocking progress:

{
  "auto": {
    "circuitBreaker": {
      "github": { "maxFailures": 3, "resetMinutes": 5 },
      "jira": { "maxFailures": 3, "resetMinutes": 5 },
      "ado": { "maxFailures": 3, "resetMinutes": 5 }
    }
  }
}

Best Practices

✅ DO

Start with small increments (5-10 tasks max for first time)
Monitor first few iterations (check if it's progressing correctly)
Ensure tests exist (auto mode needs tests to validate)
Use for repetitive tasks (CRUD operations, API endpoints)
Review logs periodically (check .specweave/logs/auto-iterations.log)

❌ DON'T

Don't use for exploratory work (architecture decisions need human input)
Don't ignore test failures (fix broken tests before starting auto)
Don't run on dirty git tree (commit or stash changes first)
Don't use without tests (auto mode validates via tests)

Real-World Examples

Example 1: Mobile App Generation (2-3 hours)

/sw:increment "React Native app with authentication and offline sync"
# Creates 25 tasks: setup, navigation, auth screens, API, offline storage, tests

/sw:auto
# Runs for 2.5 hours:
# - Installs dependencies (Expo, React Navigation)
# - Creates screens with proper navigation
# - Implements auth flow with AsyncStorage
# - Sets up offline sync with network detection
# - Writes and runs 42 tests (all passing)
# - Updates living docs
# Session completes autonomously!

Example 2: Microservices Coordination

/sw:increment "Add payment webhook to order service and update frontend"
# Multi-repo increment: backend service + frontend + shared types

/sw:auto
# Coordinates across repos:
# 1. Updates shared/ with PaymentWebhookEvent type
# 2. Adds webhook handler to backend/
# 3. Updates frontend/ to show payment status
# 4. Runs tests in all three repos
# 5. Syncs to GitHub (3 PRs created)

Example 3: Documentation Generation

/sw:increment "Generate API docs for all endpoints"
# 15 tasks: one per endpoint category

/sw:auto
# Processes each endpoint:
# - Extracts OpenAPI specs from code
# - Generates markdown docs
# - Creates Postman collection
# - Adds examples and response schemas
# - Validates docs against actual API
# Completes in 45 minutes

Troubleshooting

"Session keeps retrying same failure"

Symptom: Auto mode stuck retrying a failing test 3 times.

Solution:

Let it complete 3 retries (it will pause)
Review the failure details in the pause message
Fix manually with /sw:do
Continue with /sw:resume or start fresh

"Auto mode stopped early"

Symptom: Session ended before all tasks complete.

Possible causes:

Max iterations reached → Check logs
Max hours exceeded → Increase limit or split increment
Low confidence score → Review last few tasks for quality

Check logs:

tail -50 .specweave/logs/auto-stop-reasons.log

"Tests not running"

Symptom: Auto mode completes but shows "Tests: NOT YET RUN"

Solution:

Ensure npm test command works
Check test files exist (*.test.ts, *.spec.ts)
Verify test framework installed (Vitest, Jest, Playwright)

"Circuit breaker triggered"

Symptom: Message says "GitHub circuit breaker open"

Solution:

Wait 5 minutes (auto-reset)
Check GitHub API rate limits
Verify GITHUB_TOKEN is valid
Auto mode will queue sync and continue with other work

Monitoring & Logs

Log Files

Auto mode creates detailed logs:

File	Contains
`.specweave/logs/auto-iterations.log`	Every iteration with timestamp
`.specweave/logs/auto-stop-reasons.log`	Why session stopped each time
`.specweave/logs/auto-sessions.log`	Session start/end events
`.specweave/state/auto-session.json`	Current session state

Session State File

View current session details:

cat .specweave/state/auto-session.json

{
  "sessionId": "auto-2026-01-06-a8b012",
  "status": "running",
  "startTime": "2026-01-06T10:00:00Z",
  "iteration": 847,
  "maxIterations": 2500,
  "currentIncrement": "0023-payment-integration",
  "completedIncrements": ["0022-user-profile"],
  "testRetryCount": 0,
  "circuitBreakers": {
    "github": { "state": "closed", "failures": 0 },
    "jira": { "state": "closed", "failures": 0 }
  }
}

Comparison: Auto vs Manual

Aspect	`/sw:auto`	`/sw:do`
Execution	Autonomous (hours)	Manual (one task)
Test validation	Automatic	Manual
Failure handling	Self-healing (3 retries)	Human fixes
Progress visibility	Labels show status	Direct feedback
Best for	Repetitive tasks, CRUD	Exploratory work
Supervision	Monitor periodically	Full attention

Choose auto mode when:

Tasks are well-defined (clear acceptance criteria)
Tests exist for validation
Work is repetitive (many similar tasks)
You want to "set and forget"

Choose manual mode when:

Exploring new architecture
Making complex design decisions
Debugging tricky issues
Learning the codebase

Next Steps

Try a small increment first (5 tasks max)

/sw:increment "Add user profile page with avatar upload"
/sw:auto

Monitor the first session (watch the labels, check logs)
Review results (check code quality, test coverage, docs)
Scale up gradually (10 tasks → 25 tasks → multiple increments)
Join the community (Discord) and share your autonomous execution stories!

Quick Start​

What is Auto Mode?​

NEW in v2.9: Label Visibility​

During Execution​

On Completion​

How It Works​

The Execution Loop​

Key Mechanisms​

Stop Conditions​

✅ Success Conditions​

🛑 Stop Conditions​

⏸️ Pause Conditions​

Advanced Usage​

Check Progress​

Emergency Stop​

TDD Strict Mode​

Configuration Options​

Session Limits​

Circuit Breakers​

Best Practices​

✅ DO​

❌ DON'T​

Real-World Examples​

Example 1: Mobile App Generation (2-3 hours)​

Example 2: Microservices Coordination​

Example 3: Documentation Generation​

Troubleshooting​

"Session keeps retrying same failure"​

"Auto mode stopped early"​

"Tests not running"​

"Circuit breaker triggered"​

Monitoring & Logs​

Log Files​

Session State File​

Comparison: Auto vs Manual​

Next Steps​

See Also​

Quick Start

What is Auto Mode?

NEW in v2.9: Label Visibility

During Execution

On Completion

How It Works

The Execution Loop

Key Mechanisms

Stop Conditions

✅ Success Conditions

🛑 Stop Conditions

⏸️ Pause Conditions

Advanced Usage

Check Progress

Emergency Stop

TDD Strict Mode

Configuration Options

Session Limits

Circuit Breakers

Best Practices

✅ DO

❌ DON'T

Real-World Examples

Example 1: Mobile App Generation (2-3 hours)

Example 2: Microservices Coordination

Example 3: Documentation Generation

Troubleshooting

"Session keeps retrying same failure"

"Auto mode stopped early"

"Tests not running"

"Circuit breaker triggered"

Monitoring & Logs

Log Files

Session State File

Comparison: Auto vs Manual

Next Steps

See Also