Auto Mode

Fully autonomous development. Works through all tasks without stopping until complete.

Current State

!git status --short !node -e "try{const p=require('./prd.json');const sp=p.sprints?p.sprints[p.sprints.length-1]:p;const s=Object.values(sp.stories||p.stories||{});const name=sp.id||sp.name||p.sprint||'unknown';const done=s.filter(x=>x.passes===true).length;const pend=s.filter(x=>x.passes===null||x.passes===false).length;console.log('Sprint:',name,'| Done:',done,'| Pending:',pend,'| Total:',s.length)}catch(e){console.log('No prd.json')}"

Entry Flow

auto
  |-- Activate: write .claude/auto-active
  |-- Check prd.json exists?
  |   |-- No -> Bootstrap from context
  |   +-- Yes -> Check pending tasks
  |               |-- None pending -> IDLE Detection
  |               +-- Has pending -> Execute tasks
  |
  +-- Execute until done or interrupted
  +-- Deactivate: delete .claude/auto-active

Auto-Active Flag (Continuous Execution)

On start, create the flag file:

bash
echo '{"started":"'$(date -Iseconds)'","sprint":"current"}' > .claude/auto-active

PowerShell: @{started=(Get-Date -Format o)} | ConvertTo-Json > .claude/auto-active

This flag tells the Stop hook to block Claude from stopping. Claude keeps working as long as this flag exists.

On exit (user says "done", or nothing left), delete the flag:

bash
rm -f .claude/auto-active

Delete the flag when auto mode ends. If asking the user what's next (IDLE Detection), keep the flag active.

Autonomous Behavior

Do not ask "Should I continue?" or show summaries and wait.

Instead:

• Make autonomous decisions
• Log decisions to .claude/decisions.md
• Keep working until truly done
• The Stop hook prevents Claude from ending — trust it

Persist to prd.json

When findings, scan results, or ad-hoc issues are identified during execution, write them to prd.json as stories before fixing them. prd.json is the source of truth that survives session restarts and /compact.

Lightweight Mode

If the user gives a direct instruction (e.g., "fix this button", "update that copy") rather than saying "auto":

• Skip prd.json and sprint creation entirely
• Just fix, verify, done
• Use prd.json only when there are 5+ tasks to track

Bootstrap (No prd.json)

When prd.json does not exist:

1. Read CLAUDE.md, README.md, package.json for context
2. Generate 5-10 starter tasks based on project
3. Create prd.json with stories
4. Continue immediately — do not stop for approval

Pre-flight (Quick)

Before first task:

bash
git status --short
npm run build 2>&1 | tail -5

Skip if takes >10 seconds.

Task Execution

Find Next Task

javascript
// prd.json has two shapes:
// Flat:   { stories: { "S1-001": {...} }, sprint: "sprint-1" }
// Nested: { sprints: [{ id: "sprint-1", stories: { "S1-001": {...} } }] }
const sp = prd.sprints ? prd.sprints[prd.sprints.length - 1] : prd;
const stories = sp.stories || prd.stories || {};
const storyEntries = Object.entries(stories);
const executable = storyEntries.filter(([id, s]) =>
  s.passes !== true &&
  (s.blockedBy || []).every(dep => stories[dep]?.passes === true)
);

Execute Each Task

1. Read the task description
2. Context Loading — read 2-3 similar files to match existing patterns
3. Implement the solution
4. npm run typecheck — fix if fails
5. npm run build — fix if fails
6. Self-Verification (see below)
7. Update prd.json: passes: true
8. Start next task immediately

Context Loading (before writing any code)

1. Read 2-3 existing files most similar to what you're building
2. Identify patterns: naming conventions, import style, error handling, state management
3. Match patterns — do not introduce new patterns when existing ones cover the use case

Verification

