zhongwei/gh-jschulte-claude-plugins-stackshift
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:29:31 +08:00
commit f8e59e249c
39 changed files with 12575 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

759
skills/analyze/SKILL.md Normal file
View File

@@ -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.

198
skills/analyze/batch-session-state.ts Normal file
View File

@@ -0,0 +1,198 @@
/**
* Batch Session State Management
*
* Stores answers from initial batch configuration and reuses them
* across all widgets in the batch session, eliminating repetitive questions.
*/
import * as fs from 'fs';
import * as path from 'path';
export interface BatchSessionAnswers {
detection_type?: 'generic' | 'monorepo-service' | 'nx-app' | 'turborepo-package' | 'lerna-package';
route?: 'greenfield' | 'brownfield';
brownfield_mode?: 'standard' | 'upgrade';
transmission?: 'manual' | 'cruise-control';
clarifications_strategy?: 'defer' | 'prompt' | 'skip';
implementation_scope?: 'none' | 'p0' | 'p0_p1' | 'all';
spec_output_location?: string;
target_stack?: string;
build_location?: string;
build_location_type?: 'subfolder' | 'separate' | 'replace';
}
export interface BatchSessionState {
sessionId: string;
startedAt: string;
batchRootDirectory: string;
totalRepos: number;
batchSize: number;
answers: BatchSessionAnswers;
processedRepos: string[];
}
const BATCH_SESSION_FILENAME = '.stackshift-batch-session.json';
/**
* Find batch session file by checking current directory and walking up
* Similar to how .git directories are found
*/
function findBatchSessionFile(startDir: string = process.cwd()): string | null {
let currentDir = path.resolve(startDir);
const root = path.parse(currentDir).root;
while (currentDir !== root) {
const batchSessionPath = path.join(currentDir, BATCH_SESSION_FILENAME);
if (fs.existsSync(batchSessionPath)) {
return batchSessionPath;
}
currentDir = path.dirname(currentDir);
}
return null;
}
/**
* Get batch session file path for a directory
*/
function getBatchSessionPath(directory: string = process.cwd()): string {
return path.join(directory, BATCH_SESSION_FILENAME);
}
/**
* Create a new batch session with initial answers
*/
export function createBatchSession(
batchRootDirectory: string,
totalRepos: number,
batchSize: number,
answers: BatchSessionAnswers
): BatchSessionState {
const session: BatchSessionState = {
sessionId: `batch-${Date.now()}`,
startedAt: new Date().toISOString(),
batchRootDirectory: path.resolve(batchRootDirectory),
totalRepos,
batchSize,
answers,
processedRepos: []
};
const sessionPath = getBatchSessionPath(batchRootDirectory);
fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));
return session;
}
/**
* Get current batch session if it exists
* Searches current directory and walks up to find batch session
*/
export function getBatchSession(startDir: string = process.cwd()): BatchSessionState | null {
try {
const sessionPath = findBatchSessionFile(startDir);
if (!sessionPath) {
return null;
}
const content = fs.readFileSync(sessionPath, 'utf-8');
return JSON.parse(content);
} catch (error) {
console.error('Error reading batch session:', error);
return null;
}
}
/**
* Check if we're currently in a batch session
* Searches current directory and walks up
*/
export function hasBatchSession(startDir: string = process.cwd()): boolean {
return findBatchSessionFile(startDir) !== null;
}
/**
* Update batch session with processed repo
*/
export function markRepoProcessed(repoName: string, startDir: string = process.cwd()): void {
const sessionPath = findBatchSessionFile(startDir);
if (!sessionPath) {
return;
}
try {
const content = fs.readFileSync(sessionPath, 'utf-8');
const session: BatchSessionState = JSON.parse(content);
if (!session.processedRepos.includes(repoName)) {
session.processedRepos.push(repoName);
}
fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2));
} catch (error) {
console.error('Error updating batch session:', error);
}
}
/**
* Clear batch session in specific directory
*/
export function clearBatchSession(directory: string = process.cwd()): boolean {
try {
const sessionPath = getBatchSessionPath(directory);
if (fs.existsSync(sessionPath)) {
fs.unlinkSync(sessionPath);
return true;
}
return false;
} catch (error) {
console.error('Error clearing batch session:', error);
return false;
}
}
/**
* Get batch session progress
*/
export function getBatchProgress(startDir: string = process.cwd()): string {
const session = getBatchSession(startDir);
if (!session) {
return 'No active batch session';
}
const processed = session.processedRepos.length;
const total = session.totalRepos;
const percentage = Math.round((processed / total) * 100);
return `Batch Progress: ${processed}/${total} repos (${percentage}%)`;
}
/**
* Format batch session for display
*/
export function formatBatchSession(session: BatchSessionState): string {
const duration = Date.now() - new Date(session.startedAt).getTime();
const hours = Math.floor(duration / 3600000);
const minutes = Math.floor((duration % 3600000) / 60000);
return `
📦 Active Batch Session
Session ID: ${session.sessionId}
Batch Root: ${session.batchRootDirectory}
Started: ${new Date(session.startedAt).toLocaleString()}
Duration: ${hours}h ${minutes}m
Total Repos: ${session.totalRepos}
Batch Size: ${session.batchSize}
Processed: ${session.processedRepos.length}/${session.totalRepos}
Configuration:
Route: ${session.answers.route || 'not set'}
Transmission: ${session.answers.transmission || 'not set'}
Spec Output: ${session.answers.spec_output_location || 'current directory'}
Build Location: ${session.answers.build_location || 'greenfield/'}
Target Stack: ${session.answers.target_stack || 'not set'}
Session File: ${session.batchRootDirectory}/${BATCH_SESSION_FILENAME}
`.trim();
}

381
skills/analyze/operations/completeness-assessment.md Normal file
View File

