analyze-project

name	analyze-project
description	Use when starting work on an unfamiliar project or needing to understand a codebase - performs comprehensive analysis discovering architecture, patterns, dependencies, testing coverage, and improvement opportunities. Do NOT use on projects you already know well or for targeted questions about specific files - use direct exploration instead for focused queries.
inputs	[{"from":"any","field":"focus","required":false}]
outputs	[{"field":"analysis_report","type":"file_path"},{"field":"analysis_json","type":"file_path"}]
next_skills	["pop-project-setup","pop-writing-plans"]
workflow	{"id":"analyze-project","name":"Project Analysis Workflow","version":1,"description":"Comprehensive codebase analysis with progressive disclosure","steps":[{"id":"detect_project","description":"Detect project type and basic structure","type":"agent","agent":"code-explorer","next":"depth_decision"},{"id":"depth_decision","description":"Choose analysis depth","type":"user_decision","question":"What level of analysis do you need?","header":"Depth","options":[{"id":"quick","label":"Quick","description":"5-10 line summary, ~30 seconds","next":"quick_analysis"},{"id":"standard","label":"Standard","description":"Full analysis with recommendations","next":"focus_decision"},{"id":"deep","label":"Deep dive","description":"Exhaustive analysis with metrics","next":"focus_decision"}],"next_map":{"quick":"quick_analysis","standard":"focus_decision","deep":"focus_decision"}},{"id":"quick_analysis","description":"Generate quick summary","type":"skill","skill":"pop-auto-docs","next":"complete"},{"id":"focus_decision","description":"Choose analysis focus area","type":"user_decision","question":"Which area should we focus on?","header":"Focus","options":[{"id":"architecture","label":"Architecture","description":"Structure, patterns, entry points","next":"run_analysis"},{"id":"quality","label":"Quality","description":"Tests, linting, TypeScript","next":"run_analysis"},{"id":"dependencies","label":"Dependencies","description":"Packages, vulnerabilities","next":"run_analysis"},{"id":"all","label":"All areas","description":"Complete analysis","next":"run_analysis"}],"next_map":{"architecture":"run_analysis","quality":"run_analysis","dependencies":"run_analysis","all":"run_analysis"}},{"id":"run_analysis","description":"Execute analysis based on selections","type":"spawn_agents","agents":[{"type":"code-explorer","task":"Map project structure and architecture patterns"},{"type":"performance-optimizer","task":"Identify performance issues and bottlenecks"}],"wait_for":"all","next":"output_decision"},{"id":"output_decision","description":"Choose output format","type":"user_decision","question":"How should we present the analysis?","header":"Output","options":[{"id":"markdown","label":"Markdown","description":"Human-readable report","next":"generate_report"},{"id":"json","label":"JSON","description":"Machine-readable for tooling","next":"generate_json"},{"id":"both","label":"Both","description":"Markdown + JSON files","next":"generate_both"}],"next_map":{"markdown":"generate_report","json":"generate_json","both":"generate_both"}},{"id":"generate_report","description":"Generate markdown analysis report","type":"skill","skill":"pop-auto-docs","next":"next_step_decision"},{"id":"generate_json","description":"Generate JSON analysis output","type":"skill","skill":"pop-auto-docs","next":"next_step_decision"},{"id":"generate_both","description":"Generate both output formats","type":"skill","skill":"pop-auto-docs","next":"next_step_decision"},{"id":"next_step_decision","description":"Decide what to do after analysis","type":"user_decision","question":"Analysis complete. What's next?","header":"Next Step","options":[{"id":"generate","label":"Generate MCP","description":"Create project-specific tools","next":"generate_mcp"},{"id":"plan","label":"Create plan","description":"Plan improvements","next":"create_plan"},{"id":"done","label":"Done","description":"Stop here","next":"complete"}],"next_map":{"generate":"generate_mcp","plan":"create_plan","done":"complete"}},{"id":"generate_mcp","description":"Generate project-specific MCP server","type":"skill","skill":"pop-generate-mcp","next":"complete"},{"id":"create_plan","description":"Create implementation plan for improvements","type":"skill","skill":"pop-writing-plans","next":"complete"},{"id":"complete","description":"Analysis workflow finished","type":"terminal"}]}

Analyze Project

Overview

Perform deep analysis of a codebase to understand its architecture, patterns, dependencies, and opportunities for improvement.

Core principle: Understand before changing. Map before navigating.

Trigger: /popkit:project analyze command or when starting work on unfamiliar project

Arguments

Flag	Description
--json	Output structured JSON instead of markdown, save to .claude/analysis.json
--quick	Quick summary only (5-10 lines)
--focus <area>	Focus analysis: arch, deps, quality, patterns

JSON Output Mode

When --json flag is provided:

1. Output Format: Structured JSON matching output-styles/schemas/project-analysis.schema.json
2. Save Location: .claude/analysis.json
3. Purpose: Machine-readable output for skill generators and MCP generators

JSON Output Process

import sys
import json
from datetime import datetime
from pathlib import Path

# Add pattern detector to path
# No longer needed - install popkit-shared instead
from pattern_detector import analyze_project, detect_frameworks

# Detect patterns
project_dir = Path.cwd()
patterns = analyze_project(project_dir)
frameworks = detect_frameworks(project_dir)

# Build output
output = {
    "project_name": project_dir.name,
    "project_type": frameworks[0].name if frameworks else ,
    : datetime.now().isoformat(),
    : [
        {: p.name, : p.confidence, : }
         p  frameworks
    ],
    : [
        {
            : p.name,
            : p.category,
            : p.confidence,
            : p.examples,
            : p.description
        }
         p  patterns  p.category != 
    ],
    : [],  
    : [],  
    : {},  
    : {}  
}


claude_dir = project_dir / 
claude_dir.mkdir(exist_ok=)
(claude_dir / ).write_text(json.dumps(output, indent=))
(json.dumps(output, indent=))