Code Archaeology

Analyze legacy codebases to extract business rules, technical specifications, and migration requirements. Use when analyzing PHP, Java, Python, or other lega...

Security Scan

The skill's code and docs broadly match its stated purpose, but there are multiple inconsistencies and sloppy defaults (hardcoded user path, mismatched filenames, a missing function call) that warrant caution before running it on real data.

Purpose & Capability

The name, README, SKILL.md and included scripts (integrator, converter, process-file-manager) are coherent with a legacy-code analysis -> generate migration/context-documents workflow. However the integrator expects specific file names prefixed with 'zbs_php_' and the default business domain is hardcoded to 'finance', which narrows applicability without justification. _meta.json version (2.4.0) differs from registry version (2.5.0) — a minor metadata inconsistency.

Instruction Scope

Runtime instructions ask the agent to read full source trees and produce many local artifacts (expected for this tool). The scripts create and write files on disk and the ProcessFileManager has a hardcoded default baseDir of '/Users/admin/.openclaw/workspace' (creates folders and files there) which is surprising and platform-specific. The SKILL.md also references external CLI tools (ai-plan-generator, clawteam) that are not included; the convert script calls integrator.generateValidationStandards(), but that method is not defined in the integrator — this is a runtime bug that could cause errors during execution. No instructions request secrets, but outputs may contain sensitive business code and credentials if present in the analyzed source (so exercising principle of least privilege is important).

Install Mechanism

There is no install spec (instruction-only skill), so nothing will be automatically downloaded or installed by the platform. The included Node.js scripts are present but will only run if the user or agent executes them. This is lower-risk than remote downloads, but local execution still writes files.

Credentials

The skill declares no required environment variables or credentials (good). However it assumes a Node.js runtime (README notes Node.js v14+) and local filesystem access to the legacy codebase — which is expected for its purpose. The integrator generates integration configs (database, redis, enterprise_wechat) that may imply further credentials are needed downstream, but none are declared here.

Persistence & Privilege

The skill does not set always:true and does not request platform-wide privileges. Nevertheless, its ProcessFileManager defaults to writing into a hardcoded user path (/Users/admin/.openclaw/workspace) and will create project directories and files there if executed — this persistent file activity is surprising and could pollute or overwrite user workspace if run without checking the path. The skill does not modify other skills' configuration.

Scan Findings in Context

[hardcoded_user_path] unexpected: ProcessFileManager constructor defaults baseDir to '/Users/admin/.openclaw/workspace'. Writing to a hardcoded user home path is unexpected and platform-specific; user should verify or override before running.

[fs_write_files] expected: The converter and file manager write JSON/MD/YAML files to disk (business-rules.json, technical-specs.yaml, etc.). This is expected for a conversion/analysis tool but means outputs may include sensitive code or secrets present in the analyzed source.

[missing_method_call] unexpected: convert-to-ai-plan-generator.cjs calls integrator.generateValidationStandards(), but that method is not defined in code-archaeology-integrator.cjs — likely a bug that will cause a runtime failure.

What to consider before installing

This skill appears to do what it says (analyze legacy code + produce migration/context docs), but it contains sloppy defaults and bugs. Before running: (1) Inspect the included scripts locally and fix the missing method or other errors; (2) do not run them directly against a production codebase — run in an isolated environment or on a copy; (3) override the default baseDir (/Users/admin/...) to a safe workspace to avoid accidental file writes; (4) be aware that outputs may include sensitive data from your source — treat outputs like secrets and store them appropriately; (5) ensure required external tools (ai-plan-generator, clawteam) and Node.js are deliberate and trusted. If you lack the ability to inspect or sandbox the code, treat this package with caution.

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

# 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

node convert-to-ai-plan-generator.cjs /path/to/archaeology-results output-dir domain