@aprimediet/codewalker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aprimediet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @aprimediet/codewalker
+
+Systematic **project intelligence** for the [pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent): analyze tech stack, goals, boundaries, status, and technical issues, then generate a **PRD** for humans and **AGENTS.md** / **CLAUDE.md** for coding agents — plus integration with `@aprimediet/minion` and `@aprimediet/memory`.
+
+Documentation is split by audience: `docs/PRD.md` holds the product *what & why* (overview, goals, users, features, metrics); `AGENTS.md` holds the engineering *how* (tech stack, structure, commands, conventions, technical boundaries, gotchas); `CLAUDE.md` is a thin pointer that imports `AGENTS.md` as the single source of truth.
+
+## Phases
+
+| Phase | What it does |
+|-------|---|
+| Phase 1 | Detect primary language, frameworks, infrastructure, and package manager from manifest files |
+| Phase 2 | Find or gather project goals and non-goals (interactively, one question at a time) |
+| Phase 3 | Document key entry points, external services, exposed interfaces, and technical constraints |
+| Phase 4 | Scan recent commit history and search for technical debt markers (TODO/FIXME/HACK/BUG) |
+| Phase 5 | Detect missing test directories, broken env files, invalid configs, and TypeScript strictness issues |
+| Phase 6 | Generate docs, split by audience: `docs/PRD.md` (product), `AGENTS.md` (engineering), `CLAUDE.md` (pointer to AGENTS.md) — each with user confirmation |
+| Phase 7 | Detect active `@aprimediet/minion` and `@aprimediet/memory` integrations via the shared `.pi/<id>.md` marker |
+| Phase 8 | Compile full project intelligence document with all sections |
+| Phase 9 | Store summary to memory (if active) or save to local file |
+
+## Install
+
+```bash
+pi install npm:@aprimediet/codewalker
+pi list
+```
+
+## Quick try
+
+```bash
+pi -e ./extensions/codewalker/index.ts
+```
+
+Then run `/learn-this` in any project.
+
+## Integration
+
+codewalker automatically detects the presence of two companion extensions via a shared project marker:
+
+**Minion Integration (read-only):**
+- Reads the `.pi/<project-id>.md` marker file from the current working directory
+- Checks `~/.pi/projects/<id>/tasks/` for open kanban cards (backlog, todo, in_progress, blocked, review)
+- Counts and reports open task count during the `/learn-this` summary
+
+**Memory Integration (read-only + write):**
+- Reads the same `.pi/<project-id>.md` marker file
+- Checks `~/.pi/projects/<id>/memory/` for active memory (MEMORY.md + entries/)
+- Counts memory entries and reads the index during Phase 7
+- In Phase 9, if memory is active, calls `memory_write` with scope `"project"` to store the full intelligence snapshot
+
+Both integrations use **read-only detection** (no creation of files or directories); the marker file is created and managed by minion or memory when activated. codewalker coexists with them seamlessly in the same `~/.pi/projects/<id>/` workspace.
+
+## Layout
+
+```
+codewalker/                # @aprimediet/codewalker
+├── package.json           # pi manifest: extensions + skills
+├── index.ts               # extension factory: /learn-this command (probes + triggers the workflow)
+├── compat.ts              # minion + memory integration detection
+├── detect.ts              # phase-specific file and marker detection
+├── prd.ts                 # PRD (human) search, read, and generation
+├── agents.ts              # AGENTS.md + CLAUDE.md (agent) search and generation
+└── skills/
+    └── learn-this/
+        └── SKILL.md       # 9-phase intelligence gathering workflow + checklist
+```
+
+The `/learn-this` command probes integration status, shows it, then sends a user message
+that triggers the agent to invoke the `learn-this` skill and run all 9 phases.
+
+No third-party runtime deps — only the pi-core packages (peer, bundled by pi).

package/agents.ts

