fh:auto

Run fully autonomous multi-phase execution. Plans, reviews, builds, and reviews each phase without human intervention.

What to run autonomously: $ARGUMENTS

---

Architecture: 2-Layer Direct Dispatch

The auto-orchestrator uses a 2-layer architecture:

• Layer 1: Orchestrator (auto-orchestrator.cjs) — state machine managing phase lifecycle, spawning task sessions, handling retries and checkpoints
• Layer 2: Task sessions (claude -p per task) — individual task execution with injected plan context

For the build step, the orchestrator dispatches tasks directly via claude -p instead of invoking /fh:build. This eliminates the 3rd nesting layer.

Interactive builds still use /fh:build with Agent tool dispatch.

Fallback

Plans that can't be parsed for direct dispatch (missing XML tasks) fall back to /fh:build invocation.

State Machine

Phase lifecycle: pending → planning → planned → reviewing → reviewed → building → verifying → complete Task lifecycle: queued → dispatched → running → completed|failed|timed-out

Failed phases retry automatically (max 2 attempts). Timed-out tasks retry with extended timeout.

Shared Library

Reusable modules at .claude/skills/auto/lib/:

• task-dispatch.cjs — per-task claude -p spawning with process group kill
• context-injection.cjs — build task prompts from plan context
• wave-analysis.cjs — parse PLAN.md into ordered wave groups
• verification.cjs — run verification commands
• summary-generation.cjs — generate SUMMARY.md content

---

Walk-Away Guide

/fh:auto plans, reviews, builds, and reviews each phase without human intervention.

Prerequisites: .planning/ directory with PROJECT.md, ROADMAP.md, STATE.md (created by /fh:new-project).

Quick start:

1. Describe your project → run /fh:new-project → run /fh:auto
2. Or from scratch: /fh:auto "build a SaaS for X" (runs new-project first, then executes)

What happens: Each phase gets a plan, plan-review, build, and quick-review — all autonomous. Decisions are logged to .planning/DECISIONS.md with confidence levels.

Monitor progress:

• Live dashboard: http://127.0.0.1:4111 (auto-started if tracker is installed)
• State file: .auto-state.json in project root (phase-by-phase status)
• Stdout: real-time logs with per-phase cost and timing

Resume after interruption: /fh:auto --resume — picks up exactly where it stopped.

Review when done:

• .planning/DECISIONS.md — check entries marked LOW confidence or ⚠ NEEDS REVIEW
• .planning/phases/*/SUMMARY.md — per-phase execution reports
• Run /fh:auto --check-corrections after correcting any decisions

---

Step 0: Tool Readiness

claude-mem tools are deferred — they must be fetched before they can be called. Do this first, before any other work.

ToolSearch("+mcp-search", max_results: 10)

Also verify ast-grep CLI is available:

command -v sg &>/dev/null || command -v ast-grep &>/dev/null || echo "WARN: ast-grep not found"

These tools are used by downstream skills (plan-work, build, review) in their own sessions — no need to pass them forward.

If ToolSearch returns empty for claude-mem: Fall back to Read-based approach for this session.

---

Step 1: Validate Prerequisites

Check that the project is set up for autonomous execution:

1. .planning/PROJECT.md exists — if missing, check for startup artifacts first:
   • If .planning/startup/ exists: "Found startup validation artifacts but no project setup. Run /fh:new-project to create the project — it will auto-populate from your startup data." Stop.
   • If no .planning/ at all: "No project found. Consider running /fh:startup-design first to validate your idea, then /fh:new-project to set up the project. Or run /fh:new-project directly if you're ready to build. Or provide a project description: /fh:auto 'build a task management app with teams and real-time updates'" Stop.
2. .planning/ROADMAP.md exists — if missing: "No roadmap found. Run /fh:new-project to generate a roadmap." Stop.
3. .planning/STATE.md exists — if missing: "No state tracking found. Run /fh:new-project to initialize state." Stop.

Read STATE.md and ROADMAP.md to determine current position, total phases, and which phases are incomplete.

---

Step 1.5: Tracker Registration

Register the current project with the live dashboard and surface the URL if it's running.

# Ensure tracker directory exists
mkdir -p "$HOME/.claude/tracker"

# Register project in global registry
node -e "
const fs = require('fs');
const path = require('path');
const registryPath = path.join(process.env.HOME, '.claude', 'tracker', 'projects.json');
let registry = [];
try { const d = JSON.parse(fs.readFileSync(registryPath, 'utf8')); if (Array.isArray(d)) registry = d; } catch {}
const projectDir = process.cwd();
const now = new Date().toISOString();
const idx = registry.findIndex(e => e.path === projectDir);
const conductorMatch = projectDir.match(/\/conductor\/workspaces\/([^/]+)\//);
const entry = { path: projectDir, name: path.basename(projectDir), addedAt: now, lastSeen: now };
if (conductorMatch) entry.conductorWorkspace = conductorMatch[1];
if (idx >= 0) { Object.assign(registry[idx], { lastSeen: now, ...(conductorMatch ? { conductorWorkspace: conductorMatch[1] } : {}) }); } else { registry.push(entry); }
fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2));
"

Then check if the live dashboard is running:

# Attempt HTTP GET to tracker API with 2s timeout
node -e "
const http = require('http');
const projectDir = process.cwd();
const projectName = require('path').basename(projectDir);
const req = http.get('http://127.0.0.1:4111/api/state', { timeout: 2000 }, (res) => {
  if (res.statusCode === 200) {
    // Dashboard is running — register this project
    const postData = JSON.stringify({ path: projectDir, name: projectName });
    const postReq = http.request({
      hostname: 'localhost',
      port: 4111,
      path: '/api/register',
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(postData) }
    }, () => {});
    postReq.on('error', () => {});
    postReq.write(postData);
    postReq.end();
    console.log('TRACKER_RUNNING');
  } else {
    console.log('TRACKER_NOT_RUNNING');
  }
});
req.on('error', () => console.log('TRACKER_NOT_RUNNING'));
req.on('timeout', () => { req.destroy(); console.log('TRACKER_NOT_RUNNING'); });
" 2>/dev/null

• If output is TRACKER_RUNNING: print Live dashboard running at http://127.0.0.1:4111 — open it to watch progress
• If output is TRACKER_NOT_RUNNING: check if tracker files exist and auto-start:

[ -f "$HOME/.claude/tracker/server.cjs" ] && echo "TRACKER_FILES_EXIST" || echo "TRACKER_NO_FILES"

• If TRACKER_FILES_EXIST: kill any stale process and start the server:

  lsof -ti :4111 -s TCP:LISTEN | xargs kill 2>/dev/null; echo "port cleared"
  

  Then start the server with run_in_background: true:

  TRACKER_REGISTRY=~/.claude/tracker/projects.json node ~/.claude/tracker/server.cjs
  

  Print Live dashboard started at http://127.0.0.1:4111 — open it to watch progress

• If TRACKER_NO_FILES: print Tip: Run \/fh:tracker` to set up the live dashboard`

This step always succeeds — tracker errors are non-fatal.

---

Step 2: Strategic Requirements Workshop

Before autonomous execution, engage the user as a strategic advisor to shape and validate the project vision. This step ensures the autonomous pipeline builds the RIGHT thing, not just builds things.

Skip conditions — but always do minimal research (Step 2.1b):

• --skip-workshop or --resume flag is set
• User says "just go", "proceed", "start building", or similar
• All three conditions met: PROJECT.md has clear vision with north star, REQUIREMENTS.md has exhaustive requirements, ROADMAP.md has well-formed phases with no gaps

Even when skipping the full workshop, ALWAYS run Step 2.1b (Quick Sanity Check) below. The only exception is --resume, which skips everything.

2.1: Load Existing Context

Read existing planning artifacts to understand what's already defined:

• .planning/PROJECT.md — vision, goals, differentiation
• .planning/REQUIREMENTS.md — requirements and success criteria
• .planning/ROADMAP.md — phases and scope
• .planning/DESIGN.md — brand/design context (from /fh:ui-branding)
• .planning/research/ — existing research (FEATURES.md, PITFALLS.md, STACK.md, ARCHITECTURE.md, SUMMARY.md from /fh:new-project)
• .planning/startup/ — startup validation artifacts (from /fh:startup-design). If present, pre-index all startup artifacts alongside planning files. Market data, competitors, positioning, and financial projections should inform every phase's planning context.

If DESIGN.md exists, use it throughout to ground UX/UI guidance in the project's actual brand direction — color palette, typography, component patterns, design language, tone. When suggesting UX patterns, frame them in the project's design context: "Your brand is {tone} — for that, the proven pattern is {X}" rather than generic advice.

claude-mem observations persist across sequential claude -p sessions. No explicit pre-indexing needed.

Pattern A (Past Learnings Check): Derive project name consistently:

PROJECT_NAME=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || basename "$(pwd)")

Use $PROJECT_NAME as the project parameter for all claude-mem calls.

Call mcp__plugin_claude-mem_mcp-search__search with query=2-3 keywords from the project domain, project=, limit=10. Scan the returned index for relevant IDs — prioritize types: gotcha, decision, trade-off. For the top 2-3 relevant IDs, call mcp__plugin_claude-mem_mcp-search__get_observations with ids=[ID1, ID2, ID3] to fetch full details. If temporal context would help, call mcp__plugin_claude-mem_mcp-search__timeline with query=project domain keywords, depth_before=3. Present as: "From prior sessions: - {full observation detail}" — max 3 items. Max 3 items. Skip silently if no relevant results.

Identify what's well-defined vs what has gaps: missing vision, vague success criteria, no differentiation story, unclear scope ambition, missing UX/domain research, missing design context.

2.1b: Quick Sanity Check (always runs, even when workshop is skipped)

This step runs even when the full workshop is skipped. It takes <30 seconds and prevents the pipeline from building on a shaky foundation:

1. Read PROJECT.md, REQUIREMENTS.md, ROADMAP.md — confirm they exist and are non-trivial (>3 lines each)
2. Flag critical gaps silently — if any of these are missing or empty, warn the user: "I'm skipping the workshop as requested, but I noticed [gap]. The pipeline may produce suboptimal results."
3. Quick domain check (Pattern A) — derive project name consistently:

   PROJECT_NAME=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || basename "$(pwd)")
   

   Use $PROJECT_NAME as the project parameter for all claude-mem calls. Call mcp__plugin_claude-mem_mcp-search__search with query=2-3 project keywords, project=, limit=10. Scan the returned index for relevant IDs — prioritize types: gotcha, decision. For the top 2-3 relevant IDs, call mcp__plugin_claude-mem_mcp-search__get_observations with ids=[ID1, ID2, ID3] to fetch full details. Surface any relevant prior learnings that might affect the build. Skip silently if no relevant results.
4. Validate phase readiness — check that at least the first incomplete phase has a clear goal in ROADMAP.md. If the goal is vague (e.g., "improve things"), warn: "Phase N goal is vague — the planning step may struggle. Consider clarifying before proceeding."

This step NEVER blocks execution. It only warns. The user already said "go" — respect that while providing visibility.

2.2: Domain Research

Do research BEFORE engaging the user. Informed questions beat open questions.

For domain assessment, follow the FPF-lite research protocol at .claude/skills/plan-work/references/research-protocol.md when available. For high-complexity projects, present hypothesis diversity: conservative vs ambitious approaches. Tag findings with epistemic markers (CONFIRMED/LIKELY/SPECULATIVE) for downstream planning.

Use firecrawl for web research (see @.claude/skills/shared/firecrawl-guide.md for content-type patterns). Fallback: WebSearch, then WebFetch.

Content-type routing:

• Competitor websites/products → firecrawl_scrape with only_main_content: true

• Industry news/trends → firecrawl_search with sourceType: "news"

• GitHub repos/discussions → firecrawl_search with category: "github"

• Video content → firecrawl_scrape with formats: ["markdown"] for transcripts

• General research → firecrawl_search for discovery, firecrawl_scrape for deep reads

• Competitor analysis: Search for similar tools/products. What do they do well? Where do users complain? What's missing from the market?

• Community pain points: Search forums, GitHub issues, Reddit, HN for discussions about problems in this domain. What do people struggle with? What do they wish existed?

• Domain landscape: What's the state of the art? What approaches have been tried? What failed and why?

• User sentiment: What do users of competing/similar tools actually say? Common frustrations, feature requests, praise?

• UX/UI best practices: Research established UX patterns for the target user type and product category. For a SaaS product: onboarding flows, pricing pages, dashboard layouts, settings organization, notification patterns. For a CLI tool: DX patterns. For a mobile app: platform conventions. Identify what "good" looks like in this category.

• Established domain patterns: What are the proven patterns for this type of product? What do best-in-class products do that users take for granted? These become the baseline — table stakes the project should match before trying to differentiate.

If .planning/research/ already has research files, use those findings as the base. Only research gaps not already covered.

Present a brief research summary to the user: "Here's what I found about the landscape..." (3-5 key findings, competitors, pain points, established patterns). This grounds the conversation.

2.3: Strategic Conversation

Engage as a VC evaluating a startup pitch. Use research findings to drive concrete, informed discussions — not abstract open questions.

Research-driven questions:

• "Competitor X does {thing} — are you doing it better, differently, or not at all? Why?"
• "Users of {similar tool} consistently complain about {pain point} — is solving that part of your vision?"
• "The community is moving toward {trend} — does your roadmap account for that?"
• "Nobody in this space does {gap} — is that your moat?"
• "Here's what kills projects like this: {common failure mode}. How are you avoiding it?"

Ambitious thinking (push for scope expansion):

• "What's the north star? What does wild success look like in 6 months?"
• "If you could only ship ONE thing, what would make users tell their friends?"
• "What would make this a 10x solution, not a 1x?"
• "What are you afraid you're not thinking about?"

Concrete directions based on research:

• "Based on {finding}, you might want to consider {suggestion}"
• "Three directions this could go: (a) {option based on research}, (b) {option}, (c) {option} — which resonates?"
• "The biggest opportunity I see from the research is {X} — want to explore that?"

UX/UI and domain guidance (use research + DESIGN.md):

• If DESIGN.md exists: "Your design language is {tone/style} — for that brand, the proven {category} pattern is {X}. Does that fit your vision?"
• "For {product type}, the established pattern is {pattern} — are you following that or deliberately breaking from it?"
• "Best-in-class {category} products all have {feature} — that's table stakes, not differentiation"
• "Your target users ({user type}) expect {UX pattern} — have you accounted for that?"
• "Here are the proven patterns for {domain}: {list}. Which are you adopting, and where are you innovating?"
• If DESIGN.md is missing and the project has UI: suggest running /fh:ui-branding first, or help capture basic brand direction during the workshop.

Strategic stress-testing (borrow from plan-work and plan-review):

• "What big architectural bets are you making? What if they're wrong?"
• "What kills this project? What makes users leave?"
• "What would make this category-defining?"

Challenge safe/obvious answers. Push toward differentiation and ambition. Help users think bigger by offering concrete directions grounded in evidence.

2.4: Capture and Update

Update planning artifacts with the refined vision:

• Update PROJECT.md with clarified vision, north star, differentiation
• Update REQUIREMENTS.md with discovered requirements
• Optionally update ROADMAP.md if scope changed significantly

2.5: Confirm and Proceed

Get explicit approval: "Your vision is captured and the planning artifacts are updated. Ready to start autonomous execution?"

Only proceed to the orchestrator (Step 6) after the user confirms. If the user wants to iterate, return to 2.3.

---

Step 3: Parse Arguments

Parse $ARGUMENTS for flags:

Flag	Behavior
--resume	Resume from last crash/stop point. Read STATE.md for the last completed step and continue from there.
--phase N	Run only phase N (skip all others).
--dry-run	Show what would run without executing. See Step 4.
--budget N	Set cost ceiling in dollars. Passed to the orchestrator as --budget N.
--check-corrections	Run decision correction cascade instead of normal execution. See Step 8.
--skip-workshop	Skip the Strategic Requirements Workshop (Step 2) and go straight to execution.
--concurrency N	Max parallel claude -p sessions (default 2, max 4). Higher values increase throughput but also API cost.
--no-speculative	Disable speculative planning pipeline — fall back to fully sequential execution identical to pre-parallel behavior. Use if parallel mode causes issues.
(no flags)	Run all incomplete phases from current position in STATE.md.

Determine START_PHASE and END_PHASE:

• --phase N: both are N
• --resume: START_PHASE = phase from STATE.md's last position, END_PHASE = last phase in ROADMAP
• Default: START_PHASE = first incomplete phase, END_PHASE = last phase in ROADMAP

---

Step 4: Dry-Run Mode

If --dry-run is set:

1. Read ROADMAP.md and STATE.md
2. List each phase that would execute (from START_PHASE to END_PHASE, skipping completed phases)
3. Show the pipeline structure:

   Phase range: 4–7 (4 phases)
   Dependency analysis: (computed after planning wave)
   
   Pipeline plan:
     Wave 1 (planning): Phase 4, Phase 5, Phase 6, Phase 7 [concurrent, max 2]
     Wave 2 (review):   Phase 4, Phase 5, Phase 6, Phase 7 [concurrent, max 2]
     Wave 3 (build):    dependency-ordered (computed from plan files_modified)
     Quick reviews:     batched every 3 phases
   
   Note: Actual build order depends on file overlap between plans.
   Use --no-speculative for guaranteed sequential execution.
   

4. Report total phases to execute and exit. Do not set AUTO_MODE or invoke the orchestrator.

---

Step 5: Set AUTO_MODE

Enable autonomous advance so downstream skills (build, plan-work) make decisions without stopping:

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow.auto_advance true

Confirm the config was set successfully before proceeding.

---

Step 6: Shell Out to Orchestrator

FHHS_SKILLS_ROOT is set by /fh:setup and refreshed by /fh:update. Use it directly — no discovery needed:

# Resolve ORCHESTRATOR path with fallback discovery
ORCHESTRATOR=""
if [ -n "$FHHS_SKILLS_ROOT" ] && [ -f "$FHHS_SKILLS_ROOT/.claude/skills/auto/auto-orchestrator.cjs" ]; then
  ORCHESTRATOR="$FHHS_SKILLS_ROOT/.claude/skills/auto/auto-orchestrator.cjs"
else
  # FHHS_SKILLS_ROOT is unset or stale — search for latest installed version
  LATEST=$(ls -d "$HOME/.claude/plugins/cache/fhhs-skills/fh/"*/ 2>/dev/null | sort -V | tail -1)
  if [ -n "$LATEST" ] && [ -f "${LATEST}.claude/skills/auto/auto-orchestrator.cjs" ]; then
    ORCHESTRATOR="${LATEST}.claude/skills/auto/auto-orchestrator.cjs"
    echo "Note: FHHS_SKILLS_ROOT was stale — using latest installed version at $LATEST"
    echo "Run /fh:setup to fix FHHS_SKILLS_ROOT permanently."
  fi
