@minhduydev/mdpi 0.3.0

package/dist/template/.pi/extensions/templates-injector.ts

@@ -0,0 +1,76 @@
+/**
+ * Templates Injector Extension
+ *
+ * Auto-injects project context files into system prompt.
+ * Auto-injects project context files into system prompt via pi's before_agent_start hook.
+ *
+ * Resolution: prefer the LIVE file at `.pi/{name}` (filled by /init, the project's
+ * real state/stack/vision); fall back to the blank seed at `.pi/templates/{name}`
+ * when no live file exists. This keeps templates/ pristine as deliverables while
+ * ensuring real project state is what the agent actually sees.
+ *
+ * Auto-injected (always, whichever resolves):
+ * - project.md
+ * - tech-stack.md
+ * - state.md   ← the "you are here" marker; live version injected once /init fills it
+ *
+ * User can opt-in to inject more via /inject-template command.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const ALWAYS_INJECT = ["project.md", "tech-stack.md", "state.md"];
+
+function readTemplate(cwd: string, name: string): string | null {
+	// Prefer live file at .pi/{name} (filled by /init — real project state);
+	// fall back to blank seed at .pi/templates/{name} when no live file exists.
+	const livePath = path.join(cwd, ".pi", name);
+	const seedPath = path.join(cwd, ".pi", "templates", name);
+	const filePath = fs.existsSync(livePath) ? livePath : seedPath;
+	if (!fs.existsSync(filePath)) return null;
+	const content = fs.readFileSync(filePath, "utf-8");
+	// Strip frontmatter for injection
+	const fmMatch = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+	return (fmMatch ? fmMatch[1] : content).trim();
+}
+
+export default function templatesInjector(pi: ExtensionAPI) {
+	pi.on("before_agent_start", async (event, ctx) => {
+		const injected: string[] = [];
+
+		for (const name of ALWAYS_INJECT) {
+			const content = readTemplate(ctx.cwd, name);
+			if (content && content.length > 0) {
+				injected.push(`### ${name}\n\n${content}`);
+			}
+		}
+
+		if (injected.length === 0) return;
+
+		return {
+			systemPrompt:
+				event.systemPrompt +
+				`\n\n## Project Context (auto-injected from .pi/ — live state/stack/vision, seeded by .pi/templates/)\n\n${injected.join("\n\n---\n\n")}`,
+		};
+	});
+
+	pi.registerCommand("inject-template", {
+		description: "Inject a template into current context",
+		handler: async (args, ctx) => {
+			const name = args.trim() || (await ctx.ui.select("Choose template", fs.readdirSync(path.join(ctx.cwd, ".pi", "templates")).filter((f) => f.endsWith(".md"))));
+			if (!name) return;
+
+			const content = readTemplate(ctx.cwd, name);
+			if (!content) {
+				ctx.ui.notify(`Template not found: ${name}`, "warning");
+				return;
+			}
+
+			// Inject via sendUserMessage as a context message
+			pi.sendUserMessage(`[Template: ${name}]\n\n${content}`, { deliverAs: "followUp" });
+			ctx.ui.notify(`Injected template: ${name}`, "info");
+		},
+	});
+}

package/dist/template/.pi/extensions/workflows-runner.ts

@@ -0,0 +1,301 @@
+/**
+ * Workflows Runner Extension
+ *
+ * Executes DAG workflows from `.pi/workflows/*.md` using pi's subagent tool.
+ * Supports sequential phases, parallel tasks, and dynamic concurrency.
+ *
+ * Architecture: The extension parses workflow DAG, validates args, and returns
+ * an execution plan with concrete `task()` calls the LLM must execute in order.
+ * Subagent dispatch is the LLM's responsibility (extensions cannot spawn subagents
+ * directly in pi-coding-agent).
+ *
+ * Usage:
+ * - Place at `.pi/extensions/workflows-runner.ts`
+ * - Workflows loaded from `.pi/workflows/*.md`
+ * - Invoke via `run_workflow` tool or `/workflow` command
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+interface WorkflowPhase {
+	num: number;
+	name: string;
+	agent?: string;
+	workflow?: string;
+	concurrency: number | { rule: string };
+	dependsOn: number[];
+	prompt: string;
+}
+
+interface Workflow {
+	name: string;
+	description: string;
+	args: Array<{ name: string; required: boolean; description: string }>;
+	phases: WorkflowPhase[];
+}
+
+function parseWorkflow(content: string): Omit<Workflow, "name"> {
+	const phases: WorkflowPhase[] = [];
+	const phaseRegex = /### Phase (\d+): ([^\n]+)\n([\s\S]*?)(?=### Phase|\n## |\s*$)/g;
+	let match: RegExpExecArray | null;
+
+	while ((match = phaseRegex.exec(content)) !== null) {
+		const num = parseInt(match[1], 10);
+		const name = match[2].trim();
+		const body = match[3];
+
+		const agentMatch = body.match(/\*\*Agent:\*\*\s*@?(\w+)/);
+		const workflowMatch = body.match(/\*\*Workflow:\*\*\s*(\S+)/);
+		const concMatch = body.match(/\*\*Concurrency:\*\*\s*(\d+|Dynamic[^)]*\))/);
+		const dependsMatch = body.match(/\*\*Depends on:\*\*\s*Phase\s+(\d+)/);
+		const promptMatch = body.match(/\*\*Prompt:\*\*\s*\n+\s*([\s\S]*?)$/);
+
+		let concurrency: number | { rule: string } = 1;
+		if (concMatch) {
+			if (concMatch[1].startsWith("Dynamic")) {
+				concurrency = { rule: concMatch[1] };
+			} else {
+				concurrency = parseInt(concMatch[1], 10);
+			}
+		}
+
+		phases.push({
+			num,
+			name,
+			agent: agentMatch?.[1],
+			workflow: workflowMatch?.[1],
+			concurrency,
+			dependsOn: dependsMatch ? [parseInt(dependsMatch[1], 10)] : [],
+			prompt: promptMatch?.[1]?.trim() ?? "",
+		});
+	}
+
+	const argsMatch = content.match(/## Args\n([\s\S]*?)(?=\n## )/);
+	const args: Workflow["args"] = [];
+	if (argsMatch) {
+		const argRegex = /- `(\w+)` \((required|optional)\) — (.+)/g;
+		let am: RegExpExecArray | null;
+		while ((am = argRegex.exec(argsMatch[1])) !== null) {
+			args.push({
+				name: am[1],
+				required: am[2] === "required",
+				description: am[3],
+			});
+		}
+	}
+
+	const descMatch = content.match(/^# \w+\n\n([^#]+)/);
+	const description = descMatch?.[1]?.trim() ?? "";
+
+	return { description, args, phases };
+}
+
+function resolveConcurrency(
+	spec: number | { rule: string },
+	defaultCount: number,
+): number {
+	if (typeof spec === "number") return spec;
+	const rule = spec.rule;
+	const minMatch = rule.match(/min\s+(\d+)/);
+	const maxMatch = rule.match(/max\s+(\d+)/);
+	const min = minMatch ? parseInt(minMatch[1], 10) : 1;
+	const max = maxMatch ? parseInt(maxMatch[1], 10) : 10;
+	return Math.max(min, Math.min(max, defaultCount));
+}
+
+function loadWorkflows(workflowsDir: string): Workflow[] {
+	if (!fs.existsSync(workflowsDir)) return [];
+	const workflows: Workflow[] = [];
+	for (const file of fs.readdirSync(workflowsDir)) {
+		if (!file.endsWith(".md")) continue;
+		const content = fs.readFileSync(path.join(workflowsDir, file), "utf-8");
+		const name = path.basename(file, ".md");
+		const parsed = parseWorkflow(content);
+		workflows.push({ name, ...parsed });
+	}
+	return workflows;
+}
+
+/** Substitute placeholders in a prompt template. */
+function substitute(
+	template: string,
+	args: Record<string, string>,
+	phaseOutputs: Record<number, string>,
+): string {
+	return template
+		.replace(/\{(\w+)\}/g, (_, key) => args[key] ?? `{${key}}`)
+		.replace(/\{phase_(\d+)_output\}/g, (_, n) => {
+			const idx = parseInt(n, 10);
+			return phaseOutputs[idx] ?? `[phase ${idx} output pending]`;
+		});
+}
+
+/** Build a concrete execution plan the LLM can execute step-by-step. */
+function buildExecutionPlan(
+	wf: Workflow,
+	providedArgs: Record<string, string>,
+): string {
+	// Topological sort
+	const sorted: WorkflowPhase[] = [];
+	const visited = new Set<number>();
+	const visit = (phase: WorkflowPhase) => {
+		if (visited.has(phase.num)) return;
+		visited.add(phase.num);
+		for (const dep of phase.dependsOn) {
+			const depPhase = wf.phases.find((p) => p.num === dep);
+			if (depPhase) visit(depPhase);
+		}
+		sorted.push(phase);
+	};
+	for (const phase of wf.phases) visit(phase);
+
+	const lines: string[] = [];
+	lines.push(`# Workflow: \`${wf.name}\``);
+	lines.push("");
+	lines.push(wf.description);
+	lines.push("");
+	lines.push("## Execution Plan");
+	lines.push("");
+	lines.push("**Instructions for the assistant:** Execute each phase in order. For each phase with an `Agent` and concurrency ≥ 1, call the `task()` tool (or `subagent` tool if available) with the listed arguments. Collect outputs and substitute into subsequent phases via `{phase_N_output}`.");
+	lines.push("");
+
+	const phaseOutputs: Record<number, string> = {};
+
+	for (const phase of sorted) {
+		lines.push(`### Phase ${phase.num}: ${phase.name}`);
+		lines.push("");
+
+		if (phase.workflow) {
+			lines.push(`- **Type:** Sub-workflow composition (\`${phase.workflow}\`)`);
+			lines.push(`- **Action:** Invoke \`run_workflow\` tool with \`name: "${phase.workflow}\`, passing current \`{arg}\` values.`);
+			lines.push(`- **Output placeholder:** \`{phase_${phase.num}_output}\``);
+			lines.push("");
+			continue;
+		}
+
+		if (!phase.agent) {
+			lines.push(`- **Type:** Skip (no agent defined)`);
+			lines.push(`- **Action:** None.`);
+			lines.push("");
+			continue;
+		}
+
+		const concurrency =
+			typeof phase.concurrency === "number"
+				? phase.concurrency
+				: resolveConcurrency(phase.concurrency, 1);
+
+		const substitutedPrompt = substitute(phase.prompt, providedArgs, phaseOutputs);
+
+		lines.push(`- **Agent:** \`${phase.agent}\``);
+		lines.push(`- **Concurrency:** ${concurrency} (${concurrency === 1 ? "sequential" : "parallel"})`);
+		if (phase.dependsOn.length > 0) {
+			lines.push(`- **Depends on:** Phase ${phase.dependsOn.join(", ")}`);
+		}
+		lines.push(`- **Output placeholder:** \`{phase_${phase.num}_output}\``);
+		lines.push("");
+		lines.push("**Prompt to send:**");
+		lines.push("```");
+		lines.push(substitutedPrompt);
+		lines.push("```");
+		lines.push("");
+		lines.push(`**Tool call (${concurrency}× in ${concurrency === 1 ? "sequence" : "parallel"}):**`);
+		if (concurrency === 1) {
+			lines.push("```");
+			lines.push(`task({`);
+			lines.push(`  subagent_type: "${phase.agent}",`);
+			lines.push(`  prompt: <the prompt above>`);
+			lines.push(`})`);
+			lines.push("```");
+		} else {
+			lines.push("```");
+			lines.push(`Promise.all([`);
+			for (let i = 0; i < concurrency; i++) {
+				const variant = phase.prompt.includes("{variant}")
+					? phase.prompt.replace(/\{variant\}/g, `variant ${i + 1}`)
+					: phase.prompt;
+				const subPrompt = substitute(variant, providedArgs, phaseOutputs);
+				lines.push(`  task({ subagent_type: "${phase.agent}", prompt: \`${subPrompt.replace(/`/g, "\\`")}\` }),`);
+			}
+			lines.push(`])`);
+			lines.push("```");
+		}
+		lines.push("");
+		lines.push("---");
+		lines.push("");
+	}
+
+	lines.push("## Final Synthesis");
+	lines.push("");
+	lines.push("After all phases complete, synthesize outputs from `{phase_N_output}` placeholders into a final report. The synthesis rules (if any) are defined in the workflow markdown under `## Final Synthesis (Main Agent)`.");
+
+	return lines.join("\n");
+}
+
+export default function workflowsRunner(pi: ExtensionAPI) {
+	const workflowsDir = path.join(process.cwd(), ".pi", "workflows");
+	const workflows = loadWorkflows(workflowsDir);
+
+	if (workflows.length === 0) return;
+
+	pi.registerTool({
+		name: "run_workflow",
+		label: "Run Workflow",
+		description: [
+			"Execute a DAG workflow from .pi/workflows/.",
+			`Available: ${workflows.map((w) => w.name).join(", ")}`,
+			"Returns an execution plan with concrete task() calls for the assistant to execute.",
+		].join(" "),
+		parameters: Type.Object({
+			name: Type.String({ description: "Workflow name" }),
+			args: Type.Optional(Type.Record(Type.String(), Type.String())),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const wf = workflows.find((w) => w.name === params.name);
+			if (!wf) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Unknown workflow: ${params.name}. Available: ${workflows.map((w) => w.name).join(", ")}`,
+						},
+					],
+					isError: true,
+				};
+			}
+
+			// Validate required args
+			const providedArgs = (params.args ?? {}) as Record<string, string>;
+			const missing = wf.args.filter((a) => a.required && !(a.name in providedArgs));
+			if (missing.length > 0) {
+				const missingNames = missing.map((m) => m.name).join(", ");
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Missing required args: ${missingNames}. Provide them as run_workflow name="${params.name}" args={${JSON.stringify(Object.fromEntries(missing.map((m) => [m.name, "<value>"])))}}.`,
+						},
+					],
+					isError: true,
+				};
+			}
+
+			const plan = buildExecutionPlan(wf, providedArgs);
+
+			return {
+				content: [{ type: "text", text: plan }],
+			};
+		},
+	});
+
+	pi.registerCommand("workflows", {
+		description: "List available workflows",
+		handler: async (_args, ctx) => {
+			const items = workflows.map((w) => `${w.name} — ${w.description.slice(0, 80)}`);
+			await ctx.ui.select("Available Workflows", items);
+		},
+	});
+}

