| name | codebase-scanning |
| description | Detect platform, tech stack, features, integrations, and project scale from codebases. Use when scanning a codebase, analyzing project structure, discovering tech stack, or identifying integrations. Trigger on: 'scan my codebase', 'what tech stack am I using', 'analyze my project', 'discover integrations', 'what does this project do'. |
Codebase Scanning
Discover strategic product context from existing codebases. Covers web and mobile platforms.
Auto-loaded by the context-scanner agent for all codebase scanning operations. Also loaded when pm-setup bootstraps project context from code.
Scanning Process
- Detect platform - Identify web, mobile, or hybrid. For mobile, follow the detection order in
references/platform-detection.md
- Parse tech stack - Read manifests to identify frameworks, languages, databases. See
references/manifest-detection.md for supported manifests per platform
- Discover features - Scan routes, pages, and components for user-facing functionality
- Map integrations - Match dependencies against known 3rd party services. See
references/integration-mapping.md for lookup tables
- Estimate scale - Count files, estimate LOC, assign complexity and maturity tiers
- Present results - Use
assets/presentation-template.md format, structured per assets/output-schema.md
Feature Discovery
Scan routes, pages, and components to identify user-facing functionality.
Methods:
- Parse route files (Express routes, Next.js pages/, API routes)
- Analyze page/component names
- Identify API endpoints from route definitions
- Map features to evidence (file paths)
Return format per feature:
- name: Feature name (lowercase, descriptive)
- confidence: high/medium/low
- evidence: File paths, routes, or patterns
Common features detected: Authentication, project/task management, team collaboration, analytics/reporting, settings/configuration.
Tech Stack Detection
Parse package manifests and project files to identify technologies. Supports 7 web platforms (Node.js, Python, Go, Ruby, PHP, Rust, Java) and 4 mobile platforms (iOS, Android, Flutter, React Native).
Full manifest tables and per-platform detection rules: references/manifest-detection.md
Integration Discovery
Match package dependencies against known 3rd party services across 9 categories: Payments, Email, SMS, Auth, Cloud, Analytics, Monitoring, Push, Maps/Location.
Full lookup tables and cross-platform dependency mapping: references/integration-mapping.md
Platform Detection
For mobile projects, detect platform type using ordered priority checks (Flutter > React Native > iOS Native > Android Native > Hybrid). Includes feature discovery rules per platform.
Detection order and feature discovery methods: references/platform-detection.md
Scale Estimation
Metrics to collect:
- Total source files (excluding node_modules, dist, build, .git)
- Lines of code (estimate: average 25 LOC per KB of source file size, excluding binary and generated files)
Complexity tiers:
| Tier | Files | LOC | Characteristics |
|---|
| Simple | <50 | ~10k | Single service |
| Medium | 50-500 | 10k-100k | Few services |
| Complex | >500 | 100k+ | Many services/repos |
Maturity signals:
| Stage | LOC | Indicators |
|---|
| Prototype | ~5k | Rapid changes |
| MVP | 5k-25k | Core features present |
| Established | 25k-100k | Feature-complete |
| Mature | 100k+ | Extensive feature set |
Confidence Assignment
- High: Direct evidence from routes, manifest versions, clear file patterns
- Medium: Package present but usage not verified; ambiguous naming patterns
- Low: Indirect evidence, weak signals, potentially deprecated
Package installed does not mean actively used. Assign medium confidence to integrations by default.
Edge Cases & Limitations
Large Codebases (>100k LOC, >1000 files)
- Limit scanning to primary directories: src/, pages/, routes/, api/, lib/
- Skip: node_modules/, dist/, build/, .git/, vendor/, test/ (unless small)
- Sample large directories (first 100 files, warn about remaining)
- Maximum 60 seconds total scan time
- Graceful degradation: return partial results with limitation note
Monorepos
Detection: Check for lerna.json, nx.json, turbo.json, pnpm-workspace.yaml. Identify workspace structure (packages/, apps/).
Handling: Scan each workspace individually. Detect mobile + web combinations. Report tech stack per app with shared packages noted.
Hybrid Mobile Apps
- React Native with custom native modules: ios/ and android/ with custom .swift or .kt files beyond standard RN setup
- Flutter with platform channels: ios/Runner/ or android/app/ with custom native code
- Capacitor/Ionic: capacitor.config.json present
Conflicting Manifests
- If multiple manifests disagree (e.g., package.json has both react-native and expo), report both with evidence and let the user resolve
- Prefer the more specific indicator (expo in app.json overrides generic react-native in package.json)
- For monorepos with mixed platforms, report per-app rather than trying to unify
Other Edge Cases
- Permission issues: Log warning, continue with accessible files, report in scan_limitations
- Ambiguous patterns: Assign lower confidence, provide evidence, let user decide. Better to under-report than hallucinate
- Deprecated code: Report what exists (facts), flag as medium/low confidence if evidence is weak
- Multi-language projects: Scan all tech stacks present, report separately
- Empty projects: Return empty findings, note "Project appears empty or very early stage". pm-setup falls back to manual questions
