diff --git a/docs/guides/BROWNFIELD_UPGRADE_MODE.md b/docs/guides/BROWNFIELD_UPGRADE_MODE.md
new file mode 100644
index 0000000..fd0814b
--- /dev/null
+++ b/docs/guides/BROWNFIELD_UPGRADE_MODE.md
@@ -0,0 +1,339 @@
+<!--
+SPDX-License-Identifier: MIT
+Copyright (c) 2024 Jonah Schulte
+-->
+
+# Brownfield Upgrade Mode
+
+**Modernize dependencies without a full rewrite**
+
+---
+
+## Overview
+
+Brownfield Upgrade Mode allows you to upgrade ALL dependencies to their latest versions after establishing complete spec coverage. Unlike a full rewrite (Greenfield), this approach modernizes your existing codebase systematically using specs as your safety net.
+
+**When to use:**
+- Legacy app stuck on old dependencies (security vulnerabilities)
+- Want modern tooling benefits without full rewrite
+- Have completed StackShift Gears 1-6 (full spec coverage)
+- Ready for systematic modernization
+
+**What you get:**
+- All dependencies at latest stable versions
+- 85%+ test coverage (improved using spec acceptance criteria)
+- Specs validated to match upgraded code
+- Security vulnerabilities eliminated
+- Breaking changes fixed with spec guidance
+
+---
+
+## Inspiration: existing migration tools
+
+
+
+### Phase 0: Spec-Guided Test Coverage (30-90 min)
+
+**Goal:** Achieve 85%+ test coverage BEFORE upgrading
+
+**Why first:**
+- Acts as safety net during upgrade
+- Detects regressions immediately
+- Validates behavior preservation
+
+**Approach:**
+1. Load all specs from `.specify/memory/specifications/`
+2. Extract acceptance criteria from each spec
+3. Map existing tests to acceptance criteria
+4. Write tests for missing criteria
+5. Iterate until 85%+ coverage
+
+**Output:**
+- `.upgrade/spec-coverage-map.json` - Maps tests to specs
+- 85%+ test coverage
+- Every acceptance criterion has test
+
+**Example:**
+
+From `user-authentication.md`:
+```markdown
+## Acceptance Criteria
+- AC-1: Given valid email, When user submits, Then account created
+- AC-2: Given weak password, When user submits, Then error shown
+- AC-3: Given user logs in, When session expires, Then redirect to login
+```
+
+Tests written:
+```typescript
+// AC-1 test
+it('should create account with valid email', ...)
+
+// AC-2 test
+it('should show error for weak password', ...)
+
+// AC-3 test
+it('should redirect to login when session expires', ...)
+```
+
+---
+
+### Phase 1: Baseline & Analysis - READ ONLY (15-30 min)
+
+**Goal:** Understand current state and plan upgrade
+
+**Why read-only:**
+- Understand impact before making changes
+- Plan fixes before breaking things
+- Identify high-risk areas
+
+**Steps:**
+1. Run `/speckit.analyze` → Document current spec-code alignment
+2. Run `npm outdated` → See what will change
+3. Analyze spec impact → Which specs affected by breaking changes?
+4. Generate upgrade plan → `.upgrade/UPGRADE_PLAN.md`
+5. Create tracking file → `.upgrade/stackshift-upgrade.yml`
+
+**Output:**
+- `.upgrade/UPGRADE_PLAN.md` - Complete upgrade plan
+- `.upgrade/spec-impact-analysis.json` - Which specs affected
+- `.upgrade/dependencies-before.txt` - Current versions
+- `.upgrade/stackshift-upgrade.yml` - Progress tracking
+
+**Example Spec Impact:**
+
+```json
+{
+  "react": {
+    "current": "17.0.2",
+    "latest": "19.2.0",
+    "breaking": true,
+    "affectedSpecs": [
+      "user-interface.md",  // Uses React components
+      "form-handling.md"    // State batching changes
+    ],
+    "risk": "HIGH"
+  }
+}
+```
+
+---
+
+### Phase 2: Upgrade & Spec-Guided Fixes (1-4 hours)
+
+**Goal:** Upgrade dependencies, fix breaking changes
+
+**Approach:**
+1. Create upgrade branch
+2. Upgrade ALL dependencies (`npx npm-check-updates -u`)
+3. Run tests → Detect failures
+4. For EACH failure:
+   - Load spec that test validates (from coverage map)
+   - Read acceptance criterion test is checking
+   - Fix code to preserve spec behavior
+   - Verify fix with test
+   - Commit incremental fix
+5. Continue until all tests pass
+
+**Spec-Guided Fix Example:**
+
+```
+Test fails: user-interface.test.ts - "renders user profile"
+
+1. Find spec: spec-coverage-map.json → "user-interface.md"
+
+2. Load spec:
+   cat .specify/memory/specifications/user-interface.md
+
+3. Find AC:
+   "AC-5: Given user profile data, When component renders,
+    Then displays name, email, and avatar"
+
+4. Fix code:
+   - React 19 changed rendering behavior
+   - Update component to preserve "displays name, email, avatar" behavior
+   - Ensure spec AC-5 still met
+
+5. Verify:
+   npm test -- user-interface.test.ts ✅
+```
+
+**Decision Matrix:**
+
+| Situation | Action |
+|-----------|--------|
+| Breaking change, spec clear | Fix code to match spec |
+| Breaking change, spec unclear | Run `/speckit.clarify` first |
+| Breaking change is improvement | Update spec + code (document why) |
+| Just API change, same behavior | Update code only (no spec change) |
+
+---
+
+### Phase 3: Validation & PR (15-30 min)
+
+**Goal:** Ensure specs match code, create PR
+
+**Steps:**
+1. Run `/speckit.analyze` → Validate no drift
+2. Verify coverage ≥85%
+3. Run full validation (tests, build, lint)
+4. Generate upgrade report
+5. Create PR with spec validation
+
+**Validation:**
+
+```bash
+# All must pass
+npm test              # ✅ All passing
+npm run build         # ✅ Successful
+npm run lint          # ✅ No errors
+/speckit.analyze      # ✅ All specs match code
+npm audit             # ✅ No high/critical
+
+# Coverage check
+COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+[ $(echo "$COVERAGE >= 85" | bc) -eq 1 ] && echo "✅ Coverage: ${COVERAGE}%" || echo "❌ Coverage too low"
+```
+
+---
+
+
+## Usage
+
+### Option 1: During Initial Analysis (Gear 1)
+
+When asked about Brownfield mode:
+
+```
+Would you like to enable Upgrade mode?
+
+A) Standard - Spec the current state as-is
+B) Upgrade - Spec current state + modernize dependencies
+
+Choose: B
+```
+
+This sets `modernize: true` in state. After Gear 6, modernize auto-triggers.
+
+### Option 2: After Gear 6
+
+If you completed Gears 1-6 without upgrade mode:
+
+```bash
+# Run the slash command
+/stackshift.modernize
+
+# Or invoke the skill
+"I want to modernize this application's dependencies"
+```
+
+---
+
+## Prerequisites
+
+Before running modernize:
+
+- ✅ Completed Gears 1-6 (Brownfield route)
+- ✅ Full spec coverage in `.specify/memory/specifications/`
+- ✅ `/speckit.*` commands available
+- ✅ Tests currently passing
+- ✅ Build currently working
+- ✅ Git working tree clean
+
+If any missing, fix first.
+
+---
+
+## Files Created
+
+```
+.upgrade/
+├── stackshift-upgrade.yml           # Progress tracking
+├── spec-coverage-map.json           # Tests → Specs mapping
+├── baseline-coverage.txt            # Pre-upgrade test coverage
+├── dependencies-before.txt          # Pre-upgrade versions
+├── UPGRADE_PLAN.md                  # Phase 1 analysis & plan
+├── spec-impact-analysis.json        # Which specs affected
+├── dependencies-after.txt           # Post-upgrade versions
+├── test-results-post-upgrade.txt    # Initial test run
+├── fixes-applied.log                # Each breaking change fix
+├── final-spec-analysis.txt          # /speckit.analyze results
+└── UPGRADE_REPORT.md                # Final comprehensive report
+```
+
+---
+
+## Success Criteria
+
+Upgrade complete when:
+
+- ✅ All dependencies at latest stable versions
+- ✅ Test coverage ≥85%
+- ✅ All tests passing
+- ✅ Build successful
+- ✅ Lint passing
+- ✅ `/speckit.analyze` shows all specs COMPLETE (no drift)
+- ✅ No high/critical security vulnerabilities
+- ✅ PR created with comprehensive report
+- ✅ Specs updated if behavior changed (documented why)
+
+---
+
+## Benefits
+
+**vs. Staying on Old Dependencies:**
+- ✅ Eliminate security vulnerabilities
+- ✅ Get modern tooling features
+- ✅ Improved performance
+- ✅ Active maintenance/support
+
+**vs. Full Rewrite (Greenfield):**
+- ✅ Much faster (days vs. months)
+- ✅ Lower risk (incremental changes)
+- ✅ Keep working code
+- ✅ Spec-guided safety net
+
+**vs. Manual Upgrade:**
+- ✅ Systematic process
+- ✅ Spec guidance on fixes
+- ✅ Comprehensive validation
+- ✅ Documented in upgrade report
+
+---
+
+## Example: Next.js 12 → 15 Upgrade
+
+```bash
+# Before upgrade
+next: 12.3.0
+react: 17.0.2
+test coverage: 78%
+
+# After Phase 0
+test coverage: 87% (added tests from spec ACs)
+
+# After Phase 1
+.upgrade/UPGRADE_PLAN.md created
+Identified: 5 high-risk specs affected by Next.js 15 changes
+
+# After Phase 2
+next: 15.1.0
+react: 19.2.0
+Breaking changes: 12 fixed (spec-guided)
+All tests passing ✅
+
+# After Phase 3
+/speckit.analyze: All specs validated ✅
+PR created with upgrade report
+```
+
+---
+
+## Related Commands
+
+- `/speckit.analyze` - Validate specs match code
+- `/speckit.clarify` - Resolve spec ambiguities
+- `/stackshift.modernize` - This command
+
+---
+
+**Remember:** Specs make upgrades safer. They're your contract defining how the system should behave. Preserve that contract while modernizing underneath.
diff --git a/plugin/claude-commands/speckit.analyze.md b/plugin/.claude/commands/speckit.analyze.md
similarity index 100%
rename from plugin/claude-commands/speckit.analyze.md
rename to plugin/.claude/commands/speckit.analyze.md
diff --git a/plugin/claude-commands/speckit.clarify.md b/plugin/.claude/commands/speckit.clarify.md
similarity index 100%
rename from plugin/claude-commands/speckit.clarify.md
rename to plugin/.claude/commands/speckit.clarify.md
diff --git a/plugin/claude-commands/speckit.implement.md b/plugin/.claude/commands/speckit.implement.md
similarity index 100%
rename from plugin/claude-commands/speckit.implement.md
rename to plugin/.claude/commands/speckit.implement.md
diff --git a/plugin/claude-commands/speckit.plan.md b/plugin/.claude/commands/speckit.plan.md
similarity index 100%
rename from plugin/claude-commands/speckit.plan.md
rename to plugin/.claude/commands/speckit.plan.md
diff --git a/plugin/claude-commands/speckit.specify.md b/plugin/.claude/commands/speckit.specify.md
similarity index 100%
rename from plugin/claude-commands/speckit.specify.md
rename to plugin/.claude/commands/speckit.specify.md
diff --git a/plugin/claude-commands/speckit.tasks.md b/plugin/.claude/commands/speckit.tasks.md
similarity index 100%
rename from plugin/claude-commands/speckit.tasks.md
rename to plugin/.claude/commands/speckit.tasks.md
diff --git a/plugin/.claude/commands/stackshift.modernize.md b/plugin/.claude/commands/stackshift.modernize.md
new file mode 100644
index 0000000..6b274a3
--- /dev/null
+++ b/plugin/.claude/commands/stackshift.modernize.md
@@ -0,0 +1,663 @@
+---
+name: stackshift.modernize
+description: Execute Brownfield Upgrade Mode - spec-driven dependency modernization workflow. Runs 4-phase process: spec-guided test coverage, baseline analysis, dependency upgrade with spec-guided fixes, and spec validation. Systematic 4-phase process for dependency modernization.
+---
+
+# StackShift Modernize: Spec-Driven Dependency Upgrade
+
+**Brownfield Upgrade Mode** - Execute after completing Gears 1-6
+
+Run this command to modernize all dependencies while using specs as your guide and safety net.
+
+---
+
+## Quick Status Check
+
+```bash
+# Check prerequisites
+echo "=== Prerequisites Check ==="
+
+# 1. Specs exist?
+SPEC_COUNT=$(find .specify/memory/specifications -name "*.md" 2>/dev/null | wc -l)
+echo "Specs found: $SPEC_COUNT"
+
+# 2. /speckit commands available?
+ls .claude/commands/speckit.*.md 2>/dev/null | wc -l | xargs -I {} echo "Speckit commands: {}"
+
+# 3. Tests passing?
+npm test --silent && echo "Tests: ✅ PASSING" || echo "Tests: ❌ FAILING"
+
+# 4. StackShift state?
+cat .stackshift-state.json 2>/dev/null | jq -r '"\(.path) - Gear \(.currentStep // "complete")"' || echo "No state file"
+
+if [ "$SPEC_COUNT" -lt 1 ]; then
+  echo "❌ No specs found. Run Gears 1-6 first."
+  exit 1
+fi
+```
+
+---
+
+## Phase 0: Spec-Guided Test Coverage Foundation
+
+**Goal:** 85%+ coverage using spec acceptance criteria as test blueprint
+
+**Time:** 30-90 minutes | **Mode:** Autonomous test writing
+
+### 0.1: Load Specifications & Baseline Coverage
+
+```bash
+echo "=== Phase 0: Spec-Guided Test Coverage ==="
+mkdir -p .upgrade
+
+# List all specs
+find .specify/memory/specifications -name "*.md" | sort | tee .upgrade/all-specs.txt
+SPEC_COUNT=$(wc -l < .upgrade/all-specs.txt)
+
+# Baseline coverage
+npm test -- --coverage --watchAll=false 2>&1 | tee .upgrade/baseline-coverage.txt
+COVERAGE=$(grep "All files" .upgrade/baseline-coverage.txt | grep -oE "[0-9]+\.[0-9]+" | head -1 || echo "0")
+
+echo "Specs: $SPEC_COUNT"
+echo "Coverage: ${COVERAGE}%"
+echo "Target: 85%"
+```
+
+### 0.2: Map Tests to Specs
+
+Create `.upgrade/spec-coverage-map.json` mapping each spec to its tests:
+
+```bash
+# For each spec, find which tests validate it
+# Track which acceptance criteria are covered vs. missing
+```
+
+### 0.3: Write Tests for Missing Acceptance Criteria
+
+**For each spec with missing coverage:**
+
+1. Read spec file
+2. Extract acceptance criteria section
+3. For each criterion without a test:
+   - Write test directly validating that criterion
+   - Use Given-When-Then from spec
+   - Ensure test actually validates behavior
+
+**Example:**
+
+```typescript
+// From spec: user-authentication.md
+// AC-3: "Given user logs in, When session expires, Then user redirected to login"
+
+describe('User Authentication - AC-3: Session Expiration', () => {
+  it('should redirect to login when session expires', async () => {
+    // Given: User is logged in
+    renderWithAuth(<Dashboard />, { authenticated: true });
+
+    // When: Session expires
+    await act(async () => {
+      expireSession(); // Helper to expire token
+    });
+
+    // Then: User redirected to login
+    await waitFor(() => {
+      expect(mockNavigate).toHaveBeenCalledWith('/login');
+    });
+  });
+});
+```
+
+### 0.4: Iterative Coverage Improvement
+
+```bash
+ITERATION=1
+TARGET=85
+MIN=80
+
+while (( $(echo "$COVERAGE < $TARGET" | bc -l) )); do
+  echo "Iteration $ITERATION: ${COVERAGE}%"
+
+  # Stop conditions
+  if (( $(echo "$COVERAGE >= $MIN" | bc -l) )) && [ $ITERATION -gt 5 ]; then
+    echo "✅ Min coverage reached"
+    break
+  fi
+
+  # Find spec with lowest coverage
+  # Write tests for missing acceptance criteria
+  # Prioritize P0 > P1 > P2 specs
+
+  npm test -- --coverage --watchAll=false --silent
+  PREV=$COVERAGE
+  COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+  GAIN=$(echo "$COVERAGE - $PREV" | bc)
+
+  # Diminishing returns?
+  if (( $(echo "$GAIN < 0.5" | bc -l) )) && (( $(echo "$COVERAGE >= $MIN" | bc -l) )); then
+    echo "✅ Diminishing returns (${GAIN}% gain)"
+    break
+  fi
+
+  ITERATION=$((ITERATION + 1))
+  [ $ITERATION -gt 10 ] && break
+done
+
+echo "✅ Phase 0 Complete: ${COVERAGE}% coverage"
+```
+
+### 0.5: Completion Marker
+
+```bash
+cat > .upgrade/stackshift-upgrade.yml <<EOF
+widget_name: $(cat package.json | jq -r '.name')
+route: brownfield-upgrade
+started: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+phase_0_complete: true
+phase_0_coverage: $COVERAGE
+specs_analyzed: $SPEC_COUNT
+all_tests_passing: true
+EOF
+```
+
+---
+
+## Phase 1: Baseline & Analysis (READ-ONLY)
+
+**Goal:** Understand current state, plan upgrade, identify spec impact
+
+**Time:** 15-30 minutes | **Mode:** Read-only analysis
+
+**🚨 NO FILE MODIFICATIONS IN PHASE 1**
+
+### 1.1: Spec-Code Baseline
+
+```bash
+echo "=== Phase 1: Baseline & Analysis ==="
+
+# Run spec analysis
+/speckit.analyze | tee .upgrade/baseline-spec-analysis.txt
+
+# Document which specs are COMPLETE/PARTIAL/MISSING
+grep -E "✅|⚠️|❌" .upgrade/baseline-spec-analysis.txt > .upgrade/baseline-spec-status.txt
+```
+
+### 1.2: Dependency Analysis
+
+```bash
+# Current dependencies
+npm list --depth=0 > .upgrade/dependencies-before.txt
+
+# Outdated packages
+npm outdated --json > .upgrade/outdated.json || echo "{}" > .upgrade/outdated.json
+
+# Count major upgrades
+MAJOR_COUNT=$(cat .upgrade/outdated.json | jq '[.[] | select(.current != .latest)] | length')
+echo "Major upgrades: $MAJOR_COUNT"
+```
+
+### 1.3: Spec Impact Analysis
+
+**For each major dependency upgrade, identify affected specs:**
+
+```bash
+# Create impact analysis
+cat > .upgrade/spec-impact-analysis.json <<'EOF'
+{
+  "react": {
+    "current": "17.0.2",
+    "latest": "19.2.0",
+    "breaking": true,
+    "affectedSpecs": [
+      "user-interface.md",
+      "form-handling.md"
+    ],
+    "acceptanceCriteria": [
+      "user-interface.md: AC-1, AC-3",
+      "form-handling.md: AC-2"
+    ],
+    "testFiles": [
+      "components/UserInterface.test.tsx"
+    ],
+    "risk": "HIGH"
+  }
+}
+EOF
+```
+
+### 1.4: Generate Upgrade Plan
+
+Create `.upgrade/UPGRADE_PLAN.md`:
+
+```markdown
+# Upgrade Plan
+
+## Summary
+- Dependencies to upgrade: ${MAJOR_COUNT} major versions
+- Specs affected: [count from impact analysis]
+- Risk level: [HIGH/MEDIUM/LOW]
+- Estimated effort: 2-4 hours
+
+## Critical Upgrades (Breaking Changes Expected)
+
+### react: 17.0.2 → 19.2.0
+- **Breaking Changes:**
+  - Automatic batching
+  - Hydration mismatches
+  - useId for SSR
+- **Affected Specs:**
+  - user-interface.md (AC-1, AC-3, AC-5)
+  - form-handling.md (AC-2, AC-4)
+- **Test Files:**
+  - components/UserInterface.test.tsx
+  - components/FormHandler.test.tsx
+- **Risk:** HIGH
+
+[Continue for all major upgrades...]
+
+## Spec Impact Summary
+
+### High-Risk Specs (Validate Carefully)
+1. user-interface.md - React changes affect all components
+2. form-handling.md - State batching changes
+
+### Low-Risk Specs (Quick Validation)
+[List specs unlikely to be affected]
+
+## Upgrade Sequence
+1. Update package.json versions
+2. npm install
+3. Fix TypeScript errors
+4. Fix test failures (spec-guided)
+5. Fix build errors
+6. Validate with /speckit.analyze
+```
+
+### 1.5: Update Tracking
+
+```bash
+cat >> .upgrade/stackshift-upgrade.yml <<EOF
+phase_1_complete: true
+phase_1_date: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+planned_major_upgrades: $MAJOR_COUNT
+high_risk_specs: [count]
+upgrade_plan_created: true
+EOF
+```
+
+---
+
+## Phase 2: Dependency Upgrade & Spec-Guided Fixes
+
+**Goal:** Upgrade all dependencies, fix breaking changes using specs
+
+**Time:** 1-4 hours | **Mode:** Implementation with spec guidance
+
+### 2.1: Pre-Flight Check
+
+```bash
+echo "=== Pre-Flight Health Check ==="
+
+npm test && echo "Tests: ✅" || (echo "Tests: ❌ STOP" && exit 1)
+npm run build && echo "Build: ✅" || (echo "Build: ❌ STOP" && exit 1)
+npm run lint 2>/dev/null && echo "Lint: ✅" || echo "Lint: ⚠️ OK"
+
+# Must be green to proceed
+```
+
+### 2.2: Create Upgrade Branch
+
+```bash
+git checkout -b upgrade/dependencies-to-latest
+git add .upgrade/
+git commit -m "docs: upgrade baseline and plan
+
+Phase 0: Coverage ${COVERAGE}%
+Phase 1: Analysis complete
+Specs: $SPEC_COUNT validated
+Ready for Phase 2
+"
+```
+
+### 2.3: Upgrade Dependencies
+
+```bash
+echo "=== Upgrading Dependencies ==="
+
+# Upgrade to latest
+npx npm-check-updates -u
+npm install
+
+# Update Node (optional but recommended)
+echo "22.21.0" > .nvmrc
+nvm install 22.21.0
+nvm use
+
+# Document changes
+npm list --depth=0 > .upgrade/dependencies-after.txt
+```
+
+### 2.4: Detect Breaking Changes
+
+```bash
+echo "=== Testing After Upgrade ==="
+
+npm test 2>&1 | tee .upgrade/test-results-post-upgrade.txt
+
+# Extract failures
+grep -E "FAIL|✕" .upgrade/test-results-post-upgrade.txt > .upgrade/failures.txt || true
+FAILURE_COUNT=$(wc -l < .upgrade/failures.txt)
+
+echo "Breaking changes: $FAILURE_COUNT test failures"
+```
+
+### 2.5: Spec-Guided Fix Loop
+
+**Autonomous iteration until all tests pass:**
+
+```bash
+ITERATION=1
+MAX_ITERATIONS=20
+
+while ! npm test --silent 2>&1; do
+  echo "=== Fix Iteration $ITERATION ==="
+
+  # Get first failing test
+  FAILING_TEST=$(npm test 2>&1 | grep -m 1 "FAIL" | grep -oE "[^ ]+\.test\.[jt]sx?" || echo "")
+
+  if [ -z "$FAILING_TEST" ]; then
+    echo "No specific test file found, checking for general errors..."
+    npm test 2>&1 | head -50
+    break
+  fi
+
+  echo "Failing test: $FAILING_TEST"
+
+  # Find spec from coverage map
+  SPEC=$(jq -r "to_entries[] | select(.value.testFiles[] | contains(\"$FAILING_TEST\")) | .key" .upgrade/spec-coverage-map.json || echo "")
+
+  if [ -n "$SPEC" ]; then
+    echo "Validates spec: $SPEC"
+    echo "Loading spec acceptance criteria..."
+    cat ".specify/memory/specifications/$SPEC" | grep -A 20 "Acceptance Criteria"
+  fi
+
+  # FIX THE BREAKING CHANGE
+  # - Read spec acceptance criteria
+  # - Understand intended behavior
+  # - Fix code to preserve that behavior
+  # - Run test to verify fix
+
+  # Log fix
+  echo "[$ITERATION] Fixed: $FAILING_TEST (spec: $SPEC)" >> .upgrade/fixes-applied.log
+
+  # Commit incremental fix
+  git add -A
+  git commit -m "fix: breaking change in $FAILING_TEST
+
+Spec: $SPEC
+Fixed to preserve acceptance criteria behavior
+"
+
+  ITERATION=$((ITERATION + 1))
+
+  if [ $ITERATION -gt $MAX_ITERATIONS ]; then
+    echo "⚠️ Max iterations reached - manual review needed"
+    break
+  fi
+done
+
+echo "✅ All tests passing"
+```
+
+### 2.6: Build & Lint
+
+```bash
+# Fix build
+npm run build || (echo "Fixing build errors..." && [fix build])
+
+# Fix lint (often ESLint 9 config changes)
+npm run lint || (echo "Fixing lint..." && [update eslint.config.js])
+```
+
+### 2.7: Phase 2 Complete
+
+```bash
+npm test && npm run build && npm run lint
+
+FINAL_COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+
+cat >> .upgrade/stackshift-upgrade.yml <<EOF
+phase_2_complete: true
+phase_2_date: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+test_coverage_after: $FINAL_COVERAGE
+fixes_applied: $(wc -l < .upgrade/fixes-applied.log)
+all_passing: true
+EOF
+```
+
+---
+
+## Phase 3: Spec Validation & PR
+
+**Goal:** Validate specs match code, create PR
+
+**Time:** 15-30 minutes
+
+### 3.1: Spec Validation
+
+```bash
+echo "=== Phase 3: Spec Validation ==="
+
+# Run spec analysis
+/speckit.analyze | tee .upgrade/final-spec-analysis.txt
+
+# Check for drift
+if grep -q "drift\|mismatch\|inconsistent" .upgrade/final-spec-analysis.txt; then
+  echo "⚠️ Drift detected - investigating..."
+  # Review and fix any drift
+fi
+```
+
+### 3.2: Generate Upgrade Report
+
+```bash
+# Create comprehensive report
+cat > .upgrade/UPGRADE_REPORT.md <<EOF
+# Dependency Upgrade Report
+
+**Date:** $(date)
+**Project:** $(cat package.json | jq -r '.name')
+**Route:** Brownfield Upgrade (StackShift Modernize)
+
+## Summary
+
+- **Dependencies Upgraded:** $(wc -l < .upgrade/dependencies-after.txt) packages
+- **Breaking Changes Fixed:** $(wc -l < .upgrade/fixes-applied.log)
+- **Test Coverage:** ${BASELINE_COVERAGE}% → ${FINAL_COVERAGE}%
+- **Spec Validation:** ✅ $(grep -c "✅ COMPLETE" .upgrade/final-spec-analysis.txt) specs validated
+- **Security:** $(npm audit --json | jq '.metadata.vulnerabilities.total // 0') vulnerabilities
+
+## Major Dependency Upgrades
+
+$(npm outdated --json | jq -r 'to_entries[] | "- **\(.key):** \(.value.current) → \(.value.latest)"')
+
+## Breaking Changes Fixed
+
+$(cat .upgrade/fixes-applied.log)
+
+## Spec Validation Results
+
+- **Total Specs:** $SPEC_COUNT
+- **Validated:** ✅ All passing
+- **Drift:** None detected
+- **Specs Updated:** [if any, list why]
+
+## Test Coverage
+
+- **Before:** ${BASELINE_COVERAGE}%
+- **After:** ${FINAL_COVERAGE}%
+- **Target:** 85% ✅
+
+## Security Improvements
+
+$(npm audit --json | jq -r '.vulnerabilities | to_entries[] | select(.value.via[0].severity == "high" or .value.via[0].severity == "critical") | "- \(.key): \(.value.via[0].title)"' || echo "No high/critical vulnerabilities")
+
+## Validation Checklist
+
+- [x] All tests passing
+- [x] Build successful
+- [x] Lint passing
+- [x] Coverage ≥85%
+- [x] Specs validated (/speckit.analyze)
+- [x] No high/critical vulnerabilities
+- [ ] Code review
+- [ ] Merge approved
+EOF
+
+cat .upgrade/UPGRADE_REPORT.md
+```
+
+### 3.3: Create Pull Request
+
+```bash
+# Final commit
+git add -A
+git commit -m "$(cat <<'EOF'
+chore: upgrade all dependencies to latest versions
+
+Spec-driven upgrade using StackShift modernize workflow.
+
+Phases Completed:
+- Phase 0: Test coverage ${BASELINE_COVERAGE}% → ${FINAL_COVERAGE}%
+- Phase 1: Analysis & planning
+- Phase 2: Upgrades & spec-guided fixes
+- Phase 3: Validation ✅
+
+See .upgrade/UPGRADE_REPORT.md for complete details.
+EOF
+)"
+
+# Push
+git push -u origin upgrade/dependencies-to-latest
+
+# Create PR
+gh pr create \
+  --title "chore: Upgrade all dependencies to latest versions" \
+  --body-file .upgrade/UPGRADE_REPORT.md
+```
+
+### 3.4: Final Tracking Update
+
+```bash
+cat >> .upgrade/stackshift-upgrade.yml <<EOF
+phase_3_complete: true
+upgrade_complete: true
+completion_date: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+pr_number: $(gh pr list --head upgrade/dependencies-to-latest --json number -q '.[0].number')
+pr_url: $(gh pr list --head upgrade/dependencies-to-latest --json url -q '.[0].url')
+final_status: SUCCESS
+EOF
+
+echo ""
+echo "🎉 ========================================="
+echo "   MODERNIZATION COMPLETE!"
+echo "========================================="
+echo ""
+echo "✅ Dependencies: All latest versions"
+echo "✅ Tests: All passing"
+echo "✅ Coverage: ${FINAL_COVERAGE}% (target: 85%)"
+echo "✅ Specs: Validated with /speckit.analyze"
+echo "✅ Build: Successful"
+echo "✅ Security: Vulnerabilities resolved"
+echo ""
+echo "📋 Report: .upgrade/UPGRADE_REPORT.md"
+echo "🔗 PR: $(gh pr list --head upgrade/dependencies-to-latest --json url -q '.[0].url')"
+echo ""
+```
+
+---
+
+## Key Differences from existing migration tools
+
+**existing migration tools :**
+- 3 phases (coverage, discovery, implementation)
+- Hardcoded versions (ws-scripts 22.0.0-beta.11, React 19.2.0)
+- Enzyme removal required
+- ESLint 9 flat config required
+- Batch processing 90+ widgets
+
+**StackShift modernize (Generic + Spec-driven):**
+- 4 phases (includes spec validation)
+- Latest versions (whatever is current)
+- **Spec acceptance criteria guide test writing**
+- **Specs guide breaking change fixes**
+- **Continuous spec validation**
+- Single repo focus
+
+**What we learned from existing migration tools:**
+- ✅ Phase 0 test coverage foundation
+- ✅ Read-only analysis phase
+- ✅ Iterative fix loop
+- ✅ Autonomous test writing
+- ✅ Comprehensive tracking files
+- ✅ Validation before proceeding
+
+**What we added for specs:**
+- ✅ Spec acceptance criteria = test blueprint
+- ✅ Spec impact analysis
+- ✅ Spec-guided breaking change fixes
+- ✅ /speckit.analyze validation
+- ✅ Spec-coverage mapping
+
+---
+
+## Success Criteria
+
+- ✅ All dependencies at latest stable
+- ✅ Test coverage ≥85%
+- ✅ All tests passing
+- ✅ Build successful
+- ✅ /speckit.analyze: No drift
+- ✅ PR created
+- ✅ Security issues resolved
+
+---
+
+## Troubleshooting
+
+**"Tests failing after upgrade"**
+```bash
+# 1. Find failing test
+npm test 2>&1 | grep FAIL
+
+# 2. Find spec
+jq '.[] | select(.testFiles[] | contains("failing-test.ts"))' .upgrade/spec-coverage-map.json
+
+# 3. Read spec acceptance criteria
+cat .specify/memory/specifications/[spec-name].md | grep -A 10 "Acceptance Criteria"
+
+# 4. Fix to match spec
+# 5. Verify with npm test
+```
+
+**"Can't reach 85% coverage"**
+```bash
+# Check which acceptance criteria lack tests
+cat .upgrade/spec-coverage-map.json | jq '.[] | select(.missingCoverage | length > 0)'
+
+# Write tests for those criteria
+```
+
+**"/speckit.analyze shows drift"**
+```bash
+# Review what changed
+/speckit.analyze
+
+# Fix code to match spec OR
+# Update spec if intentional improvement
+```
+
+---
+
+**Remember:** Specs are your north star. When breaking changes occur, specs tell you what behavior to preserve.
diff --git a/plugin/.claude/commands/stackshift.setup.md b/plugin/.claude/commands/stackshift.setup.md
new file mode 100644
index 0000000..5e23ac4
--- /dev/null
+++ b/plugin/.claude/commands/stackshift.setup.md
@@ -0,0 +1,133 @@
+---
+name: stackshift.setup
+description: Install StackShift and Spec Kit slash commands to this project for team use. Run this if you joined a project after StackShift analysis was completed.
+---
+
+# StackShift Setup - Install Slash Commands
+
+**Use this if:**
+- You cloned a project that uses StackShift
+- Slash commands aren't showing up (/speckit.*, /stackshift.*)
+- You want to add features but don't have the commands
+
+---
+
+## Step 1: Install Commands
+
+```bash
+# Create commands directory
+mkdir -p .claude/commands
+
+# Copy from StackShift plugin
+cp ~/.claude/plugins/stackshift/.claude/commands/speckit.*.md .claude/commands/
+cp ~/.claude/plugins/stackshift/.claude/commands/stackshift.*.md .claude/commands/
+
+# Verify
+ls .claude/commands/
+```
+
+**You should see:**
+- ✅ speckit.analyze.md
+- ✅ speckit.clarify.md
+- ✅ speckit.implement.md
+- ✅ speckit.plan.md
+- ✅ speckit.specify.md
+- ✅ speckit.tasks.md
+- ✅ stackshift.modernize.md
+- ✅ stackshift.setup.md
+
+---
+
+## Step 2: Update .gitignore
+
+**Ensure .gitignore allows .claude/commands/ to be committed:**
+
+```bash
+# Check if .gitignore exists
+if [ ! -f .gitignore ]; then
+  echo "Creating .gitignore..."
+  touch .gitignore
+fi
+
+# Add rules to allow slash commands
+cat >> .gitignore <<'EOF'
+
+# Claude Code - Allow slash commands (team needs these!)
+!.claude/
+!.claude/commands/
+!.claude/commands/*.md
+
+# Ignore user-specific Claude settings
+.claude/settings.json
+.claude/mcp-settings.json
+.claude/.storage/
+EOF
+
+echo "✅ .gitignore updated"
+```
+
+---
+
+## Step 3: Commit to Git
+
+```bash
+git add .claude/commands/
+git add .gitignore
+
+git commit -m "chore: add StackShift slash commands for team
+
+Adds /speckit.* and /stackshift.* slash commands.
+
+Commands installed:
+- /speckit.specify - Create feature specifications
+- /speckit.plan - Create technical implementation plans
+- /speckit.tasks - Generate task breakdowns
+- /speckit.implement - Execute implementation
+- /speckit.clarify - Resolve specification ambiguities
+- /speckit.analyze - Validate specs match code
+- /stackshift.modernize - Upgrade dependencies
+- /stackshift.setup - Install commands (this command)
+
+These enable spec-driven development for the entire team.
+All team members will have commands after cloning.
+"
+```
+
+---
+
+## Done!
+
+✅ Commands installed to project
+✅ .gitignore updated to allow commands
+✅ Commands committed to git
+✅ Team members will have commands when they clone
+
+**Type `/spec` and you should see all commands autocomplete!**
+
+---
+
+## For Project Leads
+
+**After running StackShift on a project, always:**
+
+1. ✅ Run `/stackshift.setup` (or manual Step 1-3 above)
+2. ✅ Commit .claude/commands/ to git
+3. ✅ Push to remote
+
+**This ensures everyone on your team has access to slash commands without individual setup.**
+
+---
+
+## Troubleshooting
+
+**"Commands still not showing up"**
+→ Restart Claude Code after installing
+
+**"Git says .claude/ is ignored"**
+→ Check .gitignore has `!.claude/commands/` rule
+
+**"Don't have StackShift plugin installed"**
+→ Install from your plugin marketplace or clone from GitHub
+
+**"StackShift plugin not in ~/.claude/plugins/"**
+→ Commands might be in different location, manually copy from project that has them
diff --git a/plugin/skills/analyze/SKILL.md b/plugin/skills/analyze/SKILL.md
index d451d39..bb903f3 100644
--- a/plugin/skills/analyze/SKILL.md
+++ b/plugin/skills/analyze/SKILL.md
@@ -175,7 +175,32 @@ D) All - Every feature (may take hours/days)
    → Longest runtime
 ```
 
-**Question 5: Target Stack** _(If Greenfield + Implementation selected)_
+**Question 5: Spec Output Location** _(If Greenfield selected)_
+```
+Where should specifications and documentation be written?
+
+A) Current repository (default)
+   → Specs in: ./docs/reverse-engineering/, ./.specify/
+   → Simple, everything in one place
+   → Good for: small teams, single repo
+
+B) New application repository
+   → Specs in: ~/git/my-new-app/.specify/
+   → Specs live with NEW codebase
+   → Good for: clean separation, NEW repo already exists
+
+C) Separate documentation repository
+   → Specs in: ~/git/my-app-docs/.specify/
+   → Central docs repo for multiple apps
+   → Good for: enterprise, multiple related apps
+
+D) Custom location
+   → Your choice: [specify path]
+
+Default: Current repository (A)
+```
+
+**Question 6: Target Stack** _(If Greenfield + Implementation selected)_
 ```
 What tech stack for the new implementation?
 
@@ -186,7 +211,7 @@ Examples:
 - Your choice: [specify your preferred stack]
 ```
 
-**Question 6: Build Location** _(If Greenfield + Implementation selected)_
+**Question 7: Build Location** _(If Greenfield + Implementation selected)_
 ```
 Where should the new application be built?
 
@@ -232,6 +257,32 @@ Claude Code Web users: This won't work in Web - use subfolder instead.
 
 All answers are stored in `.stackshift-state.json` and guide the entire workflow.
 
+**State file example:**
+```json
+{
+  "path": "greenfield",
+  "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)
+    "target_stack": "Next.js 15 + React 19 + Prisma",
+    "clarifications_strategy": "defer",
+    "implementation_scope": "p0_p1"
+  }
+}
+```
+
+**How it works:**
+
+**Spec Output Location:**
+- Gear 2 writes to: `{spec_output_location}/docs/reverse-engineering/`
+- Gear 3 writes to: `{spec_output_location}/.specify/memory/`
+- If not set: defaults to current directory
+
+**Build Location:**
+- Gear 6 writes code to: `{build_location}/src/`, `{build_location}/package.json`, etc.
+- Can be same as spec location OR different
+- If not set: defaults to `greenfield/` subfolder
+
 ### Implementing the Questionnaire
 
 Use the `AskUserQuestion` tool to collect all configuration upfront:
diff --git a/plugin/skills/create-specs/SKILL.md b/plugin/skills/create-specs/SKILL.md
index 091c587..c64bd03 100644
--- a/plugin/skills/create-specs/SKILL.md
+++ b/plugin/skills/create-specs/SKILL.md
@@ -49,6 +49,46 @@ Use this skill when:
 
 ---
 
+## Configuration Check (FIRST STEP!)
+
+**Load state file to determine output location:**
+
+```bash
+# Check route
+ROUTE=$(cat .stackshift-state.json | jq -r '.path')
+
+# Check spec output location (Greenfield may have custom location)
+SPEC_OUTPUT=$(cat .stackshift-state.json | jq -r '.config.spec_output_location // "."')
+
+echo "Route: $ROUTE"
+echo "Spec output: $SPEC_OUTPUT"
+
+# If custom location, ensure .specify directory exists there
+if [ "$SPEC_OUTPUT" != "." ]; then
+  echo "Creating .specify/ structure at custom location..."
+  mkdir -p "$SPEC_OUTPUT/.specify/memory/specifications"
+  mkdir -p "$SPEC_OUTPUT/.specify/memory/plans"
+  mkdir -p "$SPEC_OUTPUT/.specify/templates"
+  mkdir -p "$SPEC_OUTPUT/.specify/scripts"
+fi
+```
+
+**Where specs will be written:**
+
+| Route | Config | Specs Written To |
+|-------|--------|------------------|
+| Greenfield | spec_output_location set | `{spec_output_location}/.specify/memory/` |
+| Greenfield | Not set (default) | `./.specify/memory/` (current repo) |
+| Brownfield | Always current | `./.specify/memory/` (current repo) |
+
+**Common patterns:**
+- Same repo: `spec_output_location: "."` (default)
+- New repo: `spec_output_location: "~/git/my-new-app"`
+- Docs repo: `spec_output_location: "~/git/my-app-docs"`
+- Subfolder: `spec_output_location: "./new-version"`
+
+---
+
 ## 🤖 Execution Instructions
 
 **IMPORTANT**: This skill uses automated spec generation tools from F002.
