# Importing A Codebase

Use when asked to create the initial spec graph for an existing codebase that has...

- Repository: https://github.com/JetBrains/thinkrail (6952 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add JetBrains/thinkrail --skill importing-a-codebase -g -a claude-code -y`
Codex: `npx skills add JetBrains/thinkrail --skill importing-a-codebase -g -a codex -y`
Cursor: `npx skills add JetBrains/thinkrail --skill importing-a-codebase -g -a cursor -y`
Gemini CLI: `npx skills add JetBrains/thinkrail --skill importing-a-codebase -g -a gemini-cli -y`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/JetBrains/thinkrail/blob/HEAD/packages/pi-thinkrail-workflow/skills/importing-a-codebase/SKILL.md