pi-loopflows 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.1 - 2026-06-22
+
+- Polish product README and usage guidance for public release.
+- Add bundled `build-review` loopflow for lightweight implementation feedback loops.
+- Add bundled `plan-review` loopflow for plan quality gates before implementation.
+- Expand loopflows skill instructions.
+- Clarify adapter/backend direction for future compatible executors.
+
 ## 0.1.0 - 2026-06-22
 
 - Initial release.

package/README.md

@@ -1,12 +1,26 @@
 # pi-loopflows
 
-Deterministic loop workflows for Pi subagents.
+Build deterministic AI workflows out of 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.
+A **loopflow** is a reusable process for agent work: steps, gates, feedback loops, stop rules, and evidence artifacts. Instead of asking one agent to “do the whole thing”, you describe how specialist agents should cooperate: one agent gathers context, another plans, another builds, another reviews, and a gate decides whether the work moves forward, loops back for fixes, or stops.
 
-## Why
+`pi-loopflows` ships with a production-ready **Launch Control** loopflow out of the box, and it is also a flexible constructor for your own workflows.
 
-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.
+## Why loopflows
+
+Linear chains are useful, but real work is not always linear. A reviewer can request changes. A validator can reject missing evidence. A planner can reveal that the task is blocked. A builder may need several focused passes before the result is safe to accept.
+
+Loopflows make that control flow explicit:
+
+```text
+step → step → gate
+             ↓
+          approved → continue
+          changes_requested → loop back
+          blocked → stop
+```
+
+The philosophy is simple: AI should work through a process, not just produce a confident answer. A loopflow defines who does the work, who checks it, what counts as success, how many attempts are allowed, where evidence is saved, and when the run must stop instead of guessing.
 
 ## Install
 
@@ -14,19 +28,19 @@ Normal chains are linear. Real work is not. A reviewer may request changes, a bu
 pi install npm:pi-loopflows
 ```
 
-Or from GitHub:
+`pi-loopflows` uses Pi subagent definitions as its first backend. Install `pi-subagents` if you have not already:
 
 ```bash
-pi install https://github.com/nik1t7n/pi-loopflows
+pi install npm:pi-subagents
 ```
 
-Reload Pi after installing:
+Then reload Pi:
 
 ```text
 /reload
 ```
 
-## What it adds
+## What you get
 
 ### Tool
 
@@ -45,9 +59,15 @@ loopflow_run({
 /loopflow launch-control -- Implement this approved backend plan
 ```
 
-### Bundled loopflow
+### Built-in loopflows
+
+- `launch-control` — plan-as-contract implementation loop with builder/reviewer feedback and final audit.
+- `build-review` — small generic build → review → fix loop for scoped implementation tasks.
+- `plan-review` — planning loop that lets a reviewer reject vague or unsafe plans before implementation.
+
+## Built-in: Launch Control
 
-`launch-control`:
+Launch Control is bundled because it is the clearest example of why loopflows exist. It turns a plan into a controlled implementation process:
 
 ```text
 context-builder
@@ -61,19 +81,59 @@ context-builder
   → final audit
 ```
 
+Use it when drift, skipped validation, PR correctness, or multi-step delivery risk matter.
+
+Example:
+
+```text
+/loopflow launch-control -- Implement the auth migration plan in docs/auth-plan.md
+```
+
+Launch Control is not hard-coded. It is just a `.loopflow.json` file. You can copy it, change the agents, change the prompts, adjust max iterations, add stricter gates, or create a project-specific version in `.pi/loopflows/`.
+
+## Loopflows as a constructor
+
+Think of loopflows as LEGO for agent processes. A loopflow can use any available Pi subagent role:
+
+- `context-builder`
+- `scout`
+- `researcher`
+- `planner`
+- `worker`
+- `reviewer`
+- `oracle`
+- your own custom agents
+
+You decide:
+
+- which agent runs first;
+- what each agent receives;
+- which output is saved;
+- which step is a gate;
+- what statuses mean pass, retry, or stop;
+- how many loop iterations are allowed;
+- where artifacts go;
+- what final audit should prove.
+
+Today, the backend runs Pi-compatible subagents. The engine is intentionally built behind an adapter boundary, so future versions can add other compatible backends — Codex CLI, OpenCode, ACP workers, remote agents, or custom executors — without changing the loopflow concept.
+
 ## Loopflow files
 
-Loopflows are JSON files named `*.loopflow.json`.
+Loopflows are JSON files named:
+
+```text
+*.loopflow.json
+```
 
 Discovery locations:
 
-- bundled package `loopflows/`
-- user: `~/.pi/agent/loopflows/`
-- project: `.pi/loopflows/`
+- bundled package loopflows;
+- user loopflows: `~/.pi/agent/loopflows/`;
+- project loopflows: `.pi/loopflows/`.
 
