dotdotgod Traceability

Change a file, know what else must be checked.

Dotdotgod gives AI coding agents a maintained project-memory map, bounded context loading, durable task plans, and changed-file impact review. Agents begin with the smallest useful set of project evidence and expand context through maintained documentation routes.

Use it to carry project knowledge across sessions while keeping plans, verification, and historical context explicit.

Repository: https://github.com/dotdotgod/dotdotgod-kit

Obsidian Traceability Plugin

Explore project traceability in the native global graph with relationship colors, weighted lines, clickable relation filters, document-group colors, and compact hover paths. Desktop Obsidian 1.14.5+ is required (tested on 1.14.5). Copy main.js, manifest.json, and styles.css from the 0.7.3 plugin release into <vault>/.obsidian/plugins/dotdotgod-traceability/, reload, and enable dotdotgod Traceability. Then export in the project/vault:

npx @dotdotgod/[email protected] graph export .

Open Graph view and use Reload traceability. The default graph file is .dotdotgod/traceability.json; settings accept another vault-relative JSON path. The referenced files must exist in the vault. Non-Markdown clicks reveal files in the OS file browser, never execute them. No network, telemetry, payment, or account is used by the plugin; npx installation may contact npm.

Compatibility: the plugin uses undocumented native renderer APIs. Its community listing is public, but automated review completion is not yet confirmed. Native filters may not constrain injected endpoints. Mobile/local graphs are unsupported. Licensed under Elastic License 2.0. See full installation, usage, privacy, and compatibility details.

0.7.0 Upgrade

See 0.7.0 release notes for the standalone graph, graph export, packaged Obsidian plugin, and Pi project-root isolation. graph serve no longer accepts --changed; use graph impact for ranking. For earlier migrations, see 0.6.6 notes. Restart agent sessions after updating adapters.

The Working Loop

Every adapter follows the same loop:

1. init — create the docs-first project-memory scaffold.
2. load — start from a bounded documentation map and focused local query; Pi performs one mode-neutral automatic assessment when baseline context is missing.
3. plan — record durable task intent under docs/plan/ before source edits when the work warrants a saved plan.
4. impact — identify related specs, tests, docs, commands, and source before broad verification or handoff.

Pick the Package You Need

The source checkout includes @dotdotgod/skills, a standalone skills package with role-based planning and document-clarify (no longer bundled with adapters). Its Skills CLI installation guide covers Codex, Claude Code, Pi, Hermes Agent, and OpenCode without a new plugin; native host discovery verification is still pending.

The source checkout also includes @dotdotgod/hermes for Hermes CLI/gateway, with per-session MCP connections and no Plan Mode. Install its npm tarball into the native Hermes plugin directory; see its package README.

Quick Start

Pi

Install the adapter:

pi install npm:@dotdotgod/pi

Open Pi in the target repository and ask:

Initialize this project with dotdotgod.

The initializer creates or normalizes shared agent instructions, documentation indexes, behavior, architecture, and test areas, plus local plan and archive memory. Validate the result with:

npx @dotdotgod/cli validate .

CLI only

npx @dotdotgod/cli init .
npx @dotdotgod/cli validate .
npx @dotdotgod/cli graph impact . --changed <path> --compact
npx @dotdotgod/cli graph serve .

For Claude Code and Codex setup, follow the package-specific Start Here links in the package table.

Why dotdotgod

Dotdotgod keeps a small, high-signal project-memory surface so an agent can answer three questions:

1. What should I load? Start from canonical instructions, README indexes, maintained docs, active plans, and the archive map.
2. What is related to this change? Use graph impact to rank likely specs, tests, docs, commands, and neighboring files.
3. What should I verify? Select documentation checks, traceability, focused tests, dry-runs, or workspace verification from the changed surface.

The structure provides:

• Focused loading: agents begin with a bounded documentation map and expand context through relevant indexes and evidence.
• Durable intent: active plans and archived outcomes survive compaction, handoff, and new sessions.
• Traceable behavior: behavior specs connect to implementation, verification, and design evidence through configured graph relations.
• Routed history: docs/archive/README.md guides agents to historical records relevant to the current task.
• Local processing: graph, query, and execution results stay locally available while agent-facing commands return bounded summaries.

