@dotdotgod/claude-code 0.1.29 → 0.1.30

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dotdotgod",
-  "description": "Dotdotgod project memory workflows for Claude Code: initialize shared docs, load project memory, plan doc-first, and review graph impact.",
+  "description": "Dotdotgod project memory workflows for Claude Code: initialize shared docs, load project memory, plan doc-first, review graph impact, and clarify documentation.",
   "author": {
     "name": "dotdotgod"
   }

package/README.md

@@ -25,7 +25,7 @@ files:
 
 `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.
 
-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.
+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.
 
 ## What Gets Better?
 
@@ -35,14 +35,15 @@ Claude Code adapter for dotdotgod's context curation workflow. It packages `/dd:
 - Planning guidance encourages agents to keep README routes, traceability blocks, plans, and archives current so `graph impact` remains useful.
 - `/dd:plan` writes or updates durable task intent in `docs/plan/<task-slug>/README.md` before implementation.
 - `/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.
+- `document-clarify` improves project docs using memory-area roles and optional config guidance while preserving behavior contracts.
 - Product intent, design rationale, verification standards, and completed work stay in durable files rather than chat history.
-- Skills mirror the commands so natural-language requests can use the same workflows.
+- Skills mirror the command workflows for init/load/plan/impact, and `document-clarify` adds a skill-only docs clarity workflow.
 
 ## Shared Memory and Traceability Model
 
 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:
 
-- `memory.areas` customizes memory classification, freshness, local/shared scope, priorities, and archive-body inclusion.
+- `memory.areas` customizes memory classification, freshness, local/shared scope, priorities, archive-body inclusion, and optional document-area `description`/`clarify` guidance.
 - `traceability.required` / `traceability.exclude` customizes which markdown paths must end with `json dotdotgod` blocks.
 
 `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
   - `doc-first-planning`
   - `project-initializer`
   - `impact-review`
+  - `document-clarify`
 
 ## Optional Hooks
 

package/commands/dd/impact.md

@@ -4,6 +4,8 @@ argument-hint: [changed path or focus]
 allowed-tools: [Read, Glob, Grep, Bash]
 ---
 
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
 # /dd:impact - Impact Review
 
 Review current changes with dotdotgod impact data.

package/commands/dd/init.md

@@ -4,6 +4,8 @@ argument-hint: [project-root] [--project-name NAME] [--dotdot-setting] [--force]
 allowed-tools: [Read, Glob, Grep, Bash]
 ---
 
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
 # /dd:init - Initialize Project Memory
 
 Initialize or normalize a repository with dotdotgod shared agent docs and docs folders.

package/commands/dd/load.md

@@ -4,6 +4,8 @@ argument-hint: [optional focus]
 allowed-tools: [Read, Glob, Grep, Bash]
 ---
 
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
 # /dd:load - Load Project Memory
 
 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
    - If `dotdotgod` is installed or available in the repository, run `dotdotgod load-snapshot <root> --json`.
    - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
    - Treat the snapshot as the first-pass project-memory map for cache 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.
-   - 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.
+   - During load/planning, treat `dotdotgod status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and `index` as bounded context/status helpers. `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, and `index` are project-content safe but may refresh ignored `.dotdotgod/` cache metadata. Avoid mutating scaffold/config commands such as `init` or `config init` unless the user explicitly asks for initialization or config creation.
    - Use `dotdotgod graph impact <root> --changed <path> --yml` as a task-focused structured impact map when the user identifies a likely source/config/doc file. In Claude Code, `/dd:impact` can run the same review; in Codex, `dd:impact` is the command-like trigger for the `impact-review` skill.
    - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
    - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
    - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
-   - Related behavior docs: [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).
+   - Related behavior docs: `docs/spec/LOAD_PROJECT.md`, `docs/spec/CROSS_AGENT_SUPPORT.md`, and `docs/arch/CROSS_AGENT_ARCHITECTURE.md`.
    - If the CLI is unavailable, network/package execution is undesirable, or the command fails, continue with the manual README-index fallback below.
 3. Inspect baseline memory files when present:
    - `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`

package/commands/dd/plan.md

@@ -4,6 +4,8 @@ argument-hint: <task or change request>
 allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
 ---
 
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
 # /dd:plan - Doc-First Planning
 
 Create or update a dotdotgod implementation plan before changing source/config files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/claude-code",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "Claude Code adapter for dotdotgod project memory workflows.",
   "type": "module",
   "license": "Elastic-2.0",
@@ -38,7 +38,7 @@
     "url": "https://github.com/dotdotgod/dotdotgod-kit/issues"
   },
   "scripts": {
-    "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')\"",
+    "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')\"",
     "pack:dry-run": "pnpm pack --dry-run --json"
   }
 }

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

@@ -4,6 +4,8 @@ description: Use this skill when the user asks Claude Code to plan a feature, re
 version: 1.0.0
 ---
 
+<!-- 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`. -->
+
 # Doc-First Planning
 
 ## Goal

package/skills/document-clarify/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: document-clarify
+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.
+version: 1.0.0
+---
+
+<!-- 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`. -->
+
+# Document Clarify
+
+## Goal
+
+Improve project documentation clarity without changing the document's role, behavior contract, traceability semantics, or project-specific memory intent.
+
+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.
+
+## Source Order
+
+Prefer live repository context in this order:
+
+1. The user's target file or requested documentation area.
+2. Resolved dotdotgod memory-area metadata from `dotdotgod load-snapshot <root> --json` when available.
+3. Resolved config from `dotdotgod config <root> --json` when a snapshot is unavailable or stale.
+4. The nearest README index, especially `docs/README.md` and the local area `README.md`.
+5. Directly linked specs, tests, architecture notes, commands, and traceability targets needed to preserve meaning.
+6. `docs/archive/README.md` as the history map; read archive bodies only when the current clarification task needs a targeted past decision.
+
+If the CLI is unavailable, continue from README indexes, path conventions, and traceability blocks.
+
+## Resolve the Document Role
+
+Before editing, decide what job the document is supposed to do.
+
+For configured memory areas, apply guidance in this order:
+
+1. Matched area's `clarify` guidance:
+   - `audience`: who must understand the document.
+   - `documentType`: recommended type such as index, tutorial, how-to, reference, explanation, spec, test strategy, architecture note, runbook, plan, archive map, or archive body.
+   - `clarityGoal`: the north star for edits.
+   - `editRules`: local constraints that must be preserved.
+2. Matched area's `description`, `label`, and `role`.
+3. Default dotdotgod roles:
+   - `AGENTS.md`: canonical working rules.
+   - `CLAUDE.md` and `CODEX.md`: thin agent-specific entrypoints.
+   - root `README.md`: project map and start path.
+   - `docs/README.md` and area README files: routing maps and next actions.
+   - `docs/spec/**`: behavior contracts and acceptance criteria.
+   - `docs/test/**`: verification strategy, regression coverage, fixtures, and commands.
+   - `docs/arch/**`: rationale, boundaries, implementation constraints, data flow, and integration decisions.
+   - `docs/plan/**`: active task intent, decisions, risks, verification, and resume state.
+   - `docs/archive/README.md`: history map.
+   - `docs/archive/**`: targeted historical body, not a default reading surface.
+
+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.
+
+## Assess Clarity Problems
+
+Look for problems that prevent first-time developers, contributors, or AI coding agents from understanding and acting correctly:
+
+- unclear purpose or missing opening context
+- missing next action or command boundary
+- jargon without definition or link
+- ambiguous terms, inconsistent naming, or overloaded concepts
+- passive or indirect wording that hides who does what
+- excessive background before the task or contract
+- duplicated headings and intros that repeat without adding value
+- weak information scent in links, headings, and README routes
+- examples that are not runnable or are disconnected from the described behavior
+- mixed document roles, such as specs becoming implementation plans or architecture notes becoming tutorials
+
+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.
+
+## Edit Safely
+
+- 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.
+- Put action guidance before internal model details when the audience needs a next step first.
+- Use the same term for the same concept throughout the document.
+- Split or route deep background to focused docs instead of making README indexes dense.
+- For behavior specs, do not weaken MUST/SHOULD requirements or acceptance criteria under the guise of copy edits.
+- For test docs, clarify what is covered and how to verify it; do not invent behavior requirements.
+- For architecture docs, clarify boundaries, constraints, and rationale; do not add unapproved implementation work.
+- For plans, preserve scope, decisions, verification notes, current status, and resume context.
+
+## Traceability and Generated Content
+
+- Treat the fenced `json dotdotgod` block as canonical traceability data.
+- Do not manually edit generated `<!-- dotdotgod:traceability-links:* -->` sections.
+- If traceability mappings need to change, edit the canonical JSON block and run `dotdotgod traceability links <root> --write`.
+- Keep generated links and compact JSON synchronized before final validation.
+- Do not directly maintain generated adapter skill bodies. Edit shared workflow files and `scripts/generate-adapters.mjs`, then run `pnpm run generate`.
+
+## Verification
+
+After documentation edits, run checks that match the changed surface:
+
+```bash
+node packages/cli/bin/dotdotgod.mjs traceability links . --check --json
+node packages/cli/bin/dotdotgod.mjs validate . --include-local-memory --check-index
+```
+
+If validation reports index drift, run:
+
+```bash
+node packages/cli/bin/dotdotgod.mjs index . --json
+node packages/cli/bin/dotdotgod.mjs validate . --include-local-memory --check-index
+```
+
+When shared workflow text, generated adapter resources, package metadata, or cross-agent docs change, also run:
+
+```bash
+pnpm run generate
+pnpm run verify:generated
+pnpm run verify
+```
+
+Use focused package tests or package dry-runs when package resources or CLI config behavior changed.

package/skills/document-clarify/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Document Clarify"
+  short_description: "Clarify dotdotgod project documentation."
+  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

@@ -4,6 +4,8 @@ description: Use this skill when Claude Code should review changed files with do
 version: 1.0.0
 ---
 
+<!-- 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`. -->
+
 # Impact Review
 
 ## Goal

package/skills/project-initializer/SKILL.md

@@ -4,6 +4,8 @@ description: Use this skill when Claude Code is asked to initialize or normalize
 version: 1.0.0
 ---
 
+<!-- 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`. -->
+
 # Project Initializer
 
 ## Overview

package/skills/project-load/SKILL.md

@@ -4,6 +4,8 @@ description: Use this skill when the user asks Claude Code to load, refresh, ins
 version: 1.0.0
 ---
 
+<!-- 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`. -->
+
 # Project Load
 
 ## Goal
@@ -23,12 +25,12 @@ Do not modify files during the load pass unless the user explicitly asks for edi
    - If `dotdotgod` is installed or available in the repository, run `dotdotgod load-snapshot <root> --json`.
    - If the local environment allows package execution but no `dotdotgod` binary is available, optionally run `npx @dotdotgod/cli load-snapshot <root> --json`.
    - Treat the snapshot as the first-pass project-memory map for cache 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.
-   - 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.
+   - During load/planning, treat `dotdotgod status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and `index` as bounded context/status helpers. `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, and `index` are project-content safe but may refresh ignored `.dotdotgod/` cache metadata. Avoid mutating scaffold/config commands such as `init` or `config init` unless the user explicitly asks for initialization or config creation.
    - Use `dotdotgod graph impact <root> --changed <path> --yml` as a task-focused structured impact map when the user identifies a likely source/config/doc file. In Claude Code, `/dd:impact` can run the same review; in Codex, `dd:impact` is the command-like trigger for the `impact-review` skill.
    - Use `grep` or `find` after `expand`, impact, and targeted reads when the task needs fallback discovery or raw source text search.
    - Fall back to raw `dotdotgod graph impact <root> --changed <path> --json` only when diagnostics need the full payload.
    - When graph impact surfaces traceability relations, inspect the related specs, tests, and docs before editing source.
-   - Related behavior docs: [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).
+   - Related behavior docs: `docs/spec/LOAD_PROJECT.md`, `docs/spec/CROSS_AGENT_SUPPORT.md`, and `docs/arch/CROSS_AGENT_ARCHITECTURE.md`.
    - If the CLI is unavailable, network/package execution is undesirable, or the command fails, continue with the manual README-index fallback below.
 3. Inspect baseline memory files when present:
    - `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`