@@ -0,0 +1,381 @@
# Completeness Assessment
Assess how complete the application implementation is.
## Overview
Estimate the percentage completion for:
- Overall application
- Backend implementation
- Frontend implementation
- Test coverage
- Documentation
- Deployment/Infrastructure
---
## Evidence Collection
### Placeholder Files
Look for files indicating incomplete work:
```bash
# Find TODO/WIP/PLACEHOLDER files
find . -iname "*todo*" -o -iname "*wip*" -o -iname "*placeholder*" -o -iname "*draft*" 2>/dev/null \
| grep -v "node_modules\|\.git"
# Find empty or near-empty files
find . -type f -size 0 2>/dev/null | grep -v "node_modules\|\.git\|\.keep"
# Files with just placeholders
find . -type f -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null \
| xargs grep -l "TODO\|FIXME\|PLACEHOLDER\|XXX\|HACK" \
| head -20
```
### README Mentions
```bash
# Search README for incomplete features
grep -i "todo\|wip\|work in progress\|coming soon\|not yet\|planned\|roadmap\|incomplete" README.md 2>/dev/null
```
### Code Comments
```bash
# Count TODO/FIXME comments
grep -r "TODO\|FIXME\|XXX\|HACK" src/ 2>/dev/null | wc -l
# Show sample TODOs
grep -r "TODO\|FIXME" src/ 2>/dev/null | head -10
```
---
## Component-Specific Assessment
### Backend Completeness
**Check for:**
1. **API Endpoints**
```bash
# Count API routes
find . -path "*/api/*" -o -path "*/routes/*" 2>/dev/null | wc -l
# Find routes with placeholder responses
grep -r "res.json({})\|return {}\|NotImplementedError" src/api/ src/routes/ 2>/dev/null
```
2. **Business Logic**
```bash
# Count service/controller files
find . -path "*/services/*" -o -path "*/controllers/*" 2>/dev/null | wc -l
# Find stub implementations
grep -r "throw new Error.*not implemented\|NotImplementedError" src/ 2>/dev/null
```
3. **Database**
```bash
# Check if migrations are applied
ls -la prisma/migrations/ 2>/dev/null | wc -l
# Check for empty seed files
ls -la prisma/seed.ts 2>/dev/null
```
4. **Authentication**
```bash
# Check for auth middleware
find . -name "*auth*" -o -name "*session*" | grep -v node_modules
# Look for JWT/session handling
grep -r "jwt\|jsonwebtoken\|express-session\|passport" package.json src/ 2>/dev/null
```
**Estimate:**
- 100% = All endpoints implemented, tested, documented
- 75% = All endpoints exist, some missing tests/validation
- 50% = Core endpoints done, advanced features missing
- 25% = Skeleton only, most logic unimplemented
- 0% = No backend implementation
### Frontend Completeness
**Check for:**
1. **Pages/Views**
```bash
# Count pages
find . -path "*/pages/*" -o -path "*/app/*" -o -path "*/views/*" 2>/dev/null \
| grep -E "\.(tsx?|jsx?|vue)$" | wc -l
# Find placeholder pages
grep -r "Coming Soon\|Under Construction\|TODO\|Placeholder" app/ pages/ components/ 2>/dev/null
```
2. **Components**
```bash
# Count components
find . -path "*/components/*" | grep -E "\.(tsx?|jsx?|vue)$" | wc -l
# Find stub components
grep -r "return null\|return <div>TODO\|placeholder" components/ 2>/dev/null
```
3. **Styling**
```bash
# Check for styling setup
ls -la tailwind.config.* 2>/dev/null
find . -name "*.css" -o -name "*.scss" 2>/dev/null | head -10
# Check if components are styled
grep -r "className\|style=" components/ 2>/dev/null | wc -l
```
4. **State Management**
```bash
# Check for state management
grep -r "redux\|zustand\|recoil\|jotai\|mobx" package.json 2>/dev/null
grep -r "createContext\|useContext" src/ app/ 2>/dev/null | wc -l
```
**Estimate:**
- 100% = All pages implemented, styled, interactive
- 75% = All pages exist, some missing polish/interactivity
- 50% = Core pages done, advanced features missing
- 25% = Skeleton pages, minimal styling/functionality
- 0% = No frontend implementation
### Testing Completeness
**Check for:**
1. **Test Files**
```bash
# Count test files
find . -name "*.test.*" -o -name "*.spec.*" 2>/dev/null | wc -l
# Count tests
grep -r "test(\|it(\|describe(" tests/ __tests__/ src/ 2>/dev/null | wc -l
```
2. **Test Coverage**
```bash
# Check for coverage reports
ls -la coverage/ 2>/dev/null
# Check test configuration
ls -la jest.config.* vitest.config.* 2>/dev/null
```
3. **Test Types**
```bash
# Unit tests
find . -path "*/tests/unit/*" -o -name "*.unit.test.*" 2>/dev/null | wc -l
# Integration tests
find . -path "*/tests/integration/*" -o -name "*.integration.test.*" 2>/dev/null | wc -l
# E2E tests
find . -path "*/tests/e2e/*" -o -name "*.e2e.*" -o -name "cypress/" -o -name "playwright/" 2>/dev/null
```
**Estimate:**
- 100% = >80% code coverage, unit + integration + E2E tests
- 75% = 60-80% coverage, unit + integration tests
- 50% = 40-60% coverage, mostly unit tests
- 25% = <40% coverage, sparse unit tests
- 0% = No tests
### Documentation Completeness
Use findings from [documentation-scan.md](documentation-scan.md):
**Estimate:**
- 100% = README, API docs, architecture, deployment, developer guide, all current
- 75% = README + API docs + some architecture/deployment docs
- 50% = Good README, partial API docs
- 25% = Basic README only
- 0% = No meaningful documentation
### Infrastructure/Deployment Completeness
**Check for:**
1. **Infrastructure as Code**
```bash
# Check for IaC files
find . -name "*.tf" -o -name "serverless.yml" -o -name "cdk.json" 2>/dev/null
# Count resources defined
grep -r "resource\|AWS::" infrastructure/ terraform/ 2>/dev/null | wc -l
```
2. **CI/CD**
```bash
# GitHub Actions
ls -la .github/workflows/ 2>/dev/null
# Other CI/CD
ls -la .gitlab-ci.yml .circleci/config.yml .travis.yml 2>/dev/null
```
3. **Environment Configuration**
```bash
# Environment files
ls -la .env.example .env.template 2>/dev/null
# Environment validation
grep -r "dotenv\|env-var\|envalid" package.json src/ 2>/dev/null
```
4. **Deployment Scripts**
```bash
# Deployment scripts
find . -name "deploy.sh" -o -name "deploy.js" -o -name "deploy.ts" 2>/dev/null
# Package scripts
grep "deploy\|build\|start\|test" package.json 2>/dev/null
```
**Estimate:**
- 100% = Full IaC, CI/CD, monitoring, auto-deployment
- 75% = IaC + CI/CD, manual deployment
- 50% = Basic CI/CD, no IaC
- 25% = Manual deployment only
- 0% = No deployment setup
---
## Overall Completeness Calculation
Calculate weighted average:
```
Overall = (Backend × 0.3) + (Frontend × 0.3) + (Tests × 0.2) + (Docs × 0.1) + (Infra × 0.1)
```
Example:
- Backend: 100%
- Frontend: 60%
- Tests: 30%
- Docs: 40%
- Infra: 80%
Overall = (100 × 0.3) + (60 × 0.3) + (30 × 0.2) + (40 × 0.1) + (80 × 0.1)
= 30 + 18 + 6 + 4 + 8
= **66%**
---
## Missing Components Identification
List what's missing or incomplete:
**High Priority:**
- [ ] Frontend: User profile page (placeholder only)
- [ ] Frontend: Analytics dashboard (not started)
- [ ] Backend: Email notification service (stub)
- [ ] Tests: Integration tests for API (0 tests)
- [ ] Docs: API specification (no OpenAPI)
**Medium Priority:**
- [ ] Frontend: Mobile responsive design (partially done)
- [ ] Backend: Rate limiting (not implemented)
- [ ] Tests: E2E tests (no framework setup)
- [ ] Infra: Monitoring/alerting (not configured)
**Low Priority:**
- [ ] Frontend: Dark mode (placeholder toggle)
- [ ] Backend: Admin panel API (not started)
- [ ] Docs: Troubleshooting guide (missing)
---
## Evidence Summary
Document the evidence used for estimates:
```markdown
### Evidence
**Backend (100%):**
- 17 Lambda functions fully implemented
- All database models defined and migrated
- Authentication and authorization complete
- API endpoints tested and documented
**Frontend (60%):**
- 8 of 12 planned pages implemented
- Core components complete (Header, Footer, Nav)
- 4 pages are placeholder/TODO:
- Analytics Dashboard (TODO comment in code)
- User Settings (returns "Coming Soon")
- Admin Panel (not started)
- Reports (skeleton only)
- Styling ~80% complete
**Tests (30%):**
- 12 unit tests for backend utilities
- 0 integration tests
- 0 E2E tests
- No test coverage reports
- jest.config.js exists but minimal tests
**Documentation (40%):**
- Good README with setup instructions
- No API documentation (no OpenAPI spec)
- No architecture diagrams
- Basic deployment guide
- No developer guide
**Infrastructure (80%):**
- Full Terraform IaC for AWS
- GitHub Actions CI/CD configured
- Auto-deploy to staging
- Manual production deploy
- No monitoring/alerting setup
```
---
## Output Format
```markdown
## Completeness Assessment
### Estimated Completion
- **Overall:** ~66%
- **Backend:** ~100%
- **Frontend:** ~60%
- **Tests:** ~30%
- **Documentation:** ~40%
- **Infrastructure:** ~80%
### Evidence
[Detailed evidence as shown above]
### Missing Components
[Categorized list of missing/incomplete features]
### Placeholder Files
- app/analytics/page.tsx (TODO comment)
- app/settings/page.tsx ("Coming Soon" text)
- src/services/email.ts (stub functions)
### TODO Comments
- Found 23 TODO/FIXME comments across codebase
- Most common: Frontend polish, missing tests, error handling
```
---
## Notes
- Be conservative with estimates - round down when uncertain
- Provide evidence for all estimates
- Consider quality, not just quantity (a poorly implemented feature counts less)
- Differentiate between "not started" vs "partially done" vs "mostly complete"

