@dotdotgod/claude-code 0.2.4 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.md +3 -3
  2. package/commands/dd/init.md +35 -41
  3. package/commands/dd/load.md +32 -44
  4. package/commands/dd/plan.md +1 -1
  5. package/hooks/README.md +3 -3
  6. package/package.json +2 -2
  7. package/skills/doc-first-planning/SKILL.md +1 -1
  8. package/skills/document-clarify/SKILL.md +2 -2
  9. package/skills/project-initializer/SKILL.md +32 -38
  10. package/skills/project-initializer/agents/openai.yaml +2 -2
  11. package/skills/project-initializer/scripts/init_project.sh +19 -28
  12. package/skills/project-initializer/templates/dotdotgod.config.json +269 -0
  13. package/skills/project-load/SKILL.md +31 -43
  14. package/skills/project-load/agents/openai.yaml +1 -1
package/README.md CHANGED
@@ -37,8 +37,8 @@ claude --plugin-dir /path/to/dotdotgod/packages/claude-code
37
37
 
38
38
  | Command or skill | Use it for | Result |
39
39
  | --- | --- | --- |
40
- | `/dd:init` | Start a repository with dotdotgod conventions. | Creates or normalizes `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, and archive map. |
41
- | `/dd:load` | Load project memory read-only. | Prefers `dotdotgod load-snapshot <root> --json`, then falls back to README-index reads. |
40
+ | `/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. |
41
+ | `/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. |
42
42
  | `/dd:plan` | Plan before implementation. | Writes or updates durable task intent in `docs/plan/<task-slug>/README.md`. |
43
43
  | `/dd:plan-goal` | Run 5-stage structured planning before implementation. | Produces durable checkpoint files in `docs/plan/<task>/.dotdotgod-plan/` and a plan README. |
44
44
  | `/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
86
86
 
87
87
  ## Compared with Graphify-Style Memory
88
88
 
89
- 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.
89
+ 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 CHANGED
@@ -1,73 +1,67 @@
1
1
  ---
2
- description: Initialize dotdotgod shared agent docs and documentation scaffold
3
- argument-hint: [project-root] [--project-name NAME] [--dotdot-setting] [--force] [--dry-run]
4
- allowed-tools: [Read, Glob, Grep, Bash]
2
+ description: Initialize dotdotgod project memory and config
3
+ argument-hint: [project-root] [--dotdot-setting] [--dry-run]
4
+ allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
5
5
  ---
6
6
 
7
7
  <!-- 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`. -->
8
8
 
9
9
  # /dd:init - Initialize Project Memory
10
10
 
11
- Initialize or normalize a repository with dotdotgod shared agent docs and docs folders.
11
+ Initialize or normalize a repository with dotdotgod project memory and the complete default config.
12
12
 
13
13
  Arguments: `$ARGUMENTS`
14
14
 
15
15
  ## Overview
16
16
 
17
- Create a conservative dotdotgod project baseline that multiple AI coding agents can share:
17
+ Create a conservative dotdotgod project baseline shared by AI coding agents:
18
18
 
19
19
  - `AGENTS.md` is the canonical project instruction file.
20
- - `CLAUDE.md` imports `AGENTS.md` for Claude Code.
21
- - `CODEX.md` points Codex users to `AGENTS.md`.
22
- - `docs/` contains `spec`, `test`, `arch`, `plan`, and `archive` areas with concise README files.
23
- - `docs/arch/` covers architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
24
- - Behavior specs can include fenced `json dotdotgod` traceability blocks as the final section; `dotdotgod validate` owns and enforces that machine-readable schema for CLI users.
25
- - Code conventions can start as `docs/arch/CODE_CONVENTIONS.md`; when they grow across multiple topics, promote them to `docs/arch/conventions/README.md` plus supporting UPPER_SNAKE_CASE files.
26
- - Under `docs/`, all directories use kebab-case and all markdown file names use UPPER_SNAKE_CASE, including `README.md`.
27
- - `docs/plan/<task-slug>/README.md` is the default shape for active plan work.
28
- - Completed plans move to `docs/archive/plan/<task-slug>/`.
29
- - Temporary reports and investigations move to `docs/archive/report/<report-slug>/`.
30
- - `.gitignore` includes `docs/plan`, `docs/archive`, and `.dotdotgod` so local memory and the graph cache stay local by default.
31
-
32
- Use the dotdotgod CLI initializer when it is already available in the target environment:
20
+ - `CLAUDE.md` and `CODEX.md` are thin agent-specific entrypoints.
21
+ - `docs/` contains concise indexes for specs, tests, architecture, active plans, and archives.
22
+ - `dotdotgod.config.json` materializes the complete editable default project policy.
23
+ - `.gitignore` keeps `docs/plan`, `docs/archive`, and `.dotdotgod` local by default.
24
+
25
+ Under `docs/`, directories use kebab-case and markdown file names use UPPER_SNAKE_CASE, including `README.md`.
26
+
27
+ ## CLI and Fallback
28
+
29
+ Prefer the CLI initializer:
33
30
 
34
31
  ```bash
35
32
  dotdotgod init <project-root>
36
33
  ```
37
34
 
38
- Do not require users to install the CLI just to initialize. If `dotdotgod` is unavailable or the command is not executable, use the bundled dependency-free shell fallback:
35
+ Use the bundled fallback when the CLI is unavailable:
39
36
 
40
37
  ```bash
41
38
  sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>