diff --git a/plugin/skills/gap-analysis/SKILL.md b/plugin/skills/gap-analysis/SKILL.md
index 1e3751a..a91ae0e 100644
--- a/plugin/skills/gap-analysis/SKILL.md
+++ b/plugin/skills/gap-analysis/SKILL.md
@@ -1,44 +1,162 @@
 ---
 name: gap-analysis
-description: Use /speckit.analyze to compare specifications against implementation, then create prioritized gap list. Identifies incomplete features, missing UI components, technical debt, and inconsistencies between specs and code. This is Step 4 of 6 in the reverse engineering process.
+description: Route-aware gap analysis. For Brownfield - uses /speckit.analyze to compare specs against implementation. For Greenfield - validates spec completeness and asks about target tech stack for new implementation. This is Step 4 of 6 in the reverse engineering process.
 ---
 
-# Gap Analysis (with GitHub Spec Kit)
+# Gap Analysis (Route-Aware)
 
 **Step 4 of 6** in the Reverse Engineering to Spec-Driven Development process.
 
 **Estimated Time:** 15 minutes
 **Prerequisites:** Step 3 completed (`.specify/` directory exists with specifications)
-**Output:** Prioritized gap analysis and implementation roadmap
+**Output:** Route-specific analysis and implementation roadmap
 
 ---
 
