sourcecode-analyzer

name	sourcecode-analyzer
description	Multi-agent deep source code analysis for architecture, coding style, design patterns, languages, frameworks, libraries, module structure, extension points, and integration readiness. Use when agents must understand a codebase before planning features, refactoring, integration, migration, auditing, or documentation.
projectType	all

Source Code Analyzer

Objective

Produce a high-confidence architecture and integration analysis of the repository with evidence from real files.

Scope

Analyze:

• Architecture boundaries and layering
• Framework/CMS/runtime and dependency stack
• Coding style and conventions
• Modules/themes/plugins and extension points
• API surfaces (REST/GraphQL/webhooks/events/CLI/jobs)
• Data layer and configuration model
• Security and operational posture
• Integration capability and constraints

Do not:

• Modify business logic
• Run destructive commands
• Install or upgrade dependencies unless requested

Required Output

Write a report to _analytics/structure.md (or user-provided path) with the exact section order defined in "Report Template".

Evidence Rules

For every important claim:

• Include concrete evidence (file path, symbol/class/function, and short snippet summary)
• Mark confidence as High, Medium, or Low
• Label statement type:
  • Observed: Directly confirmed in source
  • Inferred: Derived from multiple observed facts
  • Assumed: Plausible but not yet confirmed

Avoid ungrounded conclusions.

Multi-Agent Orchestration

If subagents are available, split work in parallel:

1. Architecture lane

• Map directory topology, layers, modules/plugins/themes
• Identify entry points and dependency direction

2. Style and design lane

• Detect naming conventions, folder conventions, patterns, anti-patterns
• Detect coding standards and linting/testing quality gates

3. Dependency and runtime lane

• Detect language/runtime/framework versions
• Inventory key libraries and their roles

4. Integration and security lane

• Map APIs, events/hooks, queues, cron/jobs, webhooks, third-party SDKs
• Assess authN/authZ, input validation, secrets handling, and attack surface

Coordinator responsibilities:

• Normalize lane outputs
• Resolve contradictions
• Produce one final report with evidence and confidence

If subagents are unavailable, execute the same lanes sequentially.

Workflow

Step 0 — Knowledge Lookup (Pre-Analysis)

Before starting full analysis, check if pre-analyzed knowledge exists:

1. Check if heraspec/knowledge/index.json exists in the project
2. Read all entries and match against the current project:
   • For file-contains signals: check if the file exists AND contains the specified string
   • For directory-exists signals: check if the directory exists
   • Each matched signal = +1 to the match score
3. If score >= minMatchScore for any entry:
   • Read the corresponding structure.md from heraspec/knowledge/<knowledgePath>/
   • Use it as the baseline analysis — skip redundant Steps 1-8 for sections already covered
   • Focus only on project-specific differences (custom plugins, configs, .env, custom code)
   • Output: merge baseline knowledge + project-specific delta into final report
4. Also check heraspec/knowledge/custom/index.json for project-specific knowledge entries
5. If no match found in either index: proceed with full analysis from Step 1

Knowledge hierarchy: heraspec/knowledge/<category>/<runtime>/<framework>/<cms>/

Step 1 - Baseline Metadata

Read root metadata first:

• composer.json, composer.lock
• package.json, lockfiles
• docker*, Makefile, CI configs
• .env.example, config directories

Capture:

• Language/runtime versions
• Framework/CMS versions
• Build and deployment model

Step 2 - Repository Topology

Map major folders and responsibilities:

• Core/domain/infrastructure boundaries
• Plugin/module/theme architecture
• Shared libraries and cross-cutting concerns
• Bootstrapping and entry points

Step 3 - Architectural Patterns

Identify and evaluate:

• Layered/hexagonal/modular/monolith/microservice patterns
• Service container/DI usage
• Event-driven flows
• Boundaries and coupling hotspots

Step 4 - Coding Style and Design Conventions

Inspect representative files from each major layer:

• Naming conventions (class/function/file)
• Folder and namespace strategy
• Error handling patterns
• Test style and coverage signals
• Static analysis/lint/format rules

Step 5 - Extension Model

Map extensibility mechanisms:

• Hooks/filters/events/listeners
• Plugin/module registration and lifecycle
• Theme/template override model
• Custom providers, middleware, policies

Step 6 - API and Interaction Surfaces

Inventory internal and external interfaces:

• REST/GraphQL routes and controllers
• Command bus, queues, jobs, schedulers
• CLI commands, webhooks, callbacks
• Public SDK/service abstractions

Step 7 - Data and State

Analyze:

• ORM/data access strategy
• Migration and seeding patterns
• Cache/session/queue drivers
• Transaction boundaries and consistency risks

Step 8 - Security and Compliance Signals

Check:

• Authentication and authorization model
• CSRF/XSS/SQLi protections
• Secrets and credential handling
• Rate limiting and abuse protection
• Audit logging and sensitive operation traces

Step 9 - Integration Readiness

Evaluate integration capability across:

• Data integration
• API integration
• Event integration
• UI/theme integration
• Deployment/infra integration

For each integration type, summarize:

• Available entry points
• Required adapters
• Estimated complexity (Low/Medium/High)
• Major risks and mitigations

Step 10 - Synthesis

Consolidate findings into one report, prioritize evidence-backed conclusions, and list unknowns that block confidence.

Report Template

Use this exact section order in _analytics/structure.md:

1. Executive Summary
2. Technology Profile
3. Repository Topology
4. Architecture and Dependency Flow
5. Coding Style and Conventions
6. Extension Points (Modules/Themes/Plugins/Hooks)
7. API and Interaction Surfaces
8. Data Model and State Management
9. Security Posture
10. Integration Capability Matrix
11. Strengths, Weaknesses, Risks
12. Top 10 Evidence Items
13. Unknowns and Verification Plan
14. Recommended Next Actions (30/60/90 day)

Integration Capability Matrix Format

Use one row per integration domain:

Domain	Entry Points	Required Adapters	Complexity	Risks	Confidence

Domains to include:

• External APIs
• Authentication/SSO
• Payment
• Messaging/Queue
• Storage/CDN
• Observability
• Admin/UI customization
• Content/data migration

Completion Checklist

Complete the skill execution only when all conditions are met:

• Report file exists at target path
• Every critical claim has evidence
• Assumptions are explicitly marked
• Integration matrix is complete
• Top risks include mitigation guidance