@dotdotgod/codex 0.1.12 → 0.1.14

package/README.md

@@ -18,10 +18,16 @@ Codex adapter for dotdotgod's context curation workflow. It packages reusable sk
 - Skills:
   - `project-load`: load project memory read-only.
   - `doc-first-planning`: plan from docs before implementation.
-  - `project-initializer`: initialize shared agent docs and docs folders.
+  - `project-initializer`: initialize shared agent docs and docs folders, using `dotdotgod init` when available and the bundled fallback when not.
 
 Codex may not expose the same slash-command model as Pi or Claude Code. Treat `dd:load`, `dd:plan`, and `dd:init` as command-like trigger phrases for these skills unless the active Codex plugin runtime provides direct command registration.
 
+## Optional Hooks
+
+Codex can run lifecycle hooks from trusted Codex configuration layers. dotdotgod does not require hooks: the bundled skills and `dd:load`, `dd:plan`, and `dd:init` trigger phrases work without them.
+
+Use hooks only when you want opt-in reminders or validation around the same workflow. See [`hooks/README.md`](hooks/README.md) for advisory examples and stricter plan-safety patterns.
+
 ## Local Development
 
 Run package checks:

package/hooks/README.md

@@ -0,0 +1,98 @@
+# Optional Codex Hooks
+
+Codex hooks can complement dotdotgod skills and `dd:*` trigger phrases, but they are not required. The `project-load`, `doc-first-planning`, and `project-initializer` 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. Project-local `.codex/` hooks should be reviewed and trusted before use.
+
+## 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.
+- Use hooks for small reminders at session start, prompt submission, supported tool boundaries, or stop time.
+
+## Opt-In Levels
+
+- `advisory`: print reminders or read-only status only.
+- `validate`: run `dotdotgod validate` 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, Codex trust state, and your local policy script.
+
+## Advisory `hooks.json` Example
+
+This example reminds Codex to use dotdotgod intentionally at session start:
+
+```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
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Inline TOML Shape
+
+Codex can also express hooks in `config.toml`:
+
+```toml
+[[hooks.PostToolUse]]
+matcher = "Edit|Write|apply_patch"
+
+[[hooks.PostToolUse.hooks]]
+type = "command"
+command = "sh .codex/hooks/validate-docs-if-needed.sh"
+timeout = 120
+statusMessage = "Checking dotdotgod docs when relevant"
+```
+
+Use validation hooks only by explicit opt-in. They are useful for docs-heavy sessions but can be noisy if they run after every supported edit. Prefer a local wrapper that filters to docs-related edits or writes validation logs without returning invalid hook output.
+
+## 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.
+
+## Strict Plan Safety Pattern
+
+Strict safety belongs in a local script, not a generic package default:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .codex/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. Codex tool interception may not cover every command path, so do not treat this as complete Plan Mode parity.
+
+## 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 move active plans to `docs/archive/` automatically.
+- Do not block all source writes without an explicit plan-only state signal.
+- Do not imply Codex has Claude/Pi slash-command parity.
+- Treat `dotdotgod load-snapshot` as a cache-aware opt-in, not as a side-effect-free strict hook; it may lazily refresh the ignored `.dotdotgod/` cache.
+- Do not return raw `dotdotgod status` JSON from `Stop`; Codex stop hooks need Codex-compatible hook output. Use a tested wrapper if you want stop-time status reporting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/codex",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Codex adapter for dotdotgod project memory workflows.",
   "type": "module",
   "license": "MIT",
@@ -19,11 +19,12 @@
   "files": [
     ".codex-plugin",
     "skills",
+    "hooks",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "verify": "node -e \"const fs=require('fs'); const req=['.codex-plugin/plugin.json','skills/project-load/SKILL.md','skills/doc-first-planning/SKILL.md','skills/project-initializer/SKILL.md','skills/project-initializer/scripts/init_project.sh']; JSON.parse(fs.readFileSync('.codex-plugin/plugin.json','utf8')); for (const f of req) { if (!fs.existsSync(f)) throw new Error('missing '+f); } console.log('codex adapter ok')\"",
+    "verify": "node -e \"const fs=require('fs'); const req=['.codex-plugin/plugin.json','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('.codex-plugin/plugin.json','utf8')); for (const f of req) { if (!fs.existsSync(f)) throw new Error('missing '+f); } console.log('codex adapter ok')\"",
     "pack:dry-run": "pnpm pack --dry-run --json"
   }
 }

package/skills/project-initializer/SKILL.md

@@ -20,14 +20,22 @@ Create a conservative dotdotgod project baseline that multiple AI coding agents
 - `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` and `docs/archive` so local memory stays local by default.
+- `.gitignore` includes `docs/plan`, `docs/archive`, and `.dotdotgod` so local memory and the graph cache stay local by default.
 
-Prefer the bundled dependency-free shell script for deterministic setup:
+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 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
@@ -37,21 +45,22 @@ Use `--dry-run` before touching an unfamiliar repository. Use `--dotdot-setting`
    - 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` and `docs/archive` entries.
+   - `.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` and follow any traceability schema/example shown in validation errors.
+   - 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`: creates the scaffold and handles overwrite policy with POSIX shell only.
+- `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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Project Initializer"
-  short_description: "Initialize agent docs and local docs folders with shell."
-  default_prompt: "Initialize this project with AGENTS.md, CLAUDE.md, CODEX.md, docs folders, and local plan/archive gitignore entries."
+  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/scripts/init_project.sh

@@ -13,7 +13,7 @@ Initializes:
   docs/arch/README.md
   docs/plan/README.md
   docs/archive/README.md
-  .gitignore entries for docs/plan and docs/archive
+  .gitignore entries for docs/plan, docs/archive, and .dotdotgod
 EOF
 }
 
@@ -339,3 +339,4 @@ 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"