@dotdotgod/pi 0.1.21

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@dotdotgod/pi",
+  "version": "0.1.21",
+  "description": "Pi adapter for dotdotgod: project-initializer skill, shared docs scaffold, plan/archive workflow, and project loading extensions.",
+  "type": "module",
+  "license": "Elastic-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "agent-memory",
+    "ai-agent",
+    "context-curation",
+    "context-loader",
+    "documentation",
+    "dotdotgod",
+    "extension",
+    "graph-impact",
+    "pi",
+    "pi-coding-agent",
+    "pi-package",
+    "plan-mode",
+    "project-initializer",
+    "project-loader",
+    "project-memory",
+    "skill",
+    "traceability"
+  ],
+  "scripts": {
+    "syntax": "node --check extensions/context-metrics/utils.ts && node --check extensions/load-project/index.ts && node --check extensions/load-project/utils.ts && node --check extensions/plan-mode/index.ts && node --check extensions/plan-mode/utils.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "verify": "pnpm run syntax && pnpm run typecheck && pnpm run test",
+    "pack:dry-run": "pnpm pack --dry-run --json"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "files": [
+    "skills",
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/pi#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotdotgod/dotdotgod-kit.git",
+    "directory": "packages/pi"
+  },
+  "bugs": {
+    "url": "https://github.com/dotdotgod/dotdotgod-kit/issues"
+  }
+}

package/skills/project-initializer/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: project-initializer
+description: Initialize a new software project with shared AI agent instructions and a documentation scaffold. Use when asked to set up a new project, create or normalize AGENTS.md/CLAUDE.md/CODEX.md, create docs/spec docs/test docs/arch docs/plan docs/archive, or establish a doc-first project baseline for multiple AI agents.
+---
+
+# 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 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"