@dotdotgod/codex 0.1.13 → 0.1.15

package/README.md

@@ -1,13 +1,15 @@
 # @dotdotgod/codex
 
-Codex adapter for dotdotgod's context curation workflow. It packages reusable skills that help Codex load curated project memory, plan from docs before implementation, and initialize the shared agent documentation scaffold.
+> **Change a file, know what else must be checked.**
+
+Codex adapter for dotdotgod's context curation workflow. It packages reusable skills that help Codex load curated project memory, plan from docs before implementation, and initialize the shared agent documentation scaffold so changes start with the right specs, tests, plans, and archive map.
 
 ## What Gets Better?
 
-- Codex can start from `AGENTS.md` and the dotdotgod docs map instead of rebuilding context manually.
+- Codex can start from `AGENTS.md` and the dotdotgod docs map.
 - Load guidance prefers `dotdotgod load-snapshot <root> --json` when the CLI is available, then falls back to README-index reads.
 - Codex 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.
-- Product intent, design rationale, and verification standards stay in durable docs instead of transient chat.
+- Product intent, design rationale, and verification standards stay in durable docs.
 - Planning work captures current intent in `docs/plan/<task-slug>/README.md` before implementation.
 - Completed plans and temporary reports use the same archive structure as Pi and Claude Code, turning outcomes into future context.
 - `dd:load`, `dd:plan`, and `dd:init` can be used as command-like trigger phrases where direct slash commands are unavailable.
@@ -22,6 +24,12 @@ Codex adapter for dotdotgod's context curation workflow. It packages reusable sk
 
 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:
@@ -42,6 +50,6 @@ pnpm --filter @dotdotgod/codex run pack:dry-run
 
 ## Compared with Graphify-Style Memory
 
-This adapter packages reusable workflow skills rather than a repo-wide extraction engine. It guides Codex to prefer a bounded dotdotgod load snapshot when available, avoid broad archive scans, and follow README indexes before reading raw files.
+This adapter packages reusable workflow skills. It guides Codex 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: project docs declare which files are rules, specs, architecture, verification, active intent, or historical memory. That keeps the memory layer portable across Codex runtimes and useful on small tasks where a large graph report would be overhead.

package/hooks/README.md

@@ -0,0 +1,104 @@
+# 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 . --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, Codex trust state, and your local policy script.
+
+## Review Before First Run
+
+Codex may detect a configured hook but keep it disabled until you review it. If Codex shows `1 hook needs review before it can run. Open /hooks to review it.`, open `/hooks`, inspect the command, and approve only commands you trust.
+
+After approval, trigger a small supported edit such as an `apply_patch` documentation comment change and confirm the hook status message or command output appears. If the hook was added while a Codex session was already running, restart Codex before the smoke test so the current configuration is loaded.
+
+## 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 = "dotdotgod validate . --include-local-memory --check-index"
+timeout = 120
+statusMessage = "Checking dotdotgod docs and index freshness"
+```
+
+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. `--check-index` compares current markdown fingerprints with `.dotdotgod/manifest.json` without refreshing the cache; if the only failure is an index freshness error, run `dotdotgod index .` or `pnpm run verify:cache` intentionally.
+
+## 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.13",
+  "version": "0.1.15",
   "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/references/agent-docs.md

@@ -20,6 +20,6 @@ Put durable, project-wide instructions in `AGENTS.md`:
 - 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 rather than duplicating it across agent memory files.
+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-load/SKILL.md

@@ -34,7 +34,7 @@ Do not modify files during the load pass unless the user explicitly asks for edi
    - `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 instead of re-scanning every listed file unless the task needs a full refresh.
+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.