@minhduydev/mdpi 0.3.2 → 0.4.0

package/README.md

@@ -38,6 +38,7 @@ npx mdpi init
 | Command | What it does |
 |---------|--------------|
 | `mdpi init` | Scaffold the curated `.pi/` kit into the current repo + write `.version` + `.template-manifest.json` (SHA-256 file map). Idempotent; `--force` overwrites template files (preserves user files), `--quiet` for CI. `--only <cats>` installs only the listed category dirs (`agents,prompts,skills,templates,workflows,context,extensions`) and trims settings.json to match. |
+| `mdpi install` | Install the kit's declared npm packages — core (`.pi/settings.json:packages`) + optional (`.pi/packages.json`). Shells out to `pi install npm:<pkg>` (idempotent, safe to re-run). `--core` / `--optional` scope; `--check` dry-runs and reports installed/missing; `--yes` skips the confirm prompt. |
 | `mdpi upgrade` | Bring `.pi/` up to the bundled template version. Manifest-based: overwrites only user-unmodified files, preserves user edits, lists orphans. `--check` dry-run, `--force` overwrite modified, `--prune-all` delete orphans. |
 | `mdpi new <kind> [name]` | Scaffold a new kit component (`skill\|prompt\|agent\|workflow\|template`) from a lint-passing skeleton. `-d <text>` sets the description; `--force` overwrites. The skill skeleton comes with frontmatter + When to Use/NOT so it passes `mdpi lint` immediately. |
 | `mdpi lint [skills\|docs\|all]` | Governance: SKILL.md frontmatter (pi `name`+`description`), H1, When to Use/NOT, line limits, references/ depth, **dead cross-ref detection** (skills referencing non-existent skills), + README count/slash-command drift. `--json` for machine output. |
@@ -53,4 +54,4 @@ npx mdpi init
 
 ## What's in the kit
 
-`agents/` (7) · `prompts/` (11) · `skills/` (67 + INDEX) · `templates/` (11) · `workflows/` (6) · `context/` (2) · `extensions/` (2 TS) · `settings.json` · `AGENTS.md` · `README.md` · `QUALITY.md` · `.env.example` · `guard.example.json` · `subagents.json` · `artifacts/example/` (template examples).
+`agents/` (7) · `prompts/` (11) · `skills/` (67 + INDEX) · `templates/` (11) · `workflows/` (6) · `context/` (2) · `extensions/` (2 TS) · `settings.json` · `packages.json` · `AGENTS.md` · `README.md` · `QUALITY.md` · `.env.example` · `guard.example.json` · `subagents.json` · `artifacts/example/` (template examples).

package/dist/index.js

@@ -5,10 +5,12 @@ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statS
 import * as p from "@clack/prompts";
 import color from "picocolors";
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { mkdir, readdir } from "node:fs/promises";
 //#region package.json