fi

if [ -z "$ORCHESTRATOR" ]; then
  echo "FATAL: auto-orchestrator.cjs not found."
  echo "FHHS_SKILLS_ROOT=$FHHS_SKILLS_ROOT"
  echo "Run /fh:setup to reconfigure the plugin path."
  echo "STOP — do NOT proceed to execute phases manually. The orchestrator is required."
  exit 1
fi

node "$ORCHESTRATOR" \
  --project-dir "$(pwd)" \
  --start-phase "${START_PHASE}" \
  --end-phase "${END_PHASE}" \
  ${BUDGET:+--budget $BUDGET} \
  ${DRY_RUN:+--dry-run} \
  ${RESUME:+--resume}

CRITICAL: If the Bash command above fails (non-zero exit, or prints FATAL), STOP immediately. Do NOT attempt to run the phases manually or inline. The orchestrator is a required external process — the skill cannot substitute for it. Tell the user the exact error and suggest running /fh:setup.

The orchestrator runs phases using claude -p for fresh-context sessions. Each session receives:

• --plugin-dir pointing to the fh plugin root (so /fh: skills are available)
• --permission-mode bypassPermissions (non-interactive, no prompts)
• --append-system-prompt with CLAUDE.md content (project context)
• Testing enforcement: "Every phase build must include tests for business logic. Build Step 2.5 auto-generates test specs from plan must_haves. plan-work rejects plans without test coverage for business logic (check 7). UI phases should include E2E tests using Playwright. Coverage metrics are tracked in SUMMARY.md test_metrics field."
• A rich prompt with the phase goal and explicit autonomous instructions