-## When to Use This Skill
+## Route Detection (FIRST STEP!)
 
-Use this skill when:
-- You've completed Step 3 (Create Specifications)
-- Have specifications in `specs/`
-- Ready to identify what's missing or incomplete
-- Want to validate specs against actual implementation
+**CRITICAL:** Check which route was selected:
 
-**Trigger Phrases:**
-- "Analyze gaps in implementation"
-- "What's missing from the application?"
-- "Run speckit analyze"
-- "Compare specs to code"
+```bash
+# Load state file
+cat .stackshift-state.json | jq -r '.path'
+```
+
+**Routes:**
+- **greenfield** → Building NEW app (tech-agnostic specs)
+- **brownfield** → Managing EXISTING app (tech-prescriptive specs)
+
+**Based on route, this skill behaves differently!**
+
+---
+
+## Greenfield Route: Spec Completeness Analysis
+
+**Goal:** Validate specs are complete enough to build NEW application
+
+**NOT analyzing:** Old codebase (we're not fixing it, we're building new)
+**YES analyzing:** Spec quality, completeness, readiness
+
+### Step 1: Review Spec Completeness
+
+For each specification:
+
+```bash
+# Check each spec
+for spec in .specify/memory/specifications/*.md; do
+  echo "Analyzing: $(basename $spec)"
+
+  # Look for ambiguities
+  grep "\[NEEDS CLARIFICATION\]" "$spec" || echo "No clarifications needed"
+
+  # Check for acceptance criteria
+  grep -A 10 "Acceptance Criteria" "$spec" || echo "⚠️ No acceptance criteria"
+
+  # Check for user stories
+  grep -A 5 "User Stories" "$spec" || echo "⚠️ No user stories"
+done
+```
+
+### Step 2: Identify Clarification Needs
+
+**Common ambiguities in Greenfield specs:**
+- UI/UX details missing (what should it look like?)
+- Business rules unclear (what happens when...?)
+- Data relationships ambiguous (how do entities relate?)
+- Non-functional requirements vague (how fast? how secure?)
+
+**Mark with [NEEDS CLARIFICATION]:**
+```markdown
+### Photo Upload Feature
+- Users can upload photos [NEEDS CLARIFICATION: drag-drop or click-browse?]
+- Photos stored in cloud [NEEDS CLARIFICATION: S3, Cloudinary, or Vercel Blob?]
+- Max 10 photos [NEEDS CLARIFICATION: per fish or per tank?]
+```
+
+### Step 3: Ask About Target Tech Stack
+
+**For Greenfield, you're building NEW - need to choose stack!**
+
+```
+I've extracted the business logic into tech-agnostic specifications.
+Now we need to decide what to build the NEW application in.
+
+What tech stack would you like to use for the new implementation?
+
+Examples:
+A) Next.js 15 + React 19 + Prisma + PostgreSQL + Vercel
+B) Python FastAPI + SQLAlchemy + PostgreSQL + AWS ECS
+C) Ruby on Rails 7 + PostgreSQL + Heroku
+D) Your choice: [describe your preferred stack]
+```
+
+**Document choice** in Constitution for consistency.
+
+### Step 4: Create Implementation Roadmap
+
+**Greenfield roadmap focuses on BUILD ORDER:**
+
+```markdown
+# Greenfield Implementation Roadmap
+
+## Tech Stack Selected
+- Frontend: Next.js 15 + React 19
+- Backend: Next.js API Routes
+- Database: PostgreSQL + Prisma
+- Auth: NextAuth.js
+- Hosting: Vercel
+
+## Build Phases
+
+### Phase 1: Foundation (Week 1)
+- Set up Next.js project
+- Database schema with Prisma
+- Authentication system
+- Base UI components
+
+### Phase 2: Core Features (Week 2-3)
+- User management
+- Fish tracking
+- Tank management
+- Water quality logging
+
+### Phase 3: Advanced Features (Week 4)
+- Photo upload
+- Analytics dashboard
+- Notifications
+- Social features
+
+## All Features are ❌ MISSING
+(Greenfield = building from scratch)
+
+Ready to proceed to:
+- Step 5: Resolve clarifications
+- Step 6: Implement features in new stack
+```
 
 ---
 