42
39
  ```
43
40
 
44
- The fallback still creates the baseline docs indexes and local-memory `.gitignore` entries, so project loading can work from README indexes until the CLI is added later.
45
-
46
- Use `--dry-run` before touching an unfamiliar repository. Use `--dotdot-setting` when the user wants general dotdot documentation structure and code conventions generated under `docs/arch/DOCS_STRUCTURE.md` and `docs/arch/CODE_CONVENTIONS.md`, then referenced from `AGENTS.md`. Use `--force` only when explicitly requested; it creates timestamped backups before replacing files.
41
+ Both paths create the same baseline file set and canonical config while preserving existing files. Use `--dry-run` for unfamiliar repositories and `--dotdot-setting` for the optional documentation and code-convention guidance.
47
42
 
48
43
  ## Workflow
49
44
 
50
- 1. Inspect the target project root.
51
- - Check for existing `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, and `docs/`.
52
- - Preserve project-specific instructions unless the user asks to replace them.
53
- - If both `AGENT.md` and `AGENTS.md` exist, prefer `AGENTS.md` as canonical and leave `AGENT.md` untouched unless asked.
45
+ 1. Inspect the project root.
46
+ - Check `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, `docs/`, and `dotdotgod.config.json`.
47
+ - Preserve project-specific instructions and unrelated user work.
48
+ - Keep `AGENTS.md` canonical when both `AGENT.md` and `AGENTS.md` exist.
54
49
  2. Run the initializer.
55
- - Try `dotdotgod init` only when the CLI is available; otherwise run the bundled fallback script without blocking initialization.
56
- - Default behavior creates missing files only.
57
- - Existing files are skipped.
58
- - `.gitignore` is created or appended with missing `docs/plan`, `docs/archive`, and `.dotdotgod` entries.
59
- - `--dotdot-setting` additionally creates `docs/arch/DOCS_STRUCTURE.md` and `docs/arch/CODE_CONVENTIONS.md`, adds them to the architecture README index, and adds an `AGENTS.md` reference.
60
- - `--force` backs up replaced files as `<name>.bak.<timestamp>`.
61
- 3. Review generated files.
62
- - Fill project-specific sections in `AGENTS.md` when context is available.
63
- - Keep `CLAUDE.md` and `CODEX.md` thin so instructions do not drift.
64
- - Treat `docs/plan` and `docs/archive` as local working memory unless the project deliberately changes that policy.
65
- - When adding behavior specs, run `dotdotgod validate` when the CLI is available and follow any traceability schema/example shown in validation errors; if the CLI is unavailable, keep README indexes accurate and validate later.
50
+ - Use the CLI when available; otherwise use the bundled fallback.
51
+ - Existing files are always preserved and skipped.
52
+ 3. Review and validate.
53
+ - Fill project-specific placeholders in `AGENTS.md` when the required context is known.
54
+ - Keep `CLAUDE.md` and `CODEX.md` thin.
55
+ - Preserve the generated complete memory-area set; do not replace it with a partial hand-written list.
56
+ - Run `dotdotgod validate <project-root>` after creating or changing config when the CLI is available.
57
+ - Inspect `dotdotgod config <project-root> --json` when validation fails or resolved policy needs review.
66
58
  4. Report the result.
67
- - List created/skipped/backed-up files.
68
- - Mention any existing instructions that still need manual consolidation.
59
+ - List created, updated, and skipped files, plus validation failures.
60
+ - Report when CLI validation was unavailable.
61
+ - Identify existing instructions that still require manual consolidation.
69
62
 
70
63
  ## Bundled Resources
71
64
 
72
- - `scripts/init_project.sh`: fallback scaffold generator that mirrors `dotdotgod init` with POSIX shell only.
73
- - `references/agent-docs.md`: naming rationale and expected content model for shared agent docs.
65
+ - `scripts/init_project.sh`: POSIX fallback initializer.
66
+ - `templates/dotdotgod.config.json`: generated canonical config template used by the fallback.
67
+ - `references/agent-docs.md`: shared agent-document naming and content model.
package/commands/dd/load.md CHANGED
@@ -8,64 +8,52 @@ allowed-tools: [Read, Glob, Grep, Bash]
8
8
 
9
9
  # /dd:load - Load Project Memory
10
10
 
11
- Load the current repository's dotdotgod project memory in a read-only pass.
11
+ Load project memory without modifying source, documentation, or project config; focused query may refresh ignored caches.
12
12
 
13
13
  User focus, if provided: `$ARGUMENTS`
14
14
 
15
15
  ## Goal
16
16
 
17
- 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.
18
-
19
- Do not modify files during the load pass unless the user explicitly asks for edits after the summary.
17
+ Load the current repository's dotdotgod project memory without modifying source, documentation, or project config. A focused query may refresh ignored `.dotdotgod/vectors/` data and the runtime's user-level model cache. Use a full load for an explicit project overview and a compact load to refresh an already-loaded session. Treat free-form arguments as query text, not as mode switches.
20
18
 
21
19
  ## Workflow
22
20
 
23
21
  1. Identify the repository root and current state.
24
- - Check current directory, git root, branch, and dirty worktree status.
22
+ - Check the current directory and, when Git is available, the repository root, branch, and dirty worktree status.
25
23
  - Mention user changes and avoid reverting or cleaning them.
26
- 2. Prefer the bounded CLI snapshot when available.
27
- - 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.
28
- - 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.
29
- - 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`.
30
- - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
31
- - 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.
32
- - 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.
33
- - 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.
34
- - 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.
35
- - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
36
- - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
37
- - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
38
- - Related behavior docs: `docs/spec/LOAD_PROJECT.md`, `docs/spec/CROSS_AGENT_SUPPORT.md`, and `docs/arch/CROSS_AGENT_ARCHITECTURE.md`.
39
- - If the CLI is unavailable, network/package execution is undesirable, or the command fails, continue with the manual README-index fallback below.
40
- 3. Inspect baseline memory files when present:
41
- - `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`
42
- - `docs/README.md`
43
- - `docs/spec/README.md`
44
- - `docs/test/README.md`
45
- - `docs/arch/README.md`
46
- - `docs/plan/README.md`
47
- - `docs/archive/README.md`
48
- 4. Start with `AGENTS.md`, `README.md`, and `docs/README.md` when they are not already clear from the CLI snapshot or loaded context.
49
- 5. Follow README indexes. Read relevant docs under `docs/spec`, `docs/test`, and `docs/arch` selectively unless the task needs a full refresh.
50
- 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.
51
- 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.
52
- 8. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.
24
+ 2. Read baseline memory only when it is not already clear from loaded context.
25
+ - Start with `AGENTS.md`, the current adapter entrypoint when present, `README.md`, and `docs/README.md`.
26
+ - Do not run scaffold, config-writing, or source-modifying commands during a load.
27
+ 3. Build the shared documentation map.
28
+ - Discover Markdown files under `docs/` after applying `load.documentationSummary.exclude`, which excludes `docs/plan` and `docs/archive` by default.
29
+ - Render repository-relative paths as a prefix-compressed tree. Count `docs/` as directory depth 1.
30
+ - Without arguments, expand through directory depth 5. At the boundary, summarize deeper descendants with exact directory and Markdown-file counts.
31
+ 4. Use query routing only when arguments are present.
32
+ - Run `dotdotgod query <root> "<arguments>" --limit 30 --json` when the command is available.
33
+ - Show the best-ranked chunk from each of at most 30 distinct Markdown files and render the documentation tree through directory depth 3.
34
+ - If query is unavailable, continue from the tree, README indexes, and targeted reads.
35
+ 5. Read document bodies selectively.
36
+ - Follow README indexes as maintained tables of contents.
37
+ - Prefer query results, explicit paths, and the current request before broader search.
38
+ - Use `grep` or `find` only when targeted reads do not provide enough evidence.
39
+ 6. Read local memory only when relevant.
40
+ - For active plans, list `docs/plan` entries first and read only relevant plan files.
41
+ - Use `docs/archive/README.md` as the history map. Do not scan archive bodies by default.
42
+ 7. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.
53
43
 
