@dotdotgod/claude-code 0.1.29 → 0.1.31

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/.claude-plugin/plugin.json +1 -1
  2. package/README.md +5 -3
  3. package/commands/dd/impact.md +2 -0
  4. package/commands/dd/init.md +2 -0
  5. package/commands/dd/load.md +4 -2
  6. package/commands/dd/plan.md +13 -9
  7. package/package.json +2 -2
  8. package/skills/doc-first-planning/SKILL.md +13 -9
  9. package/skills/document-clarify/SKILL.md +116 -0
  10. package/skills/document-clarify/agents/openai.yaml +4 -0
  11. package/skills/impact-review/SKILL.md +2 -0
  12. package/skills/project-initializer/SKILL.md +2 -0
  13. package/skills/project-load/SKILL.md +4 -2
package/.claude-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dotdotgod",
3
- "description": "Dotdotgod project memory workflows for Claude Code: initialize shared docs, load project memory, plan doc-first, and review graph impact.",
3
+ "description": "Dotdotgod project memory workflows for Claude Code: initialize shared docs, load project memory, plan doc-first, review graph impact, and clarify documentation.",
4
4
  "author": {
5
5
  "name": "dotdotgod"
6
6
  }
package/README.md CHANGED
@@ -25,7 +25,7 @@ files:
25
25
 
26
26
  `graph impact` ranks the specs, tests, architecture notes, config docs, and source files most likely to matter for a change. `--compact` keeps the result agent-facing: grouped by docs/tests/files and annotated with the reasons each item is likely relevant. It uses the project-memory graph built from Markdown links, README routes, headings, traceability blocks, package metadata, memory areas, and deterministic routing hints.
27
27
 
28
- Claude Code adapter for dotdotgod's context curation workflow. It packages `/dd:init`, `/dd:load`, `/dd:plan`, `/dd:impact`, and matching skills so Claude Code can start from the fixed load-context surface and use explicit maintained graph links instead of rediscovering specs, tests, plans, and archives from scratch.
28
+ Claude Code adapter for dotdotgod's context curation workflow. It packages `/dd:init`, `/dd:load`, `/dd:plan`, `/dd:impact`, matching skills for those command workflows, and the `document-clarify` skill so Claude Code can start from the fixed load-context surface and use explicit maintained graph links instead of rediscovering specs, tests, plans, and archives from scratch.
29
29
 
30
30
  ## What Gets Better?
31
31
 
@@ -35,14 +35,15 @@ Claude Code adapter for dotdotgod's context curation workflow. It packages `/dd:
35
35
  - Planning guidance encourages agents to keep README routes, traceability blocks, plans, and archives current so `graph impact` remains useful.
36
36
  - `/dd:plan` writes or updates durable task intent in `docs/plan/<task-slug>/README.md` before implementation.
37
37
  - `/dd:impact` reviews changed files with `dotdotgod graph impact` before broad verification or handoff, giving Claude Code a Pi-like impact workflow without Pi runtime enforcement.
38
+ - `document-clarify` improves project docs using memory-area roles and optional config guidance while preserving behavior contracts.
38
39
  - Product intent, design rationale, verification standards, and completed work stay in durable files rather than chat history.
39
- - Skills mirror the commands so natural-language requests can use the same workflows.
40
+ - Skills mirror the command workflows for init/load/plan/impact, and `document-clarify` adds a skill-only docs clarity workflow.
40
41
 
41
42
  ## Shared Memory and Traceability Model
42
43
 
43
44
  By default, `docs/spec/**` has two roles: it is stable shared/fresh project memory, and it is the traceability-enforced behavior-spec path. These concepts are independent:
44
45
 
45
- - `memory.areas` customizes memory classification, freshness, local/shared scope, priorities, and archive-body inclusion.
46
+ - `memory.areas` customizes memory classification, freshness, local/shared scope, priorities, archive-body inclusion, and optional document-area `description`/`clarify` guidance.
46
47
  - `traceability.required` / `traceability.exclude` customizes which markdown paths must end with `json dotdotgod` blocks.
47
48
 
48
49
  `docs/archive/README.md` is the history map. Archive bodies remain targeted historical memory and should not be read broadly by default.
@@ -60,6 +61,7 @@ By default, `docs/spec/**` has two roles: it is stable shared/fresh project memo
60
61
  - `doc-first-planning`
61
62
  - `project-initializer`
62
63
  - `impact-review`
