Autonomous Execution

Start autonomous execution session using Claude Code's Stop Hook.

Auto mode enables continuous autonomous execution until all tasks are complete. It uses a stop hook feedback loop to keep Claude working until completion.

Usage

"Ship while I sleep"

Arguments

INCREMENT_IDS: One or more increment IDs to process (e.g., 0001, 0001-feature)
- If omitted, uses current in-progress increment

Options

Option	Description	Default
`--max-iterations N`	Maximum iterations before stopping	100
`--max-hours N`	Maximum hours to run	None
`--simple`	Simple mode (minimal context)	false
`--dry-run`	Preview without starting	false
`--all-backlog`	Process all backlog items	false
`--skip-gates G1,G2`	Pre-approve specific gates	None

How It Works

1. User starts autonomous execution
           |
           v
2. setup-auto.sh creates session state
   -- .specweave/state/auto-session.json
           |
           v
3. Claude starts working on tasks
   -- Execute tasks runs sequentially
           |
           v
4. Claude tries to exit (naturally)
           |
           v
5. Stop Hook intercepts (stop-auto.sh)
   |- Checks: All tasks complete?
   |- Checks: Max iterations reached?
   |- Checks: Completion promise?
   \- Checks: Human gate pending?
           |
   +------+------+
   v             v
INCOMPLETE    COMPLETE
   |             |
   v             v
Block exit    Approve exit
Re-feed       Session ends
prompt

Examples

Basic Usage

"Run autonomously"

Additional variations:

# Multiple increments
sw:auto 0001 0002 0003

With Options

# Limit iterations
sw:auto --max-iterations 50

# Time limit
sw:auto --max-hours 8

# Simple mode (minimal context)
sw:auto --simple

# Preview only
sw:auto --dry-run

# All backlog items
sw:auto --all-backlog

Pre-approve Gates

# Skip deploy gate (pre-approved)
sw:auto --skip-gates deploy

# Multiple gates
sw:auto --skip-gates "deploy,migrate"

Session Management

Check Status

You can say "check auto status" or use the command:

"How's auto going?"

See: Auto Status Documentation

Cancel Session

You can say "stop auto" or use the command:

"Cancel autonomous"

See: Cancel Auto Documentation

Resume After Crash

Just say "continue working" or type sw:do -- it will detect incomplete tasks and continue.

Or use Claude Code's built-in:

/resume           # Pick session to resume
claude --continue # Continue last session

Configuration

In .specweave/config.json:

{
  "auto": {
    "enabled": true,
    "maxIterations": 100,
    "maxHours": 24,
    "testCommand": "npm test",
    "coverageThreshold": 80,
    "enforceTestFirst": false,
    "humanGated": {
      "patterns": ["deploy", "migrate", "publish"],
      "timeout": 1800
    }
  }
}

Completion Signals

The session ends when ANY of these occur:

Signal	Description
All tasks complete	tasks.md has all `[x]` checkboxes
Completion promise	Output contains `<!-- auto-complete:DONE -->` (hidden HTML comment)
Max iterations	Reached configured limit (default: 100)
Max hours	Time limit exceeded
User cancellation	User cancels the session (or types `sw:cancel-auto` in Claude Code)
Human gate timeout	Gate pending too long
Low confidence score	Self-assessment score < 0.50

Simple Mode (--simple)

Pure stop hook loop behavior:

Minimal context in re-feed prompt
No session state UI
No queue management
Just: loop + tasks.md completion + max iterations

sw:auto --simple

Safety Features

Feature	Description
Human Gates	Sensitive operations (deploy, publish, force-push) require approval
Circuit Breakers	External service failures (GitHub/JIRA/ADO) handled gracefully
Max Iterations	Prevents runaway loops (default: 100)
Max Hours	Optional time boxing
stop_hook_active	Prevents infinite continuation loops
Self-Assessment	Scores below 0.50 pause for human review
Test Failures	Multiple failures (>3) pause for review
Credential Errors	Repeated deployment errors pause for credential check

Self-Assessment Scoring

Auto mode uses self-assessment scoring to guide continuation decisions.

Confidence Scoring

After each task, Claude self-assesses execution quality:

{
  "iteration": 5,
  "task": "T-003",
  "confidence": {
    "execution_quality": 0.92,
    "test_coverage": 0.85,
    "spec_alignment": 0.95,
    "credential_success": 1.0,
    "overall": 0.93
  }
}

Score Thresholds

Overall Score	Action
>= 0.90	Continue confidently
0.70-0.89	Continue with caution, log concerns
0.50-0.69	Pause for self-review before continuing
< 0.50	Stop and request human review

Test Execution Integration

Auto mode runs tests after completing testable tasks in a self-healing loop:

+-------------------------------------------------------------+
| IMPLEMENT -> TEST -> FAIL? -> FIX -> TEST -> PASS -> NEXT   |
|                     ^________________|                       |
|                    (max 3 iterations)                        |
+-------------------------------------------------------------+

Mandatory Test Reporting after every task:

## Test Status Report (after T-003)

| Type | Status | Pass/Total | Coverage |
|------|--------|------------|----------|
| Unit | pass | 42/42 | 87% |
| Integration | pass | 12/12 | - |
| E2E | warn | 8/10 | - |

Auto-Execute Rules

In auto mode, all agents MUST follow auto-execute rules:

FORBIDDEN: "Next Steps: Run wrangler deploy"
FORBIDDEN: "Execute the schema in Supabase SQL Editor"

REQUIRED: Execute commands DIRECTLY using available credentials

Credential Lookup Order

.env file - Primary credential storage
Environment variables - Already loaded in session
CLI tool auth - wrangler whoami, gh auth status, etc.
Config files - wrangler.toml, .specweave/config.json

If credentials found -> AUTO-EXECUTE If credentials missing -> ASK (don't show manual steps)

Human-Gated Operations

These operations require manual approval even in auto mode:

npm publish, git push --force, rm -rf /
Any production deployment
API key or credential changes
Database migrations (drop, delete from, migrate)

Session State

Session state is stored in .specweave/state/auto-session.json:

{
  "sessionId": "auto-2025-12-29-abc123",
  "status": "running",
  "startTime": "2025-12-29T10:00:00Z",
  "iteration": 47,
  "maxIterations": 100,
  "incrementQueue": ["0001-user-auth", "0002-payment"],
  "currentIncrement": "0001-user-auth",
  "completedIncrements": [],
  "simple": false
}

For Non-Claude AI Systems

If using SpecWeave with other AI systems (GPT, Gemini, etc.), implement this loop pattern:

# Bash loop for autonomous execution
while true; do
    # Check if all tasks complete
    TOTAL=$(grep -c "^### T-" .specweave/increments/*/tasks.md 2>/dev/null || echo "0")
    DONE=$(grep -c '\[x\].*completed' .specweave/increments/*/tasks.md 2>/dev/null || echo "0")

    if [ "$TOTAL" -gt 0 ] && [ "$DONE" -ge "$TOTAL" ]; then
        echo "All tasks complete!"
        break
    fi

    # Feed prompt to your AI
    cat PROMPT.md | your-ai-cli

    # Safety: max iterations
    ITER=$((ITER + 1))
    if [ "$ITER" -ge 100 ]; then
        echo "Max iterations reached"
        break
    fi
done

Natural Language	Claude Code	Other AI Tools	Purpose
"Check auto status"	`sw:auto-status`	`auto-status`	Check session status
"Stop auto"	`sw:cancel-auto`	`cancel-auto`	Cancel running session
"Start implementing"	`sw:do`	`do`	Execute tasks (also works standalone)
"What's the status?"	`sw:progress`	`progress`	Show increment progress

Usage​

Arguments​

Options​

How It Works​

Examples​

Basic Usage​

With Options​

Pre-approve Gates​

Session Management​

Check Status​

Cancel Session​

Resume After Crash​

Configuration​

Completion Signals​

Simple Mode (--simple)​

Safety Features​

Self-Assessment Scoring​

Confidence Scoring​

Score Thresholds​

Test Execution Integration​

Auto-Execute Rules​

Credential Lookup Order​

Human-Gated Operations​

Session State​

For Non-Claude AI Systems​

Related Commands​

See Also​