Pipeline execution (default):
1. Pre-index shared docs (PROJECT, ROADMAP, research, codebase mapping)
2. Planning wave: all phases plan concurrently via ConcurrencyPool
   - Phase-local decisions (.decisions-pending.md), merged after wave
   - Dependency graph computed from plan frontmatter files_modified
3. Review wave: all plans reviewed concurrently
4. Build wave: phases built in dependency-wave order
   - Phases with no file overlap build concurrently within each wave
   - Phases with dependencies wait for predecessor waves to complete
   - Each build preceded by speculative plan validation (file overlap check)
   - Post-wave batched review for all phases built in that wave
     Test metrics:   coverage tracked per phase in SUMMARY.md test_metrics
5. Final review + state update

Sequential fallback (--no-speculative):
Per-phase loop (unchanged from pre-parallel behavior):
1. claude -p → PLAN.md
2. claude -p → HOLD review
3. claude -p → build
4. claude -p → quick review
5. Update STATE.md

Each step is a separate claude -p session with fresh context. The orchestrator handles crash recovery, state persistence to .planning/, and budget tracking.

Known pitfalls:

• claude -p does NOT support --cwd — use spawn cwd option only
• gsd-tools.cjs must resolve from $HOME/.claude/get-shit-done/bin/ (created by /fh:setup), never from projectDir
• Without --plugin-dir, /fh: skill commands are unavailable in -p sessions
• Without --permission-mode bypassPermissions, interactive prompts hang the process
• Bare skill invocations (e.g. /fh:plan-work) alone are insufficient — include phase goal and autonomy instructions
• Without CLAUDE_MEM_PROJECT env var, claude-mem stores observations under the plugin-dir project name instead of the actual project name, causing observation misattribution across projects
• Project name uses git rev-parse --git-common-dir (not --show-toplevel) to resolve actual repo name in Conductor worktrees (e.g., "fh-starter-project" not "havana")

