Project Analyzer

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

<identity> Project Analyzer - Automated brownfield codebase analysis for rapid project onboarding and understanding. </identity>

<capabilities>

• Detecting project type (frontend, backend, fullstack, library, cli, mobile, monorepo)
• Identifying frameworks and libraries from manifests and structure
• Generating file statistics and language breakdown
• Mapping component relationships and module structure
• Detecting architecture patterns (MVC, layered, microservices, etc.)
• Analyzing dependency health and outdated packages
• Identifying code quality indicators (linting, testing, type safety)
• Detecting technical debt and anti-patterns
• Generating prioritized improvement recommendations

</capabilities>

<instructions> <execution_process>

Step 1: Identify Project Root

Locate project root by finding manifest files:

1. 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)

2. Identify project root:

• Directory containing primary package manager file
• Handle monorepos (multiple package.json files)
• Detect workspace configuration

3. 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:

1. Frontend Projects:

• Indicators: React, Vue, Angular, Svelte dependencies
• Directory: src/components/, public/, assets/
• Frameworks: Next.js, Nuxt.js, Gatsby, Vite

2. Backend Projects:

• Indicators: Express, FastAPI, Django, Flask, Gin dependencies
• Directory: routes/, controllers/, models/, api/
• Frameworks: Next.js API routes, FastAPI, Express

3. Fullstack Projects:

• Indicators: Both frontend and backend frameworks
• Directory: Combined frontend + backend structure
• Frameworks: Next.js, Remix, SvelteKit, Nuxt.js

4. Library/Package Projects:

• Indicators: No application-specific directories
• Files: index.ts, lib/, dist/, build/
• Manifests: library field in package.json

5. CLI Projects:

• Indicators: bin field in package.json
• Files: CLI entry points, command parsers
• Dependencies: Commander, Yargs, Inquirer

6. Mobile Projects:

• Indicators: React Native, Flutter, Ionic dependencies
• Files: android/, ios/, mobile/
• Frameworks: React Native, Expo, Flutter

7. Monorepo Projects:

• Indicators: workspaces in package.json, pnpm-workspace.yaml
• Structure: Multiple packages in subdirectories
• Tools: Turborepo, Nx, Lerna

8. 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:

1. Read package.json dependencies (Node.js):

• Parse dependencies and devDependencies
• Detect framework versions
• Categorize by type (framework, ui-library, testing, etc.)

2. Read requirements.txt (Python):

• Parse Python dependencies
• Detect FastAPI, Django, Flask
• Identify version constraints

3. Analyze imports (optional deep scan):

• Scan source files for import statements
• Detect used vs declared dependencies
• Identify framework-specific patterns

4. 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

5. 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:

1. Count files by type:

• Use glob patterns for common extensions
• Exclude: node_modules/, .git/, dist/, build/
• Group by language/file type

2. Count lines of code:

• Read source files and count lines
• Exclude empty lines and comments (optional)
• Calculate total LOC per language

3. Identify largest files:

• Track file sizes (line count)
• Report top 10 largest files
• Flag files > 1000 lines (violates micro-service principle)

4. Calculate averages:

• Average file size (lines)
• Average directory depth
• Files per directory

5. 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:

1. 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/

2. 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/

3. 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/

4. 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:

1. Count dependencies:

• Production dependencies
• Development dependencies
• Total dependency count

2. Check for outdated packages (optional):

• Run npm outdated or equivalent
• Parse output for outdated packages
• Identify major version updates (breaking changes)

3. 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:

1. Linting Configuration:

• Detect: .eslintrc.json, eslint.config.js, ruff.toml
• Tool: ESLint, Ruff, Flake8, Pylint
• Run linter if configured (optional)

2. Formatting Configuration:

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

3. Testing Framework:

• Detect: Jest, Vitest, Pytest, Cypress
• Count test files
• Check for coverage configuration

4. 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:

1. Good Practices:

• Modular component structure
• Comprehensive test coverage
• TypeScript strict mode enabled
• CI/CD configuration present

2. Anti-Patterns:

• Large files (> 1000 lines)
• Missing tests
• Outdated dependencies
• No linting configuration

3. Neutral Patterns:

• Specific architecture choices
• Framework-specific patterns

Step 9: Technical Debt Analysis

Calculate technical debt score:

1. 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

2. 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

