project-analyzer

project-analyzer

When to use

Use this skill when:

• Starting work on an unfamiliar project
• Onboarding to a new codebase
• Auditing the current state of agent docs, contexts, and features
• Creating a baseline understanding of the project for future work
• Generating comprehensive project documentation for knowledge transfer

Do NOT use when:

• Small, focused code changes
• Regular feature development

Procedure: Analyze a project

A project analysis is a systematic walkthrough of the entire codebase that:

1. Detects — framework, language, tech stack, patterns, legacy vs. modern
2. Inventories — modules, services, models, endpoints, tests
3. Analyzes — business domains, data flows, API contracts, dependencies
4. Documents — writes structured analysis files to agents/evidence/analysis/
5. Assesses — identifies gaps, technical debt, missing docs

It orchestrates other skills and commands to produce a comprehensive picture.

Analysis output

All analysis results are written to agents/evidence/analysis/ in a structured directory layout. The goal: someone could rebuild the project from these documents alone.

Directory structure

agents/evidence/analysis/
├── overview.md                  ← Project profile, tech stack, architecture summary
├── architecture/
│   ├── database.md              ← Schema, connections, multi-tenancy, migrations
│   ├── api.md                   ← Versioning, routes, middleware, auth flow
│   ├── infrastructure.md        ← Docker, CI/CD, deployment, AWS, monitoring
│   └── patterns.md              ← Design patterns used (Repository, Service, Pipeline, etc.)
├── domains/
│   ├── {domain}.md              ← One file per business domain (see below)
│   └── ...
├── modules/
│   ├── {module}.md              ← One file per module (see below)
│   └── ...
├── models/
│   ├── api-database.md          ← All api_database models, relationships, key columns
│   └── customer-database.md     ← All customer_database models, relationships, key columns
├── services/
│   └── service-map.md           ← All services with purpose, dependencies, key methods
├── api/
│   ├── endpoints-v1.md          ← All v1 endpoints: route, controller, request, resource
│   ├── endpoints-v2.md          ← All v2 endpoints: route, controller, request, resource
│   └── contracts.md             ← API contracts: request/response shapes, validation rules
└── testing/
    └── test-map.md              ← Test suites, coverage areas, test data strategy

Domain analysis files

Each business domain gets its own file in agents/evidence/analysis/domains/. A domain groups related models, services, controllers, jobs, and events around a business concept:

Not every project has all domains. Only create files for domains that actually exist.

Domain file template

Each domain file should contain:

# Domain: {Name}

## Purpose

{What this domain does in 2-3 sentences}

## Models

| Model | Table | Connection | Key Relationships |
|---|---|---|---|

## Services

| Service | Purpose | Key Methods |
|---|---|---|

## Controllers (API Endpoints)

| Endpoint | Controller | Request | Resource |
|---|---|---|---|

## Jobs & Events

| Class | Type | Trigger | What it does |
|---|---|---|---|

## Business Rules

- {Rule 1: e.g. "A project can only be deleted if it has no working times"}
- {Rule 2}

## Data Flow

{Describe how data moves through this domain — from input to storage to output}

## Dependencies

- Depends on: {other domains}
- Depended on by: {other domains}

Module analysis files

Each module gets its own file in agents/evidence/analysis/modules/. Format:

# Module: {Name}

## Purpose

{What this module does}

## Structure

{Directory tree with key files}

## Public API

{What other parts of the app use from this module: Services, Events, Models}

## Internal Components

{Controllers, Jobs, Commands, Listeners that are module-internal}

## Configuration

{Config files, .env variables, feature flags}

## Testing

{Test suites, test data, stubs}

Detection checklist

Framework & language (multi-stack)

After detecting any match, record the stack in the analysis output and select the matching project-analysis-* sub-skill (Laravel, Symfony, Next.js, React, Node/Express, Zend/Laminas) — fall back to project-analysis-core if no framework-specific sub-skill applies.

Project type

