Cruise Control

Cruise Control Mode 🚗💨

Automatic transmission for StackShift - Shift through all 6 gears sequentially without manual intervention.

When to Use This Skill

Use cruise control when:

• You want to run the entire workflow automatically
• Don't need to review each step before proceeding
• Trust StackShift to make reasonable defaults
• Want unattended execution (kick it off and come back later)
• Prefer automatic over manual transmission

Trigger Phrases:

• "Run StackShift in cruise control mode"
• "Automatically shift through all gears"
• "Run the full workflow automatically"
• "StackShift autopilot"

What This Does

Runs all 6 gears sequentially:

Gear 1: Analyze → Gear 2: Reverse Engineer → Gear 3: Create Specs →
Gear 4: Gap Analysis → Gear 5: Complete Spec → Gear 6: Implement

Without stopping between gears!

Setup

Initial Configuration (One-Time)

At the start, you'll be asked:

1. Route Selection:

   Choose your route:
   A) Greenfield - Shift to new tech stack
   B) Brownfield - Manage existing code
   

2. Implementation Framework:

   Choose implementation framework:
   A) GitHub Spec Kit - Feature specs in .specify/, /speckit.* commands
   B) BMAD Method - Same docs, hands off to BMAD's collaborative agents
   

3. Clarifications Handling: (Spec Kit only)

   How to handle [NEEDS CLARIFICATION] markers?
   A) Defer - Mark them, implement around them, clarify later
   B) Prompt - Stop and ask questions interactively
   C) Skip - Only implement fully-specified features
   

4. Implementation Scope: (Spec Kit only)

   What to implement in Gear 6?
   A) P0 only - Critical features only
   B) P0 + P1 - Critical and high-value
   C) All - Everything (may take hours/days)
   D) None - Stop after specs are ready
   

Then cruise control takes over!

Note: For BMAD Method, questions 3-4 are skipped. BMAD agents handle clarifications and implementation through their interactive workflow.

Execution Flow

GitHub Spec Kit Path

Gear 1: Analyze (Auto)

• Detects tech stack
• Assesses completeness
• Sets route and framework (from your selections)
• Saves state with auto_mode: true
• Auto-shifts to Gear 2 ✅

Gear 2: Reverse Engineer (Auto)

• Launches stackshift:code-analyzer agent
• Extracts documentation based on route
• Generates all 9 files (including integration-points.md)
• Auto-shifts to Gear 3 ✅

Gear 3: Create Specifications (Auto)

• Calls automated spec generation (F002)
• Generates constitution (appropriate template for route)
• Creates all feature specs programmatically
• Creates implementation plans for incomplete features
• Sets up /speckit.* slash commands
• Auto-shifts to Gear 4 ✅

Gear 4: Gap Analysis (Auto)

• Runs /speckit.analyze
• Identifies PARTIAL/MISSING features
• Creates prioritized roadmap
• Marks [NEEDS CLARIFICATION] items
• Auto-shifts to Gear 5 ✅

Gear 5: Complete Specification (Conditional)

• If clarifications handling = "Defer": Skips, moves to Gear 6
• If clarifications handling = "Prompt": Asks questions interactively, then continues
• If clarifications handling = "Skip": Marks unclear features as P2, moves on
• Auto-shifts to Gear 6 ✅

Gear 6: Implement (Based on Scope)

• If scope = "None": Stops, specs ready
• If scope = "P0 only": Implements critical features only
• If scope = "P0 + P1": Implements critical + high-value
• If scope = "All": Implements everything
• Uses /speckit.tasks and /speckit.implement for each feature
• Completes! 🏁

BMAD Method Path

Gear 1: Analyze (Auto)

• Detects tech stack
• Assesses completeness
• Sets route and framework (from your selections)
• Saves state with auto_mode: true
• Auto-shifts to Gear 2 ✅

Gear 2: Reverse Engineer (Auto)

• Launches stackshift:code-analyzer agent
• Extracts documentation (same 9 files as Spec Kit path)
• Generates all docs in docs/reverse-engineering/
• Skips to Gear 6 ✅

Gears 3-5: Skipped

• BMAD agents handle PRD creation, architecture, and clarifications collaboratively
• StackShift's reverse-engineering docs provide rich context for BMAD

Gear 6: BMAD Handoff

• Displays instructions for BMAD installation and setup
• Provides *workflow-init command to start BMAD workflow
• Explains how to point BMAD to docs/reverse-engineering/
• StackShift completes - BMAD takes over! 🏁

Progress Monitoring

While cruise control is running, you can check progress:

# See current gear
node plugin/scripts/state-manager.js status

# Detailed progress
node plugin/scripts/state-manager.js progress

# Watch progress in real-time
watch -n 5 'node plugin/scripts/state-manager.js progress'

Or via MCP resource:

Read stackshift://progress

Interrupting Cruise Control