3. 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:

1. 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

2. Prioritize by Impact:

• P0: Critical security, blocking production
• P1: High impact, affects reliability
• P2: Medium impact, improves quality
• P3: Low impact, nice-to-have

3. Estimate Effort and Impact:

• Effort: trivial, minor, moderate, major, massive
• Impact: low, medium, high, critical

Step 11: Validate Output

Validate analysis output against schema:

1. Schema Validation:

• Validate against project-analysis.schema.json
• Ensure all required fields present
• Check data types and formats

2. Output Metadata:

• Analyzer version
• Analysis duration (ms)
• Files analyzed count
• Files skipped count
• Errors encountered

</execution_process>

<performance> Performance Requirements:

• 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

</performance>

<integration> Integration with Conductor:

• Provides automated project discovery
• Eliminates manual context gathering
• Enables 80% faster brownfield onboarding
• Feeds project context to chat interface

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

</integration>

<best_practices>

1. Progressive Disclosure: Start with manifest analysis, add deep scans if needed 2. Performance First: Skip expensive operations for large projects 3. Fail Gracefully: Handle missing files, parse errors 4. Validate Output: Always validate against schema 5. Cache Results: Store analysis output for reuse 6. Incremental Updates: Re-analyze only changed files </best_practices> </instructions>

<examples> <usage_example> Programmatic Usage:

# 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> </examples>

Smart Categorization Scoring (Inspired by Skill_Seekers smart_categorize)

When classifying files, directories, or components into categories, use weighted keyword scoring instead of simple string matching to prevent false positives:

Threshold: Require 2+ total points before assigning a category. Falls back to "other" if no category scores above threshold. This prevents weak single-signal matches from misclassifying components.

Category keywords (extend per project type):

• API: route, endpoint, controller, handler, middleware, api, rest, graphql
• Auth: auth, login, session, jwt, oauth, token, credential, permission
• Database: model, schema, migration, seed, repository, entity, query
• Testing: test, spec, fixture, mock, stub, e2e, integration
• Config: config, env, setting, constant, option, feature-flag
• UI: component, view, page, layout, template, style, theme

Three-Stream Analysis (Inspired by Skill_Seekers unified_codebase_analyzer)

For comprehensive project understanding, analyze three parallel streams:

Stream 1 — Code Analysis: AST patterns, framework detection, dependency graph, architecture classification. This is the existing core workflow (Steps 1-11).

Stream 2 — Documentation: README quality, API docs existence, inline doc coverage, changelog maintenance, contribution guides. Score: docFiles / totalFiles weighted by type.

Stream 3 — Community/Operations: Git activity (commit frequency, contributor count), CI/CD configuration, issue templates, PR templates, release workflow, Docker/container setup.

Combine all three streams into the output JSON under analysis.streams:

{
  "streams": {
    "code": { "score": 0.85, "findings": [...] },
    "documentation": { "score": 0.60, "findings": [...] },
    "operations": { "score": 0.75, "findings": [...] }
  },
  "compositeHealth": 0.73
}

Design Pattern Recognition (Inspired by Skill_Seekers C3.1 PatternRecognizer)

Detect common design patterns with confidence scoring:

Output detected patterns in the analysis JSON with location, confidence, and evidence:

{
  "patterns": [
    {
      "type": "Factory",
      "category": "Creational",
      "confidence": 0.85,
      "location": "src/services/UserFactory.ts",
      "evidence": ["createUser method", "returns IUser interface"]
    }
  ]
}

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.

Invoke the project-analyzer skill and follow it exactly as presented to you

Auto-Claude Detection Patterns

Source: Auto-Claude analysis framework (project_analyzer_module.py, base.py)

Overview

This document contains detection patterns extracted from the Auto-Claude autonomous coding framework for identifying monorepo structures, services, infrastructure configurations, and project conventions.

Monorepo Detection

Monorepo Indicator Files

Check for these files at project root to identify monorepo projects:

Detection logic:

1. If any indicator file exists, mark as monorepo 2. Extract tool name from filename (strip .json/.yaml extension) 3. Store as monorepo_tool in analysis

Example:

monorepo_indicators = [
    "pnpm-workspace.yaml",
    "lerna.json",
    "nx.json",
    "turbo.json",
    "rush.json",
]