-## What This Skill Does
+## Brownfield Route: Implementation Gap Analysis
+
+**Goal:** Identify gaps in EXISTING codebase implementation
+
+**YES analyzing:** Old codebase vs specs
+**Using:** /speckit.analyze to find gaps
+
+### Step 1: Run /speckit.analyze
+
+GitHub Spec Kit's built-in validation:
 
-Uses **GitHub Spec Kit's `/speckit.analyze`** command plus additional analysis to:
+```bash
+> /speckit.analyze
+```
 
-1. **Validate Consistency** - Check specs match implementation
-2. **Identify Gaps** - Find PARTIAL and MISSING features
-3. **Detect Inconsistencies** - Specs say one thing, code does another
-4. **Catalog Technical Debt** - Code quality, tests, documentation needs
-5. **Prioritize Implementation** - P0/P1/P2/P3 classification
-6. **Create Roadmap** - Phased implementation plan
+**What it checks:**
+- Specifications marked ✅ COMPLETE but implementation missing
+- Implementation exists but not documented in specs
+- Inconsistencies between related specifications
+- Conflicting requirements across specs
+- Outdated implementation status
 
 ---
 
@@ -438,4 +556,22 @@ Once gap analysis is complete, proceed to:
 
 ---
 
-**Remember:** This step combines GitHub Spec Kit's automated validation with manual gap analysis to create a complete picture of what needs to be built.
+## Route Comparison: What Gap Analysis Means
+
+| Aspect | Greenfield | Brownfield |
+|--------|-----------|-----------|
+| **Analyzing** | Spec completeness | Existing code vs specs |
+| **Goal** | Validate specs ready to build NEW | Find gaps in CURRENT implementation |
+| **/speckit.analyze** | Skip (no old code to compare) | Run (compare specs to code) |
+| **Gap Definition** | Missing requirements, ambiguities | Missing features, partial implementations |
+| **Roadmap** | Build order for NEW app | Fill gaps in EXISTING app |
+| **Tech Stack** | ASK user (choosing for new) | Already decided (current stack) |
+| **All Features** | ❌ MISSING (building from scratch) | Mix of ✅⚠️❌ (some exist) |
+
+**Key Insight:**
+- **Greenfield:** Specs describe WHAT to build (old code doesn't matter)
+- **Brownfield:** Specs describe current reality (validate against old code)
+
+---
+
+**Remember:** Check route first! Greenfield analyzes SPECS, Brownfield analyzes IMPLEMENTATION.
diff --git a/plugin/skills/reverse-engineer/SKILL.md b/plugin/skills/reverse-engineer/SKILL.md
index 358592a..53e43ab 100644
--- a/plugin/skills/reverse-engineer/SKILL.md
+++ b/plugin/skills/reverse-engineer/SKILL.md
@@ -67,27 +67,50 @@ This skill performs deep codebase analysis and generates **9 comprehensive docum
 
 ---
 
-## Path Detection
+## Configuration Check (FIRST STEP!)
 
-**FIRST:** Check which path was selected in Step 1:
+**Load state file to check:**
 
-```javascript
-// State file will contain:
+```bash
+# Check route
+ROUTE=$(cat .stackshift-state.json | jq -r '.path')
+echo "Route: $ROUTE"
+
+# Check spec output location (Greenfield only)
+SPEC_OUTPUT=$(cat .stackshift-state.json | jq -r '.config.spec_output_location // "."')
+echo "Writing specs to: $SPEC_OUTPUT"
+
+# Create output directories if needed
+if [ "$SPEC_OUTPUT" != "." ]; then
+  mkdir -p "$SPEC_OUTPUT/docs/reverse-engineering"
+  mkdir -p "$SPEC_OUTPUT/.specify/memory/specifications"
+fi
+```
+
+**State file structure:**
+```json
 {
-  "path": "greenfield" | "brownfield",
-  "metadata": {
-    "pathDescription": "..."
+  "path": "greenfield",
+  "config": {
+    "spec_output_location": "~/git/my-new-app",  // Where to write specs
+    "build_location": "~/git/my-new-app",         // Where to build code (Gear 6)
+    "target_stack": "Next.js 15..."
   }
 }
 ```
 
-**Based on path:**
+**File write locations:**
+
+| Route | Spec Output | Where Files Go |
+|-------|-------------|----------------|
+| **Greenfield** | Custom location | `{spec_output_location}/docs/`, `{spec_output_location}/.specify/` |
+| **Greenfield** | Not set (default) | `./docs/reverse-engineering/`, `./.specify/` (current repo) |
+| **Brownfield** | Always current repo | `./docs/reverse-engineering/`, `./.specify/` |
+
+**Based on route:**
 - **Greenfield** → Use `prompts/greenfield/02-reverse-engineer-business-logic.md`
 - **Brownfield** → Use `prompts/brownfield/02-reverse-engineer-full-stack.md`
-
-Or for manual users:
-- Check `.stackshift-state.json` for `path` field
-- Follow corresponding prompt file
+- **Osiris** → Use custom Osiris extraction workflow
 
 ---