pi-loopflows 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - 2026-06-22
+
+- Initial release.
+- Add `loopflow_run` tool.
+- Add `/loopflow` and `/loopflow-list` commands.
+- Add JSON loopflow discovery from bundled, user, and project locations.
+- Add step, loop, gate, max-iteration, artifact, and adapter primitives.
+- Bundle `launch-control` loopflow preset.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Nosov
+
+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,174 @@
+# pi-loopflows
+
+Deterministic loop workflows for Pi subagents.
+
+A **loopflow** describes agent work as a process instead of a single prompt: steps, gates, feedback loops, stop conditions, and saved evidence. It lets you connect Pi subagents like building blocks: gather context, plan, build, review, loop back for fixes, and audit the result.
+
+## Why
+
+Normal chains are linear. Real work is not. A reviewer may request changes, a builder may need another pass, or a gate may block because evidence is missing. `pi-loopflows` adds that missing control flow while keeping the agents focused on their roles.
+
+## Install
+
+```bash
+pi install npm:pi-loopflows
+```
+
+Or from GitHub:
+
+```bash
+pi install https://github.com/nik1t7n/pi-loopflows
+```
+
+Reload Pi after installing:
+
+```text
+/reload
+```
+
+## What it adds
+
+### Tool
+
+```ts
+loopflow_run({
+  workflow: "launch-control",
+  task: "Implement this approved backend plan",
+  maxIterations: 3
+})
+```
+
+### Commands
+
+```text
+/loopflow-list
+/loopflow launch-control -- Implement this approved backend plan
+```
+
+### Bundled loopflow
+
+`launch-control`:
+
+```text
+context-builder
+  → planner
+  → loop max 3:
+      worker
+      reviewer gate
+        approved -> continue
+        changes_requested -> repeat
+        blocked -> stop
+  → final audit
+```
+
+## Loopflow files
+
+Loopflows are JSON files named `*.loopflow.json`.
+
+Discovery locations:
+
+- bundled package `loopflows/`
+- user: `~/.pi/agent/loopflows/`
+- project: `.pi/loopflows/`
+
+Project loopflows can override or add workflows for a repo.
+
+## Minimal shape
+
+```json
+{
+  "name": "build-review",
+  "description": "Build, review, and fix until approved.",
+  "steps": [
+    {
+      "id": "plan",
+      "agent": "planner",
+      "task": "Plan this task: {task}"
+    },
+    {
+      "loop": {
+        "id": "build-review",
+        "maxIterations": 3,
+        "gateStep": "review",
+        "passStatuses": ["approved"],
+        "retryStatuses": ["changes_requested"],
+        "stopStatuses": ["blocked"],
+        "body": [
+          {
+            "id": "build",
+            "agent": "worker",
+            "task": "Build from plan: {outputs.plan}"
+          },
+          {
+            "id": "review",
+            "agent": "reviewer",
+            "gate": { "type": "json-status" },
+            "task": "Review and return JSON with status approved, changes_requested, or blocked."
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## Template variables
+
+- `{task}` — original user task
+- `{previous}` — previous step output
+- `{outputs.stepId}` — output from a named step
+- `{outputs.stepId.status}` — parsed gate status
+- `{outputs.stepId.json}` — parsed gate JSON
+- `{loop.iteration}` — current loop iteration
+- `{artifactsDir}` — current run artifact directory
+- `{params.name}` — runtime params passed to `loopflow_run`
+
+## Artifacts
+
+Every run writes evidence to:
+
+```text
+<cwd>/.pi/loopflows/runs/<timestamp>-<workflow>/
+```
+
+Typical files:
+
+```text
+task.md
+workflow.json
+context.md
+block-plan.md
+build-1.md
+review-1.json
+final-audit.json
+summary.md
+```
+
+## Backend design
+
+The engine uses an executor adapter boundary:
+
+```ts
+runAgent(agent, task, options) -> StepResult
+```
+
+Current backend: Pi subprocess agents compatible with `pi-subagents` agent definitions.
+
+Future backends can support Codex CLI, OpenCode, ACP-based workers, remote workers, or other agent runtimes without changing loopflow definitions.
+
+## Requirements
+
+- Pi coding agent
+- `pi-subagents` installed for the bundled agent roles:
+
+```bash
+pi install npm:pi-subagents
+```
+
+## Status
+
+Early but usable. The core model is intentionally small: steps, loops, gates, artifacts, and adapters.
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,449 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+type BackendName = "pi-subprocess";
+type GateStatus = "approved" | "changes_requested" | "blocked" | "complete" | "incomplete" | string;
+
+type StepDef = {
+  id: string;
+  agent: string;
+  task: string;
+  gate?: GateDef;
+  output?: string;
+  model?: string;
+  tools?: string[];
+};
+
+type LoopDef = {
+  id: string;
+  maxIterations: number;
+  body: StepDef[];
+  gateStep: string;
+  passStatuses?: string[];
+  retryStatuses?: string[];
+  stopStatuses?: string[];
+  onExhausted?: "stop" | "continue";
+};
+
+type WorkflowNode = StepDef | { loop: LoopDef };
+
+const EXTENSION_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(EXTENSION_DIR, "..");
+
+type WorkflowDef = {
+  name: string;
+  description?: string;
+  version?: string;
+  backend?: BackendName;
+  defaults?: {
+    maxIterations?: number;
+    agentScope?: "user" | "project" | "both";
+  };
+  steps: WorkflowNode[];
+};
+
+type AgentDef = {
+  name: string;
+  description?: string;
+  systemPrompt: string;
+  model?: string;
+  tools?: string[];
+  source: string;
+};
+
+type StepResult = {
+  id: string;
+  agent: string;
+  iteration?: number;
+  output: string;
+  json?: any;
+  status?: GateStatus;
+  artifactPath?: string;
+  exitCode: number;
+  stderr?: string;
+};
+
+type RunContext = {
+  cwd: string;
+  task: string;
+  artifactsDir: string;
+  outputs: Record<string, StepResult>;
+  sequence: StepResult[];
+  params: Record<string, any>;
+};
+
+type GateDef = {
+  type?: "json-status";
+  passStatuses?: string[];
+  retryStatuses?: string[];
+  stopStatuses?: string[];
+};
+
+function safeName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80) || "item";
+}
+
+async function ensureDir(dir: string) {
+  await fs.promises.mkdir(dir, { recursive: true });
+}
+
+function readJsonFile<T>(file: string): T | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+function parseFrontmatter(md: string): { data: Record<string, any>; body: string } {
+  if (!md.startsWith("---\n")) return { data: {}, body: md };
+  const end = md.indexOf("\n---", 4);
+  if (end < 0) return { data: {}, body: md };
+  const raw = md.slice(4, end).trim();
+  const body = md.slice(end + 4).replace(/^\n/, "");
+  const data: Record<string, any> = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!m) continue;
+    const key = m[1];
+    let value: any = m[2].trim();
+    if (value === "") value = undefined;
+    if (typeof value === "string" && value.includes(",")) {
+      value = value.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+    data[key] = value;
+  }
+  return { data, body };
+}
+
+function agentDirs(cwd: string, scope: "user" | "project" | "both"): string[] {
+  const dirs: string[] = [];
+  const add = (p: string) => { if (fs.existsSync(p)) dirs.push(p); };
+  const pkg = path.join(getAgentDir(), "npm/node_modules/pi-subagents/agents");
+  add(pkg);
+  if (scope === "user" || scope === "both") add(path.join(getAgentDir(), "agents"));
+  if (scope === "project" || scope === "both") {
+    add(path.join(cwd, ".pi/agents"));
+    add(path.join(cwd, ".agents"));
+  }
+  return dirs;
+}
+
+function walkMd(dir: string): string[] {
+  const out: string[] = [];
+  if (!fs.existsSync(dir)) return out;
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, ent.name);
+    if (ent.isDirectory()) out.push(...walkMd(p));
+    else if (ent.isFile() && ent.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+
+function discoverAgents(cwd: string, scope: "user" | "project" | "both"): Map<string, AgentDef> {
+  const map = new Map<string, AgentDef>();
+  // Load lower priority first; later dirs override.
+  for (const dir of agentDirs(cwd, scope)) {
+    for (const file of walkMd(dir)) {
+      const md = fs.readFileSync(file, "utf8");
+      const { data, body } = parseFrontmatter(md);
+      const name = typeof data.name === "string" ? data.name : path.basename(file, ".md");
+      const pkg = typeof data.package === "string" ? data.package : undefined;
+      const runtime = pkg ? `${pkg}.${name}` : name;
+      const tools = Array.isArray(data.tools) ? data.tools : typeof data.tools === "string" ? data.tools.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+      map.set(runtime, {
+        name: runtime,
+        description: data.description,
+        systemPrompt: body,
+        model: typeof data.model === "string" ? data.model : undefined,
+        tools,
+        source: file,
+      });
+      if (!pkg) map.set(name, map.get(runtime)!);
+    }
+  }
+  return map;
+}
+
+function workflowDirs(cwd: string): string[] {
+  return [
+    path.join(PACKAGE_ROOT, "loopflows"),
+    path.join(getAgentDir(), "loopflows"),
+    path.join(cwd, ".pi/loopflows"),
+  ].filter((p) => fs.existsSync(p));
+}
+
+function discoverWorkflows(cwd: string): Map<string, { file: string; workflow: WorkflowDef }> {
+  const map = new Map<string, { file: string; workflow: WorkflowDef }>();
+  for (const dir of workflowDirs(cwd)) {
+    for (const file of fs.readdirSync(dir).filter((f) => f.endsWith(".loopflow.json"))) {
+      const full = path.join(dir, file);
+      const wf = readJsonFile<WorkflowDef>(full);
+      if (wf?.name && Array.isArray(wf.steps)) map.set(wf.name, { file: full, workflow: wf });
+    }
+  }
+  return map;
+}
+
+function renderTemplate(template: string, ctx: RunContext, iteration?: number): string {
+  return template.replace(/\{([^}]+)\}/g, (_m, keyRaw) => {
+    const key = String(keyRaw).trim();
+    if (key === "task") return ctx.task;
+    if (key === "artifactsDir") return ctx.artifactsDir;
+    if (key === "previous") return ctx.sequence.at(-1)?.output ?? "";
+    if (key === "loop.iteration") return String(iteration ?? "");
+    if (key.startsWith("params.")) return String(ctx.params[key.slice(7)] ?? "");
+    if (key.startsWith("outputs.")) {
+      const rest = key.slice(8);
+      const [id, prop] = rest.split(".");
+      const res = ctx.outputs[id];
+      if (!res) return "";
+      if (!prop || prop === "output") return res.output;
+      if (prop === "status") return String(res.status ?? "");
+      if (prop === "json") return JSON.stringify(res.json ?? null, null, 2);
+      return String((res as any)[prop] ?? res.json?.[prop] ?? "");
+    }
+    return "";
+  });
+}
+
+function extractJson(text: string): any | undefined {
+  const trimmed = text.trim();
+  try { return JSON.parse(trimmed); } catch {}
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fenced) {
+    try { return JSON.parse(fenced[1].trim()); } catch {}
+  }
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    try { return JSON.parse(trimmed.slice(start, end + 1)); } catch {}
+  }
+  return undefined;
+}
+
+function finalAssistantTextFromJsonLines(stdout: string): string {
+  let final = "";
+  for (const line of stdout.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    let ev: any;
+    try { ev = JSON.parse(line); } catch { continue; }
+    const msg = ev.message;
+    if (ev.type === "message_end" && msg?.role === "assistant") {
+      for (const part of msg.content ?? []) {
+        if (part.type === "text") final = part.text;
+      }
+    }
+  }
+  return final;
+}
+
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1];
+  if (currentScript && fs.existsSync(currentScript) && !currentScript.startsWith("/$bunfs/root/")) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+  const execName = path.basename(process.execPath).toLowerCase();
+  if (!/^(node|bun)(\.exe)?$/.test(execName)) return { command: process.execPath, args };
+  return { command: "pi", args };
+}
+
+async function writePrompt(agentName: string, prompt: string) {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-loopflows-"));
+  const file = path.join(dir, `prompt-${safeName(agentName)}.md`);
+  await withFileMutationQueue(file, async () => fs.promises.writeFile(file, prompt, { mode: 0o600 }));
+  return { dir, file };
+}
+
+interface ExecutorAdapter {
+  runAgent(agent: string, task: string, options: { cwd: string; signal?: AbortSignal; model?: string; tools?: string[]; scope: "user" | "project" | "both" }): Promise<{ output: string; exitCode: number; stderr: string }>;
+}
+
+class PiSubprocessAdapter implements ExecutorAdapter {
+  async runAgent(agentName: string, task: string, options: { cwd: string; signal?: AbortSignal; model?: string; tools?: string[]; scope: "user" | "project" | "both" }) {
+    const agents = discoverAgents(options.cwd, options.scope);
+    const agent = agents.get(agentName);
+    if (!agent) {
+      return { output: "", exitCode: 1, stderr: `Unknown agent ${agentName}. Available: ${[...agents.keys()].sort().join(", ")}` };
+    }
+    const args = ["--mode", "json", "-p", "--no-session"];
+    const model = options.model ?? agent.model;
+    const tools = options.tools ?? agent.tools;
+    if (model) args.push("--model", model);
+    if (tools?.length) args.push("--tools", tools.join(","));
+    const tmp = agent.systemPrompt.trim() ? await writePrompt(agentName, agent.systemPrompt) : undefined;
+    if (tmp) args.push("--append-system-prompt", tmp.file);
+    args.push(task);
+
+    const invocation = getPiInvocation(args);
+    let stdout = "";
+    let stderr = "";
+    const exitCode = await new Promise<number>((resolve) => {
+      const proc = spawn(invocation.command, invocation.args, { cwd: options.cwd, stdio: ["ignore", "pipe", "pipe"] });
+      proc.stdout.on("data", (d) => { stdout += d.toString(); });
+      proc.stderr.on("data", (d) => { stderr += d.toString(); });
+      proc.on("close", (code) => resolve(code ?? 0));
+      proc.on("error", (err) => { stderr += String(err?.message ?? err); resolve(1); });
+      if (options.signal) {
+        const kill = () => { proc.kill("SIGTERM"); setTimeout(() => proc.kill("SIGKILL"), 3000); };
+        if (options.signal.aborted) kill();
+        else options.signal.addEventListener("abort", kill, { once: true });
+      }
+    });
+    if (tmp) {
+      fs.rmSync(tmp.dir, { recursive: true, force: true });
+    }
+    return { output: finalAssistantTextFromJsonLines(stdout) || stdout.trim(), exitCode, stderr };
+  }
+}
+
+async function saveArtifact(ctx: RunContext, name: string, content: string): Promise<string> {
+  const file = path.join(ctx.artifactsDir, name);
+  await ensureDir(path.dirname(file));
+  await fs.promises.writeFile(file, content, "utf8");
+  return file;
+}
+
+async function runStep(def: StepDef, ctx: RunContext, adapter: ExecutorAdapter, scope: "user" | "project" | "both", signal: AbortSignal | undefined, iteration?: number): Promise<StepResult> {
+  const task = renderTemplate(def.task, ctx, iteration);
+  const run = await adapter.runAgent(def.agent, task, { cwd: ctx.cwd, signal, model: def.model, tools: def.tools, scope });
+  const json = def.gate ? extractJson(run.output) : undefined;
+  const status = json?.status;
+  const artifactName = def.output ? renderTemplate(def.output, ctx, iteration) : `${safeName(def.id)}${iteration ? `-${iteration}` : ""}.${def.gate ? "json" : "md"}`;
+  const artifactPath = await saveArtifact(ctx, artifactName, def.gate ? JSON.stringify(json ?? { parse_error: true, raw: run.output }, null, 2) : run.output);
+  const result: StepResult = { id: def.id, agent: def.agent, iteration, output: run.output, json, status, artifactPath, exitCode: run.exitCode, stderr: run.stderr };
+  ctx.outputs[def.id] = result;
+  ctx.outputs[iteration ? `${def.id}_${iteration}` : def.id] = result;
+  ctx.sequence.push(result);
+  return result;
+}
+
+function statusIn(status: GateStatus | undefined, values: string[] | undefined, fallback: string[]) {
+  return !!status && (values ?? fallback).includes(status);
+}
+
+async function runLoop(loop: LoopDef, ctx: RunContext, adapter: ExecutorAdapter, scope: "user" | "project" | "both", signal: AbortSignal | undefined): Promise<StepResult> {
+  const max = Math.max(1, loop.maxIterations);
+  let lastGate: StepResult | undefined;
+  for (let i = 1; i <= max; i++) {
+    await saveArtifact(ctx, `${safeName(loop.id)}/iteration-${i}.txt`, `Starting iteration ${i}/${max}\n`);
+    for (const step of loop.body) {
+      const stepWithGate = step.id === loop.gateStep && !step.gate ? { ...step, gate: { type: "json-status" as const } } : step;
+      const result = await runStep(stepWithGate, ctx, adapter, scope, signal, i);
+      if (step.id === loop.gateStep) lastGate = result;
+      if (result.exitCode !== 0) return result;
+    }
+    const status = lastGate?.status;
+    if (statusIn(status, loop.passStatuses, ["approved", "complete"])) return lastGate!;
+    if (statusIn(status, loop.stopStatuses, ["blocked"])) return lastGate!;
+    if (!statusIn(status, loop.retryStatuses, ["changes_requested", "incomplete"])) return lastGate!;
+  }
+  if (lastGate) {
+    lastGate.status = `exhausted:${lastGate.status ?? "unknown"}`;
+    await saveArtifact(ctx, `${safeName(loop.id)}/exhausted.json`, JSON.stringify(lastGate.json ?? { status: lastGate.status }, null, 2));
+  }
+  return lastGate ?? { id: loop.id, agent: "loop", output: "Loop had no gate result", exitCode: 1 };
+}
+
+async function runWorkflow(workflow: WorkflowDef, task: string, opts: { cwd: string; signal?: AbortSignal; params?: Record<string, any>; maxIterations?: number }) {
+  const adapter = new PiSubprocessAdapter();
+  const runId = `${new Date().toISOString().replace(/[:.]/g, "-")}-${safeName(workflow.name)}`;
+  const artifactsDir = path.join(opts.cwd, ".pi/loopflows/runs", runId);
+  await ensureDir(artifactsDir);
+  const ctx: RunContext = { cwd: opts.cwd, task, artifactsDir, outputs: {}, sequence: [], params: opts.params ?? {} };
+  const scope = workflow.defaults?.agentScope ?? "both";
+
+  await saveArtifact(ctx, "workflow.json", JSON.stringify(workflow, null, 2));
+  await saveArtifact(ctx, "task.md", task);
+
+  for (const node of workflow.steps) {
+    if ("loop" in node) {
+      const loop = { ...node.loop };
+      if (opts.maxIterations) loop.maxIterations = opts.maxIterations;
+      const result = await runLoop(loop, ctx, adapter, scope, opts.signal);
+      if (result.exitCode !== 0 || String(result.status ?? "").startsWith("exhausted") || statusIn(result.status, loop.stopStatuses, ["blocked"])) break;
+    } else {
+      const result = await runStep(node, ctx, adapter, scope, opts.signal);
+      if (result.exitCode !== 0) break;
+      if (node.gate && statusIn(result.status, node.gate.stopStatuses, ["blocked", "incomplete"])) break;
+    }
+  }
+
+  const summary = [
+    `# Loopflow run: ${workflow.name}`,
+    ``,
+    `Task: ${task}`,
+    `Artifacts: ${artifactsDir}`,
+    ``,
+    `## Steps`,
+    ...ctx.sequence.map((r, idx) => `${idx + 1}. ${r.id}${r.iteration ? `#${r.iteration}` : ""} (${r.agent}) - exit ${r.exitCode}${r.status ? ` - status ${r.status}` : ""}${r.artifactPath ? ` - ${path.relative(opts.cwd, r.artifactPath)}` : ""}`),
+  ].join("\n");
+  const summaryPath = await saveArtifact(ctx, "summary.md", summary);
+  return { artifactsDir, summaryPath, results: ctx.sequence, summary };
+}
+
+const RunParams = Type.Object({
+  workflow: Type.String({ description: "Loopflow name, e.g. launch-control" }),
+  task: Type.String({ description: "Task/spec/plan for the loopflow" }),
+  maxIterations: Type.Optional(Type.Number({ description: "Override max iterations for loops" })),
+  params: Type.Optional(Type.Record(Type.String(), Type.Any())),
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "loopflow_run",
+    label: "Loopflow Run",
+    description: "Run a deterministic loopflow: subagent steps, gates, loops, artifacts, and max-iteration feedback cycles.",
+    parameters: RunParams,
+    promptSnippet: "Run deterministic subagent loop workflows with gates and feedback loops.",
+    promptGuidelines: ["Use loopflow_run when the user asks to run a loopflow, launch-control workflow, or builder/reviewer feedback loop."],
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const workflows = discoverWorkflows(ctx.cwd);
+      const found = workflows.get(params.workflow);
+      if (!found) {
+        return { content: [{ type: "text", text: `Unknown loopflow ${params.workflow}. Available: ${[...workflows.keys()].join(", ") || "none"}` }], details: {}, isError: true };
+      }
+      onUpdate?.({ content: [{ type: "text", text: `Running loopflow ${params.workflow}...` }], details: {} });
+      const result = await runWorkflow(found.workflow, params.task, { cwd: ctx.cwd, signal, params: params.params, maxIterations: params.maxIterations });
+      return { content: [{ type: "text", text: result.summary }], details: result };
+    },
+  });
+
+  pi.registerCommand("loopflow-list", {
+    description: "List available loopflows",
+    handler: async (_args, ctx) => {
+      const workflows = discoverWorkflows(ctx.cwd);
+      const lines = [...workflows.values()].map(({ file, workflow }) => `- ${workflow.name}: ${workflow.description ?? ""}\n  ${file}`);
+      ctx.ui.notify(lines.length ? lines.join("\n") : "No loopflows found", "info");
+    },
+  });
+
+  pi.registerCommand("loopflow", {
+    description: "Run a loopflow: /loopflow <name> -- <task>",
+    handler: async (args, ctx) => {
+      const [namePart, ...rest] = args.split(/\s+--\s+/);
+      const name = namePart.trim().split(/\s+/)[0];
+      const task = rest.join(" -- ").trim() || namePart.trim().replace(/^\S+\s*/, "");
+      if (!name || !task) {
+        ctx.ui.notify("Usage: /loopflow <name> -- <task>", "error");
+        return;
+      }
+      await ctx.waitForIdle();
+      const workflows = discoverWorkflows(ctx.cwd);
+      const found = workflows.get(name);
+      if (!found) {
+        ctx.ui.notify(`Unknown loopflow ${name}. Available: ${[...workflows.keys()].join(", ") || "none"}`, "error");
+        return;
+      }
+      ctx.ui.notify(`Running loopflow ${name}`, "info");
+      const result = await runWorkflow(found.workflow, task, { cwd: ctx.cwd });
+      pi.sendMessage({ customType: "loopflow-result", content: result.summary, display: true, details: result }, { triggerTurn: false });
+    },
+  });
+}