54
44
  ## Output Shape
55
45
 
56
- For explicit manual full loads, respond concisely with:
46
+ For a full load, respond concisely with:
57
47
 
58
- - Project summary
48
+ - Project narrative and purpose
59
49
  - Key working rules
60
- - Available commands and verification methods, including `/dd:impact` or `dd:impact` when available for changed-file review
61
- - Documentation map
62
- - Active plans
63
- - Relevant archive notes
64
- - Open TODO/TBD items or questions to clarify
50
+ - Relevant documentation and verification routes
51
+ - Relevant active plans or archive history only when needed
52
+ - Questions surfaced by loaded material
65
53
 
66
- For compact loads, respond with compact routing information:
54
+ For a compact load, respond with:
67
55
 
68
- - Project-memory status: available, stale, missing, or newly refreshed memory
69
- - Relevant docs map: only the docs areas or README indexes likely needed for the current request
70
- - Active plan hints: active plan paths only when relevant
71
- - Next recommended reads: a short, bounded list, or a note that no further reads are needed
56
+ - Compact project-memory status
57
+ - Relevant documentation routes
58
+ - Relevant active plan hints only when needed
59
+ - A short bounded list of next reads, or a note that none are needed
package/commands/dd/plan.md CHANGED
@@ -44,7 +44,7 @@ Prefer live repository docs in this order:
44
44
  - 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.
45
45
  - 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.
46
46
  - 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.
