From ca2c1d5432a6700ba868ccd7fef6e0968ef942fa Mon Sep 17 00:00:00 2001 From: Jonah Schulte Date: Wed, 17 Dec 2025 23:04:52 -0500 Subject: [PATCH 1/2] feat: Add universal LLM tool compatibility and BE RAD framework option This implements the patterns from the OpenCode compatibility guide: ## Universal LLM Tool Support - Add multi-tool instructions to slash commands (Claude Code, OpenCode, Cursor, etc.) - Create universal installer script (scripts/install-universal.sh) - Add .stackshift-config-example.json for pre-configuration - Commands now include bash fallbacks for non-Claude Code tools ## BE RAD Framework Option - Add "BOTH" as third framework choice (speckit, bmad, or both) - Default to BOTH when user presses Enter (maximum flexibility) - Visual framework selection with ASCII box presentation - BOTH generates Spec Kit artifacts AND provides BMAD handoff ## Key Changes - stackshift.analyze.md: Multi-tool instructions, config check, bash workflow - stackshift.implement.md: Path C for BOTH framework with mix-and-match guidance - skills/analyze/SKILL.md: BE RAD framework presentation, BOTH option - skills/cruise-control/SKILL.md: BOTH path execution flow - README.md: Universal tool support section, BE RAD documentation BE RAD = Business logic Extraction + Reverse engineering + Agent-Driven development --- .claude/commands/stackshift.analyze.md | 112 ++++++++++++- .claude/commands/stackshift.implement.md | 83 ++++++++++ .stackshift-config-example.json | 49 ++++++ README.md | 94 +++++++++-- scripts/install-universal.sh | 190 +++++++++++++++++++++++ skills/analyze/SKILL.md | 77 ++++++--- skills/cruise-control/SKILL.md | 69 +++++++- 7 files changed, 629 insertions(+), 45 deletions(-) create mode 100644 .stackshift-config-example.json create mode 100755 scripts/install-universal.sh diff --git a/.claude/commands/stackshift.analyze.md b/.claude/commands/stackshift.analyze.md index 0919d8d..ce46f2a 100644 --- a/.claude/commands/stackshift.analyze.md +++ b/.claude/commands/stackshift.analyze.md @@ -6,9 +6,28 @@ description: Gear 1 - Analyze codebase and detect tech stack **IMPORTANT**: This command runs AST analysis ONCE and saves results for all gears. +--- + +## Step 0: Check for Pre-Configuration + +```bash +# Check if config file exists (skip prompts if pre-configured) +if [ -f .stackshift-config.json ]; then + echo "✅ Found .stackshift-config.json - using pre-configured settings" + cat .stackshift-config.json | jq '.frameworks' + SKIP_PROMPTS=true +else + echo "ℹī¸ No .stackshift-config.json found (optional)" + echo "Create one to pre-configure options and skip prompts." + SKIP_PROMPTS=false +fi +``` + +--- + ## Step 1: Run Full AST Analysis (Deterministic - Saves to Files) -First, use the Bash tool to execute comprehensive AST analysis: +**For all tools (Claude Code, OpenCode, Cursor, VSCode, etc.):** ```bash ~/stackshift/scripts/run-ast-analysis.mjs analyze . @@ -28,21 +47,102 @@ First, use the Bash tool to execute comprehensive AST analysis: **Cache duration**: 1 hour (auto-refreshes if stale) +--- + ## Step 2: Detect Tech Stack, Route, and Framework -After AST analysis completes, use the Skill tool to detect tech stack: +### For Claude Code users: Use the Skill tool with skill="analyze". -**The skill will**: +### For OpenCode users: + +Use the StackShift agent: `@stackshift analyze this codebase` + +Or run the bash workflow below. + +### For VSCode/Cursor/Codex users: + +Run this interactive workflow: + +```bash +# 1. Detect tech stack +if [ -f package.json ]; then + echo "đŸ“Ļ Node.js project detected" + echo "Dependencies:" + cat package.json | jq '.dependencies // {} | keys' +fi + +# 2. Choose route +echo "" +echo "Choose your route:" +echo " A) Greenfield - Shift to new tech stack (extract business logic only)" +echo " B) Brownfield - Manage existing code (extract full implementation)" +read -p "Your choice (A/B): " route_choice +case ${route_choice^^} in + A) ROUTE="greenfield" ;; + B) ROUTE="brownfield" ;; + *) ROUTE="brownfield" ;; +esac + +# 3. Choose framework (BE RAD!) +echo "" +echo "╔═══════════════════════════════════════════════════════════════╗" +echo "║ Choose Your Implementation Framework ║" +echo "╚═══════════════════════════════════════════════════════════════╝" +echo "" +echo "A) GitHub Spec Kit" +echo " ✓ Feature-level specs in .specify/" +echo " ✓ Task-driven workflow with /speckit.* commands" +echo "" +echo "B) BMAD Method" +echo " ✓ Hands off to BMAD's collaborative PM/Architect agents" +echo " ✓ PRD + Architecture created through conversation" +echo "" +echo "C) BOTH (Recommended for maximum power! 🚀)" +echo " ✓ Generate Spec Kit specs (.specify/)" +echo " ✓ Hand off to BMAD with rich context" +echo " ✓ BE RAD: Best of All Worlds!" +echo "" +read -p "Your choice (A/B/C - or press Enter for C): " fw_choice +fw_choice=${fw_choice:-C} +case ${fw_choice^^} in + A) FRAMEWORK="speckit" ;; + B) FRAMEWORK="bmad" ;; + C) FRAMEWORK="both" ;; + *) FRAMEWORK="both" ;; +esac + +# 4. Save state +cat > .stackshift-state.json << EOF +{ + "route": "$ROUTE", + "implementation_framework": "$FRAMEWORK", + "gear": 1, + "timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" +} +EOF + +echo "" +echo "✅ Configuration saved to .stackshift-state.json" +echo " Route: $ROUTE" +echo " Framework: $FRAMEWORK" +``` + +--- + +## What the Analysis Does + +**The analysis will**: - Read file structure - Detect frameworks from package.json - Choose route (Greenfield/Brownfield) -- Choose implementation framework (GitHub Spec Kit / BMAD Method) +- Choose implementation framework (GitHub Spec Kit / BMAD Method / BOTH) - Auto-detect app type (monorepo, Nx, etc.) - Create analysis-report.md - Save to .stackshift-state.json -**Framework choice determines output format**: +**Framework choice determines workflow**: - **GitHub Spec Kit**: Creates `.specify/` structure, uses `/speckit.*` commands -- **BMAD Method**: Creates `docs/` structure, hands off to `*workflow-init` +- **BMAD Method**: Creates `docs/reverse-engineering/`, hands off to `*workflow-init` +- **BOTH (BE RAD)**: Creates both `.specify/` AND BMAD handoff for maximum flexibility diff --git a/.claude/commands/stackshift.implement.md b/.claude/commands/stackshift.implement.md index 531e851..c83c297 100644 --- a/.claude/commands/stackshift.implement.md +++ b/.claude/commands/stackshift.implement.md @@ -109,3 +109,86 @@ docs/reverse-engineering/ **You get the best of both worlds:** - StackShift's deep, accurate reverse engineering as input - BMAD's interactive, collaborative artifact creation as output + +--- + +## Path C: BOTH (implementation_framework: both) 🚀 + +### BE RAD: Best of All Worlds! + +When you chose "BOTH", you get maximum flexibility. + +### Step 1: Implement Features with Spec Kit + +**First**, run Spec Kit implementation: + +Use the Skill tool with skill="implement". + +**The skill will**: +- Build features using `/speckit.tasks` and `/speckit.implement` +- Only implement PARTIAL and MISSING features +- Follow spec requirements exactly + +### Step 2: Verify Implementation + +```bash +~/stackshift/scripts/run-ast-analysis.mjs status . +``` + +### Step 3: BMAD Handoff (Optional) + +**Then**, you have the option to hand off to BMAD for collaborative refinement. + +**What you now have:** +``` +.specify/ # Spec Kit artifacts +├── memory/ +│ ├── constitution.md +│ └── [feature-name]/ +│ ├── spec.md +│ ├── plan.md +│ └── tasks.md + +docs/reverse-engineering/ # BMAD context +├── functional-specification.md +├── data-architecture.md +├── integration-points.md +└── ... (9 files total) +``` + +**Your options going forward:** + +1. **Use Spec Kit workflow** for task-driven development: + - `/speckit.specify` for new features + - `/speckit.plan` for implementation plans + - `/speckit.tasks` for task lists + - `/speckit.implement` for execution + +2. **Use BMAD workflow** for collaborative refinement: + - `npx bmad-method@alpha install` + - Run `*workflow-init` + - Point BMAD to `docs/reverse-engineering/` + - Let PM/Architect agents create artifacts through conversation + +3. **Mix and match** as needed: + - Use Spec Kit for quick, focused tasks + - Use BMAD when you need deeper architectural discussion + - Both have access to the same rich context + +### Why BOTH is Powerful + +| Scenario | Use This | +|----------|----------| +| Quick bug fix | Spec Kit `/speckit.implement` | +| New feature with clear scope | Spec Kit workflow | +| Complex feature needing discussion | BMAD PM agent | +| Architecture decision | BMAD Architect agent | +| Day-to-day development | Spec Kit | +| Strategic planning | BMAD | + +**The BE RAD philosophy:** +- **B**usiness logic extraction (StackShift) +- **E**verything documented (9 comprehensive files) +- **R**eady for any workflow (Spec Kit OR BMAD) +- **A**daptable to your needs (switch anytime) +- **D**ecision-free (no commitment upfront) diff --git a/.stackshift-config-example.json b/.stackshift-config-example.json new file mode 100644 index 0000000..ea46cac --- /dev/null +++ b/.stackshift-config-example.json @@ -0,0 +1,49 @@ +{ + "$schema": "https://stackshift.dev/config-schema.json", + "version": "1.0", + "description": "StackShift Configuration - Copy to .stackshift-config.json to customize", + + "frameworks": { + "_comment": "Framework preferences (overrides prompts)", + "implementation_framework": null, + "_valid_values": ["speckit", "bmad", "both", null], + "_note": "Set to null to be prompted, or pre-configure for automation" + }, + + "route": { + "_comment": "Route preference", + "default_route": null, + "_valid_values": ["greenfield", "brownfield", null] + }, + + "generation": { + "_comment": "Control what to generate (cost optimization)", + "generate_specs": true, + "generate_plans": true, + "generate_tasks": false, + "_note": "Set generate_tasks to false for faster analysis" + }, + + "cruise_control": { + "_comment": "Cruise control settings", + "clarifications_strategy": "defer", + "_valid_strategies": ["defer", "prompt", "skip"], + "implementation_scope": "p0_p1", + "_valid_scopes": ["none", "p0", "p0_p1", "all"] + }, + + "tool_modes": { + "_comment": "Enable tool-specific optimizations", + "opencode_enabled": false, + "skip_interactive_prompts": false, + "use_explicit_mentions": true, + "_note": "Set skip_interactive_prompts to true for CI/CD" + }, + + "paths": { + "_comment": "Custom output paths (optional)", + "spec_output_location": null, + "build_location": null, + "_note": "Set to null to use defaults (current directory)" + } +} diff --git a/README.md b/README.md index 5e14a98..4f08c25 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Transform any application into a fully-specified, spec-driven project with compl -> **Two paths, two frameworks, complete control:** +> **Two paths, three frameworks, complete control:** > > **🔀 Greenfield:** Extract business logic from your legacy app, then rebuild in a modern stack using tech-agnostic specs. > @@ -28,7 +28,10 @@ Transform any application into a fully-specified, spec-driven project with compl > > **🛠ī¸ Choose Your Implementation Framework:** > - **GitHub Spec Kit** - Feature specs in `.specify/`, task-driven workflow -> - **BMAD Method** - PRD + Architecture in `docs/`, agent-driven workflow +> - **BMAD Method** - PRD + Architecture through collaborative agents +> - **BOTH (BE RAD!)** - Get both workflows for maximum flexibility 🚀 +> +> **🌐 Works Everywhere:** Claude Code, OpenCode, Cursor, Windsurf, Codex, VSCode > > Start in reverse (engineering), shift through 6 gears, and cruise into spec-driven development! > @@ -150,9 +153,46 @@ stateDiagram-v2 --- +## 🌐 Universal LLM Tool Support + +StackShift works with multiple LLM coding tools: + +| Tool | Status | Installation | +|------|--------|--------------| +| **Claude Code** | ✅ Full support | Plugin or slash commands | +| **OpenCode** | ✅ Full support | Slash commands + agents | +| **Cursor** | ✅ Supported | Natural language + bash | +| **Windsurf** | ✅ Supported | Natural language + bash | +| **Codex** | ✅ Supported | Natural language + bash | +| **VSCode** | ✅ Supported | Continue extension + bash | + +### Universal Installer + +Install StackShift commands to any/all detected tools: + +```bash +./scripts/install-universal.sh +``` + +The installer will: +- Auto-detect installed LLM tools +- Let you choose which tools to install to +- Copy commands to appropriate locations + +### Pre-Configuration (CI/CD Friendly) + +Create `.stackshift-config.json` to skip interactive prompts: + +```bash +cp .stackshift-config-example.json .stackshift-config.json +# Edit to set your preferences +``` + +--- + ## 🚀 Quick Start -### Three Ways to Use StackShift +### Four Ways to Use StackShift #### Option 1: Claude Code Plugin (Local - Best Experience) @@ -396,17 +436,49 @@ docs/reverse-engineering/ **Best for:** Large projects, enterprise teams, agent-driven workflows +### BOTH (BE RAD!) - Recommended 🚀 + +**Why choose when you can have both?** + +``` +BE RAD = Business logic Extraction + Reverse engineering + Agent-Driven development +``` + +**Output structure:** +``` +.specify/ # Spec Kit artifacts +├── memory/ +│ ├── constitution.md +│ └── [feature-name]/ +│ ├── spec.md +│ ├── plan.md +│ └── tasks.md + +docs/reverse-engineering/ # BMAD context (same 9 files) +├── functional-specification.md +├── data-architecture.md +└── ... (9 files total) +``` + +**Benefits:** +- Use Spec Kit for quick, focused tasks +- Use BMAD when you need collaborative refinement +- Switch between workflows as your needs change +- No commitment required upfront + +**Best for:** Teams that want maximum flexibility + ### Framework Comparison -| Aspect | GitHub Spec Kit | BMAD Method | -|--------|-----------------|-------------| -| **Gear 2 Output** | Same 9 docs | Same 9 docs | -| **Gears 3-5** | Create `.specify/` specs | Skipped (BMAD handles) | -| **Gear 6** | `/speckit.implement` | Handoff to `*workflow-init` | -| **Artifact Creation** | Automated from docs | Collaborative with BMAD agents | -| **Best For** | Task-driven teams | Agent-driven enterprise teams | +| Aspect | GitHub Spec Kit | BMAD Method | BOTH (BE RAD!) | +|--------|-----------------|-------------|----------------| +| **Gear 2 Output** | 9 docs | 9 docs | 9 docs | +| **Gears 3-5** | Create `.specify/` specs | Skipped | Create `.specify/` specs | +| **Gear 6** | `/speckit.implement` | BMAD handoff | Both! | +| **Artifact Creation** | Automated | Collaborative | Your choice | +| **Best For** | Task-driven | Agent-driven | Flexibility | -**Note:** StackShift's reverse engineering (Gear 2) replaces BMAD's Phase 0 (`document-project`) with deeper AST-powered analysis. Both frameworks get the same rich context. +**Note:** StackShift's reverse engineering (Gear 2) replaces BMAD's Phase 0 (`document-project`) with deeper AST-powered analysis. All frameworks get the same rich context. --- diff --git a/scripts/install-universal.sh b/scripts/install-universal.sh new file mode 100755 index 0000000..b2cac98 --- /dev/null +++ b/scripts/install-universal.sh @@ -0,0 +1,190 @@ +#!/bin/bash + +# StackShift Universal Installer +# Detects and installs to Claude Code, OpenCode, Cursor, Windsurf, Codex, etc. + +set -e + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" +COMMANDS_SOURCE="$PROJECT_ROOT/.claude/commands" + +echo "🚀 StackShift Universal Installer" +echo "==================================" +echo "" + +# Detect available LLM tools +declare -a DETECTED_TOOLS=() +declare -A TOOL_PATHS=() + +echo "🔍 Detecting installed LLM tools..." +echo "" + +# Claude Code +if [ -d "$HOME/.claude" ] || command -v claude &> /dev/null; then + DETECTED_TOOLS+=("claude-code") + TOOL_PATHS["claude-code"]="$HOME/.claude/commands" + echo " ✅ Claude Code detected → $HOME/.claude/commands" +fi + +# OpenCode +if command -v opencode &> /dev/null || [ -d "$HOME/.config/opencode" ]; then + DETECTED_TOOLS+=("opencode") + TOOL_PATHS["opencode"]="$HOME/.config/opencode/commands" + echo " ✅ OpenCode detected → $HOME/.config/opencode/commands" +fi + +# Cursor +if [ -d "$HOME/.cursor" ] || command -v cursor &> /dev/null; then + DETECTED_TOOLS+=("cursor") + TOOL_PATHS["cursor"]="$HOME/.cursor/prompts" + echo " ✅ Cursor detected → $HOME/.cursor/prompts" +fi + +# Windsurf +if [ -d "$HOME/.windsurf" ] || command -v windsurf &> /dev/null; then + DETECTED_TOOLS+=("windsurf") + TOOL_PATHS["windsurf"]="$HOME/.windsurf/commands" + echo " ✅ Windsurf detected → $HOME/.windsurf/commands" +fi + +# Codex (OpenAI) +if command -v codex &> /dev/null || [ -d "$HOME/.codex" ]; then + DETECTED_TOOLS+=("codex") + TOOL_PATHS["codex"]="$HOME/.codex/commands" + echo " ✅ Codex detected → $HOME/.codex/commands" +fi + +# VSCode with Continue extension +if [ -d "$HOME/.continue" ]; then + DETECTED_TOOLS+=("continue") + TOOL_PATHS["continue"]="$HOME/.continue/prompts" + echo " ✅ Continue (VSCode) detected → $HOME/.continue/prompts" +fi + +echo "" +echo "Detected ${#DETECTED_TOOLS[@]} LLM tool(s)" +echo "" + +# Handle no tools detected +if [ ${#DETECTED_TOOLS[@]} -eq 0 ]; then + echo "❌ No LLM tools detected!" + echo "" + echo "Supported tools:" + echo " â€ĸ Claude Code (claude)" + echo " â€ĸ OpenCode (opencode)" + echo " â€ĸ Cursor (cursor)" + echo " â€ĸ Windsurf (windsurf)" + echo " â€ĸ Codex (codex)" + echo " â€ĸ Continue VSCode extension" + echo "" + echo "Please install one of these tools and try again." + echo "Or specify a custom path:" + echo "" + read -p "Custom installation path (or press Enter to exit): " custom_path + + if [ -z "$custom_path" ]; then + echo "Installation cancelled." + exit 0 + fi + + DETECTED_TOOLS+=("custom") + TOOL_PATHS["custom"]="$custom_path" +fi + +# Show detected tools and get selection +echo "Where would you like to install StackShift commands?" +echo "" +for i in "${!DETECTED_TOOLS[@]}"; do + tool="${DETECTED_TOOLS[$i]}" + path="${TOOL_PATHS[$tool]}" + echo " $((i+1)). $tool → $path" +done +echo " A. Install to ALL detected tools" +echo " Q. Quit" +echo "" +read -p "Select tools (1-${#DETECTED_TOOLS[@]}, A, or Q): " selection + +# Parse selection +declare -a INSTALL_TOOLS=() + +case "${selection^^}" in + Q) + echo "Installation cancelled." + exit 0 + ;; + A) + INSTALL_TOOLS=("${DETECTED_TOOLS[@]}") + ;; + *) + # Parse comma/space-separated list + IFS=', ' read -r -a INDICES <<< "$selection" + for idx in "${INDICES[@]}"; do + if [ "$idx" -ge 1 ] 2>/dev/null && [ "$idx" -le "${#DETECTED_TOOLS[@]}" ] 2>/dev/null; then + INSTALL_TOOLS+=("${DETECTED_TOOLS[$((idx-1))]}") + fi + done + ;; +esac + +if [ ${#INSTALL_TOOLS[@]} -eq 0 ]; then + echo "No valid tools selected. Installation cancelled." + exit 1 +fi + +echo "" +echo "đŸ“Ļ Installing to: ${INSTALL_TOOLS[*]}" +echo "" + +# Installation function +install_to_tool() { + local tool="$1" + local target_dir="$2" + + echo "Installing to $tool..." + + # Create target directory + mkdir -p "$target_dir" + + # Copy commands + local count=0 + for cmd in "$COMMANDS_SOURCE"/*.md; do + if [ -f "$cmd" ]; then + cmd_name=$(basename "$cmd") + cp "$cmd" "$target_dir/$cmd_name" + count=$((count + 1)) + fi + done + + echo " ✓ Installed $count commands to $target_dir" +} + +# Install to each selected tool +for tool in "${INSTALL_TOOLS[@]}"; do + target="${TOOL_PATHS[$tool]}" + install_to_tool "$tool" "$target" +done + +echo "" +echo "✅ Installation complete!" +echo "" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "📚 Usage varies by tool:" +echo "" +echo "Claude Code:" +echo " /stackshift.analyze" +echo " /stackshift.reverse-engineer" +echo " /stackshift.create-specs" +echo " /stackshift.implement" +echo "" +echo "OpenCode:" +echo " /stackshift.analyze" +echo " @stackshift analyze this codebase" +echo "" +echo "Cursor/Windsurf/Codex:" +echo ' Use natural language: "Run StackShift analysis on this project"' +echo " Or run bash commands from the command files directly" +echo "" +echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +echo "" +echo "🚗 Happy Shifting!" diff --git a/skills/analyze/SKILL.md b/skills/analyze/SKILL.md index 9604897..72560cb 100644 --- a/skills/analyze/SKILL.md +++ b/skills/analyze/SKILL.md @@ -223,27 +223,51 @@ B) Brownfield: Extract for maintaining existing codebase - Generic + Brownfield = Full implementation for management **Question 2: Implementation Framework** + +**Present this prominently with visual emphasis:** + ``` -Which implementation framework do you want to use? +╔═══════════════════════════════════════════════════════════════╗ +║ Choose Your Implementation Framework ║ +╚═══════════════════════════════════════════════════════════════╝ -A) GitHub Spec Kit (Recommended for most projects) - → Feature-level specifications in .specify/ - → Task-driven implementation with /speckit.* commands - → Simpler, lightweight workflow - → Best for: small-medium projects, focused features +A) GitHub Spec Kit + ✓ Feature-level specifications in .specify/ + ✓ Task-driven implementation with /speckit.* commands + ✓ Simpler, lightweight workflow + ✓ Best for: small-medium projects, focused features -B) BMAD Method (For larger/enterprise projects) - → Uses same reverse-engineering docs as Spec Kit - → Hands off to BMAD's collaborative PM/Architect agents - → BMAD creates PRD + Architecture through conversation - → Best for: large projects, multi-team, enterprise +B) BMAD Method + ✓ Uses same reverse-engineering docs as Spec Kit + ✓ Hands off to BMAD's collaborative PM/Architect agents + ✓ BMAD creates PRD + Architecture through conversation + ✓ Best for: large projects, multi-team, enterprise -After StackShift extracts documentation (Gear 2): -- Both frameworks get the same 9 docs in docs/reverse-engineering/ -- Spec Kit: Gears 3-6 create .specify/ specs, use /speckit.implement -- BMAD: Skip to Gear 6, hand off to *workflow-init with rich context +C) BOTH (Recommended for maximum power! 🚀) + ✓ Generate Spec Kit specs (.specify/) + ✓ Generate reverse-engineering docs + ✓ Hand off to BMAD with rich context + ✓ BE RAD: Reverse Engineer + Spec Kit + BMAD = Best of All Worlds! + ✓ Use whichever workflow fits your current task + ✓ Best for: Teams that want flexibility and maximum context + +Your choice (A/B/C - or press Enter for C): ``` +**Default to "BOTH" (C)** - Users who are uncertain get maximum power. + +**Why "BOTH" as default:** +- Most powerful option - no commitment required upfront +- Generates all artifacts - user can choose later which to use +- Provides maximum context to downstream systems +- Removes decision paralysis - "when in doubt, get both" + +After StackShift extracts documentation (Gear 2): +- All frameworks get the same 9 docs in docs/reverse-engineering/ +- Spec Kit path: Gears 3-6 create .specify/ specs, use /speckit.implement +- BMAD path: Skip to Gear 6, hand off to *workflow-init with rich context +- BOTH path: Create .specify/ specs AND hand off to BMAD with full context + **Question 3: Brownfield Mode** _(If Brownfield selected)_ ``` Do you want to upgrade dependencies after establishing specs? @@ -432,7 +456,7 @@ All answers are stored in `.stackshift-state.json` and guide the entire workflow { "detection_type": "monorepo-service", // What kind of app: monorepo-service, nx-app, generic, etc. "route": "greenfield", // How to spec it: greenfield or brownfield - "implementation_framework": "speckit", // speckit or bmad + "implementation_framework": "both", // speckit, bmad, or both "config": { "spec_output_location": "~/git/my-new-app", // Where to write specs/docs "build_location": "~/git/my-new-app", // Where to build new code (Gear 6) @@ -446,7 +470,10 @@ All answers are stored in `.stackshift-state.json` and guide the entire workflow **Key fields:** - `detection_type` - What we're analyzing (monorepo-service, nx-app, turborepo-package, generic) - `route` - How to spec it (greenfield = tech-agnostic, brownfield = tech-prescriptive) -- `implementation_framework` - Which tool for implementation (speckit = GitHub Spec Kit, bmad = BMAD Method) +- `implementation_framework` - Which tool for implementation: + - `speckit` = GitHub Spec Kit only (task-driven) + - `bmad` = BMAD Method only (agent-driven) + - `both` = Both frameworks (recommended - BE RAD!) **Examples:** - Monorepo Service + Greenfield = Extract business logic for platform migration @@ -468,10 +495,12 @@ All answers are stored in `.stackshift-state.json` and guide the entire workflow ### Implementing the Questionnaire -Use the `AskUserQuestion` tool to collect all configuration upfront: +**For Claude Code users:** Use the `AskUserQuestion` tool to collect all configuration upfront. + +**For OpenCode/Cursor/VSCode users:** Use bash prompts with the visual presentation shown above. ```typescript -// Example implementation +// Claude Code implementation with AskUserQuestion AskUserQuestion({ questions: [ { @@ -495,12 +524,16 @@ AskUserQuestion({ multiSelect: false, options: [ { - label: "GitHub Spec Kit (Recommended)", - description: "Feature specs in .specify/, task-driven, simpler workflow" + label: "GitHub Spec Kit", + description: "Feature specs in .specify/, task-driven workflow" }, { label: "BMAD Method", - description: "PRD + Architecture in docs/, agent-driven, enterprise-scale" + description: "Hands off to BMAD's collaborative PM/Architect agents" + }, + { + label: "BOTH (Recommended)", + description: "BE RAD! Generate both Spec Kit specs AND BMAD handoff for maximum flexibility" } ] }, diff --git a/skills/cruise-control/SKILL.md b/skills/cruise-control/SKILL.md index 785cf83..228f489 100644 --- a/skills/cruise-control/SKILL.md +++ b/skills/cruise-control/SKILL.md @@ -52,14 +52,20 @@ At the start, you'll be asked: B) Brownfield - Manage existing code ``` -2. **Implementation Framework:** +2. **Implementation Framework (BE RAD!):** ``` - Choose implementation framework: + ╔═══════════════════════════════════════════════════════════════╗ + ║ Choose Your Implementation Framework ║ + ╚═══════════════════════════════════════════════════════════════╝ + A) GitHub Spec Kit - Feature specs in .specify/, /speckit.* commands - B) BMAD Method - Same docs, hands off to BMAD's collaborative agents + B) BMAD Method - Hands off to BMAD's collaborative agents + C) BOTH (Recommended!) - BE RAD: Best of All Worlds! + + Press Enter for C (BOTH) ``` -3. **Clarifications Handling:** (Spec Kit only) +3. **Clarifications Handling:** (Spec Kit or BOTH) ``` How to handle [NEEDS CLARIFICATION] markers? A) Defer - Mark them, implement around them, clarify later @@ -67,7 +73,7 @@ At the start, you'll be asked: C) Skip - Only implement fully-specified features ``` -4. **Implementation Scope:** (Spec Kit only) +4. **Implementation Scope:** (Spec Kit or BOTH) ``` What to implement in Gear 6? A) P0 only - Critical features only @@ -78,7 +84,9 @@ At the start, you'll be asked: Then cruise control takes over! -**Note**: For BMAD Method, questions 3-4 are skipped. BMAD agents handle clarifications and implementation through their interactive workflow. +**Note**: +- For BMAD-only, questions 3-4 are skipped (BMAD agents handle everything) +- For BOTH, questions 3-4 apply to the Spec Kit portion; BMAD handoff always happens --- @@ -157,6 +165,55 @@ Then cruise control takes over! --- +### BOTH Path (BE RAD!) 🚀 + +**The recommended path for maximum flexibility!** + +#### Gear 1: Analyze (Auto) +- Detects tech stack +- Assesses completeness +- Sets route and framework to "both" +- Saves state with `auto_mode: true` +- **Auto-shifts to Gear 2** ✅ + +#### Gear 2: Reverse Engineer (Auto) +- Launches `stackshift:code-analyzer` agent +- Extracts documentation (9 files to `docs/reverse-engineering/`) +- **Auto-shifts to Gear 3** ✅ + +#### Gear 3: Create Specifications (Auto) +- Creates `.specify/` structure with Spec Kit specs +- Generates constitution and feature specs +- Creates implementation plans for incomplete features +- **Auto-shifts to Gear 4** ✅ + +#### Gear 4: Gap Analysis (Auto) +- Runs `/speckit.analyze` +- Identifies PARTIAL/MISSING features +- Creates prioritized roadmap +- **Auto-shifts to Gear 5** ✅ + +#### Gear 5: Complete Specification (Conditional) +- Handles clarifications based on your setting +- **Auto-shifts to Gear 6** ✅ + +#### Gear 6: Implement + BMAD Handoff +- **First**: Runs Spec Kit implementation (based on scope) +- **Then**: Displays BMAD handoff instructions +- **Result**: You have BOTH: + - `.specify/` with Spec Kit artifacts + - `docs/reverse-engineering/` ready for BMAD + - Can use either workflow going forward! +- **Completes!** 🏁 + +**Why BOTH is powerful:** +- Use Spec Kit for quick task-driven implementation +- Use BMAD when you need collaborative refinement +- Switch between workflows as needed +- No commitment required upfront + +--- + ## Progress Monitoring While cruise control is running, you can check progress: From be3909360f7d1eff116b19eaedc922964032a5c1 Mon Sep 17 00:00:00 2001 From: Jonah Schulte Date: Wed, 17 Dec 2025 23:40:16 -0500 Subject: [PATCH 2/2] docs: Update repository URLs in VSCODE_COPILOT.md Use public GitHub URLs for installation instructions --- docs/guides/VSCODE_COPILOT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/VSCODE_COPILOT.md b/docs/guides/VSCODE_COPILOT.md index c86323c..3e560f9 100644 --- a/docs/guides/VSCODE_COPILOT.md +++ b/docs/guides/VSCODE_COPILOT.md @@ -14,7 +14,7 @@ For VSCode/Copilot users, use the web bootstrap prompt instead. ```bash # Clone StackShift -git clone git@ghe.coxautoinc.com:DDC-WebPlatform/stackshift.git ~/stackshift +git clone https://github.com/jschulte/stackshift.git ~/stackshift ``` ### Usage @@ -56,7 +56,7 @@ Copilot will then: ```bash # Clone mcp-tools -git clone git@ghe.coxautoinc.com:Jonah-Schulte/mcp-tools.git +# git clone cd mcp-tools # Install dependencies