# Spec Graph

Use when locating, reading, creating, updating, or validating project specs, or when...

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

## Install

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

## Description

Use when locating, reading, creating, updating, or validating project specs, or when work is governed by or may alter a documented boundary, contract, invariant, behavior, or architecture decision.

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

# Spec graph

## Specs are the ground truth

- Specs describe the architecture, decisions, contracts, and boundaries behind the code, the intent
  that the code alone does not reveal. Treat them as authoritative.
- **Consult the owning spec when it governs the work.** When work depends on, checks, explains, or
  may alter a documented boundary, contract, invariant, behavior, or architecture decision, use
  `spec_grep` / `spec_get` / `spec_graph` to find the applicable record and align with it. If a change contradicts a recorded
  decision, surface and reconcile the contradiction rather than silently diverging.
- **Keep lookup proportional.** Specs are the map for decisions and boundaries; code confirms the
  implementation. A localized fix, explanation, or check that changes no documented decision may
  inspect only the files it needs without reading unrelated specs.
- **Keep them honest.** A change that moves or blurs a boundary, or overturns a decision, updates the
  spec as part of the same change. Specs that drift from the code stop being ground truth.

## What a spec is

- A durable, declarative document. It states the world as it is, the intent, decisions, contracts, and
  boundaries behind the code, not plans, tasks, phases, or a work journey.
- Concise and readable. It captures what is *not* obvious from the code; it never restates the code.
- The bar: reading the relevant specs should be enough to understand an area and to formulate a task to
  improve it.

### Keep specs lean

The rest: https://github.com/JetBrains/thinkrail/blob/HEAD/packages/spec-graph/skills/spec-graph/SKILL.md