for indicator in monorepo_indicators:
    if (project_dir / indicator).exists():
        project_type = "monorepo"
        monorepo_tool = indicator.replace(".json", "").replace(".yaml", "")
        break

Structure-Based Detection

If no indicator files found, check directory structure:

Packages/Apps directories:

• Presence of packages/ directory
• Presence of apps/ directory

Multiple service directories: Count directories with service root files. If 2+ directories have root files, classify as monorepo.

Service Detection

SERVICE_INDICATORS - Common Service Names

Directories with these names (case-insensitive) suggest service boundaries:

backend, frontend, api, web, app, server, client,
worker, workers, services, packages, apps, libs,
scraper, crawler, proxy, gateway, admin, dashboard,
mobile, desktop, cli, sdk, core, shared, common

SERVICE_ROOT_FILES - Service Manifest Files

Files that indicate a service/package root:

Service Location Patterns

In monorepos, search these locations for services:

1. Project root (for hybrid monorepos) 2. packages/ directory 3. apps/ directory 4. services/ directory

For each potential service:

• Check for SERVICE_ROOT_FILES
• Verify directory is not in SKIP_DIRS
• Skip hidden directories (starting with .)

Directories to Skip

SKIP_DIRS - Excluded from Analysis

Never traverse into these directories:

node_modules, .git, __pycache__, .venv, venv, .env, env,
dist, build, .next, .nuxt, target, vendor, .idea, .vscode,
.pytest_cache, .mypy_cache, coverage, .coverage, htmlcov,
eggs, *.egg-info, .turbo, .cache, .worktrees, .auto-claude

Infrastructure Detection

Docker Configuration

Extract docker-compose services: Parse services: block in YAML and extract service names at 2-space indent.

CI/CD Detection

Deployment Platform Detection

Convention Detection

Python Linting

Python Formatting

JavaScript/TypeScript Linting

Check for any of these files:

.eslintrc
.eslintrc.js
.eslintrc.json
.eslintrc.yml
eslint.config.js

Prettier Formatting

Check for any of these files:

.prettierrc
.prettierrc.js
.prettierrc.json
prettier.config.js

TypeScript Detection

Git Hooks

Integration Notes

When using these patterns with project-analyzer skill:

1. Order matters: Check monorepo indicators before structure-based detection 2. Fail gracefully: Handle missing files/parse errors 3. Cache results: Store analysis in .claude/context/artifacts/project-analysis.json 4. Respect SKIP_DIRS: Never traverse into excluded directories 5. Combine with framework_analyzer: These patterns identify structure; framework_analyzer identifies tech stack

Memory Protocol (MANDATORY)

After using these patterns:

• Record new patterns discovered in .claude/context/memory/learnings.md
• Document edge cases in .claude/context/memory/issues.md

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

Database Detection Patterns

Source: Auto-Claude analysis framework (database_detector.py)

Overview

This document contains patterns for detecting database models and schemas across different ORMs. Use these patterns to identify data models, tables, fields, and database technology choices in a codebase.

Supported ORMs

SQLAlchemy Detection

File Pattern

All .py files in the project.

Class Pattern

class\s+(\w+)\([^)]*(?:Base|db\.Model|DeclarativeBase)[^)]*\):

Matches classes inheriting from:

• Base (common SQLAlchemy pattern)
• db.Model (Flask-SQLAlchemy)
• DeclarativeBase (SQLAlchemy 2.0+)

Table Name Detection

__tablename__\s*=\s*["\'](\w+)["\']

Default table name if not specified: model_name.lower() + "s"

Column Detection

(\w+)\s*=\s*Column\((.*?)\)

Field Properties:

Type Detection:

(Integer|String|Text|Boolean|DateTime|Float|JSON)

Example

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True)
    email = Column(String(255), unique=True, nullable=False)
    name = Column(String(100))
    created_at = Column(DateTime)

Django ORM Detection

File Patterns

