@dotdotgod/claude-code 0.1.30 → 0.1.40
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.
- package/README.md +42 -66
- package/commands/dd/plan.md +11 -9
- package/package.json +1 -1
- package/skills/doc-first-planning/SKILL.md +11 -9
package/README.md
CHANGED
|
@@ -2,91 +2,67 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@dotdotgod/claude-code) [](https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/claude-code) [](../../LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Claude Code adapter for dotdotgod's docs-first project-memory workflow.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
```text
|
|
12
|
-
docs:
|
|
13
|
-
- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
|
|
14
|
-
- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)
|
|
15
|
-
- docs/spec/LOAD_PROJECT.md (35.8; related_doc, semantic_similarity)
|
|
16
|
-
|
|
17
|
-
tests:
|
|
18
|
-
- packages/cli/test/core.test.mjs (78.6; semantic_similarity, incoming:semantic_similarity, verified_by)
|
|
19
|
-
- packages/cli/test/e2e.test.mjs (51.4; verified_by)
|
|
20
|
-
|
|
21
|
-
files:
|
|
22
|
-
- packages/cli/src/core.mjs (100; changed-file)
|
|
23
|
-
- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
|
|
24
|
-
```
|
|
25
|
-
|
|
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
|
-
|
|
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.
|
|
7
|
+
Use this package when you want Claude Code to initialize shared project docs, load bounded repository context, plan from durable docs before implementation, and review changed files with graph-impact evidence before handoff.
|
|
29
8
|
|
|
30
|
-
##
|
|
9
|
+
## Start Here
|
|
31
10
|
|
|
32
|
-
|
|
33
|
-
- `/dd:load` prefers `dotdotgod load-snapshot <root> --json` when the CLI is available, then falls back to README-index reads.
|
|
34
|
-
- Claude Code can use docs structure as retrieval intent: specs for behavior, architecture for rationale, tests for verification, plans for current work, and archive indexes for past decisions.
|
|
35
|
-
- Planning guidance encourages agents to keep README routes, traceability blocks, plans, and archives current so `graph impact` remains useful.
|
|
36
|
-
- `/dd:plan` writes or updates durable task intent in `docs/plan/<task-slug>/README.md` before implementation.
|
|
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.
|
|
39
|
-
- Product intent, design rationale, verification standards, and completed work stay in durable files rather than chat history.
|
|
40
|
-
- Skills mirror the command workflows for init/load/plan/impact, and `document-clarify` adds a skill-only docs clarity workflow.
|
|
11
|
+
Install or register this package as a Claude Code plugin, then use the bundled `/dd:*` commands in your repository:
|
|
41
12
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
`docs/archive/README.md` is the history map. Archive bodies remain targeted historical memory and should not be read broadly by default.
|
|
13
|
+
```text
|
|
14
|
+
/dd:init
|
|
15
|
+
/dd:load
|
|
16
|
+
/dd:plan Update the API migration plan.
|
|
17
|
+
/dd:impact
|
|
18
|
+
```
|
|
50
19
|
|
|
51
|
-
|
|
20
|
+
For local development from this checkout:
|
|
52
21
|
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
-
|
|
56
|
-
- `/dd:load`: load project memory read-only.
|
|
57
|
-
- `/dd:plan`: plan from docs before implementation.
|
|
58
|
-
- `/dd:impact`: review current changes with dotdotgod graph-impact evidence before broad verification or handoff.
|
|
59
|
-
- Skills:
|
|
60
|
-
- `project-load`
|
|
61
|
-
- `doc-first-planning`
|
|
62
|
-
- `project-initializer`
|
|
63
|
-
- `impact-review`
|
|
64
|
-
- `document-clarify`
|
|
22
|
+
```bash
|
|
23
|
+
claude --plugin-dir /path/to/dotdotgod/packages/claude-code
|
|
24
|
+
```
|
|
65
25
|
|
|
66
|
-
##
|
|
26
|
+
## What It Adds to Claude Code
|
|
67
27
|
|
|
68
|
-
|
|
28
|
+
| Command or skill | Use it for | Result |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| `/dd:init` | Start a repository with dotdotgod conventions. | Creates or normalizes `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, and archive map. |
|
|
31
|
+
| `/dd:load` | Load project memory read-only. | Prefers `dotdotgod load-snapshot <root> --json`, then falls back to README-index reads. |
|
|
32
|
+
| `/dd:plan` | Plan before implementation. | Writes or updates durable task intent in `docs/plan/<task-slug>/README.md`. |
|
|
33
|
+
| `/dd:impact` | Review changed files before verification or handoff. | Uses `dotdotgod graph impact` to identify likely related docs, tests, commands, and source files. |
|
|
34
|
+
| `document-clarify` | Improve docs wording without changing behavior contracts. | Clarifies README/spec/test/arch/plan/archive docs using memory-area roles. |
|
|
69
35
|
|
|
70
|
-
|
|
36
|
+
The package also includes matching skills for init, load, planning, and impact-review workflows.
|
|
71
37
|
|
|
72
|
-
## Shared Contract
|
|
38
|
+
## Shared Project-Memory Contract
|
|
73
39
|
|
|
74
40
|
- `AGENTS.md` remains canonical.
|
|
75
41
|
- `CLAUDE.md` stays thin and imports or points to `AGENTS.md`.
|
|
42
|
+
- Specs describe behavior and requirements.
|
|
43
|
+
- Architecture docs explain rationale, boundaries, and conventions.
|
|
44
|
+
- Test docs explain verification strategy, regression coverage, fixtures, and commands.
|
|
76
45
|
- Active plans use `docs/plan/<task-slug>/README.md`.
|
|
77
46
|
- Completed plans move to `docs/archive/plan/<task-slug>/`.
|
|
78
47
|
- Temporary reports move to `docs/archive/report/<report-slug>/`.
|
|
79
48
|
- `docs/archive/README.md` is the archive map; archive bodies should be read only when targeted.
|
|
80
49
|
|
|
81
|
-
##
|
|
50
|
+
## Memory Areas and Traceability
|
|
82
51
|
|
|
83
|
-
|
|
52
|
+
By default, `docs/spec/**` has two separate roles:
|
|
84
53
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
```
|
|
54
|
+
- It is stable shared project memory for product behavior and requirements.
|
|
55
|
+
- It is the traceability-enforced path for behavior specs.
|
|
88
56
|
|
|
89
|
-
|
|
57
|
+
Projects can customize memory roles with `memory.areas`, and can customize traceability requirements with `traceability.required` and `traceability.exclude`.
|
|
58
|
+
|
|
59
|
+
## Optional Hooks
|
|
60
|
+
|
|
61
|
+
Claude Code can run local lifecycle hooks from Claude settings. dotdotgod does not require hooks: `/dd:init`, `/dd:load`, `/dd:plan`, `/dd:impact`, and the bundled skills work without them.
|
|
62
|
+
|
|
63
|
+
Use hooks only when you want opt-in reminders, validation, or local safety rails around the same loop: plan, implement, impact-review, verify, review, and archive. See [`hooks/README.md`](hooks/README.md) for current lifecycle notes and advisory examples.
|
|
64
|
+
|
|
65
|
+
## Local Development
|
|
90
66
|
|
|
91
67
|
```bash
|
|
92
68
|
pnpm --filter @dotdotgod/claude-code run verify
|
|
@@ -95,8 +71,8 @@ pnpm --filter @dotdotgod/claude-code run pack:dry-run
|
|
|
95
71
|
|
|
96
72
|
## Learn More
|
|
97
73
|
|
|
98
|
-
See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod-kit), [
|
|
74
|
+
See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod-kit), [Context curation](../../docs/concept/CONTEXT_CURATION.md), [Context mechanics](../../docs/concept/CONTEXT_MECHANICS.md), [Memory area config](../../docs/spec/MEMORY_AREA_CONFIG.md), and [Traceability config](../../docs/spec/TRACEABILITY_CONFIG.md).
|
|
99
75
|
|
|
100
76
|
## Compared with Graphify-Style Memory
|
|
101
77
|
|
|
102
|
-
This adapter is guidance-oriented. It asks Claude Code to prefer a bounded dotdotgod load snapshot
|
|
78
|
+
This adapter is guidance-oriented. It asks Claude Code to prefer a bounded dotdotgod load snapshot, avoid broad archive scans, and follow README indexes before reading raw files. The strength is structured retrieval from explicit project-maintained links, not a giant graph report.
|
package/commands/dd/plan.md
CHANGED
|
@@ -54,9 +54,10 @@ Prefer live repository docs in this order:
|
|
|
54
54
|
```
|
|
55
55
|
|
|
56
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.
|
|
57
|
-
4.
|
|
58
|
-
5.
|
|
59
|
-
6.
|
|
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:
|
|
60
61
|
- scope and current status
|
|
61
62
|
- target files and rationale
|
|
62
63
|
- impact-derived related files/checks when available
|
|
@@ -66,12 +67,13 @@ Prefer live repository docs in this order:
|
|
|
66
67
|
- current resume state when useful
|
|
67
68
|
- final housekeeping step to move completed work to `docs/archive/plan/<task-slug>/`
|
|
68
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
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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.
|
|
75
77
|
|
|
76
78
|
## Quality Rules
|
|
77
79
|
|
package/package.json
CHANGED
|
@@ -50,9 +50,10 @@ Prefer live repository docs in this order:
|
|
|
50
50
|
```
|
|
51
51
|
|
|
52
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.
|
|
53
|
-
4.
|
|
54
|
-
5.
|
|
55
|
-
6.
|
|
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:
|
|
56
57
|
- scope and current status
|
|
57
58
|
- target files and rationale
|
|
58
59
|
- impact-derived related files/checks when available
|
|
@@ -62,12 +63,13 @@ Prefer live repository docs in this order:
|
|
|
62
63
|
- current resume state when useful
|
|
63
64
|
- final housekeeping step to move completed work to `docs/archive/plan/<task-slug>/`
|
|
64
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
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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.
|
|
71
73
|
|
|
72
74
|
## Quality Rules
|
|
73
75
|
|