-Project loopflows can override or add workflows for a repo.
+Project loopflows are the easiest way to customize behavior for one repo.
 
-## Minimal shape
+## Minimal example
 
 ```json
 {
@@ -114,14 +174,39 @@ Project loopflows can override or add workflows for a repo.
 
 ## 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`
+- `{task}` — original user task.
+- `{previous}` — previous step output.
+- `{outputs.stepId}` — output from a named step.
+- `{outputs.stepId.output}` — same as above, explicit form.
+- `{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`.
+
+## Gate contract
+
+Gate steps should return JSON. A typical reviewer gate returns:
+
+```json
+{
+  "status": "approved",
+  "summary": "The implementation satisfies the plan.",
+  "findings": [],
+  "validation_gaps": [],
+  "requires_user_decision": false
+}
+```
+
+Common statuses:
+
+- `approved` — move forward.
+- `changes_requested` — loop back for another pass.
+- `blocked` — stop; user or environment action is required.
+- `complete` — final audit passed.
+- `incomplete` — final audit failed.
+
+Each loopflow decides which statuses pass, retry, or stop.
 
 ## Artifacts
 
@@ -131,7 +216,7 @@ Every run writes evidence to:
 <cwd>/.pi/loopflows/runs/<timestamp>-<workflow>/
 ```
 
-Typical files:
+Typical artifacts:
 
 ```text
 task.md
@@ -144,30 +229,92 @@ final-audit.json
 summary.md
 ```
 
+This makes loopflows inspectable. You can see what each agent claimed, what the gate decided, and why the run stopped or passed.
+
+## Customization patterns
+
+### Make Launch Control stricter
+
+Copy the bundled file:
+
+```bash
+mkdir -p .pi/loopflows
+cp ~/.pi/agent/npm/node_modules/pi-loopflows/loopflows/launch-control.loopflow.json \
+  .pi/loopflows/launch-control.loopflow.json
+```
+
+Then edit the project copy. Common changes:
+
+- increase `maxIterations`;
+- change `reviewer` to a custom security reviewer;
+- add stricter validation language;
+- add a docs or migration audit step;
+- change stop statuses;
+- make the final audit require `complete` only.
+
+### Create a lightweight workflow
+
+Use `build-review` for small implementation tasks where full Launch Control is too formal.
+
+```text
+/loopflow build-review -- Add validation to the import endpoint
+```
+
+### Review a plan before coding
+
+Use `plan-review` when you want a plan to be checked before a worker touches files.
+
+```text
+/loopflow plan-review -- Plan the database migration for workspace roles
+```
+
 ## Backend design
 
-The engine uses an executor adapter boundary:
+The runtime uses an executor adapter boundary:
 
 ```ts
 runAgent(agent, task, options) -> StepResult
 ```
 
-Current backend: Pi subprocess agents compatible with `pi-subagents` agent definitions.
+Current backend:
 
-Future backends can support Codex CLI, OpenCode, ACP-based workers, remote workers, or other agent runtimes without changing loopflow definitions.
+- Pi subprocess agents compatible with `pi-subagents` agent definitions.
 
-## Requirements
+Future-compatible backend ideas:
 
-- Pi coding agent
-- `pi-subagents` installed for the bundled agent roles:
+- Codex CLI workers;
+- OpenCode workers;
+- ACP-compatible agents;
+- remote worker pools;
+- project-specific executors.
 
-```bash
-pi install npm:pi-subagents
+The point is that loopflows describe the process. The backend decides how each agent is actually executed.
+
+## When to use loopflows vs chains
+
+Use normal Pi subagent chains when the process is linear:
+
+```text
+scout → planner → worker
 ```
 
+Use loopflows when a step can send work backward or stop the process:
+
+```text
+worker → reviewer → worker → reviewer
+```
+
+If you need a feedback loop, a quality gate, a max iteration limit, or saved evidence, use a loopflow.
+
 ## Status
 
-Early but usable. The core model is intentionally small: steps, loops, gates, artifacts, and adapters.
+`pi-loopflows` is early, but designed as a real product surface rather than a one-off script. The core model is intentionally small:
+
+```text
+steps + loops + gates + artifacts + adapters
+```
+
+That is enough to build useful workflows without turning the extension into a giant orchestration platform.
 
 ## License
 

package/loopflows/build-review.loopflow.json

