code-archaeology

# Code Archaeology Skill ## Overview Code Archaeology is a systematic analysis methodology for understanding legacy codebases and extracting actionable insights for modernization. This skill provides tools and workflows for: - **Business Rule Extraction**: Identify and document business logic from legacy code - **Technical Specification Generation**: Extract data models, API contracts, and system architecture - **Security Risk Assessment**: Identify security vulnerabilities and technical debt - **Migration Planning**: Generate detailed migration requirements and task breakdowns - **AI Plan Generator Integration**: Convert analysis results into AI-executable context documents ## Unified Directory Structure Code Archaeology results are organized in a standardized directory structure: ``` {project}_code_archaeology/ ├── results/ # Primary analysis outputs (for AI integration) │ ├── {project}_api_analysis.md │ ├── {project}_security_audit_results.md │ ├── {project}_performance_analysis.md │ ├── {project}_technical_debt_assessment.md │ ├── {project}_optimization_recommendations.md │ └── {project}_code_archaeology_final_report.md ├── process/ # Detailed analysis artifacts (30+ files) │ ├── 01-system-constants-analysis.md │ ├── 02-database-schema-analysis.md │ ├── 03-business-domain-file-list.md │ ├── {domain}-analysis.md (per business domain) │ └── round2_progress.json ├── source/ # Original source code reference │ └── {project}/ └── {project}_archaeology_status.json # Analysis status tracking ``` ## Core Capabilities ### 1. Multi-Round Analysis - **Round 1**: Business domain mapping and core architecture analysis - **Round 2**: Deep technical assessment (security, performance, optimization) ### 2. Domain-Specific Analysis - **Financial Management**: Payment processing, invoicing, reconciliation - **Customer Management**: User authentication, profile management - **Contract Management**: Contract lifecycle, status transitions - **Supply Chain**: Inventory, procurement, logistics ### 3. Security Risk Identification - **Critical**: Hardcoded credentials, SQL injection vulnerabilities - **High**: Weak password storage, session management issues - **Medium**: XSS/CSRF protection gaps, insecure file permissions ### 4. Technical Debt Assessment - **Architecture**: Monolithic limitations, lack of layered architecture - **Code Quality**: Code duplication, outdated language features - **Maintainability**: Missing documentation, poor test coverage - **Performance**: Database query optimization, caching mechanisms ## AI Plan Generator Integration Code Archaeology results can be directly consumed by AI Plan Generator to create: - **Campaign Documents**: Strategic migration plans with clear boundaries - **Context Documents**: AI-executable business rules and technical specifications - **Task Decomposition**: Detailed implementation tasks with priorities and dependencies - **Validation Standards**: Comprehensive testing requirements and acceptance criteria ### Integration Workflow ```bash # 1. Run Code Archaeology analysis code-archaeology analyze legacy-project --output-dir legacy_project_code_archaeology # 2. Generate AI Plan Generator context from archaeology results ai-plan-generator generate-context-from-archaeology \ /path/to/legacy_project_code_archaeology \ context-documents \ finance # 3. Validate context document completeness ai-plan-generator analyze-completeness context-documents # 4. Create ClawTeam migration team clawteam create --name "finance-migration" --description-file campaign.md ``` ## Usage Guidelines ### When to Use - **Legacy System Modernization**: Planning migration from PHP 5.x, legacy Java, etc. - **Business Logic Documentation**: Extracting undocumented business rules - **Security Remediation**: Identifying and prioritizing security vulnerabilities - **Technical Debt Reduction**: Planning systematic codebase improvements ### Input Requirements - **Source Code Access**: Full access to legacy codebase - **Business Context**: Understanding of business domains and requirements - **Target Architecture**: Clear vision of target modern architecture ### Output Artifacts - **Comprehensive Reports**: Executive summaries and detailed technical analysis - **Actionable Recommendations**: Prioritized improvement and migration tasks - **Risk Assessments**: Security and business continuity risk evaluations - **Integration Ready**: Structured data for AI Plan Generator consumption ## Best Practices ### Analysis Process 1. **Start Broad**: Begin with high-level business domain mapping 2. **Go Deep**: Focus on critical domains (financial, security-sensitive) 3. **Validate Findings**: Cross-reference analysis results with business stakeholders 4. **Iterate**: Refine analysis based on feedback and new discoveries ### Documentation Standards - **Machine Readable**: Structure outputs for AI consumption - **Human Understandable**: Provide clear explanations for business stakeholders - **Action Oriented**: Focus on actionable insights and recommendations - **Version Controlled**: Track analysis evolution over time ### Integration Patterns - **ClawTeam Orchestration**: Use analysis results to drive multi-agent coordination - **Continuous Validation**: Regularly validate AI interpretations against original code - **Feedback Loops**: Use implementation results to refine future analyses ## Example Use Cases ### Financial Module Migration **Input**: Legacy PHP financial system with hardcoded credentials **Analysis**: Identifies payment processing logic, security vulnerabilities, data models **Output**: Complete migration plan with security remediation and validation standards ### User Authentication Modernization **Input**: Custom authentication system with weak password storage **Analysis**: Extracts user management workflows, identifies security gaps **Output**: Modern authentication implementation plan with proper security controls ### API Standardization **Input**: Inconsistent RPC-style APIs across multiple modules **Analysis**: Documents all API endpoints, request/response formats, error handling **Output**: RESTful API redesign specification with backward compatibility strategy Code Archaeology transforms legacy code understanding from an art into a systematic, repeatable science that powers AI-driven modernization. ## Integration Scripts This skill includes integration scripts for converting Code Archaeology results to AI Plan Generator format: - `convert-to-ai-plan-generator.cjs`: Main conversion utility - `code-archaeology-integrator.cjs`: Core parsing and extraction logic - `process-file-manager.cjs`: File location and organization management ### Usage ```bash node convert-to-ai-plan-generator.cjs /path/to/archaeology-results output-dir domain ```