importing-a-codebase

1# Importing a codebase
2 
3The workspace holds real code but no specs. **Reverse-engineer the spec graph the project should have
4had.** When the repo already carries real spec-like documents, build the graph around them, not
5parallel to them. Do as much as possible yourself, from the files; ask the user only where the code genuinely can't
6tell you and the answer changes a spec.
7 
8**Hold the writing-specs bar.** Read that concept skill before drafting — everything in this flow is
9inferred rather than confirmed, so its honesty rules (draft until the user reviews, unconfirmed marked
10inline) bind hardest here.
11 
12## 1. Read first, ask last
13 
14Survey before you ask a single question. Read, in roughly this order:
15 
16- **Agent files (mine these first — they state intent + conventions directly):** `AGENTS.md`, `CLAUDE.md`,
17  `.cursor/rules/*`, `.cursorrules`, `.github/copilot-instructions.md`, `GEMINI.md`, `.windsurfrules`.
18- **Docs:** `README`, `docs/`, `CONTRIBUTING`, ADRs.
19- **Manifests & layout:** `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml`, workspace globs,
20  `tree`-style structure, entry points, build/test scripts.
21- **Code:** entry points and the top of each candidate module — enough to see responsibilities and the
22  dependency edges between them.
23 
24While you read, collect **adoption candidates**: durable, declarative documents that state the world
25as it is — architecture/design docs, ADRs / decision records, domain glossaries, protocol/contract
26…