268
skills/analyze/operations/detect-stack.md Normal file
View File

@@ -0,0 +1,268 @@
# Tech Stack Detection
Comprehensive commands for detecting programming languages, frameworks, and build systems.
## Overview
Run all detection commands **in parallel** to identify the technology stack. Missing files are normal - they just mean that technology isn't used.
---
## Detection Commands
Execute these commands to detect the primary language and framework:
```bash
# Get current directory context
pwd
# Show directory contents
ls -la
# Get git repository info
git remote -v 2>/dev/null
# Language/Framework Detection (run all in parallel)
cat package.json 2>/dev/null # Node.js/JavaScript/TypeScript
cat composer.json 2>/dev/null # PHP
cat requirements.txt 2>/dev/null # Python (pip)
cat Pipfile 2>/dev/null # Python (pipenv)
cat pyproject.toml 2>/dev/null # Python (poetry)
cat Gemfile 2>/dev/null # Ruby
cat pom.xml 2>/dev/null # Java/Maven
cat build.gradle 2>/dev/null # Java/Gradle
cat Cargo.toml 2>/dev/null # Rust
cat go.mod 2>/dev/null # Go
cat pubspec.yaml 2>/dev/null # Dart/Flutter
cat mix.exs 2>/dev/null # Elixir
find . -maxdepth 2 -name "*.csproj" 2>/dev/null # .NET/C#
find . -maxdepth 2 -name "*.sln" 2>/dev/null # .NET Solution
```
---
## Framework-Specific Detection
### JavaScript/TypeScript Frameworks
If `package.json` exists, look for these framework indicators:
```json
{
"dependencies": {
"react": "...", // React
"next": "...", // Next.js
"vue": "...", // Vue.js
"nuxt": "...", // Nuxt.js
"@angular/core": "...", // Angular
"svelte": "...", // Svelte
"express": "...", // Express.js (backend)
"fastify": "...", // Fastify (backend)
"nestjs": "..." // NestJS (backend)
}
}
```
### Python Frameworks
Look for these imports or dependencies:
- `django` - Django web framework
- `flask` - Flask micro-framework
- `fastapi` - FastAPI
- `pyramid` - Pyramid
- `tornado` - Tornado
### Ruby Frameworks
In `Gemfile`:
- `rails` - Ruby on Rails
- `sinatra` - Sinatra
- `hanami` - Hanami
### PHP Frameworks
In `composer.json`:
- `laravel/framework` - Laravel
- `symfony/symfony` - Symfony
- `slim/slim` - Slim
### Java Frameworks
In `pom.xml` or `build.gradle`:
- `spring-boot` - Spring Boot
- `quarkus` - Quarkus
- `micronaut` - Micronaut
---
## Database Detection
Look for database-related dependencies or configuration:
### SQL Databases
```bash
# PostgreSQL indicators
grep -r "postgres" package.json composer.json requirements.txt 2>/dev/null
ls -la prisma/ 2>/dev/null # Prisma ORM
# MySQL indicators
grep -r "mysql" package.json composer.json requirements.txt 2>/dev/null
# SQLite
find . -name "*.db" -o -name "*.sqlite" 2>/dev/null
```
### NoSQL Databases
```bash
# MongoDB
grep -r "mongodb\|mongoose" package.json requirements.txt 2>/dev/null
# Redis
grep -r "redis" package.json requirements.txt 2>/dev/null
# DynamoDB (AWS)
grep -r "dynamodb\|@aws-sdk" package.json requirements.txt 2>/dev/null
```
---
## Infrastructure Detection
### Cloud Providers
```bash
# AWS
find . -name "*.tf" -o -name "terraform.tfvars" 2>/dev/null # Terraform
find . -name "serverless.yml" 2>/dev/null # Serverless Framework
find . -name "cdk.json" 2>/dev/null # AWS CDK
grep -r "@aws-sdk\|aws-lambda" package.json 2>/dev/null
# Azure
grep -r "@azure" package.json 2>/dev/null
# GCP
grep -r "@google-cloud" package.json 2>/dev/null
```
### Container/Orchestration
```bash
# Docker
ls -la Dockerfile docker-compose.yml 2>/dev/null
# Kubernetes
find . -name "*.yaml" | xargs grep -l "apiVersion: apps/v1" 2>/dev/null
```
---
## Build System Detection
Identify the build tool based on manifest files:
- `package.json` → npm, yarn, or pnpm (check for lock files)
- `pom.xml` → Maven
- `build.gradle` → Gradle
- `Cargo.toml` → Cargo (Rust)
- `go.mod` → Go modules
- `Gemfile` → Bundler
- `composer.json` → Composer
- `requirements.txt` → pip
- `Pipfile` → pipenv
- `pyproject.toml` → poetry
---
## Version Extraction
Extract version numbers from manifests:
```bash
# Node.js
cat package.json | grep '"version"' | head -1
# Python
cat setup.py | grep "version=" 2>/dev/null
cat pyproject.toml | grep "version =" 2>/dev/null
# Java
cat pom.xml | grep "<version>" | head -1
# Rust
cat Cargo.toml | grep "version =" | head -1
```
---
## Multi-Language Projects
If multiple language manifest files exist, identify:
- **Primary language** - The main application language (most source files)
- **Secondary languages** - Supporting tools, scripts, infrastructure
Example:
- Primary: TypeScript (Next.js frontend + backend)
- Secondary: Python (data processing scripts), Terraform (infrastructure)
---
## Output Summary
After detection, summarize as:
```markdown
## Technology Stack
### Primary Language
- TypeScript 5.2
### Frameworks & Libraries
- Next.js 14.0.3 (React framework)
- Prisma 5.6.0 (ORM)
- tRPC 10.45.0 (API)
### Build System
- npm 10.2.3
### Database
- PostgreSQL (via Prisma)
### Infrastructure
- AWS Lambda (Serverless)
- Terraform 1.6.0 (IaC)
```
---
## Common Patterns
### Full-Stack JavaScript/TypeScript
- Frontend: React/Next.js/Vue
- Backend: Express/Fastify/NestJS
- Database: PostgreSQL/MongoDB
- Infrastructure: AWS/Vercel/Netlify
### Python Web App
- Framework: Django/Flask/FastAPI
- Database: PostgreSQL/MySQL
- Cache: Redis
- Infrastructure: AWS/GCP
### Ruby on Rails
- Framework: Rails
- Database: PostgreSQL
- Cache: Redis
- Infrastructure: Heroku/AWS
### Java Enterprise
- Framework: Spring Boot
- Database: PostgreSQL/Oracle
- Message Queue: RabbitMQ/Kafka
- Infrastructure: Kubernetes

