@dotdotgod/claude-code 0.2.5 → 0.2.7

package/README.md

@@ -38,7 +38,7 @@ claude --plugin-dir /path/to/dotdotgod/packages/claude-code
 | Command or skill | Use it for | Result |
 | --- | --- | --- |
 | `/dd:init` | Start a repository with dotdotgod conventions. | Creates or normalizes shared agent files, docs indexes, local-memory areas, and the complete default project config. |
-| `/dd:load` | Load project memory read-only. | Prefers `dotdotgod load-snapshot <root> --json`, then falls back to README-index reads. |
+| `/dd:load` | Load project memory without changing maintained project files. | Renders the shared Markdown tree and uses `dotdotgod query` when focus text is provided; query may refresh ignored caches. |
 | `/dd:plan` | Plan before implementation. | Writes or updates durable task intent in `docs/plan/<task-slug>/README.md`. |
 | `/dd:plan-goal` | Run 5-stage structured planning before implementation. | Produces durable checkpoint files in `docs/plan/<task>/.dotdotgod-plan/` and a plan README. |
 | `/dd:impact` | Review changed files before verification or handoff. | Uses `dotdotgod graph impact` to identify likely related docs, tests, commands, and source files. |
@@ -86,4 +86,4 @@ See the [root README](https://github.com/dotdotgod/dotdotgod-kit#readme), [Conte
 
 ## Compared with Graphify-Style Memory
 
-This adapter is guidance-oriented. It asks Claude Code to prefer a bounded dotdotgod load snapshot, avoid broad archive scans, and follow README indexes before reading raw files. The strength is structured retrieval from explicit project-maintained links, not a giant graph report.
+This adapter is guidance-oriented. It asks Claude Code to prefer a depth-bounded documentation map with optional focused local query, avoid broad archive scans, and follow README indexes before reading raw files. The strength is structured retrieval from maintained project docs, not a giant graph report.

package/commands/dd/init.md

@@ -1,67 +1,24 @@
 ---
-description: Initialize dotdotgod shared agent docs and documentation scaffold
-argument-hint: [project-root] [--project-name NAME] [--dotdot-setting] [--force] [--dry-run]
-allowed-tools: [Read, Glob, Grep, Bash]
+description: Initialize dotdotgod project memory and config
+argument-hint: [project-root] [--dotdot-setting] [--dry-run]
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
 ---
 
 <!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
 
 # /dd:init - Initialize Project Memory
 
-Initialize or normalize a repository with dotdotgod shared agent docs and docs folders.
+Initialize or normalize a repository with dotdotgod project memory and the complete default config.
 
 Arguments: `$ARGUMENTS`
 
-## Overview
+## Goal
 
-Create a conservative dotdotgod project baseline shared by AI coding agents:
-
-- `AGENTS.md` is the canonical project instruction file.
-- `CLAUDE.md` and `CODEX.md` are thin agent-specific entrypoints.
-- `docs/` contains concise indexes for specs, tests, architecture, active plans, and archives.
-- `dotdotgod.config.json` materializes the complete editable default project policy.
-- `.gitignore` keeps `docs/plan`, `docs/archive`, and `.dotdotgod` local by default.
-
-Under `docs/`, directories use kebab-case and markdown file names use UPPER_SNAKE_CASE, including `README.md`.
-
-## CLI and Fallback
-
-Prefer the CLI initializer:
-
-```bash
-dotdotgod init <project-root>
-```
-
-Use the bundled fallback when the CLI is unavailable:
-
-```bash
-sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>
-```
-
-Both paths create the same baseline file set and canonical config while preserving existing files by default. Use `--dry-run` for unfamiliar repositories, `--dotdot-setting` for the optional documentation and code-convention guidance, and `--force` only with explicit user approval.
+Create a non-destructive dotdotgod baseline with canonical agent instructions, thin agent entrypoints, documentation indexes, project config, and local-memory ignore rules.
 
 ## Workflow
 
-1. Inspect the project root.
-   - Check `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, `docs/`, `dotdotgod.config.json`, and `.dotdotgodrc.json`.
-   - Preserve project-specific instructions and unrelated user work.
-   - Keep `AGENTS.md` canonical when both `AGENT.md` and `AGENTS.md` exist.
-2. Run the initializer.
-   - Use the CLI when available; otherwise use the bundled fallback.
-   - Existing files are skipped unless the user approved `--force`.
-   - If `.dotdotgodrc.json` exists, preserve it and skip creation of `dotdotgod.config.json`, including under `--force`.
-3. Review and validate.
-   - Fill project-specific placeholders in `AGENTS.md` when the required context is known.
-   - Keep `CLAUDE.md` and `CODEX.md` thin.
-   - Preserve the generated complete memory-area set; do not replace it with a partial hand-written list.
-   - Run `dotdotgod validate <project-root>` after creating or changing config when the CLI is available.
-   - Inspect `dotdotgod config <project-root> --json` when validation fails or resolved policy needs review.
-4. Report the result.
-   - List created, skipped, replaced, backed-up, conflicting, and invalid files.
-   - Identify existing instructions that still require manual consolidation.
-
-## Bundled Resources
-
-- `scripts/init_project.sh`: POSIX fallback initializer.
-- `templates/dotdotgod.config.json`: generated canonical config template used by the fallback.
-- `references/agent-docs.md`: shared agent-document naming and content model.
+1. Inspect existing agent instructions, documentation, config, and ignore rules; preserve existing files and unrelated user work.
+2. Run `dotdotgod init <project-root>` when available; otherwise run `sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>`. Existing files must be skipped, not replaced.
+3. Validate the initialized project with `dotdotgod validate <project-root>` when available.
+4. Report created and skipped files, validation failures, and unresolved instruction conflicts.

package/commands/dd/load.md

@@ -8,64 +8,22 @@ allowed-tools: [Read, Glob, Grep, Bash]
 
 # /dd:load - Load Project Memory
 
-Load the current repository's dotdotgod project memory in a read-only pass.
+Load project memory without modifying source, documentation, or project config; focused query may refresh ignored caches.
 
 User focus, if provided: `$ARGUMENTS`
 
 ## Goal
 
-Load the current repository's dotdotgod project memory in a read-only pass. Explicit manual loads should build the fuller curated project map. Prompt-injected refreshes and already-loaded sessions should use the explicit compact load command and build a delta-oriented context map from shared agent instructions, README indexes, specs, architecture notes, test docs, active plans, and relevant archive notes. In Pi, `/dd:load` runs a full load and `/dd:load:compact` runs a compact load; free-form arguments are treated as focus text and never change the load mode.
-
-Do not modify files during the load pass unless the user explicitly asks for edits after the summary.
+Load the repository's dotdotgod project memory without modifying maintained files. Treat free-form arguments as query text, not mode switches.
 
 ## Workflow
 
-1. Identify the repository root and current state.
-   - Check current directory, git root, branch, and dirty worktree status.
-   - Mention user changes and avoid reverting or cleaning them.
-2. Prefer the bounded CLI snapshot when available.
-   - If the user prompt contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<prompt>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
-   - If the prompt has high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, use `dotdotgod expand <root> "<prompt>" --fuzzy --json` before broad scans; avoid fuzzy expansion for low-signal generic words alone and respect configured fuzzy low-signal add/remove terms.
-   - If `dotdotgod` is installed or available in the repository, run `dotdotgod load-snapshot <root> --json`. This bounded CLI snapshot backs `/dd:load` and `/dd:load:compact`.
-   - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
-   - Treat the snapshot as the first-pass project-memory map for cache trust/freshness status, graph size, memory policy, top memory areas, top related communities, and archive inclusion policy. Avoid expanding command/event-heavy details unless the user asks for a full or diagnostic load.
-   - Treat docs structure as metadata: use README.md paths as a book-like table of contents and expand a specific docs subtree only when the user request, a graph community, a memory area, or a README route identifies it. Respect `load.documentationSummary.exclude`; its default omits `docs/plan` and `docs/archive` independently from local-memory classification.
-   - During load/planning, treat `dotdotgod status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and `index` as bounded context/status helpers. `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, and `index` are project-content safe but may refresh ignored `.dotdotgod/` cache metadata. Avoid mutating scaffold/config commands such as `init` or `config init` unless the user explicitly asks for initialization or config creation.
-   - Use `dotdotgod graph impact <root> --changed <path> --yml` as a task-focused structured impact map when the user identifies a likely source/config/doc file. In Claude Code, `/dd:impact` can run the same review; in Codex, `dd:impact` is the command-like trigger for the `impact-review` skill.
-   - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
-   - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
-   - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
-   - Related behavior docs: `docs/spec/LOAD_PROJECT.md`, `docs/spec/CROSS_AGENT_SUPPORT.md`, and `docs/arch/CROSS_AGENT_ARCHITECTURE.md`.
-   - If the CLI is unavailable, network/package execution is undesirable, or the command fails, continue with the manual README-index fallback below.
-3. Inspect baseline memory files when present:
-   - `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`
-   - `docs/README.md`
-   - `docs/spec/README.md`
-   - `docs/test/README.md`
-   - `docs/arch/README.md`
-   - `docs/plan/README.md`
-   - `docs/archive/README.md`
-4. Start with `AGENTS.md`, `README.md`, and `docs/README.md` when they are not already clear from the CLI snapshot or loaded context.
-5. Follow README indexes. Read relevant docs under `docs/spec`, `docs/test`, and `docs/arch` selectively unless the task needs a full refresh.
-6. When plans are relevant through the request or snapshot routing, list `docs/plan` entries first, then selectively read only relevant active plans. Do not infer documentation-summary inclusion from local-memory scope.
-7. Use `docs/archive/README.md` as the archive history map when history is relevant. Do not scan archive bodies by default; read targeted completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly relevant.
-8. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.
-
-## Output Shape
-
-For explicit manual full loads, respond concisely with:
-
-- Project summary
-- Key working rules
-- Available commands and verification methods, including `/dd:impact` or `dd:impact` when available for changed-file review
-- Documentation map
-- Active plans
-- Relevant archive notes
-- Open TODO/TBD items or questions to clarify
+1. Identify the repository root.
+2. When baseline context is missing, read `AGENTS.md`, the adapter entrypoint, `README.md`, and `docs/README.md` when present.
+3. Build a prefix-compressed tree of `docs/**/*.md` after `load.documentationSummary.exclude`. Count `docs/` as depth 1; without arguments, expand through depth 5 and summarize deeper descendants with exact directory and Markdown-file counts.
+4. With arguments, run `dotdotgod query <root> "<arguments>" --limit 30 --json` when available, return at most 30 distinct Markdown files, and render the tree through depth 3. Fall back to the tree and README indexes when query is unavailable.
+5. Read bodies selectively from query results, explicit paths, and README indexes. Read relevant active plans only when needed, use `docs/archive/README.md` as the history map, and avoid broad generated, dependency, cache, or secret reads.
 
-For compact loads, respond with compact routing information:
+## Output
 
-- Project-memory status: available, stale, missing, or newly refreshed memory
-- Relevant docs map: only the docs areas or README indexes likely needed for the current request
-- Active plan hints: active plan paths only when relevant
-- Next recommended reads: a short, bounded list, or a note that no further reads are needed
+Report the project purpose, key rules, relevant documentation routes, and only the active-plan or next-read hints needed for the request. Keep compact loads to a brief refresh.

package/commands/dd/plan.md

@@ -14,74 +14,23 @@ Task request: `$ARGUMENTS`
 
 ## Goal
 
-Create implementation plans from the repository's documented design sources before changing source/config files when the work needs durable coordination. Treat substantial planning as a managed artifact under `docs/plan`.
+Create an implementation plan from maintained repository documentation before substantial source or configuration changes.
 
-Do not start substantial implementation until the plan has a clear evidence trail and the user has asked to execute it. Treat the written plan file as the durable review artifact for large, risky, multi-file, behavior-changing, architecture-changing, CLI/API-affecting, source/config-heavy, or resumable work. For obvious bounded work, a short in-chat checklist is enough unless the user asks for a saved plan.
-
-## Source Order
-
-Prefer live repository docs in this order:
-
-1. `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, and `docs/README.md` for working rules and project map.
-2. `docs/spec/` for behavior, domain rules, API contracts, and acceptance criteria.
-3. `docs/test/` for verification strategy, regression cases, fixtures, and manual checks.
-4. `docs/arch/` for architecture decisions, module boundaries, integration constraints, and runtime assumptions.
-5. `docs/plan/README.md` and matching active plans under `docs/plan/`.
-6. Relevant completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly useful.
+Use `docs/plan/<task-slug>/README.md` for substantial, risky, or resumable work; otherwise use a short in-chat checklist unless the user requests a saved plan.
 
 ## Workflow
 
-1. Establish current state.
-   - Check git status.
-   - Locate relevant docs and active plans.
-   - Preserve user edits and unrelated dirty worktree changes.
-   - If the session is long or noisy, suggest a user-initiated planning-focused compaction before writing or revising the plan; do not compact automatically because compaction is lossy.
-2. Gather evidence before planning.
-   - When the request contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<request>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
-   - When the request uses high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, run `dotdotgod expand <root> "<request>" --fuzzy --json`; skip fuzzy expansion for generic low-signal words alone and respect configured fuzzy low-signal add/remove terms.
-   - Search docs by domain terms from the user request.
-   - Read nearest README indexes and relevant focused docs.
-   - For behavior changes, prefer specs with CLI-enforced fenced `json dotdotgod` traceability blocks in the final section; use their source, test, related-doc, and verification-command mappings before editing code.
-   - When the dotdotgod CLI is available and likely target files are known, run one bounded multi-seed `dotdotgod graph impact <root> --changed <path-a> --changed <path-b> --yml` command for up to 20 unique files, splitting only larger sets into ordered batches. Use the combined ranking and per-seed top-five related specs, tests, docs, commands, scores, and reasons to strengthen target files, risks, and verification steps. If impact lookup fails or the CLI is unavailable, continue with README-index and traceability fallback evidence.
-   - For Claude Code and Codex, add an explicit post-edit impact-review step to the plan when the task will change source/config files, because those adapters do not have Pi's automatic pending-impact reminder or `/impact-check` enforcement.
-   - During planning, treat these dotdotgod commands as bounded context/status helpers: `status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and `index`. Do not run mutating scaffold/config commands such as `init` or `config init` unless the user explicitly asks for initialization or config creation.
-   - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
-   - Read code only after docs identify likely module boundaries, impact output points to relevant files, or docs are missing/stale.
-3. Create or update an active plan at this path when durable planning is needed:
-
-   ```text
-   docs/plan/<task-slug>/README.md
-   ```
-
-   Skip the saved plan for obvious bounded work such as typos, single-file documentation clarifications, targeted test/validation runs, or one-file fixes with an unambiguous implementation path.
-4. For durable active plans that will be executed, keep the user-facing plan in `docs/plan/<task-slug>/README.md`. If `/plan-goal` staged planning is useful, it may record internal checkpoints under `docs/plan/<task-slug>/.dotdotgod-plan/NN_STAGE_NAME.md`; do not make legacy stage directories such as `01-intake/README.md` the required plan product.
-5. Use UPPER_SNAKE_CASE support files in the task directory only when they improve resume quality, such as `ROLE_AREA_WORKSTREAMS.md`, `ATOMIC_TASKS.md`, `PROGRESS_LOG.md`, or `VERIFICATION_EVIDENCE.md`.
-6. For long-running durable tasks, use concise README sections or optional support files for chronological progress, durable decisions, resume state, and task-specific verification checklists. `.dotdotgod-plan/` checkpoints are `/plan-goal` state, not a general Plan Mode requirement.
-7. When a durable plan is created, include:
-   - scope and current status
-   - target files and rationale
-   - impact-derived related files/checks when available
-   - implementation steps
-   - risks and edge cases when useful
-   - verification method
-   - current resume state when useful
-   - final housekeeping step to move completed work to `docs/archive/plan/<task-slug>/`
-   - for Claude Code/Codex plans, a concrete `dd:impact` or `impact-review` step before broad verification or final handoff when source/config/docs files changed
-8. Before executing a durable active plan, ensure the user has explicitly asked to execute it and resolve any plan-local Discussion Queue items that block execution review. Plan Mode does not require `dotdotgod plan validate` before execution; `/plan-goal` and manual/non-Plan-Mode workflows may still use the CLI plan-validation contract when appropriate.
-9. Update `docs/plan/README.md` if the repository keeps active plan entries there.
-10. Use repository-local package manager evidence for verification commands. In this repository, prefer `pnpm run verify`, `pnpm run pack:dry-run`, and `.husky/pre-push` when applicable.
-11. After creating or updating behavior specs, run project validation when possible. For dotdotgod projects, `dotdotgod validate` enforces machine-readable `json dotdotgod` traceability blocks as the final section in specs. Use `dotdotgod validate --check-index` when you need to confirm markdown fingerprints match the graph index. If validation fails, use the schema, property guidance, and example shown in the validation error to repair the spec.
-12. Stop after presenting the plan unless the user explicitly asks for execution.
-13. During implementation in Claude Code or Codex, use `/dd:impact`, `dd:impact`, or the `impact-review` skill after edits and before broad verification, commits, pushes, publishing, or final handoff.
-14. After implementation and verification, archive completed or superseded plan directories under `docs/archive/plan/<task-slug>/`; remove stale local plan artifacts only when the project policy allows plan/archive housekeeping.
+1. Check for a matching active plan.
+2. Reuse loaded memory and the documentation map, then use focused query and README indexes to select maintained docs and verify conclusions in them.
+3. Inspect the source needed to confirm targets and constraints.
+4. Run impact review on likely changed files and refine targets, risks, and verification.
+5. For durable work, write and present the task README with scope, targets, executable steps, verification, and required completion gates.
+6. Resolve blocking decisions and stop until the user asks to execute the plan.
 
 ## Quality Rules
 
 - Prefer documented facts over inference; label inference explicitly.
-- Keep plans concise and maintainable.
-- Use local repository terminology and existing module names.
-- Validation steps must be executable commands or concrete review checks.
-- Avoid turning explanatory numbered lists into executable implementation plans. Use concrete action-oriented `Plan:` steps only when a real active plan artifact is being created or updated.
+- Keep plans concise, executable, and maintainable.
 
 ## Execution Rule
 

package/hooks/README.md

@@ -43,7 +43,7 @@ This SDLC framing maps common Claude Code guidance about a project brain to dotd
 - Use `/dd:load` or the `project-load` skill when you intentionally want a curated project-memory load.
 - Use `/dd:plan` or the `doc-first-planning` skill before implementation, refactors, migrations, or multi-step work.
 - Use `/dd:impact` or the `impact-review` skill after source/config/docs edits and before broad verification, commits, pushes, publishing, or final handoff.
-- During planning, prefer bounded dotdotgod context/status helpers: `status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and intentional `index` refreshes. Do not run mutating scaffold/config commands such as `init` or `config init` from hooks unless the user explicitly requested that setup.
+- During planning, prefer bounded dotdotgod context/status helpers: `status`, `query`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and intentional `index` refreshes. Do not run mutating scaffold/config commands such as `init` or `config init` from hooks unless the user explicitly requested that setup.
 - Use hooks for small reminders at session start, prompt submission, tool boundaries, or stop time.
 
 ## Opt-In Levels
@@ -67,7 +67,7 @@ This example reminds Claude to use dotdotgod intentionally and checks cache stat
         "hooks": [
           {
             "type": "command",
-            "command": "printf '%s\\n' 'dotdotgod: use /dd:load or dotdotgod load-snapshot when project memory is needed.'",
+            "command": "printf '%s\\n' 'dotdotgod: use /dd:load for project memory or dotdotgod query for focused documentation search.'",
             "timeout": 10
           }
         ]
@@ -167,4 +167,4 @@ A strict script must read hook JSON from stdin, confirm the session is explicitl
 - Do not run `dotdotgod init` or `dotdotgod config init` automatically.
 - Do not move active plans to `docs/archive/` automatically.
 - Do not block all source writes without an explicit plan-only state signal.
-- Do not treat `dotdotgod load-snapshot` as side-effect-free in strict hooks; it may lazily refresh the ignored `.dotdotgod/` cache.
+- Treat `dotdotgod query` as a cache-writing command in strict hooks; it may refresh `.dotdotgod/vectors/` and download the local model on first use.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/claude-code",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Claude Code adapter for dotdotgod project memory workflows.",
   "type": "module",
   "license": "Elastic-2.0",

package/skills/doc-first-planning/SKILL.md

@@ -10,71 +10,20 @@ version: 1.0.0
 
 ## Goal
 
-Create implementation plans from the repository's documented design sources before changing source/config files when the work needs durable coordination. Treat substantial planning as a managed artifact under `docs/plan`.
+Create an implementation plan from maintained repository documentation before substantial source or configuration changes.
 
-Do not start substantial implementation until the plan has a clear evidence trail and the user has asked to execute it. Treat the written plan file as the durable review artifact for large, risky, multi-file, behavior-changing, architecture-changing, CLI/API-affecting, source/config-heavy, or resumable work. For obvious bounded work, a short in-chat checklist is enough unless the user asks for a saved plan.
-
-## Source Order
-
-Prefer live repository docs in this order:
-
-1. `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, and `docs/README.md` for working rules and project map.
-2. `docs/spec/` for behavior, domain rules, API contracts, and acceptance criteria.
-3. `docs/test/` for verification strategy, regression cases, fixtures, and manual checks.
-4. `docs/arch/` for architecture decisions, module boundaries, integration constraints, and runtime assumptions.
-5. `docs/plan/README.md` and matching active plans under `docs/plan/`.
-6. Relevant completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly useful.
+Use `docs/plan/<task-slug>/README.md` for substantial, risky, or resumable work; otherwise use a short in-chat checklist unless the user requests a saved plan.
 
 ## Workflow
 
-1. Establish current state.
-   - Check git status.
-   - Locate relevant docs and active plans.
-   - Preserve user edits and unrelated dirty worktree changes.
-   - If the session is long or noisy, suggest a user-initiated planning-focused compaction before writing or revising the plan; do not compact automatically because compaction is lossy.
-2. Gather evidence before planning.
-   - When the request contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<request>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
-   - When the request uses high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, run `dotdotgod expand <root> "<request>" --fuzzy --json`; skip fuzzy expansion for generic low-signal words alone and respect configured fuzzy low-signal add/remove terms.
-   - Search docs by domain terms from the user request.
-   - Read nearest README indexes and relevant focused docs.
-   - For behavior changes, prefer specs with CLI-enforced fenced `json dotdotgod` traceability blocks in the final section; use their source, test, related-doc, and verification-command mappings before editing code.
-   - When the dotdotgod CLI is available and likely target files are known, run one bounded multi-seed `dotdotgod graph impact <root> --changed <path-a> --changed <path-b> --yml` command for up to 20 unique files, splitting only larger sets into ordered batches. Use the combined ranking and per-seed top-five related specs, tests, docs, commands, scores, and reasons to strengthen target files, risks, and verification steps. If impact lookup fails or the CLI is unavailable, continue with README-index and traceability fallback evidence.
-   - For Claude Code and Codex, add an explicit post-edit impact-review step to the plan when the task will change source/config files, because those adapters do not have Pi's automatic pending-impact reminder or `/impact-check` enforcement.
-   - During planning, treat these dotdotgod commands as bounded context/status helpers: `status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and `index`. Do not run mutating scaffold/config commands such as `init` or `config init` unless the user explicitly asks for initialization or config creation.
-   - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
-   - Read code only after docs identify likely module boundaries, impact output points to relevant files, or docs are missing/stale.
-3. Create or update an active plan at this path when durable planning is needed:
-
-   ```text
-   docs/plan/<task-slug>/README.md
-   ```
-
-   Skip the saved plan for obvious bounded work such as typos, single-file documentation clarifications, targeted test/validation runs, or one-file fixes with an unambiguous implementation path.
-4. For durable active plans that will be executed, keep the user-facing plan in `docs/plan/<task-slug>/README.md`. If `/plan-goal` staged planning is useful, it may record internal checkpoints under `docs/plan/<task-slug>/.dotdotgod-plan/NN_STAGE_NAME.md`; do not make legacy stage directories such as `01-intake/README.md` the required plan product.
-5. Use UPPER_SNAKE_CASE support files in the task directory only when they improve resume quality, such as `ROLE_AREA_WORKSTREAMS.md`, `ATOMIC_TASKS.md`, `PROGRESS_LOG.md`, or `VERIFICATION_EVIDENCE.md`.
-6. For long-running durable tasks, use concise README sections or optional support files for chronological progress, durable decisions, resume state, and task-specific verification checklists. `.dotdotgod-plan/` checkpoints are `/plan-goal` state, not a general Plan Mode requirement.
-7. When a durable plan is created, include:
-   - scope and current status
-   - target files and rationale
-   - impact-derived related files/checks when available
-   - implementation steps
-   - risks and edge cases when useful
-   - verification method
-   - current resume state when useful
-   - final housekeeping step to move completed work to `docs/archive/plan/<task-slug>/`
-   - for Claude Code/Codex plans, a concrete `dd:impact` or `impact-review` step before broad verification or final handoff when source/config/docs files changed
-8. Before executing a durable active plan, ensure the user has explicitly asked to execute it and resolve any plan-local Discussion Queue items that block execution review. Plan Mode does not require `dotdotgod plan validate` before execution; `/plan-goal` and manual/non-Plan-Mode workflows may still use the CLI plan-validation contract when appropriate.
-9. Update `docs/plan/README.md` if the repository keeps active plan entries there.
-10. Use repository-local package manager evidence for verification commands. In this repository, prefer `pnpm run verify`, `pnpm run pack:dry-run`, and `.husky/pre-push` when applicable.
-11. After creating or updating behavior specs, run project validation when possible. For dotdotgod projects, `dotdotgod validate` enforces machine-readable `json dotdotgod` traceability blocks as the final section in specs. Use `dotdotgod validate --check-index` when you need to confirm markdown fingerprints match the graph index. If validation fails, use the schema, property guidance, and example shown in the validation error to repair the spec.
-12. Stop after presenting the plan unless the user explicitly asks for execution.
-13. During implementation in Claude Code or Codex, use `/dd:impact`, `dd:impact`, or the `impact-review` skill after edits and before broad verification, commits, pushes, publishing, or final handoff.
-14. After implementation and verification, archive completed or superseded plan directories under `docs/archive/plan/<task-slug>/`; remove stale local plan artifacts only when the project policy allows plan/archive housekeeping.
+1. Check for a matching active plan.
+2. Reuse loaded memory and the documentation map, then use focused query and README indexes to select maintained docs and verify conclusions in them.
+3. Inspect the source needed to confirm targets and constraints.
+4. Run impact review on likely changed files and refine targets, risks, and verification.
+5. For durable work, write and present the task README with scope, targets, executable steps, verification, and required completion gates.
+6. Resolve blocking decisions and stop until the user asks to execute the plan.
 
 ## Quality Rules
 
 - Prefer documented facts over inference; label inference explicitly.
-- Keep plans concise and maintainable.
-- Use local repository terminology and existing module names.
-- Validation steps must be executable commands or concrete review checks.
-- Avoid turning explanatory numbered lists into executable implementation plans. Use concrete action-oriented `Plan:` steps only when a real active plan artifact is being created or updated.
+- Keep plans concise, executable, and maintainable.

package/skills/document-clarify/SKILL.md

@@ -19,8 +19,8 @@ Use this workflow for README indexes, specs, test docs, architecture docs, activ
 Prefer live repository context in this order:
 
 1. The user's target file or requested documentation area.
-2. Resolved dotdotgod memory-area metadata from `dotdotgod load-snapshot <root> --json` when available.
-3. Resolved config from `dotdotgod config <root> --json` when a snapshot is unavailable or stale.
+2. Relevant documentation from `dotdotgod query <root> "<focus>" --json` when semantic routing is useful.
+3. Resolved config from `dotdotgod config <root> --json` when memory-area or documentation-map policy is needed.
 4. The nearest README index, especially `docs/README.md` and the local area `README.md`.
 5. Directly linked specs, tests, architecture notes, commands, and traceability targets needed to preserve meaning.
 6. `docs/archive/README.md` as the history map; read archive bodies only when the current clarification task needs a targeted past decision.

package/skills/project-initializer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-initializer
-description: Use this skill when Claude Code is asked to initialize or normalize a project with dotdotgod shared agent instructions, AGENTS.md/CLAUDE.md/CODEX.md, docs/spec docs/test docs/arch docs/plan docs/archive, or a doc-first project baseline.
+description: Initialize or normalize shared project memory and a complete editable dotdotgod config. Use when asked to set up shared agent entrypoints, docs indexes, local-memory ignores, or dotdotgod.config.json.
 version: 1.0.0
 ---
 
@@ -8,56 +8,13 @@ version: 1.0.0
 
 # Project Initializer
 
-## Overview
+## Goal
 
-Create a conservative dotdotgod project baseline shared by AI coding agents:
-
-- `AGENTS.md` is the canonical project instruction file.
-- `CLAUDE.md` and `CODEX.md` are thin agent-specific entrypoints.
-- `docs/` contains concise indexes for specs, tests, architecture, active plans, and archives.
-- `dotdotgod.config.json` materializes the complete editable default project policy.
-- `.gitignore` keeps `docs/plan`, `docs/archive`, and `.dotdotgod` local by default.
-
-Under `docs/`, directories use kebab-case and markdown file names use UPPER_SNAKE_CASE, including `README.md`.
-
-## CLI and Fallback
-
-Prefer the CLI initializer:
-
-```bash
-dotdotgod init <project-root>
-```
-
-Use the bundled fallback when the CLI is unavailable:
-
-```bash
-sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>
-```
-
-Both paths create the same baseline file set and canonical config while preserving existing files by default. Use `--dry-run` for unfamiliar repositories, `--dotdot-setting` for the optional documentation and code-convention guidance, and `--force` only with explicit user approval.
+Create a non-destructive dotdotgod baseline with canonical agent instructions, thin agent entrypoints, documentation indexes, project config, and local-memory ignore rules.
 
 ## Workflow
 
-1. Inspect the project root.
-   - Check `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, `docs/`, `dotdotgod.config.json`, and `.dotdotgodrc.json`.
-   - Preserve project-specific instructions and unrelated user work.
-   - Keep `AGENTS.md` canonical when both `AGENT.md` and `AGENTS.md` exist.
-2. Run the initializer.
-   - Use the CLI when available; otherwise use the bundled fallback.
-   - Existing files are skipped unless the user approved `--force`.
-   - If `.dotdotgodrc.json` exists, preserve it and skip creation of `dotdotgod.config.json`, including under `--force`.
-3. Review and validate.
-   - Fill project-specific placeholders in `AGENTS.md` when the required context is known.
-   - Keep `CLAUDE.md` and `CODEX.md` thin.
-   - Preserve the generated complete memory-area set; do not replace it with a partial hand-written list.
-   - Run `dotdotgod validate <project-root>` after creating or changing config when the CLI is available.
-   - Inspect `dotdotgod config <project-root> --json` when validation fails or resolved policy needs review.
-4. Report the result.
-   - List created, skipped, replaced, backed-up, conflicting, and invalid files.
-   - Identify existing instructions that still require manual consolidation.
-
-## Bundled Resources
-
-- `scripts/init_project.sh`: POSIX fallback initializer.
-- `templates/dotdotgod.config.json`: generated canonical config template used by the fallback.
-- `references/agent-docs.md`: shared agent-document naming and content model.
+1. Inspect existing agent instructions, documentation, config, and ignore rules; preserve existing files and unrelated user work.
+2. Run `dotdotgod init <project-root>` when available; otherwise run `sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>`. Existing files must be skipped, not replaced.
+3. Validate the initialized project with `dotdotgod validate <project-root>` when available.
+4. Report created and skipped files, validation failures, and unresolved instruction conflicts.

package/skills/project-initializer/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Project Initializer"
   short_description: "Initialize project memory and config."
-  default_prompt: "Initialize this project with dotdotgod init when available, otherwise use the bundled fallback; preserve existing files and create shared agent docs, docs indexes, local memory ignores, and the complete default project config."
+  default_prompt: "Initialize shared project memory and the complete default config with dotdotgod init or the bundled fallback, preserving existing files."

package/skills/project-initializer/scripts/init_project.sh

@@ -6,7 +6,7 @@ CONFIG_TEMPLATE="$SCRIPT_DIR/../templates/dotdotgod.config.json"
 
 usage() {
   cat <<'EOF'
-Usage: init_project.sh <project-root> [--project-name NAME] [--dotdot-setting] [--force] [--dry-run]
+Usage: init_project.sh <project-root> [--project-name NAME] [--dotdot-setting] [--dry-run]
 
 Initializes:
   AGENTS.md, CLAUDE.md, CODEX.md
@@ -23,7 +23,6 @@ EOF
 
 PROJECT_ROOT=""
 PROJECT_NAME=""
-FORCE=0
 DRY_RUN=0
 DOTDOT_SETTING=0
 
@@ -41,10 +40,6 @@ while [ "$#" -gt 0 ]; do
       DOTDOT_SETTING=1
       shift
       ;;
-    --force)
-      FORCE=1
-      shift
-      ;;
     --dry-run)
       DRY_RUN=1
       shift
@@ -85,16 +80,11 @@ if [ -z "$PROJECT_NAME" ]; then
 fi
 
 CONFIG_PATH="$PROJECT_ROOT/dotdotgod.config.json"
-RC_PATH="$PROJECT_ROOT/.dotdotgodrc.json"
-if [ ! -e "$RC_PATH" ] && { [ ! -e "$CONFIG_PATH" ] || [ "$FORCE" -eq 1 ]; } && [ ! -f "$CONFIG_TEMPLATE" ]; then
+if [ ! -e "$CONFIG_PATH" ] && [ ! -f "$CONFIG_TEMPLATE" ]; then
   echo "error: missing initializer config template: $CONFIG_TEMPLATE" >&2
   exit 2
 fi
 
-timestamp() {
-  date -u "+%Y%m%d%H%M%S"
-}
-
 print_result() {
   status=$1
   path=$2
@@ -110,41 +100,19 @@ write_file() {
   path=$1
   content=$2
 
-  if [ -e "$path" ] && [ "$FORCE" -ne 1 ]; then
+  if [ -e "$path" ]; then
     print_result "skipped" "$path"
     return
   fi
 
-  backup=""
-  if [ -e "$path" ] && [ "$FORCE" -eq 1 ]; then
-    backup_base="$path.bak.$(timestamp)"
-    backup="$backup_base"
-    suffix=1
-    while [ -e "$backup" ]; do
-      backup="$backup_base.$suffix"
-      suffix=$((suffix + 1))
-    done
-    if [ "$DRY_RUN" -ne 1 ]; then
-      mv "$path" "$backup"
-    fi
-  fi
-
   if [ "$DRY_RUN" -eq 1 ]; then
-    if [ -n "$backup" ]; then
-      print_result "would_replace" "$path" "backup=$backup"
-    else
-      print_result "would_create" "$path"
-    fi
+    print_result "would_create" "$path"
     return
   fi
 
   mkdir -p "$(dirname "$path")"
   printf '%s\n' "$content" > "$path"
-  if [ -n "$backup" ]; then
-    print_result "replaced" "$path" "backup=$backup"
-  else
-    print_result "created" "$path"
-  fi
+  print_result "created" "$path"
 }
 
 ensure_gitignore_entry() {
@@ -422,9 +390,7 @@ Use this area for local completed plans, temporary reports, historical notes, pa
 
 This directory is local-only and ignored by git by default."
 
-if [ -e "$RC_PATH" ]; then
-  print_result "conflict" "$CONFIG_PATH" "existing=$RC_PATH"
-elif [ -e "$CONFIG_PATH" ] && [ "$FORCE" -ne 1 ]; then
+if [ -e "$CONFIG_PATH" ]; then
   print_result "skipped" "$CONFIG_PATH"
 else
   write_file "$CONFIG_PATH" "$(cat "$CONFIG_TEMPLATE")"

package/skills/project-load/SKILL.md

@@ -10,58 +10,16 @@ version: 1.0.0
 
 ## Goal
 
-Load the current repository's dotdotgod project memory in a read-only pass. Explicit manual loads should build the fuller curated project map. Prompt-injected refreshes and already-loaded sessions should use the explicit compact load command and build a delta-oriented context map from shared agent instructions, README indexes, specs, architecture notes, test docs, active plans, and relevant archive notes. In Pi, `/dd:load` runs a full load and `/dd:load:compact` runs a compact load; free-form arguments are treated as focus text and never change the load mode.
-
-Do not modify files during the load pass unless the user explicitly asks for edits after the summary.
+Load the repository's dotdotgod project memory without modifying maintained files. Treat free-form arguments as query text, not mode switches.
 
 ## Workflow
 
-1. Identify the repository root and current state.
-   - Check current directory, git root, branch, and dirty worktree status.
-   - Mention user changes and avoid reverting or cleaning them.
-2. Prefer the bounded CLI snapshot when available.
-   - If the user prompt contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<prompt>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
-   - If the prompt has high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, use `dotdotgod expand <root> "<prompt>" --fuzzy --json` before broad scans; avoid fuzzy expansion for low-signal generic words alone and respect configured fuzzy low-signal add/remove terms.
-   - If `dotdotgod` is installed or available in the repository, run `dotdotgod load-snapshot <root> --json`. This bounded CLI snapshot backs `/dd:load` and `/dd:load:compact`.
-   - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
-   - Treat the snapshot as the first-pass project-memory map for cache trust/freshness status, graph size, memory policy, top memory areas, top related communities, and archive inclusion policy. Avoid expanding command/event-heavy details unless the user asks for a full or diagnostic load.
-   - Treat docs structure as metadata: use README.md paths as a book-like table of contents and expand a specific docs subtree only when the user request, a graph community, a memory area, or a README route identifies it. Respect `load.documentationSummary.exclude`; its default omits `docs/plan` and `docs/archive` independently from local-memory classification.
-   - During load/planning, treat `dotdotgod status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and `index` as bounded context/status helpers. `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, and `index` are project-content safe but may refresh ignored `.dotdotgod/` cache metadata. Avoid mutating scaffold/config commands such as `init` or `config init` unless the user explicitly asks for initialization or config creation.
-   - Use `dotdotgod graph impact <root> --changed <path> --yml` as a task-focused structured impact map when the user identifies a likely source/config/doc file. In Claude Code, `/dd:impact` can run the same review; in Codex, `dd:impact` is the command-like trigger for the `impact-review` skill.
-   - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
-   - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
-   - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
-   - Related behavior docs: `docs/spec/LOAD_PROJECT.md`, `docs/spec/CROSS_AGENT_SUPPORT.md`, and `docs/arch/CROSS_AGENT_ARCHITECTURE.md`.
-   - If the CLI is unavailable, network/package execution is undesirable, or the command fails, continue with the manual README-index fallback below.
-3. Inspect baseline memory files when present:
-   - `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`
-   - `docs/README.md`
-   - `docs/spec/README.md`
-   - `docs/test/README.md`
-   - `docs/arch/README.md`
-   - `docs/plan/README.md`
-   - `docs/archive/README.md`
-4. Start with `AGENTS.md`, `README.md`, and `docs/README.md` when they are not already clear from the CLI snapshot or loaded context.
-5. Follow README indexes. Read relevant docs under `docs/spec`, `docs/test`, and `docs/arch` selectively unless the task needs a full refresh.
-6. When plans are relevant through the request or snapshot routing, list `docs/plan` entries first, then selectively read only relevant active plans. Do not infer documentation-summary inclusion from local-memory scope.
-7. Use `docs/archive/README.md` as the archive history map when history is relevant. Do not scan archive bodies by default; read targeted completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly relevant.
-8. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.
-
-## Output Shape
-
-For explicit manual full loads, respond concisely with:
-
-- Project summary
-- Key working rules
-- Available commands and verification methods, including `/dd:impact` or `dd:impact` when available for changed-file review
-- Documentation map
-- Active plans
-- Relevant archive notes
-- Open TODO/TBD items or questions to clarify
+1. Identify the repository root.
+2. When baseline context is missing, read `AGENTS.md`, the adapter entrypoint, `README.md`, and `docs/README.md` when present.
+3. Build a prefix-compressed tree of `docs/**/*.md` after `load.documentationSummary.exclude`. Count `docs/` as depth 1; without arguments, expand through depth 5 and summarize deeper descendants with exact directory and Markdown-file counts.
+4. With arguments, run `dotdotgod query <root> "<arguments>" --limit 30 --json` when available, return at most 30 distinct Markdown files, and render the tree through depth 3. Fall back to the tree and README indexes when query is unavailable.
+5. Read bodies selectively from query results, explicit paths, and README indexes. Read relevant active plans only when needed, use `docs/archive/README.md` as the history map, and avoid broad generated, dependency, cache, or secret reads.
 
-For compact loads, respond with compact routing information:
+## Output
 
-- Project-memory status: available, stale, missing, or newly refreshed memory
-- Relevant docs map: only the docs areas or README indexes likely needed for the current request
-- Active plan hints: active plan paths only when relevant
-- Next recommended reads: a short, bounded list, or a note that no further reads are needed
+Report the project purpose, key rules, relevant documentation routes, and only the active-plan or next-read hints needed for the request. Keep compact loads to a brief refresh.

package/skills/project-load/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Project Load"
   short_description: "Load dotdotgod project memory."
-  default_prompt: "Load this project's dotdotgod memory and summarize rules, docs, commands, active plans, and open questions."
+  default_prompt: "Load this project's dotdotgod memory and summarize rules, docs, commands, relevant active plans, and questions surfaced by the loaded material."