@@ -0,0 +1,48 @@
+{
+  "name": "build-review",
+  "version": "1.0.0",
+  "description": "Generic scoped implementation loop: plan, build, independent review, repeat fixes until approved or blocked.",
+  "backend": "pi-subprocess",
+  "defaults": {
+    "agentScope": "both"
+  },
+  "steps": [
+    {
+      "id": "plan",
+      "agent": "planner",
+      "output": "plan.md",
+      "task": "Create a concise implementation plan for this task:\n\n{task}\n\nInclude acceptance criteria, likely files, validation commands, non-goals, and stop conditions. 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 iteration {loop.iteration}.\n\nTask:\n{task}\n\nPlan:\n{outputs.plan}\n\nPrevious review, if any:\n{outputs.review.output}\n\nIf this is iteration 1, implement the planned change. If this is a later iteration, apply only required reviewer fixes. Use the real project stack. Do not add mocks, demos, fake validation, or hidden fallbacks unless explicitly requested. Run focused validation and report changed files, commands with exit codes, evidence, blockers, and remaining risks."
+          },
+          {
+            "id": "review",
+            "agent": "reviewer",
+            "output": "review-{loop.iteration}.json",
+            "gate": {
+              "type": "json-status",
+              "passStatuses": ["approved"],
+              "retryStatuses": ["changes_requested"],
+              "stopStatuses": ["blocked"]
+            },
+            "task": "Review iteration {loop.iteration}. Do not edit project/source files.\n\nTask:\n{task}\n\nPlan:\n{outputs.plan}\n\nBuilder report:\n{outputs.build.output}\n\nReturn ONLY valid JSON:\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\": [\"gap\"],\n  \"requires_user_decision\": false\n}\n\nApprove only if the implementation and evidence satisfy the plan. Request changes for required fixable issues. Block for missing credentials, missing decisions, unsafe scope, or stale plan."
+          }
+        ]
+      }
+    }
+  ]
+}

package/loopflows/plan-review.loopflow.json

@@ -0,0 +1,48 @@
+{
+  "name": "plan-review",
+  "version": "1.0.0",
+  "description": "Planning loop: gather context, draft a plan, review the plan, and revise until approved or blocked before implementation.",
+  "backend": "pi-subprocess",
+  "defaults": {
+    "agentScope": "both"
+  },
+  "steps": [
+    {
+      "id": "context",
+      "agent": "context-builder",
+      "output": "context.md",
+      "task": "Build planning context for this task:\n\n{task}\n\nInspect the repository enough to identify relevant files, constraints, validation commands, risks, and unknowns. Do not edit files."
+    },
+    {
+      "loop": {
+        "id": "plan-review",
+        "maxIterations": 2,
+        "gateStep": "review",
+        "passStatuses": ["approved"],
+        "retryStatuses": ["changes_requested"],
+        "stopStatuses": ["blocked"],
+        "onExhausted": "stop",
+        "body": [
+          {
+            "id": "plan",
+            "agent": "planner",
+            "output": "plan-{loop.iteration}.md",
+            "task": "Draft or revise implementation plan iteration {loop.iteration}.\n\nTask:\n{task}\n\nContext:\n{outputs.context}\n\nPrevious review, if any:\n{outputs.review.output}\n\nReturn a practical implementation plan with scope, non-goals, acceptance criteria, likely files, validation commands, risks, and open questions. Do not edit files."
+          },
+          {
+            "id": "review",
+            "agent": "reviewer",
+            "output": "plan-review-{loop.iteration}.json",
+            "gate": {
+              "type": "json-status",
+              "passStatuses": ["approved"],
+              "retryStatuses": ["changes_requested"],
+              "stopStatuses": ["blocked"]
+            },
+            "task": "Review this implementation plan before any code is written. Do not edit files.\n\nTask:\n{task}\n\nContext:\n{outputs.context}\n\nPlan:\n{outputs.plan}\n\nReturn ONLY valid JSON:\n{\n  \"status\": \"approved\" | \"changes_requested\" | \"blocked\",\n  \"summary\": \"short verdict\",\n  \"findings\": [{\"severity\": \"blocker|required|optional\", \"issue\": \"specific issue\", \"required_fix\": \"specific plan change or null\"}],\n  \"missing_acceptance_criteria\": [\"criterion\"],\n  \"requires_user_decision\": false\n}\n\nApprove only if the plan is specific, scoped, testable, and safe to hand to a worker. Request changes for vague scope, missing validation, or unclear acceptance criteria. Block when user/product decisions or credentials are required."
+          }
+        ]
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-loopflows",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Deterministic loop workflows for Pi subagents: steps, gates, feedback loops, and artifacts.",
   "license": "MIT",
   "author": "Nikita Nosov <20nik.nosov21@gmail.com>",
@@ -26,6 +26,7 @@
     "extensions",
     "loopflows",
     "skills",
+    "scripts",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -36,8 +37,7 @@
     ],
     "skills": [
       "./skills"
-    ],
-    "image": "https://raw.githubusercontent.com/nik1t7n/pi-loopflows/main/assets/pi-loopflows.png"
+    ]
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -51,6 +51,8 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "validate": "node scripts/validate.mjs",
+    "prepublishOnly": "npm run validate && npm run typecheck && npm run pack:check"
   }
 }

