---
name: spec-graph
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."
title: spec-graph
canonical_url: https://skilld.dev/gh/jetbrains/thinkrail/spec-graph
last_updated: 2026-11-15T04:03:07.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install jetbrains/thinkrail/spec-graph`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/spec-graph`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jetbrains/thinkrail/spec-graph) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/spec-graph`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/spec-graph --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/spec-graph --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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_search` / `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

- **Explain intent, not inventory.** Describe what a module is for, what it owns, and where its boundaries
  are — not a file-by-file transcript of its directory. The reader can see the files; the spec exists for
  what the files *don't* say.
- **Record the edges that matter.** State the module's boundary (allowed / forbidden deps) and the
  dependency edges between its sub-modules. List a part only when its role or its edges aren't obvious from
  its name — e.g. a small table that carries a real dependency DAG earns its place; a table that just
  pairs `foo.ts` with "the foo tool" is noise, so say it in a sentence instead.
- **Say each thing once.** A fact lives in exactly one spec; others link to it by `id` rather than restate
  it. If a paragraph is being copied between specs, move it to the spec that owns the concept and point at
  it. Duplicated prose drifts and turns into contradictions.
- **Prefer prose to exhaustive tables**, and cut anything that only paraphrases code, filenames, or a
  sibling spec.

## The graph

- `parent` links form a hierarchy that mirrors the code structure: a `SPEC.md` sits beside the module it
  describes (fractal — a package and its sub-directories each have one), and root documents sit at the
  repository root.
- `depends-on`, `references`, and `implements` form a dependency layer across the tree.

## Frontmatter

- Required: `id` (a unique slug), `type`, `title`.
- Optional: `status` (lifecycle), `parent` (single link), `depends-on` / `references` / `implements`
  (link lists), `covers`, `tags`.
- A file is a spec when its frontmatter carries `id` and `type`.
- `status` tracks a spec's lifecycle: `draft` (being written) → `active` (in force), then `stale` (drifting
  from the code), `done`, or `deprecated`. It's optional, but keep it current as a spec firms up or ages.
- Types:
  - `goal-and-requirements` — the product goal and scope; the root of the graph.
  - `architecture-design` — system-wide topology, cross-cutting decisions, and invariants.
  - `module-design` — a package or module's responsibility and boundary.
  - `submodule-design` — the same, for a directory-level module inside a package.
  - `task-spec` — a working document for one piece of work; not durable. Once the work lands it is
    retired with `status: done`, never deleted: spec search skips it, and the user keeps it as an
    artifact.

## Tools

Read:
- `spec_search` — the sections that answer a question, ranked by words: any order, word forms
  (`renaming` ↔ `rename`), identifiers split (`renameSession` ↔ `rename session`). Several phrasings
  fuse into one ranking. It matches words, not meaning — when nothing fits, rephrase with the words a
  spec would use.
- `spec_grep` — search within specs (content, narrowed by metadata filters).
- `spec_get` — a spec's frontmatter, its resolved links, and its path. Read the body with the normal
  `read` tool using that path.
- `spec_graph` — a bounded slice of the graph: a subtree, ancestors, or a node's neighbors, to a depth.

Manage:
- `spec_create` — a new spec with scaffolded frontmatter and headings.
- `spec_update` — a spec's frontmatter (fields and links). It does not touch the body.
- `spec_delete` — remove a spec.
- `spec_validate` — report dangling links, duplicate ids, and parent cycles.

Prose is written and edited with the normal `write`/`edit` tools; the spec tools own frontmatter and
structure.

## Working with specs

1. **Orient when specs govern the work.** From a known root or the module you are touching, use
   `spec_graph` for the neighborhood, `spec_get` for a node's metadata, and `read` for its body. Use
   `spec_search` to find the governing section by words, and `spec_grep` for an exact pattern or
   metadata narrowing.
2. **Align.** Reconcile the change with the decisions and contracts the specs record; surface
   contradictions before diverging.
3. **Update.** When the change alters a boundary, contract, or decision, update the spec — frontmatter
   (including `status`) with `spec_update`, prose with `edit` — and add `spec_create` for a new module.
4. **Check.** Run `spec_validate` after structural changes.
