@dotdotgod/claude-code 0.2.5 → 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 (13) hide show
  1. package/README.md +2 -2
  2. package/commands/dd/init.md +9 -9
  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 +1 -1
  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 +6 -6
  10. package/skills/project-initializer/agents/openai.yaml +1 -1
  11. package/skills/project-initializer/scripts/init_project.sh +6 -40
  12. package/skills/project-load/SKILL.md +31 -43
  13. package/skills/project-load/agents/openai.yaml +1 -1
package/README.md CHANGED
@@ -38,7 +38,7 @@ claude --plugin-dir /path/to/dotdotgod/packages/claude-code
38
38
  | Command or skill | Use it for | Result |
39
39
  | --- | --- | --- |
40
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 read-only. | Prefers `dotdotgod load-snapshot <root> --json`, then falls back to README-index reads. |
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,14 +1,14 @@
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
 
@@ -38,18 +38,17 @@ Use the bundled fallback when the CLI is unavailable:
38
38
  sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>
39
39
  ```
40
40
 
41
- 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.
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.
42
42
 
43
43
  ## Workflow
44
44
 
45
45
  1. Inspect the project root.
46
- - Check `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, `docs/`, `dotdotgod.config.json`, and `.dotdotgodrc.json`.
46
+ - Check `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, `docs/`, and `dotdotgod.config.json`.
47
47
  - Preserve project-specific instructions and unrelated user work.
48
48
  - Keep `AGENTS.md` canonical when both `AGENT.md` and `AGENTS.md` exist.
49
49
  2. Run the initializer.
50
50
  - Use the CLI when available; otherwise use the bundled fallback.
51
- - Existing files are skipped unless the user approved `--force`.
52
- - If `.dotdotgodrc.json` exists, preserve it and skip creation of `dotdotgod.config.json`, including under `--force`.
51
+ - Existing files are always preserved and skipped.
53
52
  3. Review and validate.
54
53
  - Fill project-specific placeholders in `AGENTS.md` when the required context is known.
55
54
  - Keep `CLAUDE.md` and `CODEX.md` thin.
@@ -57,7 +56,8 @@ Both paths create the same baseline file set and canonical config while preservi
57
56
  - Run `dotdotgod validate <project-root>` after creating or changing config when the CLI is available.
58
57
  - Inspect `dotdotgod config <project-root> --json` when validation fails or resolved policy needs review.
59
58
  4. Report the result.
60
- - List created, skipped, replaced, backed-up, conflicting, and invalid files.
59
+ - List created, updated, and skipped files, plus validation failures.
60
+ - Report when CLI validation was unavailable.
61
61
  - Identify existing instructions that still require manual consolidation.
62
62
 
63
63
  ## Bundled Resources
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.5",
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",
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
 
@@ -34,18 +34,17 @@ Use the bundled fallback when the CLI is unavailable:
34
34
  sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>
35
35
  ```
36
36
 
37
- 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.
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.
38
38
 
39
39
  ## Workflow
40
40
 
41
41
  1. Inspect the project root.
42
- - Check `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, `docs/`, `dotdotgod.config.json`, and `.dotdotgodrc.json`.
42
+ - Check `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, `docs/`, and `dotdotgod.config.json`.
43
43
  - Preserve project-specific instructions and unrelated user work.
44
44
  - Keep `AGENTS.md` canonical when both `AGENT.md` and `AGENTS.md` exist.
45
45
  2. Run the initializer.
46
46
  - Use the CLI when available; otherwise use the bundled fallback.
47
- - Existing files are skipped unless the user approved `--force`.
48
- - If `.dotdotgodrc.json` exists, preserve it and skip creation of `dotdotgod.config.json`, including under `--force`.
47
+ - Existing files are always preserved and skipped.
49
48
  3. Review and validate.
50
49
  - Fill project-specific placeholders in `AGENTS.md` when the required context is known.
51
50
  - Keep `CLAUDE.md` and `CODEX.md` thin.
@@ -53,7 +52,8 @@ Both paths create the same baseline file set and canonical config while preservi
53
52
  - Run `dotdotgod validate <project-root>` after creating or changing config when the CLI is available.
54
53
  - Inspect `dotdotgod config <project-root> --json` when validation fails or resolved policy needs review.
55
54
  4. Report the result.
56
- - List created, skipped, replaced, backed-up, conflicting, and invalid files.
55
+ - List created, updated, and skipped files, plus validation failures.
56
+ - Report when CLI validation was unavailable.
57
57
  - Identify existing instructions that still require manual consolidation.
58
58
 
59
59
  ## Bundled Resources