You can stop cruise control at any time:

"Stop cruise control"
"Pause StackShift"
"Switch to manual mode"

This will:

• Save current state
• Set auto_mode: false
• Allow you to proceed manually from current gear

You can resume cruise control later:

"Resume cruise control from current gear"

Example: Full Automatic Run

User: "Run StackShift in cruise control mode"

StackShift:
Setting up cruise control...

Choose your route:
A) Greenfield - Shift to new tech stack
B) Brownfield - Manage existing code

User: "B - Brownfield"

StackShift:
How to handle clarifications?
A) Defer - Clarify later
B) Prompt - Ask me now
C) Skip - Only implement clear features

User: "A - Defer"

StackShift:
Implementation scope?
A) P0 only
B) P0 + P1
C) All features
D) None (stop after specs)

User: "B - P0 + P1"

StackShift:
✅ Cruise control engaged! Shifting through all gears automatically...

🔍 Gear 1: Analyzing... ✅ Complete (2 min)
🔄 Gear 2: Reverse engineering... ✅ Complete (8 min)
📋 Gear 3: Creating specifications... ✅ Complete (5 min)
🔍 Gear 4: Gap analysis... ✅ Complete (3 min)
✨ Gear 5: Completing specs (deferred clarifications)... ✅ Complete (1 min)
🚀 Gear 6: Implementing P0 + P1 features... 🔄 In Progress (est. 45 min)

   Feature 1/8: user-authentication... ✅
   Feature 2/8: fish-management... ✅
   Feature 3/8: photo-upload... 🔄 In progress...

[... continues automatically ...]

🏁 All gears complete! Application at 85% implementation.

Deferred clarifications (3) saved in: .specify/memory/clarifications.md
You can resolve these later with: /speckit.clarify

Configuration Options

Cruise control can be configured via state:

{
  "auto_mode": true,
  "auto_config": {
    "route": "brownfield",
    "clarifications_strategy": "defer",
    "implementation_scope": "p0_p1",
    "pause_between_gears": false,
    "notify_on_completion": true
  }
}

Advanced: Scheduled Execution

Run cruise control in background:

# Start in background
nohup stackshift cruise-control --route brownfield --scope p0 &

# Check progress
tail -f stackshift-cruise.log

# Or via state
watch stackshift://progress

Use Cases

1. Overnight Execution

5pm: "Run cruise control, brownfield, P0+P1, defer clarifications"
9am: Check results, review generated specs, answer deferred questions

2. CI/CD Integration

# .github/workflows/stackshift.yml
- name: Run StackShift Analysis
  run: stackshift cruise-control --route brownfield --scope none
  # Generates specs, doesn't implement (safe for CI)

3. Batch Processing

Run cruise control on multiple projects:
- project-a: greenfield
- project-b: brownfield
- project-c: brownfield

4. Demo Mode

"Show me what StackShift does - run full demo"
→ Runs cruise control with sample project

Safety Features

Checkpoints

Cruise control creates checkpoints at each gear:

• State saved after each gear completes
• Can resume from any checkpoint if interrupted
• Rollback possible if issues detected

Validation

Before proceeding:

• Validates output files were created
• Checks for errors in previous gear
• Ensures prerequisites met

User Intervention

Pauses automatically if:

• Critical error detected
• /speckit.analyze shows major inconsistencies
• Implementation fails tests
• Disk space low
• Git conflicts detected

Manual Override

At any point, you can:

"Pause after current gear"
"Stop cruise control"
"Switch to manual mode"
"Take control"

State saved, you can continue manually from that point.

Success Criteria

GitHub Spec Kit Path

After cruise control completes:

• ✅ All 6 gears complete
• ✅ .stackshift-state.json shows 6/6 gears
• ✅ All output files generated
• ✅ GitHub Spec Kit initialized (.specify/ directory)
• ✅ Features implemented (based on scope)
• ✅ Ready for production (or clarifications if deferred)

BMAD Method Path

After cruise control completes:

• ✅ Gears 1, 2, 6 complete (3-5 skipped)
• ✅ .stackshift-state.json shows framework: "bmad"
• ✅ docs/reverse-engineering/ structure generated (same 9 files as Spec Kit)
• ✅ BMAD handoff instructions displayed
• ✅ Ready for *workflow-init to create PRD/Architecture collaboratively

Technical Notes

• Cruise control is a special skill that orchestrates other skills
• Each gear is still executed by its corresponding skill
• Auto mode can be toggled on/off at any time
• State tracks auto_mode for resume capability
• Great for CI/CD, batch processing, or overnight runs

Remember: Cruise control is like automatic transmission - convenient and hands-off. Manual mode (using individual skills) gives you more control. Choose based on your needs!

🚗 Manual = Control each gear yourself 🤖 Cruise Control = Let StackShift handle it

Both get you to the same destination!