@dotdotgod/pi

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

Use this package when you want Pi to initialize project memory, load bounded repository context, plan before source edits, generate staged durable plans, run impact-aware checks, and archive completed work for future sessions.

Pi is the fullest dotdotgod experience: it is the only adapter that enforces Plan Mode before source edits, generates staged durable plans, and can gate commit, push, and publish on pending impact checks. Throughout, the maintained graph stays a compact map for targeted reads, not a giant report to consume in full.

Start Here

Install the adapter in Pi:

pi install npm:@dotdotgod/pi

Then open Pi in your repository and ask:

Initialize this project with dotdotgod.

A good first run:

1. Install this package.
2. Start Pi in the target repository.
3. Ask Pi to initialize the project with dotdotgod.
4. Review the files the initializer will create or skip.
5. Run /dd:load to load bounded project memory.
6. Use /plan <request> before implementation work.

What It Adds to Pi

| Need | Pi command or feature | | --- | --- | | Create the docs-first project scaffold | project-initializer skill | | Load project memory without broad file reads | /dd:load (full), /dd:load:compact (compact), or /load | | Plan safely before source/config edits | /plan and /plan <request> | | Generate a staged durable plan | /plan-goal | | Show execution progress | /todos | | Review changed-file impact | /impact-check or dotdotgod_graph_impact | | Improve docs clarity | document-clarify skill | | Clarify completed /plan-goal plans without inherited context | dotdotgod.plan-doc-clarifier subagent | | Delegate analysis or implementation work | bundled pi-subagents resources |

Project Initializer

The bundled project-initializer skill creates or normalizes this memory surface:

AGENTS.md                    # canonical working rules for agents
CLAUDE.md                    # thin Claude Code pointer to AGENTS.md
CODEX.md                     # thin Codex pointer to AGENTS.md
docs/
  README.md                  # project documentation map
  spec/README.md             # behavior, requirements, product truth
  arch/README.md             # architecture, conventions, boundaries
  test/README.md             # verification strategy and smoke tests
  plan/README.md             # active local plans, ignored by git
  archive/README.md          # completed-work history map, ignored by git

The package includes @dotdotgod/cli as a runtime dependency. Pi extensions prefer a source-checkout CLI when present, then the package-local CLI, then a global dotdotgod fallback. The initializer also includes a shell fallback for constrained environments.

Planning Workflow

/plan

Use /plan when a request may lead to source or config changes. Plan Mode keeps implementation mutations blocked until there is a durable plan under docs/plan/<task-slug>/README.md and the user chooses to execute it.

Plan Mode helps Pi:

• load relevant project memory,
• write or update active plan docs,
• track execution steps with [DONE:n] markers,
• remind agents to run impact checks after source/config edits,
• archive completed plans under docs/archive/plan/.

/plan-goal

Use /plan-goal when you want Pi to author a plan through explicit stages instead of writing a one-pass plan.

The simplified stages are:

1. 01-intake
2. 02-context-load
3. 03-discovery
4. 04-plan
5. optional 05-workstream-handoff

The generator creates or resumes docs/plan/<task-slug>/README.md and stores internal checkpoint context in docs/plan/<task-slug>/.dotdotgod-plan/. Those checkpoint files are workflow state, not final user-facing plan content.

Useful controls:

• /plan-goal <request> starts a new staged plan.
• /plan-goal docs/plan/<task-slug>/README.md resumes or starts staged work for that managed plan path.
• /plan-goal with no argument pauses an active or waiting generator so it can resume from later input.
• /plan-goal --stop stops the active generator and clears the shared workflow flag.

/plan-goal does not execute implementation work automatically. Plan Mode still requires user approval before source/config edits.

After the final stage passes, /plan-goal queues one documentation-clarity follow-up. The follow-up prefers the packaged dotdotgod.plan-doc-clarifier subagent with context: "fresh" and explicit reads limited to the durable plan README plus named task-local support or workstream markdown. If the subagent tool or packaged agent is unavailable, agents should fall back to the document-clarify skill with the same explicit-file-only boundaries.

While /plan-goal is active or waiting, Plan Mode suppresses normal execution review so the staged authoring loop can finish first.

Loading and Impact Checks

/dd:load starts from dotdotgod load-snapshot when available, then reads only relevant docs from the fixed memory surface. The snapshot includes cache status, graph size, memory areas, communities, archive policy, and configured pinned files such as code-convention docs pinned via load.pinnedPaths/load.pinnedBodies in dotdotgod.config.json.

/impact-check and the dotdotgod_graph_impact tool use the maintained graph to surface related specs, tests, docs, commands, source, and config after a change. Pi can remind the agent to run impact checks and can block commit, push, or publish commands until pending impact checks pass.

Included Resources

• project-initializer skill
• document-clarify skill
• dotdotgod.plan-doc-clarifier packaged subagent
• plan-mode extension
• plan-goal extension, providing the /plan-goal command
• load-project extension
• pi-subagents wrapper resources
• package-local @dotdotgod/cli dependency

If standalone pi-subagents is already installed, the wrapper avoids duplicate dotdotgod-provided tool, skill, and prompt resources.

Local Development

pi install /path/to/dotdotgod/packages/pi
pnpm --filter @dotdotgod/pi run verify
pnpm --filter @dotdotgod/pi run pack:dry-run

Learn More

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

Compared with Graphify-Style Memory

The Pi adapter focuses on workflow. It initializes the project-memory scaffold, loads a bounded snapshot, plans before source edits, checks changed-file impact, and archives completed work for future sessions. The graph is a compact map for targeted reads, not a giant report for agents to consume in full.