47
- - 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.
47
+ - During planning, treat these dotdotgod commands as bounded context/status helpers: `status`, `query`, `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.
48
48
  - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
49
49
  - Read code only after docs identify likely module boundaries, impact output points to relevant files, or docs are missing/stale.
50
50
  3. Create or update an active plan at this path when durable planning is needed:
package/hooks/README.md CHANGED
@@ -43,7 +43,7 @@ This SDLC framing maps common Claude Code guidance about a project brain to dotd
43
43
  - Use `/dd:load` or the `project-load` skill when you intentionally want a curated project-memory load.
44
44
  - Use `/dd:plan` or the `doc-first-planning` skill before implementation, refactors, migrations, or multi-step work.
45
45
  - Use `/dd:impact` or the `impact-review` skill after source/config/docs edits and before broad verification, commits, pushes, publishing, or final handoff.
46
- - 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.
46
+ - 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.
47
47
  - Use hooks for small reminders at session start, prompt submission, tool boundaries, or stop time.
48
48
 
49
49
  ## Opt-In Levels
@@ -67,7 +67,7 @@ This example reminds Claude to use dotdotgod intentionally and checks cache stat
67
67
  "hooks": [
68
68
  {
69
69
  "type": "command",
70
- "command": "printf '%s\\n' 'dotdotgod: use /dd:load or dotdotgod load-snapshot when project memory is needed.'",
70
+ "command": "printf '%s\\n' 'dotdotgod: use /dd:load for project memory or dotdotgod query for focused documentation search.'",
71
71
  "timeout": 10
72
72
  }
73
73
  ]
@@ -167,4 +167,4 @@ A strict script must read hook JSON from stdin, confirm the session is explicitl
167
167
  - Do not run `dotdotgod init` or `dotdotgod config init` automatically.
168
168
  - Do not move active plans to `docs/archive/` automatically.
169
169
  - Do not block all source writes without an explicit plan-only state signal.
170
- - Do not treat `dotdotgod load-snapshot` as side-effect-free in strict hooks; it may lazily refresh the ignored `.dotdotgod/` cache.
170
+ - 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dotdotgod/claude-code",
3
- "version": "0.2.4",
3
+ "version": "0.2.6",
4
4
  "description": "Claude Code adapter for dotdotgod project memory workflows.",
5
5
  "type": "module",
6
6
  "license": "Elastic-2.0",
@@ -38,7 +38,7 @@
38
38
  "url": "https://github.com/dotdotgod/dotdotgod-kit/issues"
39
39
  },
40
40
  "scripts": {
41
- "verify": "node -e \"const fs=require('fs'); const req=['.claude-plugin/plugin.json','commands/dd/load.md','commands/dd/plan.md','commands/dd/plan-goal.md','commands/dd/init.md','commands/dd/impact.md','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/plan-goal/SKILL.md','skills/plan-goal/agents/openai.yaml','skills/project-initializer/SKILL.md','skills/impact-review/SKILL.md','skills/document-clarify/SKILL.md','skills/document-clarify/agents/openai.yaml','skills/project-initializer/scripts/init_project.sh','hooks/README.md']; JSON.parse(fs.readFileSync('.claude-plugin/plugin.json','utf8')); for (const f of req) { if (!fs.existsSync(f)) throw new Error('missing '+f); } console.log('claude-code adapter ok')\"",
41
+ "verify": "node -e \"const fs=require('fs'); const req=['.claude-plugin/plugin.json','commands/dd/load.md','commands/dd/plan.md','commands/dd/plan-goal.md','commands/dd/init.md','commands/dd/impact.md','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/plan-goal/SKILL.md','skills/plan-goal/agents/openai.yaml','skills/project-initializer/SKILL.md','skills/impact-review/SKILL.md','skills/document-clarify/SKILL.md','skills/document-clarify/agents/openai.yaml','skills/project-initializer/scripts/init_project.sh','skills/project-initializer/templates/dotdotgod.config.json','hooks/README.md']; JSON.parse(fs.readFileSync('.claude-plugin/plugin.json','utf8')); for (const f of req) { if (!fs.existsSync(f)) throw new Error('missing '+f); } console.log('claude-code adapter ok')\"",
42
42
  "pack:dry-run": "pnpm pack --dry-run --json"
43
43
  }
44
44
  }
package/skills/doc-first-planning/SKILL.md CHANGED
@@ -40,7 +40,7 @@ Prefer live repository docs in this order:
40
40
  - 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.
41
41
  - 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.
42
42
  - 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.
43
- - 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.
43
+ - During planning, treat these dotdotgod commands as bounded context/status helpers: `status`, `query`, `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.
44
44
  - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
45
45
  - Read code only after docs identify likely module boundaries, impact output points to relevant files, or docs are missing/stale.
46
46
  3. Create or update an active plan at this path when durable planning is needed:
package/skills/document-clarify/SKILL.md CHANGED
@@ -19,8 +19,8 @@ Use this workflow for README indexes, specs, test docs, architecture docs, activ
19
19
  Prefer live repository context in this order:
20
20
 
21
21
  1. The user's target file or requested documentation area.
22
- 2. Resolved dotdotgod memory-area metadata from `dotdotgod load-snapshot <root> --json` when available.
23
- 3. Resolved config from `dotdotgod config <root> --json` when a snapshot is unavailable or stale.
22
+ 2. Relevant documentation from `dotdotgod query <root> "<focus>" --json` when semantic routing is useful.
23
+ 3. Resolved config from `dotdotgod config <root> --json` when memory-area or documentation-map policy is needed.
24
24
  4. The nearest README index, especially `docs/README.md` and the local area `README.md`.
25
25
  5. Directly linked specs, tests, architecture notes, commands, and traceability targets needed to preserve meaning.
26
26
  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 CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: project-initializer
3
- 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.
3
+ 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.
4
4
  version: 1.0.0
5
5
  ---
6
6
 
@@ -10,60 +10,54 @@ version: 1.0.0
10
10
 
11
11
  ## Overview
12
12
 
13
- Create a conservative dotdotgod project baseline that multiple AI coding agents can share:
13
+ Create a conservative dotdotgod project baseline shared by AI coding agents:
14
14
 
15
15
  - `AGENTS.md` is the canonical project instruction file.
16
- - `CLAUDE.md` imports `AGENTS.md` for Claude Code.
17
- - `CODEX.md` points Codex users to `AGENTS.md`.
18
- - `docs/` contains `spec`, `test`, `arch`, `plan`, and `archive` areas with concise README files.
19
- - `docs/arch/` covers architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
20
- - Behavior specs can include fenced `json dotdotgod` traceability blocks as the final section; `dotdotgod validate` owns and enforces that machine-readable schema for CLI users.
21
- - Code conventions can start as `docs/arch/CODE_CONVENTIONS.md`; when they grow across multiple topics, promote them to `docs/arch/conventions/README.md` plus supporting UPPER_SNAKE_CASE files.
22
- - Under `docs/`, all directories use kebab-case and all markdown file names use UPPER_SNAKE_CASE, including `README.md`.
23
- - `docs/plan/<task-slug>/README.md` is the default shape for active plan work.
24
- - Completed plans move to `docs/archive/plan/<task-slug>/`.
25
- - Temporary reports and investigations move to `docs/archive/report/<report-slug>/`.
26
- - `.gitignore` includes `docs/plan`, `docs/archive`, and `.dotdotgod` so local memory and the graph cache stay local by default.
27
-
28
- Use the dotdotgod CLI initializer when it is already available in the target environment:
16
+ - `CLAUDE.md` and `CODEX.md` are thin agent-specific entrypoints.
17
+ - `docs/` contains concise indexes for specs, tests, architecture, active plans, and archives.
18
+ - `dotdotgod.config.json` materializes the complete editable default project policy.
19
+ - `.gitignore` keeps `docs/plan`, `docs/archive`, and `.dotdotgod` local by default.
20
+
21
+ Under `docs/`, directories use kebab-case and markdown file names use UPPER_SNAKE_CASE, including `README.md`.
22
+
23
+ ## CLI and Fallback
24
+
25
+ Prefer the CLI initializer:
29
26
 
