Auto Command

Project Overrides

!s="auto"; for d in .specweave/skill-memories .claude/skill-memories "$HOME/.claude/skill-memories"; do p="$d/$s.md"; [ -f "$p" ] && awk '/^## Learnings$/{ok=1;next}/^## /{ok=0}ok' "$p" && break; done 2>/dev/null; true

Project Context

!.specweave/scripts/skill-context.sh auto 2>/dev/null; true

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	Minimal context mode	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

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

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

{
  "active": true,
  "timestamp": "<ISO>",
  "incrementIds": ["0001-feature"],
  "tddMode": false,
  "requireTests": false,
  "userGoal": null,
  "successCriteria": [
    { "type": "tasks_complete", "description": "All tasks marked complete", "required": true },
    { "type": "acs_satisfied", "description": "All ACs satisfied", "required": true }
  ],
  "successSummary": "All tasks and acceptance criteria complete"
}

Map flags to extra successCriteria entries:

• --tests -> { "type": "tests_pass", "required": true }
• --build -> { "type": "build_succeeds", "required": true }
• --e2e -> { "type": "tests_pass", "description": "E2E tests", "required": true }
• --lint -> { "type": "custom_command", "command": "<lint-cmd>", "required": true }
• --types -> { "type": "custom_command", "command": "npx tsc --noEmit", "required": true }
• --cov N -> { "type": "tests_pass", "threshold": N, "required": true }
• --cmd "X" -> { "type": "custom_command", "command": "X", "required": true }
• --tdd -> set "tddMode": true

Always include tasks_complete and acs_satisfied as base criteria. Ensure .specweave/state/ dir exists.

userGoal field: Set to the user's stated intent from conversation context. If the user said "fix the auth bug", set userGoal to "fix the auth bug". If no clear intent is expressed, set to null. This field is read by the stop hook to provide context-aware feedback and guide /sw:do to the correct increment.

Step 1.5a: MANDATORY - Complexity Check for Team-Lead Routing

Before starting autonomous execution, check if this increment needs team-lead:

1. Count pending tasks in tasks.md (count [ ] markers)

2. Detect domains from file paths in tasks.md and plan.md:

   • Frontend: .tsx, src/components/, src/pages/, React/Vue keywords
   • Backend: src/api/, src/services/, src/routes/, Express/NestJS keywords
   • Database: prisma/, migrations/, SQL keywords
   • DevOps: Dockerfile, .github/, k8s/ keywords
   • Testing: tests/, e2e/, .test. keywords
   • Security: src/auth/, auth keywords
   • Mobile: ios/, android/, React Native keywords

3. If 3+ domains detected OR domain count suggests multi-agent benefit:

   ⚠️  COMPLEXITY ASSESSMENT
   ══════════════════════════════════════════
   Tasks: [N] pending | Domains: [N] ([list])
   ──────────────────────────────────────────
   This increment spans 3+ domains. /sw:team-lead is recommended
   for parallel execution with higher quality results.
   ⚡ Trade-off: ~2-3x more tokens, but parallel agents
      produce better results for multi-domain work.
   ══════════════════════════════════════════

   Then use AskUserQuestion:

   • Option A: "Use /sw:team-lead (Recommended)" — invoke team-lead and stop auto
   • Option B: "Continue with /sw:auto (sequential)" — proceed normally

   In auto mode (no user present): Auto-invoke /sw:team-lead for 3+ domains.
   This is the default behavior per CLAUDE.md execution strategy.

Step 1.5: MANDATORY - Display Stop Conditions

You MUST output a stop conditions banner BEFORE starting work. Detect test frameworks, count test files, then show:

AUTO MODE STARTING
======================================================================
Increment: [ID] | Tasks: [N] pending
======================================================================
TESTS THAT MUST PASS:
  Unit: [command] - [N] test files ([list key ones])
  E2E: [command] - [N] test files (if applicable)
  [NEW] files to be created during auto mode
======================================================================
COMPLETES WHEN: All tasks done + tests pass + /sw:done passes
STOPS IF: 3 consecutive test failures | /sw:cancel-auto | max turns
======================================================================

Fill ALL placeholders with real values. Be specific about test files and commands.

Step 1.6: TDD Enforcement (if TDD mode enabled)

Check TDD priority: --tdd flag > increment metadata.json > config.json

If TDD enabled, validate tasks.md has [RED]/[GREEN]/[REFACTOR] markers. If no markers found:

• strict: BLOCK — cannot proceed, fix tasks first
• warn: show warning, continue without enforcement
• off: skip silently

Enforcement rules: [RED] tasks complete freely. [GREEN] requires its [RED] done first. [REFACTOR] requires its [GREEN] done first.

Step 2: Intelligent Increment Creation (when none found)

Analyze context and decide:

• Match existing: find planned/backlog increment matching user intent, activate it
• Extend existing: add tasks to active incomplete increment
• Create new: invoke /sw:increment "description" then set up session
• Multiple: activate all matching, include in session marker
• Ambiguous: ask user to choose

Then return to Step 1c-1d to set up the session, then Step 1.5 for the banner.

Step 3: Execute Tasks

1. Run /sw:do in a loop (stop hook handles continuation)
2. Mark tasks complete in tasks.md, update spec.md ACs
3. Run tests after each task
4. Before /sw:done: verify all quality gates from successCriteria
5. Closure: When all tasks are complete (stop hook blocks with all_complete_needs_closure), run /sw:done --auto <id> for each increment in the session
6. On success: If /sw:done succeeds, clean up session state (rm -f auto-mode.json, turn counter, dedup files) and output <!-- auto-complete:DONE -->
7. On failure: If /sw:done fails (gate failure), report the failure and do NOT clean up session state. The stop hook will block again on the next turn for a retry.

Credential Auto-Execution

In auto mode, execute deployment commands directly using available credentials. Check .env, env vars, CLI auth (wrangler whoami, gh auth status). If credentials missing, ask user — never output manual steps.

Session Management

• Status: /sw:auto-status
• Cancel: /sw:cancel-auto
• Resume after crash: /sw:do or claude --continue
• Multi-agent: use /sw:team-lead instead

Safety

Mechanism	Default
Turn limit	20
Staleness cleanup	2h
Human gates	deploy, migrate, publish patterns

Related Commands

Command	Purpose
/sw:auto-status	Check session status
/sw:cancel-auto	Cancel session
/sw:do	Execute tasks (standalone)
/sw:progress	Show progress
/sw:team-lead	Multi-agent orchestration