-var version = "0.3.2";
+var version = "0.4.0";
 //#endregion
 //#region src/utils/manifest.ts
 /**
@@ -78,6 +80,192 @@ function fileModificationStatus(filePath, relativePath, manifest) {
 	return hashFile(filePath) === templateHash ? "unmodified" : "modified";
 }
 //#endregion
+//#region src/commands/install.ts
+/**
+* mdpi install — install the npm packages this kit depends on.
+*
+* The kit references two kinds of external packages:
+*   - **core**: declared in `.pi/settings.json:packages` (auto-loaded by pi at
+*     startup — e.g. `@sting8k/pi-srcwalk`, `pi-hermes-memory`). Single source
+*     of truth = settings.json; this command reads it, does not duplicate it.
+*   - **optional**: declared in `.pi/packages.json` (recommended add-ons the
+*     user opts into — e.g. `@davecodes/pi-dcp`, `pi-guard`).
+*
+* `mdpi install` shells out to `pi install <id>` for each declared package.
+* `pi install` is idempotent (re-running on an already-installed package is a
+* no-op), so this command is safe to re-run.
+*
+* Flags:
+*   (default)  install core + optional
+*   --core     only settings.json:packages
+*   --optional only packages.json:optional
+*   --check    dry-run: list declared packages + report which are already
+*              installed under ~/.pi/agent/npm/node_modules (no shell-out)
+*   --yes      skip the confirmation prompt (for CI)
+*
+* Why a dedicated command instead of `mdpi init` doing it: init copies files
+* only and must work offline / without `pi` on PATH. Package installation is a
+* separate, network-dependent step the user controls explicitly. `mdpi init`
+* reminds the user to run `mdpi install` next.
+*/
+/** Path to pi's global npm install dir (where `pi install npm:foo` lands). */
+function globalNpmDir() {
+	return join(homedir(), ".pi", "agent", "npm", "node_modules");
+}
+/**
+* Extract the npm package name from a `npm:<name>` source id.
+* `npm:@davecodes/pi-dcp` → `@davecodes/pi-dcp`. Non-npm ids return null
+* (presence check only supports npm sources).
+*/
+function npmNameFromId(id) {
+	if (!id.startsWith("npm:")) return null;
+	return id.slice(4);
+}
+/** Is a package already installed in pi's global npm dir? */
+function isInstalled(id) {
+	const name = npmNameFromId(id);
+	if (!name) return false;
+	return existsSync(join(globalNpmDir(), name));
+}
+/** Read core packages from `.pi/settings.json:packages`. */
+function readCorePackages(piDir) {
+	const path = join(piDir, "settings.json");
+	if (!existsSync(path)) return [];
+	let json;
+	try {
+		json = JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return [];
+	}
+	const packages = json.packages;
+	if (!Array.isArray(packages)) return [];
+	return packages.filter((id) => typeof id === "string" && id.length > 0).map((id) => ({
+		id,
+		source: "core"
+	}));
+}
+/** Read optional packages from `.pi/packages.json:optional`. */
+function readOptionalPackages(piDir) {
+	const path = join(piDir, "packages.json");
+	if (!existsSync(path)) return [];
+	let json;
+	try {
+		json = JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return [];
+	}
+	const optional = json.optional;
+	if (!Array.isArray(optional)) return [];
+	const out = [];
+	for (const entry of optional) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const id = entry.id;
+		if (typeof id !== "string" || id.length === 0) continue;
+		const note = entry.note;
+		out.push({
+			id,
+			note: typeof note === "string" ? note : void 0,
+			source: "optional"
+		});
+	}
+	return out;
+}
+/** Run `pi install <id>`. Resolves true on exit 0, false otherwise. */
+function runPiInstall(id, quiet) {
+	return new Promise((resolve) => {
+		const child = spawn("pi", ["install", id], { stdio: quiet ? "ignore" : "inherit" });
+		child.on("error", (err) => {
+			if (!quiet) console.error(color.red(`  pi install ${id} failed to start: ${err.message}`));
+			resolve(false);
+		});
+		child.on("exit", (code) => resolve(code === 0));
+	});
+}
+/** Check whether `pi` is on PATH. */
+function hasPi() {
+	try {
+		return spawnSync("pi", ["--version"], { stdio: "ignore" }).status === 0;
+	} catch {
+		return false;
+	}
+}
+async function installCommand(options = {}) {
+	const quiet = process.argv.includes("--quiet");
+	if (!quiet) p.intro(color.bgCyan(color.black(" mdpi install ")));
+	const piDir = options.piDir || join(process.cwd(), ".pi");
+	if (!existsSync(piDir)) {
+		if (!quiet) {
+			p.log.error(".pi/ not found — run `mdpi init` first");
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const core = readCorePackages(piDir);
+	const optional = readOptionalPackages(piDir);
+	const wantCore = options.core || !options.core && !options.optional;
+	const wantOptional = options.optional || !options.core && !options.optional;
+	const selected = [...wantCore ? core : [], ...wantOptional ? optional : []];
+	if (selected.length === 0) {
+		if (!quiet) {
+			p.log.warn("No packages declared (settings.json:packages empty and packages.json:optional empty)");
+			p.outro("Nothing to do");
+		}
+		return;
+	}
+	if (options.check) {
+		console.log(`\n${color.bold("mdpi install --check")} — declared packages\n`);
+		const installed = selected.filter((pkg) => isInstalled(pkg.id));
+		const missing = selected.filter((pkg) => !isInstalled(pkg.id));
+		for (const pkg of selected) {
+			const mark = isInstalled(pkg.id) ? color.green("✓ installed") : color.yellow("✗ missing");
+			const note = pkg.note ? color.gray(` — ${pkg.note}`) : "";
+			console.log(`  ${mark}  ${color.cyan(pkg.id)}${note}`);
+		}
+		console.log(`\n  ${color.green(`${installed.length}`)} installed · ${color.yellow(`${missing.length}`)} missing · ${selected.length} total`);
+		if (missing.length > 0) console.log(`\n  Run ${color.cyan("mdpi install")} to install the missing ${missing.length} package(s).`);
+		if (!quiet) p.outro(missing.length === 0 ? color.green("All installed") : color.yellow("Some missing"));
+		process.exitCode = missing.length === 0 ? 0 : 1;
+		return;
+	}
+	if (!hasPi()) {
+		if (!quiet) {
+			p.log.error("`pi` not found on PATH — install pi first (npm i -g @earendil-works/pi-coding-agent)");
+			p.outro(color.red("Failed"));
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const missing = selected.filter((pkg) => !isInstalled(pkg.id));
+	const alreadyOk = selected.length - missing.length;
+	if (!quiet && !options.yes) {
+		const scope = wantCore && wantOptional ? "core + optional" : wantCore ? "core" : "optional";
+		const confirm = await p.confirm({
+			message: `Install ${missing.length} missing package(s) [${scope}]?${alreadyOk > 0 ? ` (${alreadyOk} already installed, skipped)` : ""}`,
+			initialValue: true
+		});
+		if (p.isCancel(confirm) || !confirm) {
+			p.outro("Cancelled");
+			return;
+		}
+	}
+	if (quiet) console.log(`mdpi: installing ${missing.length}/${selected.length} packages (core=${wantCore} optional=${wantOptional})`);
+	else p.log.info(`Installing ${missing.length} missing package(s) of ${selected.length} declared`);
+	let ok = 0;
+	let fail = 0;
+	for (const pkg of missing) {
+		if (!quiet) p.log.step(`${color.cyan(pkg.id)}${pkg.note ? color.gray(` — ${pkg.note}`) : ""}`);
+		if (await runPiInstall(pkg.id, quiet)) ok++;
+		else fail++;
+	}
+	if (quiet) console.log(`mdpi: done — ${ok} installed, ${fail} failed, ${alreadyOk} already present`);
+	else {
+		p.note(`${ok} installed · ${fail} failed · ${alreadyOk} already present\n\n` + (fail > 0 ? `${color.red("Some installs failed — check pi output above.")}\n` : `${color.green("All declared packages are now installed.")}\n`) + `Re-run anytime: ${color.cyan("mdpi install")} (idempotent).`, "Install complete");
+		p.outro(fail === 0 ? color.green("Ready!") : color.red("Partial failure"));
+	}
+	process.exitCode = fail === 0 ? 0 : 1;
+}
+//#endregion
 //#region src/utils/template.ts
 /** Shared template + version helpers used by init / upgrade / doctor. */
 const DEFAULT_SKIP_DIRS = [
@@ -499,8 +687,9 @@ function lintAll(piDir, opts = {}) {
 * mdpi doctor — .pi/ health check.
 *
 * Verifies: mdpi version match, manifest valid, settings.json valid JSON, kit
-* dirs present (skills/prompts/agents/templates/workflows/extensions), orphan
-* detection (manifest files no longer in template), and a lint summary.
+* dirs present (skills/prompts/agents/templates/workflows/extensions), package
+* install status (core settings.json + optional packages.json vs installed),
+* orphan detection (manifest files no longer in template), and a lint summary.
 */
 function row(ok, label, detail) {
 	console.log(`  ${ok ? color.green("✓") : color.red("✗")} ${label}: ${detail}`);
@@ -559,6 +748,11 @@ async function doctorCommand(options = {}) {
 	row(countMd("templates") > 0, "templates", `${countMd("templates")} templates`);
 	row(countMd("workflows") > 0, "workflows", `${countMd("workflows")} workflows`);
 	row(countExt("extensions", ".ts") > 0, "extensions", `${countExt("extensions", ".ts")} extensions`);
+	const corePkgs = readCorePackages(piDir);
+	const optPkgs = readOptionalPackages(piDir);
+	const allPkgs = [...corePkgs, ...optPkgs];
+	const installedPkgs = allPkgs.filter((pkg) => isInstalled(pkg.id)).length;
+	row(allPkgs.length > 0, "packages", allPkgs.length === 0 ? "none declared (settings.json:packages + packages.json:optional)" : `${installedPkgs}/${allPkgs.length} installed` + (installedPkgs < allPkgs.length ? color.yellow(`  (run mdpi install)`) : "") + ` — core ${corePkgs.length}, optional ${optPkgs.length}`);
 	if (templateRoot) row(orphans === 0, "orphans", orphans === 0 ? "none (template-removed files)" : `${orphans} orphan(s) — run mdpi upgrade --prune-all`);
 	const lr = lintSkills(piDir);
 	console.log(`  ${lr.ok ? color.green("✓") : color.red("✗")} lint: ${lr.stats.failed} errors · ${lr.stats.warnings} warnings (run ${color.cyan("mdpi lint")} for detail)`);
@@ -622,6 +816,7 @@ const ALWAYS_ENTRIES = [
 	"scripts",
 	"artifacts/example",
 	"settings.json",
+	"packages.json",
 	"AGENTS.md",
 	"README.md",
 	"QUALITY.md",
@@ -760,7 +955,7 @@ async function initCommand(options = {}) {
 		console.log(`mdpi: installed ${fileCount} files to ${piDir} (v${version})${subset}`);
 	} else {
 		const subsetNote = only ? `Subset: ${[...only].join(", ")} (+ always-on config).\n\nsettings.json trimmed to drop references to excluded\nskills/prompts/extensions dirs.\n\nNote: mdpi upgrade compares against the FULL template —\nrun \`mdpi upgrade --check\` before applying.\n\n` : "";
-		p.note(`Pi kit installed at:\n${piDir}\n\n${fileCount} template files tracked via manifest.\n\n` + subsetNote + `Next: open pi in this repo to use the kit.`, "Installation complete");
+		p.note(`Pi kit installed at:\n${piDir}\n\n${fileCount} template files tracked via manifest.\n\n` + subsetNote + `Next: run ${color.cyan("mdpi install")} to install the kit's npm packages,\nthen open pi in this repo to use the kit.`, "Installation complete");
 		p.outro(color.green("Ready!"));
 	}
 }
@@ -1152,6 +1347,9 @@ cli.help();
 cli.command("init", "Scaffold a Pi coding-agent kit (.pi/) into the current repo").option("--force", "Overwrite existing .pi/ template files (preserves extra user files)").option("-y, --yes", "Skip prompts, use defaults (for CI)").option("--only <cats>", "Install only these categories (comma-sep: agents,prompts,skills,templates,workflows,context,extensions)").action(async (options) => {
 	await initCommand(options);
 });
+cli.command("install", "Install the kit's declared npm packages (core from settings.json + optional from packages.json)").option("--core", "Only install core packages (settings.json:packages)").option("--optional", "Only install optional packages (packages.json:optional)").option("--check", "Dry-run: list declared packages + report installed/missing").option("-y, --yes", "Skip confirmation prompt (for CI)").action(async (options) => {
+	await installCommand(options);
+});
 cli.command("upgrade", "Bring .pi/ up to the bundled template version").option("--force", "Overwrite user-modified files (default: preserve them)").option("--check", "Dry-run: report what would change without writing").option("--prune-all", "Delete orphan files (template-removed since install)").action(async (options) => {
 	await upgradeCommand(options);
 });

package/dist/template/.pi/README.md

@@ -241,22 +241,43 @@ This kit ships **2 custom TypeScript extensions** and uses **2 external npm pack
 | `workflows-runner` | Parses DAG workflows from `.pi/workflows/*.md`, returns execution plan with `subagent()` calls | Production |
 | `templates-injector` | Auto-injects `project.md`, `tech-stack.md`, `state.md` into system prompt | Production |
 
-### External packages (auto-loaded from global)
+### External packages
 
-| Package | Purpose | Why external |
-|---------|---------|--------------|
-| `@davecodes/pi-dcp` | Dynamic context pruning (dedup, error purge, compress tool) | Battle-tested, superset of what we'd write |
-| `jdiamond/pi-guard` | Tool permission system (bash AST parser, path globs, default ruleset) | Proper bash AST parser handles `\|`, `&&`, `xargs` — regex can't |
+The kit depends on external npm packages, split into two sets:
 
-Install with `pi install npm:@davecodes/pi-dcp npm:pi-guard`. The pi-guard config example lives at `.pi/guard.example.json` — copy the `guard` block into `.pi/settings.json` to enable.
+- **Core** — declared in `.pi/settings.json:packages`, auto-loaded by pi at
+  startup. Single source of truth = `settings.json`.
+- **Optional** — declared in `.pi/packages.json`, recommended add-ons you opt
+  into.
+
+| Package | Set | Purpose | Why external |
+|---------|-----|---------|--------------|
+| `@tintinweb/pi-subagents` | core | Subagent dispatch (`subagent()` tool) | Battle-tested pi-native package |
+| `@sting8k/pi-srcwalk` | core | `semantic_*` code navigation tools | Trigram-indexed search, deep |
+| `pi-hermes-memory` | core | Long-term memory (`memory`/`memory_search`/`session_search`/`skill_manage`) | Mature, 368 tests, FTS5 + two-tier |
+| `@davecodes/pi-dcp` | optional | Dynamic context pruning (dedup, error purge, compress tool) | Superset of the kit's former dcp-strategies extension |
+| `pi-guard` | optional | Tool permission system (bash AST parser, path globs) | AST parser handles `\|`, `&&`, `xargs` — regex can't |
+
+Install the full set with one command (idempotent, safe to re-run):
+
+```bash
+mdpi install            # core + optional
+mdpi install --core     # only settings.json:packages
+mdpi install --optional # only packages.json:optional
+mdpi install --check    # dry-run: report installed/missing
+```
+
+`mdpi install` shells out to `pi install npm:<pkg>` for each declared package.
+The pi-guard config example lives at `.pi/guard.example.json` — copy the `guard`
+block into `.pi/settings.json` to enable its rules.
 
 ### Removed (intentionally)
 
 | Extension | Reason | Replaced by |
 |-----------|--------|-------------|
 | `commands-dispatcher` | Pi's built-in prompt template loader already does this | pi core (no install needed) |
-| `dcp-strategies` | Superseded by `@davecodes/pi-dcp` (active globally) | `pi install npm:@davecodes/pi-dcp` |
-| `pi-guard` (local) | Superseded by `jdiamond/pi-guard` (proper AST parser) | `pi install npm:pi-guard` |
+| `dcp-strategies` | Superseded by `@davecodes/pi-dcp` (active globally) | `mdpi install --optional` |
+| `pi-guard` (local) | Superseded by `jdiamond/pi-guard` (proper AST parser) | `mdpi install --optional` |
 
 ---
 

package/dist/template/.pi/VERSION

@@ -1 +1 @@
-0.2.0
+0.4.0

package/dist/template/.pi/agents/general.md

@@ -2,7 +2,7 @@
 name: general
 description: General-purpose subagent for small, well-defined implementation tasks (1-3 files)
 tools: read, grep, find, ls, bash, edit, write, semantic_query, semantic_inspect, semantic_grep, semantic_show
-model: ollama-cloud/glm-5.2
+model: opencode-go/deepseek-v4-flash
 ---
 
 You are Pi — a surgical implementer.

package/dist/template/.pi/agents/review.md

@@ -2,7 +2,7 @@
 name: review
 description: Read-only code review, debugging, and security audit specialist with severity-ranked findings
 tools: read, grep, find, ls, bash, semantic_query, semantic_inspect, semantic_grep, semantic_show
-model: ollama-cloud/glm-5.2
+model: opencode-go/minimax-m3
 ---
 
 You are Pi — a read-only review specialist.

package/dist/template/.pi/packages.json

@@ -0,0 +1,13 @@
+{
+  "$comment": "Optional packages recommended by this kit. `mdpi install` installs these alongside the core packages declared in settings.json:packages. Core lives there (single source of truth); this file only lists the opt-in set. Edit freely — adding an entry here makes `mdpi install` pick it up.",
+  "optional": [
+    {
+      "id": "npm:@davecodes/pi-dcp",
+      "note": "Dynamic context pruning — dedup, error purge, compress tool. Superset of the kit's former dcp-strategies extension."
+    },
+    {
+      "id": "npm:pi-guard",
+      "note": "Tool permission system (bash AST parser, path globs, default ruleset). Config example at .pi/guard.example.json."
+    }
+  ]
+}

package/dist/template/.pi/prompts/audit.md

@@ -39,6 +39,7 @@ Find all occurrences of a code pattern in the codebase, review each for issues,
 | `security-and-hardening` | Pattern involves auth, secrets, validation, input | Identify vulnerability patterns in audited code |
 | `code-review-and-quality` | Occurrences > 5 | Assess correctness and structural quality across results |
 | `fallow` | Occurrences > 20 or scope is project-wide | Structural analysis for dead code, duplication, complexity |
+| `dcp-hygiene` | Output (after workflow execution) | Compress closed grep+read occurrence output when `compress` is available |
 
 ## Execution
 
@@ -67,7 +68,7 @@ For small audits, execute directly without workflow overhead:
 
 | Scenario | Action |
 |----------|--------|
-| Workflow phase fails | Retry once with adjusted prompt, then escalate |
+| Workflow phase fails | Retry once with adjusted prompt, then escalate. If retry also fails, **save the failure** to `memory(action: "add", target: "failure", category: "failure")` — the pattern, scope, and what went wrong. |
 | No occurrences found | Report: "Pattern not found in codebase." |
 | Audit timeout | Report partial results with what was covered |
 | Subagent returns failure | Read error, retry once, then escalate |
@@ -81,6 +82,8 @@ For small audits, execute directly without workflow overhead:
 
 ## Output
 
+> **DCP hygiene:** Before writing the final report, if the `compress` tool is available, compress the closed discovery work-stream (`semantic_grep` results + per-occurrence `read` output) per the `dcp-hygiene` skill — occurrences and findings are captured in the report and `.pi/artifacts/$SLUG/audit.md`. Skip if `compress` is unavailable.
+
 1. **Pattern:** [pattern searched]
 2. **Occurrences found:** [count]
 3. **Files affected:** [count]

package/dist/template/.pi/prompts/create.md

@@ -25,6 +25,7 @@ Before creating, verify:
 - If active slug exists with a `spec.md`, ask user: continue with `/ship` or start new?
 - Check `git status --porcelain` — if uncommitted changes, ask user to stash, commit, or continue
 - Use `vcc_recall` to search session history for prior decisions on this topic — avoid repeating explored/rejected approaches
+- Use `memory_search({ project: "$(cat .pi/artifacts/.active 2>/dev/null || echo '')" })` for durable prior decisions across sessions
 
 ## Load Skills
 

package/dist/template/.pi/prompts/fix.md

@@ -21,6 +21,7 @@ Systematically debug and fix the reported issue.
 
 Before fixing:
 - Use `vcc_recall` to search for prior fix attempts on the same issue — avoid repeating failed approaches
+- Use `memory_search({ query: "<issue keywords>", target: "failure", category: "failure" })` for durable cross-session failed approaches
 - Check that the codebase builds/tests pass at baseline (confirm the bug is not a pre-existing state)
 
 ## Load Skills
@@ -32,6 +33,7 @@ Before fixing:
 | `verification-before-completion` | Always | Evidence-before-claims; verify fix actually resolves the bug |
 | `defense-in-depth` | After fix is verified | Harden the layer so the bug becomes structurally impossible |
 | `testing-anti-patterns` | If writing tests | Ensure regression test isn't a mock-only test |
+| `dcp-hygiene` | Phase 5 Report | Compress the closed reproduce+isolate work-stream when `compress` is available |
 
 ## Phase 1: Reproduce
 
@@ -59,6 +61,8 @@ If `--attach` provided, read the attached log/error file for context.
 
 ## Phase 4: Verify
 
+> **DCP hygiene (mid-command):** The fix is applied — the root cause is now captured; the reproduce/isolate reads and greps are no longer needed verbatim. If `compress` is available, compress the closed Phase 1-2 reproduce+isolate work-stream per the `dcp-hygiene` skill before running gates. Keep the root cause (file:line) and reproduction command in the summary. Skip if `compress` is unavailable.
+
 Run verification gates:
 
 ```bash
@@ -80,7 +84,7 @@ Then, load `defense-in-depth` skill and add validation at the data entry layer.
 |----------|--------|
 | Cannot reproduce issue | Report reproduction steps attempted, ask for clarification |
 | Root cause ambiguous | Trace backward through call stack, add instrumentation |
-| Verification fails 2x | Stop, report blocker with learnings from both attempts |
+| Verification fails 2x | Stop, report blocker with learnings from both attempts. **Also:** save to `memory(action: "add", target: "failure", category: "failure", content: "[root cause + approach tried + error + reproduction]")` so future sessions don't repeat the failed approach. |
 | Fix causes regression | Revert fix, report regression with evidence |
 
 ## Stop Conditions
@@ -92,6 +96,8 @@ Then, load `defense-in-depth` skill and add validation at the data entry layer.
 
 ## Phase 5: Report
 
+> **DCP hygiene:** Before reporting, if the `compress` tool is available, compress the closed Phase 1-3 exploratory work-stream (reproduce bash + isolate grep/inspect/read output) per the `dcp-hygiene` skill — the root cause and fix are now captured in this report and the artifact. Skip if `compress` is unavailable; the artifact already holds the facts.
+
 1. Root cause (with file:line)
 2. Fix applied
 3. Verification results (typecheck, lint, test)

package/dist/template/.pi/prompts/gc.md

@@ -31,6 +31,7 @@ Run structural analysis, update quality grades, and open cleanup PRs.
 | `code-cleanup` | Phase 4 (cleanup PRs) | Safe code removal patterns |
 | `verification-before-completion` | After cleanup PRs | Verify typecheck + lint pass before merging |
 | `observability-and-instrumentation` | If removing instrumented code | Check that cleanup doesn't break monitoring/logging |
+| `dcp-hygiene` | Phase 5 Report | Compress the closed Fallow scan + grading output when `compress` is available |
 
 ## Execution
 
@@ -75,6 +76,8 @@ If `--dry-run` (default), skip actual cleanup and report what would be cleaned.
 
 ### Phase 5: Report
 
+> **DCP hygiene:** Before reporting, if the `compress` tool is available, compress the closed Phase 1-3 Fallow scan + grading output (the large JSON and finding lists) per the `dcp-hygiene` skill — grades and prioritized findings are captured in this report and `.pi/QUALITY.md`. Skip if `compress` is unavailable.
+
 1. **Quality Grades:** Per-domain status (before → after)
 2. **Issues Found:** Count by severity
 3. **Cleanup PRs:** Opened / not needed / skipped (dry-run)

package/dist/template/.pi/prompts/init.md

@@ -56,6 +56,7 @@ Before initializing:
 | `documentation-and-adrs` | Always (Mode 1) | Doc conventions, ADR format when architectural decisions arise |
 | `verification-before-completion` | Before writing AGENTS.md | Validate commands before documenting them |
 | `brainstorming` | Conditionally: when ambiguous requirements arise | Refine project vision before initializing |
+| `dcp-hygiene` | Output (after `--deep` runs) | Compress closed detection + srcwalk/fallow work-stream when `compress` is available |
 
 ---
 
@@ -171,6 +172,8 @@ Write to `.pi/user.md` with the captured preferences.
 
 ## Output
 
+> **DCP hygiene:** If `--deep` ran and `compress` is available, compress the closed Phase 1 detection + git-history + srcwalk/fallow work-stream per the `dcp-hygiene` skill — tech stack, validated commands, and structure are captured in `AGENTS.md` and `tech-stack.md`. Skip if `compress` is unavailable (non-deep init produces little output).
+
 Report what was created:
 1. AGENTS.md (if core setup ran)
 2. tech-stack.md (if core setup ran)

package/dist/template/.pi/prompts/plan.md

@@ -36,12 +36,13 @@ Before planning:
 | `incremental-implementation` | Always | Thin vertical slice discipline — each task is verify-after-each |
 | `subagent-driven-development` | Multi-wave plan | Plan tasks for fresh subagent dispatch per task |
 | `source-driven-development` | Level 1-3 | Ground decisions in official docs when researching dependencies |
+| `dcp-hygiene` | Phase 8 Report | Compress closed git-history + research work-stream when `compress` is available |
 
 ## Phase 0: Institutional Research (Mandatory)
 
 ### Step 1: Search institutional memory
 
-Use `vcc_recall` to search for bugfixes and existing plans. If relevant observations found, incorporate them.
+Use `vcc_recall` to search for bugfixes and existing plans. Also use `memory_search({ query: "<plan topic>", target: "failure", category: "insight" })` for durable institutional knowledge. If relevant observations found, incorporate them.
 
 ### Step 2: Mine git history
 
@@ -216,7 +217,7 @@ Scan plan against AGENTS.md hard constraints:
 | Plan already exists | Ask user: overwrite or skip? |
 | Missing spec artifact | Report: "No spec found. Run `/create` first." |
 | Subagent research fails | Retry once with adjusted prompt, then proceed with existing knowledge |
-| Verification fails 2x | Stop, report blocker with file:line evidence |
+| Verification fails 2x | Stop, report blocker with file:line evidence. **Also:** save the failed approach to `memory(action: "add", target: "failure", category: "failure")` — the plan decomposition or approach that failed, and why. |
 
 ## Stop Conditions
 
@@ -227,6 +228,8 @@ Scan plan against AGENTS.md hard constraints:
 
 ## Phase 8: Report
 
+> **DCP hygiene:** Before reporting, if the `compress` tool is available, compress the closed Phase 0-2 institutional-research + git-history + scout work-stream per the `dcp-hygiene` skill — observable truths, artifacts, and dependency waves are captured in `plan.md` and `tasks.json`. Skip if `compress` is unavailable.
+
 1. **Discovery Level:** [0-3] with rationale
 2. **Must-Haves:** [N] observable truths, [M] required artifacts, [K] key links
 3. **Context Budget:** [Estimated usage]

package/dist/template/.pi/prompts/research.md

@@ -62,6 +62,7 @@ Before starting, analyze the research topic complexity:
 | `srcwalk` | Codebase research | Navigate codebase with repo maps, symbol search, callers/callees |
 | `opensrc` | Researching dependencies | Inspect library source for internal behavior |
 | `gemini-large-context` | Large codebase or multi-repo | Analyze beyond typical context limits |
+| `dcp-hygiene` | Phase 3 Synthesize (+ mid-research if `--thorough`) | Compress closed search/verify work-streams when `compress` is available |
 
 ## Direct Execution (Simple Research)
 
@@ -82,6 +83,8 @@ Cross-check findings:
 
 ### Phase 3: Synthesize
 
+> **DCP hygiene:** If `compress` is available, compress the closed Phase 1-2 search/verify work-stream per the `dcp-hygiene` skill — questions, answers, confidence, and sources are captured in the findings. For `--thorough` (~100+ calls), compress every ~30 calls mid-research to keep context bounded. Skip if `compress` is unavailable.
+
 If within active work, write findings to `.pi/artifacts/$SLUG/research.md`. Otherwise report inline.
 
 ## Workflow Execution (Complex Research)

package/dist/template/.pi/prompts/ship.md

@@ -21,6 +21,7 @@ Execute spec tasks, verify each passes, run review, mark complete.
 
 Before shipping:
 - Use `vcc_recall` to search for failed approaches to avoid repeating
+- Use `memory_search({ query: "<feature keywords>", target: "failure", category: "failure" })` for durable cross-session failures and prior decisions
 - Verify `.pi/artifacts/$(cat .pi/artifacts/.active)/spec.md` exists (if not, tell user to run `/create` first)
 - If `plan.md` exists, verify it references the current spec
 - Workspace check: create branch if needed, install deps if needed
@@ -37,6 +38,7 @@ Before shipping:
 | `code-review-and-quality` | Phase 5 review | 5-axis review: correctness, readability, architecture, security, performance |
 | `doubt-driven-development` | High-risk features | In-flight adversarial review before merge |
 | `context-engineering` | Batch workflow (≥5 independent tasks) | Context budget management for parallel subagent handoffs |
+| `dcp-hygiene` | Phase 7 Report (+ Phase 2/3→4 transition) | Compress closed implement/verify work-streams when `compress` is available |
 
 ## Phase 1: Route to Execution
 
@@ -118,6 +120,8 @@ If routed to workflow mode:
 
 ## Phase 4: Verification Gate
 
+> **DCP hygiene (mid-command):** Implementation is complete — the diff is now the source of truth, not the edit/read history. If `compress` is available, compress the closed Phase 2/3 implementation work-stream (file reads + edits) per the `dcp-hygiene` skill before running gates. Keep task results, commits, and affected-file lists in the summary. Skip if `compress` is unavailable.
+
 **Delegate to `/verify` — do not duplicate the gate logic here.** Run the canonical verification protocol defined in `prompts/verify.md` (Phase 1 Completeness → Phase 2 Correctness → Phase 4 Phantom Detection). Concretely:
 
 1. Invoke `/verify all --full` semantics (or run the same steps inline if already mid-session): load `verification-before-completion`, run typecheck + lint + test gates, use **full mode** for shipping (incremental is for iteration only), record stamp to `.pi/artifacts/verify.log` after all gates pass, run phantom completion detection, and do goal-backward verification (observable truths from plan/spec satisfied).
@@ -182,7 +186,7 @@ Ask user before closing. If confirmed:
 
 | Scenario | Action |
 |----------|--------|
-| Task verification fails 2x | Stop, report blocker with file:line evidence |
+| Task verification fails 2x | Stop, report blocker with file:line evidence. **Also:** save the failed approach to `memory(action: "add", target: "failure", category: "failure")` — what was tried, why it failed, the error, and the task description. |
 | Subagent returns failure | Read error, retry once with adjusted prompt, then escalate |
 | Review finds critical issue | Fix inline, re-run Phase 4, continue |
 | Batch workflow failure | Fall back to sequential execution |
@@ -190,6 +194,8 @@ Ask user before closing. If confirmed:
 
 ## Phase 7: Report
 
+> **DCP hygiene:** Before reporting, if the `compress` tool is available, compress the closed implementation + verification work-stream (file reads, edits, gate bash output) per the `dcp-hygiene` skill — task results, commits, and gate results are captured in this report and `progress.md`. Skip if `compress` is unavailable.
+
 1. **Execution Summary:** tasks completed/total, waves executed, commits made
 2. **Task Results:** per-task status, files modified, commit hashes
 3. **Verification Gate Results:** typecheck, lint, test, build — pass/fail

package/dist/template/.pi/prompts/verify.md

@@ -41,6 +41,7 @@ Check implementation against PRD before shipping.
 | `verification-before-completion` | Always | Evidence-before-claims; phantom detection; verification cache protocol; Worker Distrust Protocol |
 | `code-review-and-quality` | Phase 4 coherence check | Cross-reference artifacts for correctness |
 | `testing-anti-patterns` | Phase 3 after tests pass | Detect mock-only tests, production pollution, and fragile assertions |
+| `dcp-hygiene` | Phase 5 Report | Compress the closed gate output (typecheck/lint/test) when `compress` is available |
 
 ## Phase 0: Verification Cache
 
@@ -115,7 +116,7 @@ Load `verification-before-completion` skill. Follow its phantom completion detec
 | Scenario | Action |
 |----------|--------|
 | Gate fails | Report which gate failed with exact error |
-| Verification fails 2x | Stop, report blocker with file:line evidence |
+| Verification fails 2x | Stop, report blocker with file:line evidence. **Also:** save the failure to `memory(action: "add", target: "failure", category: "failure")` — the gate that failed, the error, and what was tried. |
 | Cache stamp mismatch | Run gates fresh — don't reuse stale cache |
 | Phantom artifacts detected | Report PHANTOM score, block completion |
 
@@ -128,6 +129,8 @@ Load `verification-before-completion` skill. Follow its phantom completion detec
 
 ## Phase 5: Report
 
+> **DCP hygiene:** Before reporting, if the `compress` tool is available, compress the closed Phase 2 gate output (typecheck/lint/test/bash) per the `dcp-hygiene` skill — results are recorded in the report table and the verification cache. Skip if `compress` is unavailable.
+
 Append to `.pi/artifacts/$SLUG/progress.md`: `Verification: [PASS|PARTIAL|FAIL] - [summary]`
 
 1. **Result**: READY TO SHIP / NEEDS WORK / BLOCKED

package/dist/template/.pi/skills/INDEX.md

@@ -48,6 +48,8 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | docs, documentation, README, ADR, changelog | `documentation-and-adrs` |
 | commit, branch, merge, rebase, git, worktree | `git-workflow-and-versioning`, `using-git-worktrees` |
 | context, memory, token, agent quality, degraded | `context-engineering` |
+| memory_system, memory-search, memory_search, pi-hermes, /memory-insights, save memory, remember this, past failure, previous attempt | `memory-system` |
+| compress, dcp, context prune, cleanup context, context filling up | `context-engineering`, `dcp-hygiene` |
 | brainstorm, idea, design, concept, explore, ideate, refine | `brainstorming`, `idea-refine`, `spec-driven-development` |
 | interview, grill, are we sure, what do you want | `interview-me` |
 | plan, break down, decompose, tasks, roadmap | `planning-and-task-breakdown` |
@@ -98,6 +100,8 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | `deprecation-and-migration` | Deprecating APIs, migrating library versions, removing legacy code | Ship | High |
 | `writing-skills` | Creating new skills, editing existing skills, verifying skills before deployment | Build | Low |
 | `context-engineering` | Optimizing agent context setup — rules files, selective loading, confusion management | All | Low |
+| `dcp-hygiene` | At command/phase closure — compress closed exploratory work-streams via pi-dcp when `compress` is available; no-ops if DCP absent | All | Low |
+| `memory-system` | Understanding/leveraging pi-hermes-memory — auto-flywheel, tools, commands, when to use memory_search vs vcc_recall | All | Low |
 | `doubt-driven-development` | In-flight adversarial review of non-trivial decisions before they stand | Build | Medium |
 | `loop-engineering` | Designing/qualifying/running unattended coding loops; 2-condition test + VISION/state + confidence-gated action | All | Medium |
 | `loop-audit` | Scoring a project's loop-readiness 0-100 + L0/L1/L2/L3; L3 gated on proven run | Review | Low |
@@ -214,6 +218,8 @@ Maps user intent to skill(s). `→` = sequential pipeline (execute in order). `+
 | "set up database" / "Supabase" | `supabase` + `supabase-postgres-best-practices` | Build | High |
 | "add logging" / "monitoring" / "observability" | `observability-and-instrumentation` | Ship | Medium |
 | "optimize context" / "agent quality degraded" / "too many tokens" | `context-engineering` | All | Low |
+| "remember this" / "memory-search" / "past failure" / "previous attempt" / "save to memory" | `memory-system` | All | Low |
+| "compress context" / "dcp" / "context filling up" / "cleanup context" | `dcp-hygiene` | All | Low |
 | "verify this approach" / "challenge this decision" / "doubt check" | `doubt-driven-development` | Build | Medium |
 | "security audit" / "auth setup" / "vulnerability" | `security-and-hardening` | Review | High |
 | "profile" / "too slow" / "bundle size" / "lighthouse" | `performance-optimization` | Review | Medium |

package/dist/template/.pi/skills/dcp-hygiene/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: dcp-hygiene
+description: "Use at command/phase closure points to compress closed exploratory work-streams via the pi-dcp `compress` tool, preserving file:line refs, root causes, decisions, and verification results in the summary. No-ops gracefully when DCP is not installed."
+---
+
+# DCP Hygiene
+
+## When to Use
+
+- A slash command's Report/Closure phase just finished writing its artifact (spec.md, plan.md, progress.md, fix.md, audit.md, research.md, etc.) — the exploratory tool output (reads, greps, bash) that produced it is now closed.
+- A long command transitions between phases and the previous phase's detailed output is captured in the next phase's input or an artifact.
+- A workflow loop iteration (e.g. quality-loop) finishes a fix cycle and is about to re-review — accumulated output can be compressed before the next round.
+
+## When NOT to Use
+
+- The `compress` tool is not registered (DCP extension not installed, or `compress.permission: "deny"`) — see No-op clause below.
+- The work-stream is still in-flight or spans your most recent turn — DCP turn protection (last 3 turns) already refuses these; don't try.
+- The user just asked about the content you'd be compressing — they still need it verbatim.
+- The command is read-only/scaffold and produced almost no tool output (`/status`, `/close`, `/loop-init`, `/loop-check`, `/loop-review`) — compressing near-empty streams wastes more tokens than it saves.
+- Inside orchestrator workflows' phase prompts — subagents carry their own context; only the orchestrator's accumulated summaries matter, and those are bounded by "Keep under N words" per prompt.
+
+## Core Principle
+
+**Compress closed work, preserve the facts that produced it.**
+
+A compress call only pays off when (a) the tool output is genuinely closed and (b) the summary keeps every fact a later turn might need. A lossy summary that drops a file:line or a root cause is worse than no compression — it forces a re-read.
+
+## The Compress Protocol (range mode)
+
+DCP's default `compress.mode` is `"range"` — pass the FIRST and LAST tool-call IDs of the closed span.
+
+1. **Identify the closed span** — the contiguous block of tool calls from the start of the just-completed phase/section up to (but not including) the current in-flight turn.
+2. **Pick endpoints** — `startToolCallId` = first call of the span, `endToolCallId` = last call of the span. Everything between (inclusive) is summarized, except protected tools (write/edit/todo/task/skill/compress) which are appended verbatim.
+3. **Never pick endpoints inside your most recent turn or in-flight work** — DCP refuses these upfront; respect the boundary.
+4. **Write a lossless-but-terse summary** in the `summary` argument. Include:
+   - What was accomplished (one line)
+   - **Concrete facts**: file paths, line numbers, error messages, decisions made
+   - Root cause / diagnosis (for `/fix`)
+   - Verification results (for `/verify`, `/ship`)
+   - What is still open / unresolved
+5. **The replacement applies on the next LLM request** — your current turn still sees the originals, so you can read them while writing the summary.
+
+## What to Preserve (per command)
+
+| Command | Must keep in summary |
+|---------|----------------------|
+| `/fix` | root cause with file:line, fix applied, verification results |
+| `/verify` | gate results (typecheck/lint/test pass/fail), completeness score, phantom score |
+| `/ship` | tasks completed/total, commits made, verification gate results, review summary |
+| `/gc` | quality grades (before→after), issue counts by severity, PRs opened |
+| `/audit` | pattern, occurrence count, issues by severity with file:line, recommended fixes |
+| `/research` | questions, answer status + confidence, key insights, sources |
+| `/plan` | discovery level, observable truths, required artifacts, dependency waves |
+| `/init` | detected tech stack, validated commands, created files |
+
+## What NEVER to Compress
+
+- Your most recent turn (turn protection: last 3 turns are immune anyway).
+- In-flight work — anything you're still actively reading/editing.
+- Content the user just referenced in their last message.
+- Protected tools' output (write/edit/todo/task/skill/compress) — DCP appends these verbatim regardless, so don't exclude them from your span; just know they survive.
+
+## No-op Clause (portability)
+
+This skill must work whether or not DCP is installed:
+
+- If the `compress` tool is **not available** in the current tool set, **skip compression entirely**. The artifact (spec.md/plan.md/progress.md/etc.) already captures the durable facts — skipping is correct, not a failure.
+- If `compress` is available but the closed span is tiny (< ~5 tool calls, < ~2k tokens of output), the compress call costs more than it saves — skip.
+- Never error or retry on a missing `compress` tool. Treat it as an optional optimization.
+
+## Procedure
+
+### At a closure point
+
+1. Confirm the work-stream is actually closed (artifact written OR next phase already has the summary it needs).
+2. Check: is `compress` available? If no → stop here, report "DCP not installed — skipped, artifact captures facts."
+3. Check: is the span worth it? (≥ ~5 tool calls, ≥ ~2k tokens). If no → skip.
+4. Call `compress({ startToolCallId, endToolCallId, topic, summary })` with a terse, lossless summary preserving the table above.
+5. Continue to the next phase/command. The compression applies on the next request.
+
+### At a mid-command phase transition (long commands only: `/ship`, `/fix`, `quality-loop`)
+
+1. Confirm the previous phase's output is fully consumed by the next phase's input (the next prompt references `{phase_N_output}` or the artifact).
+2. Compress the previous phase's exploratory calls (reads/greps/bash), NOT the phase output summary itself if it's about to be passed forward.
+3. Proceed to the next phase.
+
+## Pitfalls
+
+- **Compressing too early** — before the artifact is written — loses the facts with nowhere captured. Always write the artifact first, then compress what produced it.
+- **Lossy summaries** — dropping file:line or "because" clauses forces expensive re-reads. Terse ≠ incomplete.
+- **Compressing the phase output you're about to pass forward** — the next phase needs it. Compress the *exploratory calls* that produced the output, not the output itself.
+- **Forcing compress when DCP is absent** — errors and wastes a turn. The no-op is the correct behavior.
+- **Compressing inside turn protection** — DCP refuses; don't try to work around it.
+- **Over-compressing short commands** — a 3-call `/status` has nothing worth compressing.
+
+## Verification
+
+Before claiming a compress was done correctly:
+
+- [ ] `compress` tool was available (else no-op was the correct outcome)
+- [ ] The compressed span was genuinely closed (artifact written or output consumed)
+- [ ] Summary preserves file:line, root cause/decisions, verification results per the table above
+- [ ] No endpoint landed inside the most recent turn or in-flight work
+- [ ] The next phase/command still has everything it needs (no forced re-reads)
+
+If `compress` was unavailable and you skipped — that's a successful no-op, not a failure. Report "DCP not installed — artifact captures facts; skipped compression."

package/dist/template/.pi/skills/memory-system/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: memory-system
+description: "Documents pi-hermes-memory capabilities: background auto-review, correction detection, tools (memory, memory_search, session_search), and commands. Load when the agent needs to understand or leverage the memory system — searching past failures, saving learnings, or learning the auto-flywheel."
+---
+
+# Memory System (pi-hermes-memory)
+
+## Overview
+
+pi-hermes-memory is the **persistent memory extension** that runs automatically in every pi session. It provides a self-learning flywheel without the agent needing to trigger it manually. This skill documents its capabilities so the agent can leverage them strategically.
+
+## Auto-Flywheel (already running — no trigger needed)
+
+### 1. Background Review — automated "compound" every ~10 turns
+
+Every N turns (default: 10) OR after accumulating enough tool calls, pi-hermes-memory spawns a background child process that:
+
+- Snaps the full conversation as `[USER]`/`[ASSISTANT]` prefixed text
+- Reviews for: user preferences, corrections, failures, insights, conventions, tool-quirks  
+- Saves notable findings to `MEMORY.md`, `USER.md`, or `failures.md`
+- Only acts if there's something genuinely worth saving ("Nothing to save." otherwise)
+- Non-blocking — the session continues while the review runs
+
+**→ You do NOT need to call this yourself.** It fires automatically on `turn_end`.
+
+### 2. Correction Detection — real-time error learning
+
+On every user message, pi-hermes-memory checks for correction patterns:
+
+| Strength | Patterns | Example |
+|----------|----------|---------|
+| **Strong** (always trigger) | `"don't do that"`, `"not like that"`, `"I said..."`, `"I told you..."`, `"that's not what I..."` | "Don't do that — use pnpm instead" |
+| **Weak** (needs directive) | `"no, ..."`, `"wrong, ..."`, `"actually..."` + verb like "use", "change", "fix" | "No, use the other approach" |
+| **Negative** (suppress) | `"no worries"`, `"no problem"`, `"actually looks great"` | Ignored |
+
+When detected → immediately saves to `target='failure', category='correction'` with the reason "User corrected the agent".
+
+**→ Corrections are captured automatically.** You don't need to save them — it's already done.
+
+### 3. Session Flush
+
+Before session compaction/shutdown, a flush prompt extracts anything worth remembering from the closing session.
+
+### 4. Auto-Consolidation
+
+When `MEMORY.md` reaches the 5,000 character limit, entries are auto-merged, deduped, and staled entries (>30 days, unreferenced) are removed.
+
+## Tools Available (agent can call)
+
+| Tool | Purpose | Key params |
+|------|---------|------------|
+| `memory` | Save/update/delete memories | `action` (add/replace/remove), `target` (memory/user/failure/project), `content`, `category` |
+| `memory_search` | Search durable memories across sessions | `query`, `target`, `category`, `project` |
+| `session_search` | Search past conversation messages | `query`, `project`, `role` |
+| `skill_manage` | Create/update procedural skills | `action`, `name`, `scope`, `when_to_use`, `procedure_steps` |
+
+## Memory Categories (for `target='failure'`)
+
+| Category | When to use | Example |
+|----------|------------|---------|
+| `failure` | Something tried that didn't work | "Used localStorage for tokens — XSS vulnerability" |
+| `correction` | User corrected the agent | "Use pnpm, not npm" |
+| `insight` | Durable learning from experience | "Complexity over 15 in a single function causes CI timeout" |
+| `preference` | User preference or work style | "Prefers terse responses, no cheerleading" |
+| `convention` | Project or team convention | "Monorepo with turborepo, uses pnpm workspaces" |
+| `tool-quirk` | Non-obvious tool behavior | "tsc --noEmit fails silently on .d.ts syntax errors" |
+
+## Commands Available (user can run)
+
+| Command | Purpose |
+|---------|---------|
+| `/memory-insights` | Show everything stored in memory |
+| `/memory-skills` | List all saved procedural skills |
+| `/memory-consolidate` | Manually trigger memory cleanup/merge |
+| `/memory-interview` | Onboarding interview to pre-fill user profile |
+| `/memory-switch-project` | List all project memories |
+| `/memory-index-sessions` | Import past sessions for search |
+| `/memory-sync-markdown` | Backfill Markdown entries into SQLite search |
+| `/memory-preview-context` | Show memory policy or legacy prompt blocks |
+| `/learn-memory-tool` | Interactive guide to the memory system |
+
+## When to Use memory_search
+
+Use `memory_search` when you need **durable, cross-session knowledge** — things that happened in previous sessions, not just the current one:
+
+- **Searching past failures**: `memory_search({ query: "similar error", target: "failure", category: "failure" })`
+- **Finding project conventions**: `memory_search({ query: "typescript pattern", project: "<project>" })`
+- **Recalling user preferences**: `memory_search({ query: "prefers", target: "user" })`
+- **Checking tool quirks**: `memory_search({ query: "pnpm install", category: "tool-quirk" })`
+
+Use `vcc_recall` when you need **current-session lineage** — what was just discussed or tried in this active workflow.
+
+Use both together in Guard phases for maximum recall coverage.
+
+## When to Explicitly Save (manual `memory` tool)
+
+Even though auto-review runs every 10 turns, manually save when:
+
+- **On 2x verification failure** — save the failed approach immediately so future sessions won't repeat it. Use `target='failure', category='failure'` with: what was tried, why it failed, the error, and what worked instead (if known).
+- **On a critical discovery** — if you learn something that would save 15+ minutes for future-self, don't wait for the auto-review cycle.
+- **On user's explicit request** — "remember this" → save immediately.
+- **On learning a tool-quirk** — non-obvious behavior that would trip up a future agent.
+
+## Pitfalls
+
+- **Waiting for auto-review for critical failures** — if verification just failed 2x, save that failure NOW. The auto-review might not fire for 10 more turns.
+- **Using vcc_recall for cross-session knowledge** — vcc_recall is lineage-scoped (active session); it may not find failures from a closed session. Use `memory_search` instead.
+- **Over-saving** — don't save task progress, session outcomes, or temporary state. The auto-review already captures durable learnings. Manual saves are for URGENT or USER-REQUESTED facts only.
+- **Assuming memory_search has everything** — if the SQLite sync is broken (the memory-sync-markdown command can fix this), older Markdown entries may not appear in search. The `/memory-sync-markdown` command backfills them.
+
+## Verification
+
+Before relying on memory_search:
+
+- [ ] Check if the SQLite sync is healthy (`/memory-insights` shows recent entries)
+- [ ] If search returns nothing but you KNOW the info was saved, run `/memory-sync-markdown` 
+- [ ] Use both `memory_search` AND `vcc_recall` in Guard phases for dual coverage
+- [ ] When saving a failure, include: what was tried, why it failed, the error message, reproduction steps

package/dist/template/.pi/workflows/quality-loop.md

@@ -170,6 +170,8 @@ Score-gated, review-driven feedback loop for high-risk features. Runs iterative
 - **Concurrency:** 1
 - **Depends on:** Phase 6
 - **Prompt:**
+  > **DCP hygiene (loop iteration):** This loop runs up to 5 rounds — context accumulates across iterations. Before re-reviewing, if `compress` is available, compress this iteration's closed Phase 6 fix work-stream (file reads + edits) per the `dcp-hygiene` skill. Keep the finding fixed (file:line), the fix applied, and the verification result in the summary; drop the exploratory reads. Skip if `compress` is unavailable.
+
   Loop back to Phase 2. The implementation has been updated based on review findings. Spawn a fresh review agent with the updated diff and spec.
 
   ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhduydev/mdpi",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "CLI to scaffold and manage a Pi coding-agent kit (.pi/) in any repo",
   "keywords": [
     "pi",