@dotdotgod/claude-code 0.2.3 → 0.2.5

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 +1 -1
  2. package/commands/dd/impact.md +5 -4
  3. package/commands/dd/init.md +31 -37
  4. package/commands/dd/plan-goal.md +1 -1
  5. package/commands/dd/plan.md +1 -1
  6. package/hooks/README.md +2 -2
  7. package/package.json +2 -2
  8. package/skills/doc-first-planning/SKILL.md +1 -1
  9. package/skills/impact-review/SKILL.md +5 -4
  10. package/skills/plan-goal/SKILL.md +1 -1
  11. package/skills/project-initializer/SKILL.md +31 -37
  12. package/skills/project-initializer/agents/openai.yaml +2 -2
  13. package/skills/project-initializer/scripts/init_project.sh +26 -1
  14. package/skills/project-initializer/templates/dotdotgod.config.json +269 -0
package/README.md CHANGED
@@ -37,7 +37,7 @@ 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. |
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
41
  | `/dd:load` | Load project memory read-only. | Prefers `dotdotgod load-snapshot <root> --json`, then falls back to README-index reads. |
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. |
package/commands/dd/impact.md CHANGED
@@ -24,12 +24,13 @@ This workflow is the Claude Code and Codex counterpart to Pi's `/impact-check` r
24
24
  - Check git status and preserve unrelated user edits.
25
25
  - Include unstaged, staged, and untracked source/config/docs files that are relevant to the current task.
26
26
  - Exclude dependencies, generated caches, build artifacts, secrets, and unrelated local-memory files unless the user explicitly asks about them.
27
- 2. Prefer bounded graph impact.
28
- - For each relevant changed source/config file, run `dotdotgod graph impact <root> --changed <path> --compact` or `--yml`.
29
- - If the local repository uses the source checkout CLI, use `node packages/cli/bin/dotdotgod.mjs graph impact <root> --changed <path> --compact` or `--yml`.
27
+ 2. Prefer bounded multi-seed graph impact.
28
+ - Collect the complete relevant changed-file set, preserve first-seen order, and run one command with repeated `--changed <path>` options for up to 20 unique paths: `dotdotgod graph impact <root> --changed <path-a> --changed <path-b> --compact` or `--yml`.
29
+ - If more than 20 unique paths remain, split them into ordered batches of at most 20. Do not run one command per file unless only one relevant path exists.
30
+ - If the local repository uses the source checkout CLI, use `node packages/cli/bin/dotdotgod.mjs graph impact <root> --changed <path-a> --changed <path-b> --compact` or `--yml`.
30
31
  - If the CLI is unavailable, continue with README indexes, traceability blocks, package metadata, and targeted grep/find fallback.
31
32
  3. Inspect impact output selectively.
32
- - Review related specs, tests, architecture docs, and source files with the highest scores and clearest reasons.
33
+ - Review the deduplicated combined ranking and each seed's non-seed top-five results, prioritizing related specs, tests, architecture docs, and source files with the highest scores and clearest reasons.
33
34
  - When behavior specs appear through `implemented_by`, `verified_by`, or `related_doc`, read those docs before broad verification.
34
35
  - Do not paste large raw impact JSON into the response unless the user asks for diagnostics.
35
36
  4. Repair or update related docs/tests when the impact output shows stale, missing, or contradictory project memory.
package/commands/dd/init.md CHANGED
@@ -14,60 +14,54 @@ 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 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.
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/`, `dotdotgod.config.json`, and `.dotdotgodrc.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 skipped unless the user approved `--force`.
52
+ - If `.dotdotgodrc.json` exists, preserve it and skip creation of `dotdotgod.config.json`, including under `--force`.
53
+ 3. Review and validate.
54
+ - Fill project-specific placeholders in `AGENTS.md` when the required context is known.
55
+ - Keep `CLAUDE.md` and `CODEX.md` thin.
56
+ - Preserve the generated complete memory-area set; do not replace it with a partial hand-written list.
57
+ - Run `dotdotgod validate <project-root>` after creating or changing config when the CLI is available.
58
+ - Inspect `dotdotgod config <project-root> --json` when validation fails or resolved policy needs review.
66
59
  4. Report the result.