30
27
  ```bash
31
28
  dotdotgod init <project-root>
32
29
  ```
33
30
 
34
- Do not require users to install the CLI just to initialize. If `dotdotgod` is unavailable or the command is not executable, use the bundled dependency-free shell fallback:
31
+ Use the bundled fallback when the CLI is unavailable:
35
32
 
36
33
  ```bash
37
34
  sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>
38
35
  ```
39
36
 
40
- The fallback still creates the baseline docs indexes and local-memory `.gitignore` entries, so project loading can work from README indexes until the CLI is added later.
41
-
42
- Use `--dry-run` before touching an unfamiliar repository. Use `--dotdot-setting` when the user wants general dotdot documentation structure and code conventions generated under `docs/arch/DOCS_STRUCTURE.md` and `docs/arch/CODE_CONVENTIONS.md`, then referenced from `AGENTS.md`. Use `--force` only when explicitly requested; it creates timestamped backups before replacing files.
37
+ Both paths create the same baseline file set and canonical config while preserving existing files. Use `--dry-run` for unfamiliar repositories and `--dotdot-setting` for the optional documentation and code-convention guidance.
43
38
 
44
39
  ## Workflow
45
40
 
46
- 1. Inspect the target project root.
47
- - Check for existing `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, and `docs/`.
48
- - Preserve project-specific instructions unless the user asks to replace them.
49
- - If both `AGENT.md` and `AGENTS.md` exist, prefer `AGENTS.md` as canonical and leave `AGENT.md` untouched unless asked.
41
+ 1. Inspect the project root.
42
+ - Check `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, `docs/`, and `dotdotgod.config.json`.
43
+ - Preserve project-specific instructions and unrelated user work.
44
+ - Keep `AGENTS.md` canonical when both `AGENT.md` and `AGENTS.md` exist.
50
45
  2. Run the initializer.
51
- - Try `dotdotgod init` only when the CLI is available; otherwise run the bundled fallback script without blocking initialization.
52
- - Default behavior creates missing files only.
53
- - Existing files are skipped.
54
- - `.gitignore` is created or appended with missing `docs/plan`, `docs/archive`, and `.dotdotgod` entries.
55
- - `--dotdot-setting` additionally creates `docs/arch/DOCS_STRUCTURE.md` and `docs/arch/CODE_CONVENTIONS.md`, adds them to the architecture README index, and adds an `AGENTS.md` reference.
56
- - `--force` backs up replaced files as `<name>.bak.<timestamp>`.
57
- 3. Review generated files.
58
- - Fill project-specific sections in `AGENTS.md` when context is available.
59
- - Keep `CLAUDE.md` and `CODEX.md` thin so instructions do not drift.
60
- - Treat `docs/plan` and `docs/archive` as local working memory unless the project deliberately changes that policy.
61
- - When adding behavior specs, run `dotdotgod validate` when the CLI is available and follow any traceability schema/example shown in validation errors; if the CLI is unavailable, keep README indexes accurate and validate later.
46
+ - Use the CLI when available; otherwise use the bundled fallback.
47
+ - Existing files are always preserved and skipped.
48
+ 3. Review and validate.
49
+ - Fill project-specific placeholders in `AGENTS.md` when the required context is known.
50
+ - Keep `CLAUDE.md` and `CODEX.md` thin.
51
+ - Preserve the generated complete memory-area set; do not replace it with a partial hand-written list.
52
+ - Run `dotdotgod validate <project-root>` after creating or changing config when the CLI is available.
53
+ - Inspect `dotdotgod config <project-root> --json` when validation fails or resolved policy needs review.
62
54
  4. Report the result.
63
- - List created/skipped/backed-up files.
64
- - Mention any existing instructions that still need manual consolidation.
55
+ - List created, updated, and skipped files, plus validation failures.
56
+ - Report when CLI validation was unavailable.
57
+ - Identify existing instructions that still require manual consolidation.
65
58
 
66
59
  ## Bundled Resources
67
60
 
68
- - `scripts/init_project.sh`: fallback scaffold generator that mirrors `dotdotgod init` with POSIX shell only.
69
- - `references/agent-docs.md`: naming rationale and expected content model for shared agent docs.
61
+ - `scripts/init_project.sh`: POSIX fallback initializer.
62
+ - `templates/dotdotgod.config.json`: generated canonical config template used by the fallback.
63
+ - `references/agent-docs.md`: shared agent-document naming and content model.
package/skills/project-initializer/agents/openai.yaml CHANGED
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: "Project Initializer"
3
- short_description: "Initialize agent docs and local docs folders."
4
- default_prompt: "Initialize this project with dotdotgod init when available, otherwise use the bundled fallback; include AGENTS.md, CLAUDE.md, CODEX.md, docs folders, and local memory gitignore entries."
3
+ short_description: "Initialize project memory and config."
4
+ 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 CHANGED
@@ -1,12 +1,16 @@
1
1
  #!/bin/sh
2
2
  set -eu
3
3
 