395
skills/analyze/operations/directory-analysis.md Normal file
View File

@@ -0,0 +1,395 @@
# Directory Structure Analysis
Analyze directory structure to identify architecture patterns and key components.
## Overview
Map the directory structure to understand the application's organization and identify:
- Architecture patterns (MVC, microservices, monolith, etc.)
- Key components (backend, frontend, database, API, infrastructure)
- Configuration files
- Source code organization
---
## Directory Mapping Commands
### Basic Structure
```bash
# Show directory tree (limited depth to avoid noise)
find . -type d -maxdepth 3 | grep -v -E "node_modules|vendor|\.git|build|dist|target|__pycache__|\.next|\.nuxt" | sort | head -50
```
### Configuration Files
```bash
# Find all configuration files
find . -maxdepth 3 \( \
-name "*.json" -o \
-name "*.yaml" -o \
-name "*.yml" -o \
-name "*.toml" -o \
-name "*.xml" -o \
-name "*.conf" -o \
-name "*.config" -o \
-name ".env*" \
\) | grep -v -E "node_modules|vendor|\.git|dist|build" | sort | head -40
```
---
## Architecture Pattern Recognition
### Frontend Patterns
**Next.js / React (App Router)**
```
app/ # Next.js 13+ app directory
components/
api/
(routes)/
public/
```
**Next.js (Pages Router)**
```
pages/ # Next.js pages
api/ # API routes
components/
public/
```
**Standard React**
```
src/
components/
hooks/
pages/
utils/
public/
```
**Vue.js**
```
src/
components/
views/
router/
store/
public/
```
**Angular**
```
src/
app/
components/
services/
modules/
assets/
```
### Backend Patterns
**Node.js/Express**
```
src/
routes/
controllers/
models/
middleware/
services/
```
**NestJS**
```
src/
modules/
controllers/
services/
entities/
dto/
```
**Django**
```
project_name/
app_name/
models/
views/
templates/
migrations/
settings/
manage.py
```
**Ruby on Rails**
```
app/
models/
controllers/
views/
helpers/
db/
migrate/
config/
```
### Microservices Pattern
```
services/
service-a/
service-b/
service-c/
shared/
docker-compose.yml
```
### Monorepo Pattern
```
packages/
package-a/
package-b/
apps/
app-1/
app-2/
turbo.json (or lerna.json, nx.json)
```
---
## Component Detection
### Backend Detection
Indicators of backend code:
```bash
# API/Backend directories
find . -type d -name "api" -o -name "server" -o -name "backend" -o -name "routes" -o -name "controllers" 2>/dev/null
# Server files
find . -name "server.js" -o -name "server.ts" -o -name "app.js" -o -name "app.ts" -o -name "main.py" 2>/dev/null
```
### Frontend Detection
Indicators of frontend code:
```bash
# Frontend directories
find . -type d -name "components" -o -name "pages" -o -name "views" -o -name "public" -o -name "assets" 2>/dev/null
# Frontend config files
find . -name "next.config.*" -o -name "vite.config.*" -o -name "vue.config.*" -o -name "angular.json" 2>/dev/null
```
### Database Detection
Indicators of database usage:
```bash
# ORM/Database directories
find . -type d -name "prisma" -o -name "migrations" -o -name "models" -o -name "entities" 2>/dev/null
# Database schema files
find . -name "schema.prisma" -o -name "*.sql" -o -name "database.yml" 2>/dev/null
```
### Infrastructure Detection
Indicators of infrastructure-as-code:
```bash
# IaC directories
find . -type d -name "terraform" -o -name "infrastructure" -o -name "infra" -o -name ".aws" 2>/dev/null
# IaC files
find . -name "*.tf" -o -name "cloudformation.yml" -o -name "serverless.yml" -o -name "cdk.json" 2>/dev/null
```
---
## Source File Counting
Count source files by type to understand project size:
### JavaScript/TypeScript
```bash
# TypeScript/JavaScript files (excluding tests, node_modules, build)
find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) \
| grep -v -E "node_modules|dist|build|\.next|coverage|test|spec" \
| wc -l
```
### Python
```bash
# Python files
find . -type f -name "*.py" \
| grep -v -E "__pycache__|venv|\.venv|dist|build|test_" \
| wc -l
```
### Java
```bash
# Java files
find . -type f -name "*.java" \
| grep -v -E "build|target|test" \
| wc -l
```
### Ruby
```bash
# Ruby files
find . -type f -name "*.rb" \
| grep -v -E "vendor|spec|test" \
| wc -l
```
### Other Languages
Adapt the pattern based on detected language:
- PHP: `*.php`
- Go: `*.go`
- Rust: `*.rs`
- C#: `*.cs`
- Swift: `*.swift`
- Kotlin: `*.kt`
---
## Key Components Summary
After analysis, summarize key components:
```markdown
### Key Components Identified
- **Backend:** Yes - Express.js API server
- Location: `src/api/` (12 routes, 8 controllers)
- Database: PostgreSQL via Prisma ORM
- Authentication: JWT-based
- **Frontend:** Yes - Next.js 14 with App Router
- Location: `app/` (15 pages, 23 components)
- Styling: Tailwind CSS
- State: React Context + Server Components
- **Database:** PostgreSQL
- ORM: Prisma
- Schema: `prisma/schema.prisma` (8 models)
- Migrations: 12 migration files
- **API:** RESTful + tRPC
- REST endpoints: `app/api/` (5 routes)
- tRPC router: `src/server/api/` (4 routers)
- OpenAPI: Not found
- **Infrastructure:** AWS Serverless
- IaC: Terraform (`infrastructure/terraform/`)
- Services: Lambda, API Gateway, RDS, S3
- CI/CD: GitHub Actions (`.github/workflows/`)
```
---
## Architecture Pattern Summary
Based on directory structure, identify the overall pattern:
**Examples:**
- **Monolithic Full-Stack** - Single repo with frontend + backend + database
- **Microservices** - Multiple independent services
- **JAMstack** - Static frontend + serverless functions + headless CMS
- **Serverless** - No traditional servers, all functions/managed services
- **Monorepo** - Multiple packages/apps in one repository
- **Client-Server** - Clear separation between client and server code
---
## Common Directory Structures by Framework
### Next.js 13+ (App Router)
```
app/
(auth)/
login/
register/
dashboard/
api/
components/
ui/
lib/
public/
prisma/
```
### Next.js (Pages Router)
```
pages/
api/
_app.tsx
index.tsx
components/
public/
styles/
```
### Express.js Backend
```
src/
routes/
controllers/
models/
middleware/
services/
utils/
config/
tests/
```
### Django
```
project/
app/
models.py
views.py
urls.py
serializers.py
settings/
wsgi.py
manage.py
requirements.txt
```
### Rails
```
app/
models/
controllers/
views/
jobs/
mailers/
db/
migrate/
config/
routes.rb
Gemfile
```
---
## Notes
- Exclude common noise directories: node_modules, vendor, .git, dist, build, target, __pycache__, .next, .nuxt, coverage
- Limit depth to 3 levels to avoid overwhelming output
- Use `head` to limit file counts for large codebases
- Look for naming conventions that indicate purpose (e.g., `controllers/`, `services/`, `utils/`)

