Initial Analysis

Step 1 of 6 in the Reverse Engineering to Spec-Driven Development process.

Estimated Time: 5 minutes Output: analysis-report.md

When to Use This Skill

Use this skill when:

• Starting reverse engineering on a new or existing codebase

• Need to understand tech stack and architecture before making changes

• Want to assess project completeness and identify gaps

• First time analyzing this project with the toolkit

• User asks "analyze this codebase" or "what's in this project?"

Trigger Phrases:

• "Analyze this codebase"

• "What tech stack is this using?"

• "How complete is this application?"

• "Run initial analysis"

• "Start reverse engineering process"

What This Skill Does

This skill performs comprehensive initial analysis by:

• Asking which path you want - Greenfield (new app) or Brownfield (manage existing)

• Auto-detecting application context - Identifies programming languages, frameworks, and build systems

• Analyzing directory structure - Maps architecture patterns and key components

• Scanning existing documentation - Assesses current documentation quality

• Estimating completeness - Evaluates how complete the implementation is

• Generating analysis report - Creates analysis-report.md with all findings

• Storing path choice - Saves your selection to guide subsequent steps

Choose Your Path

FIRST: Determine which path aligns with your goals.

Path A: Greenfield (Build New App from Business Logic)

Use when:

• Building a new application based on existing app's business logic

• Migrating to a different tech stack

• Want flexibility in implementation choices

• Need platform-agnostic specifications

Result:

• Specifications focus on WHAT, not HOW

• Business requirements only

• Can implement in any technology

• Tech-stack agnostic

Example: "Extract the business logic from this Rails app so we can rebuild it in Next.js"

Path B: Brownfield (Manage Existing with Spec Kit)

Use when:

• Managing an existing codebase with GitHub Spec Kit

• Want spec-code validation with /speckit.analyze

• Planning upgrades or refactoring

• Need specs that match current implementation exactly

Result:

• Specifications include both WHAT and HOW

• Business logic + technical implementation

• Tech-stack prescriptive

• /speckit.analyze can validate alignment

Example: "Add GitHub Spec Kit to this Next.js app so we can manage it with specs going forward"

Batch Session Auto-Configuration

Before showing questions, check for batch session by walking up directories:

Function to find batch session file (walks up like .git search)