64
+ - `document-clarify`
63
65
 
64
66
  ## Optional Hooks
65
67
 
package/commands/dd/impact.md CHANGED
@@ -4,6 +4,8 @@ argument-hint: [changed path or focus]
4
4
  allowed-tools: [Read, Glob, Grep, Bash]
5
5
  ---
6
6
 
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
+
7
9
  # /dd:impact - Impact Review
8
10
 
9
11
  Review current changes with dotdotgod impact data.
package/commands/dd/init.md CHANGED
@@ -4,6 +4,8 @@ argument-hint: [project-root] [--project-name NAME] [--dotdot-setting] [--force]
4
4
  allowed-tools: [Read, Glob, Grep, Bash]
5
5
  ---
6
6
 
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
+
7
9
  # /dd:init - Initialize Project Memory
8
10
 
9
11
  Initialize or normalize a repository with dotdotgod shared agent docs and docs folders.
package/commands/dd/load.md CHANGED
@@ -4,6 +4,8 @@ argument-hint: [optional focus]
4
4
  allowed-tools: [Read, Glob, Grep, Bash]
5
5
  ---
6
6
 
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
+
7
9
  # /dd:load - Load Project Memory
8
10
 
9
11
  Load the current repository's dotdotgod project memory in a read-only pass.
@@ -27,12 +29,12 @@ Do not modify files during the load pass unless the user explicitly asks for edi
27
29
  - If `dotdotgod` is installed or available in the repository, run `dotdotgod load-snapshot <root> --json`.
28
30
  - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
29
31
  - Treat the snapshot as the first-pass project-memory map for cache status, graph size, 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.
30
- - During load/planning, treat `dotdotgod status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and `index` as bounded context/status helpers. Avoid mutating scaffold/config commands such as `init` or `config init` unless the user explicitly asks for initialization or config creation.
32
+ - 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.
31
33
  - 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.
32
34
  - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
33
35
  - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
34
36
  - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
35
- - Related behavior docs: [load project](../../../docs/spec/LOAD_PROJECT.md), [cross-agent support](../../../docs/spec/CROSS_AGENT_SUPPORT.md), and [cross-agent architecture](../../../docs/arch/CROSS_AGENT_ARCHITECTURE.md).
37
+ - Related behavior docs: `docs/spec/LOAD_PROJECT.md`, `docs/spec/CROSS_AGENT_SUPPORT.md`, and `docs/arch/CROSS_AGENT_ARCHITECTURE.md`.
36
38
  - If the CLI is unavailable, network/package execution is undesirable, or the command fails, continue with the manual README-index fallback below.
37
39
  3. Inspect baseline memory files when present:
38
40
  - `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`
package/commands/dd/plan.md CHANGED
@@ -4,6 +4,8 @@ argument-hint: <task or change request>
4
4
  allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
5
5
  ---
6
6
 
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
+
7
9
  # /dd:plan - Doc-First Planning
8
10
 
9
11
  Create or update a dotdotgod implementation plan before changing source/config files.
@@ -52,9 +54,10 @@ Prefer live repository docs in this order:
52
54
  ```
53
55
 
54
56
  Skip the saved plan for obvious bounded work such as typos, single-file documentation clarifications, targeted test/validation runs, or one-file fixes with an unambiguous implementation path.
55
- 4. Use supporting files in the same task directory only when useful, with UPPER_SNAKE_CASE markdown names such as `RESEARCH_NOTES.md`, `PROGRESS.md`, `DECISIONS.md`, or `VERIFY.md`.
56
- 5. For long-running durable tasks, use concise README sections or optional support files for chronological progress, durable decisions, resume state, and task-specific verification checklists.
57
- 6. When a durable plan is created, include:
57
+ 4. For durable active plans that will be executed, keep the user-facing plan in `docs/plan/<task-slug>/README.md`. If `/plan-generator` staged planning is useful, it may record internal checkpoints under `docs/plan/<task-slug>/.dotdotgod-plan/NN_STAGE_NAME.md`; do not make legacy stage directories such as `01-intake/README.md` the required plan product.
58
+ 5. Use UPPER_SNAKE_CASE support files in the task directory only when they improve resume quality, such as `ROLE_AREA_WORKSTREAMS.md`, `ATOMIC_TASKS.md`, `PROGRESS_LOG.md`, or `VERIFICATION_EVIDENCE.md`.
59
+ 6. For long-running durable tasks, use concise README sections or optional support files for chronological progress, durable decisions, resume state, and task-specific verification checklists. `.dotdotgod-plan/` checkpoints are `/plan-generator` state, not a general Plan Mode requirement.
60
+ 7. When a durable plan is created, include:
58
61
  - scope and current status
59
62
  - target files and rationale
60
63
  - impact-derived related files/checks when available
@@ -64,12 +67,13 @@ Prefer live repository docs in this order:
64
67
  - current resume state when useful
65
68
  - final housekeeping step to move completed work to `docs/archive/plan/<task-slug>/`
66
69
  - for Claude Code/Codex plans, a concrete `dd:impact` or `impact-review` step before broad verification or final handoff when source/config/docs files changed
67
- 7. Update `docs/plan/README.md` if the repository keeps active plan entries there.
68
- 8. Use repository-local package manager evidence for verification commands. In this repository, prefer `pnpm run verify`, `pnpm run pack:dry-run`, and `.husky/pre-push` when applicable.
69
- 9. After creating or updating behavior specs, run project validation when possible. For dotdotgod projects, `dotdotgod validate` enforces machine-readable `json dotdotgod` traceability blocks as the final section in specs. Use `dotdotgod validate --check-index` when you need to confirm markdown fingerprints match the graph index. If validation fails, use the schema, property guidance, and example shown in the validation error to repair the spec.
70
- 10. Stop after presenting the plan unless the user explicitly asks for execution.
71
- 11. During implementation in Claude Code or Codex, use `/dd:impact`, `dd:impact`, or the `impact-review` skill after edits and before broad verification, commits, pushes, publishing, or final handoff.
72
- 12. After implementation and verification, archive completed or superseded plan directories under `docs/archive/plan/<task-slug>/`; remove stale local plan artifacts only when the project policy allows plan/archive housekeeping.
70
+ 8. Before executing a durable active plan, ensure the user has explicitly asked to execute it and resolve any plan-local Discussion Queue items that block execution review. Plan Mode does not require `dotdotgod plan validate` before execution; `/plan-generator` and manual/non-Plan-Mode workflows may still use the CLI plan-validation contract when appropriate.
71
+ 9. Update `docs/plan/README.md` if the repository keeps active plan entries there.
72
+ 10. Use repository-local package manager evidence for verification commands. In this repository, prefer `pnpm run verify`, `pnpm run pack:dry-run`, and `.husky/pre-push` when applicable.
73
+ 11. After creating or updating behavior specs, run project validation when possible. For dotdotgod projects, `dotdotgod validate` enforces machine-readable `json dotdotgod` traceability blocks as the final section in specs. Use `dotdotgod validate --check-index` when you need to confirm markdown fingerprints match the graph index. If validation fails, use the schema, property guidance, and example shown in the validation error to repair the spec.
74
+ 12. Stop after presenting the plan unless the user explicitly asks for execution.
75
+ 13. During implementation in Claude Code or Codex, use `/dd:impact`, `dd:impact`, or the `impact-review` skill after edits and before broad verification, commits, pushes, publishing, or final handoff.
76
+ 14. After implementation and verification, archive completed or superseded plan directories under `docs/archive/plan/<task-slug>/`; remove stale local plan artifacts only when the project policy allows plan/archive housekeeping.
73
77
 
74
78
  ## Quality Rules
75
79
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dotdotgod/claude-code",
3
- "version": "0.1.29",
3
+ "version": "0.1.31",
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/init.md','commands/dd/impact.md','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/project-initializer/SKILL.md','skills/impact-review/SKILL.md','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/init.md','commands/dd/impact.md','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','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')\"",
42
42
  "pack:dry-run": "pnpm pack --dry-run --json"
43
43
  }
44
44
  }
package/skills/doc-first-planning/SKILL.md CHANGED
@@ -4,6 +4,8 @@ description: Use this skill when the user asks Claude Code to plan a feature, re
4
4
  version: 1.0.0
5
5
  ---
6
6
 
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
+
7
9
  # Doc-First Planning
8
10
 
9
11
  ## Goal
@@ -48,9 +50,10 @@ Prefer live repository docs in this order:
48
50
  ```
49
51
 
50
52
  Skip the saved plan for obvious bounded work such as typos, single-file documentation clarifications, targeted test/validation runs, or one-file fixes with an unambiguous implementation path.
51
- 4. Use supporting files in the same task directory only when useful, with UPPER_SNAKE_CASE markdown names such as `RESEARCH_NOTES.md`, `PROGRESS.md`, `DECISIONS.md`, or `VERIFY.md`.
52
- 5. For long-running durable tasks, use concise README sections or optional support files for chronological progress, durable decisions, resume state, and task-specific verification checklists.
53
- 6. When a durable plan is created, include:
53
+ 4. For durable active plans that will be executed, keep the user-facing plan in `docs/plan/<task-slug>/README.md`. If `/plan-generator` staged planning is useful, it may record internal checkpoints under `docs/plan/<task-slug>/.dotdotgod-plan/NN_STAGE_NAME.md`; do not make legacy stage directories such as `01-intake/README.md` the required plan product.
54
+ 5. Use UPPER_SNAKE_CASE support files in the task directory only when they improve resume quality, such as `ROLE_AREA_WORKSTREAMS.md`, `ATOMIC_TASKS.md`, `PROGRESS_LOG.md`, or `VERIFICATION_EVIDENCE.md`.
55
+ 6. For long-running durable tasks, use concise README sections or optional support files for chronological progress, durable decisions, resume state, and task-specific verification checklists. `.dotdotgod-plan/` checkpoints are `/plan-generator` state, not a general Plan Mode requirement.
56
+ 7. When a durable plan is created, include:
54
57
  - scope and current status
55
58
  - target files and rationale
56
59
  - impact-derived related files/checks when available
@@ -60,12 +63,13 @@ Prefer live repository docs in this order:
60
63
  - current resume state when useful
61
64
  - final housekeeping step to move completed work to `docs/archive/plan/<task-slug>/`
62
65
  - for Claude Code/Codex plans, a concrete `dd:impact` or `impact-review` step before broad verification or final handoff when source/config/docs files changed
63
- 7. Update `docs/plan/README.md` if the repository keeps active plan entries there.
64
- 8. Use repository-local package manager evidence for verification commands. In this repository, prefer `pnpm run verify`, `pnpm run pack:dry-run`, and `.husky/pre-push` when applicable.
65
- 9. After creating or updating behavior specs, run project validation when possible. For dotdotgod projects, `dotdotgod validate` enforces machine-readable `json dotdotgod` traceability blocks as the final section in specs. Use `dotdotgod validate --check-index` when you need to confirm markdown fingerprints match the graph index. If validation fails, use the schema, property guidance, and example shown in the validation error to repair the spec.
66
- 10. Stop after presenting the plan unless the user explicitly asks for execution.
67
- 11. During implementation in Claude Code or Codex, use `/dd:impact`, `dd:impact`, or the `impact-review` skill after edits and before broad verification, commits, pushes, publishing, or final handoff.
68
- 12. After implementation and verification, archive completed or superseded plan directories under `docs/archive/plan/<task-slug>/`; remove stale local plan artifacts only when the project policy allows plan/archive housekeeping.
66
+ 8. Before executing a durable active plan, ensure the user has explicitly asked to execute it and resolve any plan-local Discussion Queue items that block execution review. Plan Mode does not require `dotdotgod plan validate` before execution; `/plan-generator` and manual/non-Plan-Mode workflows may still use the CLI plan-validation contract when appropriate.
67
+ 9. Update `docs/plan/README.md` if the repository keeps active plan entries there.
68
+ 10. Use repository-local package manager evidence for verification commands. In this repository, prefer `pnpm run verify`, `pnpm run pack:dry-run`, and `.husky/pre-push` when applicable.
69
+ 11. After creating or updating behavior specs, run project validation when possible. For dotdotgod projects, `dotdotgod validate` enforces machine-readable `json dotdotgod` traceability blocks as the final section in specs. Use `dotdotgod validate --check-index` when you need to confirm markdown fingerprints match the graph index. If validation fails, use the schema, property guidance, and example shown in the validation error to repair the spec.
70
+ 12. Stop after presenting the plan unless the user explicitly asks for execution.
71
+ 13. During implementation in Claude Code or Codex, use `/dd:impact`, `dd:impact`, or the `impact-review` skill after edits and before broad verification, commits, pushes, publishing, or final handoff.
72
+ 14. After implementation and verification, archive completed or superseded plan directories under `docs/archive/plan/<task-slug>/`; remove stale local plan artifacts only when the project policy allows plan/archive housekeeping.
69
73
 
70
74
  ## Quality Rules
71
75
 
package/skills/document-clarify/SKILL.md ADDED
@@ -0,0 +1,116 @@
1
+ ---
2
+ name: document-clarify
3
+ description: Use this skill when Claude Code should clarify project documentation using dotdotgod memory-area metadata, default document roles, and docs-as-code clarity rules; when README indexes, docs/spec, docs/test, docs/arch, docs/plan, docs/archive, or project-specific docs need clearer wording without changing behavior contracts.
4
+ version: 1.0.0
5
+ ---
6
+
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
+
9
+ # Document Clarify
10
+
11
+ ## Goal
12
+
13
+ Improve project documentation clarity without changing the document's role, behavior contract, traceability semantics, or project-specific memory intent.
14
+
15
+ Use this workflow for README indexes, specs, test docs, architecture docs, active plans, archive maps, and custom documentation areas configured through dotdotgod memory-area policy.
16
+
17
+ ## Source Order
18
+
19
+ Prefer live repository context in this order:
20
+
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.
24
+ 4. The nearest README index, especially `docs/README.md` and the local area `README.md`.
25
+ 5. Directly linked specs, tests, architecture notes, commands, and traceability targets needed to preserve meaning.
26
+ 6. `docs/archive/README.md` as the history map; read archive bodies only when the current clarification task needs a targeted past decision.
27
+
28
+ If the CLI is unavailable, continue from README indexes, path conventions, and traceability blocks.
29
+
30
+ ## Resolve the Document Role
31
+
32
+ Before editing, decide what job the document is supposed to do.
33
+
34
+ For configured memory areas, apply guidance in this order:
35
+
36
+ 1. Matched area's `clarify` guidance:
37
+ - `audience`: who must understand the document.
38
+ - `documentType`: recommended type such as index, tutorial, how-to, reference, explanation, spec, test strategy, architecture note, runbook, plan, archive map, or archive body.
39
+ - `clarityGoal`: the north star for edits.
40
+ - `editRules`: local constraints that must be preserved.
41
+ 2. Matched area's `description`, `label`, and `role`.
42
+ 3. Default dotdotgod roles:
43
+ - `AGENTS.md`: canonical working rules.
44
+ - `CLAUDE.md` and `CODEX.md`: thin agent-specific entrypoints.
45
+ - root `README.md`: project map and start path.
46
+ - `docs/README.md` and area README files: routing maps and next actions.
47
+ - `docs/spec/**`: behavior contracts and acceptance criteria.
48
+ - `docs/test/**`: verification strategy, regression coverage, fixtures, and commands.
49
+ - `docs/arch/**`: rationale, boundaries, implementation constraints, data flow, and integration decisions.
50
+ - `docs/plan/**`: active task intent, decisions, risks, verification, and resume state.
51
+ - `docs/archive/README.md`: history map.
52
+ - `docs/archive/**`: targeted historical body, not a default reading surface.
53
+
54
+ Treat custom memory-area metadata as project policy. If custom guidance conflicts with current document content or would change product meaning, surface the conflict and ask before rewriting semantics.
55
+
56
+ ## Assess Clarity Problems
57
+
58
+ Look for problems that prevent first-time developers, contributors, or AI coding agents from understanding and acting correctly:
59
+
60
+ - unclear purpose or missing opening context
61
+ - missing next action or command boundary
62
+ - jargon without definition or link
63
+ - ambiguous terms, inconsistent naming, or overloaded concepts
64
+ - passive or indirect wording that hides who does what
65
+ - excessive background before the task or contract
66
+ - duplicated headings and intros that repeat without adding value
67
+ - weak information scent in links, headings, and README routes
68
+ - examples that are not runnable or are disconnected from the described behavior
69
+ - mixed document roles, such as specs becoming implementation plans or architecture notes becoming tutorials
70
+
71
+ Use plain language, active voice, descriptive links, global-audience wording, and concise sections. Keep exact commands, paths, package names, API names, and behavior claims unless verified evidence supports a change.
72
+
73
+ ## Edit Safely
74
+
75
+ - Preserve the document's role. Do not turn specs into tutorials, tests into product promises, architecture into task plans, plans into permanent specs, or archives into broad default reading surfaces.
76
+ - Put action guidance before internal model details when the audience needs a next step first.
77
+ - Use the same term for the same concept throughout the document.
78
+ - Split or route deep background to focused docs instead of making README indexes dense.
79
+ - For behavior specs, do not weaken MUST/SHOULD requirements or acceptance criteria under the guise of copy edits.
80
+ - For test docs, clarify what is covered and how to verify it; do not invent behavior requirements.
81
+ - For architecture docs, clarify boundaries, constraints, and rationale; do not add unapproved implementation work.
82
+ - For plans, preserve scope, decisions, verification notes, current status, and resume context.
83
+
84
+ ## Traceability and Generated Content
85
+
86
+ - Treat the fenced `json dotdotgod` block as canonical traceability data.
87
+ - Do not manually edit generated `<!-- dotdotgod:traceability-links:* -->` sections.
88
+ - If traceability mappings need to change, edit the canonical JSON block and run `dotdotgod traceability links <root> --write`.
89
+ - Keep generated links and compact JSON synchronized before final validation.
90
+ - Do not directly maintain generated adapter skill bodies. Edit shared workflow files and `scripts/generate-adapters.mjs`, then run `pnpm run generate`.
91
+
92
+ ## Verification
93
+
94
+ After documentation edits, run checks that match the changed surface:
95
+
96
+ ```bash
97
+ node packages/cli/bin/dotdotgod.mjs traceability links . --check --json
98
+ node packages/cli/bin/dotdotgod.mjs validate . --include-local-memory --check-index
99
+ ```
100
+
101
+ If validation reports index drift, run:
102
+
103
+ ```bash
104
+ node packages/cli/bin/dotdotgod.mjs index . --json
105
+ node packages/cli/bin/dotdotgod.mjs validate . --include-local-memory --check-index
106
+ ```
107
+
108
+ When shared workflow text, generated adapter resources, package metadata, or cross-agent docs change, also run:
109
+
110
+ ```bash
111
+ pnpm run generate
112
+ pnpm run verify:generated
113
+ pnpm run verify
114
+ ```
115
+
116
+ Use focused package tests or package dry-runs when package resources or CLI config behavior changed.
package/skills/document-clarify/agents/openai.yaml ADDED
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Document Clarify"
3
+ short_description: "Clarify dotdotgod project documentation."
4
+ default_prompt: "Clarify the target docs using dotdotgod memory-area metadata, default document roles, and docs-as-code clarity rules while preserving behavior contracts."
package/skills/impact-review/SKILL.md CHANGED
@@ -4,6 +4,8 @@ description: Use this skill when Claude Code should review changed files with do
4
4
  version: 1.0.0
5
5
  ---
6
6
 
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
+
7
9
  # Impact Review
8
10
 
9
11
  ## Goal
package/skills/project-initializer/SKILL.md CHANGED
@@ -4,6 +4,8 @@ description: Use this skill when Claude Code is asked to initialize or normalize
4
4
  version: 1.0.0
5
5
  ---
6
6
 
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
+
7
9
  # Project Initializer
8
10
 
9
11
  ## Overview
package/skills/project-load/SKILL.md CHANGED
@@ -4,6 +4,8 @@ description: Use this skill when the user asks Claude Code to load, refresh, ins
4
4
  version: 1.0.0
5
5
  ---
6
6
 
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
+
7
9
  # Project Load
8
10
 
9
11
  ## Goal
@@ -23,12 +25,12 @@ Do not modify files during the load pass unless the user explicitly asks for edi
23
25
  - If `dotdotgod` is installed or available in the repository, run `dotdotgod load-snapshot <root> --json`.
24
26
  - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
25
27
  - Treat the snapshot as the first-pass project-memory map for cache status, graph size, 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.
26
- - During load/planning, treat `dotdotgod status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and `index` as bounded context/status helpers. Avoid mutating scaffold/config commands such as `init` or `config init` unless the user explicitly asks for initialization or config creation.
28
+ - 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.
27
29
  - 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.
28
30
  - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
29
31
  - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
30
32
  - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
31
- - Related behavior docs: [load project](../../../docs/spec/LOAD_PROJECT.md), [cross-agent support](../../../docs/spec/CROSS_AGENT_SUPPORT.md), and [cross-agent architecture](../../../docs/arch/CROSS_AGENT_ARCHITECTURE.md).
33
+ - Related behavior docs: `docs/spec/LOAD_PROJECT.md`, `docs/spec/CROSS_AGENT_SUPPORT.md`, and `docs/arch/CROSS_AGENT_ARCHITECTURE.md`.
32
34
  - If the CLI is unavailable, network/package execution is undesirable, or the command fails, continue with the manual README-index fallback below.
33
35
  3. Inspect baseline memory files when present:
34
36
  - `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`