Initial commit

2025-11-30 08:29:31 +08:00
commit f8e59e249c
39 changed files with 12575 additions and 0 deletions
--- a/skills/analyze/SKILL.md
+++ b/skills/analyze/SKILL.md
@@ -0,0 +1,759 @@
+---
+name: analyze
+description: Perform initial analysis of a codebase - detect tech stack, directory structure, and completeness. This is Step 1 of the 6-step reverse engineering process that transforms incomplete applications into spec-driven codebases. Automatically detects programming languages, frameworks, architecture patterns, and generates comprehensive analysis-report.md. Use when starting reverse engineering on any codebase.
+---
+
+# 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:
+
+1. **Asking which path you want** - Greenfield (new app) or Brownfield (manage existing)
+2. **Auto-detecting application context** - Identifies programming languages, frameworks, and build systems
+3. **Analyzing directory structure** - Maps architecture patterns and key components
+4. **Scanning existing documentation** - Assesses current documentation quality
+5. **Estimating completeness** - Evaluates how complete the implementation is
+6. **Generating analysis report** - Creates `analysis-report.md` with all findings
+7. **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:**
+
+```bash
+# Function to find batch session file (walks up like .git search)
+find_batch_session() {
+  local current_dir="$(pwd)"
+  while [[ "$current_dir" != "/" ]]; do
+    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:**
+1. Walk up directory tree to find `.stackshift-batch-session.json`
+2. Load answers from found batch session file
+3. Show: "Using batch session configuration: route=osiris, spec_output=~/git/specs, ..."
+4. Skip all questions below
+5. Proceed directly to analysis with pre-configured answers
+6. Save answers to local `.stackshift-state.json` as usual
+
+**Example directory structure:**
+```
+~/git/osiris/
+  ├── .stackshift-batch-session.json  ← Batch session here
+  ├── ws-vehicle-details/
+  │   └── [agent working here finds parent session]
+  ├── ws-hours/
+  │   └── [agent working here finds parent session]
+  └── ws-contact/
+      └── [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:**
+
+```bash
+# 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:**
+```bash
+# 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: 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 3: 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 4: 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 5: 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 6: 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 7: 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?
+
+Examples:
+- Next.js 15 + TypeScript + Prisma + PostgreSQL
+- Python/FastAPI + SQLAlchemy + PostgreSQL
+- Go + Gin + GORM + PostgreSQL
+- Your choice: [specify your preferred stack]
+```
+
+**Question 7: 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:**
+```json
+{
+  "detection_type": "monorepo-service",  // What kind of app: monorepo-service, nx-app, generic, etc.
+  "route": "greenfield",                  // How to spec it: greenfield or brownfield
+  "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)
+
+**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
+
+Use the `AskUserQuestion` tool to collect all configuration upfront:
+
+```typescript
+// Example implementation
+AskUserQuestion({
+  questions: [
+    {
+      question: "Which route best aligns with your goals?",
+      header: "Route",
+      multiSelect: false,
+      options: [
+        {
+          label: "Greenfield",
+          description: "Shift to new tech stack - extract business logic only (tech-agnostic)"
+        },
+        {
+          label: "Brownfield",
+          description: "Manage existing code with specs - extract full implementation (tech-prescriptive)"
+        }
+      ]
+    },
+    {
+      question: "How do you want to shift through the gears?",
+      header: "Transmission",
+      multiSelect: false,
+      options: [
+        {
+          label: "Manual",
+          description: "Review each gear before proceeding - you're in control"
+        },
+        {
+          label: "Cruise Control",
+          description: "Shift through all gears automatically - hands-free, unattended execution"
+        }
+      ]
+    }
+  ]
+});
+
+// Then 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/)
+```
+
+**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:
+```json
+{
+  "config": {
+    "greenfield_location": "v2/"  // Relative (subfolder)
+    // OR
+    "greenfield_location": "~/git/my-new-app"  // Absolute (separate)
+  }
+}
+```
+
+**How it works:**
+
+**Subfolder (relative path):**
+```bash
+# 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):**
+```bash
+# 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:**
+
+```bash
+# 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):**
+
+```bash
+# 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:**
+
+```bash
+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
+
+See [operations/detect-stack.md](operations/detect-stack.md) for detailed instructions.
+
+### 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)
+
+See [operations/directory-analysis.md](operations/directory-analysis.md) for detailed instructions.
+
+### Step 4: Check for Existing Documentation
+- Scan for docs folders and markdown files
+- Assess documentation quality
+- Identify what's documented vs. what's missing
+
+See [operations/documentation-scan.md](operations/documentation-scan.md) for detailed instructions.
+
+### 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
+
+See [operations/completeness-assessment.md](operations/completeness-assessment.md) for detailed instructions.
+
+---
+
+## 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
+
+See [operations/generate-report.md](operations/generate-report.md) for the complete template.
+
+---
+
+## 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.
+
+---
+
+## Principles
+
+For guidance on performing effective initial analysis:
+- [principles/multi-language-detection.md](principles/multi-language-detection.md) - Detecting polyglot codebases
+- [principles/architecture-pattern-recognition.md](principles/architecture-pattern-recognition.md) - Identifying common patterns
+
+---
+
+## Common Workflows
+
+**New Project Analysis:**
+1. User asks to analyze codebase
+2. Run all detection commands in parallel
+3. Generate analysis report
+4. Present summary and ask if ready for Step 2
+
+**Re-analysis:**
+1. Check if analysis-report.md already exists
+2. Ask user if they want to update it or skip to Step 2
+3. If updating, re-run analysis and show diff
+
+**Partial Analysis:**
+1. User already knows tech stack
+2. Skip detection, focus on completeness assessment
+3. 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:
+1. Detects tech stack (e.g., Next.js, TypeScript, Prisma, AWS)
+2. Analyzes directory structure (identifies app/, lib/, prisma/, infrastructure/)
+3. Scans documentation (finds README.md, basic setup docs)
+4. Assesses completeness (estimates backend 100%, frontend 60%, tests 30%)
+5. Generates analysis-report.md
+6. 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.