@@ -0,0 +1,126 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// Agent-facing guide lives at the repo root by convention (AGENTS.md), with a thin
+// CLAUDE.md pointer next to it so Claude Code auto-imports the same source of truth.
+const AGENTS_CANDIDATES = ["AGENTS.md", ".agents/AGENTS.md", "docs/AGENTS.md"];
+const CLAUDE_CANDIDATES = ["CLAUDE.md", ".claude/CLAUDE.md"];
+
+export function findExistingAgentsMd(root: string): string | null {
+  for (const p of AGENTS_CANDIDATES) {
+    const filePath = path.join(root, p);
+    if (fs.existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+export function findExistingClaudeMd(root: string): string | null {
+  for (const p of CLAUDE_CANDIDATES) {
+    const filePath = path.join(root, p);
+    if (fs.existsSync(filePath)) {
+      return filePath;
+    }
+  }
+  return null;
+}
+
+export function createAgentsMd(root: string, content: string): string {
+  const outPath = path.join(root, "AGENTS.md");
+  fs.writeFileSync(outPath, content, "utf-8");
+  return outPath;
+}
+
+export function createClaudeMd(root: string, content: string): string {
+  const outPath = path.join(root, "CLAUDE.md");
+  fs.writeFileSync(outPath, content, "utf-8");
+  return outPath;
+}
+
+/**
+ * The agent-facing engineering guide. This is the "how to work in this repo" document:
+ * tech stack, structure, commands, conventions, technical boundaries, gotchas, and how
+ * the agent should use the minion/memory companion extensions. Product "what & why"
+ * (goals, users, features, metrics) belongs in the PRD, not here.
+ */
+export function agentsMdTemplate(p: {
+  projectName: string;
+  summary: string;
+  techStack: string;
+  structure: string;
+  commands: { setup?: string; build?: string; test?: string; run?: string; lint?: string };
+  conventions: string;
+  boundaries: string;
+  knownIssues: string[];
+  integration: string;
+  currentFocus: string;
+  prdPath: string | null;
+}): string {
+  const cmd = p.commands;
+  const commandRows = [
+    cmd.setup ? `- **Setup:** \`${cmd.setup}\`` : null,
+    cmd.build ? `- **Build:** \`${cmd.build}\`` : null,
+    cmd.test ? `- **Test:** \`${cmd.test}\`` : null,
+    cmd.run ? `- **Run:** \`${cmd.run}\`` : null,
+    cmd.lint ? `- **Lint:** \`${cmd.lint}\`` : null,
+  ]
+    .filter(Boolean)
+    .join("\n");
+  const commandsSection = commandRows || "_(none detected — ask the user)_";
+  const issuesSection = p.knownIssues.length
+    ? p.knownIssues.map((i) => `- ${i}`).join("\n")
+    : "_(none known)_";
+  const productLink = p.prdPath
+    ? `Product context (goals, users, features, success metrics): see [${p.prdPath}](${p.prdPath}).`
+    : "Product context: no PRD found.";
+
+  return `# AGENTS.md — ${p.projectName}
+
+Guide for coding agents working in this repository. ${productLink}
+
+## Summary
+${p.summary}
+
+## Tech Stack
+${p.techStack}
+
+## Project Structure
+${p.structure}
+
+## Commands
+${commandsSection}
+
+## Conventions
+${p.conventions}
+
+## Boundaries (technical)
+${p.boundaries}
+
+## Known Issues & Gotchas
+${issuesSection}
+
+## Companion Extensions
+${p.integration}
+
+## Current Focus
+${p.currentFocus}
+`;
+}
+
+/**
+ * A thin CLAUDE.md that points Claude Code at AGENTS.md as the single source of truth.
+ * The `@AGENTS.md` line triggers Claude Code's file-import so the content is pulled in.
+ */
+export function claudeMdTemplate(projectName: string): string {
+  return `# CLAUDE.md — ${projectName}
+
+Guidance for Claude Code in this repository.
+
+All project conventions, architecture, build/test commands, and boundaries live in
+**[AGENTS.md](./AGENTS.md)** — the shared guide for every coding agent. Keep that file
+as the single source of truth; do not duplicate its content here.
+
+@AGENTS.md
+`;
+}

package/compat.ts

@@ -0,0 +1,217 @@
+/**
+ * Compatibility probe: detect if @aprimediet/minion and @aprimediet/memory are active
+ * for this project by reading the shared .pi/<project-id>.md marker and probing
+ * global directories.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export interface CompatResult {
+	projectId: string | null;
+	minionActive: boolean;
+	memoryActive: boolean;
+	memoryEntries: number;
+	openTaskCount: number;
+	openTaskSummary: string;
+	memorySummary: string;
+}
+
+/**
+ * Walk upward from cwd until we find a dir containing .pi/ or .git/.
+ * Return cwd if root is reached without finding either.
+ */
+function findProjectRoot(cwd: string): string {
+	let dir = cwd;
+	for (;;) {
+		const piPath = path.join(dir, CONFIG_DIR_NAME);
+		const gitPath = path.join(dir, ".git");
+		if (fs.existsSync(piPath) || fs.existsSync(gitPath)) {
+			return dir;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) {
+			// reached filesystem root
+			return cwd;
+		}
+		dir = parent;
+	}
+}
+
+/**
+ * Scan <configDir>/*.md files for one with frontmatter containing pi-project: true.
+ * Return that file's id: value, or null if none found.
+ */
+function readMarkerId(configDir: string): string | null {
+	if (!fs.existsSync(configDir)) {
+		return null;
+	}
+
+	let names: string[];
+	try {
+		names = fs.readdirSync(configDir).filter((n) => n.endsWith(".md"));
+	} catch {
+		return null;
+	}
+
+	for (const name of names) {
+		const file = path.join(configDir, name);
+		try {
+			const content = fs.readFileSync(file, "utf-8");
+			const { frontmatter } = parseFrontmatter<Record<string, string>>(content);
+			if (frontmatter && String(frontmatter["pi-project"]) === "true" && frontmatter.id) {
+				return frontmatter.id;
+			}
+		} catch {
+			// not a valid marker, skip
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Extract status and title from task frontmatter.
+ * Return { status, title } or null if cannot parse.
+ * title may be undefined if missing from frontmatter; callers should supply a fallback.
+ */
+function parseTaskMetadata(content: string): { status: string; title: string | undefined } | null {
+	try {
+		const { frontmatter } = parseFrontmatter<Record<string, string>>(content);
+		if (!frontmatter) return null;
+		const status = frontmatter.status || "";
+		const title = frontmatter.title || undefined;
+		if (!status) return null;
+		return { status, title };
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Probe minion integration: check if <globalDir>/tasks/ exists and has open tasks.
+ * Return { openTasks, openTaskSummary } or null if minion is not active.
+ */
+function probeMinionTasks(globalDir: string): { openTasks: number; openTaskSummary: string } | null {
+	const tasksDir = path.join(globalDir, "tasks");
+
+	// If tasks dir doesn't exist, minion is not active for this project
+	if (!fs.existsSync(tasksDir)) {
+		return null;
+	}
+
+	const OPEN_STATUSES = new Set(["backlog", "todo", "in_progress", "blocked", "review"]);
+	const openTasks: string[] = [];
+
+	try {
+		const names = fs.readdirSync(tasksDir);
+		for (const name of names) {
+			if (!name.endsWith(".md")) continue;
+			const file = path.join(tasksDir, name);
+			try {
+				const content = fs.readFileSync(file, "utf-8");
+				const meta = parseTaskMetadata(content);
+				if (meta && OPEN_STATUSES.has(meta.status)) {
+					const taskTitle = meta.title ?? name.replace(/\.md$/, "");
+					openTasks.push(`${meta.status}: ${taskTitle}`);
+					if (openTasks.length >= 10) break;
+				}
+			} catch {
+				// skip unparseable files
+			}
+		}
+	} catch {
+		// tasks dir exists but is unreadable — still report as active
+	}
+
+	const summary = openTasks.length > 0 ? openTasks.join("\n") : "(no open tasks)";
+	return { openTasks: openTasks.length, openTaskSummary: summary };
+}
+
+/**
+ * Probe memory integration: check if <globalDir>/memory/ exists and count entries.
+ * Also read MEMORY.md (up to 3000 chars).
+ * Return { entries, memorySummary } or null if memory is not active.
+ */
+function probeMemoryIntegration(globalDir: string): { entries: number; memorySummary: string } | null {
+	const memoryDir = path.join(globalDir, "memory");
+
+	// If memory dir doesn't exist, memory is not active for this project
+	if (!fs.existsSync(memoryDir)) {
+		return null;
+	}
+
+	// Count entries in memory/entries/
+	let entriesCount = 0;
+	const entriesDir = path.join(memoryDir, "entries");
+	try {
+		if (fs.existsSync(entriesDir)) {
+			const files = fs.readdirSync(entriesDir);
+			entriesCount = files.filter((f) => f.endsWith(".md")).length;
+		}
+	} catch {
+		// entries dir unreadable, but memory is still active
+	}
+
+	// Read MEMORY.md (truncated at 3000 chars)
+	let memorySummary = "";
+	const memoryFile = path.join(memoryDir, "MEMORY.md");
+	try {
+		if (fs.existsSync(memoryFile)) {
+			const content = fs.readFileSync(memoryFile, "utf-8");
+			memorySummary = content.length > 3000 ? content.slice(0, 3000) : content;
+		}
+	} catch {
+		// MEMORY.md unreadable
+	}
+
+	return { entries: entriesCount, memorySummary };
+}
+
+/**
+ * Probe compatibility: detect minion and memory integration for the project at cwd.
+ * Return detailed status for both extensions in a flat structure.
+ */
+export function probeCompat(cwd: string): CompatResult {
+	const root = findProjectRoot(cwd);
+	const configDir = path.join(root, CONFIG_DIR_NAME);
+	const projectId = readMarkerId(configDir);
+
+	// Initialize with defaults
+	const base: CompatResult = {
+		projectId,
+		minionActive: false,
+		memoryActive: false,
+		memoryEntries: 0,
+		openTaskCount: 0,
+		openTaskSummary: "",
+		memorySummary: "",
+	};
+
+	// If no project marker, return defaults
+	if (!projectId) {
+		return base;
+	}
+
+	const piHome = path.dirname(getAgentDir());
+	const globalDir = path.join(piHome, "projects", projectId);
+
+	// Probe minion
+	const minionProbe = probeMinionTasks(globalDir);
+	if (minionProbe) {
+		base.minionActive = true;
+		base.openTaskCount = minionProbe.openTasks;
+		base.openTaskSummary = minionProbe.openTaskSummary;
+	}
+
+	// Probe memory
+	const memoryProbe = probeMemoryIntegration(globalDir);
+	if (memoryProbe) {
+		base.memoryActive = true;
+		base.memoryEntries = memoryProbe.entries;
+		base.memorySummary = memoryProbe.memorySummary;
+	}
+
+	return base;
+}

package/detect.ts

@@ -0,0 +1,188 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+
+export interface TechStack {
+  primary: string[];
+  frameworks: string[];
+  infrastructure: string[];
+  packageManagers: string[];
+}
+
+export interface TechIssue {
+  severity: "error" | "warning" | "info";
+  location: string;
+  message: string;
+}
+
+export interface ProjectStatus {
+  recentCommits: string;
+  hasChangelog: boolean;
+  todoCount: number;
+}
+
+const LANG_FILES: Array<{ file: string; lang: string }> = [
+  { file: "package.json", lang: "Node.js" },
+  { file: "tsconfig.json", lang: "TypeScript" },
+  { file: "requirements.txt", lang: "Python" },
+  { file: "pyproject.toml", lang: "Python" },
+  { file: "go.mod", lang: "Go" },
+  { file: "Cargo.toml", lang: "Rust" },
+  { file: "pom.xml", lang: "Java" },
+  { file: "build.gradle", lang: "Java/Kotlin" },
+  { file: "build.gradle.kts", lang: "Kotlin" },
+  { file: "Gemfile", lang: "Ruby" },
+  { file: "composer.json", lang: "PHP" },
+  { file: "mix.exs", lang: "Elixir" },
+];
+
+const FRAMEWORK_FILES: Array<{ file: string; name: string; infra?: boolean }> = [
+  { file: "next.config.js", name: "Next.js" },
+  { file: "next.config.ts", name: "Next.js" },
+  { file: "next.config.mjs", name: "Next.js" },
+  { file: "vite.config.ts", name: "Vite" },
+  { file: "vite.config.js", name: "Vite" },
+  { file: "nuxt.config.ts", name: "Nuxt.js" },
+  { file: "svelte.config.js", name: "SvelteKit" },
+  { file: "astro.config.mjs", name: "Astro" },
+  { file: "remix.config.js", name: "Remix" },
+  { file: "angular.json", name: "Angular" },
+  { file: "tailwind.config.ts", name: "Tailwind CSS" },
+  { file: "tailwind.config.js", name: "Tailwind CSS" },
+  { file: "biome.json", name: "Biome" },
+  { file: "Dockerfile", name: "Docker", infra: true },
+  { file: "docker-compose.yml", name: "Docker Compose", infra: true },
+  { file: ".github/workflows", name: "GitHub Actions", infra: true },
+  { file: ".gitlab-ci.yml", name: "GitLab CI", infra: true },
+];
+
+const NPM_FRAMEWORKS: Record<string, string> = {
+  react: "React",
+  vue: "Vue",
+  express: "Express",
+  fastify: "Fastify",
+  hono: "Hono",
+  "@nestjs/core": "NestJS",
+  prisma: "Prisma",
+  "@prisma/client": "Prisma",
+  "drizzle-orm": "Drizzle ORM",
+  "@trpc/server": "tRPC",
+};
+
+export function detectTechStack(root: string): TechStack {
+  const primary = new Set<string>();
+  const frameworks = new Set<string>();
+  const infrastructure = new Set<string>();
+  const packageManagers = new Set<string>();
+
+  for (const d of LANG_FILES) {
+    if (fs.existsSync(path.join(root, d.file))) primary.add(d.lang);
+  }
+
+  for (const d of FRAMEWORK_FILES) {
+    if (fs.existsSync(path.join(root, d.file))) {
+      if (d.infra) infrastructure.add(d.name);
+      else frameworks.add(d.name);
+    }
+  }
+
+  if (fs.existsSync(path.join(root, "package-lock.json"))) packageManagers.add("npm");
+  if (fs.existsSync(path.join(root, "yarn.lock"))) packageManagers.add("yarn");
+  if (fs.existsSync(path.join(root, "pnpm-lock.yaml"))) packageManagers.add("pnpm");
+  if (fs.existsSync(path.join(root, "bun.lock"))) packageManagers.add("bun");
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8"));
+    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    for (const [dep, label] of Object.entries(NPM_FRAMEWORKS)) {
+      if (dep in deps) frameworks.add(label);
+    }
+  } catch {
+    /***/
+  }
+
+  return {
+    primary: [...primary],
+    frameworks: [...frameworks],
+    infrastructure: [...infrastructure],
+    packageManagers: [...packageManagers],
+  };
+}
+
+export function detectProjectStatus(root: string): ProjectStatus {
+  let recentCommits = "";
+  try {
+    recentCommits = execSync("git log --oneline -20", {
+      cwd: root,
+      encoding: "utf-8",
+      timeout: 5000,
+    }).trim();
+  } catch {
+    recentCommits = "(git not available or no commits)";
+  }
+
+  const hasChangelog =
+    fs.existsSync(path.join(root, "CHANGELOG.md")) || fs.existsSync(path.join(root, "CHANGELOG"));
+
+  let todoCount = 0;
+  try {
+    const result = execSync(
+      `grep -r --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" --include="*.rs" -c "TODO:\\|FIXME:\\|HACK:\\|BUG:" . 2>/dev/null || true`,
+      { cwd: root, encoding: "utf-8", timeout: 10000 }
+    );
+    for (const line of result.split("\n")) {
+      const m = line.match(/:(\d+)$/);
+      if (m) todoCount += parseInt(m[1], 10);
+    }
+  } catch {
+    /***/
+  }
+
+  return { recentCommits, hasChangelog, todoCount };
+}
+
+export function detectTechnicalIssues(root: string): TechIssue[] {
+  const issues: TechIssue[] = [];
+
+  // Invalid tsconfig.json
+  const tsconfigPath = path.join(root, "tsconfig.json");
+  if (fs.existsSync(tsconfigPath)) {
+    try {
+      JSON.parse(fs.readFileSync(tsconfigPath, "utf-8"));
+    } catch (e) {
+      issues.push({
+        severity: "error",
+        location: "tsconfig.json",
+        message: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  // No test directory or config
+  const testDirs = ["test", "tests", "__tests__", "spec"];
+  const testConfigs = ["vitest.config.ts", "vitest.config.js", "jest.config.ts", "jest.config.js"];
+  const hasTests =
+    testDirs.some((d) => fs.existsSync(path.join(root, d))) ||
+    testConfigs.some((f) => fs.existsSync(path.join(root, f)));
+  if (!hasTests) {
+    issues.push({
+      severity: "warning",
+      location: "root",
+      message: "No test directory or test config detected",
+    });
+  }
+
+  // .env.example without .env
+  if (
+    fs.existsSync(path.join(root, ".env.example")) &&
+    !fs.existsSync(path.join(root, ".env"))
+  ) {
+    issues.push({
+      severity: "info",
+      location: ".env",
+      message: ".env.example exists but .env is missing — check environment setup",
+    });
+  }
+
+  return issues;
+}

package/docs/PRD.md

@@ -0,0 +1,78 @@
+# Product Requirements Document: @aprimediet/codewalker
+
+**Version:** 1.0
+**Date:** 2026-06-25
+**Status:** Draft
+
+## Overview
+Project intelligence extension for the pi coding agent that systematically analyzes any project — tech stack, goals, boundaries, status, technical issues — and produces structured documentation: a **PRD** for humans and **AGENTS.md** / **CLAUDE.md** for coding agents.
+
+## Problem Statement
+Developers using the pi coding agent need a fast, reliable way to understand a project they're working on without manually reading every file. The coding agent also needs structured project instructions to work effectively. Currently there's no automated way to generate this intelligence snapshot and split the content by audience (human vs. agent).
+
+## Goals
+- Identify tech stack (language, frameworks, infrastructure, package manager)
+- Identify project goals and non-goals (interactively when missing)
+- Identify boundaries, scope, and constraints of a project
+- Generate a human-readable PRD.md with product context
+- Generate an engineering-focused AGENTS.md for coding agents
+- Detect companion extensions (minion, memory) and report their state
+- Store the intelligence snapshot to persistent memory for session continuity
+
+## Non-Goals
+- Give suggestions or recommendations on how to improve the project
+- Try to solve or fix technical issues found during analysis
+- Research how to solve technical issues — diagnose only, no solutions
+- Modify project files beyond the documentation it generates
+
+## Target Users
+Developers who use the pi coding agent and need to quickly get up to speed on a project or generate structured documentation for human and agent consumption.
+
+## Key Features
+
+### Tech Stack Detection
+Automatically scan manifest files (package.json, tsconfig.json, requirements.txt, go.mod, Cargo.toml, etc.) and framework configs to identify primary language, frameworks, infrastructure, and package manager.
+
+### Goals & Non-Goals Gathering
+Search README and docs for existing goals. If not found, interactively gather them from the user one question at a time — problem solved, primary users, key features, out-of-scope items, success metrics.
+
+### Boundary Documentation
+Identify key entry points, external services, exposed interfaces (APIs, CLI flags), and technical constraints (runtime version, env vars, OS requirements).
+
+### Project Status Scanning
+Read recent git commits, check for changelogs/roadmaps, scan for TODO/FIXME/HACK/BUG markers in source code.
+
+### Technical Issue Detection
+Detect missing tests, broken env files, invalid configs, and TypeScript strictness issues — report without trying to fix.
+
+### Audience-Split Documentation
+Generate three documents from the same intelligence, each targeted at its audience:
+- **docs/PRD.md** (humans, product) — overview, problem, goals, users, features, success metrics
+- **AGENTS.md** (coding agents, engineering) — tech stack, commands, conventions, technical boundaries, gotchas
+- **CLAUDE.md** (Claude Code) — thin pointer that imports AGENTS.md
+
+### Integration Detection
+Detect active `@aprimediet/minion` and `@aprimediet/memory` extensions via shared `.pi/<id>.md` project marker. Report open tasks and memory entries without modifying any files.
+
+### Memory Storage
+Store the full project intelligence snapshot to `@aprimediet/memory` (scope: project) for persistent recall across sessions.
+
+## Success Metrics
+- User can read a summary of their current project in PRD.md without reading every file manually
+- Coding agent can read specific project instructions in AGENTS.md to work effectively
+- Pi coding agent can learn and store the latest project snapshot in memory for session continuity
+- Documentation is correctly split by audience with no overlap
+
+## Scope & Boundaries
+- **Runtime:** Node.js with ESM modules (`"type": "module"`)
+- **Peer dependency:** `@earendil-works/pi-coding-agent`
+- **No third-party runtime dependencies** — Node built-ins only (`fs`, `path`, `child_process`)
+- **Exposed interface:** single `/learn-this` command registered with the pi extension API
+- **File system operations:** all detection probes are read-only; writes are confined to documentation files (PRD.md, AGENTS.md, CLAUDE.md) and memory storage
+- **Not a CI tool:** runs on-demand via `/learn-this`, not as a background service
+
+## Open Questions
+- Should AGENTS.md be auto-generated or user-edited after generation?
+- How often should memory snapshots be refreshed — on every `/learn-this` run or on demand?
+- Should the extension support non-Node.js projects (Python, Go, Rust) for full PRD/AGENTS.md generation?
+- Should there be a flag to skip interactive questions when running in non-interactive mode?

package/index.ts

@@ -0,0 +1,43 @@
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { probeCompat } from "./compat.ts";
+
+export default function codewalkExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("learn-this", {
+		description: "Analyze this project: tech stack, goals, status, issues, then generate PRD + AGENTS.md/CLAUDE.md.",
+		handler: async (_args, ctx: ExtensionContext) => {
+			const compat = probeCompat(ctx.cwd);
+
+			const minionLine = compat.minionActive
+				? `minion: active (project ${compat.projectId}, ${compat.openTaskCount} open tasks)`
+				: "minion: not detected";
+
+			const memoryLine = compat.memoryActive
+				? `memory: active (${compat.memoryEntries} entries)`
+				: "memory: not detected";
+
+			// Surface the probe result to the user immediately (TUI only).
+			if (ctx.hasUI) {
+				ctx.ui.notify(
+					["codewalker: starting /learn-this", `  ${minionLine}`, `  ${memoryLine}`].join("\n"),
+					"info",
+				);
+			}
+
+			// Actually kick off the workflow: send a user message that triggers an agent turn.
+			// The agent invokes the learn-this skill and runs all 9 phases. We hand it the
+			// integration facts up front so Phase 7 (and Phase 9 storage) start from real data.
+			const directive = [
+				"Run the /learn-this project intelligence workflow on the current working directory now.",
+				"Invoke the `learn-this` skill and complete every phase and checklist item in order.",
+				"Do not stop after detection — gather goals interactively (one question at a time) where they are missing, generate the docs (docs/PRD.md for humans, AGENTS.md + CLAUDE.md for coding agents, with the audience-correct content split), and finish with the summary and memory storage steps.",
+				"",
+				"Integration status detected by codewalker (use these facts in Phase 7 and Phase 9):",
+				`- ${minionLine}`,
+				`- ${memoryLine}`,
+				compat.projectId ? `- project id: ${compat.projectId}` : "- project id: none (no .pi marker found)",
+			].join("\n");
+
+			pi.sendUserMessage(directive, { deliverAs: "followUp" });
+		},
+	});
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@aprimediet/codewalker",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Project intelligence snapshot for the pi coding agent — /learn-this",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "codewalker",
+    "project-intelligence",
+    "prd",
+    "agents-md"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "aprimediet",
+    "url": "https://github.com/aprimediet"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aprimediet/codewalker.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aprimediet/codewalker/issues"
+  },
+  "homepage": "https://github.com/aprimediet/codewalker#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": ["./index.ts"],
+    "skills": ["./skills"]
+  },
+  "files": [
+    "*.ts",
+    "skills/**",
+    "README.md",
+    "LICENSE",
+    "docs/**"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/prd.ts

@@ -0,0 +1,106 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const PRD_CANDIDATES = [
+  "docs/PRD.md",
+  "docs/prd.md",
+  "PRD.md",
+  ".pi/prd.md",
+  "PRODUCT.md",
+  "SPEC.md",
+];
+
+export function findExistingPRD(root: string): string | null {
+  for (const p of PRD_CANDIDATES) {
+    const filePath = path.join(root, p);
+    if (fs.existsSync(filePath)) {
+      return filePath;
+    }
+  }
+
+  // README with a goals/requirements heading
+  const readme = path.join(root, "README.md");
+  if (fs.existsSync(readme)) {
+    try {
+      const text = fs.readFileSync(readme, "utf-8");
+      if (/^##\s+(Goals|Non-Goals|Requirements|Product Requirements)/im.test(text)) {
+        return readme;
+      }
+    } catch {
+      // Ignore read errors
+    }
+  }
+
+  return null;
+}
+
+export function readPRD(filePath: string): string {
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+export function createPRD(root: string, content: string): string {
+  const outPath = path.join(root, "docs", "PRD.md");
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, content, "utf-8");
+  return outPath;
+}
+
+export function prdTemplate(p: {
+  projectName: string;
+  overview: string;
+  problem: string;
+  goals: string[];
+  nonGoals: string[];
+  targetUsers: string;
+  keyFeatures: Array<{ name: string; description: string }>;
+  successMetrics: string[];
+  boundaries: string;
+  openQuestions: string[];
+  date: string;
+}): string {
+  const goalsSection = p.goals.map((g) => `- ${g}`).join("\n");
+  const nonGoalsSection = p.nonGoals.map((g) => `- ${g}`).join("\n");
+  const featuresSection = p.keyFeatures
+    .map((f) => `### ${f.name}\n${f.description}`)
+    .join("\n\n");
+  const metricsSection = p.successMetrics.map((m) => `- ${m}`).join("\n");
+  const questionsSection = p.openQuestions.map((q) => `- ${q}`).join("\n");
+
+  return `# Product Requirements Document: ${p.projectName}
+
+**Version:** 1.0
+**Date:** ${p.date}
+**Status:** Draft
+
+## Overview
+${p.overview}
+
+## Problem Statement
+${p.problem}
+
+## Goals
+${goalsSection}
+
+## Non-Goals
+${nonGoalsSection}
+
+## Target Users
+${p.targetUsers}
+
+## Key Features
+${featuresSection}
+
+## Success Metrics
+${metricsSection}
+
+## Boundaries & Constraints
+${p.boundaries}
+
+## Open Questions
+${questionsSection}
+`;
+}

package/skills/learn-this/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: learn-this
+description: Use when the user runs /learn-this or asks to analyze, understand, or get up to speed on the current project. Guides systematic project intelligence gathering across tech stack, goals, status, technical issues, PRD management, and integration detection.
+---
+
+# Learn This — Project Intelligence
+
+Build a complete project intelligence snapshot for the current working directory.
+Create a task for each phase listed below before starting any of them.
+
+---
+
+## Phase 1 — Tech Stack
+
+Read the following files if they exist and record what you find:
+
+| File | Signals |
+|---|---|
+| `package.json` | Node.js / JS / TS; read `dependencies` + `devDependencies` for frameworks |
+| `tsconfig.json` | TypeScript |
+| `bun.lock` / `pnpm-lock.yaml` / `yarn.lock` / `package-lock.json` | Package manager |
+| `requirements.txt` / `pyproject.toml` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `pom.xml` / `build.gradle` / `build.gradle.kts` | Java / Kotlin |
+| `Gemfile` | Ruby |
+| `next.config.*` / `vite.config.*` / `nuxt.config.*` / `astro.config.*` | Frontend framework |
+| `tailwind.config.*` | Tailwind CSS |
+| `Dockerfile` / `docker-compose.yml` | Docker |
+| `.github/workflows/` | GitHub Actions |
+| `.gitlab-ci.yml` | GitLab CI |
+
+Also read `package.json` deps for: `react`, `vue`, `express`, `fastify`, `hono`,
+`@nestjs/core`, `prisma`, `@prisma/client`, `drizzle-orm`, `@trpc/server`.
+
+Record: primary language(s), frameworks, infrastructure, package manager.
+
+---
+
+## Phase 2 — Goals & Non-Goals
+
+Search in order:
+1. `README.md` — look for Goals, Non-Goals, About, Overview headings
+2. `docs/PRD.md`, `docs/prd.md`, `PRD.md`, `.pi/prd.md`, `PRODUCT.md`, `SPEC.md`
+3. Any markdown file whose name contains "goals" or "requirements"
+
+**If goals are NOT found**, gather them interactively — ask ONE question at a time and wait
+for the user's answer before asking the next:
+
+1. "What problem does this project solve?"
+2. "Who is the primary user or audience?"
+3. "What are the 3 most important features?"
+4. "What is explicitly out of scope?"
+5. "What does success look like for this project?"
+
+**Do NOT present all five questions at once. Ask one. Wait for the answer. Ask the next.**
+
+---
+
+## Phase 3 — Boundaries
+
+From README and code structure, identify:
+- Key entry points (main files, API routes, CLI commands)
+- External services consumed (databases, third-party APIs, cloud services)
+- Exposed interfaces (HTTP endpoints, CLI flags, exported packages)
+- Technical constraints (runtime version, OS requirements, required env vars)
+
+---
+
+## Phase 4 — Project Status
+
+1. Run: `git log --oneline -20` — record the output
+2. Check for `CHANGELOG.md`, `TODO.md`, `ISSUES.md`, `ROADMAP.md`
+3. Scan for technical debt markers:
+   ```
+   grep -r "TODO:\|FIXME:\|HACK:\|BUG:" --include="*.ts" --include="*.js" --include="*.py" --include="*.go" . 2>/dev/null | head -20
+   ```
+
+---
+
+## Phase 5 — Technical Issues
+
+Detect and report:
+- No test directory or test config found (`test/`, `tests/`, `__tests__/`, `vitest.config.*`, `jest.config.*`)
+- `.env.example` exists but `.env` is missing
+- `tsconfig.json` is not valid JSON
+- Count of `// @ts-nocheck` or `// @ts-ignore` occurrences
+
+Then ask the user:
+> "I found [N] potential issues above. Are there additional technical issues you want me to be aware of or address?"
+
+Record their response.
+
+---
+
+## Phase 6 — Documentation Generation
+
+Produce two complementary documents from everything gathered so far, and split the content
+by audience. **Never put the same content in both.**
+
+| Document | Audience | Holds the *what & why* / *how* |
+|---|---|---|
+| `docs/PRD.md` | Humans (product) | overview, problem, goals, non-goals, target users, key features, success metrics, product-scope boundaries, open questions |
+| `AGENTS.md` (repo root) | Coding agents (engineering) | tech stack, project structure, build/test/run commands, conventions, **technical** boundaries, known issues, companion-extension usage, current focus |
+| `CLAUDE.md` (repo root) | Claude Code | thin pointer that imports `AGENTS.md` |
+
+### 6a — PRD (human, product)
+
+**Search for existing PRD** in: `docs/PRD.md`, `docs/prd.md`, `PRD.md`, `.pi/prd.md`,
+`PRODUCT.md`, `SPEC.md`, or `README.md` with a Goals/Requirements heading.
+
+**If it exists**: read and summarize key sections for the Phase 8 summary.
+
+**If it does NOT exist**:
+- Ask: "No PRD found. Should I create `docs/PRD.md` with the product information we gathered?"
+- If yes, write `docs/PRD.md` using this template (product content only — no commands, no file paths, no conventions):
+
+```
+# Product Requirements Document: <project-name>
+
+**Version:** 1.0
+**Date:** <today>
+**Status:** Draft
+
+## Overview
+<1-2 sentence vision summary>
+
+## Problem Statement
+<what problem this solves and who has it>
+
+## Goals
+- <goal from Phase 2>
+
+## Non-Goals
+- <non-goal from Phase 2>
+
+## Target Users
+<from Phase 2>
+
+## Key Features
+### <Feature>
+<product-level description>
+
+## Success Metrics
+- <metric from Phase 2>
+
+## Scope & Boundaries
+<product-scope boundaries from Phase 3 — what the product will and will not do>
+
+## Open Questions
+- <any unresolved questions>
+```
+
+### 6b — AGENTS.md (coding agent, engineering)
+
+**Search for an existing agent guide** at: `AGENTS.md`, `.agents/AGENTS.md`, `docs/AGENTS.md`.
+
+**If it exists**: read it; offer to update stale sections rather than overwrite.
+
+**If it does NOT exist**:
+- Ask: "No AGENTS.md found. Should I create one at the repo root for coding agents?"
+- If yes, write `AGENTS.md` using this template (engineering content only — NO product goals/users/metrics; link to the PRD for those):
+
+```
+# AGENTS.md — <project-name>
+
+Guide for coding agents working in this repository. Product context (goals, users,
+features, success metrics): see [docs/PRD.md](docs/PRD.md).
+
+## Summary
+<one-line: what this codebase is, technically>
+
+## Tech Stack
+<languages, frameworks, infrastructure, package manager — from Phase 1>
+
+## Project Structure
+<key entry points and directories — from Phase 3>
+
+## Commands
+- **Setup:** <install command, if any>
+- **Build:** <build command, if any>
+- **Test:** <test command, if any>
+- **Run:** <run/dev command, if any>
+- **Lint:** <lint/format command, if any>
+
+## Conventions
+<code style, naming, patterns observed in the codebase — match what exists>
+
+## Boundaries (technical)
+<do-not-touch areas, invariants, generated files, things that must not change — from Phase 3>
+
+## Known Issues & Gotchas
+- <technical issue from Phase 5>
+
+## Companion Extensions
+<if minion/memory are active (Phase 7): how the agent should use them — e.g. check the
+kanban board before starting, record durable facts to memory. If not active, say so.>
+
+## Current Focus
+<what is being worked on now — from Phase 4 recent commits / status>
+```
+
+### 6c — CLAUDE.md (Claude Code pointer)
+
+**If `CLAUDE.md` does not already exist** at the repo root, create it as a thin pointer so
+Claude Code loads the same guide (do not duplicate AGENTS.md content):
+
+```
+# CLAUDE.md — <project-name>
+
+Guidance for Claude Code in this repository.
+
+All project conventions, architecture, build/test commands, and boundaries live in
+**[AGENTS.md](./AGENTS.md)** — the shared guide for every coding agent. Keep that file
+as the single source of truth; do not duplicate its content here.
+
+@AGENTS.md
+```
+
+If `CLAUDE.md` already exists with its own content, do NOT overwrite it — instead offer to
+add the `@AGENTS.md` import line if it is missing.
+
+---
+
+## Phase 7 — Integration Detection
+
+**Detect `@aprimediet/minion`:**
+
+Step-by-step marker detection:
+1. List all `*.md` files inside the `.pi/` directory at the project root
+2. For each file, read its contents
+3. Check if the file contains both `pi-project: true` and an `id:` field (in YAML frontmatter)
+4. If found, extract the value after `id:` — this is the project id
+
+Then check for minion:
+- Check if `~/.pi/projects/<id>/tasks/` directory exists
+- If yes: read each `*.md` file in the tasks dir; count those whose frontmatter has `status:` set to one of: `backlog`, `todo`, `in_progress`, `blocked`, `review`
+- Report: count of open tasks + their titles + statuses
+
+**Detect `@aprimediet/memory`:**
+
+- Use the **same `.pi/<id>.md` marker** (one file serves both extensions — do not create a new one)
+- Check if `~/.pi/projects/<id>/memory/` directory exists
+- If yes: check for `~/.pi/projects/<id>/memory/MEMORY.md` — read it if present
+- Count `*.md` files in `~/.pi/projects/<id>/memory/entries/`
+- Report: active/not-detected, entry count, MEMORY.md contents
+
+---
+
+## Phase 8 — Compile Summary
+
+Assemble the full project intelligence document using these exact section headers:
+
+```
+# Project Intelligence: <project-name>
+> Generated by /learn-this on <date>
+
+## Tech Stack
+**Language(s):** ...
+**Frameworks:** ...
+**Infrastructure:** ...
+**Package Manager:** ...
+
+## Goals
+...
+
+## Non-Goals
+...
+
+## Boundaries
+...
+
+## Current Status
+**Recent commits:**
+<git log output>
+
+**Open TODOs/FIXMEs:** N found
+
+## Technical Issues
+- ...
+
+## Documentation
+**PRD (`docs/PRD.md`):** exists | created | not created
+**AGENTS.md:** exists | created | not created
+**CLAUDE.md:** exists | created | not created
+**Key points:** ...
+
+## Minion Integration
+**Status:** active | not detected
+**Project ID:** ...
+**Open tasks (N):**
+- ...
+
+## Memory Integration
+**Status:** active (N entries) | not detected
+**Index:**
+<MEMORY.md contents, or "(empty)">
+```
+
+---
+
+## Phase 9 — Store to Memory
+
+**If `@aprimediet/memory` is active** (detected in Phase 7):
+- Call `memory_write` with `scope: "project"`, `type: "fact"`, and `text:` set to the full Phase 8 summary
+- Report: "Summary stored to project memory."
+
+**If memory is not active**:
+- Display the summary in chat
+- Ask: "Would you like me to save this to `docs/project-intelligence.md`?"
+- If yes, write the file.
+
+---
+
+## Checklist
+
+- [ ] Phase 1: Tech stack identified
+- [ ] Phase 2: Goals/non-goals found or gathered interactively (one question at a time)
+- [ ] Phase 3: Boundaries documented
+- [ ] Phase 4: Project status from git log + TODO scan
+- [ ] Phase 5: Technical issues detected + user asked about additional issues
+- [ ] Phase 6: Docs generated — PRD (product), AGENTS.md (engineering), CLAUDE.md (pointer), with user confirmation and audience-correct content split
+- [ ] Phase 7: minion compatibility detected; memory compatibility detected
+- [ ] Phase 8: Full summary compiled
+- [ ] Phase 9: Summary stored to memory or saved to file