4
+ SCRIPT_DIR=$(CDPATH= cd -P "$(dirname "$0")" && pwd)
5
+ CONFIG_TEMPLATE="$SCRIPT_DIR/../templates/dotdotgod.config.json"
6
+
4
7
  usage() {
5
8
  cat <<'EOF'
6
- Usage: init_project.sh <project-root> [--project-name NAME] [--dotdot-setting] [--force] [--dry-run]
9
+ Usage: init_project.sh <project-root> [--project-name NAME] [--dotdot-setting] [--dry-run]
7
10
 
8
11
  Initializes:
9
12
  AGENTS.md, CLAUDE.md, CODEX.md
13
+ dotdotgod.config.json
10
14
  docs/README.md
11
15
  docs/spec/README.md
12
16
  docs/test/README.md
@@ -19,7 +23,6 @@ EOF
19
23
 
20
24
  PROJECT_ROOT=""
21
25
  PROJECT_NAME=""
22
- FORCE=0
23
26
  DRY_RUN=0
24
27
  DOTDOT_SETTING=0
25
28
 
@@ -37,10 +40,6 @@ while [ "$#" -gt 0 ]; do
37
40
  DOTDOT_SETTING=1
38
41
  shift
39
42
  ;;
40
- --force)
41
- FORCE=1
42
- shift
43
- ;;
44
43
  --dry-run)
45
44
  DRY_RUN=1
46
45
  shift
@@ -80,9 +79,11 @@ if [ -z "$PROJECT_NAME" ]; then
80
79
  PROJECT_NAME=$(basename "$PROJECT_ROOT")
81
80
  fi
82
81
 
83
- timestamp() {
84
- date -u "+%Y%m%d%H%M%S"
85
- }
82
+ CONFIG_PATH="$PROJECT_ROOT/dotdotgod.config.json"
83
+ if [ ! -e "$CONFIG_PATH" ] && [ ! -f "$CONFIG_TEMPLATE" ]; then
84
+ echo "error: missing initializer config template: $CONFIG_TEMPLATE" >&2
85
+ exit 2
86
+ fi
86
87
 