367
skills/analyze/operations/documentation-scan.md Normal file
View File

@@ -0,0 +1,367 @@
# Documentation Scan
Scan for existing documentation and assess quality.
## Overview
Identify all existing documentation to understand:
- What's already documented
- Quality and completeness of docs
- What documentation is missing
- Where docs are located
---
## Documentation Discovery
### Find Documentation Directories
```bash
# Common documentation directories
ls -la docs/ 2>/dev/null
ls -la documentation/ 2>/dev/null
ls -la doc/ 2>/dev/null
ls -la wiki/ 2>/dev/null
ls -la .docs/ 2>/dev/null
```
### Find Markdown Files
```bash
# Find all markdown files (limiting to avoid noise)
find . -type f -name "*.md" \
| grep -v -E "node_modules|vendor|\.git|dist|build" \
| head -30
```
### Common Documentation Files
Look for these standard files:
```bash
# Standard docs
ls -la README.md 2>/dev/null
ls -la CONTRIBUTING.md 2>/dev/null
ls -la CHANGELOG.md 2>/dev/null
ls -la LICENSE 2>/dev/null
ls -la CODE_OF_CONDUCT.md 2>/dev/null
ls -la SECURITY.md 2>/dev/null
# Setup/deployment docs
ls -la INSTALL.md 2>/dev/null
ls -la DEPLOYMENT.md 2>/dev/null
ls -la SETUP.md 2>/dev/null
# Architecture docs
ls -la ARCHITECTURE.md 2>/dev/null
ls -la DESIGN.md 2>/dev/null
ls -la API.md 2>/dev/null
```
---
## Documentation Categories
### README Assessment
Read `README.md` and assess quality:
**Good README includes:**
- Clear project description
- Installation/setup instructions
- Usage examples
- API documentation or links
- Development guide
- Testing instructions
- Deployment guide
- Contributing guidelines
- License information
**Rate as:**
- **Good** - Comprehensive, well-organized, covers all key areas
- **Basic** - Has description and setup, but missing key sections
- **Poor** - Minimal info, outdated, or confusing
### API Documentation
Look for API documentation:
```bash
# OpenAPI/Swagger
find . -name "openapi.yaml" -o -name "openapi.yml" -o -name "swagger.yaml" -o -name "swagger.json" 2>/dev/null
# API doc generators
find . -name "apidoc.json" -o -name ".redocly.yaml" 2>/dev/null
# API docs directories
ls -la docs/api/ 2>/dev/null
ls -la api-docs/ 2>/dev/null
```
**Assessment:**
- **Yes** - OpenAPI spec or comprehensive API docs exist
- **Partial** - Some API docs but incomplete
- **No** - No API documentation found
### Architecture Documentation
Look for architecture diagrams and docs:
```bash
# Architecture docs
find . -name "ARCHITECTURE.md" -o -name "architecture.md" -o -name "DESIGN.md" 2>/dev/null
# Diagram files
find . \( -name "*.drawio" -o -name "*.mermaid" -o -name "*.puml" -o -name "*.svg" \) \
| grep -i "architecture\|diagram\|flow" 2>/dev/null
```
**Assessment:**
- **Yes** - Architecture docs with diagrams/explanations
- **Partial** - Some architecture info in README
- **No** - No architecture documentation
### Setup/Deployment Documentation
```bash
# Deployment docs
find . -name "DEPLOYMENT.md" -o -name "deployment.md" -o -name "DEPLOY.md" 2>/dev/null
# Infrastructure docs
ls -la infrastructure/README.md 2>/dev/null
ls -la terraform/README.md 2>/dev/null
ls -la .github/workflows/ 2>/dev/null
```
**Assessment:**
- **Yes** - Clear deployment and infrastructure docs
- **Partial** - Basic setup but missing details
- **No** - No deployment documentation
### Developer Documentation
```bash
# Developer guides
find . -name "CONTRIBUTING.md" -o -name "DEVELOPMENT.md" -o -name "dev-guide.md" 2>/dev/null
# Code comments/JSDoc
grep -r "@param\|@returns\|@description" src/ 2>/dev/null | wc -l
```
**Assessment:**
- **Yes** - Developer guide with setup, conventions, workflow
- **Partial** - Some developer info scattered
- **No** - No developer documentation
### Testing Documentation
```bash
# Test docs
find . -name "TESTING.md" -o -name "test-guide.md" 2>/dev/null
# Test README files
find . -path "*/tests/README.md" -o -path "*/test/README.md" 2>/dev/null
```
**Assessment:**
- **Yes** - Testing guide with examples and conventions
- **Partial** - Basic test info in README
- **No** - No testing documentation
### Database Documentation
```bash
# Database docs
find . -name "schema.md" -o -name "database.md" -o -name "DATA_MODEL.md" 2>/dev/null
# ER diagrams
find . -name "*er-diagram*" -o -name "*schema-diagram*" 2>/dev/null
# Migration docs
ls -la migrations/README.md 2>/dev/null
ls -la prisma/README.md 2>/dev/null
```
**Assessment:**
- **Yes** - Database schema docs and ER diagrams
- **Partial** - Schema file but no explanatory docs
- **No** - No database documentation
---
## Documentation Tools Detection
Identify if automated documentation tools are configured:
### Code Documentation Generators
```bash
# JSDoc/TypeDoc (JavaScript/TypeScript)
grep -r "typedoc\|jsdoc" package.json 2>/dev/null
# Sphinx (Python)
ls -la docs/conf.py 2>/dev/null
# Javadoc (Java)
grep -r "javadoc" pom.xml build.gradle 2>/dev/null
# RDoc/YARD (Ruby)
ls -la .yardopts 2>/dev/null
# Doxygen (C/C++)
ls -la Doxyfile 2>/dev/null
```
### API Documentation Tools
```bash
# Swagger UI
grep -r "swagger-ui" package.json 2>/dev/null
# Redoc
grep -r "redoc" package.json 2>/dev/null
# Postman collections
find . -name "*.postman_collection.json" 2>/dev/null
```
### Static Site Generators
```bash
# Docusaurus
grep -r "docusaurus" package.json 2>/dev/null
ls -la docusaurus.config.js 2>/dev/null
# VuePress
grep -r "vuepress" package.json 2>/dev/null
# MkDocs
ls -la mkdocs.yml 2>/dev/null
# GitBook
ls -la .gitbook.yaml 2>/dev/null
# Mintlify
ls -la mint.json 2>/dev/null
```
---
## Documentation Quality Checklist
For each category, assess:
- [ ] **Exists** - Documentation files are present
- [ ] **Current** - Docs match current code (check dates)
- [ ] **Complete** - Covers all major features/components
- [ ] **Clear** - Well-written and easy to understand
- [ ] **Examples** - Includes code examples and usage
- [ ] **Maintained** - Recently updated (check git log)
---
## Output Summary
Summarize findings:
```markdown
## Existing Documentation
### README.md
- **Status:** Yes
- **Quality:** Good
- **Coverage:** Installation, usage, API overview, development setup
- **Last Updated:** 2024-01-15
- **Notes:** Comprehensive but missing deployment section
### API Documentation
- **Status:** Partial
- **Type:** Inline JSDoc comments only
- **Coverage:** ~60% of endpoints documented
- **OpenAPI Spec:** No
- **Notes:** Should generate OpenAPI spec
### Architecture Documentation
- **Status:** No
- **Notes:** Architecture decisions are scattered in code comments
### Setup/Deployment Documentation
- **Status:** Yes
- **Files:** DEPLOYMENT.md, infrastructure/README.md
- **Coverage:** AWS deployment, CI/CD, environment setup
- **Quality:** Basic
### Developer Documentation
- **Status:** Partial
- **Files:** CONTRIBUTING.md
- **Coverage:** PR process, code style guide
- **Missing:** Local development setup, debugging guide
### Testing Documentation
- **Status:** No
- **Notes:** No testing guide, test structure undocumented
### Database Documentation
- **Status:** Yes
- **Type:** Prisma schema file with comments
- **Coverage:** All models documented inline
- **ER Diagram:** No
- **Notes:** Should generate ER diagram from schema
### Documentation Tools
- **Configured:** None
- **Recommended:** TypeDoc for code docs, Swagger for API docs
```
---
## Missing Documentation Identification
List what documentation should be created:
**Critical (needed for Step 2):**
- OpenAPI specification for API endpoints
- Architecture overview document
- Database ER diagram
**Important (create during specification):**
- Comprehensive testing guide
- Deployment runbook
- Troubleshooting guide
**Nice-to-have:**
- Code contribution guide
- ADRs (Architecture Decision Records)
- Security documentation
---
## Documentation Metrics
Calculate documentation coverage:
```bash
# Count documented vs undocumented functions (example for JS/TS)
# Total functions
grep -r "function\|const.*=>.*{" src/ | wc -l
# Documented functions (with JSDoc)
grep -B1 "function\|const.*=>" src/ | grep -c "/\*\*"
# Calculate percentage
```
Report as:
- **Code documentation coverage:** ~45% (estimated)
- **API endpoint documentation:** ~60%
- **Feature documentation:** ~30%
- **Overall documentation score:** 4/10
---
## Notes
- Check git history to see when docs were last updated
- Compare doc dates with code changes to identify stale docs
- Look for TODO/FIXME comments in docs indicating incomplete sections
- Verify links in docs aren't broken