Local Context Runtime

The adapters share a local runtime that keeps large command output, files, and fetched text useful without filling the model context. Small results return directly; larger results become locally searchable, bounded excerpts with provenance and trust metadata. Durable ingestion jobs and opaque session resume let longer processing survive individual turns.

Pi and OpenCode use the shared local MCP runtime without native forwarding aliases. Individual tool names are unprefixed; hosts qualify them with the MCP server namespace. Pi/OpenCode track pending impact without blocking commands. Claude Code/Codex retain their hook policies; Hermes wrappers own a connection per authorized repository/session. Host shell and permission behavior remains separate. The compatibility environment preserves ordinary inherited credentials; allowlist mode provides a stricter child environment.

The runtime applies bounded capture, storage, traversal, and HTTP(S) fetch policies. These controls provide defense in depth rather than a network sandbox or prompt-injection guarantee. See the @dotdotgod/context npm landing page, behavior contract, architecture, and verification strategy.

Changed-File Impact Example

$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact

docs:
- docs/spec/CONFIG_COMMAND.md (56.8; incoming:links_to, incoming:implemented_by)
- docs/spec/cli/TRACEABILITY_LINKS.md (26.3; vector_similarity)

tests:
- packages/cli/test/core.test.mjs (6.5; verified_by)

files:
- packages/cli/src/core.mjs (100; changed-file)
- packages/cli/src/memory/config.mjs (6.5; implemented_by)

Non-seed scores use a fixed weighted Personalized PageRank connection component capped at 80 plus memory policy capped at 20. Direct, curated, test, type, and semantic evidence add no separate score or ordering bonus; relation weights participate through PPR and reasons remain explanation evidence. When the local query cache is available, impact analysis can add a bounded request-local multilingual vector_similarity overlay without changing the indexed graph or persisting changed-file vectors. Vector failures degrade to structural-only results.

Each result includes ranking reasons so agents can inspect the smallest useful set of related evidence. Exact scores vary with the project graph and memory policy. Keep results useful through focused README indexes, current traceability blocks, meaningful package metadata, and single-responsibility documents.

For visual review, start the local explorer:

dotdotgod graph serve . --changed packages/cli/src/core.mjs

The explorer keeps only shared structural nodes connected to the changed-file root, preserves relation-arrow direction, and lays nodes out from the root by structural hop. Its Node reveal control offers Instant, By hop layer, and One by one modes; the choice is saved locally, Skip reveal finishes an active sequence, and reduced-motion preferences use immediate placement. The server binds to 127.0.0.1 by default; use --host or --port only when needed.

Core Concepts

• Project memory: durable files and metadata reused across sessions.
• Memory areas: configured scopes for stable project knowledge, local active plans, and historical archives.
• Project load: a depth-bounded documentation map with focused hybrid document/code-outline search; implementation bodies are read only when needed.
• Traceability: an ordered registry of string-array keys with labels, path or command targets, graph relations, and PPR weights.
• Impact graph: fixed weighted-PPR plus memory-policy ranking, optionally enriched by a request-local multilingual vector overlay.

For the detailed model, read Context curation, Context mechanics, and Measurement design.

Develop This Repository

Use source-checkout commands in this repository:

pnpm install
pnpm run generate
node packages/cli/bin/dotdotgod.mjs index .
node packages/cli/bin/dotdotgod.mjs validate . --include-local-memory --check-index
pnpm run verify

Run package dry-runs before release-style handoff:

pnpm run pack:dry-run

Test the Pi adapter from a checkout:

pi install /path/to/dotdotgod/packages/pi

Documentation

Start with docs/README.md, then use the area indexes:

• Concepts
• Specs
• Tests
• Architecture
• Reports

Common routes:

• Project initializer
• Plan Mode
• Project Load
• Cross-agent support
• Documentation structure

Publishing

The root workspace package is private. Publish public workspace packages individually or with:

pnpm run publish:all