Legacy indicators (stack-aware)

Build & tooling (stack-agnostic)

Analysis phases

Phase 1: Project overview

• Read AGENTS.md, .github/copilot-instructions.md, README.md
• Detect framework, version, tech stack
• Identify build tools and quality tooling
• Classify: legacy vs. modern, monolith vs. modular
• Output: agents/evidence/analysis/overview.md

Phase 2: Architecture

• Map directory structure (top 3 levels)
• Identify architectural patterns (MVC, modules, services, repositories)
• Detect multi-tenancy, queue system, caching
• Count: models, controllers, services, jobs, commands
• Output: agents/evidence/analysis/architecture/*.md

Phase 3: Data layer

• List all models with their connections, tables, and key relationships
• Map database schema: tables, foreign keys, indexes
• Document multi-tenant split (which tables in which DB)
• Output: agents/evidence/analysis/models/api-database.md, customer-database.md

Phase 4: Business domains

• Identify domains from models, services, routes, and directory structure
• For each domain: map models → services → controllers → jobs → events
• Document business rules and data flows
• Document inter-domain dependencies
• Output: agents/evidence/analysis/domains/{domain}.md (one per domain)

Phase 5: API surface

• List all endpoints with controller, request, resource, OpenAPI attributes
• Document request/response contracts (field names, types, validation rules)
• Map version differences (v1 vs v2)
• Output: agents/evidence/analysis/api/endpoints-v1.md, endpoints-v2.md, contracts.md

Phase 6: Service map

• List all services with purpose, key methods, and dependencies
• Map service → repository → model relationships
• Identify God services (too many responsibilities)
• Output: agents/evidence/analysis/services/service-map.md

Phase 7: Module inventory (if modules exist)

• List all modules with purpose
• For each module: structure, public API, internal components, tests
• Check for module-level agent docs
• Output: agents/evidence/analysis/modules/{module}.md (one per module)

Phase 8: Infrastructure & testing

• Docker setup, CI/CD pipelines, deployment
• Test suites, coverage areas, test data strategy
• Output: agents/evidence/analysis/architecture/infrastructure.md, agents/evidence/analysis/testing/test-map.md

Phase 9: Agent docs audit

• List all existing docs in agents/reference/docs/, agents/settings/contexts/, module agents/
• Check for outdated docs (reference deleted files/classes)
• Identify undocumented areas
• Check for stale roadmaps

Phase 10: Gap analysis & action plan

• Modules without context docs → offer /context-create
• Complex services without docs → offer /context-create
• Existing docs that reference deleted code → offer /context-refactor
• Stale roadmaps (all steps done) → suggest archiving

Integration with other skills

Workflow

1. Ask scope: Full analysis or specific area (e.g. only domains, only API)?
2. Run phases incrementally — show findings after each phase, ask before continuing.
3. Write files after each phase — don't batch all writing to the end.
4. Ask before creating each file with numbered options:

   > 1. Create — {filename}
   > 2. Skip
   

5. Update existing files if re-running analysis — don't create duplicates.

Output format

1. Structured analysis document in agents/evidence/analysis/
2. Tech stack inventory with versions and dependencies
3. Architecture diagram or module map

Auto-trigger keywords

• project analysis
• codebase analysis
• architecture analysis

Gotcha

• Full project analysis can take several minutes — warn the user about the time investment.
• Don't analyze parts of the codebase that the user hasn't asked about — respect scope.
• Analysis documents go in agents/evidence/analysis/, not in .augment/.

Do NOT

• Do NOT create analysis files without asking — always confirm each creation.
• Do NOT modify existing code — this is analysis only.
• Do NOT commit or push.
• Do NOT overwhelm the user — present findings incrementally, one phase at a time.
• Do NOT analyze third-party code in vendor/ or node_modules/.
• Do NOT duplicate content that already exists in agents/reference/docs/ or agents/settings/contexts/ — reference it instead. Analysis files complement existing docs, they don't replace them.