package/scripts/validate.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = path.resolve(new URL('..', import.meta.url).pathname);
+const loopflowsDir = path.join(root, 'loopflows');
+const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+
+const errors = [];
+
+function assert(condition, message) {
+  if (!condition) errors.push(message);
+}
+
+assert(pkg.name === 'pi-loopflows', 'package name must be pi-loopflows');
+assert(pkg.keywords?.includes('pi-package'), 'package must include pi-package keyword');
+assert(pkg.pi?.extensions?.includes('./extensions'), 'package pi manifest must expose extensions');
+assert(pkg.pi?.skills?.includes('./skills'), 'package pi manifest must expose skills');
+
+const files = fs.readdirSync(loopflowsDir).filter((file) => file.endsWith('.loopflow.json'));
+assert(files.length >= 3, 'expected bundled launch-control, build-review, and plan-review loopflows');
+
+for (const file of files) {
+  const full = path.join(loopflowsDir, file);
+  let wf;
+  try {
+    wf = JSON.parse(fs.readFileSync(full, 'utf8'));
+  } catch (error) {
+    errors.push(`${file}: invalid JSON: ${error.message}`);
+    continue;
+  }
+
+  assert(typeof wf.name === 'string' && wf.name.length > 0, `${file}: missing name`);
+  assert(typeof wf.description === 'string' && wf.description.length > 0, `${file}: missing description`);
+  assert(Array.isArray(wf.steps) && wf.steps.length > 0, `${file}: steps must be a non-empty array`);
+
+  const topLevelIds = new Set();
+  for (const [index, node] of wf.steps.entries()) {
+    if (node.loop) {
+      const loop = node.loop;
+      assert(typeof loop.id === 'string' && loop.id.length > 0, `${file}: loop ${index} missing id`);
+      assert(Number.isInteger(loop.maxIterations) && loop.maxIterations > 0, `${file}: loop ${loop.id} maxIterations must be positive integer`);
+      assert(Array.isArray(loop.body) && loop.body.length > 0, `${file}: loop ${loop.id} body must be non-empty`);
+      assert(typeof loop.gateStep === 'string' && loop.gateStep.length > 0, `${file}: loop ${loop.id} missing gateStep`);
+      const bodyIds = new Set(loop.body.map((step) => step.id));
+      assert(bodyIds.has(loop.gateStep), `${file}: loop ${loop.id} gateStep not present in body`);
+      for (const step of loop.body) validateStep(file, step, `loop ${loop.id}`);
+    } else {
+      validateStep(file, node, `step ${index}`);
+      if (node.id) {
+        assert(!topLevelIds.has(node.id), `${file}: duplicate top-level step id ${node.id}`);
+        topLevelIds.add(node.id);
+      }
+    }
+  }
+}
+
+function validateStep(file, step, label) {
+  assert(typeof step.id === 'string' && step.id.length > 0, `${file}: ${label} missing id`);
+  assert(typeof step.agent === 'string' && step.agent.length > 0, `${file}: ${label} missing agent`);
+  assert(typeof step.task === 'string' && step.task.length > 0, `${file}: ${label} missing task`);
+  if (step.gate) {
+    assert(step.task.includes('JSON') || step.task.includes('json'), `${file}: gate step ${step.id} should explicitly request JSON`);
+  }
+}
+
+if (errors.length) {
+  console.error(errors.map((e) => `- ${e}`).join('\n'));
+  process.exit(1);
+}
+
+console.log(`Validated ${files.length} loopflows for ${pkg.name}@${pkg.version}`);

package/skills/loopflows/SKILL.md

@@ -1,19 +1,19 @@
 ---
 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.
+description: Use when the user wants deterministic multi-agent workflows, feedback loops between builder/reviewer agents, launch-control style implementation gates, repeatable Pi subagent processes, or custom workflow construction 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.
+Use `loopflow_run` when a task needs process control, not just a linear chain.
 
-Prefer loopflows when work needs:
+A loopflow is a reusable workflow made from subagent steps, gates, and loops. Use it when work should be checked, sent back for fixes, capped by max iterations, or stopped when evidence is missing.
 
-- 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.
+## Built-in loopflows
+
+- `launch-control` — strict plan-as-contract flow: context → plan → build/review loop → final audit.
+- `build-review` — lightweight implementation loop for scoped changes.
+- `plan-review` — review and revise a plan before implementation starts.
 
 ## Commands
 
@@ -38,3 +38,7 @@ 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.
+
+## Customization
+
+Loopflows are `.loopflow.json` files. Copy bundled workflows into `.pi/loopflows/` to customize them for a project: change agents, prompts, max iterations, pass/retry/stop statuses, or final audit rules.