References (archive): SCAFFOLD_SKILLS_ARCHIVE_MAP.md — ProjectAnalyzer monorepo/service detection from Auto-Claude-develop analysis/analyzers.

Step 1: Identify Project Root

Locate project root by finding manifest files:

Search for package manager files:

• package.json (Node.js/JavaScript/TypeScript)

• requirements.txt , pyproject.toml , setup.py (Python)

• go.mod (Go)

• Cargo.toml (Rust)

• pom.xml , build.gradle (Java/Maven/Gradle)

• composer.json (PHP)

Identify project root:

• Directory containing primary package manager file

• Handle monorepos (multiple package.json files)

• Detect workspace configuration

Validate project root:

• Check for .git directory

• Verify source code directories exist

• Ensure manifest files are parsable

Step 2: Detect Project Type

Classify project based on manifest files and directory structure:

Frontend Projects:

• Indicators: React, Vue, Angular, Svelte dependencies

• Directory: src/components/ , public/ , assets/

• Frameworks: Next.js, Nuxt.js, Gatsby, Vite

Backend Projects:

• Indicators: Express, FastAPI, Django, Flask, Gin dependencies

• Directory: routes/ , controllers/ , models/ , api/

• Frameworks: Next.js API routes, FastAPI, Express

Fullstack Projects:

• Indicators: Both frontend and backend frameworks

• Directory: Combined frontend + backend structure

• Frameworks: Next.js, Remix, SvelteKit, Nuxt.js

Library/Package Projects:

• Indicators: No application-specific directories

• Files: index.ts , lib/ , dist/ , build/

• Manifests: library field in package.json

CLI Projects:

• Indicators: bin field in package.json

• Files: CLI entry points, command parsers

• Dependencies: Commander, Yargs, Inquirer

Mobile Projects:

• Indicators: React Native, Flutter, Ionic dependencies

• Files: android/ , ios/ , mobile/

• Frameworks: React Native, Expo, Flutter

Monorepo Projects:

• Indicators: workspaces in package.json, pnpm-workspace.yaml

• Structure: Multiple packages in subdirectories

• Tools: Turborepo, Nx, Lerna

Microservices Projects:

• Indicators: Multiple service directories

• Files: docker-compose.yml , service configs

• Structure: Service-based organization

Step 3: Framework Detection

Identify frameworks from manifest files and imports:

Read package.json dependencies (Node.js):

• Parse dependencies and devDependencies

• Detect framework versions

• Categorize by type (framework, ui-library, testing, etc.)

Read requirements.txt (Python):

• Parse Python dependencies

• Detect FastAPI, Django, Flask

• Identify version constraints

Analyze imports (optional deep scan):

• Scan source files for import statements

• Detect used vs declared dependencies

• Identify framework-specific patterns

Framework Categories:

• Framework: React, Next.js, FastAPI, Express

• UI Library: Material-UI, Ant Design, Chakra UI

• State Management: Redux, Zustand, Pinia

• Testing: Jest, Vitest, Cypress, Playwright

• Build Tool: Vite, Webpack, Rollup, esbuild

• Database: Prisma, TypeORM, SQLAlchemy

• ORM: Prisma, Sequelize, Mongoose

• API: tRPC, GraphQL, REST

• Auth: NextAuth, Auth0, Clerk

• Logging: Winston, Pino, Bunyan

• Monitoring: Sentry, Datadog, New Relic

Confidence Scoring:

• 1.0: Framework listed in dependencies

• 0.8: Framework detected from imports

• 0.6: Framework inferred from structure

Step 4: File Statistics

Generate quantitative project statistics:

Count files by type:

• Use glob patterns for common extensions

• Exclude: node_modules/ , .git/ , dist/ , build/

• Group by language/file type

Count lines of code:

• Read source files and count lines

• Exclude empty lines and comments (optional)

• Calculate total LOC per language

Identify largest files:

• Track file sizes (line count)

• Report top 10 largest files

• Flag files > 1000 lines (violates micro-service principle)

Calculate averages:

• Average file size (lines)

• Average directory depth

• Files per directory

Language Detection:

• Map extensions to languages:

• .ts , .tsx → TypeScript

• .js , .jsx → JavaScript

• .py → Python

• .go → Go

• .rs → Rust

• .java → Java

• .md → Markdown

• .json → JSON

• .yaml , .yml → YAML