package/loopflows/launch-control.loopflow.json

@@ -0,0 +1,65 @@
+{
+  "name": "launch-control",
+  "version": "1.0.0",
+  "description": "Plan-as-contract implementation loopflow: context, block plan, builder/reviewer feedback loop, and final audit with real validation evidence.",
+  "backend": "pi-subprocess",
+  "defaults": {
+    "agentScope": "both"
+  },
+  "steps": [
+    {
+      "id": "context",
+      "agent": "context-builder",
+      "output": "context.md",
+      "task": "Build concise launch-control execution context for this task:\n\n{task}\n\nRead any provided plan/spec path, inspect the repository enough to identify relevant files, acceptance criteria, validation commands, risks, missing inputs, and stop conditions. Do not edit files. Return compact handoff context with: scope, likely files, validation contract candidates, explicit unknowns, and stop conditions."
+    },
+    {
+      "id": "plan",
+      "agent": "planner",
+      "output": "block-plan.md",
+      "task": "Create the smallest safe launch-control implementation block from this context:\n\n{outputs.context}\n\nOriginal task:\n{task}\n\nReturn a concrete block plan with: intended slice, acceptance criteria, files likely involved, real validation commands/evidence required, non-goals, stop conditions, and what the builder must report. Keep the plan lean and executable. Do not edit files."
+    },
+    {
+      "loop": {
+        "id": "build-review",
+        "maxIterations": 3,
+        "gateStep": "review",
+        "passStatuses": ["approved"],
+        "retryStatuses": ["changes_requested"],
+        "stopStatuses": ["blocked"],
+        "onExhausted": "stop",
+        "body": [
+          {
+            "id": "build",
+            "agent": "worker",
+            "output": "build-{loop.iteration}.md",
+            "task": "Implement or fix launch-control block iteration {loop.iteration}.\n\nOriginal task:\n{task}\n\nBlock plan:\n{outputs.plan}\n\nPrevious review, if any:\n{outputs.review.output}\n\nRules:\n- One writer only.\n- Use the real project stack and real integrations.\n- No mocks, demos, fallbacks, fake validation, or hidden shortcuts unless the user explicitly asked.\n- If this is iteration 1, implement exactly the block plan. If this is a later iteration, apply only required reviewer fixes.\n- If the plan is stale, acceptance criteria change, data/API model changes, or user decision is required, stop and report it instead of inventing scope.\n- Run the validation contract where possible.\n\nReturn changed files, commands run with exit codes, validation evidence, blockers, and any plan mismatch."
+          },
+          {
+            "id": "review",
+            "agent": "reviewer",
+            "output": "review-{loop.iteration}.json",
+            "gate": {
+              "type": "json-status",
+              "passStatuses": ["approved"],
+              "retryStatuses": ["changes_requested"],
+              "stopStatuses": ["blocked"]
+            },
+            "task": "Review launch-control build iteration {loop.iteration}. Do not edit project/source files.\n\nOriginal task:\n{task}\n\nBlock plan:\n{outputs.plan}\n\nBuilder report:\n{outputs.build.output}\n\nCheck: plan freshness, scope drift, correctness, real validation evidence, test coverage, hidden mocks/fallbacks/demos, over-large slice, and unlogged plan changes.\n\nReturn ONLY valid JSON matching this shape:\n{\n  \"status\": \"approved\" | \"changes_requested\" | \"blocked\",\n  \"summary\": \"short verdict\",\n  \"findings\": [{\"severity\": \"blocker|required|optional\", \"file\": \"path or null\", \"issue\": \"specific issue\", \"required_fix\": \"specific fix or null\"}],\n  \"validation_gaps\": [\"missing evidence\"],\n  \"plan_changed\": false,\n  \"requires_user_decision\": false\n}\n\nUse status=approved only when the diff and evidence satisfy the block plan. Use changes_requested for fixable required issues. Use blocked for missing credentials, stale plan, required user/product decision, or exhausted/unsafe scope."
+          }
+        ]
+      }
+    },
+    {
+      "id": "final-audit",
+      "agent": "reviewer",
+      "output": "final-audit.json",
+      "gate": {
+        "type": "json-status",
+        "passStatuses": ["complete", "approved"],
+        "stopStatuses": ["incomplete", "blocked"]
+      },
+      "task": "Run final launch-control completion audit. Do not edit files.\n\nOriginal task:\n{task}\n\nPlan:\n{outputs.plan}\n\nLast build:\n{outputs.build.output}\n\nLast review status: {outputs.review.status}\nLast review JSON:\n{outputs.review.json}\n\nVerify every explicit acceptance criterion, artifact, command, invariant, and stop condition against current repo state and available evidence.\n\nReturn ONLY valid JSON:\n{\n  \"status\": \"complete\" | \"incomplete\" | \"blocked\",\n  \"summary\": \"short audit result\",\n  \"verified_items\": [\"item\"],\n  \"remaining_blockers\": [\"blocker\"],\n  \"validation_gaps\": [\"gap\"]\n}"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "pi-loopflows",
+  "version": "0.1.0",
+  "description": "Deterministic loop workflows for Pi subagents: steps, gates, feedback loops, and artifacts.",
+  "license": "MIT",
+  "author": "Nikita Nosov <20nik.nosov21@gmail.com>",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "agent-workflows",
+    "subagents",
+    "loopflows",
+    "ai-agents"
+  ],
+  "homepage": "https://github.com/nik1t7n/pi-loopflows#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nik1t7n/pi-loopflows.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nik1t7n/pi-loopflows/issues"
+  },
+  "files": [
+    "extensions",
+    "loopflows",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "image": "https://raw.githubusercontent.com/nik1t7n/pi-loopflows/main/assets/pi-loopflows.png"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@types/node": "^26.0.0",
+    "typebox": "latest",
+    "typescript": "latest"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run"
+  }
+}

package/skills/loopflows/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: loopflows
+description: Use when the user wants deterministic multi-agent workflows, feedback loops between builder/reviewer agents, launch-control style implementation gates, or repeatable Pi subagent processes with max iterations, gates, stop conditions, and artifacts.
+---
+
+# Loopflows
+
+Use `loopflow_run` for deterministic agent workflows that need real control flow instead of a linear chain.
+
+Prefer loopflows when work needs:
+
+- a builder/reviewer feedback loop;
+- explicit pass/retry/stop gates;
+- max iteration limits;
+- saved evidence artifacts;
+- launch-control style plan → build → review → fix → audit flow.
+
+## Commands
+
+List workflows:
+
+```text
+/loopflow-list
+```
+
+Run a workflow:
+
+```text
+/loopflow launch-control -- <task or plan>
+```
+
+Or call the tool directly:
+
+```ts
+loopflow_run({ workflow: "launch-control", task: "...", maxIterations: 3 })
+```
+
+## Rule of thumb
+
+Use `pi-subagents` chains for simple linear handoffs. Use `pi-loopflows` when a gate can send work backward for fixes or stop the run.