Crawl

Produce a dense, factual CODEBASE.md at the repo root (or a caller-specified path), created or updated in place. It is the pipeline's orient step — attach it to any later skill to give accurate project context without manual re-explanation.

When to use this

• Starting work on an unfamiliar codebase, or CODEBASE.md is missing or stale.
• Skip for a codebase small enough to hold in your head.

Procedure

1. Read .specify/memory/constitution.md.

2. Anchor on config files. Root manifests first — package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, *.csproj, Dockerfile, Makefile/justfile, tsconfig.json, README.md, docs/. Record: primary language(s), runtime, frameworks, key libraries, test framework, build tool.

3. Map the directory structure. Top level and one level down, excluding noise (node_modules, .git, dist, __pycache__). Tag each significant dir: entry, core, api, data, infra, test, docs, util, generated.

4. Find entry points and hubs — files many others import or that wire the system together. Read the top 3–5. Note what starts the app, the main abstractions, how layers call each other.

5. Extract code style from 2–3 representative files: naming per symbol type, error handling, async model, test structure and naming, comment style, import ordering. Record the dominant pattern, not edge cases.

6. Find tradeoffs — ADRs, docs/decisions/, comments tagged WHY:/DECISION:/ TRADEOFF:, README "why" sections. Summarize each: what was chosen, why, what was given up.

7. Find pitfalls — FIXME:/HACK: comments, workaround/kludge language, files

   500 lines, init-order dependencies, required env vars. Capture each: what's fragile, why, what to watch.

8. Write CODEBASE.md. All seven sections, brief and accurate over long and vague:

   # Codebase Context
   <!-- Generated by the crawl skill. Re-run to refresh. Last updated: YYYY-MM-DD -->
   
   ## Business Description
   ## Tech Stack
   ## Code Style
   ## Module Map
   ## Architecture
   ## Tradeoffs
   ## Pitfalls
   

9. If CODEBASE.md already exists, update stale sections in place, preserve human-annotated lines (prefixed > ), append newly found pitfalls/tradeoffs rather than replacing, and bump the date.

Done criteria

• All 7 sections present and non-empty.
• Tech stack lists actual versions, not vague framework names.
• Module map covers every top-level source directory.
• Architecture names the main abstractions, not just "there are layers".
• Pitfalls reflects any FIXMEs/HACKs found (or states none were).