@dreadedzombie/pi-init 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# pi-init
+
+Adds `/init` to [Pi](https://pi.dev/) — generates or updates an AGENTS.md in your current project directory.
+
+## Install
+
+```bash
+pi install https://github.com/joenilan/pi-init
+```
+
+Pi clones the repo and loads the extension automatically on next start.
+
+## Usage
+
+```
+/init              Explore-first project analysis → AGENTS.md
+/init code         Same as bare /init
+/init research     Research protocol with incremental findings tracking
+/init debug        Debug protocol — carries forward research findings automatically
+```
+
+## What each type does
+
+**`/init` / `/init code`** — Pi explores the project first (reads package.json, scans
+structure, reads key source files, checks for `.cursorrules`/`CLAUDE.md`), then writes
+a filled-in AGENTS.md. If AGENTS.md already has content, running `/init` again flags it
+for update — Pi re-explores and refreshes stale sections without wiping human-authored notes.
+
+**`/init research`** — Writes a research protocol: minimum source count, citation
+requirements, when to use Playwright vs fetch, sequential-thinking for multi-step
+reasoning, memory for long sessions. Includes a `## Research Findings` section Pi
+updates incrementally — each topic gets saved to `research/<topic>.md` and linked here.
+
+**`/init debug`** — Writes an investigative protocol: verify before assuming, read logs
+first, checkpoint with `pi-rewind` before changes, trace backward from the error. If
+you ran `/init research` first, the Research Findings section carries forward
+automatically — Pi reads those files at step 1 before touching any code.
+
+## Research → Debug workflow
+
+```
+/init research        # set up research protocol
+# describe your topic — Pi searches, reads sources, saves to research/*.md
+
+/init debug           # switch to debug — research findings carry forward automatically
+# Pi reads linked research files before starting any investigation
+```
+
+Colony agents read AGENTS.md from the working directory on every action, so they see
+research findings and debug context the same way a single-agent session does.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@dreadedzombie/pi-init",
+  "version": "1.0.0",
+  "description": "Generates a typed AGENTS.md for your project — /init, /init research, /init debug, /init code",
+  "license": "MIT",
+  "author": "DreadedZombie",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DreadedZombie/pi-init.git"
+  },
+  "homepage": "https://github.com/DreadedZombie/pi-init#readme",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "agents",
+    "agents-md",
+    "init",
+    "scaffold",
+    "research",
+    "debug"
+  ],
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,256 @@
+/**
+ * pi-init — /init slash command
+ *
+ * Generates or updates an AGENTS.md in the current working directory.
+ *
+ * Usage:
+ *   /init              Explore-first project analysis → AGENTS.md
+ *   /init code         Same as bare /init
+ *   /init research     Research protocol with incremental findings tracking
+ *   /init debug        Debug protocol — carries forward Research Findings from prior /init research
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ─── Templates ────────────────────────────────────────────────────────────────
+
+const TEMPLATE_CODE = `# Project Agent
+
+<!-- Pi: before writing anything, explore this project:
+  1. Read package.json / pyproject.toml / Cargo.toml / go.mod — identify stack and versions
+  2. Scan directory structure: rg --files | head -60
+  3. Read 3-5 key source files to understand patterns and conventions
+  4. Check for .cursorrules, CLAUDE.md, .eslintrc, prettier.config — existing AI/style config
+  Then fill in each section below based on what you actually find.
+  Adapt or add sections if the project has unique needs.
+-->
+
+**Generated:** <!-- Pi: insert today's date (YYYY-MM-DD) -->
+
+## Stack
+<!-- Pi: languages, frameworks, key libraries and their versions -->
+
+## Structure
+<!-- Pi: key directories and what each contains — a mental map, not a full file list -->
+
+## Commands
+| Action  | Command |
+|---------|---------|
+| Install |         |
+| Build   |         |
+| Test    |         |
+| Run     |         |
+
+## Conventions
+<!-- Pi: coding style, patterns in use, formatter/linter config, naming conventions -->
+
+## Key Files
+<!-- Pi: the 5-10 most important files and what each one does -->
+
+## What to Avoid
+<!-- Pi: patterns or changes that would break things or go against project style -->
+
+## Notes
+<!-- Pi: existing AI config files (.cursorrules, CLAUDE.md), gotchas, constraints, anything a new agent must know -->
+`;
+
+const TEMPLATE_RESEARCH = `# Research Agent
+
+**Started:** <!-- Pi: insert today's date (YYYY-MM-DD) -->
+
+## Search Protocol
+- Run at least **4 distinct queries** approaching the topic from different angles before drawing conclusions
+- Read the **full content** of at least 6 sources — not just summaries or snippets
+- For JS-heavy or dynamically rendered pages where \`fetch\` returns sparse HTML, use **Playwright** to render and extract
+- Cross-reference findings across sources before responding
+- Do **not** respond until you have read multiple sources and built a complete picture
+
+## Source Quality Standards
+- Prefer primary sources: official documentation, research papers, original announcements
+- Flag secondary sources: forums, blog posts, aggregators — note them as such
+- When sources conflict, surface the contradiction explicitly — do not silently pick one
+- Cite every factual claim with its source URL
+
+## Research Process
+1. **Map** — 3-4 broad queries to understand the landscape and identify the key sources
+2. **Dive** — read the full content of the 5-6 most relevant sources
+3. **Cross-reference** — identify what sources agree and disagree on
+4. **Synthesize** — build a coherent picture with citations
+5. **Save** — write findings to \`research/<topic>.md\`, one file per topic or question
+6. **Update** — add each saved file to the Research Findings section below with a one-line summary
+7. **Gaps** — explicitly note what you could not find or verify
+
+## Tools
+- \`searxng\` — start here for all searches (private, no tracking)
+- \`fetch\` — static pages, documentation, GitHub READMEs
+- \`playwright\` — JS-rendered pages, React/Vue apps, login-gated content, anything fetch returns blank for
+- \`sequential-thinking\` — use when the research has multiple dependent steps or requires structured reasoning
+- \`memory\` — persist key findings across a long session so nothing gets lost to context limits
+- \`pi-docparser\` — for PDFs, papers, Word docs, spreadsheets
+
+## Research Findings
+<!-- Pi: as you complete each topic, save findings to research/<topic>.md and add a line here:
+     - [Topic title](research/filename.md) — one-line summary of what was found
+     Update this section incrementally — do not wait until the end. -->
+`;
+
+const TEMPLATE_DEBUG = `# Debug Agent
+
+## Research Findings
+<!-- Pi: read every file linked here before starting investigation — prior research is your context -->
+
+## Investigative Stance
+- **Never assume** — verify everything against logs, actual code, and runtime behavior
+- Read error messages and stack traces **in full** before proposing any fix
+- Trace from the error **backward** to the root cause — not forward from a guess
+- Document every finding, including dead ends — they matter for context
+
+## Before Any Fix
+- Checkpoint the current state with \`pi-rewind\` before touching anything
+- Understand the full failure chain before writing a single line
+- Identify whether the issue is: **configuration**, **code logic**, **dependencies**, **environment**, or **data**
+
+## Investigation Order
+1. Read all Research Findings files linked above — prior research changes what you look for
+2. Read all available logs — error, build, runtime, access
+3. Trace the startup / execution sequence from the entry point
+4. Check dependency versions and compatibility
+5. Verify environment variables and configuration files
+6. Isolate the **earliest** point of failure — fixes belong there, not downstream
+
+## Current State
+<!-- Pi: read this directory now and fill in:
+- What is this project supposed to do?
+- What is currently broken — exact error messages and symptoms
+- Where does it fail — startup, build, runtime, specific operation?
+- What has already been tried?
+- Key files to investigate first
+-->
+
+## Constraints
+- Use \`pi-rewind\` before every destructive or speculative change
+- If you find multiple possible causes, list them ranked by likelihood before acting
+- Confirm before deleting files, dropping data, or resetting state
+`;
+
+// Prepended to existing AGENTS.md when /init code is run on a project that already has one
+const UPDATE_BANNER = `<!-- Pi: UPDATE MODE
+This AGENTS.md was generated in a prior session. Your job:
+1. Re-explore the project (rg --files, re-read key source files)
+2. Check for new or changed .cursorrules, CLAUDE.md, or other AI config files
+3. Update every section below with fresh findings — fix stale info, fill gaps
+4. Preserve any human-authored notes that don't conflict with current reality
+-->
+
+`;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+type InitType = "code" | "research" | "debug";
+
+function parseType(args: string): InitType {
+  const t = (args || "").trim().toLowerCase();
+  if (t === "research") return "research";
+  if (t === "debug") return "debug";
+  return "code";
+}
+
+function getFollowUp(type: InitType): string {
+  switch (type) {
+    case "research":
+      return "AGENTS.md written with the research protocol. Describe what you want to research — Pi will search, read sources, save findings to research/ files, and update the Research Findings section as it goes.";
+    case "debug":
+      return "AGENTS.md written with the debug protocol. Ask Pi to read this directory and fill in the Current State section before starting any investigation.";
+    default:
+      return "AGENTS.md written. Ask Pi to explore this project and fill in all sections — it will read the codebase first, then generate.";
+  }
+}
+
+/**
+ * Returns true if the file has meaningful filled-in content beyond placeholders.
+ */
+function hasFilledContent(content: string): boolean {
+  const withoutComments = content.replace(/<!--[\s\S]*?-->/g, "").trim();
+  const withoutHeaders = withoutComments.replace(/^#+.*$/gm, "").replace(/^\*\*Generated:?\*\*.*$/gm, "").trim();
+  return withoutHeaders.length > 80;
+}
+
+/**
+ * Extracts the body of the ## Research Findings section from an existing AGENTS.md.
+ * Returns empty string if section is missing or contains only the placeholder comment.
+ */
+function extractResearchFindings(content: string): string {
+  const m = content.match(/^## Research Findings\n([\s\S]*?)(?=\n## |\n# |$)/m);
+  if (!m) return "";
+  const body = m[1].trim();
+  if (body.startsWith("<!--") && body.endsWith("-->")) return "";
+  return body;
+}
+
+/**
+ * Injects research findings into the debug template, replacing the placeholder comment.
+ */
+function buildDebugWithFindings(findings: string): string {
+  return TEMPLATE_DEBUG.replace(
+    "<!-- Pi: read every file linked here before starting investigation — prior research is your context -->",
+    findings
+  );
+}
+
+// ─── Extension entry ──────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("init", {
+    description: "Generate or update an AGENTS.md for this project. Usage: /init [code|research|debug]",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const type = parseType(args);
+      const cwd: string = ctx.cwd ?? process.cwd();
+      const dest = path.join(cwd, "AGENTS.md");
+      const exists = fs.existsSync(dest);
+
+      // ── Debug: carry forward Research Findings from a prior research session ──
+      if (type === "debug" && exists) {
+        const existing = fs.readFileSync(dest, "utf8");
+        const findings = extractResearchFindings(existing);
+        if (findings) {
+          fs.writeFileSync(dest, buildDebugWithFindings(findings), "utf8");
+          ctx.ui.notify(`[pi-init] AGENTS.md switched to debug protocol — research findings carried forward`, "info");
+          ctx.ui.notify(getFollowUp("debug"), "info");
+          return;
+        }
+      }
+
+      // ── Code: update mode if AGENTS.md has real content (no overwrite prompt) ──
+      if (type === "code" && exists) {
+        const existing = fs.readFileSync(dest, "utf8");
+        if (hasFilledContent(existing)) {
+          fs.writeFileSync(dest, UPDATE_BANNER + existing, "utf8");
+          ctx.ui.notify(`[pi-init] AGENTS.md flagged for update — ask Pi to re-explore and refresh all sections`, "info");
+          return;
+        }
+      }
+
+      // ── All other cases: confirm overwrite if file exists ──
+      if (exists) {
+        const overwrite = await ctx.ui.confirm(
+          `AGENTS.md already exists in:\n${cwd}`,
+          "Overwrite it?"
+        );
+        if (!overwrite) {
+          ctx.ui.notify("Cancelled — existing AGENTS.md kept.", "info");
+          return;
+        }
+      }
+
+      const content = type === "research" ? TEMPLATE_RESEARCH
+                    : type === "debug"    ? TEMPLATE_DEBUG
+                    :                       TEMPLATE_CODE;
+
+      fs.writeFileSync(dest, content, "utf8");
+      ctx.ui.notify(`[pi-init] AGENTS.md (${type}) written to ${cwd}`, "info");
+      ctx.ui.notify(getFollowUp(type), "info");
+    },
+  });
+}