@dotdotgod/codex

Codex adapter for dotdotgod's docs-first project-memory workflow.

This package brings dotdotgod's shared project memory to Codex through workflow skills, a local stdio MCP server, and trust-reviewed lifecycle hooks declared by its plugin manifest (.codex-plugin/plugin.json).

What Changes

• Codex shares the project's durable knowledge. AGENTS.md, maintained docs, active plans, and archived outcomes stay portable across agent hosts.
• Skills provide a native workflow vocabulary. dd:init, dd:load, dd:plan, and dd:impact map normal chat requests to reusable project-memory workflows.
• Large working evidence remains local and retrievable. The MCP runtime processes command output, files, and fetched text as bounded excerpts with provenance.
• Plans and impact checks survive individual turns. Durable plan files preserve intent, while trusted hooks track edits and require matching impact evidence before broad handoff operations.
• Activation follows Codex trust boundaries. Skills remain available independently; packaged hooks become active after the applicable plugin enablement and review flow.

Start Here

Make the bundled skills visible to Codex: register the package through your Codex environment's plugin mechanism if it supports plugin manifests, or copy the skills/ directories into a trusted Codex skills location.

Codex uses dotdotgod trigger phrases in normal chat when its environment does not provide a matching slash-command surface:

dd:init

dd:load

dd:plan Update the API migration plan.

dd:impact

The bundled skills interpret those phrases as command-like workflow requests. After updating or re-registering the adapter, restart Codex and verify the active MCP artifact path; source changes do not automatically replace a stale host-managed plugin cache.

What It Adds to Codex

| Skill or trigger | Use it for | Result | | --- | --- | --- | | dd:init / project-initializer | Start a repository with dotdotgod conventions. | Creates or normalizes shared agent files, docs indexes, local-memory areas, and the complete default project config. | | dd:load / project-load | Load project memory without changing maintained project files. | Renders the shared Markdown tree and uses dotdotgod query when focus text is provided; unavailable optional semantic routing falls back to the map with bounded evidence. | | dd:plan / doc-first-planning | Plan before implementation. | Captures current intent in docs/plan/<task-slug>/README.md. | | dd:impact / impact-review | Review changed files before verification or handoff. | Uses dotdotgod graph impact to identify likely related docs, tests, commands, and source files. | | document-clarify | Improve docs wording without changing behavior contracts. | Clarifies README/spec/test/arch/plan/archive docs using memory-area roles. | | dotdotgod-context MCP tools | Run commands, process files, fetch/index text, and search large output locally. | Keeps large raw bytes outside model context and returns bounded output or FTS5 excerpts. |

Included

• Codex plugin manifest: .codex-plugin/plugin.json
• Local MCP configuration: .mcp.json
• Hook configuration and runtime: hooks/hooks.json, hooks/runtime.mjs
• Skills:
  • project-load
  • doc-first-planning
  • project-initializer
  • impact-review
  • document-clarify

Shared Project-Memory Contract

• AGENTS.md remains canonical.
• CODEX.md stays thin and points to AGENTS.md.
• Specs describe behavior and requirements.
• Architecture docs explain rationale, boundaries, and conventions.
• Test docs explain verification strategy, regression coverage, fixtures, and commands.
• 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.

Memory Areas and Traceability

By default, docs/spec/** has two separate roles:

• It is stable shared project memory for product behavior and requirements.
• It is the traceability-enforced path for behavior specs.

Projects can customize memory roles with memory.areas, select traceability-enforced Markdown with traceability.required and traceability.exclude, and define the ordered complete list of traceability string arrays with traceability.keys. Each key owns its label, path or command target, graph relation, and PPR weight.

Bundled MCP And Hooks

The local stdio MCP server exposes generic execution/retrieval tools plus dotdotgod_project_load, dotdotgod_project_impact, and dotdotgod_project_initialize. These dotdotgod execution tools share a 10 MiB stdout/stderr capture ceiling per command; exceeding it terminates the process and reports captureLimitExceeded. Direct stdout and stderr excerpts are each capped at 1 MiB. Child environments preserve compatibility-oriented inheritance after filtering runtime injection variables; filtered names are reported without values, but ordinary inherited credentials remain ambient. Larger output is indexed in the ignored project-local .dotdotgod/context/ SQLite FTS5 store and retrieved as bounded excerpts. The store uses WAL, a bounded busy timeout, and transactional source replacement, expiry, and purge.

The MCP index tool accepts project-contained files or bounded directories with deterministic traversal, configurable depth/entry/file/byte limits, explicit extension/path exclusions, and symlinks skipped by default. Indexed Markdown and JSON use structure-aware chunks. Search combines bounded Porter and label/path candidates with reciprocal-rank fusion plus deterministic title, path, and proximity signals. Results include operation-owned provenance and trust metadata and mark retrieved text as non-authoritative data with instructionAuthority: "none"; this is defense in depth, not a prompt-injection guarantee. URL fetching accepts credential-free HTTP(S), validates DNS answers, connected addresses, and every redirect, and applies separate wire and decoded-body limits. Accepted HTML is normalized as bounded untrusted text without browser rendering, JavaScript, subresource loading, or link following by default. The server bundles no browser renderer, so browser opt-in fails unless a host injects that capability. These controls provide application-level validation and defense in depth rather than a network sandbox or prompt-injection guarantee.

This behavior applies only when Codex calls the dotdotgod-context MCP execution, indexing, search, fetch, or diagnostic tools. It does not intercept or rewrite Codex's ordinary built-in shell calls. See the @dotdotgod/context npm package, its GitHub README, and the maintained context execution contract for the complete tool and limit definitions.

Bundled hooks become active only after Codex's applicable plugin trust/review flow. They mark project load as required, record successful source/config edits, and deny broad verification or handoff commands until matching graph impact succeeds. Codex then calls the named MCP tool and retries the original operation; hooks do not silently change a shell call into an MCP call. See hooks/README.md.

Local Development

pnpm --filter @dotdotgod/codex run verify
pnpm --filter @dotdotgod/codex run pack:dry-run

Learn More

See the root README, Context curation, Context mechanics, Memory area config, and Traceability config.

Workflow Model

The adapter maps shared project memory onto Codex's own extension model. Skills express the workflow, MCP tools provide bounded local evidence, and trust-reviewed hooks connect edits to project loading and impact review.