• **/models.py
• **/models/*.py

Class Pattern

class\s+(\w+)\(models\.Model\):

Field Detection

(\w+)\s*=\s*models\.(\w+Field)\((.*?)\)

Field Properties:

Example

class User(models.Model):
    email = models.EmailField(unique=True)
    name = models.CharField(max_length=100)
    is_active = models.BooleanField(default=True)

Prisma Detection

File Pattern

prisma/schema.prisma

Model Pattern

model\s+(\w+)\s*\{([^}]+)\}

Field Pattern

(\w+)\s+(\w+)([^/\n]*)

Field Properties:

Example

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  posts     Post[]
}

TypeORM Detection

File Patterns

• **/*.entity.ts
• **/entities/*.ts

Entity Pattern

@Entity\([^)]*\)\s*(?:export\s+)?class\s+(\w+)

Column Pattern

@(PrimaryGeneratedColumn|Column)\(([^)]*)\)\s+(\w+):\s*(\w+)

Field Properties:

Example

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ unique: true })
  email: string;

  @Column()
  name: string;
}

Drizzle Detection

File Patterns

• **/schema.ts
• **/db/schema.ts

Table Pattern

export\s+const\s+(\w+)\s*=\s*(?:pg|mysql|sqlite)Table\(["\'](\w+)["\']

Example

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: varchar('email', { length: 255 }).unique(),
  name: varchar('name', { length: 100 }),
});

Mongoose Detection

File Patterns

• **/models/*.js
• **/models/*.ts

Model Pattern

mongoose\.model\(["\'](\w+)["\']

Example

const userSchema = new Schema({
  email: { type: String, required: true, unique: true },
  name: String,
  createdAt: { type: Date, default: Date.now },
});

module.exports = mongoose.model('User', userSchema);

Database Configuration Detection

Configuration Files

Connection String Patterns

Environment Variable Patterns

Common database environment variable names:

DATABASE_URL, DB_URL, DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD,
POSTGRES_URL, MYSQL_URL, MONGO_URL, MONGODB_URI, REDIS_URL

Migration Detection

Migration Directories

Output Schema

When detecting models, structure the output as:

{
  "ModelName": {
    "table": "table_name",
    "fields": {
      "field_name": {
        "type": "FieldType",
        "primary_key": false,
        "unique": false,
        "nullable": true
      }
    },
    "file": "relative/path/to/file.py",
    "orm": "SQLAlchemy"
  }
}

Integration Notes

When using these patterns with project-analyzer skill:

1. Check all supported ORMs: Projects may use multiple ORMs (e.g., Prisma for app, Mongoose for sessions) 2. Parse field details: Extract type, constraints for schema documentation 3. Track relationships: Note foreign keys and relations for architecture diagrams 4. Combine with route-patterns.md: Link models to API endpoints they power 5. Exclude test files: Skip test_*.py, *.test.ts, *_test.go

Memory Protocol (MANDATORY)

After using these patterns:

• Record new ORM patterns in .claude/context/memory/learnings.md
• Document detection edge cases in .claude/context/memory/issues.md

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

Research Requirements

• Use Exa first for current best practices.
• Use WebFetch/arXiv fallback when Exa is insufficient.
• Capture constraints and map them to hooks/rules/schemas/workflows.

API Route Detection Patterns

Source: Auto-Claude analysis framework (route_detector.py)

Overview

This document contains patterns for detecting API routes and endpoints across different web frameworks. Use these patterns to map the API surface of a codebase.

Supported Frameworks

Directories to Exclude

Always skip these directories when scanning for routes:

node_modules, .venv, venv, __pycache__, .git

FastAPI Routes

File Pattern

All .py files (excluding excluded directories).

Decorator Patterns

Standard method decorators:

@(?:app|router)\.(get|post|put|delete|patch)\(["\']([^"\']+)["\']

Matches:

• @app.get("/users")
• @router.post("/auth/login")
• @app.delete("/users/{id}")

API route decorator:

@(?:app|router)\.api_route\(["\']([^"\']+)["\'][^)]*methods\s*=\s*\[([^\]]+)\]

Matches:

• @app.api_route("/multi", methods=["GET", "POST"])

Auth Detection

Check route definition line for auth indicators:

• Depends in the line
• require (case-insensitive) in the line

Example

@router.get("/users/{id}", dependencies=[Depends(require_auth)])
async def get_user(id: int):
    pass

@app.post("/auth/login")
async def login(credentials: Credentials):
    pass

Flask Routes

File Pattern

All .py files.

Route Pattern

@(?:app|bp|blueprint)\.route\(["\']([^"\']+)["\'](?:[^)]*methods\s*=\s*\[([^\]]+)\])?

Matches:

• @app.route("/users")
• @bp.route("/auth", methods=["GET", "POST"])
• @blueprint.route("/api/data", methods=["POST"])

Default method: GET (if methods not specified)

Auth Detection

Check decorator section (from previous @ to match end) for:

• login_required
• require (case-insensitive)

Example

@app.route("/users")
def list_users():
    pass

@login_required
@bp.route("/admin", methods=["GET", "POST"])
def admin_panel():
    pass

Django Routes

File Pattern

**/urls.py files.

