codebase-context-builder

Codebase Context Builder

Scope: Context file generation only — no user story analysis, no task breakdown. Called automatically by user-story-workflow when docs/project_context/ is absent or empty. Can be invoked directly to onboard a new repo.

---

When to Invoke

• user-story-workflow determines context is missing → chains here
• User says: "build project context", "analyse this codebase", "set up project context"
• Fresh repo with no CLAUDE.md or empty one from /init

---

Phase 1 — Stack Detection

Read whatever exists from this list:

package.json / package-lock.json
*.csproj, *.sln
pyproject.toml, requirements.txt, setup.py
pom.xml, build.gradle
Dockerfile, docker-compose.yml
azure-pipelines.yml, .github/workflows/*.yml
CLAUDE.md, AGENTS.md, README.md

Extract:

• Primary language(s) and frameworks
• Build/test/run scripts
• Key dependencies (UI lib, ORM, test framework, state management)
• Deployment target

---

Phase 2 — Structure Scan

# Map source directory 2–3 levels deep (skip noise)
find . -maxdepth 3 -type d \
  | grep -v node_modules | grep -v .git | grep -v bin \
  | grep -v obj | grep -v __pycache__ | grep -v dist

Identify:

• Feature modules / bounded contexts (folders under src/features/, src/modules/, etc.)
• Shared / common code
• API / endpoint layer
• Service / business logic layer
• Data / repository layer
• Test layout (co-located vs separate tests/)

---

Phase 3 — Pattern Sampling

Sample 2–3 files per layer to extract conventions. Use Glob then Read:

# UI/Component layer
src/**/components/*.tsx  OR  src/**/*Controller.cs  OR  app/**/views/*.py

# API endpoint / handler
grep -rl "endpoint\|controller\|router\|Endpoint\|Controller" src/ --include="*.ts" --include="*.cs" --include="*.py" | head -3

# Service / business logic  
grep -rl "Service\|Handler\|UseCase" src/ --include="*.cs" --include="*.py" --include="*.ts" | head -3

# Repository / data access
grep -rl "Repository\|DbContext\|session\|Session" src/ --include="*.cs" --include="*.py" | head -3

# Domain models / DTOs
grep -rl "interface\|type.*=\|public class\|public record\|dataclass\|BaseModel" src/ --include="*.ts" --include="*.cs" --include="*.py" | grep -i "model\|entity\|dto\|types" | head -5