Resilience features (built into orchestrator):

• Stuck detection: Sessions producing no output for 3min get warned, killed at 8min silence — prevents API stalls from running to the 45min hard timeout
• API health check: Before each session spawn, verifies claude --version responds. On failure, retries with exponential backoff (10s → 20s → 40s → 80s → 120s) up to 5 times before aborting with saved state
• API error classification: Distinguishes API/infra errors (connection refused, 502/503, rate limit) from logic errors. Orchestrator-initiated kills (stuck/timeout) are NOT classified as API errors — they skip health check backoff.
• Smart resume: --resume checks both .auto-state.json AND existing SUMMARY.md artifacts. If a phase has SUMMARY.md but the state file says incomplete (crashed between build and state update), skips ahead automatically.
• Error log persistence: On failure, writes {step}-error.log to the phase directory with full stdout/stderr tail for post-mortem analysis
• Partial SUMMARY: When a build session is killed (stuck/timeout), writes PARTIAL-SUMMARY.md with last output — preserves diagnostic context even for incomplete builds
• Decision context: Skip decisions include stdout tail (last 20 lines) in the context field, not just exit codes

Monitor the orchestrator's stdout for progress updates. If the orchestrator exits with a non-zero code, read its error output and report the failure point.

---

Parallelism Details

Dependency Graph

