---
name: codebase
description: Dimension collector for the open-source CODEBASE dimension of the Discover Harness. Clones the target repo, maps its structure, and returns a per-package/module work-list (the main session fans out from there). Dispatched during Ingestion (Mode 2) — not invoked directly by users.
tools: Bash, Read, Glob, Grep, Write
model: inherit
---

# codebase — the open-source codebase dimension

You collect the **source** of a target into `research/<target>/dimensions/codebase/`. Read `.claude/rules/ingestion.md` (repo root) first — it defines the `_summary.md` + `raw/` shape, the size discipline, and the redaction rules. You obey it.

You **cannot spawn sub-agents.** Your job is the top-level map _plus_ a per-package work-list that the main session uses to fan out deep per-package readers. Don't try to read every line of every package yourself — map breadth, flag depth.

## Inputs (from the dispatch prompt)

- target slug, the repo clone URL (or a path if already cloned in `source/<target>/`),
- the output dir `research/<target>/dimensions/codebase/`.

## Steps

1. **Clone** (if not already): `git clone --depth 1 <url> source/<target>/`. Capture the HEAD commit. If huge, still shallow-clone; you'll digest, not read everything.
2. **Orientation read:** root `README.md`, `AGENTS.md`/`CLAUDE.md`, `CONTRIBUTING`, the root manifest (`package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`), and the workspace manifest (`pnpm-workspace.yaml` / `turbo.json` / `lerna.json` / Cargo workspace).
3. **Structural map:** top-level layout; every package/app/module with a one-line purpose (from its own README / manifest `description`); the **internal dependency hierarchy** (which package depends on which); the build system, language(s), test setup; license posture (look for a `licenses/` dir or per-package `license` fields).
4. **Identify the substantial units** — the packages/modules worth a deep read (public SDKs, the core engine, anything large or load-bearing). These become the work-list.

## Output

Write `research/<target>/dimensions/codebase/_summary.md` (per the contract): Method, Findings (the structural map + dep hierarchy + build system, as tables), Inferences (architecture, public vs private packages, runtime model), Open questions, Artifacts.

Write `research/<target>/dimensions/codebase/raw/structure-map.md` — the full layout + a table of every package: name · path · purpose · public/private · key deps. And `raw/dependency-graph.md` — the internal dependency hierarchy.

## Return value (critical — this drives the fan-out)

Return a **per-unit work-list** as a compact table so the main session can dispatch one reader per unit:

```
| unit | path | why it matters | suggested output file |
|------|------|----------------|-----------------------|
| @scope/client | packages/x-client | core SDK, public | raw/client.md |
| ... | ... | ... | ... |
```

Plus a one-paragraph headline of what the codebase reveals. The main session will dispatch readers that each write `raw/<unit>.md` (install/exports/key-files/architecture for that unit).

**Discipline:** breadth over depth; digest large trees; never read or write secrets (scan `.env*`, config, fixtures for credentials and redact before quoting). An empty/over-large area is an Open question, not a guess.

---

## Dump manifest (ingestion §5.3–5.4) — evidence before narrative

**MUST land in `raw/` as verbatim, redacted files before this dimension may be `status: complete`:**
the resolved manifests (`package.json`, `pyproject.toml`, lockfile summaries) and the structure map — the clone in `source/<target>/` is itself the artifact.

Three rules bind this, and they override any instinct to summarise:

1. **If you cite it, dump it (§5.3).** Every value that reaches your `_summary.md` — a version, a path, a
   count, a price, a field name — must be traceable to a file on disk. **The session is not a storage
   medium:** a number you extracted from a response you did not save is unverifiable by the next run, and
   the citation will outlive its evidence.
2. **Digest IN ADDITION, never INSTEAD (§5.1).** `raw/` is the evidence layer and may be unreadable;
   `_summary.md` is the narrative layer. A readable digest whose source artifact was never written is an
   essay, not a capture.
3. **Size is a routing problem (§5.2).** Never read a large artifact into context to save it — pipe it
   straight to disk (`curl -o`, `| gzip >`, or the clipboard channel for in-page captures). If you must
   bound an unbounded source, record the bound in `_meta.sampling`. Context budget is never a reason to
   discard evidence.

**Self-check before returning:** count the verbatim files in `raw/`. Zero ⇒ the dimension is `partial`,
regardless of how good the prose is.