find_batch_session() { local current_dir="$(pwd)" while [[ "$current_dir" != "/" ]]; do # Stop at git root to prevent path traversal if [[ -d "$current_dir/.git" ]] && [[ ! -f "$current_dir/.stackshift-batch-session.json" ]]; then return 1 fi if [[ -f "$current_dir/.stackshift-batch-session.json" ]]; then echo "$current_dir/.stackshift-batch-session.json" return 0 fi current_dir="$(dirname "$current_dir")" done return 1 }

Check if batch session exists

BATCH_SESSION=$(find_batch_session) if [[ -n "$BATCH_SESSION" ]]; then echo "✅ Using batch session configuration from: $BATCH_SESSION" cat "$BATCH_SESSION" | jq '.answers'

Auto-apply answers from batch session

Skip questionnaire entirely

fi

If batch session exists:

• Walk up directory tree to find .stackshift-batch-session.json

• Load answers from found batch session file

• Show: "Using batch session configuration: route=brownfield, spec_output=~/git/specs, ..."

• Skip all questions below

• Proceed directly to analysis with pre-configured answers

• Save answers to local .stackshift-state.json as usual

Example directory structure:

~/git/my-platform/ ├── .stackshift-batch-session.json ← Batch session here ├── service-catalog/ │ └── [agent working here finds parent session] ├── service-auth/ │ └── [agent working here finds parent session] └── service-notifications/ └── [agent working here finds parent session]

If no batch session:

• Continue with normal questionnaire below

Step 1: Auto-Detect Application Type

Before asking questions, detect what kind of application this is:

Check repository name and structure

REPO_NAME=$(basename $(pwd)) PARENT_DIR=$(basename $(dirname $(pwd)))

Detection patterns (in priority order)

Add your own patterns here for your framework/architecture!

Monorepo service detection

if [[ "$PARENT_DIR" == "services" || "$PARENT_DIR" == "apps" ]] && [ -f "../../package.json" ]; then DETECTION="monorepo-service" echo "📦 Detected: Monorepo Service (services/* or apps/* directory)"

Nx workspace detection

elif [ -f "nx.json" ] || [ -f "../../nx.json" ]; then DETECTION="nx-app" echo "⚡ Detected: Nx Application"

Turborepo detection

elif [ -f "turbo.json" ] || [ -f "../../turbo.json" ]; then DETECTION="turborepo-package" echo "🚀 Detected: Turborepo Package"

Lerna package detection

elif [ -f "lerna.json" ] || [ -f "../../lerna.json" ]; then DETECTION="lerna-package" echo "📦 Detected: Lerna Package"

Generic application (default)

else DETECTION="generic" echo "🔍 Detected: Generic Application" fi

echo "Detection type: $DETECTION"

How Detection Patterns Work:

Detection identifies WHAT patterns to look for during analysis:

• monorepo-service: Look for shared packages, inter-service calls, monorepo structure

• nx-app: Look for project.json, workspace deps, Nx-specific patterns

• generic: Standard application analysis

Add Your Own Patterns:

Example: Custom framework detection

elif [[ "$REPO_NAME" =~ ^my-widget- ]]; then

DETECTION="my-framework-widget"

echo "🎯 Detected: My Framework Widget"

Detection determines what to analyze, but NOT how to spec it!

Step 2: Initial Questionnaire

Now that we know what kind of application this is, let's configure the extraction approach:

Question 1: Choose Your Route

Which path best aligns with your goals?

A) Greenfield: Extract for migration to new tech stack → Extract business logic only (tech-agnostic) → Can implement in any stack → Suitable for platform migrations → Example: Extract Rails app business logic → rebuild in Next.js

B) Brownfield: Extract for maintaining existing codebase → Extract business logic + technical details (tech-prescriptive) → Manage existing codebase with specs → Suitable for in-place improvements → Example: Add specs to Express API for ongoing maintenance

This applies to ALL detection types:

• Monorepo Service + Greenfield = Business logic for platform migration

• Monorepo Service + Brownfield = Full implementation for maintenance

• Nx App + Greenfield = Business logic for rebuild

• Nx App + Brownfield = Full Nx/Angular details for refactoring

• Generic + Greenfield = Business logic for rebuild

• Generic + Brownfield = Full implementation for management

Question 2: Implementation Framework

Which implementation framework do you want to use?

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

B) BMAD Auto-Pilot (Recommended for BMAD users) → Auto-generates BMAD artifacts (PRD, Architecture, Epics) from reverse-eng docs → Three modes: YOLO (fully automatic), Guided (ask on ambiguities), Interactive → Optionally hand off to BMAD agents for collaborative refinement → Best for: projects that want BMAD format without the full conversation

C) BMAD Method (Full collaborative workflow) → Uses same reverse-engineering docs as other frameworks → Hands off to BMAD's collaborative PM/Architect agents → BMAD creates PRD + Architecture through conversation → Best for: large projects needing deep collaborative refinement

D) Architecture Only → Generates architecture document with your constraints → Asks about tech stack, cloud, scale, hard constraints → Includes Mermaid diagrams, ADRs, infrastructure recommendations → Best for: when you already know what to build, need architecture

E) Portable Component Extraction → Extracts tech-agnostic epics + component spec → Abstract personas ([User], [Admin], [System]) → Output can be dropped into ANY BMAD project → Best for: reusable components, cross-project migration

After StackShift extracts documentation (Gear 2):

• All frameworks get the same 11 docs in docs/reverse-engineering/
• Spec Kit: Gears 3-6 create .specify/ specs, use /speckit.implement
• BMAD Auto-Pilot: /stackshift.bmad-synthesize generates BMAD artifacts automatically
• BMAD: Skip to Gear 6, hand off to *workflow-init with rich context
• Architecture Only: /stackshift.architect generates architecture.md with your constraints
• Portable Extraction: /stackshift.portable-extract generates portable epics + component spec