The orchestrator computes a dependency graph from plan frontmatter after the planning wave completes. Each PLAN.md may include a files_modified list. Two phases are considered dependent if their files_modified sets overlap — meaning they touch the same files and cannot safely build in parallel. Independent phases (no overlapping files) can build concurrently within the concurrency limit.

Speculative Plan Validation

Before each build session in the build wave, the orchestrator performs a file overlap check:

1. Compare the phase's planned files_modified against files already modified by earlier builds in the same wave.
2. If overlap is detected, trigger a validation session (claude -p) that re-evaluates the plan against the actual post-build state.
3. If the plan is still valid, proceed. If not, fall back to REPLAN: re-run the planning step for this phase before building.

Use --no-speculative to skip this check and always build in strict dependency order without validation sessions.

Phase-Local Decisions

During the concurrent planning wave, multiple sessions may attempt to update .planning/DECISIONS.md simultaneously, causing write races. To prevent this:

• Each planning session writes its decisions to .decisions-pending.md in the phase directory instead of the shared DECISIONS.md.
• After the planning wave completes, the orchestrator merges all .decisions-pending.md files into .planning/DECISIONS.md in a single serial step.
• This guarantees DECISIONS.md integrity without file locking.

Cross-Session Context

claude-mem observations persist across sequential claude -p sessions. No explicit pre-indexing needed — each session's key decisions and learnings are automatically available to subsequent sessions via claude-mem search.