URL Patterns

path\(["\']([^"\']+)["\']
re_path\([r]?["\']([^"\']+)["\']

Matches:

• path('users/<int:id>/', views.user_detail)
• re_path(r'^api/v\d+/', include(api_urls))

Default methods: GET, POST (Django allows both by default)

Path normalization: Add leading / if not present.

Example

urlpatterns = [
    path('users/', views.user_list),
    path('users/<int:pk>/', views.user_detail),
    path('auth/login/', views.login),
]

Express Routes

File Patterns

• All .js files
• All .ts files

Route Pattern

(?:app|router)\.(get|post|put|delete|patch|use)\(["\']([^"\']+)["\']

Matches:

• app.get('/users', handler)
• router.post('/auth', authMiddleware, login)
• app.delete('/users/:id', deleteUser)

Skip: .use() calls (middleware, not routes)

Auth Detection

Check route line for keywords:

• auth
• authenticate
• protect
• require

Example

app.get('/users', listUsers);
app.post('/users', authMiddleware, createUser);
router.delete('/users/:id', requireAuth, deleteUser);

Next.js Routes

App Router (app/ directory)

File Pattern: app/**/route.{ts,js,tsx,jsx}

Route Path Conversion:

1. Get relative path from app/ to route file's parent 2. Replace \ with / 3. Convert [id] to :id for dynamic segments

Method Detection:

export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)

Pages Router (pages/api/ directory)

File Pattern: pages/api/**/*.{ts,js,tsx,jsx}

Route Path Conversion:

1. Get relative path from pages/api/ 2. Remove file extension 3. Prepend /api/ 4. Convert [id] to :id

Default methods: GET, POST

Examples

App Router:

// app/api/users/[id]/route.ts
// Route: /api/users/:id

export async function GET(request: Request) {
  // Handle GET
}

export async function DELETE(request: Request) {
  // Handle DELETE
}

Pages Router:

// pages/api/users/[id].ts
// Route: /api/users/:id

export default function handler(req, res) {
  if (req.method === 'GET') {
    // Handle GET
  }
}

Go Routes (Gin, Echo, Chi, Fiber)

File Pattern

All .go files.

Route Pattern

(?:r|e|app|router)\.(GET|POST|PUT|DELETE|PATCH|Get|Post|Put|Delete|Patch)\(["\']([^"\']+)["\']

Matches:

• r.GET("/users", listUsers) (Gin)
• e.POST("/auth", loginHandler) (Echo)
• app.Get("/users/:id", getUser) (Fiber)
• r.Get("/users/{id}", getUser) (Chi)

Example

// Gin
r.GET("/users", listUsers)
r.POST("/users", createUser)

// Echo
e.GET("/users/:id", getUser)
e.DELETE("/users/:id", deleteUser)

// Chi
r.Get("/users/{id}", getUser)
r.Put("/users/{id}", updateUser)

Rust Routes (Axum, Actix)

File Pattern

All .rs files.

Route Patterns

Axum:

\.route\(["\']([^"\']+)["\'],\s*(get|post|put|delete|patch)

Matches:

• .route("/users", get(list_users))
• .route("/users/:id", delete(delete_user))

Actix:

web::(get|post|put|delete|patch)\(\)

Note: Actix pattern captures method but not path directly.

Example

// Axum
let app = Router::new()
    .route("/users", get(list_users).post(create_user))
    .route("/users/:id", get(get_user).delete(delete_user));

// Actix
web::resource("/users")
    .route(web::get().to(list_users))
    .route(web::post().to(create_user))

Output Schema

When detecting routes, structure the output as:

{
  "path": "/users/:id",
  "methods": ["GET", "DELETE"],
  "file": "src/routes/users.ts",
  "framework": "Express",
  "requires_auth": true
}

Aggregated API Analysis

After detecting all routes, generate summary:

{
  "routes": [...],
  "total_routes": 25,
  "methods": ["GET", "POST", "PUT", "DELETE", "PATCH"],
  "protected_routes": ["/admin", "/users/:id/settings"]
}

Integration Notes

When using these patterns with project-analyzer skill:

1. Detect framework first: Use service-patterns.md to identify which framework(s) the project uses 2. Handle multiple routers: Projects may have multiple router instances (e.g., /api/v1, /api/v2) 3. Track route prefixes: Blueprint/router mounting adds prefixes 4. Combine with database-patterns.md: Link routes to the models they manipulate 5. Document protected routes: Important for security review

Memory Protocol (MANDATORY)

After using these patterns:

• Record new route patterns in .claude/context/memory/learnings.md
• Document detection edge cases in .claude/context/memory/issues.md

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

Service Detection Patterns

Source: Auto-Claude analysis framework (service_analyzer.py, framework_analyzer.py)

Overview

This document contains patterns for detecting service types, frameworks, and entry points within a codebase. Use these patterns to classify services as frontend, backend, worker, library, etc.

Service Type Detection

Name-Based Classification

Classify services based on directory/service name keywords:

Example:

name_lower = service_name.lower()

if any(kw in name_lower for kw in ["frontend", "client", "web", "ui", "app"]):
    service_type = "frontend"
elif any(kw in name_lower for kw in ["backend", "api", "server", "service"]):
    service_type = "backend"
elif any(kw in name_lower for kw in ["worker", "job", "queue", "task", "celery"]):
    service_type = "worker"
# ... etc

Content-Based Classification

If name does not match, infer from language and file presence:

Python Backend Indicators:

• run.py exists
• main.py exists
• __main__.py exists
• agent.py or agents/ directory exists
• runner.py or runners/ directory exists

Framework Detection

Python Frameworks

Task Queue Detection:

ORM Detection:

Node.js/TypeScript Frameworks

Frontend Frameworks:

Backend Frameworks:

Build Tools:

Styling:

State Management:

ORMs:

Go Frameworks

Rust Frameworks

Ruby Frameworks

Task Queue:

Swift/iOS Detection

UI Frameworks (from imports):

Apple Frameworks:

Combine, CoreData, MapKit, WidgetKit, CoreLocation,
StoreKit, CloudKit, ActivityKit, UserNotifications

Entry Point Detection

Common Entry Point Files

Check these files in order to find the main entry point:

Python:

main.py, app.py, __main__.py, server.py, wsgi.py, asgi.py

JavaScript/TypeScript:

index.ts, index.js, main.ts, main.js, server.ts, server.js,
app.ts, app.js, src/index.ts, src/index.js, src/main.ts,
src/app.ts, src/server.ts, src/App.tsx, src/App.jsx,
pages/_app.tsx, pages/_app.js

Go:

main.go, cmd/main.go

Rust:

src/main.rs, src/lib.rs

Key Directory Detection

Directory Purpose Classification

Package Manager Detection

Node.js Package Managers

Python Package Managers

Integration Notes

When using these patterns with project-analyzer skill:

1. Check frontend frameworks first: Next.js includes React, detect the meta-framework 2. Use confidence scoring:

• 1.0 for direct dependency match
• 0.8 for import-based detection
• 0.6 for structure-based inference

3. Combine with database-patterns.md: ORMs indicate database usage 4. Combine with route-patterns.md: Routes indicate API structure

Memory Protocol (MANDATORY)

After using these patterns:

• Record new framework patterns in .claude/context/memory/learnings.md
• Document detection edge cases in .claude/context/memory/issues.md

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

project-analyzer Rules

Purpose

Automated brownfield codebase analysis. Detects project type, frameworks, dependencies, architecture patterns, and generates comprehensive project profile. Essential for Conductor integration and onboarding existing projects.

Best Practices

• Detect project root from package managers and manifest files
• Identify frameworks from dependencies and directory structure
• Generate comprehensive file statistics and language breakdown
• Map component relationships and architecture patterns
• Validate output against project-analysis.schema.json
• Execute in < 30 seconds for typical projects (< 10k files)

Integration Points

See SKILL.md for complete documentation.

project-analyzer Implementation Template

Goal

• Define target outcome and acceptance criteria.

TDD

1. Red 2. Green 3. Refactor

Verification

• lint
• format
• targeted tests