87
88
  print_result() {
88
89
  status=$1
@@ -99,35 +100,19 @@ write_file() {
99
100
  path=$1
100
101
  content=$2
101
102
 
102
- if [ -e "$path" ] && [ "$FORCE" -ne 1 ]; then
103
+ if [ -e "$path" ]; then
103
104
  print_result "skipped" "$path"
104
105
  return
105
106
  fi
106
107
 
107
- backup=""
108
- if [ -e "$path" ] && [ "$FORCE" -eq 1 ]; then
109
- backup="$path.bak.$(timestamp)"
110
- if [ "$DRY_RUN" -ne 1 ]; then
111
- mv "$path" "$backup"
112
- fi
113
- fi
114
-
115
108
  if [ "$DRY_RUN" -eq 1 ]; then
116
- if [ -n "$backup" ]; then
117
- print_result "would_replace" "$path" "backup=$backup"
118
- else
119
- print_result "would_create" "$path"
120
- fi
109
+ print_result "would_create" "$path"
121
110
  return
122
111
  fi
123
112
 
124
113
  mkdir -p "$(dirname "$path")"
125
114
  printf '%s\n' "$content" > "$path"
126
- if [ -n "$backup" ]; then
127
- print_result "replaced" "$path" "backup=$backup"
128
- else
129
- print_result "created" "$path"
130
- fi
115
+ print_result "created" "$path"
131
116
  }
132
117
 
133
118
  ensure_gitignore_entry() {
@@ -405,6 +390,12 @@ Use this area for local completed plans, temporary reports, historical notes, pa
405
390
 
406
391
  This directory is local-only and ignored by git by default."
407
392
 
393
+ if [ -e "$CONFIG_PATH" ]; then
394
+ print_result "skipped" "$CONFIG_PATH"
395
+ else
396
+ write_file "$CONFIG_PATH" "$(cat "$CONFIG_TEMPLATE")"
397
+ fi
398
+
408
399
  ensure_gitignore_entry "docs/plan"
409
400
  ensure_gitignore_entry "docs/archive"
410
401
  ensure_gitignore_entry ".dotdotgod"
package/skills/project-initializer/templates/dotdotgod.config.json ADDED
@@ -0,0 +1,269 @@
1
+ {
2
+ "memory": {
3
+ "areas": [
4
+ {
5
+ "id": "rules",
6
+ "label": "Agent Rules",
7
+ "paths": [
8
+ "AGENTS.md"
9
+ ],
10
+ "excludePaths": [],
11
+ "scope": "shared",
12
+ "freshness": "fresh",
13
+ "role": "agent-working-rules",
14
+ "priority": 100,
15
+ "includeBodiesByDefault": true
16
+ },
17
+ {
18
+ "id": "agent-entrypoint",
19
+ "label": "Agent Entrypoints",
20
+ "paths": [
21
+ "CLAUDE.md",
22
+ "CODEX.md"
23
+ ],
24
+ "excludePaths": [],
25
+ "scope": "shared",
26
+ "freshness": "fresh",
27
+ "role": "agent-specific-entrypoint",
28
+ "priority": 85,
29
+ "includeBodiesByDefault": true
30
+ },
31
+ {
32
+ "id": "project-overview",
33
+ "label": "Project Overview",
34
+ "paths": [
35
+ "README.md"
36
+ ],
37
+ "excludePaths": [],
38
+ "scope": "shared",
39
+ "freshness": "fresh",
40
+ "role": "project-map",
41
+ "priority": 85,
42
+ "includeBodiesByDefault": true
43
+ },
44
+ {
45
+ "id": "docs-index",
46
+ "label": "Docs Index",
47
+ "paths": [
48
+ "docs/README.md"
49
+ ],
50
+ "excludePaths": [],
51
+ "scope": "shared",
52
+ "freshness": "fresh",
53
+ "role": "documentation-routing-map",
54
+ "priority": 90,
55
+ "includeBodiesByDefault": true
56
+ },
57
+ {
58
+ "id": "spec",
59
+ "label": "Product Specs",
60
+ "paths": [
61
+ "docs/spec/**"
62
+ ],
63
+ "excludePaths": [],
64
+ "scope": "shared",
65
+ "freshness": "fresh",
66
+ "role": "behavior-truth",
67
+ "priority": 80,
68
+ "includeBodiesByDefault": true
69
+ },
70
+ {
71
+ "id": "architecture",
72
+ "label": "Architecture",
73
+ "paths": [
74
+ "docs/arch/**"
75
+ ],
76
+ "excludePaths": [],
77
+ "scope": "shared",
78
+ "freshness": "fresh",
79
+ "role": "architecture-rationale",
80
+ "priority": 75,
81
+ "includeBodiesByDefault": true
82
+ },
83
+ {
84
+ "id": "test",
85
+ "label": "Tests",
86
+ "paths": [
87
+ "docs/test/**"
88
+ ],
89
+ "excludePaths": [],
90
+ "scope": "shared",
91
+ "freshness": "fresh",
92
+ "role": "verification-knowledge",
93
+ "priority": 70,
94
+ "includeBodiesByDefault": true
95
+ },
96
+ {
97
+ "id": "active-plan",
98
+ "label": "Active Plans",
99
+ "paths": [
100
+ "docs/plan/**"
101
+ ],
102
+ "excludePaths": [],
103
+ "scope": "local",
104
+ "freshness": "fresh",
105
+ "role": "active-task-intent",
106
+ "priority": 95,
107
+ "includeBodiesByDefault": true
108
+ },
109
+ {
110
+ "id": "archive-map",
111
+ "label": "Archive Map",
112
+ "paths": [
113
+ "docs/archive/README.md"
114
+ ],
115
+ "excludePaths": [],
116
+ "scope": "local",
117
+ "freshness": "stale",
118
+ "role": "historical-memory-map",
119
+ "priority": 65,
120
+ "includeBodiesByDefault": true
121
+ },
122
+ {
123
+ "id": "archive-body",
124
+ "label": "Archive Body",
125
+ "paths": [
126
+ "docs/archive/**"
127
+ ],
128
+ "excludePaths": [
129
+ "docs/archive/README.md"
130
+ ],
131
+ "scope": "local",
132
+ "freshness": "stale",
133
+ "role": "historical-memory-body",
134
+ "priority": 20,
135
+ "includeBodiesByDefault": false
136
+ },
137
+ {
138
+ "id": "docs",
139
+ "label": "Project Documentation",
140
+ "paths": [
141
+ "docs/**"
142
+ ],
143
+ "excludePaths": [],
144
+ "scope": "shared",
145
+ "freshness": "fresh",
146
+ "role": "project-documentation",
147
+ "priority": 60,
148
+ "includeBodiesByDefault": true
149
+ }
150
+ ]
151
+ },
152
+ "traceability": {
153
+ "required": [
154
+ "docs/spec/**"
155
+ ],
156
+ "exclude": [
157
+ "**/README.md"
158
+ ]
159
+ },
160
+ "validation": {
161
+ "markdown": {
162
+ "maxLines": 200,
163
+ "maxChars": 10000,
164
+ "exclude": [],
165
+ "filename": {
166
+ "warnNumberedSeries": true,
167
+ "allow": []
168
+ }
169
+ }
170
+ },
171
+ "impactRanking": {
172
+ "preset": "balanced",
173
+ "weights": {
174
+ "ppr": 40,
175
+ "traceability": 30,
176
+ "memoryPolicy": 10,
177
+ "verification": 15,
178
+ "proximity": 10,
179
+ "semantic": 10,
180
+ "freshness": 5,
181
+ "archivePenalty": -25
182
+ },
183
+ "ppr": {
184
+ "enabled": true,
185
+ "damping": 0.85,
186
+ "iterations": 20,
187
+ "tolerance": 0.000001
188
+ },
189
+ "relationWeights": {
190
+ "implemented_by": 4,
191
+ "verified_by": 4,
192
+ "related_doc": 3,
193
+ "verification_command": 3,
194
+ "links_to": 2,
195
+ "belongs_to_area": 2,
196
+ "semantic_similarity": 2,
197
+ "mentions_package": 1
198
+ },
199
+ "traceabilityBoosts": {
200
+ "implemented_by": 30,
201
+ "incoming:implemented_by": 30,
202
+ "verified_by": 25,
203
+ "incoming:verified_by": 25,
204
+ "verification_command": 15,
205
+ "incoming:verification_command": 15,
206
+ "related_doc": 12,
207
+ "incoming:related_doc": 12
208
+ },
209
+ "verificationBoosts": {
210
+ "verified_by": 15,
211
+ "incoming:verified_by": 15,
212
+ "verification_command": 12,
213
+ "incoming:verification_command": 12
214
+ },
215
+ "semanticBoosts": {
216
+ "semantic_similarity": 8,
217
+ "incoming:semantic_similarity": 8,
218
+ "mentions_package": 4,
219
+ "incoming:mentions_package": 4
220
+ },
221
+ "proximityBoosts": {
222
+ "links_to": 6,
223
+ "incoming:links_to": 6,
224
+ "routes_to": 5,
225
+ "incoming:routes_to": 5
226
+ },
227
+ "semantic": {
228
+ "enabled": true,
229
+ "threshold": 0.5,
230
+ "topKPerFile": 5,
231
+ "includeArchiveBodies": false,
232
+ "signals": [
233
+ "path",
234
+ "filename",
235
+ "heading",
236
+ "package"
237
+ ]
238
+ }
239
+ },
240
+ "referenceExpansion": {
241
+ "fuzzy": {
242
+ "lowSignal": {
243
+ "add": [],
244
+ "remove": []
245
+ }
246
+ }
247
+ },
248
+ "integrations": {
249
+ "trello": {
250
+ "syncPaths": []
251
+ }
252
+ },
253
+ "load": {
254
+ "pinnedPaths": [],
255
+ "pinnedBodies": [],
256
+ "documentationSummary": {
257
+ "exclude": [
258
+ "docs/plan",
259
+ "docs/archive"
260
+ ]
261
+ }
262
+ },
263
+ "planMode": {
264
+ "writablePaths": [
265
+ "docs/plan/**",
266
+ "docs/archive/**"
267
+ ]
268
+ }
269
+ }
package/skills/project-load/SKILL.md CHANGED
@@ -10,58 +10,46 @@ version: 1.0.0
10
10
 
11
11
  ## Goal
12
12
 
13
- 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.
14
-
15
- Do not modify files during the load pass unless the user explicitly asks for edits after the summary.
13
+ Load the current repository's dotdotgod project memory without modifying source, documentation, or project config. A focused query may refresh ignored `.dotdotgod/vectors/` data and the runtime's user-level model cache. Use a full load for an explicit project overview and a compact load to refresh an already-loaded session. Treat free-form arguments as query text, not as mode switches.
16
14
 
17
15
  ## Workflow
18
16
 
19
17
  1. Identify the repository root and current state.
20
- - Check current directory, git root, branch, and dirty worktree status.
18
+ - Check the current directory and, when Git is available, the repository root, branch, and dirty worktree status.
21
19
  - Mention user changes and avoid reverting or cleaning them.
22
- 2. Prefer the bounded CLI snapshot when available.
23
- - 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.
24
- - 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.
25
- - 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`.
26
- - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
27
- - 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.
28
- - 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.
29
- - 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.
30
- - 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.
31
- - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
32
- - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
33
- - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
34
- - Related behavior docs: `docs/spec/LOAD_PROJECT.md`, `docs/spec/CROSS_AGENT_SUPPORT.md`, and `docs/arch/CROSS_AGENT_ARCHITECTURE.md`.
35
- - If the CLI is unavailable, network/package execution is undesirable, or the command fails, continue with the manual README-index fallback below.
36
- 3. Inspect baseline memory files when present:
37
- - `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`
38
- - `docs/README.md`
39
- - `docs/spec/README.md`
40
- - `docs/test/README.md`
41
- - `docs/arch/README.md`
42
- - `docs/plan/README.md`
43
- - `docs/archive/README.md`
44
- 4. Start with `AGENTS.md`, `README.md`, and `docs/README.md` when they are not already clear from the CLI snapshot or loaded context.
45
- 5. Follow README indexes. Read relevant docs under `docs/spec`, `docs/test`, and `docs/arch` selectively unless the task needs a full refresh.
46
- 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.
47
- 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.
48
- 8. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.
20
+ 2. Read baseline memory only when it is not already clear from loaded context.
21
+ - Start with `AGENTS.md`, the current adapter entrypoint when present, `README.md`, and `docs/README.md`.
22
+ - Do not run scaffold, config-writing, or source-modifying commands during a load.
23
+ 3. Build the shared documentation map.
24
+ - Discover Markdown files under `docs/` after applying `load.documentationSummary.exclude`, which excludes `docs/plan` and `docs/archive` by default.
25
+ - Render repository-relative paths as a prefix-compressed tree. Count `docs/` as directory depth 1.
26
+ - Without arguments, expand through directory depth 5. At the boundary, summarize deeper descendants with exact directory and Markdown-file counts.
27
+ 4. Use query routing only when arguments are present.
28
+ - Run `dotdotgod query <root> "<arguments>" --limit 30 --json` when the command is available.
29
+ - Show the best-ranked chunk from each of at most 30 distinct Markdown files and render the documentation tree through directory depth 3.
30
+ - If query is unavailable, continue from the tree, README indexes, and targeted reads.
31
+ 5. Read document bodies selectively.
32
+ - Follow README indexes as maintained tables of contents.
33
+ - Prefer query results, explicit paths, and the current request before broader search.
34
+ - Use `grep` or `find` only when targeted reads do not provide enough evidence.
35
+ 6. Read local memory only when relevant.
36
+ - For active plans, list `docs/plan` entries first and read only relevant plan files.
37
+ - Use `docs/archive/README.md` as the history map. Do not scan archive bodies by default.
38
+ 7. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.
49
39
 
50
40
  ## Output Shape
51
41
 
52
- For explicit manual full loads, respond concisely with:
42
+ For a full load, respond concisely with:
53
43
 
54
- - Project summary
44
+ - Project narrative and purpose
55
45
  - Key working rules
56
- - Available commands and verification methods, including `/dd:impact` or `dd:impact` when available for changed-file review
57
- - Documentation map
58
- - Active plans
59
- - Relevant archive notes
60
- - Open TODO/TBD items or questions to clarify
46
+ - Relevant documentation and verification routes
47
+ - Relevant active plans or archive history only when needed
48
+ - Questions surfaced by loaded material
61
49
 
62
- For compact loads, respond with compact routing information:
50
+ For a compact load, respond with:
63
51
 
64
- - Project-memory status: available, stale, missing, or newly refreshed memory
65
- - Relevant docs map: only the docs areas or README indexes likely needed for the current request
66
- - Active plan hints: active plan paths only when relevant
67
- - Next recommended reads: a short, bounded list, or a note that no further reads are needed
52
+ - Compact project-memory status
53
+ - Relevant documentation routes
54
+ - Relevant active plan hints only when needed
55
+ - A short bounded list of next reads, or a note that none are needed
package/skills/project-load/agents/openai.yaml CHANGED
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: "Project Load"
3
3
  short_description: "Load dotdotgod project memory."
4
- default_prompt: "Load this project's dotdotgod memory and summarize rules, docs, commands, active plans, and open questions."
4
+ default_prompt: "Load this project's dotdotgod memory and summarize rules, docs, commands, relevant active plans, and questions surfaced by the loaded material."