@dotdotgod/claude-code 0.1.21

package/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "dotdotgod",
+  "description": "Dotdotgod project memory workflows for Claude Code: initialize shared docs, load project memory, and plan implementation work doc-first.",
+  "author": {
+    "name": "dotdotgod"
+  }
+}

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2026 JooYoung Kim
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these
+terms after such reinstatement, any additional violation of these terms will
+cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,97 @@
+# @dotdotgod/claude-code
+
+[![npm version](https://img.shields.io/npm/v/@dotdotgod/claude-code.svg)](https://www.npmjs.com/package/@dotdotgod/claude-code) [![GitHub](https://img.shields.io/badge/GitHub-dotdotgod%2Fdotdotgod-kit-181717?logo=github)](https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/claude-code) [![License: Elastic 2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](../../LICENSE)
+
+> **Change a file, know what else must be checked.**
+
+```bash
+$ dotdotgod graph impact . --changed packages/cli/src/core.mjs --compact
+```
+
+```text
+docs:
+- docs/spec/REFERENCE_EXPANSION.md (91; incoming:implemented_by, semantic_similarity)
+- docs/test/REFERENCE_EXPANSION.md (65.3; verified_by, semantic_similarity)
+- docs/spec/LOAD_PROJECT.md (35.8; related_doc, semantic_similarity)
+
+tests:
+- packages/cli/test/core.test.mjs (78.6; semantic_similarity, incoming:semantic_similarity, verified_by)
+- packages/cli/test/e2e.test.mjs (51.4; verified_by)
+
+files:
+- packages/cli/src/core.mjs (100; changed-file)
+- packages/pi/extensions/plan-mode/index.ts (45; implemented_by, semantic_similarity)
+```
+
+`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`, 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.
+
+## What Gets Better?
+
+- `/dd:init` bootstraps shared agent instructions and docs folders for future context curation.
+- `/dd:load` prefers `dotdotgod load-snapshot <root> --json` when the CLI is available, then falls back to README-index reads.
+- 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.
+- 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.
+- 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.
+
+## 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.
+- `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.
+
+## Included
+
+- Claude Code plugin manifest: `.claude-plugin/plugin.json`
+- Slash commands:
+  - `/dd:init`: initialize shared agent docs and docs folders, using `dotdotgod init` when available and the bundled fallback when not.
+  - `/dd:load`: load project memory read-only.
+  - `/dd:plan`: plan from docs before implementation.
+- Skills:
+  - `project-load`
+  - `doc-first-planning`
+  - `project-initializer`
+
+## Optional Hooks
+
+Claude Code can run local lifecycle hooks from Claude settings. dotdotgod does not require hooks: `/dd:init`, `/dd:load`, `/dd:plan`, and the bundled skills work without them.
+
+Use hooks only when you want opt-in reminders, validation, or local safety rails around the same SDLC loop: plan, implement, verify, review, and archive. The hook surface changes over time, so examples stay advisory and avoid claiming unavailable plan-mode transition hooks. See [`hooks/README.md`](hooks/README.md) for current lifecycle notes, advisory examples, and stricter plan-safety patterns.
+
+## Shared Contract
+
+- `AGENTS.md` remains canonical.
+- `CLAUDE.md` stays thin and imports or points to `AGENTS.md`.
+- Active plans use `docs/plan/<task-slug>/README.md`.
+- Completed plans move to `docs/archive/plan/<task-slug>/`.
+- Temporary reports move to `docs/archive/report/<report-slug>/`.
+- `docs/archive/README.md` is the archive map; archive bodies should be read only when targeted.
+
+## Local Development
+
+Use the package as a local Claude Code plugin directory while developing:
+
+```bash
+claude --plugin-dir /Users/dotdot/Workspace/dotdotgod/packages/claude-code
+```
+
+Run package checks:
+
+```bash
+pnpm --filter @dotdotgod/claude-code run verify
+pnpm --filter @dotdotgod/claude-code run pack:dry-run
+```
+
+## Learn More
+
+See the [root README](../../README.md), [GitHub repository](https://github.com/dotdotgod/dotdotgod-kit), [`docs/concept/CONTEXT_CURATION.md`](../../docs/concept/CONTEXT_CURATION.md), [`docs/concept/CONTEXT_MECHANICS.md`](../../docs/concept/CONTEXT_MECHANICS.md), [`docs/spec/MEMORY_AREA_CONFIG.md`](../../docs/spec/MEMORY_AREA_CONFIG.md), and [`docs/spec/TRACEABILITY_CONFIG.md`](../../docs/spec/TRACEABILITY_CONFIG.md).
+
+## Compared with Graphify-Style Memory
+
+This adapter is guidance-oriented. It asks Claude Code to prefer a bounded dotdotgod load snapshot when available, avoid broad archive scans, and follow README indexes before reading raw files. The strength is structured retrieval from explicit project-maintained links and the fixed docs surface, not a giant graph report.

package/commands/dd/init.md

@@ -0,0 +1,71 @@
+---
+description: Initialize dotdotgod shared agent docs and documentation scaffold
+argument-hint: [project-root] [--project-name NAME] [--dotdot-setting] [--force] [--dry-run]
+allowed-tools: [Read, Glob, Grep, Bash]
+---
+
+# /dd:init - Initialize Project Memory
+
+Initialize or normalize a repository with dotdotgod shared agent docs and docs folders.
+
+Arguments: `$ARGUMENTS`
+
+## Overview
+
+Create a conservative dotdotgod project baseline that multiple AI coding agents can share:
+
+- `AGENTS.md` is the canonical project instruction file.
+- `CLAUDE.md` imports `AGENTS.md` for Claude Code.
+- `CODEX.md` points Codex users to `AGENTS.md`.
+- `docs/` contains `spec`, `test`, `arch`, `plan`, and `archive` areas with concise README files.
+- `docs/arch/` covers architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
+- 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.
+- 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.
+- Under `docs/`, all directories use kebab-case and all markdown file names use UPPER_SNAKE_CASE, including `README.md`.
+- `docs/plan/<task-slug>/README.md` is the default shape for active plan work.
+- Completed plans move to `docs/archive/plan/<task-slug>/`.
+- Temporary reports and investigations move to `docs/archive/report/<report-slug>/`.
+- `.gitignore` includes `docs/plan`, `docs/archive`, and `.dotdotgod` so local memory and the graph cache stay local by default.
+
+Use the dotdotgod CLI initializer when it is already available in the target environment:
+
+```bash
+dotdotgod init <project-root>
+```
+
+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:
+
+```bash
+sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>
+```
+
+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.
+
+Use `--dry-run` before touching an unfamiliar repository. Use `--dotdot-setting` when the user wants dotdot code conventions generated under `docs/arch/CODE_CONVENTIONS.md` and referenced from `AGENTS.md`. Use `--force` only when explicitly requested; it creates timestamped backups before replacing files.
+
+## Workflow
+
+1. Inspect the target project root.
+   - Check for existing `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, and `docs/`.
+   - Preserve project-specific instructions unless the user asks to replace them.
+   - If both `AGENT.md` and `AGENTS.md` exist, prefer `AGENTS.md` as canonical and leave `AGENT.md` untouched unless asked.
+2. Run the initializer.
+   - Try `dotdotgod init` only when the CLI is available; otherwise run the bundled fallback script without blocking initialization.
+   - Default behavior creates missing files only.
+   - Existing files are skipped.
+   - `.gitignore` is created or appended with missing `docs/plan`, `docs/archive`, and `.dotdotgod` entries.
+   - `--dotdot-setting` additionally creates `docs/arch/CODE_CONVENTIONS.md`, adds it to the architecture README index, and adds an `AGENTS.md` reference.
+   - `--force` backs up replaced files as `<name>.bak.<timestamp>`.
+3. Review generated files.
+   - Fill project-specific sections in `AGENTS.md` when context is available.
+   - Keep `CLAUDE.md` and `CODEX.md` thin so instructions do not drift.
+   - Treat `docs/plan` and `docs/archive` as local working memory unless the project deliberately changes that policy.
+   - 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.
+4. Report the result.
+   - List created/skipped/backed-up files.
+   - Mention any existing instructions that still need manual consolidation.
+
+## Bundled Resources
+
+- `scripts/init_project.sh`: fallback scaffold generator that mirrors `dotdotgod init` with POSIX shell only.
+- `references/agent-docs.md`: naming rationale and expected content model for shared agent docs.

package/commands/dd/load.md

@@ -0,0 +1,61 @@
+---
+description: Load dotdotgod project memory for the current repository
+argument-hint: [optional focus]
+allowed-tools: [Read, Glob, Grep, Bash]
+---
+
+# /dd:load - Load Project Memory
+
+Load the current repository's dotdotgod project memory in a read-only pass.
+
+User focus, if provided: `$ARGUMENTS`
+
+## Goal
+
+Load the current repository's dotdotgod project memory in a read-only pass. Build a compact context map from shared agent instructions, README indexes, specs, architecture notes, test docs, active plans, and relevant archive notes.
+
+Do not modify files during the load pass unless the user explicitly asks for edits after the summary.
+
+## Workflow
+
+1. Identify the repository root and current state.
+   - Check current directory, git root, branch, and dirty worktree status.
+   - Mention user changes and avoid reverting or cleaning them.
+2. Prefer the bounded CLI snapshot when available.
+   - If the user prompt contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<prompt>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
+   - If the prompt has high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, use `dotdotgod expand <root> "<prompt>" --fuzzy --json` before broad scans; avoid fuzzy expansion for low-signal generic words alone and respect configured fuzzy low-signal add/remove terms.
+   - 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, memory areas, related communities, and archive inclusion policy.
+   - 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.
+   - Use `dotdotgod graph impact <root> --changed <path> --compact --json` as a task-focused impact map when the user identifies a likely source/config/doc file.
+   - 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).
+   - 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`
+   - `docs/README.md`
+   - `docs/spec/README.md`
+   - `docs/test/README.md`
+   - `docs/arch/README.md`
+   - `docs/plan/README.md`
+   - `docs/archive/README.md`
+4. Start with `AGENTS.md`, `README.md`, and `docs/README.md` when they are not already clear from the CLI snapshot or loaded context.
+5. Follow README indexes. Read relevant docs under `docs/spec`, `docs/test`, and `docs/arch` selectively unless the task needs a full refresh.
+6. List `docs/plan` entries first, then selectively read only relevant active plans.
+7. Use `docs/archive/README.md` as the archive history map. Do not scan archive bodies by default; read targeted completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly relevant.
+8. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.
+
+## Output Shape
+
+Respond concisely with:
+
+- Project summary
+- Key working rules
+- Available commands and verification methods
+- Documentation map
+- Active plans
+- Relevant archive notes
+- Open TODO/TBD items or questions to clarify

package/commands/dd/plan.md

@@ -0,0 +1,78 @@
+---
+description: Plan a change using dotdotgod doc-first planning conventions
+argument-hint: <task or change request>
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
+---
+
+# /dd:plan - Doc-First Planning
+
+Create or update a dotdotgod implementation plan before changing source/config files.
+
+Task request: `$ARGUMENTS`
+
+## Goal
+
+Create implementation plans from the repository's documented design sources before changing source/config files. Treat planning as a managed artifact under `docs/plan`.
+
+Do not start implementation until the plan has a clear evidence trail and the user has asked to execute it. Treat the written plan file as the durable review artifact; do not rely on transient chat previews.
+
+## Source Order
+
+Prefer live repository docs in this order:
+
+1. `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, and `docs/README.md` for working rules and project map.
+2. `docs/spec/` for behavior, domain rules, API contracts, and acceptance criteria.
+3. `docs/test/` for verification strategy, regression cases, fixtures, and manual checks.
+4. `docs/arch/` for architecture decisions, module boundaries, integration constraints, and runtime assumptions.
+5. `docs/plan/README.md` and matching active plans under `docs/plan/`.
+6. Relevant completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly useful.
+
+## Workflow
+
+1. Establish current state.
+   - Check git status.
+   - Locate relevant docs and active plans.
+   - Preserve user edits and unrelated dirty worktree changes.
+   - If the session is long or noisy, suggest a user-initiated planning-focused compaction before writing or revising the plan; do not compact automatically because compaction is lossy.
+2. Gather evidence before planning.
+   - When the request contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<request>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
+   - When the request uses high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, run `dotdotgod expand <root> "<request>" --fuzzy --json`; skip fuzzy expansion for generic low-signal words alone and respect configured fuzzy low-signal add/remove terms.
+   - Search docs by domain terms from the user request.
+   - Read nearest README indexes and relevant focused docs.
+   - 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.
+   - When the dotdotgod CLI is available and likely target files are known, run `dotdotgod graph impact <root> --changed <path> --compact --json` 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.
+   - 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.
+   - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
+   - Read code only after docs identify likely module boundaries, impact output points to relevant files, or docs are missing/stale.
+3. Create or update the active plan at:
+
+   ```text
+   docs/plan/<task-slug>/README.md
+   ```
+
+4. Use supporting files in the same task directory only when useful, with UPPER_SNAKE_CASE markdown names such as `RESEARCH_NOTES.md` or `VERIFICATION.md`.
+5. Include:
+   - scope and current status
+   - target files and rationale
+   - impact-derived related files/checks when available
+   - implementation steps
+   - risks and edge cases when useful
+   - verification method
+   - final housekeeping step to move completed work to `docs/archive/plan/<task-slug>/`
+6. Update `docs/plan/README.md` if the repository keeps active plan entries there.
+7. 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.
+8. 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.
+9. Stop after presenting the plan unless the user explicitly asks for execution.
+10. 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.
+
+## Quality Rules
+
+- Prefer documented facts over inference; label inference explicitly.
+- Keep plans concise and maintainable.
+- Use local repository terminology and existing module names.
+- Validation steps must be executable commands or concrete review checks.
+- Avoid turning explanatory numbered lists into executable implementation plans. Use concrete action-oriented `Plan:` steps only when a real active plan artifact is being created or updated.
+
+## Execution Rule
+
+Do not implement source/config changes until the plan is clear and the user asks to proceed.

package/hooks/README.md

@@ -0,0 +1,166 @@
+# Optional Claude Code Hooks
+
+Claude Code hooks can complement dotdotgod commands and skills, but they are not required. `/dd:load`, `/dd:plan`, `/dd:init`, and the bundled skills work without hook configuration.
+
+Use hooks only when you want opt-in reminders, lightweight validation, or local safety rails around the same doc-first workflow. Hooks run local commands with your user permissions, so copy and adapt examples deliberately.
+
+## Current Claude Code Lifecycle Notes
+
+Claude Code exposes a broad hook lifecycle. In addition to session, prompt, tool, subagent, and stop events, current Claude Code docs include events such as `Setup`, `UserPromptExpansion`, `PermissionRequest`, `PermissionDenied`, `PostToolUseFailure`, `PostToolBatch`, `TaskCreated`, `TaskCompleted`, `StopFailure`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`, and `SessionEnd`.
+
+Dotdotgod examples intentionally use only a small subset of that surface. Prefer current events this way:
+
+- `SessionStart`: fast project-memory reminders or environment setup.
+- `UserPromptSubmit`: advisory SDLC reminders before Claude plans or implements.
+- `PreToolUse`: narrowly scoped local safety checks before writes or commands.
+- `PostToolUse`: optional feedback after a single successful tool call.
+- `PostToolBatch`: once-per-parallel-tool-batch checks or context injection when a check depends on the whole batch.
+- `Stop`: successful turn completion reminders or opt-in validation.
+- `StopFailure`: logging or notification when a turn ends due to an API error; do not use `Stop` as the only failure-path hook.
+- `SessionEnd`: cleanup or local logging at session termination, not required validation.
+
+Claude Code currently does not document dedicated plan-mode transition hooks such as `PrePlanMode`, `PostPlanMode`, plan-accept, or plan-reject events. Treat plan-mode-specific hook names found in issues or community posts as feature requests unless they appear in the official docs. Dotdotgod plan-safety examples should rely on explicit durable plans plus current hook events such as `UserPromptSubmit`, `PreToolUse`, `PostToolBatch`, and `Stop`.
+
+Hook handlers may be `command`, `http`, `mcp_tool`, `prompt`, or `agent`, with event-specific support limits. `SessionStart` and `Setup` support only `command` and `mcp_tool`. For project or plugin scripts, prefer command exec form with `args` so `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}`, and `${CLAUDE_PLUGIN_DATA}` paths are passed without shell quoting. Hooks should not write directly to `/dev/tty`; use JSON `systemMessage` for user-visible messages or Claude Code's `terminalSequence` field for terminal notifications.
+
+## SDLC Guardrail Framing
+
+Use hooks as optional guardrails around the software-development lifecycle, not as a replacement for human review or the durable plan file:
+
+1. Plan: `/dd:plan` or the planning skill creates or updates `docs/plan/<task-slug>/README.md` from docs evidence.
+2. Implement: Claude changes only the target files described by the accepted plan.
+3. Verify: run focused checks and, for docs changes, `dotdotgod validate . --include-local-memory --check-index`.
+4. Review: inspect changed files, risks, and impact-derived related checks.
+5. Archive: move completed plan artifacts only as an explicit housekeeping step, never from a default hook.
+
+This SDLC framing maps common Claude Code guidance about a project brain to dotdotgod's cross-agent contract: keep `AGENTS.md` canonical and keep `CLAUDE.md` thin rather than duplicating long-lived instructions.
+
+## When To Use Hooks
+
+- Use `/dd:load` or the `project-load` skill when you intentionally want a curated project-memory load.
+- Use `/dd:plan` or the `doc-first-planning` skill before implementation, refactors, migrations, or multi-step work.
+- During planning, prefer bounded dotdotgod context/status helpers: `status`, `load-snapshot`, `resolve`, `expand`, `graph impact`, `graph communities`, read-only `config`, and intentional `index` refreshes. Do not run mutating scaffold/config commands such as `init` or `config init` from hooks unless the user explicitly requested that setup.
+- Use hooks for small reminders at session start, prompt submission, tool boundaries, or stop time.
+
+## Opt-In Levels
+
+- `advisory`: print reminders or read-only status only.
+- `validate`: run `dotdotgod validate . --include-local-memory --check-index` after docs work or at stop time.
+- `strict-plan-safety`: add local blocking scripts only when a reliable plan-only state signal exists.
+
+Start with advisory hooks. Do not enable blocking hooks until you have tested the hook payload and your local policy script.
+
+## Advisory Example
+
+This example reminds Claude to use dotdotgod intentionally and checks cache status without rebuilding it:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "printf '%s\\n' 'dotdotgod: use /dd:load or dotdotgod load-snapshot when project memory is needed.'",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dotdotgod status . --json 2>/dev/null || true",
+            "timeout": 20
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Opt-In Validation Example
+
+Use this only when you want stop-time docs validation. It may be noisier than advisory hooks, but it keeps dotdotgod docs contracts visible:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "dotdotgod validate . --include-local-memory --check-index",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Prompt Reminder Pattern
+
+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.
+
+`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:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "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. If docs change, run dotdotgod validate . --include-local-memory --check-index.'; print(msg) if re.search(r'plan|planning|플랜|계획|\\[\\[', p, re.I) else None\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Strict Plan Safety Pattern
+
+Strict safety belongs in a local script, not a generic package default. Use exec form when referencing project-local scripts so paths with spaces do not require shell quoting:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/dotdotgod-plan-safety.py"],
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+A strict script must read hook JSON from stdin, confirm the session is explicitly in plan-only mode, allow expected `docs/plan/**` and `docs/archive/**` plan/archive updates, and fail open or advisory unless the mode signal and path parsing are tested.
+
+## Avoid By Default
+
+- Do not run `pnpm run verify` after every tool call.
+- Do not run `dotdotgod index` as an automatic stop hook.
+- Do not run `dotdotgod init` or `dotdotgod config init` automatically.
+- Do not move active plans to `docs/archive/` automatically.
+- Do not block all source writes without an explicit plan-only state signal.
+- Do not treat `dotdotgod load-snapshot` as side-effect-free in strict hooks; it may lazily refresh the ignored `.dotdotgod/` cache.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dotdotgod/claude-code",
+  "version": "0.1.21",
+  "description": "Claude Code adapter for dotdotgod project memory workflows.",
+  "type": "module",
+  "license": "Elastic-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agent-memory",
+    "ai-coding-agent",
+    "claude-code",
+    "context-curation",
+    "documentation",
+    "dotdotgod",
+    "graph-impact",
+    "planning",
+    "plugin",
+    "project-memory",
+    "traceability"
+  ],
+  "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','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/project-initializer/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')\"",
+    "pack:dry-run": "pnpm pack --dry-run --json"
+  },
+  "files": [
+    ".claude-plugin",
+    "commands",
+    "skills",
+    "hooks",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/claude-code#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotdotgod/dotdotgod-kit.git",
+    "directory": "packages/claude-code"
+  },
+  "bugs": {
+    "url": "https://github.com/dotdotgod/dotdotgod-kit/issues"
+  }
+}

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

