repo-reading

Reading an existing repository

Three levels, run lazily and in order. Each is more expensive than the last, so no level runs until something actually needs it. Most of a spec never needs level 3.

Everything Brownspec writes lives under .brownspec/ in the target repository:

.brownspec/
├── conventions.md          generated, safe to overwrite
├── policies.md             written by people, never overwritten
├── project-map.json        cache
└── features/<slug>/        spec.md · design.md · tasks.md · trace.json

---

Level 1 — Project map

Cost: cheap. Cached: .brownspec/project-map.json.

Establish the shape of the repository, nothing more:

• Language, runtime version, dependency manager, and the manifest file that declares them
• Top-level module or service layout, and what each is for in one line
• Entry points — binaries, HTTP servers, workers, scheduled jobs, CLI
• Where tests live and how they are run
• Where database migrations live, if any
• Build, lint, and CI configuration files

Invalidation. Record the dependency manifest's path and modification time in the cache. If the manifest has changed since, rebuild the map. Otherwise reuse it — do not re-read the repository to answer a question level 1 already answered.

Write it as JSON so later runs can read it without re-deriving anything:

{
  "generated": "<date>",
  "manifest": { "path": "pyproject.toml", "mtime": "<iso8601>" },
  "language": "python 3.12",
  "package_manager": "uv",
  "modules": [{ "path": "app/api", "role": "HTTP handlers" }],
  "entry_points": [{ "kind": "http", "path": "app/main.py" }],
  "tests": { "path": "tests", "runner": "pytest" },
  "migrations": { "path": "migrations", "tool": "alembic" }
}

---

Level 2 — Conventions by sample

Cost: moderate. Cached: .brownspec/conventions.md.

Do not summarize the whole codebase, and do not describe an ideal. Pick two or three modules closest to the work at hand and extract what they actually do: