/auto

description: Start autonomous execution with stop hook feedback loop. Works until all tasks complete or max iterations reached. Use when you want continuous unattended execution.
version: 1.0.0
argument-hint: "[INCREMENT_IDS...] [OPTIONS]"

Auto Command

Project Overrides

**Skill Memories**: If `.specweave/skill-memories/auto.md` exists, read and apply its learnings.

Project Context

**Project Context**: If `.specweave/config.json` exists, read it for testing mode, TDD enforcement, and multi-project settings. Check for active increments in `.specweave/increments/*/metadata.json`.

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

Usage

sw:auto [INCREMENT_IDS...] [OPTIONS]

• `INCREMENT_IDS`: One or more increment IDs (e.g., `0001`, `0001-feature`). If omitted, finds active increments or intelligently creates new ones.

Options

| Option | Description | Default | |--------|-------------|---------| | `--max-turns N` | Max hook invocations before hard stop | 20 | | `--simple-compat` | **Deprecated**. Equivalent to the legacy `--simple` flag. Emits a deprecation warning and will be removed in v1.3.0. | false | | `--dry-run` | Preview without starting | false | | `--all-backlog` | Process all backlog items | false | | `--skip-gates G1,G2` | Pre-approve specific gates | None | | `--no-increment` | Require existing increments (no auto-creation) | false | | `--yes`, `-y` | Auto-approve increment plan | false | | `--tdd`, `--strict` | TDD strict mode (RED->GREEN->REFACTOR enforced) | false | | `--build` | Build must pass before completion | false | | `--tests` | Tests must pass before completion | false | | `--e2e` | E2E tests must pass before completion | false | | `--lint` | Linting must pass before completion | false | | `--types` | Type-checking must pass before completion | false | | `--cov <n>` | Code coverage threshold (%) | 80 | | `--cmd "<command>"` | Custom command must pass | None |

Context-Adaptive Execution (default)

`sw:auto` no longer exposes `--simple` as a primary execution path. Every session uses context-adaptive execution:

• On large specs (>40KB), `sw:auto` **automatically reduces context re-reads internally** — no manual `--simple` flag needed. Specs are read once at session start; subsequent iterations rely on `tasks.md` plus diffs.
• On smaller specs, spec re-reads stay enabled for maximum coherence.
• Sub-skill loading is decided per-task based on domain signals, not by a global flag.

Legacy `--simple-compat` (deprecated)

The legacy `--simple` minimal-context mode is retained for one minor release as `--simple-compat`.

• Emits a deprecation warning on invocation.
• Will be removed in v1.3.0.
• Equivalent behaviour (for compatibility with external runbooks):

1. Skip spec re-reads — read `spec.md` once at session start, rely on `tasks.md` alone afterward. 2. Minimal task context — read only the current task's section from `tasks.md`. 3. No sub-skill loading — execute tasks directly using code tools. 4. Shorter status output — skip banners and progress tables between tasks. 5. No complexity re-check — skip Step 1.5a (team-lead routing check).

New callers should rely on the context-adaptive default above instead.

Tool-Use Rationale

• **Read**: Load `.specweave/config.json`, `metadata.json`, `spec.md`, and `tasks.md` to drive the auto loop.
• **Write/Edit**: Update `auto-mode.json` session marker and flip task/AC status as work completes.
• **Glob**: Locate active/planned increments and test files during gate evaluation.
• **Bash**: Run the configured quality gates (tests, build, lint, types, custom commands).

Native Auto Mode

Claude Code ships with a built-in auto mode, toggled with **Shift+Tab**. That native mode runs the agent autonomously without any SpecWeave-specific orchestration.

**When to use `sw:auto` vs native auto**:

• Use **`sw:auto`** when you need increment-aware gates: spec validation, AC tracking, rubric evaluation, task-level test enforcement, or external sync to GitHub/Jira/ADO.
• Use **Claude Code native auto (Shift+Tab)** for general-purpose autonomous execution without increment tracking — e.g. quick refactors, research loops, exploration.

**One-time advisory**: When invoked in Claude Code, `sw:auto` prints a one-time advisory pointing to Shift+Tab for users who may not need increment gates. The advisory is suppressed after the first acknowledgement.

**Opt-out for power users**: Pass `--force-sw-auto` to suppress the advisory permanently.

Core Loop

IMPLEMENT task -> TEST -> FAIL? -> FIX -> PASS -> mark complete -> NEXT task -> ... -> ALL DONE -> sw:done --auto -> CLOSED

Stop hook blocks when tasks/ACs remain. When all work is complete, stop hook blocks with `all_complete_needs_closure` to trigger `sw:done --auto`. Model enforces quality gates (build/tests/lint) before closure.

Execution

Step 1: Set Up Auto Session

Use Read/Write/Edit/Glob tools directly (no CLI needed):

**1a. Read config** — `.specweave/config.json`: `auto.enabled`, `auto.maxTurns` (default 20), `testing.defaultTestMode`, `testing.tddEnforcement`

**1b. Find increments:**

• If IDs specified: Glob `.specweave/increments/{ID}*/metadata.json`, verify exists
• If no IDs: find active/in-progress increments. If none, check backlog/planned. If none at all, go to Step 2 (Intelligent Creation).

**1c. Activate increments** — Edit `metadata.json`: set `"status": "active"`, update timestamp

**1c.5. PR-Based Branch Setup (conditional):**

PUSH_STRATEGY=$(jq -r '.cicd.pushStrategy // "direct"' .specweave/config.json 2>/dev/null)

If `pr-based`: create/checkout feature branch before starting work (same logic as `sw:do` Step 2.5). Branch name: `{branchPrefix}{increment-id}`. If `direct`: skip.

**1d. Write session marker** — `.specweave/state/auto-mode.json`:

{
  "active": true,
  "timestamp": "<ISO>",
  "incrementIds": ["0001-feature"],
  "simple": false,
  "tddMod