Question 3: Brownfield Mode (If Brownfield selected)

Do you want to upgrade dependencies after establishing specs?

A) Standard - Just create specs for current state → Document existing implementation as-is → Specs match current code exactly → Good for maintaining existing versions

B) Upgrade - Create specs + upgrade all dependencies → Spec current state first (100% coverage) → Then upgrade all dependencies to latest versions → Fix breaking changes with spec guidance → Improve test coverage to spec standards → End with modern, fully-spec'd application → Perfect for modernizing legacy apps

Upgrade mode includes:

• npm update / pip upgrade / go get -u (based on tech stack)
• Automated breaking change detection
• Test-driven upgrade fixes
• Spec updates for API changes
• Coverage improvement to 85%+

Question 4: Choose Your Transmission

How do you want to shift through the gears?

A) Manual - Review each gear before proceeding → You're in control → Stop at each step → Good for first-time users

B) Cruise Control - Shift through all gears automatically → Hands-free → Unattended execution → Good for experienced users or overnight runs

Question 5: Specification Thoroughness

How thorough should specification generation be in Gear 3?

A) Specs only (30 min - fast) → Generate specs for all features → Create plans manually with /speckit.plan as needed → Good for: quick assessment, flexibility

B) Specs + Plans (45-60 min - recommended) → Generate specs for all features → Auto-generate implementation plans for incomplete features → Ready for /speckit.tasks when you implement → Good for: most projects, balanced automation

C) Specs + Plans + Tasks (90-120 min - complete roadmap) → Generate specs for all features → Auto-generate plans for incomplete features → Auto-generate comprehensive task lists (300-500 lines each) → Ready for immediate implementation → Good for: large projects, maximum automation

Question 6: Clarifications Strategy (If Cruise Control selected)

How should [NEEDS CLARIFICATION] markers be handled?

A) Defer - Mark them, continue implementation around them → Fastest → Can clarify later with /speckit.clarify

B) Prompt - Stop and ask questions interactively → Most thorough → Takes longer

C) Skip - Only implement fully-specified features → Safest → Some features won't be implemented

Question 7: Implementation Scope (If Cruise Control selected)

What should be implemented in Gear 6?

A) None - Stop after specs are ready → Just want specifications → Will implement manually later

B) P0 only - Critical features only → Essential features → Fastest implementation

C) P0 + P1 - Critical + high-value features → Good balance → Most common choice

D) All - Every feature (may take hours/days) → Complete implementation → Longest runtime

Question 8: 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 9: Target Stack (If Greenfield + Implementation selected)

What tech stack for the new implementation?

Examples:

• Next.js 15 + TypeScript + Prisma + PostgreSQL
• Python/FastAPI + SQLAlchemy + PostgreSQL
• Go + Gin + GORM + PostgreSQL
• Your choice: [specify your preferred stack]

Question 10: Build Location (If Greenfield + Implementation selected)

Where should the new application be built?

A) Subfolder (recommended for Web) → Examples: greenfield/, v2/, new-app/ → Keeps old and new in same repo → Works in Claude Code Web

B) Separate directory (local only) → Examples: ~/git/my-new-app, ../my-app-v2 → Completely separate location → Requires local Claude Code (doesn't work in Web)

C) Replace in place (destructive) → Removes old code as new is built → Not recommended

Then ask for the specific path:

If subfolder (A):

Folder name within this repo? (default: greenfield/)

Examples: v2/, new-app/, nextjs-version/, rebuilt/ Your choice: [or press enter for greenfield/]

If separate directory (B):

Full path to new application directory:

Examples:

• ~/git/my-new-app
• ../my-app-v2
• /Users/you/projects/new-version

Your choice: [absolute or relative path]

⚠️ Note: Directory will be created if it doesn't exist. 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:

{ "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, bmad-autopilot, bmad, architect-only, or portable-extract "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" } }

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)

Examples:

• Monorepo Service + Greenfield = Extract business logic for platform migration

• Monorepo Service + Brownfield = Extract full implementation for maintenance

• Nx App + Greenfield = Extract business logic (framework-agnostic)

• Nx App + Brownfield = Extract full Nx/Angular implementation details

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

Present the questions conversationally and collect answers through natural dialogue. Ask questions one at a time (or in small groups of related questions) and wait for the user to respond before continuing.

Based on answers, ask follow-up questions conditionally:

• If cruise control: Ask clarifications strategy, implementation scope

• If greenfield + implementing: Ask target stack

• If greenfield subfolder: Ask folder name (or accept default: greenfield/)

• If BMAD Auto-Pilot selected: Skip spec thoroughness question (BMAD Synthesize handles artifact creation)

• If BMAD Auto-Pilot + cruise control: After Gear 2, runs /stackshift.bmad-synthesize in YOLO mode

• If BMAD selected: Skip spec thoroughness question (BMAD handles its own planning)

• If BMAD + cruise control: Gear 6 hands off to BMAD instead of /speckit.implement

• If Architecture Only selected: Skip spec thoroughness, clarifications, implementation scope questions

• If Architecture Only + cruise control: After Gear 2, runs /stackshift.architect

• If Portable Extraction selected: Skip spec thoroughness, clarifications, implementation scope questions

• If Portable Extraction + cruise control: After Gear 2, runs /stackshift.portable-extract

For custom folder name: Use free-text input or accept default.

Example:

StackShift: "What folder name for the new application? (default: greenfield/)"

User: "v2/" (or just press enter for greenfield/)

StackShift: "✅ New app will be built in: v2/"

Stored in state as:

{ "config": { "greenfield_location": "v2/" // Relative (subfolder) // OR "greenfield_location": "~/git/my-new-app" // Absolute (separate) } }

How it works:

Subfolder (relative path):

Building in: /Users/you/git/my-app/greenfield/

cd /Users/you/git/my-app

StackShift creates: ./greenfield/

Everything in one repo

Separate directory (absolute path):

Current repo: /Users/you/git/my-app

New app: /Users/you/git/my-new-app

StackShift:

- Reads specs from: /Users/you/git/my-app/.specify/

- Builds new app in: /Users/you/git/my-new-app/

- Two completely separate repos

Step 0: Install Slash Commands (FIRST!)

Before any analysis, ensure /speckit. commands are available:*

Create project commands directory

mkdir -p .claude/commands

Copy StackShift's slash commands to project

cp ~/.claude/plugins/stackshift/.claude/commands/speckit.*.md .claude/commands/ cp ~/.claude/plugins/stackshift/.claude/commands/stackshift.modernize.md .claude/commands/

Verify installation

ls .claude/commands/speckit.*.md

You should see:

• ✅ speckit.analyze.md

• ✅ speckit.clarify.md

• ✅ speckit.implement.md

• ✅ speckit.plan.md

• ✅ speckit.specify.md

• ✅ speckit.tasks.md

• ✅ stackshift.modernize.md

Why this is needed:

• Claude Code looks for slash commands in project .claude/commands/ directory

• Plugin-level commands are not automatically discovered

• This copies them to the current project so they're available

• Only needs to be done once per project

After copying:

• /speckit.* commands will be available for this project

• No need to restart Claude Code

• Commands work immediately

Critical: Commit Commands to Git

Add to .gitignore (or create if missing):

Allow .claude directory structure

!.claude/ !.claude/commands/

Track slash commands (team needs these!)

!.claude/commands/*.md

Ignore user-specific settings

.claude/settings.json .claude/mcp-settings.json

Then commit:

git add .claude/commands/ git commit -m "chore: add StackShift and Spec Kit slash commands

Adds /speckit.* and /stackshift.* slash commands for team use.

Commands added:

• /speckit.specify - Create feature specifications
• /speckit.plan - Create technical plans
• /speckit.tasks - Generate task lists
• /speckit.implement - Execute implementation
• /speckit.clarify - Resolve ambiguities
• /speckit.analyze - Validate specs match code
• /stackshift.modernize - Upgrade dependencies

These commands enable spec-driven development workflow. All team members will have access after cloning. "

Why this is critical:

• ✅ Teammates get commands when they clone

• ✅ Commands are versioned with project

• ✅ No setup needed for new team members

• ✅ Commands always available

Without committing:

• ❌ Each developer needs to run StackShift or manually copy

• ❌ Confusion: "Why don't slash commands work?"

• ❌ Inconsistent developer experience

Process Overview

The analysis follows 5 steps:

Step 1: Auto-Detect Application Context

• Run detection commands for all major languages/frameworks

• Identify the primary technology stack

• Extract version information

Step 2: Extract Core Metadata

• Application name from manifest or directory

• Version number from package manifests

• Description from README or manifest

• Git repository URL if available

• Technology stack summary

Step 3: Analyze Directory Structure

• Identify architecture patterns (MVC, microservices, monolith, etc.)

• Find configuration files

• Count source files by type

• Map key components (backend, frontend, database, API, infrastructure)

Step 4: Check for Existing Documentation

• Scan for docs folders and markdown files

• Assess documentation quality

• Identify what's documented vs. what's missing

Step 5: Assess Completeness

• Look for placeholder files (TODO, WIP, etc.)

• Check README for mentions of incomplete features

• Count test files and estimate test coverage

• Verify deployment/CI setup

Output Format

This skill generates analysis-report.md in the project root with:

• Application Metadata - Name, version, description, repository

• Technology Stack - Languages, frameworks, libraries, build system

• Architecture Overview - Directory structure, key components

• Existing Documentation - What docs exist and their quality

• Completeness Assessment - Estimated % completion with evidence

• Source Code Statistics - File counts, lines of code estimates

• Recommended Next Steps - Focus areas for reverse engineering

• Notes - Additional observations

Success Criteria

After running this skill, you should have:

• ✅ analysis-report.md file created in project root

• ✅ Technology stack clearly identified

• ✅ Directory structure and architecture understood

• ✅ Completeness estimated (% done for backend, frontend, tests, docs)

• ✅ Ready to proceed to Step 2 (Reverse Engineer)

Next Step

Once analysis-report.md is created and reviewed, proceed to:

Step 2: Reverse Engineer - Use the reverse-engineer skill to generate comprehensive documentation.

Common Workflows

New Project Analysis:

• User asks to analyze codebase

• Run all detection commands in parallel

• Generate analysis report

• Present summary and ask if ready for Step 2

Re-analysis:

• Check if analysis-report.md already exists

• Ask user if they want to update it or skip to Step 2

• If updating, re-run analysis and show diff

Partial Analysis:

• User already knows tech stack

• Skip detection, focus on completeness assessment

• Generate abbreviated report

Technical Notes

• Parallel execution: Run all language detection commands in parallel for speed

• Error handling: Missing manifest files are normal (return empty), don't error

• File limits: Use head to limit output for large codebases

• Exclusions: Always exclude node_modules, vendor, .git, build, dist, target

• Platform compatibility: Commands work on macOS, Linux, WSL

Example Invocation

When a user says:

"I need to reverse engineer this application and create specifications. Let's start."

This skill auto-activates and:

• Detects tech stack (e.g., Next.js, TypeScript, Prisma, AWS)

• Analyzes directory structure (identifies app/, lib/, prisma/, infrastructure/)

• Scans documentation (finds README.md, basic setup docs)

• Assesses completeness (estimates backend 100%, frontend 60%, tests 30%)

• Generates analysis-report.md

• Presents summary and recommends proceeding to Step 2

Remember: This is Step 1 of 6. After analysis, you'll proceed to reverse-engineer, create-specs, gap-analysis, complete-spec, and implement. Each step builds on the previous one.