475
skills/analyze/operations/generate-report.md Normal file
View File

@@ -0,0 +1,475 @@
# Generate Analysis Report
Template and guidelines for creating `analysis-report.md`.
## Overview
After completing all analysis steps, generate a comprehensive `analysis-report.md` file in the project root.
---
## Report Template
```markdown
# Initial Analysis Report
**Date:** [Current Date - YYYY-MM-DD]
**Directory:** [Full path from pwd]
**Analyst:** Claude Code (Reverse Engineering Toolkit v1.0.0)
---
## Executive Summary
[2-3 paragraph summary of the application, its purpose, current state, and overall completeness]
Example:
> This is a full-stack Next.js application for managing aquarium fish care ("fishfan"). The backend is fully implemented with 17 AWS Lambda functions, PostgreSQL database, and complete authentication. The frontend is ~60% complete with core functionality implemented but several pages still in placeholder state. Overall project completion is estimated at ~66%.
---
## Application Metadata
- **Name:** [Application Name from package.json or directory]
- **Version:** [Version from manifest]
- **Description:** [From manifest or README]
- **Repository:** [Git remote URL or "Not configured"]
- **License:** [From LICENSE file or package.json]
- **Primary Language:** [Language] [Version if available]
---
## Technology Stack
### Primary Language
- [Language] [Version]
- [Key notes about language usage]
### Frontend Framework
- [Framework] [Version]
- [Key dependencies and notes]
### Backend Framework
- [Framework] [Version]
- [Key dependencies and notes]
### Database
- [Database Type] [Version/Service]
- ORM: [ORM if applicable]
- Migration System: [Yes/No with details]
### Infrastructure & Deployment
- **Cloud Provider:** [AWS/GCP/Azure/Other]
- **IaC Tool:** [Terraform/CloudFormation/CDK/None]
- **CI/CD:** [GitHub Actions/GitLab CI/CircleCI/None]
- **Hosting:** [Vercel/Netlify/AWS Lambda/EC2/etc.]
### Key Dependencies
| Category | Library | Version | Purpose |
|----------|---------|---------|---------|
| Auth | [Library] | [Version] | [Purpose] |
| API | [Library] | [Version] | [Purpose] |
| UI | [Library] | [Version] | [Purpose] |
| Testing | [Library] | [Version] | [Purpose] |
| Build | [Library] | [Version] | [Purpose] |
---
## Architecture Overview
### Application Type
[Full-Stack Monolith / Microservices / JAMstack / Serverless / etc.]
### Directory Structure
```
[Project Root]/
├── [key-directory-1]/ # [Purpose]
│ ├── [subdirectory]/ # [Purpose]
│ └── ...
├── [key-directory-2]/ # [Purpose]
├── [configuration-files] # [Purpose]
└── [other-key-files]
```
### Key Components
#### Backend
- **Status:** [Exists / Not Found]
- **Location:** [Directory path]
- **Type:** [REST API / GraphQL / tRPC / Mixed]
- **Endpoints:** [Count] endpoints identified
- **Database Models:** [Count] models
- **Authentication:** [Method - JWT/Session/OAuth/None]
- **Key Features:**
- [Feature 1]
- [Feature 2]
- [Feature 3]
#### Frontend
- **Status:** [Exists / Not Found]
- **Location:** [Directory path]
- **Type:** [SPA / SSR / SSG / Hybrid]
- **Pages:** [Count] pages identified
- **Components:** [Count] reusable components
- **Styling:** [Tailwind/CSS Modules/Styled Components/etc.]
- **State Management:** [Redux/Context/Zustand/None]
- **Key Features:**
- [Feature 1]
- [Feature 2]
- [Feature 3]
#### Database
- **Type:** [PostgreSQL/MySQL/MongoDB/etc.]
- **ORM:** [Prisma/TypeORM/Sequelize/etc.]
- **Schema Location:** [Path to schema files]
- **Models:** [Count] models defined
- **Migrations:** [Count] migrations
- **Seeding:** [Configured / Not Configured]
#### API Architecture
- **Type:** [RESTful / GraphQL / tRPC / Mixed]
- **Endpoints:** [Count] total endpoints
- **Documentation:** [OpenAPI Spec / Inline Comments / None]
- **Versioning:** [v1/v2/etc. or None]
- **Rate Limiting:** [Configured / Not Configured]
#### Infrastructure
- **IaC Tool:** [Terraform/CloudFormation/etc.]
- **Services Used:**
- [Service 1]: [Purpose]
- [Service 2]: [Purpose]
- [Service 3]: [Purpose]
- **Configuration:** [Location of IaC files]
- **Environments:** [dev/staging/prod or single]
---
## Existing Documentation
### README.md
- **Status:** [Yes / No]
- **Quality:** [Good / Basic / Poor]
- **Sections:**
- [✓] Description
- [✓] Installation
- [✗] API Documentation
- [✓] Development Setup
- [✗] Testing Guide
- [✓] Deployment
- **Last Updated:** [Date from git log]
- **Notes:** [Any observations]
### API Documentation
- **Status:** [Yes / Partial / No]
- **Format:** [OpenAPI/Postman/Inline/None]
- **Coverage:** [Percentage or count]
- **Location:** [Path or URL]
- **Notes:** [Any observations]
### Architecture Documentation
- **Status:** [Yes / Partial / No]
- **Files:** [List of architecture docs]
- **Diagrams:** [Yes/No - list types]
- **Notes:** [Any observations]
### Setup/Deployment Documentation
- **Status:** [Yes / Partial / No]
- **Files:** [List files]
- **Coverage:** [What's documented]
- **Notes:** [Any observations]
### Developer Documentation
- **Status:** [Yes / Partial / No]
- **Files:** [CONTRIBUTING.md, etc.]
- **Coverage:** [What's documented]
- **Notes:** [Any observations]
### Testing Documentation
- **Status:** [Yes / Partial / No]
- **Files:** [Test guide files]
- **Coverage:** [What's documented]
- **Notes:** [Any observations]
### Database Documentation
- **Status:** [Yes / Partial / No]
- **Type:** [ER Diagram / Schema Comments / None]
- **Coverage:** [What's documented]
- **Notes:** [Any observations]
### Documentation Tools
- **Configured:** [List tools like TypeDoc, JSDoc, Sphinx, etc.]
- **Output Location:** [Where docs are generated]
- **Notes:** [Any observations]
---
## Completeness Assessment
### Overall Completion: ~[X]%
### Component Breakdown
| Component | Completion | Evidence |
|-----------|------------|----------|
| Backend | ~[X]% | [Brief evidence] |
| Frontend | ~[X]% | [Brief evidence] |
| Database | ~[X]% | [Brief evidence] |
| Tests | ~[X]% | [Brief evidence] |
| Documentation | ~[X]% | [Brief evidence] |
| Infrastructure | ~[X]% | [Brief evidence] |
### Detailed Evidence
#### Backend (~[X]%)
[Detailed evidence with specific examples, file counts, etc.]
Example:
- 17 Lambda functions fully implemented and tested
- All API endpoints functional with proper error handling
- Authentication/authorization complete with JWT
- Database queries optimized
- No placeholder or TODO comments in backend code
#### Frontend (~[X]%)
[Detailed evidence]
Example:
- 8 of 12 planned pages implemented
- Core pages complete: Login, Dashboard, Fish List, Fish Detail
- Placeholder pages: Analytics (TODO), Settings (stub), Admin (not started), Reports (skeleton)
- Components: 23 reusable components, all functional
- Styling: ~80% complete, missing dark mode and mobile polish
#### Tests (~[X]%)
[Detailed evidence]
#### Documentation (~[X]%)
[Detailed evidence]
#### Infrastructure (~[X]%)
[Detailed evidence]
### Placeholder Files & TODOs
**Files with Placeholder Content:**
- [File path]: [Description]
- [File path]: [Description]
**TODO/FIXME Comments:**
- Found [N] TODO comments across codebase
- Top categories:
1. [Category]: [Count]
2. [Category]: [Count]
3. [Category]: [Count]
**Sample TODOs:**
```
[File:Line] - TODO: [Comment]
[File:Line] - FIXME: [Comment]
[File:Line] - TODO: [Comment]
```
### Missing Components
**Not Started:**
- [Component/Feature]: [Description]
- [Component/Feature]: [Description]
**Partially Implemented:**
- [Component/Feature]: [What exists vs what's missing]
- [Component/Feature]: [What exists vs what's missing]
**Needs Improvement:**
- [Component/Feature]: [Current state and what needs work]
- [Component/Feature]: [Current state and what needs work]
---
## Source Code Statistics
- **Total Source Files:** [Count]
- **Lines of Code:** ~[Estimate from cloc or wc]
- **Test Files:** [Count]
- **Test Coverage:** [Percentage if available or "Not measured"]
- **Configuration Files:** [Count]
### File Type Breakdown
| Type | Count | Purpose |
|------|-------|---------|
| TypeScript/JavaScript | [Count] | [Application code/Components/etc.] |
| Tests | [Count] | [Unit/Integration/E2E] |
| Styles | [Count] | [CSS/SCSS/etc.] |
| Configuration | [Count] | [Build/Deploy/Environment] |
| Documentation | [Count] | [Markdown files] |
---
## Technical Debt & Issues
### Identified Issues
1. [Issue 1]: [Description and impact]
2. [Issue 2]: [Description and impact]
3. [Issue 3]: [Description and impact]
### Security Concerns
- [Concern 1]: [Description]
- [Concern 2]: [Description]
### Performance Concerns
- [Concern 1]: [Description]
- [Concern 2]: [Description]
### Code Quality
- Linting: [Configured / Not Configured]
- Type Checking: [Strict / Loose / None]
- Code Formatting: [Prettier/ESLint/None]
- Pre-commit Hooks: [Configured / Not Configured]
---
## Recommended Next Steps
Based on this analysis, the reverse engineering process should focus on:
### Immediate Priorities
1. **[Priority 1]**
- Why: [Reasoning]
- Impact: [Expected outcome]
2. **[Priority 2]**
- Why: [Reasoning]
- Impact: [Expected outcome]
3. **[Priority 3]**
- Why: [Reasoning]
- Impact: [Expected outcome]
### Reverse Engineering Focus Areas
For **Step 2 (Reverse Engineer)**:
- Prioritize extracting documentation for: [List components]
- Pay special attention to: [Areas of concern]
- Can likely skip: [Well-documented areas]
### Estimated Reverse Engineering Effort
- **Step 2 (Reverse Engineer):** ~[X] minutes (based on codebase size)
- **Step 3 (Create Specifications):** ~[X] minutes
- **Step 4 (Gap Analysis):** ~[X] minutes
- **Step 5 (Complete Specification):** ~[X] minutes (interactive)
- **Step 6 (Implement from Spec):** ~[X] hours/days (depends on gaps)
---
## Notes & Observations
[Any additional observations, concerns, or context that doesn't fit above categories]
Examples:
- Monorepo structure detected but not using workspace tools
- Multiple authentication methods suggest migration in progress
- Infrastructure code is more mature than application code
- Build process is complex and could be simplified
- Dependencies are up-to-date (as of [date])
---
## Appendices
### A. Dependency Tree (Top-Level)
```
[Main dependencies with versions]
```
### B. Configuration Files Inventory
```
[List of all configuration files with brief descriptions]
```
### C. Database Schema Summary
```
[List of models/tables with key relationships]
```
---
**Report Generated:** [Timestamp]
**Toolkit Version:** 1.0.0
**Ready for Step 2:** ✅
```
---
## Filling Out the Template
### Executive Summary Guidelines
Write a 2-3 paragraph summary answering:
1. What is this application? (Purpose, domain, users)
2. What's the tech stack? (Key technologies)
3. What's the current state? (Completion %, what's done, what's missing)
4. What's next? (Main recommendation)
### Evidence Requirements
For every percentage estimate, provide concrete evidence:
- File counts
- Feature lists
- Specific examples
- Code samples (for TODOs)
- Dates (for documentation)
### Prioritization Logic
Recommend next steps based on:
1. **Critical gaps** - Security, data integrity, deployment blockers
2. **High-value gaps** - User-facing features, core functionality
3. **Quality gaps** - Tests, documentation, error handling
4. **Nice-to-haves** - Polish, optimizations, extras
---
## Report Validation Checklist
Before finalizing the report, verify:
- [ ] All sections filled out (no [TODO] markers left)
- [ ] Percentages are evidence-based, not guesses
- [ ] File paths are accurate and up-to-date
- [ ] Tech stack versions are correct
- [ ] Missing components are clearly identified
- [ ] Recommendations are actionable
- [ ] Executive summary is clear and concise
- [ ] Report is saved to project root as `analysis-report.md`
---
## Sample Output Location
The report should be saved to:
```
/path/to/project-root/analysis-report.md
```
This ensures it's:
- Easy to find
- Version controlled (add to git)
- Referenced by subsequent steps
---
## Next Steps After Report
Once the report is generated and reviewed:
1. **Review with user** - Present key findings
2. **Confirm accuracy** - Ask if the analysis matches their understanding
3. **Adjust estimates** - Update based on user feedback
4. **Proceed to Step 2** - Use the reverse-engineer skill to generate comprehensive documentation
The analysis report serves as the foundation for the entire reverse engineering process.