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

323
skills/reverse-engineer/SKILL.md Normal file
View File

@@ -0,0 +1,323 @@
---
name: reverse-engineer
description: Deep codebase analysis to generate 8 comprehensive documentation files. Adapts based on path choice - Greenfield extracts business logic only (tech-agnostic), Brownfield extracts business logic + technical implementation (tech-prescriptive). This is Step 2 of 6 in the reverse engineering process.
---
# Reverse Engineer (Path-Aware)
**Step 2 of 6** in the Reverse Engineering to Spec-Driven Development process.
**Estimated Time:** 30-45 minutes
**Prerequisites:** Step 1 completed (`analysis-report.md` and path selection)
**Output:** 9 comprehensive documentation files in `docs/reverse-engineering/`
**Path-Dependent Behavior:**
- **Greenfield:** Extract business logic only (framework-agnostic)
- **Brownfield:** Extract business logic + technical implementation details
---
## When to Use This Skill
Use this skill when:
- You've completed Step 1 (Initial Analysis) with path selection
- Ready to extract comprehensive documentation from code
- Path has been chosen (greenfield or brownfield)
- Preparing to create formal specifications
**Trigger Phrases:**
- "Reverse engineer the codebase"
- "Generate comprehensive documentation"
- "Extract business logic" (greenfield)
- "Document the full implementation" (brownfield)
---
## What This Skill Does
This skill performs deep codebase analysis and generates **9 comprehensive documentation files**.
**Content adapts based on your path:**
### Path A: Greenfield (Business Logic Only)
- Focus on WHAT the system does
- Avoid framework/technology specifics
- Extract user stories, business rules, workflows
- Framework-agnostic functional requirements
- Can be implemented in any tech stack
### Path B: Brownfield (Business Logic + Technical)
- Focus on WHAT and HOW
- Document exact frameworks, libraries, versions
- Extract file paths, configurations, schemas
- Prescriptive technical requirements
- Enables `/speckit.analyze` validation
**9 Documentation Files Generated:**
1. **functional-specification.md** - Business logic, requirements, user stories (+ tech details for brownfield)
2. **integration-points.md** - External services, APIs, dependencies, data flows (single source of truth)
3. **configuration-reference.md** - Config options (business-level for greenfield, all details for brownfield)
4. **data-architecture.md** - Data models, API contracts (abstract for greenfield, schemas for brownfield)
5. **operations-guide.md** - Operational needs (requirements for greenfield, current setup for brownfield)
6. **technical-debt-analysis.md** - Issues and improvements
7. **observability-requirements.md** - Monitoring needs (goals for greenfield, current state for brownfield)
8. **visual-design-system.md** - UI/UX patterns (requirements for greenfield, implementation for brownfield)
9. **test-documentation.md** - Testing requirements (targets for greenfield, current state for brownfield)
---
## Configuration Check (FIRST STEP!)
**Load state file to check detection type and route:**
```bash
# Check what kind of application we're analyzing
DETECTION_TYPE=$(cat .stackshift-state.json | jq -r '.detection_type // .path')
echo "Detection: $DETECTION_TYPE"
# Check extraction approach
ROUTE=$(cat .stackshift-state.json | jq -r '.route // .path')
echo "Route: $ROUTE"
# Check spec output location (Greenfield only)
SPEC_OUTPUT=$(cat .stackshift-state.json | jq -r '.config.spec_output_location // "."')
echo "Writing specs to: $SPEC_OUTPUT"
# Create output directories if needed
if [ "$SPEC_OUTPUT" != "." ]; then
mkdir -p "$SPEC_OUTPUT/docs/reverse-engineering"
mkdir -p "$SPEC_OUTPUT/.specify/memory/specifications"
fi
```
**State file structure (new):**
```json
{
"detection_type": "monorepo-service", // What kind of app
"route": "greenfield", // How to spec it
"config": {
"spec_output_location": "~/git/my-new-app",
"build_location": "~/git/my-new-app",
"target_stack": "Next.js 15..."
}
}
```
**File write locations:**
| Route | Spec Output | Where Files Go |
|-------|-------------|----------------|
| **Greenfield** | Custom location | `{spec_output_location}/docs/`, `{spec_output_location}/.specify/` |
| **Greenfield** | Not set (default) | `./docs/reverse-engineering/`, `./.specify/` (current repo) |
| **Brownfield** | Always current repo | `./docs/reverse-engineering/`, `./.specify/` |
**Extraction approach based on detection + route:**
| Detection Type | + Greenfield | + Brownfield |
|----------------|--------------|--------------|
| **Monorepo Service** | Business logic only (tech-agnostic) | Full implementation + shared packages (tech-prescriptive) |
| **Nx App** | Business logic only (framework-agnostic) | Full Nx/Angular implementation details |
| **Generic App** | Business logic only | Full implementation |
**How it works:**
- `detection_type` determines WHAT patterns to look for (shared packages, Nx project config, monorepo structure, etc.)
- `route` determines HOW to document them (tech-agnostic vs tech-prescriptive)
**Examples:**
- Monorepo Service + Greenfield → Extract what the service does (not React/Express specifics)
- Monorepo Service + Brownfield → Extract full Express routes, React components, shared utilities
- Nx App + Greenfield → Extract business logic (not Angular specifics)
- Nx App + Brownfield → Extract full Nx configuration, Angular components, project graph
---
## Process Overview
### Phase 1: Deep Codebase Analysis
**Approach depends on path:**
Use the Task tool with `subagent_type=stackshift:code-analyzer` (or `Explore` as fallback) to analyze:
#### 1.1 Backend Analysis
- All API endpoints (method, path, auth, params, purpose)
- Data models (schemas, types, interfaces, fields)
- Configuration (env vars, config files, settings)
- External integrations (APIs, services, databases)
- Business logic (services, utilities, algorithms)
See [operations/backend-analysis.md](operations/backend-analysis.md)
#### 1.2 Frontend Analysis
- All pages/routes (path, purpose, auth requirement)
- Components catalog (layout, form, UI components)
- State management (store structure, global state)
- API client (how frontend calls backend)
- Styling (design system, themes, component styles)
See [operations/frontend-analysis.md](operations/frontend-analysis.md)
#### 1.3 Infrastructure Analysis
- Deployment (IaC tools, configuration)
- CI/CD (pipelines, workflows)
- Hosting (cloud provider, services)
- Database (type, schema, migrations)
- Storage (object storage, file systems)
See [operations/infrastructure-analysis.md](operations/infrastructure-analysis.md)
#### 1.4 Testing Analysis
- Test files (location, framework, coverage)
- Test types (unit, integration, E2E)
- Coverage estimates (% covered)
- Test data (mocks, fixtures, seeds)
See [operations/testing-analysis.md](operations/testing-analysis.md)
### Phase 2: Generate Documentation
Create `docs/reverse-engineering/` directory and generate all 8 documentation files.
See [operations/generate-docs.md](operations/generate-docs.md) for templates and guidelines.
---
## Output Files
### 1. functional-specification.md
**Focus:** Business logic, WHAT the system does (not HOW)
**Sections:**
- Executive Summary (purpose, users, value)
- Functional Requirements (FR-001, FR-002, ...)
- User Stories (P0/P1/P2/P3 priorities)
- Non-Functional Requirements (NFR-001, ...)
- Business Rules (validation, authorization, workflows)
- System Boundaries (scope, integrations)
- Success Criteria (measurable outcomes)
**Critical:** Framework-agnostic, testable, measurable
### 2. configuration-reference.md
**Complete inventory** of all configuration:
- Environment variables
- Config file options
- Feature flags
- Secrets and credentials (how managed)
- Default values
### 3. data-architecture.md
**All data models and API contracts:**
- Data models (with field types, constraints, relationships)
- API endpoints (request/response formats)
- JSON Schemas
- GraphQL schemas (if applicable)
- Database ER diagram (textual)
### 4. operations-guide.md
**How to deploy and maintain:**
- Deployment procedures
- Infrastructure overview
- Monitoring and alerting
- Backup and recovery
- Troubleshooting runbooks
### 5. technical-debt-analysis.md
**Issues and improvements:**
- Code quality issues
- Missing tests
- Security vulnerabilities
- Performance bottlenecks
- Refactoring opportunities
### 6. observability-requirements.md
**Logging, monitoring, alerting:**
- What to log (events, errors, metrics)
- Monitoring requirements (uptime, latency, errors)
- Alerting rules and thresholds
- Debugging capabilities
### 7. visual-design-system.md
**UI/UX patterns:**
- Component library
- Design tokens (colors, typography, spacing)
- Responsive breakpoints
- Accessibility standards
- User flows
### 8. test-documentation.md
**Testing requirements:**
- Test strategy
- Coverage requirements
- Test patterns and conventions
- E2E scenarios
- Performance testing
---
## Success Criteria
After running this skill, you should have:
- ✅ `docs/reverse-engineering/` directory created
- ✅ All 8 documentation files generated
- ✅ Comprehensive coverage of all application aspects
- ✅ Framework-agnostic functional specification
- ✅ Complete data model documentation
- ✅ Ready to proceed to Step 3 (Create Specifications)
---
## Next Step
Once all documentation is generated and reviewed, proceed to:
**Step 3: Create Specifications** - Use the create-specs skill to transform docs into formal specifications.
---
## Important Guidelines
### Framework-Agnostic Documentation
**DO:**
- Describe WHAT, not HOW
- Focus on business logic and requirements
- Use generic terms (e.g., "HTTP API" not "Express routes")
**DON'T:**
- Hard-code framework names in functional specs
- Describe implementation details in requirements
- Mix business logic with technical implementation
### Completeness
Use the Explore agent to ensure you find:
- ALL API endpoints (not just the obvious ones)
- ALL data models (including DTOs, types, interfaces)
- ALL configuration options (check multiple files)
- ALL external integrations
### Quality Standards
Each document must be:
- **Comprehensive** - Nothing important missing
- **Accurate** - Reflects actual code, not assumptions
- **Organized** - Clear sections, easy to navigate
- **Actionable** - Can be used to rebuild the system
---
## Technical Notes
- Use Task tool with `subagent_type=stackshift:code-analyzer` for path-aware extraction
- Fallback to `subagent_type=Explore` if StackShift agent not available
- Parallel analysis: Run backend, frontend, infrastructure analysis concurrently
- Use multiple rounds of exploration for complex codebases
- Cross-reference findings across different parts of the codebase
- The `stackshift:code-analyzer` agent understands greenfield vs brownfield routes automatically
---
**Remember:** This is Step 2 of 6. The documentation you generate here will be transformed into formal specifications in Step 3.