Step 5: Structure Analysis

Analyze project structure and architecture:

Identify root directories:

• Classify directories by purpose:

• source: src/ , app/ , lib/

• tests: test/ , tests/ , cypress/

• config: config/ , .config/

• docs: docs/ , documentation/

• build: dist/ , build/ , out/

• scripts: scripts/ , bin/

• assets: assets/ , static/ , public/

Detect entry points:

• Main entry: index.ts , main.py , app.py

• App entry: app.ts , server.ts , app/page.tsx

• Handler: handler.ts , lambda.ts

• CLI: cli.ts , bin/

Detect architecture pattern:

• MVC: models/ , views/ , controllers/

• Layered: presentation/ , business/ , data/

• Hexagonal: domain/ , application/ , infrastructure/

• Microservices: Multiple service directories

• Modular: Feature-based organization

• Flat: All files in src/

Detect module system:

• Check package.json for "type": "module" (ESM)

• Scan for import /export (ESM) vs require (CommonJS)

• Identify mixed module systems

Step 6: Dependency Analysis

Analyze dependency health:

Count dependencies:

• Production dependencies

• Development dependencies

• Total dependency count

Check for outdated packages (optional):

• Run npm outdated or equivalent

• Parse output for outdated packages

• Identify major version updates (breaking changes)

Security scan (optional):

• Run npm audit or equivalent

• Identify vulnerabilities by severity

• Flag critical security issues

Step 7: Code Quality Indicators

Detect code quality tooling:

Linting Configuration:

• Detect: .eslintrc.json , eslint.config.js , ruff.toml

• Tool: ESLint, Ruff, Flake8, Pylint

• Run linter if configured (optional)

Formatting Configuration:

• Detect: .prettierrc , pyproject.toml (Black/Ruff)

• Tool: Prettier, Black, Ruff

Testing Framework:

• Detect: Jest, Vitest, Pytest, Cypress

• Count test files

• Check for coverage configuration

Type Safety:

• Detect TypeScript: tsconfig.json

• Check strict mode: "strict": true

• Detect Python typing: mypy, pyright

Step 8: Pattern Detection

Identify common patterns and anti-patterns:

Good Practices:

• Modular component structure

• Comprehensive test coverage

• TypeScript strict mode enabled

• CI/CD configuration present

Anti-Patterns:

• Large files (> 1000 lines)

• Missing tests

• Outdated dependencies

• No linting configuration

Neutral Patterns:

• Specific architecture choices

• Framework-specific patterns

Step 9: Technical Debt Analysis

Calculate technical debt score:

Debt Indicators:

• Outdated Dependencies: Count outdated packages

• Missing Tests: Low test file ratio

• Dead Code: Unused imports/exports (optional)

• Complexity: Large files, deep nesting

• Documentation: Missing README, docs

• Security: Known vulnerabilities

• Performance: Bundle size, load time

Debt Score (0-100):

• 0-20: Excellent health

• 21-40: Good health, minor issues

• 41-60: Moderate debt, needs attention

• 61-80: High debt, refactoring recommended

• 81-100: Critical debt, major overhaul needed

Remediation Effort:

• Trivial: < 1 hour

• Minor: 1-4 hours

• Moderate: 1-3 days

• Major: 1-2 weeks

• Massive: > 2 weeks

Step 10: Generate Recommendations

Create prioritized improvement recommendations:

Categorize Recommendations:

• Security: Critical vulnerabilities, outdated auth

• Performance: Bundle optimization, lazy loading

• Maintainability: Refactor large files, add tests

• Testing: Increase coverage, add E2E tests

• Documentation: Add README, API docs

• Architecture: Improve modularity, separation of concerns

• Dependencies: Update packages, remove unused

Prioritize by Impact:

• P0: Critical security, blocking production

• P1: High impact, affects reliability

• P2: Medium impact, improves quality

• P3: Low impact, nice-to-have

Estimate Effort and Impact:

• Effort: trivial, minor, moderate, major, massive

• Impact: low, medium, high, critical

Step 11: Validate Output

Validate analysis output against schema:

Schema Validation:

• Validate against project-analysis.schema.json

• Ensure all required fields present

• Check data types and formats

Output Metadata:

• Analyzer version

• Analysis duration (ms)

• Files analyzed count

• Files skipped count

• Errors encountered

</execution_process>