package/skills/project-initializer/agents/openai.yaml CHANGED
@@ -1,4 +1,4 @@
1
1
  interface:
2
2
  display_name: "Project Initializer"
3
3
  short_description: "Initialize project memory and config."
4
- 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."
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
@@ -6,7 +6,7 @@ CONFIG_TEMPLATE="$SCRIPT_DIR/../templates/dotdotgod.config.json"
6
6
 
7
7
  usage() {
8
8
  cat <<'EOF'
9
- 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]
10
10
 
11
11
  Initializes:
12
12
  AGENTS.md, CLAUDE.md, CODEX.md
@@ -23,7 +23,6 @@ EOF
23
23
 
24
24
  PROJECT_ROOT=""
25
25
  PROJECT_NAME=""
26
- FORCE=0
27
26
  DRY_RUN=0
28
27
  DOTDOT_SETTING=0
29
28
 
@@ -41,10 +40,6 @@ while [ "$#" -gt 0 ]; do
41
40
  DOTDOT_SETTING=1
42
41
  shift
43
42
  ;;
44
- --force)
45
- FORCE=1
46
- shift
47
- ;;
48
43
  --dry-run)
49
44
  DRY_RUN=1
50
45
  shift
@@ -85,16 +80,11 @@ if [ -z "$PROJECT_NAME" ]; then
85
80
  fi
86
81
 
87
82
  CONFIG_PATH="$PROJECT_ROOT/dotdotgod.config.json"
88
- RC_PATH="$PROJECT_ROOT/.dotdotgodrc.json"
89
- if [ ! -e "$RC_PATH" ] && { [ ! -e "$CONFIG_PATH" ] || [ "$FORCE" -eq 1 ]; } && [ ! -f "$CONFIG_TEMPLATE" ]; then
83
+ if [ ! -e "$CONFIG_PATH" ] && [ ! -f "$CONFIG_TEMPLATE" ]; then
90
84
  echo "error: missing initializer config template: $CONFIG_TEMPLATE" >&2
91
85
  exit 2
92
86
  fi
93
87
 
94
- timestamp() {
95
- date -u "+%Y%m%d%H%M%S"
96
- }
97
-
98
88
  print_result() {
99
89
  status=$1
100
90
  path=$2
@@ -110,41 +100,19 @@ write_file() {
110
100
  path=$1
111
101
  content=$2
112
102
 
113
- if [ -e "$path" ] && [ "$FORCE" -ne 1 ]; then
103
+ if [ -e "$path" ]; then
114
104
  print_result "skipped" "$path"
115
105
  return
116
106
  fi
117
107
 
118
- backup=""
119
- if [ -e "$path" ] && [ "$FORCE" -eq 1 ]; then
120
- backup_base="$path.bak.$(timestamp)"
121
- backup="$backup_base"
122
- suffix=1
123
- while [ -e "$backup" ]; do
124
- backup="$backup_base.$suffix"
125
- suffix=$((suffix + 1))
126
- done
127
- if [ "$DRY_RUN" -ne 1 ]; then
128
- mv "$path" "$backup"
129
- fi
130
- fi
131
-
132
108
  if [ "$DRY_RUN" -eq 1 ]; then
133
- if [ -n "$backup" ]; then
134
- print_result "would_replace" "$path" "backup=$backup"
135
- else
136
- print_result "would_create" "$path"
137
- fi
109
+ print_result "would_create" "$path"
138
110
  return
139
111
  fi
140
112
 
141
113
  mkdir -p "$(dirname "$path")"
142
114
  printf '%s\n' "$content" > "$path"
143
- if [ -n "$backup" ]; then
144
- print_result "replaced" "$path" "backup=$backup"
145
- else
146
- print_result "created" "$path"
147
- fi
115
+ print_result "created" "$path"
148
116
  }
149
117
 
150
118
  ensure_gitignore_entry() {
@@ -422,9 +390,7 @@ Use this area for local completed plans, temporary reports, historical notes, pa
422
390
 
423
391
  This directory is local-only and ignored by git by default."
424
392
 
425
- if [ -e "$RC_PATH" ]; then
426
- print_result "conflict" "$CONFIG_PATH" "existing=$RC_PATH"
427
- elif [ -e "$CONFIG_PATH" ] && [ "$FORCE" -ne 1 ]; then
393
+ if [ -e "$CONFIG_PATH" ]; then
428
394
  print_result "skipped" "$CONFIG_PATH"
429
395
  else
430
396
  write_file "$CONFIG_PATH" "$(cat "$CONFIG_TEMPLATE")"
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."