Analyze and summarize this project's structure, identifying key components and technologies.

Show me the dependency graph for this project, highlighting critical and outdated packages.

Calculate complexity metrics for the core modules and identify high-risk areas.

1. Identify project type (monorepo, library, application, etc.)
2. Map top-level directories and their purposes
3. Locate entry points (main, index, app files)
4. Identify configuration files and their roles
5. Note test locations and documentation

## Project: {name}
**Type:** {monorepo|library|application|service|cli}
**Stack:** {primary technologies}

### Structure
- `src/` - Main source code
- `tests/` - Test suites
- `docs/` - Documentation
...

### Entry Points
- Main: `src/index.ts`
- CLI: `bin/cli.js`

### Key Files
- Config: `tsconfig.json`, `.eslintrc`
- CI: `.github/workflows/`

# Check outdated packages
npm outdated --json

# Audit for vulnerabilities
npm audit --json

# Analyze bundle size impact
npx bundle-phobia-cli package-name

# List installed with versions
pip list --format=json

# Check for updates
pip list --outdated --format=json

# Security check
pip-audit --format=json

+-------------+     +-------------+
|   Web UI    |---->|   API       |
+-------------+     +------+------+
                           |
                    +------v------+
                    |  Services   |
                    +------+------+
                           |
              +------------+------------+
              v            v            v
        +---------+  +---------+  +---------+
        |   DB    |  |  Cache  |  |  Queue  |
        +---------+  +---------+  +---------+

# JavaScript/TypeScript
npx escomplex src/ --format json

# Python
radon cc src/ -a -j

# Go
gocyclo -over 10 ./...

# General (multi-language)
lizard src/

# JavaScript - dependency-cruiser
npx dependency-cruiser --output-type dot src | dot -T svg > deps.svg

# Python - pydeps
pydeps src --cluster --max-bacon 2

# TypeScript/JavaScript
# Find all exports
grep -r "^export" src/ --include="*.ts"

# Find default exports
grep -r "export default" src/ --include="*.ts"

## Public API Surface

### Exported Functions
| Function | Module | Parameters | Returns |
|----------|--------|------------|---------|
| `createUser` | `src/users.ts` | `(data: UserInput)` | `Promise<User>` |
| `validateEmail` | `src/utils.ts` | `(email: string)` | `boolean` |

### Exported Types
| Type | Module | Description |
|------|--------|-------------|
| `User` | `src/types.ts` | User entity interface |
| `Config` | `src/config.ts` | Configuration options |

### Breaking Change Risk
- High: `createUser` - used by 15 external modules
- Low: `validateEmail` - internal utility only

User Input --> Validation --> Business Logic --> Persistence --> Response
     |              |               |                |              |
     v              v               v                v              v
  [Forms]      [Validators]    [Services]       [Database]     [API Response]

## External Integrations

### Databases
| Type | Connection | Usage |
|------|------------|-------|
| PostgreSQL | `DATABASE_URL` | Primary data store |
| Redis | `REDIS_URL` | Session cache, job queue |

### Third-Party APIs
| Service | Purpose | Criticality |
|---------|---------|-------------|
| Stripe | Payments | Critical |
| SendGrid | Email | High |
| S3 | File storage | High |

### Internal Services
| Service | Protocol | Purpose |
|---------|----------|---------|
| Auth Service | gRPC | Authentication |
| Notification Service | HTTP | Push notifications |

# Node.js
npx license-checker --json > licenses.json
npx license-checker --onlyAllow "MIT;Apache-2.0;BSD-3-Clause"

# Python
pip-licenses --format=json > licenses.json

# Go
go-licenses report ./...

## Technical Debt Assessment

### High Priority (Address within 2 weeks)
- [ ] 3 critical security vulnerabilities in dependencies
- [ ] Circular dependency between auth and user modules

### Medium Priority (Address within quarter)
- [ ] 5 modules with cyclomatic complexity > 20
- [ ] Test coverage below 60% for payment module

### Low Priority (Track and address opportunistically)
- [ ] Outdated documentation for API endpoints
- [ ] Inconsistent error handling patterns

## First PR Guide for {Project}

### Quick Setup
1. Fork and clone the repository
2. Install dependencies: `npm install`
3. Copy `.env.example` to `.env`
4. Run tests: `npm test`
5. Start dev server: `npm run dev`

### Finding Your First Issue
- Look for issues labeled `good first issue` or `help wanted`
- Issues in `docs/` are great for getting familiar
- Small bug fixes help you understand the codebase

### Code Conventions
- Use TypeScript strict mode
- Follow ESLint configuration
- Write tests for new features
- Update documentation for API changes

### PR Process
1. Create branch: `feat/issue-123-description`
2. Make atomic commits with conventional commit messages
3. Run `npm test` and `npm run lint` before pushing
4. Create PR with description linking to issue
5. Address review comments
6. Squash merge when approved

### Getting Help
- Check existing documentation in `docs/`
- Ask questions in PR comments
- Join #dev-help channel on Slack

1. Scan root directory for project type indicators
2. Read primary config files (package.json, etc.)
3. Map directory structure (exclude node_modules, .git, etc.)
4. Identify entry points and build outputs
5. Analyze dependencies for health/security
6. Calculate complexity metrics for core modules
7. Detect architectural patterns
8. Map data flows and integrations
9. Scan for license compliance
10. Generate summary with recommendations

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "command": "claude-skill project-understanding --quick-summary"
    }]
  }
}

interface ProjectAnalysisHookResponse {
  projectType: 'monorepo' | 'library' | 'application' | 'service' | 'cli';
  stack: string[];
  entryPoints: string[];
  keyDirectories: Record<string, string>;
  warnings?: string[];
}

name: Project Analysis
on:
  pull_request:
    types: [opened]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Dependency Analysis
        run: |
          npm audit --json > audit.json
          npm outdated --json > outdated.json

      - name: Complexity Check
        run: |
          npx escomplex src/ --format json > complexity.json

      - name: License Check
        run: |
          npx license-checker --onlyAllow "MIT;Apache-2.0;BSD-3-Clause"

      - name: Comment Results
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const audit = JSON.parse(fs.readFileSync('audit.json'));
            // Create PR comment with analysis results

#!/bin/bash
# .git/hooks/pre-commit

# Check for high complexity in changed files
changed_files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|js)$')

for file in $changed_files; do
  complexity=$(npx escomplex "$file" --format json | jq '.aggregate.cyclomatic')
  if [ "$complexity" -gt 20 ]; then
    echo "Warning: $file has high cyclomatic complexity: $complexity"
  fi
done