--- 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 ` | Focus analysis: `arch`, `deps`, `quality`, `patterns` | ## Analysis Areas ### 1. Project Structure Directory structure, entry points, file counts by type. ### 2. Technology Stack Package managers, frameworks (Next.js, React, Vue, Express, FastAPI, Rust), databases (Supabase, Prisma, MongoDB, PostgreSQL). ### 3. Architecture Patterns Frontend (component structure, state management, routing), Backend (API design, service layer, database access), Common (error handling, logging, configuration). ### 4. Code Quality Linting config, TypeScript strictness, TODO/FIXME comments. ### 5. Testing Coverage Test files, test frameworks, coverage reports. ### 6. Dependencies Count, outdated packages, security vulnerabilities. ### 7. CI/CD and DevOps CI config, Docker, deployment configuration. ## Output Format ### Markdown Report ```markdown # [Project Name] Analysis Report ## Summary - **Type**: [Web App / API / CLI / Library] - **Stack**: [Primary technologies] - **Size**: [Files, Lines of code] - **Health**: [Good / Needs attention / Critical issues] ## Technology Stack ### Frontend - Framework: [Next.js 14 / React / Vue / etc.] - Styling: [Tailwind / styled-components / etc.] - State: [Redux / Zustand / Context] ### Backend - Runtime: [Node.js / Python / Rust / Go] - Framework: [Express / FastAPI / Actix] - Database: [PostgreSQL / MongoDB / etc.] ### DevOps - CI/CD: [GitHub Actions / GitLab CI / etc.] - Deployment: [Vercel / AWS / etc.] - Container: [Docker / etc.] ## Architecture ### Key Patterns - [Pattern 1]: [Where used] - [Pattern 2]: [Where used] ### Entry Points - Main: `[path]` - API: `[path]` - Tests: `[path]` ## Code Quality | Metric | Value | Status | | ----------------- | -------------------- | ------------ | | Linting | [Configured/Missing] | [OK/Warning] | | TypeScript Strict | [Yes/No] | [OK/Warning] | | Test Coverage | [X%] | [OK/Warning] | | TODO Comments | [N] | [OK/Warning] | ## Recommendations ### Critical 1. [Issue requiring immediate attention] ### High Priority 1. [Important improvement] ### Nice to Have 1. [Enhancement suggestion] ## Next Steps 1. Run `/generate-mcp` to create project-specific tools 2. Run `/generate-skills` to capture discovered patterns 3. Run `/setup-precommit` to configure quality gates ``` ### JSON Output When `--json` flag is provided, saves to `.claude/analysis.json`: ```json { "project_name": "project-name", "project_type": "nextjs", "analyzed_at": "2026-01-30T00:00:00Z", "frameworks": [{ "name": "nextjs", "confidence": 0.95, "version": "14.0.0" }], "patterns": [ { "name": "pattern-name", "category": "architecture", "confidence": 0.85, "examples": ["path1", "path2"], "description": "Description" } ], "recommended_skills": ["skill1", "skill2"], "recommended_agents": ["agent1", "agent2"], "commands": {}, "quality_metrics": {} } ``` ## Skill/Agent Recommendations Based on detected patterns: | Pattern | Recommended Skill | Priority | | ---------------------- | ------------------------ | -------- | | nextjs + vercel-config | `project:deploy` | high | | prisma OR drizzle | `project:db-migrate` | high | | supabase | `project:supabase-sync` | medium | | docker-compose | `project:docker-dev` | medium | | feature-flags | `project:feature-toggle` | low | | Pattern | Recommended Agent | | --------------------------- | ------------------------ | | Large codebase (>100 files) | `performance-optimizer` | | React/Vue components | `accessibility-guardian` | | API routes | `api-designer` | | Security-sensitive | `security-auditor` | | Low test coverage | `test-writer-fixer` | ## Integration **Called by:** - Manual `/analyze-project` command - After `/init-project` **Informs:** - **/generate-mcp** - What tools to create - **/generate-skills** - What patterns to capture - **/setup-precommit** - What checks to configure