Collection

---
name: Project Context Analyzer
description: Analyzes project structure, dependencies, and patterns to generate comprehensive context documentation. Uses parallel agent execution for faster analysis. Helps understand unfamiliar codebases quickly.
trigger: both
allowed-tools:
  - Read
  - Glob
  - Bash
  - Write
  - Task
  - TaskOutput
---

# Purpose

Analyze a project's structure, dependencies, framework, and patterns to generate comprehensive context documentation. Uses parallel agent swarm execution for blazing-fast analysis. Helps with onboarding, understanding unfamiliar codebases, and providing context to other AI agents. Uses specialized analysis tools for deep project understanding.

## Variables

ENABLE_JAVASCRIPT: true           # Enable JavaScript/TypeScript project analysis
ENABLE_PYTHON: true               # Enable Python project analysis
ENABLE_GO: false                  # Enable Go project analysis (not yet implemented)
ENABLE_PARALLEL_EXECUTION: true   # Use parallel agent swarm for faster analysis
OUTPUT_MODE: display              # Options: display (show results), save (write to file)
OUTPUT_FILE: .project-context.md  # Where to save report if OUTPUT_MODE is save
SUPPORTED_PROJECT_TYPES: javascript, typescript, python # Currently supported project types

## Workflow

1. **Parse User Request**

   - Determine intent: analyze, generate, show project context
   - Determine output mode: display or save
   - Display mode triggers: "analyze project", "show me project context", "what is this project"
   - Save mode triggers: "generate project context and save", "save project context"
   - Example: "analyze this project" → Intent: analyze, Mode: display

2. **Detect Project Type**

   - Tool: Run `tools/detect_framework.py`
   - Checks for: package.json (JS/TS), requirements.txt/pyproject.toml (Python), go.mod (Go)
   - Returns: {type, framework, language, confidence}
   - Example: package.json found → {type: "nodejs", framework: "react-vite", language: "typescript", confidence: "high"}

3. **Route to Cookbook**

   - Based on detected type and ENABLE flags
   - JavaScript/TypeScript: IF package.json AND ENABLE_JAVASCRIPT → javascript.md
   - Python: IF requirements.txt/pyproject.toml AND ENABLE_PYTHON → python.md
   - Unknown: IF no match → Basic analysis with Glob/Read
   - Example: TypeScript project detected + ENABLE_JAVASCRIPT=true → Route to cookbook/javascript.md

4. **Execute Analysis Tools**

   - IF: ENABLE_PARALLEL_EXECUTION is true → Launch parallel agent swarm for analysis tasks
   - Tools in `tools/` directory perform specialized analysis
   - Tool: Task with run_in_background: true for each analysis task
   - Agents: DependencyAnalyzer, StructureMapper, EntryPointFinder run simultaneously
   - Common tools: detect_framework, analyze_dependencies, analyze_structure, find_entry_points
   - Example: JavaScript project → Launch 3 parallel agents (dependencies, structure, entry points) → All complete in ~4s vs ~9s sequential

5. **Aggregate Results**

   - IF parallel execution used → Collect all agent results using TaskOutput
   - Combine data from all analysis tools
   - Generate formatted report with sections: overview, structure, dependencies, entry points
   - Keep comprehensive but concise (focus on what's important)
   - Example: Collect swarm results → Combine framework info + dependencies + structure → Complete context document with performance metrics

6. **Output Report**
   - IF OUTPUT_MODE is "display" OR user requested display: Show results in chat
   - IF OUTPUT_MODE is "save" OR user requested save: Write to OUTPUT_FILE
   - Example: "show me context" → Display in chat, "generate and save" → Write to .project-context.md

## Cookbook

### JavaScript/TypeScript Projects

- IF: The project has a `package.json` file AND `ENABLE_JAVASCRIPT` is true.
- THEN: Read and execute: `.claude/skills/project-context/cookbook/javascript.md`

### Python Projects

- IF: The project has `requirements.txt` or `pyproject.toml` AND `ENABLE_PYTHON` is true.
- THEN: Read and execute: `.claude/skills/project-context/cookbook/python.md`

### Unknown Project Type

- IF: No specific project type detected.
- THEN: Perform basic analysis using available built-in tools (Glob, Read).
- Report what can be detected and suggest adding Go or other language support.