English | 日本語

artgraph detects drift between your specs, docs, code, and tests — deterministically, no LLM.

Specs go stale. An agent changes the implementation and leaves the spec behind; or the spec gets updated and the code never follows. artgraph links the requirement IDs in your specs to the code that implements them and the tests that verify them, hashes each side, and tells you which side moved. Nothing on that path calls an LLM, so the same repo state always produces the same output.

A spec says one thing:

- REQ-001: The system rejects passwords shorter than 8 characters at signup.

An agent edits the implementation and leaves the spec alone:

  // @impl REQ-001
  export function validatePassword(password: string): void {
-   if (password.length < 8) {
+   if (password.length < 6) {
      throw new Error("password too short");
    }
  }

artgraph check catches the one-sided change, at symbol granularity:

npx artgraph check

DRIFT:
  symbol:src/validate-password.ts#validatePassword (symbol)

The spec still says 8; the code says 6. The reverse case — spec edited, code untouched — is detected the same way. And because artgraph init wires this same artgraph check into your agent's Stop hook, the agent hits exit 2 when it tries to end its turn on a drifted repo, and goes back to fix it. It also detects orphans (@impl pointing at a REQ that doesn't exist) and uncovered requirements (no @impl, no test).

Table of contents

• 30-second tag-zero start
• Why artgraph
• Bootstrapping an existing project
• Quickstart
• How the agent loop works
• SDD tool integration
  • A turn with Spec Kit + artgraph
• End-to-end: spec → @impl → check
• See the graph
• Skills
• How references are expressed
• Commands
• Documentation
• Requirements
• License

30-second tag-zero start

Get impact analysis on an existing repo in three commands — no specs, no @impl tags, no config required:

npx artgraph init --agents=claude   # brownfield-safe; no specs required
# ... edit a file ...
npx artgraph impact --diff          # → files affected via your import graph

Using another package manager? Read npx artgraph as pnpm dlx artgraph (or pnpm exec once installed), bunx artgraph, or deno run -A npm:artgraph/cli throughout — see Quickstart.

impact --diff walks the deterministic import graph, so it works from day one on an untouched repo. Specs, @impl tags, and drift detection are opt-in — add them as you need them.

Why artgraph

It's the second half of Spec Kit and Kiro

Spec Kit and Kiro are good at the first half — turning a spec into code. Neither ships a deterministic answer for the second half: keeping the spec and the code in agreement after generation.

artgraph is built on top of them. It replaces neither — it takes that second half:

npx artgraph integrate speckit   # adds after_tasks / before_implement / after_implement hooks
npx artgraph integrate kiro      # writes .kiro/steering/artgraph.md

artgraph init detects an installed SDD tool and wires this up automatically — see SDD tool integration.

Your code graph doesn't know your spec

Code-graph MCPs — codegraph, GitNexus, Sourcegraph MCP, and dozens more — give AI coding agents a symbol-level map of your codebase. Useful, but the map stops at the code. When an agent rewrites signIn, nothing tells it that REQ-001 in specs/auth.md said "email and password", that docs/auth.md is now stale, or that a test still asserts the old contract.

artgraph adds the layer above the code:

• Requirement IDs are the primary key — the same REQ-001 string is what the spec lists, what the agent puts in @impl, and what the test brackets. That single key is what joins the four layers.
• Every edge is deterministic — @impl tags, [REQ-ID] test names, markdown links, YAML frontmatter, SDD-tool conventions, TypeScript imports, test-execution traces. No LLM in the graph, no embeddings, no RAG.
• Per-change context routing — artgraph impact --diff returns only the specs, docs, and tests a given change touches. Feed that to the agent instead of the whole context file. The scoping is narrow on purpose: sibling requirements declared in the same spec.md, and sibling methods declared in the same class, don't ride along — see docs/skills-guide.md.
• Drift as a CI gate — artgraph check --gate fails the build when a spec changed but the code/tests didn't. Byte-identical output on every run.

Code-graph MCPs answer "where is this used?". artgraph answers "which requirement does this satisfy, and does it still?".

Bootstrapping an existing project

Already have code but no REQs? Ask an agent that speaks artgraph:

you> Please bootstrap traceability for src/auth.

The artgraph-bootstrap Skill proposes specs/auth.md with fresh REQ-NNN entries, adds @impl REQ-NNN tags to the code that implements each one, marks the covering tests with [REQ-NNN], and verifies the result with artgraph scan && artgraph check — all as a single reviewable diff. You review, tweak, and commit.

Quickstart

Platforms: macOS and Linux — including WSL2 on Windows. Native Windows (PowerShell / cmd) is not supported; see the Windows note.

# Pick your package manager (npm / pnpm / Bun / Deno all supported; Yarn falls back to pnpm)
npm install -D artgraph && npx artgraph init --agents=claude       # pick your agent(s)
# pnpm add -D artgraph && pnpm exec artgraph init --agents=claude,codex
# bun add -d artgraph && bunx artgraph init --agents=claude
# deno add npm:artgraph && deno run -A npm:artgraph/cli init --agents=claude

