Dev pilot

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Overview

Dev-pilot is the top-level orchestrator for the Project-Forge autonomous pipeline. It reads features.json, processes each feature in priority order, and drives the entire cycle:

features.json → for each feature (by priority):
  /speckit-feature  → spec + plan + tasks + prd
  tools/ralph       → implementation (parallel stories)
  tools/validate-feature → typecheck + lint + tests + build
  tools/deploy-staging   → push + Vercel preview
  tools/smoke-test       → verify routes
  [HUMAN REVIEW]         → approve + promote
  features.json status=done

Prerequisites

Before running, verify:

1. Project has .speckit/features.json with at least one feature status=todo
2. tools/ralph, tools/validate-feature, tools/deploy-staging, tools/smoke-test exist and are executable
3. Git repo is clean (no uncommitted changes)
4. Required CLIs available: gh, vercel, claude (check with command -v)

If prerequisites fail, report what's missing and stop.

Step 1: Load and Sort Features

# Read features.json
cat .speckit/features.json

Sort features by:

1. Priority: P1 before P2 before P3
2. Within same priority: by ID (F01 before F02)

Filter to features with status=todo or status=specifying (resume interrupted work).

If no features to process, report "All features are done or in progress" and stop.

Step 2: Process Each Feature

For each feature in priority order:

2a. Specification Phase

If feature status is todo:

• Run /speckit-feature {feature-id} (chains specify → plan → tasks → convert)
• This updates status to implementing
• On failure: Log error, skip feature, continue to next

2b. Implementation Phase

If feature status is implementing:

• Find the ralph session from features.json prdSession
• Run tools/ralph --session {session-id} --auto-merge
• On failure (3 retries exhausted on a story):
  • Update features.json: status=blocked
  • Log: "Feature {id} blocked: story {N} failed after 3 retries"
  • Continue to next feature

2c. Validation Phase

After ralph completes:

• Run tools/validate-feature
• Update status to validating
• On failure:
  • Log validation errors
  • Keep status as implementing (don't advance)
  • Continue to next feature

2d. Staging Phase

After validation passes:

• Run tools/deploy-staging
• Update status to staging
• Read the preview URL from .staging-url
• On failure:
  • Log deployment error
  • Keep status as validating
  • Continue to next feature

2e. Smoke Test Phase

After deployment:

• Run tools/smoke-test
• On failure:
  • Log failed routes
  • Keep status as staging (deployed but not verified)
  • Continue to next feature

2f. Human Review Gate

After smoke tests pass:

• Report: "Feature {id} ({name}) is ready for review"
• Print preview URL
• Print summary of changes (stories completed, files modified)
• STOP and wait for human input

The human can:

• approve → run tools/promote-to-prod --auto-merge, set status to done
• skip → leave in staging, move to next feature
• reject → set status to implementing, move to next feature
• abort → stop the entire pipeline

Step 3: Report

After all features processed (or pipeline aborted):

Dev-Pilot Pipeline Report
═════════════════════════

Features Processed: {N}

  F01 auth          done      ✓ (promoted to prod)
  F02 payments      staging   ⏳ (awaiting review)
  F03 dashboard     blocked   ✗ (story 4 failed)
  F04 settings      todo      — (not started)

Summary:
  Completed:  {N}
  Staging:    {N}
  Blocked:    {N}
  Remaining:  {N}

Next actions:
  - Review F02 at https://preview-url.vercel.app
  - Fix F03 story 4 manually, then re-run dev-pilot

Escalation Rules

Scenario	Action	Status
speckit-feature fails	Skip feature, log error	remains todo
Ralph story fails 3x	Skip feature, log blocker	blocked
Validation fails	Don't advance, log errors	implementing
Deploy fails	Don't advance, log error	validating
Smoke test fails	Keep deployed, log routes	staging
Human rejects	Reset to implementing	implementing

Mutation Testing (Optional)

After validation passes (step 2c) and before deploy (step 2d):

• If stryker.config.json exists, run pnpm test:mutation
• If mutation score < 50%: warn "Tests may be insufficient" but don't block
• Log mutation score in the report

Configuration

Dev-pilot reads configuration from features.json top level:

{
  "project": "my-project",
  "config": {
    "autoMerge": true,
    "skipMutationTesting": false,
    "ralphModel": "sonnet",
    "ralphBudget": "2.00"
  },
  "features": [...]
}

Defaults if config section missing:

• autoMerge: false (require human approval)
• skipMutationTesting: true (opt-in)
• ralphModel: "sonnet"
• ralphBudget: "2.00"

Headless Mode

Dev-pilot can run in fully headless mode (no human review gate):

• Pass --headless flag
• All features auto-promote after smoke tests pass
• Best for CI/CD environments
• Still stops on blocked features

Safety

• NEVER force-push or delete branches
• NEVER modify main directly
• Always create feature branches via ralph
• Always wait for CI before merge (auto-merge handles this)
• Preserve features.json as single source of truth