Partial Failure Handling

If a phase fails during the build wave:

• Phases that depend on the failed phase (via the dependency graph) are rescheduled to sequential execution after the wave completes.
• Phases that are independent of the failed phase continue running concurrently without interruption.
• The failed phase is logged as failed in the per-phase state map and can be retried via --resume.

Parallel-Aware Resume (--resume)

In parallel mode, --resume uses a per-phase state map (.auto-state.json) that tracks each phase's status individually:

Status	Meaning
planned	PLAN.md produced, not yet reviewed
reviewed	Plan reviewed and approved
built	Build complete, SUMMARY.md exists
failed	Session exited non-zero
blocked	Waiting on a failed dependency

On resume, the orchestrator reconstructs the dependency graph from existing PLAN.md files and re-enters the pipeline at the earliest incomplete wave, skipping phases already in built state.

---

Step 7: Completion or Interruption

Whether the orchestrator completes successfully or is interrupted, always:

1. Reset AUTO_MODE:

   node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-set workflow.auto_advance false
   

2. Report final state (format as a clear summary the user can act on):

   • Phases completed (e.g., "Completed phases 3-5 of 8")
   • Total decisions logged to .planning/DECISIONS.md
   • Any LOW confidence decisions that need human review (flagged with ⚠ NEEDS REVIEW)
   • If interrupted: the exact stop point so --resume can pick up

3. Milestone completion: If the orchestrator reports all phases complete:

   • Confirm all SUMMARY.md files exist for each executed phase
   • Suggest: "All phases complete. Run gsd-tools milestone complete to archive this milestone."
   • If there were LOW confidence decisions, remind: "Review DECISIONS.md before archiving — N decisions flagged for review."

3.5. Learnings prompt: After successful completion of 2+ phases, suggest:

Run /fh:learnings to review what worked well and what could improve across the phases you just built.

This only triggers on successful completion (not failures/interruptions) and only when claude-mem is installed.

4. If orchestrator failed, provide actionable diagnostics:

   • Read the error output and any {step}-error.log files in the failed phase directory
   • Classify the failure: API error (suggest retry with --resume), logic error (show the error and suggest investigating), stuck session (note the phase and suggest --resume)
   • If PARTIAL-SUMMARY.md exists, read it and summarize what was completed before failure
   • Always end with: "Run /fh:auto --resume to continue from where it stopped."
   • Never leave the user without a clear next action

5. Read final STATE.md and confirm it reflects the orchestrator's last successful step.

---

Step 8: Decision Correction Cascade (--check-corrections)

When invoked with --check-corrections, the orchestrator runs in a separate mode that does NOT execute the normal phase loop. Instead:

1. Reads .planning/DECISIONS.md for entries with Status: CORRECTED
2. For each CORRECTED entry, parses the Affects field to identify impacted artifacts
3. Classifies each correction as Mechanical (string/config changes) or Architectural (design changes)
4. Mechanical corrections are auto-fixed via claude -p sessions targeting the affected files
5. Architectural corrections produce a .planning/CORRECTION-PLAN.md for manual review
6. Logs a cascade analysis decision entry summarizing what was processed

Invoke via:

node "$ORCHESTRATOR" --project-dir "$(pwd)" --check-corrections

This mode is useful after a human reviews DECISIONS.md and marks entries as CORRECTED — the cascade propagates those corrections to affected artifacts automatically where possible.

---

Cross-Session Output

[auto-output] Milestone: {name}. Phases completed: {count}/{total}. Total plans: {executed}. Decisions logged: {count}. Issues: {unresolved_count}.