artgraph init runs the full setup: .artgraph.json config + initial scan + cross-agent Skills distribution + auto-integrate detected SDD tools + Stop hook + AGENTS.md snippet. Pass --minimal for bare config only, or any of --no-skills / --no-agent-context / --no-integrate / --no-hooks to skip specific stages. See docs/commands.md#artgraph-init for the full flag list.

Tier 1 cross-agent distribution

--agents=<list> distributes the same canonical SKILL.md set (6 Skills + 3 _shared/ fragments) to each agent's native discovery path. AGENTS.md is the canonical agent-context body; per-agent wrappers only contain a @AGENTS.md import line.

--agents value	Agent	Skills path	Wrapper file
claude	Claude Code	.claude/skills/	CLAUDE.md
codex	Codex CLI (OpenAI)	.agents/skills/	— (AGENTS.md native)
cursor	Cursor	.cursor/skills/	— (AGENTS.md native)
copilot	GitHub Copilot	.github/skills/	.github/copilot-instructions.md
kiro	Kiro	.kiro/skills/	— (.kiro/steering/artgraph.md via artgraph integrate kiro)

The 5 agents above are the entire supported set — artgraph has no roadmap to expand beyond Tier 1 in v0.x. See docs/architecture.md §8 Support Scope.

Windows note

Native Windows (PowerShell / cmd) is not supported. Run artgraph inside WSL2 — all supported package managers and Tier 1 agents work there. Git Bash is untested. See docs/getting-started.md#windows for the CRLF / .gitattributes details when teammates check the repo out on native Windows.

How the agent loop works

Once installed, artgraph plugs into the agent's runtime at three points:

1. In-flight (Skills) — while the agent is editing, artgraph-impact and artgraph-plan-coverage fire on the agent's initiative to surface which REQs a proposed change touches, before the change lands.
2. On turn completion (Stop hook) — when Claude Code hits Stop, the .claude/settings.json hook runs artgraph check --diff and blocks the turn if drift is detected. Similar hook shapes exist for other Tier 1 agents where the runtime supports it.
3. At SDD checkpoints — with Spec Kit or Kiro installed, artgraph integrate wires after_tasks / after_implement / a non-blocking before_implement preview (opt-in blocking gate via --gate) into the SDD workflow, so tasks.md / plan.md changes are checked at the right moment instead of a batch pass later.

Every hook reduces to artgraph check on the same graph, and --diff compares against .trace.lock. No LLM in the loop.

SDD tool integration

artgraph integrate wires the scan / reconcile / check loop into the SDD tool you already use. Built-in targets are Spec Kit (.specify/extensions/artgraph/ with after_tasks / after_implement + a non-blocking before_implement preview; the blocking gate is opt-in via --gate) and Kiro (.kiro/steering/artgraph.md). OpenSpec is not supported yet — its specs are heading-driven with no stable requirement IDs to key the graph on; tracked in #25.

artgraph integrate speckit          # idempotent; hooks into .specify/
artgraph integrate speckit --gate   # upgrade before_implement to a blocking gate
artgraph integrate kiro             # writes .kiro/steering/artgraph.md
artgraph integrate list             # detected / installed per tool

artgraph init auto-integrates every detected SDD tool by default (Spec Kit gets the non-blocking before_implement preview; pass --no-integrate to skip). Note that the opt-in --gate runs an absolute check, so it always fails right before the first implementation of a new spec (every REQ is still uncovered) — expected behavior, see #178 for the gating policy work. Worked examples: examples/speckit-integration/ and examples/kiro-integration/. Full detail in docs/sdd-integration.md.

A turn with Spec Kit + artgraph

Here is what a /speckit-tasks turn looks like once installed, with the artgraph-plan-coverage Skill wired in:

you> /speckit-tasks

<Spec Kit generates tasks.md with T001, T002 pointing at REQ-003, REQ-004>
<Stop → hook runs artgraph check --diff → clean>
<artgraph-plan-coverage fires because tasks.md changed>

agent> tasks.md lists Files: src/auth.ts, but that file also implements
       REQ-001 and REQ-002 — neither is referenced from tasks.md / plan.md /
       spec.md. Do you want me to (a) add tasks for REQ-001/002, (b) exclude
       them from src/auth.ts's scope, or (c) accept and move on?

Which REQs weren't mentioned and why they were reachable comes from artgraph plan-coverage on the changed files. No LLM reasoning about the graph itself — just the CLI's deterministic output.

End-to-end: spec → @impl → check

# 1. Write a requirement
mkdir -p specs && cat > specs/auth.md <<'EOF'
- REQ-001: Users can sign in with email and password.
EOF

# 2. Tag the implementation
cat > src/auth.ts <<'EOF'
// @impl REQ-001
export function signIn(email: string, password: string) { /* … */ }
EOF

# 3. Tag the test
cat > tests/auth.test.ts <<'EOF'
import { describe, it } from "vitest";
describe("auth", () => {
  it("[REQ-001] accepts non-empty credentials", () => { /* … */ });
});
EOF