package/dist/template/.pi/guard.example.json

@@ -0,0 +1,75 @@
+# pi-guard Configuration Example for This Kit
+#
+# This file shows recommended guard rules for projects using the ockit-mapping kit.
+# Copy the `guard` block into your project's `.pi/settings.json` or merge into
+# `~/.pi/agent/settings.json` (global).
+#
+# Rule format: action is one of "allow", "ask", "deny"
+# - "allow": silently permit
+# - "ask": prompt user for confirmation
+# - "deny": block with error message
+#
+# Match priority: most specific rule wins. Subsequence matching for bash means
+# tokens must appear in order but extra args are allowed.
+#
+# Reference: https://github.com/jdiamond/pi-guard
+
+{
+  "guard": {
+    "enabled": true,
+    "rules": {
+      "*": "ask",
+      "bash": {
+        "*": "ask",
+        "git status": "allow",
+        "git log": "allow",
+        "git diff": "allow",
+        "git show": "allow",
+        "ls": "allow",
+        "pwd": "allow",
+        "cat *": "allow",
+        "echo *": "allow",
+        "rm *": "deny",
+        "rm -rf *": "deny",
+        "sudo *": "deny",
+        "curl * | bash": "deny",
+        "wget * | bash": "deny",
+        "git push": "ask",
+        "git push --force": "deny",
+        "git reset --hard": "deny",
+        "git clean -fd": "deny",
+        "npm publish": "deny",
+        "cat *.env*": "deny",
+        "cat .env": "deny"
+      },
+      "read": {
+        "*": "allow",
+        "**/*.env": "deny",
+        "**/*.env.*": "deny",
+        "**/*.pem": "deny",
+        "**/*.key": "deny",
+        "**/secrets/*": "deny"
+      },
+      "write": {
+        "*": "ask",
+        ".pi/artifacts/**": "allow",
+        ".pi/state/**": "allow",
+        ".pi/memory/**": "allow"
+      },
+      "edit": {
+        "*": "ask",
+        ".pi/**": "allow"
+      },
+      "spawn": {
+        "build": "allow",
+        "explore": "allow",
+        "general": "allow",
+        "plan": "allow",
+        "review": "allow",
+        "scout": "allow",
+        "vision": "allow",
+        "*": "deny"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,78 @@
+---
+purpose: Index of slash commands with purpose, when-to-use, and lifecycle position
+---
+
+# Prompts Index
+
+14 slash commands. Lifecycle is canonical; utilities attach at any phase.
+
+## Canonical Lifecycle
+
+```
+   ┌──── /init ────┐
+   │               ▼
+/init → /create → /plan? → /ship ⇄ /verify
+   │                  │           │
+   │                  ▼           │
+   │            (tasks.json)      │
+   │                              │
+   └──── /close ←─────────────────┘
+   
+Utilities (any phase):  /research  /audit  /fix  /gc
+Status:                 /status
+```
+
+**Artifact chain:** `/init` → templates · `/create` → `spec.md` · `/plan` → `plan.md` + `tasks.json` · `/ship` → implementation + `progress.md` · `/verify` → `verify.log` · `/close` → clears `.active`.
+
+## Commands
+
+| Command | Purpose | When to use | Arg-hint | Lifecycle |
+|---------|---------|-------------|----------|-----------|
+| `/init` | Bootstrap project: AGENTS.md + planning context + user profile | Once per project (or after stack change) | `[--deep] [--context\|--user\|--all] [--dry-run]` | Setup |
+| `/create` | Create spec (PRD) + workspace + task outline | Starting a feature/fix with a description | `<desc> [--lite] [--dry-run]` | Define |
+| `/plan` | Detailed implementation plan + tasks.json (optional, between create and ship) | Complex tasks needing TDD-step guidance | `[--level 0-3] [--dry-run]` | Plan |
+| `/ship` | Execute tasks, verify, review, close | Ready to implement the spec | `[--skip-review] [--dry-run]` | Build/Ship |
+| `/verify` | Check completeness/correctness/coherence against PRD | Before shipping, or anytime mid-implementation | `[path\|all] [--quick] [--full] [--fix] [--no-cache]` | Verify |
+| `/fix` | Debug + fix a bug or failing test | Bug reported, test failing | `<desc> [--attach <file>] [--dry-run]` | Verify (utility) |
+| `/research` | Gather info before implementation (direct or deep-research workflow) | Need external/codebase understanding | `<topic> [--quick\|--thorough] [--dry-run]` | Define (utility) |
+| `/audit` | Find all occurrences of a pattern, review, remediate | Cross-cutting concern (auth, error handling) | `<pattern> [--scope <dir>] [--dry-run]` | Review (utility) |
+| `/gc` | Fallow analysis + quality grades + optional cleanup PRs | Maintenance cadence; not during active feature work | `[--dry-run] [--apply] [--scope <dir>]` | Maintenance |
+| `/status` | Show active feature, progress tail, blockers | Orient at session start or when unsure | `[--full]` | Any (read-only) |
+| `/close` | Finalize active feature, clear `.active` | Feature done/blocked/abandoned, or recover dangling `.active` | `[--done\|--blocked\|--abandoned] [--note <text>]` | Ship/Recovery |
+| `/loop-check` | NO-GO qualification gate — refuse-list + 2-condition test + 30s checklist | Before scheduling a task as an unattended loop | `<task description> [--help]` | Define |
+| `/loop-init` | Scaffold `.pi/loops/<name>/` from templates (VISION/STATE/SKILL) | Once a task passes /loop-check | `<name> [--help]` | Define |
+| `/loop-review` | Maker/checker gate — verifier subagent runs the gate, emits ACCEPT/REJECT | After a maker run, before ship | `<loop-name> [--help]` | Review |
+
+## When to use what
+
+| Situation | Command |
+|-----------|---------|
+| Fresh repo, first session | `/init --all` |
+| Existing repo, want codebase map | `/init --deep` then `/research` |
+| "Build X" with a clear description | `/create "X"` → `/ship` |
+| "Build X" but complex/multi-step | `/create "X"` → `/plan` → `/ship` |
+| "Fix this bug / failing test" | `/fix "..."` |
+| "How does X work / best practice for X" | `/research "X"` |
+| "Find all console.log / auth checks" | `/audit "console.log"` |
+| "Where am I / what's the state" | `/status` |
+| Feature done but `/ship` left `.active` dangling | `/close --done` |
+| Maintenance / dead code sweep | `/gc --dry-run` |
+| Qualify a task as an unattended loop (refuse-list + 2-condition test) | `/loop-check "<task>"` (Define) |
+| Scaffold a loop after /loop-check returns GO | `/loop-init <name>` (Define) |
+| Maker/checker gate on a loop run before shipping | `/loop-review <name>` (Review) |
+
+## Conventions (shared across commands)
+
+- **Parse Arguments** — every command accepts `--help` and `--dry-run`.
+- **Guard Phase** — preconditions checked before work begins (existing artifacts, uncommitted changes, missing deps).
+- **Load Skills** — each command names the skills it needs; full routing in `skills/INDEX.md`.
+- **Failure Handling** — 2-failure rule: if verification fails twice on the same approach, stop and escalate.
+- **Stop Conditions** — explicit list per command; never silently continue past a blocker.
+- **Workflow invocation** — commands that need multi-agent parallelism call `run_workflow({ name, args })`, not manual workflow-file reading.
+- **`.active` convention** — `.pi/artifacts/.active` holds the current feature slug; `/close` clears it.
+
+## Related
+
+- `skills/INDEX.md` — task → skill routing (70 skills)
+- `workflows/INDEX.md` — 6 DAG workflows invoked by commands
+- `templates/` — 19 template files (PRD, plan body, state, roadmap, loop-vision, loop-state, orchestrators, etc.)

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

@@ -0,0 +1,109 @@
+---
+description: Audit codebase for a specific pattern
+argument-hint: "<pattern> [--scope <dir>] [--dry-run] [--help]"
+---
+
+# Audit: $ARGUMENTS
+
+Find all occurrences of a code pattern in the codebase, review each for issues, and produce prioritized remediation recommendations.
+
+> Use for cross-cutting concerns like auth checks, error handling, API patterns, or security vulnerabilities.
+
+## Parse Arguments
+
+| Argument     | Default  | Description                          |
+| ------------ | -------- | ------------------------------------ |
+| `<pattern>`  | required | Code pattern to search for           |
+| `--scope`    | `.`      | Limit audit to specific directory    |
+| `--format`   | markdown | Output format: `markdown` (default), `json`, `inline` |
+| `--dry-run`  | false    | Search and count without reviewing or reporting |
+| `--help`     | false    | Show this usage                      |
+
+**Examples:**
+- `/audit console.log` — Find all console.log statements
+- `/audit app.use(` — Find all middleware registrations
+- `/audit fetch(` — Find all fetch calls
+- `/audit try {` — Find all try-catch blocks
+- `/audit "await.*catch" --scope src/api` — Limit to src/api directory
+
+## Guard Phase
+
+- Check `.pi/artifacts/.active` — if active slug exists, write report to that artifact directory
+- If `.active` is missing, write report inline
+- If `--dry-run`, skip guard and proceed to search only
+
+## Load Skills
+
+| Skill | When | Why |
+|-------|------|-----|
+| `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 |
+
+## Execution
+
+This command invokes the `audit-pattern` workflow via the `run_workflow` tool for multi-agent parallel execution.
+
+### Direct Execution (≤5 occurrences)
+
+For small audits, execute directly without workflow overhead:
+1. Search with `semantic_grep`
+2. Read each occurrence
+3. Report findings inline
+
+### Workflow Execution (>5 occurrences)
+
+1. **Invoke the workflow:**
+   ```
+   run_workflow({ name: "audit-pattern", args: { pattern: "<pattern from $ARGUMENTS>", scope: "<--scope value or '.'>" } })
+   ```
+2. The workflow runner handles phase dispatch (explore → review) and placeholder substitution (`{pattern}`, `{phase_N_output}`).
+3. **Aggregate results** between phases as returned by the runner.
+4. **Write final report** to `.pi/artifacts/$SLUG/audit.md` (or inline if no active slug)
+
+**Announce:** "Auditing codebase for pattern: [pattern]. Invoking audit-pattern workflow."
+
+## Failure Handling
+
+| Scenario | Action |
+|----------|--------|
+| Workflow phase fails | Retry once with adjusted prompt, then escalate |
+| 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 |
+
+## Stop Conditions
+
+- Pattern returns 0 occurrences → report, stop (not an error)
+- Workflow phase fails 2x → stop, escalate with partial results
+- Audit timeout → report partial findings, note uncovered scope
+- `.active` slug missing → write inline report (not an error)
+
+## Output
+
+1. **Pattern:** [pattern searched]
+2. **Occurrences found:** [count]
+3. **Files affected:** [count]
+4. **Issues by severity:**
+   - Critical: [N]
+   - Important: [N]
+   - Minor: [N]
+5. **Recommended fixes:** [list with file:line refs]
+6. **Correct patterns:** [list of occurrences that are already correct]
+
+> **Post-audit routing:** Individual issue remediation → `/fix`. Systematic cross-cutting fixes → `/create`.
+
+## Related Commands
+
+| Need           | Command      |
+| -------------- | ------------ |
+| Research topic | `/research`  |
+| Create feature | `/create`    |
+| Fix a bug      | `/fix`       |
+| Verify gates   | `/verify`    |
+
+## Related Skills
+
+- `security-and-hardening` — vulnerability detection in audited code
+- `code-review-and-quality` — correctness assessment of findings
+- `fallow` — structural analysis for large-scale audits