- name
- importing-a-codebase
- description
- Use when asked to create the initial spec graph for an existing codebase that has source code but no specs. Normally reached via setting-up-a-project.
Importing a codebase
The workspace holds real code but no specs. Reverse-engineer the spec graph the project should have had. When the repo already carries real spec-like documents, build the graph around them, not parallel to them. Do as much as possible yourself, from the files; ask the user only where the code genuinely can't tell you and the answer changes a spec.
Hold the writing-specs bar. Read that concept skill before drafting — everything in this flow is inferred rather than confirmed, so its honesty rules (draft until the user reviews, unconfirmed marked inline) bind hardest here.
1. Read first, ask last
Survey before you ask a single question. Read, in roughly this order:
- Agent files (mine these first — they state intent + conventions directly):
AGENTS.md,CLAUDE.md,.cursor/rules/*,.cursorrules,.github/copilot-instructions.md,GEMINI.md,.windsurfrules. - Docs:
README,docs/,CONTRIBUTING, ADRs. - Manifests & layout:
package.json/pyproject.toml/go.mod/Cargo.toml, workspace globs,tree-style structure, entry points, build/test scripts. - Code: entry points and the top of each candidate module — enough to see responsibilities and the dependency edges between them.
While you read, collect adoption candidates: durable, declarative documents that state the world as it is — architecture/design docs, ADRs / decision records, domain glossaries, protocol/contract docs. Never candidates (input only): READMEs, CONTRIBUTING, changelogs, roadmaps, TODOs, implementation plans (finished or planned), generated API docs.
Confirm with the spec tools (spec_grep / spec_graph) that there's no graph yet. If specs already
exist, stop and hand back to the setting-up-a-project dispatcher — this flow is for un-specced repos.
2. Build a working model
From what you read, form a working model of what the project is and how it's shaped — held in the conversation, not written to a file (this flow declares no working files):