# 4. Snapshot the baseline, then change the spec to see drift surface
artgraph reconcile
sed -i 's/email and password\./email, password, and TOTP./' specs/auth.md
artgraph check

DRIFT:
  REQ-001 (req)
  doc:auth.md (doc)
COVERAGE:
  REQ-001: verified

A runnable copy of this flow lives in examples/basic/.

See the graph

artgraph scan --serve opens the req / doc / code / test graph as an interactive Cytoscape.js page in your browser. Node border color and style encode drift / orphan / uncovered, so you can spot problem areas at a glance without reading check output line by line.

artgraph scan --serve                            # http://127.0.0.1:3737/
artgraph scan --serve --port 4000 --host 0.0.0.0 # override port / bind address
artgraph scan --output ./graph-out               # static HTML export

With a .trace.lock present, drift / orphan / uncovered nodes are colored; without one, the raw graph structure is rendered. See docs/commands.md for the full reference.

Skills

artgraph ships 6 Skills that wire the CLI into the agent workflow. All are distributed to every agent selected via --agents=<list>.

Skill	Input mode	When it fires
artgraph-setup	n/a	User wants to install / set up artgraph, or wire in an SDD tool added after artgraph
artgraph-bootstrap	n/a	User wants to bootstrap / cold-start / seed initial REQs on an existing untagged (or partially-tagged) project
artgraph-impact	file + symbol	Agent proposes a change; needs to know which REQs / docs / tests it touches (file paths or path:symbol pairs)
artgraph-plan-coverage	file + symbol	tasks.md / plan.md changed; reverse-audit for REQs reached by Files: but not mentioned
artgraph-verify	n/a	Implementation complete; run artgraph check --diff to self-verify before code review
artgraph-rename	n/a	User wants to rename / split / merge requirement IDs

Skills marked file + symbol accept a file, a symbol, or a class method as input; the latter two need "mode": "symbol" in .artgraph.json. See docs/skills-guide.md#file-mode-vs-symbol-mode for the trade-off and the impactReqs / originReqs dual-axis drift guide.

How references are expressed

Artifact	Reference form
Spec list item	- REQ-001: description
Spec heading (Kiro)	### Requirement 1: description
Implementation	// @impl REQ-001
Test	it("[REQ-001] …") or // req: "REQ-001"
Doc relations	frontmatter artgraph.depends_on / derives_from, inferred from kiro / spec-kit file-name conventions, or inline [text](./other.md) links

ID prefixes are free-form ([A-Z][A-Za-z]*-\d+): the REQ- prefix used in the examples above is just a convention — FR-001, AUTH-2, or US-12 work with zero configuration. If you use Spec Kit, keep its default FR-NNN IDs as-is. To exclude an ID family from tracking (e.g. Spec Kit's SC-NNN Success Criteria, which are outcomes rather than implementable requirements), list its prefix in .artgraph.json ignoreIdPrefixes — see docs/configuration.md.

Custom grammars are configurable via reqPatterns in .artgraph.json — see docs/configuration.md.

Commands

Command	Purpose
artgraph init	Full agent-native setup: config + scan + Skills + SDD integrate + Stop hook + agent context
artgraph scan	Build the graph and report counts (--serve / --output render as interactive HTML)
artgraph check	Report drift / orphans / uncovered (--gate to fail a hook)
artgraph impact	File-only forward impact (file paths / --diff; --tests selects tagged tests to re-run)
artgraph trace	Coverage-derived traceability: status (shard health) / report (@impl-vs-evidence audit)
artgraph plan-coverage	Detect implicit REQ impacts from tasks.md Files:
artgraph reconcile	Rebuild .trace.lock from the current graph
artgraph rename	Rename / split / merge requirement IDs
artgraph integrate	Wire artgraph into an installed SDD tool (Spec Kit / Kiro)
artgraph doctor	Diagnose Tier 1 cross-agent distributions

See docs/commands.md for the detailed reference on every flag, including scan --serve, doctor finding taxonomy, and the rename split/merge caveats.

Note that reconcile rebuilds .trace.lock entirely from the current graph: after upgrading to a version that changes symbol-extraction granularity, the next reconcile may rewrite the lock's symbol entries and @impl attributions accordingly. The 0.x series ships no migration tooling for this — review the .trace.lock diff before committing it.

Documentation

• Getting Started — Windows CRLF, committing Skills, Stop hook troubleshooting
• Configuration — reqPatterns, ignoreIdPrefixes, docGraph, taskConventions, edge provenance
• Commands — full CLI reference
• SDD Tool Integration — Spec Kit / Kiro details
• Skills Guide — file vs symbol mode, Skill customization
• Architecture — design decisions and positioning

Repository: https://github.com/mori-shin-x/artgraph. To work on artgraph itself, see CONTRIBUTING.md. For release history, see CHANGELOG.md.

Requirements

• Node.js ≥ 22
• macOS or Linux (WSL2 on Windows)
• One or more Tier 1 agents: Claude Code, Codex CLI, Cursor, GitHub Copilot, or Kiro

License

MIT