@@ -0,0 +1,70 @@
+---
+name: doc-first-planning
+description: Use this skill when the user asks Claude Code to plan a feature, refactor, migration, architecture change, test strategy, or multi-step task using dotdotgod docs before implementation; when docs/spec, docs/test, docs/arch, docs/plan, or dd:plan are mentioned.
+version: 1.0.0
+---
+
+# Doc-First Planning
+
+## Goal
+
+Create implementation plans from the repository's documented design sources before changing source/config files. Treat planning as a managed artifact under `docs/plan`.
+
+Do not start implementation until the plan has a clear evidence trail and the user has asked to execute it. Treat the written plan file as the durable review artifact; do not rely on transient chat previews.
+
+## Source Order
+
+Prefer live repository docs in this order:
+
+1. `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, and `docs/README.md` for working rules and project map.
+2. `docs/spec/` for behavior, domain rules, API contracts, and acceptance criteria.
+3. `docs/test/` for verification strategy, regression cases, fixtures, and manual checks.
+4. `docs/arch/` for architecture decisions, module boundaries, integration constraints, and runtime assumptions.
+5. `docs/plan/README.md` and matching active plans under `docs/plan/`.
+6. Relevant completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly useful.
+
+## Workflow
+
+1. Establish current state.
+   - Check git status.
+   - Locate relevant docs and active plans.
+   - Preserve user edits and unrelated dirty worktree changes.
+   - If the session is long or noisy, suggest a user-initiated planning-focused compaction before writing or revising the plan; do not compact automatically because compaction is lossy.
+2. Gather evidence before planning.
+   - When the request contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<request>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
+   - When the request uses high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, run `dotdotgod expand <root> "<request>" --fuzzy --json`; skip fuzzy expansion for generic low-signal words alone and respect configured fuzzy low-signal add/remove terms.
+   - Search docs by domain terms from the user request.
+   - Read nearest README indexes and relevant focused docs.
+   - 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.
+   - When the dotdotgod CLI is available and likely target files are known, run `dotdotgod graph impact <root> --changed <path> --compact --json` 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.
+   - 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.
+   - Use `grep` or `find` after reference expansion, impact, and targeted reads when the task needs fallback discovery or raw source text search.
+   - Read code only after docs identify likely module boundaries, impact output points to relevant files, or docs are missing/stale.
+3. Create or update the active plan at:
+
+   ```text
+   docs/plan/<task-slug>/README.md
+   ```
+
+4. Use supporting files in the same task directory only when useful, with UPPER_SNAKE_CASE markdown names such as `RESEARCH_NOTES.md` or `VERIFICATION.md`.
+5. Include:
+   - scope and current status
+   - target files and rationale
+   - impact-derived related files/checks when available
+   - implementation steps
+   - risks and edge cases when useful
+   - verification method
+   - final housekeeping step to move completed work to `docs/archive/plan/<task-slug>/`
+6. Update `docs/plan/README.md` if the repository keeps active plan entries there.
+7. 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.
+8. 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.
+9. Stop after presenting the plan unless the user explicitly asks for execution.
+10. 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.
+
+## Quality Rules
+
+- Prefer documented facts over inference; label inference explicitly.
+- Keep plans concise and maintainable.
+- Use local repository terminology and existing module names.
+- Validation steps must be executable commands or concrete review checks.
+- Avoid turning explanatory numbered lists into executable implementation plans. Use concrete action-oriented `Plan:` steps only when a real active plan artifact is being created or updated.

package/skills/doc-first-planning/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Doc-First Planning"
+  short_description: "Plan work from dotdotgod docs first."
+  default_prompt: "Plan this change from AGENTS.md, docs/spec, docs/test, docs/arch, and docs/plan before implementation."

package/skills/project-initializer/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: project-initializer
+description: Use this skill when Claude Code is asked to initialize or normalize a project with dotdotgod shared agent instructions, AGENTS.md/CLAUDE.md/CODEX.md, docs/spec docs/test docs/arch docs/plan docs/archive, or a doc-first project baseline.
+version: 1.0.0
+---
+
+# Project Initializer
+
+## Overview
+
+Create a conservative dotdotgod project baseline that multiple AI coding agents can share:
+
+- `AGENTS.md` is the canonical project instruction file.
+- `CLAUDE.md` imports `AGENTS.md` for Claude Code.
+- `CODEX.md` points Codex users to `AGENTS.md`.
+- `docs/` contains `spec`, `test`, `arch`, `plan`, and `archive` areas with concise README files.
+- `docs/arch/` covers architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
+- 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.
+- 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.
+- Under `docs/`, all directories use kebab-case and all markdown file names use UPPER_SNAKE_CASE, including `README.md`.
+- `docs/plan/<task-slug>/README.md` is the default shape for active plan work.
+- Completed plans move to `docs/archive/plan/<task-slug>/`.
+- Temporary reports and investigations move to `docs/archive/report/<report-slug>/`.
+- `.gitignore` includes `docs/plan`, `docs/archive`, and `.dotdotgod` so local memory and the graph cache stay local by default.
+
+Use the dotdotgod CLI initializer when it is already available in the target environment:
+
+```bash
+dotdotgod init <project-root>
+```
+
+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:
+
+```bash
+sh "${CLAUDE_PLUGIN_ROOT}/skills/project-initializer/scripts/init_project.sh" <project-root>
+```
+
+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.
+
+Use `--dry-run` before touching an unfamiliar repository. Use `--dotdot-setting` when the user wants dotdot code conventions generated under `docs/arch/CODE_CONVENTIONS.md` and referenced from `AGENTS.md`. Use `--force` only when explicitly requested; it creates timestamped backups before replacing files.
+
+## Workflow
+
+1. Inspect the target project root.
+   - Check for existing `AGENTS.md`, `AGENT.md`, `CLAUDE.md`, `CODEX.md`, `README.md`, `.gitignore`, and `docs/`.
+   - Preserve project-specific instructions unless the user asks to replace them.
+   - If both `AGENT.md` and `AGENTS.md` exist, prefer `AGENTS.md` as canonical and leave `AGENT.md` untouched unless asked.
+2. Run the initializer.
+   - Try `dotdotgod init` only when the CLI is available; otherwise run the bundled fallback script without blocking initialization.
+   - Default behavior creates missing files only.
+   - Existing files are skipped.
+   - `.gitignore` is created or appended with missing `docs/plan`, `docs/archive`, and `.dotdotgod` entries.
+   - `--dotdot-setting` additionally creates `docs/arch/CODE_CONVENTIONS.md`, adds it to the architecture README index, and adds an `AGENTS.md` reference.
+   - `--force` backs up replaced files as `<name>.bak.<timestamp>`.
+3. Review generated files.
+   - Fill project-specific sections in `AGENTS.md` when context is available.
+   - Keep `CLAUDE.md` and `CODEX.md` thin so instructions do not drift.
+   - Treat `docs/plan` and `docs/archive` as local working memory unless the project deliberately changes that policy.
+   - 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.
+4. Report the result.
+   - List created/skipped/backed-up files.
+   - Mention any existing instructions that still need manual consolidation.
+
+## Bundled Resources
+
+- `scripts/init_project.sh`: fallback scaffold generator that mirrors `dotdotgod init` with POSIX shell only.
+- `references/agent-docs.md`: naming rationale and expected content model for shared agent docs.

package/skills/project-initializer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Project Initializer"
+  short_description: "Initialize agent docs and local docs folders."
+  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."

package/skills/project-initializer/references/agent-docs.md

@@ -0,0 +1,25 @@
+# Shared Agent Docs
+
+Use `AGENTS.md` as the canonical shared instruction file.
+
+## Naming
+
+- `AGENTS.md`: preferred shared file name. OpenAI Codex recognizes this convention, and the community `agents.md` convention uses the plural form.
+- `CLAUDE.md`: Claude Code's project memory file. Keep it thin and import `AGENTS.md` with `@AGENTS.md`.
+- `CODEX.md`: project-local Codex pointer. Keep it thin and link to `AGENTS.md`.
+- `AGENT.md`: avoid for new projects unless an existing tool in the repo requires it.
+
+## Content Model
+
+Put durable, project-wide instructions in `AGENTS.md`:
+
+- project purpose and stack
+- install, test, run, and lint commands
+- architecture and ownership notes
+- documentation map
+- coding and review expectations
+- environment constraints
+
+For projects using the dotdotgod CLI, `dotdotgod validate` is the enforcement point for machine-readable docs rules such as fenced `json dotdotgod` traceability blocks in behavior specs. Keep the detailed schema in the CLI and its validation errors.
+
+Do not duplicate the same body in `CLAUDE.md` and `CODEX.md`; duplication causes drift.

package/skills/project-initializer/scripts/init_project.sh

@@ -0,0 +1,344 @@
+#!/bin/sh
+set -eu
+
+usage() {
+  cat <<'EOF'
+Usage: init_project.sh <project-root> [--project-name NAME] [--dotdot-setting] [--force] [--dry-run]
+
+Initializes:
+  AGENTS.md, CLAUDE.md, CODEX.md
+  docs/README.md
+  docs/spec/README.md
+  docs/test/README.md
+  docs/arch/README.md
+  docs/plan/README.md
+  docs/archive/README.md
+  .gitignore entries for docs/plan, docs/archive, and .dotdotgod
+EOF
+}
+
+PROJECT_ROOT=""
+PROJECT_NAME=""
+FORCE=0
+DRY_RUN=0
+DOTDOT_SETTING=0
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --project-name)
+      [ "$#" -ge 2 ] || {
+        echo "error: --project-name requires a value" >&2
+        exit 2
+      }
+      PROJECT_NAME=$2
+      shift 2
+      ;;
+    --dotdot-setting)
+      DOTDOT_SETTING=1
+      shift
+      ;;
+    --force)
+      FORCE=1
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    -*)
+      echo "error: unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+    *)
+      if [ -n "$PROJECT_ROOT" ]; then
+        echo "error: unexpected argument: $1" >&2
+        usage >&2
+        exit 2
+      fi
+      PROJECT_ROOT=$1
+      shift
+      ;;
+  esac
+done
+
+[ -n "$PROJECT_ROOT" ] || {
+  usage >&2
+  exit 2
+}
+
+case "$PROJECT_ROOT" in
+  /*) ;;
+  *) PROJECT_ROOT="$(pwd)/$PROJECT_ROOT" ;;
+esac
+
+if [ -z "$PROJECT_NAME" ]; then
+  PROJECT_NAME=$(basename "$PROJECT_ROOT")
+fi
+
+timestamp() {
+  date -u "+%Y%m%d%H%M%S"
+}
+
+print_result() {
+  status=$1
+  path=$2
+  extra=${3:-}
+  if [ -n "$extra" ]; then
+    printf '%-13s %s %s\n' "$status" "$path" "$extra"
+  else
+    printf '%-13s %s\n' "$status" "$path"
+  fi
+}
+
+write_file() {
+  path=$1
+  content=$2
+
+  if [ -e "$path" ] && [ "$FORCE" -ne 1 ]; then
+    print_result "skipped" "$path"
+    return
+  fi
+
+  backup=""
+  if [ -e "$path" ] && [ "$FORCE" -eq 1 ]; then
+    backup="$path.bak.$(timestamp)"
+    if [ "$DRY_RUN" -ne 1 ]; then
+      mv "$path" "$backup"
+    fi
+  fi
+
+  if [ "$DRY_RUN" -eq 1 ]; then
+    if [ -n "$backup" ]; then
+      print_result "would_replace" "$path" "backup=$backup"
+    else
+      print_result "would_create" "$path"
+    fi
+    return
+  fi
+
+  mkdir -p "$(dirname "$path")"
+  printf '%s\n' "$content" > "$path"
+  if [ -n "$backup" ]; then
+    print_result "replaced" "$path" "backup=$backup"
+  else
+    print_result "created" "$path"
+  fi
+}
+
+ensure_gitignore_entry() {
+  entry=$1
+  path="$PROJECT_ROOT/.gitignore"
+  existed=0
+  [ -f "$path" ] && existed=1
+
+  if [ -f "$path" ] && grep -Fxq "$entry" "$path"; then
+    return
+  fi
+
+  if [ "$DRY_RUN" -eq 1 ]; then
+    if [ -f "$path" ]; then
+      print_result "would_update" "$path" "add=$entry"
+    else
+      print_result "would_create" "$path" "add=$entry"
+    fi
+    return
+  fi
+
+  mkdir -p "$PROJECT_ROOT"
+  if [ -f "$path" ] && [ -s "$path" ]; then
+    last_char=$(tail -c 1 "$path" || true)
+    [ "$last_char" = "" ] || printf '\n' >> "$path"
+  fi
+  printf '%s\n' "$entry" >> "$path"
+  if [ "$existed" -eq 1 ]; then
+    print_result "updated" "$path" "add=$entry"
+  else
+    print_result "created" "$path" "add=$entry"
+  fi
+}
+
+if [ "$DRY_RUN" -ne 1 ]; then
+  mkdir -p "$PROJECT_ROOT"
+fi
+
+DOTDOT_AGENT_RULE=""
+if [ "$DOTDOT_SETTING" -eq 1 ]; then
+  DOTDOT_AGENT_RULE='
+- Follow the project code conventions in `docs/arch/CODE_CONVENTIONS.md`.'
+fi
+
+ARCH_README_EXTRA=""
+if [ "$DOTDOT_SETTING" -eq 1 ]; then
+  ARCH_README_EXTRA='
+
+## Index
+
+- `CODE_CONVENTIONS.md`: dotdot code conventions, including abstraction boundaries and when to split long code. If conventions grow across multiple topics, promote them to `conventions/README.md` with supporting UPPER_SNAKE_CASE files.'
+fi
+
+write_file "$PROJECT_ROOT/AGENTS.md" "# AGENTS.md
+
+Canonical instructions for AI coding agents working in this repository.
+
+## Project
+
+- Name: $PROJECT_NAME
+- Purpose: TODO: describe the product, service, or library.
+- Primary stack: TODO: list runtime, framework, database, and package manager.
+
+## Working Rules
+
+- Read existing code and docs before changing behavior.
+- Keep changes scoped to the user's request.
+- Preserve user edits and unrelated dirty worktree changes.
+- Prefer existing local patterns over introducing new abstractions.
+- Update docs when behavior, architecture, or test strategy changes.
+- When using the dotdotgod CLI, run \`dotdotgod validate\` after docs changes and follow its traceability guidance for behavior specs.$DOTDOT_AGENT_RULE
+
+## Commands
+
+Document the project-specific commands here:
+
+\`\`\`bash
+# Install dependencies
+TODO
+
+# Run tests
+TODO
+
+# Run the app
+TODO
+\`\`\`
+
+## Documentation Map
+
+- \`docs/spec/\`: product behavior, API contracts, user-facing requirements.
+- \`docs/test/\`: test strategy, regression cases, manual verification notes.
+- \`docs/arch/\`: architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
+- \`docs/\`: all directories use kebab-case; all markdown file names use UPPER_SNAKE_CASE, including \`README.md\`.
+- \`docs/\`: prefer keeping individual markdown files under 200 lines and under 10,000 characters; split larger docs into focused UPPER_SNAKE_CASE files and keep \`README.md\` as the index/overview.
+- \`docs/\`: when adding, renaming, splitting, moving, or archiving docs, update the nearest relevant \`README.md\` index/table of contents in the same change.
+- \`docs/\`: each docs subdirectory \`README.md\` acts as the local table of contents; list important files, task directories, status, and a one-line purpose for each entry.
+- \`docs/\`: start small with a single focused markdown file; when one domain grows into multiple docs, promote it to \`docs/<area>/<domain>/README.md\` plus related UPPER_SNAKE_CASE files in that directory.
+- \`docs/arch/\`: code conventions may start as \`CODE_CONVENTIONS.md\`; when they grow across multiple topics, use \`docs/arch/conventions/README.md\` as the index with supporting UPPER_SNAKE_CASE files.
+- \`docs/plan/\`: local active implementation plans. Create one kebab-case directory per task (\`docs/plan/<task-slug>/\`), keep the task overview/index in that directory's \`README.md\`, and add supporting UPPER_SNAKE_CASE plan files alongside it. Ignored by git by default.
+- \`docs/archive/\`: local completed plans, temporary reports, historical notes, payload captures. Move completed plan task directories to \`docs/archive/plan/<task-slug>/\`; put temporary reports and investigations under \`docs/archive/report/<report-slug>/\`. Ignored by git by default.
+
+## Agent-Specific Entrypoints
+
+- \`CLAUDE.md\` imports this file with \`@AGENTS.md\`.
+- \`CODEX.md\` points users to this file.
+
+Keep long-lived instructions here so agent-specific files do not drift."
+
+write_file "$PROJECT_ROOT/CLAUDE.md" "# CLAUDE.md
+
+@AGENTS.md"
+
+write_file "$PROJECT_ROOT/CODEX.md" "# CODEX.md
+
+See [AGENTS.md](./AGENTS.md)."
+
+write_file "$PROJECT_ROOT/docs/README.md" "# Docs
+
+This directory keeps project knowledge close to the code.
+
+## Naming
+
+- All directories under \`docs/\` use kebab-case.
+- All markdown file names under \`docs/\` use UPPER_SNAKE_CASE, including \`README.md\`.
+- Prefer keeping individual markdown files under 200 lines and under 10,000 characters; split larger docs into focused UPPER_SNAKE_CASE files and keep \`README.md\` as the index/overview.
+
+## Indexing
+
+- When adding, renaming, splitting, moving, or archiving docs, update the nearest relevant \`README.md\` index/table of contents in the same change.
+- Each docs subdirectory \`README.md\` acts as the local table of contents; list important files, task directories, status, and a one-line purpose for each entry.
+- Start small with a single focused markdown file; when one domain grows into multiple docs, promote it to \`docs/<area>/<domain>/README.md\` plus related UPPER_SNAKE_CASE files in that directory.
+
+## Map
+
+- \`spec/\`: product behavior, API contracts, user-facing requirements.
+- \`test/\`: test strategy, regression cases, manual verification notes.
+- \`arch/\`: architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
+- \`plan/\`: local active implementation plans. Create one kebab-case directory per task (\`plan/<task-slug>/\`), keep the task overview/index in that directory's \`README.md\`, and add supporting UPPER_SNAKE_CASE plan files alongside it. Ignored by git by default.
+- \`archive/\`: local completed plans, temporary reports, historical notes, payload captures. Move completed plan task directories to \`archive/plan/<task-slug>/\`; put temporary reports and investigations under \`archive/report/<report-slug>/\`. Ignored by git by default."
+
+write_file "$PROJECT_ROOT/docs/spec/README.md" "# Specs
+
+Use this area for behavior specs, API contracts, and product requirements.
+
+For projects using the dotdotgod CLI, behavior specs may be required by \`dotdotgod validate\` to include fenced \`json dotdotgod\` traceability blocks as the final section. The CLI owns the schema and prints property-level repair guidance when validation fails."
+
+write_file "$PROJECT_ROOT/docs/test/README.md" "# Tests
+
+Use this area for test strategy, coverage notes, regression cases, and manual verification records."
+
+write_file "$PROJECT_ROOT/docs/arch/README.md" "# Architecture
+
+Use this area for architecture decisions, code conventions, module boundaries, data flow notes, infrastructure/runtime dependencies, integration boundaries, and migration design.$ARCH_README_EXTRA"
+
+if [ "$DOTDOT_SETTING" -eq 1 ]; then
+  write_file "$PROJECT_ROOT/docs/arch/CODE_CONVENTIONS.md" "# Code Conventions
+
+Dotdot code conventions for keeping implementation simple and maintainable.
+
+## Abstraction Boundaries
+
+- Do not introduce unnecessary abstractions.
+- Do not abstract code that is not reused.
+- If code grows beyond 150 lines, consider splitting or extracting focused units even when it is not reused.
+- Review files approaching 250 lines for focused extraction by responsibility.
+- Treat repeated \`dotdotgod graph impact\` results that collapse onto one large file as a design signal to split mixed responsibilities by behavior.
+- Dotdotgod impact reveals hotspots but does not replace focused module boundaries.
+- Prefer extracting pure helpers when behavior can be tested without runtime dependencies.
+- Keep runtime integration explicit and local until a stable reuse pattern appears.
+- Do not abstract reused code when the reused behavior is likely to split into separate features or flows later.
+- Keep source files readable as plain text for humans and coding agents.
+"
+fi
+
+write_file "$PROJECT_ROOT/docs/plan/README.md" "# Plans
+
+Use this area for active implementation plans.
+
+## Naming
+
+- Task directories use kebab-case: \`docs/plan/<task-slug>/\`.
+- Markdown file names use UPPER_SNAKE_CASE: \`README.md\`, \`RESEARCH_NOTES.md\`, \`VERIFICATION.md\`.
+
+## Structure
+
+- Create one directory per task: \`docs/plan/<task-slug>/\`.
+- Put the task overview, index, scope, status, and main plan in \`docs/plan/<task-slug>/README.md\`.
+- Add supporting research, checklists, payload captures, or verification notes as additional UPPER_SNAKE_CASE markdown files in the same task directory.
+- Move completed or superseded task directories to \`docs/archive/plan/<task-slug>/\`.
+
+This directory is local-only and ignored by git by default."
+
+write_file "$PROJECT_ROOT/docs/archive/README.md" "# Archive
+
+Use this area for local completed plans, temporary reports, historical notes, payload captures, and investigation notes.
+
+## Naming
+
+- Archived plan task directories preserve their kebab-case task slug.
+- Archived report directories use a focused kebab-case report slug.
+- Markdown file names use UPPER_SNAKE_CASE, including \`README.md\`.
+
+## Structure
+
+- Move completed plan task directories from \`docs/plan/<task-slug>/\` to \`docs/archive/plan/<task-slug>/\`.
+- Put temporary investigations, reports, payload captures, and historical notes under \`docs/archive/report/<report-slug>/\`.
+- Preserve each archive directory's \`README.md\` overview/index and supporting UPPER_SNAKE_CASE markdown files.
+- Additional archive categories can be added later as focused kebab-case subdirectories when needed.
+
+This directory is local-only and ignored by git by default."
+
+ensure_gitignore_entry "docs/plan"
+ensure_gitignore_entry "docs/archive"
+ensure_gitignore_entry ".dotdotgod"

package/skills/project-load/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: project-load
+description: Use this skill when the user asks Claude Code to load, refresh, inspect, summarize, or resume a repository's dotdotgod project memory; when starting unfamiliar work; or when a dd:load style project context pass is requested.
+version: 1.0.0
+---
+
+# Project Load
+
+## Goal
+
+Load the current repository's dotdotgod project memory in a read-only pass. Build a compact context map from shared agent instructions, README indexes, specs, architecture notes, test docs, active plans, and relevant archive notes.
+
+Do not modify files during the load pass unless the user explicitly asks for edits after the summary.
+
+## Workflow
+
+1. Identify the repository root and current state.
+   - Check current directory, git root, branch, and dirty worktree status.
+   - Mention user changes and avoid reverting or cleaning them.
+2. Prefer the bounded CLI snapshot when available.
+   - If the user prompt contains explicit project-memory refs such as `[[PLAN_MODE]]`, run `dotdotgod expand <root> "<prompt>" --json` before broad `grep` or `find` scans, then read the resolved candidates selectively.
+   - If the prompt has high-signal natural refs such as `PLAN_MODE`, `docs/spec/PLAN_MODE.md`, or quoted doc names, use `dotdotgod expand <root> "<prompt>" --fuzzy --json` before broad scans; avoid fuzzy expansion for low-signal generic words alone and respect configured fuzzy low-signal add/remove terms.
+   - 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, memory areas, related communities, and archive inclusion policy.
+   - 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.
+   - Use `dotdotgod graph impact <root> --changed <path> --compact --json` as a task-focused impact map when the user identifies a likely source/config/doc file.
+   - 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).
+   - 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`
+   - `docs/README.md`
+   - `docs/spec/README.md`
+   - `docs/test/README.md`
+   - `docs/arch/README.md`
+   - `docs/plan/README.md`
+   - `docs/archive/README.md`
+4. Start with `AGENTS.md`, `README.md`, and `docs/README.md` when they are not already clear from the CLI snapshot or loaded context.
+5. Follow README indexes. Read relevant docs under `docs/spec`, `docs/test`, and `docs/arch` selectively unless the task needs a full refresh.
+6. List `docs/plan` entries first, then selectively read only relevant active plans.
+7. Use `docs/archive/README.md` as the archive history map. Do not scan archive bodies by default; read targeted completed plans under `docs/archive/plan/` or reports under `docs/archive/report/` only when directly relevant.
+8. Avoid broad reads of generated outputs, dependencies, databases, caches, secrets, and `.env*` contents.
+
+## Output Shape
+
+Respond concisely with:
+
+- Project summary
+- Key working rules
+- Available commands and verification methods
+- Documentation map
+- Active plans
+- Relevant archive notes
+- Open TODO/TBD items or questions to clarify

package/skills/project-load/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Project Load"
+  short_description: "Load dotdotgod project memory."
+  default_prompt: "Load this project's dotdotgod memory and summarize rules, docs, commands, active plans, and open questions."