67
- - List created/skipped/backed-up files.
68
- - Mention any existing instructions that still need manual consolidation.
60
+ - List created, skipped, replaced, backed-up, conflicting, and invalid files.
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/plan-goal.md CHANGED
@@ -82,7 +82,7 @@ Use the Stage 01 context, then update the durable plan artifact and checkpoint.
82
82
 
83
83
  Include in the durable plan and checkpoint:
84
84
  - **Memory Reads** — agent docs, README indexes, specs, architecture notes, test docs, and active plans consulted. Use `dotdotgod expand <root> "<request>" --json` when the request contains `[[...]]` refs; use `--fuzzy` for high-signal doc names before broad grep/find.
85
- - **Impact Candidates** — for each likely target file, run `dotdotgod graph impact <root> --changed <path> --compact` and record related specs, tests, scores, and reasons. Fall back to README indexes and traceability blocks when the CLI is unavailable.
85
+ - **Impact Candidates** — collect the likely target files and run one bounded multi-seed `dotdotgod graph impact <root> --changed <path-a> --changed <path-b> --compact` command for up to 20 unique paths, splitting only larger sets into ordered batches. Record the combined ranking and each seed's non-seed top-five specs, tests, scores, and reasons. Fall back to README indexes and traceability blocks when the CLI is unavailable.
86
86
  - **Related Files** — source, config, and doc files identified as relevant.
87
87
 
88
88
  Construction checklist categories: Memory reads, Impact candidates, Related files, Boundary risk.
package/commands/dd/plan.md CHANGED
@@ -42,7 +42,7 @@ Prefer live repository docs in this order:
42
42
  - Search docs by domain terms from the user request.
43
43
  - Read nearest README indexes and relevant focused docs.
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
- - When the dotdotgod CLI is available and likely target files are known, run `dotdotgod graph impact <root> --changed <path> --yml` for a small bounded set of those files. Use the 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.
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
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.
48
48
  - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
package/hooks/README.md CHANGED
@@ -114,7 +114,7 @@ Use this only when you want stop-time docs validation. It may be noisier than ad
114
114
 
115
115
  A `UserPromptSubmit` hook can add a reminder for implementation-like prompts. Keep the command fast and non-mutating. Prefer reminders over automatic planning because `/dd:plan` and the planning skill are the explicit durable workflow.
116
116
 
117
- `UserPromptSubmit` does not support matchers in Claude Code settings, so filter on the submitted `prompt` field inside the hook command. For planning-like prompts, use an advisory reminder that asks Claude to resolve explicit `[[...]]` project-memory refs with `dotdotgod expand`, identify the complete target file list, and run graph impact checks for every target file before finalizing the plan:
117
+ `UserPromptSubmit` does not support matchers in Claude Code settings, so filter on the submitted `prompt` field inside the hook command. For planning-like prompts, use an advisory reminder that asks Claude to resolve explicit `[[...]]` project-memory refs with `dotdotgod expand`, identify the complete target file list, and run one bounded multi-seed graph impact command with repeated `--changed` options for up to 20 unique paths before finalizing the plan. Split only larger sets into ordered batches:
118
118
 