| Task Type | Verification | |-----------|--------------| | UX/UI | agent-browser visual + console + network | | Feature | Build passes + browser devtools check | | API | Endpoint returns expected data + network check | | Bug fix | Reproduce, verify fixed, no new errors |

For UI/API tasks with a running dev server:

bash
agent-browser open http://localhost:3000/path
agent-browser snapshot -i
agent-browser errors
agent-browser network requests

Fix console errors or failed network requests before moving on.

Self-Verification (after each task)

Before marking any task as complete:

1. Type Safety

bash
npm run typecheck 2>/dev/null || npx tsc --noEmit 2>/dev/null

2. Tests

bash
npm test -- --passWithNoTests --watchAll=false 2>/dev/null

3. Self-Review Run git diff and check:

• No console.log or debugger left in
• No hardcoded colors (use design tokens)
• All UI states handled (loading, empty, error)
• No any types introduced
• No commented-out code

4. UI/API Change? Browser Verification If agent-browser is available and a dev server is running:

bash
agent-browser open http://localhost:3000/[page]
agent-browser screenshot .claude/screenshots/verify-$(date +%s).png
agent-browser snapshot -i
agent-browser errors
agent-browser network requests --filter api

5. Mark Complete Only after all checks pass. If any check fails, fix it first.

Parallel Execution (Optional)

For independent tasks, launch multiple agents:

Task({ subagent_type: "general-purpose", prompt: "...", run_in_background: true })

Smart Retry

On failure (maximum 2 retries, then move on):

1. Log to .claude/mistakes.md
2. Retry 1: Different approach
3. Retry 2: Simplest possible implementation
4. Still fails: set passes: false, continue to next task

Do not retry a third time. Do not spend more than 10 minutes on retries for a single task.

Commit Cadence

• Commit every 3 completed tasks
• Or after major milestones
• Use conventional commits: feat|fix|refactor

Token Management

After every 3 completed tasks, recommend /compact:

Checkpoint: 3 tasks complete. Run /compact to reclaim ~40% tokens.

Be concise. Short responses = more runway.

Completion

When all stories have passes === true:

All [N] tasks complete.

Summary:
- [X] features implemented
- [X] bugs fixed
- [X] improvements made

Run `progress` to see full results.

IDLE Detection (Smart Next Action)

If no tasks to work on:

1. Are all stories passes: true?

• No: find blocked tasks and resolve blockers
• Yes: continue to step 2

1. Output completion summary for current sprint
2. Assess context to decide next action:

Decision Matrix

| Signal | Action | |--------|--------| | TODOs/FIXMEs in code | Brainstorm (auto mode creates stories) | | Console.logs left in | Quick cleanup sprint | | No tests exist | Suggest test sprint | | Build warnings | Fix warnings sprint | | Clean codebase | Ask user (see below) |

Auto-Continue (Obvious Work)

If brainstorm scan finds 3+ actionable improvements, auto-create next sprint and continue:

Sprint [N] complete (8/8 tasks).
Scanning codebase... found 5 improvements.
Creating Sprint [N+1] and continuing.

Limit: 1 auto-generated sprint per session. After that, ask the user.

Ask User (No Obvious Work or Limit Reached)

Sprint [N] complete (8/8 tasks).

What's next? (Recommended: ship)
1. ship - Deploy current work
2. audit - Deep quality check
3. brainstorm - Find more improvements
4. Done for now

Use AskUserQuestion with these options. Pick recommendation based on context.

Keep .claude/auto-active flag while asking. Only delete it if user picks "Done for now".

Quick Reference

| Situation | Action | |-----------|--------| | No prd.json | Bootstrap from context | | All done + issues found | Brainstorm (auto-creates stories) | | All done + clean code | Ask user for next action | | All done + already auto-sprinted | Ask user (limit reached) | | Build broken | Fix first | | Task fails | Retry 2x, then skip | | UX task | Browser verify | | Blocked task | Skip, work on unblocked | | < 5 tasks, no sprint | Work directly |