• Target: < 30 seconds for typical projects (< 10k files)

• Optimization:

• Skip large directories: node_modules/ , .git/ , dist/

• Use parallel file processing

• Cache results for incremental analysis

• Limit deep scans to essential files

• Use streaming for large file counts

Integration with Other Skills:

• rule-selector: Auto-select rules based on detected frameworks

• repo-rag: Semantic search for architectural patterns

• dependency-analyzer: Deep dependency analysis

<best_practices>

• Progressive Disclosure: Start with manifest analysis, add deep scans if needed

• Performance First: Skip expensive operations for large projects

• Fail Gracefully: Handle missing files, parse errors

• Validate Output: Always validate against schema

• Cache Results: Store analysis output for reuse

• Incremental Updates: Re-analyze only changed files </best_practices>

Analyze current project

node .claude/tools/analysis/project-analyzer/analyzer.mjs

Analyze specific directory

node .claude/tools/analysis/project-analyzer/analyzer.mjs /path/to/project

Output to file

node .claude/tools/analysis/project-analyzer/analyzer.mjs --output .claude/context/artifacts/project-analysis.json

Agent Invocation:

Analyze current project

Analyze this project

Generate comprehensive analysis

Perform full project analysis and save to artifacts

Quick analysis (manifest only)

Quick project type detection

</usage_example>

<formatting_example> Sample Output (.claude/context/artifacts/project-analysis.json ):

{ "analysis_id": "analysis-llm-rules-20250115", "project_type": "fullstack", "analyzed_at": "2025-01-15T10:30:00.000Z", "project_root": "C:\dev\projects\LLM-RULES", "stats": { "total_files": 1243, "total_lines": 125430, "languages": { "JavaScript": 45230, "TypeScript": 38120, "Markdown": 25680, "JSON": 12400, "YAML": 4000 }, "file_types": { ".js": 234, ".mjs": 156, ".ts": 89, ".md": 312, ".json": 145 }, "directories": 87, "avg_file_size_lines": 101, "largest_files": [ { "path": ".claude/tools/enforcement-gate.mjs", "lines": 1520 } ] }, "frameworks": [ { "name": "nextjs", "version": "14.0.0", "category": "framework", "confidence": 1.0, "source": "package.json" }, { "name": "react", "version": "18.2.0", "category": "framework", "confidence": 1.0, "source": "package.json" } ], "structure": { "root_directories": [ { "name": ".claude", "purpose": "config", "file_count": 543 }, { "name": "conductor-main", "purpose": "source", "file_count": 234 } ], "entry_points": [ { "path": "conductor-main/src/index.ts", "type": "main" } ], "architecture_pattern": "modular", "module_system": "esm" }, "dependencies": { "production": 45, "development": 23 }, "code_quality": { "linting": { "configured": true, "tool": "eslint" }, "formatting": { "configured": true, "tool": "prettier" }, "testing": { "framework": "vitest", "test_files": 89, "coverage_configured": true }, "type_safety": { "typescript": true, "strict_mode": true } }, "tech_debt": { "score": 35, "indicators": [ { "category": "complexity", "severity": "medium", "description": "3 files exceed 1000 lines", "remediation_effort": "moderate" } ] }, "recommendations": [ { "priority": "P1", "category": "maintainability", "title": "Refactor large files", "description": "Break down files > 1000 lines into smaller modules", "effort": "moderate", "impact": "high" } ], "metadata": { "analyzer_version": "1.0.0", "analysis_duration_ms": 2340, "files_analyzed": 1243, "files_skipped": 3420, "errors": [] } }

</formatting_example>

References

For additional detection patterns extracted from the Auto-Claude analysis framework, see:

• references/auto-claude-patterns.md

• Monorepo indicators, SERVICE_INDICATORS, SERVICE_ROOT_FILES, infrastructure detection, convention detection

• references/service-patterns.md

• Service type detection (frontend, backend, library), framework-specific patterns, entry point detection

• references/database-patterns.md

• Database configuration file patterns, ORM detection (Prisma, SQLAlchemy, TypeORM, Drizzle, Mongoose), connection string patterns

• references/route-patterns.md

• Express, FastAPI, Flask, Django, Next.js, Go, Rust API route detection patterns

These references provide comprehensive regex patterns and detection logic for brownfield codebase analysis.

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md

• Issue found -> .claude/context/memory/issues.md

• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.