119
119
  ```json
120
120
  {
@@ -124,7 +124,7 @@ A `UserPromptSubmit` hook can add a reminder for implementation-like prompts. Ke
124
124
  "hooks": [
125
125
  {
126
126
  "type": "command",
127
- "command": "python3 -c \"import json,re,sys; p=json.load(sys.stdin).get('prompt',''); msg='dotdotgod: advisory reminder only. If the prompt contains [[...]] refs, run dotdotgod expand . \\\"<prompt>\\\" --json before broad grep/find. For planning work, identify the complete target file list, run dotdotgod graph impact . --changed <path> --compact for every target file, and use impact output to strengthen related docs, risks, and verification steps. After edits, use /dd:impact before broad verification or handoff. If docs change, run dotdotgod validate . --include-local-memory --check-index.'; print(msg) if re.search(r'plan|planning|플랜|계획|\\[\\[', p, re.I) else None\"",
127
+ "command": "python3 -c \"import json,re,sys; p=json.load(sys.stdin).get('prompt',''); msg='dotdotgod: advisory reminder only. If the prompt contains [[...]] refs, run dotdotgod expand . \\\"<prompt>\\\" --json before broad grep/find. For planning work, identify the complete target file list, run one bounded dotdotgod graph impact . --changed <path-a> --changed <path-b> --compact command for up to 20 unique paths, split only larger sets into ordered batches, and use combined and per-seed impact output to strengthen related docs, risks, and verification steps. After edits, use /dd:impact before broad verification or handoff. If docs change, run dotdotgod validate . --include-local-memory --check-index.'; print(msg) if re.search(r'plan|planning|플랜|계획|\\[\\[', p, re.I) else None\"",
128
128
  "timeout": 10
129
129
  }
130
130
  ]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dotdotgod/claude-code",
3
- "version": "0.2.3",
3
+ "version": "0.2.5",
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
@@ -38,7 +38,7 @@ Prefer live repository docs in this order:
38
38
  - Search docs by domain terms from the user request.
39
39
  - Read nearest README indexes and relevant focused docs.
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
- - When the dotdotgod CLI is available and likely target files are known, run `dotdotgod graph impact <root> --changed <path> --yml` for a small bounded set of those files. Use the 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.
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
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.
44
44
  - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
package/skills/impact-review/SKILL.md CHANGED
@@ -20,12 +20,13 @@ This workflow is the Claude Code and Codex counterpart to Pi's `/impact-check` r
20
20
  - Check git status and preserve unrelated user edits.
21
21
  - Include unstaged, staged, and untracked source/config/docs files that are relevant to the current task.
22
22
  - Exclude dependencies, generated caches, build artifacts, secrets, and unrelated local-memory files unless the user explicitly asks about them.
23
- 2. Prefer bounded graph impact.
24
- - For each relevant changed source/config file, run `dotdotgod graph impact <root> --changed <path> --compact` or `--yml`.
25
- - If the local repository uses the source checkout CLI, use `node packages/cli/bin/dotdotgod.mjs graph impact <root> --changed <path> --compact` or `--yml`.
23
+ 2. Prefer bounded multi-seed graph impact.
24
+ - Collect the complete relevant changed-file set, preserve first-seen order, and run one command with repeated `--changed <path>` options for up to 20 unique paths: `dotdotgod graph impact <root> --changed <path-a> --changed <path-b> --compact` or `--yml`.
25
+ - If more than 20 unique paths remain, split them into ordered batches of at most 20. Do not run one command per file unless only one relevant path exists.
26
+ - If the local repository uses the source checkout CLI, use `node packages/cli/bin/dotdotgod.mjs graph impact <root> --changed <path-a> --changed <path-b> --compact` or `--yml`.
26
27
  - If the CLI is unavailable, continue with README indexes, traceability blocks, package metadata, and targeted grep/find fallback.
27
28
  3. Inspect impact output selectively.
28
- - Review related specs, tests, architecture docs, and source files with the highest scores and clearest reasons.
29
+ - Review the deduplicated combined ranking and each seed's non-seed top-five results, prioritizing related specs, tests, architecture docs, and source files with the highest scores and clearest reasons.
29
30
  - When behavior specs appear through `implemented_by`, `verified_by`, or `related_doc`, read those docs before broad verification.
30
31
  - Do not paste large raw impact JSON into the response unless the user asks for diagnostics.
31
32
  4. Repair or update related docs/tests when the impact output shows stale, missing, or contradictory project memory.
package/skills/plan-goal/SKILL.md CHANGED
@@ -78,7 +78,7 @@ Use the Stage 01 context, then update the durable plan artifact and checkpoint.
78
78
 
79
79
  Include in the durable plan and checkpoint:
80
80
  - **Memory Reads** — agent docs, README indexes, specs, architecture notes, test docs, and active plans consulted. Use `dotdotgod expand <root> "<request>" --json` when the request contains `[[...]]` refs; use `--fuzzy` for high-signal doc names before broad grep/find.
81
- - **Impact Candidates** — for each likely target file, run `dotdotgod graph impact <root> --changed <path> --compact` and record related specs, tests, scores, and reasons. Fall back to README indexes and traceability blocks when the CLI is unavailable.
81
+ - **Impact Candidates** — collect the likely target files and run one bounded multi-seed `dotdotgod graph impact <root> --changed <path-a> --changed <path-b> --compact` command for up to 20 unique paths, splitting only larger sets into ordered batches. Record the combined ranking and each seed's non-seed top-five specs, tests, scores, and reasons. Fall back to README indexes and traceability blocks when the CLI is unavailable.
82
82
  - **Related Files** — source, config, and doc files identified as relevant.
83
83
 
84
84
  Construction checklist categories: Memory reads, Impact candidates, Related files, Boundary risk.
package/skills/project-initializer/SKILL.md CHANGED
@@ -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 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.
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/`, `dotdotgod.config.json`, and `.dotdotgodrc.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 skipped unless the user approved `--force`.
48
+ - If `.dotdotgodrc.json` exists, preserve it and skip creation of `dotdotgod.config.json`, including under `--force`.
49
+ 3. Review and validate.
50
+ - Fill project-specific placeholders in `AGENTS.md` when the required context is known.
51
+ - Keep `CLAUDE.md` and `CODEX.md` thin.
52
+ - Preserve the generated complete memory-area set; do not replace it with a partial hand-written list.
53
+ - Run `dotdotgod validate <project-root>` after creating or changing config when the CLI is available.
54
+ - Inspect `dotdotgod config <project-root> --json` when validation fails or resolved policy needs review.
62
55
  4. Report the result.
63
- - List created/skipped/backed-up files.
64
- - Mention any existing instructions that still need manual consolidation.
56
+ - List created, skipped, replaced, backed-up, conflicting, and invalid files.
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 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."
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
9
  Usage: init_project.sh <project-root> [--project-name NAME] [--dotdot-setting] [--force] [--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
@@ -80,6 +84,13 @@ if [ -z "$PROJECT_NAME" ]; then
80
84
  PROJECT_NAME=$(basename "$PROJECT_ROOT")
81
85
  fi
82
86
 
87
+ 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
90
+ echo "error: missing initializer config template: $CONFIG_TEMPLATE" >&2
91
+ exit 2
92
+ fi
93
+
83
94
  timestamp() {
84
95
  date -u "+%Y%m%d%H%M%S"
85
96
  }
@@ -106,7 +117,13 @@ write_file() {
106
117
 
107
118
  backup=""
108
119
  if [ -e "$path" ] && [ "$FORCE" -eq 1 ]; then
109
- backup="$path.bak.$(timestamp)"
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
110
127
  if [ "$DRY_RUN" -ne 1 ]; then
111
128
  mv "$path" "$backup"
112
129
  fi
@@ -405,6 +422,14 @@ Use this area for local completed plans, temporary reports, historical notes, pa
405
422
 
406
423
  This directory is local-only and ignored by git by default."
407
424
 
425
+ if [ -e "$RC_PATH" ]; then
426
+ print_result "conflict" "$CONFIG_PATH" "existing=$RC_PATH"
427
+ elif [ -e "$CONFIG_PATH" ] && [ "$FORCE" -ne 1 ]; then
428
+ print_result "skipped" "$CONFIG_PATH"
429
+ else
430
+ write_file "$CONFIG_PATH" "$(cat "$CONFIG_TEMPLATE")"
431
+ fi
432
+
408
433
  ensure_gitignore_entry "docs/plan"
409
434
  ensure_gitignore_entry "docs/archive"
410
435
  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
+ }