@dotdotgod/cli

@dotdotgod/cli

Command-line tools for dotdotgod project memory.

Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, load bounded context snapshots, expand project references, or ask what should be checked after a file changes.

Start Here

Run one command without installing globally:

npx @dotdotgod/cli validate .

Install only if you want a persistent dotdotgod command:

npm install -g @dotdotgod/cli

Common first commands:

dotdotgod init .
dotdotgod validate .
dotdotgod load-snapshot .
dotdotgod graph impact . --changed <path> --compact

What It Does

• init creates AGENTS.md, thin agent entrypoints, docs indexes, active-plan space, archive map, and local cache ignores.
• validate checks the dotdotgod docs/project-memory structure, local links, traceability blocks, config validity, and optional index freshness.
• index builds .dotdotgod/manifest.json and compact graph shards from maintained project files.
• load-snapshot returns a bounded first-pass project map for AI agents.
• resolve and expand map explicit or high-signal prompt references to project files.
• graph impact ranks likely related specs, tests, docs, commands, and source files for a changed path.
• traceability links checks or repairs generated Markdown traceability-link sections.
• plan validate validates active plan artifacts and simplified Plan Generator checkpoints before execution.
• plan stage create creates an internal .dotdotgod-plan/NN_STAGE_NAME.md checkpoint for a simplified Plan Generator stage.
• trello sync plans or writes Trello linked-doc metadata from configured docs paths.

Commands

dotdotgod --help
dotdotgod --version
dotdotgod init .
dotdotgod validate .
dotdotgod validate . --check-index
dotdotgod config .
dotdotgod config init .
dotdotgod status .
dotdotgod index .
dotdotgod load-snapshot .
dotdotgod resolve . PLAN_MODE
dotdotgod expand . "Update [[PLAN_MODE]] and [[HOOKS]]"
dotdotgod expand . "PLAN_MODE 수정하자" --fuzzy
dotdotgod traceability links . --check
dotdotgod traceability links . --write
dotdotgod plan validate docs/plan/<task-slug>/README.md
dotdotgod plan validate docs/plan/<task-slug>/README.md --stage 04
dotdotgod plan stage create 02 docs/plan/<task-slug>/README.md
dotdotgod graph impact . --changed <path>
dotdotgod graph impact . --changed <path> --compact
dotdotgod graph impact . --changed <path> --yml
dotdotgod graph communities .

--help, -h, and help print usage to stdout. Command-specific help is available with dotdotgod <command> --help, including nested commands such as dotdotgod graph impact --help, dotdotgod config init --help, dotdotgod plan stage create --help, and dotdotgod traceability links --help.

Which Command Should I Use?

Need	Command
Add the dotdotgod scaffold to a repository	dotdotgod init .
Check docs, links, config, traceability, and optional index freshness	dotdotgod validate . --check-index
Refresh the local graph/cache	dotdotgod index .
Give an agent a bounded project map	dotdotgod load-snapshot .
Resolve [[...]] references from a prompt	dotdotgod expand . "Update [[PLAN_MODE]]"
Repair generated traceability-link sections	dotdotgod traceability links . --write
Validate an active plan before execution	dotdotgod plan validate docs/plan/<task>/README.md
Create an internal Plan Generator stage checkpoint	dotdotgod plan stage create 03 docs/plan/<task>/README.md
See what else to inspect after a change	dotdotgod graph impact . --changed <path> --compact
Preview Trello linked-doc updates	dotdotgod trello sync . --dry-run

Changed-File Impact

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

docs:
- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)

files:
- packages/cli/src/core.mjs (100; changed-file)
- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)

graph impact needs --changed <path> so ranking has a seed file. Use --compact for short text, --yml or --yaml for compact structured agent-facing output, and --json for machine-readable detail.

The graph is built from maintained project files: Markdown links, README routes, headings, traceability blocks, package metadata, memory areas, imports, exports, commands, tests, and deterministic routing hints.

Validation and Verification Boundaries

Command	Responsibility
dotdotgod validate <root>	Checks dotdotgod docs/project-memory structure, local links, traceability blocks, generated traceability-link drift, config validity, and optional index freshness.
dotdotgod traceability links <root> --check	Runs only the generated traceability-link and compact JSON drift check.
dotdotgod traceability links <root> --write	Repairs generated traceability-link sections and rewrites canonical json dotdotgod blocks as compact JSON.
dotdotgod plan validate <plan-readme>	Checks active-plan structure, required Markdown sections, decision/assumption blockers, atomic-task verification, and simplified Plan Generator checkpoints when present.
pnpm run verify	Runs this repository's quality gate: generated-resource checks, package verify contracts, tests, typecheck, and docs validation where each package defines it.

Most users start with validate. Use traceability links --write only when generated traceability output needs repair, and use verify before release-style handoff in this repository.

Memory, Specs, and Config

The default scaffold gives docs explicit roles:

• docs/spec/**: product behavior and requirements. This path is traceability-enforced by default.
• docs/arch/**: architecture rationale, boundaries, conventions, and decisions.
• docs/test/**: verification strategy, regression coverage, fixtures, and commands.
• docs/plan/**: local active-task intent.
• docs/archive/README.md: local archive map included by default.
• docs/archive/**: local archive bodies excluded by default unless targeted.

Use memory.areas to customize memory classification and retrieval priority. Use traceability.required and traceability.exclude to customize which Markdown paths need json dotdotgod traceability blocks. Use validation.markdown, impactRanking, and referenceExpansion to tune size budgets, impact scoring, and fuzzy prompt matching.

Indexing Scope

dotdotgod index is gitignore-aware by default. It uses git ls-files --cached --others --exclude-standard when possible, then filters to supported text, source, script, config, web, and infrastructure files.

Default exclusions include dependency, generated, cache, and secret-like paths such as .git/, .dotdotgod/, node_modules/, dist/, build/, coverage/, .next/, target/, vendor/, .venv/, and .env. Example env templates such as .env.example remain indexable.

Learn More

See the root README, GitHub repository, Context curation, Context mechanics, Memory area config, and Traceability config.