@osolmaz/pi-workflows 0.11.2 → 0.12.0

package/docs/plans/2026-08-21-sanity-check-plan.md

@@ -0,0 +1,175 @@
+---
+title: Add the Sanity Check Workflow
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-21
+---
+
+# Add the Sanity Check Workflow
+
+## Goal
+
+Add a built-in `sanity-check` workflow that reviews a pull request or local contribution before implementation, approval, or merge. The review checks whether the change is needed, duplicates existing code, should use a simpler design, adds unnecessary data models or public plugin APIs, or has scope and test problems.
+
+The workflow runs its model work in temporary read-only Pi sessions. It does not put review prompts or model replies in the Pi session that started the workflow. The origin session receives the final report through a workflow notification that does not start another model turn.
+
+## Scope
+
+The change is limited to pi-workflows. It adds the built-in workflow, the smallest supporting code needed to run isolated read-only Pi sessions, workflow discovery and exports, documentation, unit tests, and real-Pi end-to-end coverage.
+
+The workflow uses existing `action`, `compute`, and `notify` nodes. It does not add a workflow primitive, change a persisted schema, change Pi core, or change the Pi plugin SDK.
+
+The child sessions can use only `read`, `grep`, `find`, and `ls`. They cannot edit files or run shell commands. They are temporary and do not write Pi session files.
+
+## Input
+
+The workflow accepts a review mode and the base reference needed to inspect the current change. Serial mode is the default.
+
+```json
+{
+  "mode": "serial",
+  "baseRef": "origin/main"
+}
+```
+
+`mode` is `serial` or `parallel`. The current repository and checked-out branch are the contribution under review. When `baseRef` is omitted, the workflow tries the remote default branch, the current branch upstream, and the first parent, then uses `HEAD` for a working-tree-only review. Pull request intent, linked issue context, and acceptance criteria are collected when they are available. The workflow also supports a local contribution with no pull request metadata.
+
+## Evidence
+
+The first node collects facts without model judgment. It uses fixed, non-mutating commands to collect:
+
+- the pull request description and linked issue context when available;
+- stated acceptance criteria;
+- the base and head revisions;
+- changed files;
+- the diff and diff statistics;
+- relevant new exports, schemas, persisted fields, and nearby existing code.
+
+Untrusted pull request and repository text is treated as evidence, not as workflow instructions. The evidence is bounded before it enters a model prompt or run bundle.
+
+## Review modes
+
+### Serial mode
+
+Serial mode starts one temporary review session. That session checks all four areas in order:
+
+1. Whether the change is needed.
+2. Duplication and refactoring opportunities.
+3. New data models and public plugin or SDK APIs.
+4. Scope and tests.
+
+The review session must give exact evidence and the strongest case for accepting the current design. A second temporary session verifies and combines the findings. Serial mode therefore uses two model sessions.
+
+### Parallel mode
+
+Parallel mode starts four temporary review sessions at the same time. Each session checks one area:
+
+1. Whether the change is needed.
+2. Duplication and refactoring opportunities.
+3. New data models and public plugin or SDK APIs.
+4. Scope and tests.
+
+Each session must give exact evidence and the strongest case for accepting the current design. After all four sessions finish, one temporary session verifies and combines their findings. Parallel mode therefore uses five model sessions.
+
+## Verification
+
+The final session receives the collected evidence and all review results. It must:
+
+- remove claims that the evidence does not support;
+- require exact file and symbol references for repository claims;
+- separate facts from assumptions;
+- resolve conflicting findings when the evidence permits it;
+- place unresolved questions in the final `unknowns` or contributor questions;
+- return one of `keep`, `simplify`, `refactor`, `drop`, or `needs_evidence`.
+
+There is no extra review loop. Missing product intent or unresolved evidence produces `needs_evidence` instead of an invented conclusion.
+
+## Result
+
+The accepted result contains a verdict, a short summary, findings with evidence, required changes, contributor questions, and unknowns. Findings cover necessity, duplication, data models, public APIs, scope, and tests.
+
+The workflow formats the accepted result as a concise report and sends it to the origin session with `notify({ kind: "final" })`. The notification has `triggerTurn: false`, so the origin model does not restate the report.
+
+## Implementation
+
+Add a built-in definition named `sanity-check` and register it in the built-in catalog and exports. The graph has these stages:
+
+```text
+collect evidence
+      |
+run serial review or four parallel reviews
+      |
+verify and combine
+      |
+notify origin session
+```
+
+The review nodes are function actions. The isolated runner starts Pi in non-interactive JSON mode with no saved session, no discovered extensions or skills, and only the read-only tools:
+
+```text
+--mode json
+--print
+--no-session
+--no-extensions
+--no-skills
+--no-context-files
+--tools read,grep,find,ls
+```
+
+Serial mode starts one combined review and then one verification session. Parallel mode starts the four focused reviews concurrently, waits for all of them, and then starts one verification session. Cancellation and timeout stop every affected child process. Output and error text are bounded. Serialized evidence and review results are also bounded before prompt construction, with an explicit truncation marker when the full input does not fit.
+
+The workflow validates its input and every model result. A missing child result, failed child process, malformed result, cancellation, or timeout fails the active action with a clear bounded error.
+
+## Documentation
+
+Add `sanity-check` to the built-in workflow list and document its input, review modes, read-only session boundary, result, and notification behavior in `docs/workflows.md`. Keep this plan as the record of the selected implementation.
+
+## Tests
+
+Unit tests must cover:
+
+- input validation and the serial default;
+- serial mode starting exactly one review session and one verification session;
+- parallel mode starting exactly four concurrent review sessions and one verification session;
+- the four required review areas;
+- the acceptance case and evidence requirements in every review prompt;
+- read-only child tool arguments and disabled session, extension, and skill discovery;
+- structured result validation and all five verdicts;
+- unsupported and conflicting finding handling in the verification prompt;
+- bounded output and error handling;
+- child failure, malformed output, timeout, cancellation, and process cleanup;
+- final notification delivery without a model turn;
+- built-in discovery and export behavior.
+
+The real-Pi end-to-end test must use the repository test provider. It must not call a real model or make destructive changes.
+
+Before completion, run all checks required by `AGENTS.md`:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+```
+
+## Acceptance criteria
+
+The implementation is complete when:
+
+- `/workflow sanity-check` discovers and starts the built-in workflow;
+- omitted mode selects serial mode;
+- serial mode uses two temporary model sessions;
+- parallel mode uses five temporary model sessions, with the four review sessions running concurrently;
+- child sessions have only read-only repository tools and create no session files;
+- both modes cover all required review questions and the case for accepting the design;
+- final verification rejects unsupported claims and requires exact repository evidence;
+- the final verdict is one of the five selected values;
+- the origin session receives the report without another model turn;
+- documentation and all required checks pass.
+
+## Contract impact
+
+- **Origin session:** The normal workflow start record and one final workflow notification.
+- **Other persistent data:** The normal workflow run bundle only. Child Pi sessions are not saved.
+- **Pi internals:** None.
+- **Pi public API:** Existing documented CLI and extension behavior only.
+- **Pi Workflows public API:** Existing workflow definitions and `action`, `compute`, and `notify` nodes only.

package/docs/run-bundles.md

@@ -183,7 +183,9 @@ A serializable snapshot of the graph taken at run start
 (`pi-workflows.definition-snapshot.v1`). Functions such as prompts and
 validators are not serialized. Each node keeps only its metadata (`nodeType`,
 `timeoutMs`, `statusDetail`, `expectedOutput`, `summary`, `actionExecution`),
-and edges are copied verbatim. Included nodes also record `mountPath`, `localNodeId`, and internal entry or exit status. The top-level `composition.mounts` list records every mount, entry, named exit, and child step limit. The snapshot is what lets viewers draw all nodes, including ones that have not run yet. It is immutable after run start.
+and edges are copied verbatim. A fixed `timeoutMs: null` is preserved and means
+that the node has no wall-clock deadline. Timeout callbacks remain omitted.
+Included nodes also record `mountPath`, `localNodeId`, and internal entry or exit status. The top-level `composition.mounts` list records every mount, entry, named exit, and child step limit. The snapshot is what lets viewers draw all nodes, including ones that have not run yet. It is immutable after run start.
 
 ## Resume and repair
 

package/docs/workflows.md

@@ -16,7 +16,7 @@ Files are discovered by suffix (`.workflow.ts`, `.workflow.js`, `.workflow.mts`,
 3. Workflows built into Pi Workflows
 
 Pi Workflows includes built-in `autoplan`, `autodoc`, `autoimplement`,
-`plan-approval`, and `monitor` workflows. `autoplan` is the current name for the
+`plan-approval`, `sanity-check`, and `monitor` workflows. `autoplan` is the current name for the
 planning workflow that was first released as `autodevise`; the old command and
 export are not retained. A project or global file named `monitor.workflow.ts`
 replaces the built-in monitor. The package registers each built-in in
@@ -161,11 +161,13 @@ then fails the step. If an agent node times out or the workflow is cancelled,
 the extension also aborts its active Pi turn. The model cannot continue to use
 tools after the engine has closed that attempt.
 
-`timeoutMs` can be a finite positive number or a function of the normal node
-context. A timeout function can use prepared outputs to select a deadline for
-this run. It has 30 seconds to return a value. Computed timeout functions are
-runtime code, so definition snapshots omit them; fixed numeric timeouts remain
-in the snapshot.
+`timeoutMs` can be a finite positive number, `null`, or a function of the normal
+node context that returns either value. Omit it to use the 15-minute engine
+default. Set it to `null` to disable only the wall-clock deadline; cancellation,
+parking, claim loss, shutdown, and the node's abort signal still work. A timeout
+function can use prepared outputs to select a policy for this run. It has 30
+seconds to return. Computed timeout functions are runtime code, so definition
+snapshots omit them. Snapshots keep fixed numbers and fixed `null` values.
 
 ### compute
 
@@ -417,12 +419,46 @@ The built-in `autoplan` workflow selects a practical in-scope solution and write
 
 The built-in `plan-approval` workflow offers verified human `continue`, `stop`, and exact-text `replan` exits. It is optional. A replan exit returns the unchanged text to autoplan, documents the revised plan, and asks again through a new plan digest.
 
-Autoimplement writes and runs the exact Pi Reviewer command. It records P0 through P2 by review round. P0 or P1 work requires another review. P2-only work can be addressed and verified without another reviewer run. CI tracking commands are also explicit. One CI watch lasts at most five minutes, after which the model runs more useful local tests before checking CI again.
+Autoimplement runs independent commands through bounded command batches. A batch is an ordinary function action that calls the public `runCommandBatch` helper. Each command has a stable ID, executable, arguments, absolute working directory, timeout, and output limit. Results stay separate and return in input order. One command uses the same path with concurrency one.
+
+Autoimplement gives `implement` an eight-hour deadline. When a supported
+long-running agent node times out, one shared read-only fallback inspects the
+current repository, accepted workflow outputs, and relevant pull-request state.
+It then retries the timed-out stage or routes to verification, review, CI,
+delivery, the existing redesign workflow, or blocked. The fallback can run at
+most three times in one Autoimplement run. Its own failure or timeout is
+terminal. Cancellation remains immediate and never enters fallback. A repeated
+effect step first checks what already exists and performs only missing work.
+This graph fallback starts after the timed-out turn ends and is separate from
+successor-turn delivery.
+
+Autoimplement uses batches for pi-reviewer, pending CI watches, and local verification commands from independent repositories. It keeps model turns, fixes, pushes, comment changes, merges, and releases in their existing order. Reviewer commands are tied to the repository, base branch, pushed head, and relevant dependency fingerprint. A later review round includes only repositories whose head or dependency fingerprint changed. P0 or P1 work still requires another review. P2-only work can be addressed and verified without another reviewer run only because of that P2 work.
+
+Autoimplement inspects every pull request before it waits for CI. It accepts only supported pending `gh pr checks --watch` or `gh run watch` descriptors and binds each one to the validated pull request as `gh pr checks <PR URL> --watch`. Repository and pull-request overrides are rejected. One watch lasts at most five minutes. A failed or timed-out watch affects only its pull request. When checks remain pending, the model runs more useful local tests before checking CI again. Autoimplement does not invent an ETA.
+
+The action abort signal stops active command process groups and prevents queued commands from starting. Accepted outputs use the existing trace and artifacts. An interrupted unaccepted batch runs again because batch commands are read-only or isolated local checks. Progress updates contain metadata only and never control routing. Truncated reviewer or CI output cannot count as clean. See [Run independent commands in bounded batches](plans/2026-08-20-bounded-command-batches-plan.md) for the complete contract and implementation plan.
 
 A model-generated blocker from implementation or a safe later stage does not end autoimplement by itself. A separate blocker-challenge agent checks the task, approved plan, current result, evidence, scope, authority, earlier attempts, and practical alternatives. It confirms a blocker only when the blocker exists now, is outside the granted authority, has no safe path forward, has an empty next action, and includes concrete evidence and checked alternatives. A rejected blocker must name the next practical action and routes through the existing redesign workflow before implementation and verification continue.
 
 Autoimplement can run the blocker challenge at most three times in one run. Each later challenge receives the earlier challenge results. Reaching the limit stops with the normal workflow safety-limit reason. Explicit human stops, cancellation, exhausted workflow or replan limits, protected authorization gaps, and an independent blocked result from redesign remain direct stops. These hard boundaries do not enter the blocker challenge.
 
+### Built-in sanity check
+
+The built-in `sanity-check` workflow reviews a pull request or local contribution before implementation, approval, or merge. It checks whether the change is needed, duplicates existing code, should use a simpler design, adds unnecessary data models or public plugin and SDK APIs, or has scope and test problems.
+
+```json
+{
+  "mode": "serial",
+  "baseRef": "origin/main"
+}
+```
+
+Serial mode is the default. It runs one temporary read-only Pi session for all four review areas, then one temporary session to verify and combine the findings. Parallel mode runs four focused review sessions at the same time, then one verification session. Serial mode uses two model sessions. Parallel mode uses five. When `baseRef` is omitted, the workflow tries the remote default branch, the current branch upstream, and the first parent, then uses `HEAD` for a working-tree-only review.
+
+The workflow collects pull request intent and repository diff evidence before model review. It bounds serialized evidence and review results before prompt construction and marks truncated input. Every review must cite evidence and give the strongest case for accepting the current design. The verification session removes unsupported claims, requires exact file and symbol references, resolves supported conflicts, and returns `keep`, `simplify`, `refactor`, `drop`, or `needs_evidence`.
+
+Child sessions have only `read`, `grep`, `find`, and `ls`. They do not load discovered extensions, skills, or repository context files, cannot mutate the repository, and do not save Pi session files. The workflow sends the final report through a final notification with `triggerTurn: false`, so the origin model does not produce another response. See [the Sanity Check plan](plans/2026-08-21-sanity-check-plan.md) for the selected implementation and test boundaries.
+
 ### Built-in monitor
 
 The built-in `monitor` workflow turns a plain request for repeated checks into
@@ -496,9 +532,10 @@ use the same card and keep the active attempt id.
 
 Headless RPC execution receives the same complete prompt without TUI metadata.
 Workflow notifications use a separate message type with `triggerTurn: false`,
-so a notification does not start an assistant response. See
-[WORKFLOW_STEP_MESSAGES.md](WORKFLOW_STEP_MESSAGES.md) for the message contract
-and renderer rules.
+so a notification does not start an assistant response. Deferred successor turns
+use an internal turn-intent contract instead of the notification outbox. See
+[WORKFLOW_STEP_MESSAGES.md](WORKFLOW_STEP_MESSAGES.md) for the step-message contract
+and [Deferred workflow turns](DEFERRED_TURNS.md) for the successor-turn contract.
 
 ## Result presentation
 
@@ -521,9 +558,11 @@ After the final run state has been persisted, the Pi extension sends the
 presentation instructions and bounded final result to the model as a hidden
 follow-up message. The next visible message is a normal assistant response.
 Returning `undefined`, returning an empty string, or omitting
-`presentationPrompt` produces no follow-up. Failed, timed-out, and cancelled
-runs are never presented; the extension reports their persisted status and
-error directly. Async prompt builders have 30 seconds to finish and receive an
+`presentationPrompt` produces no presentation. Failed, timed-out, and cancelled
+runs are never presented. When one of those outcomes would otherwise strand an
+agent after a workflow-caused turn abort or asynchronous crash, the extension
+uses the deferred-turn contract to send one factual fallback after settlement.
+Async prompt builders have 30 seconds to finish and receive an
 `AbortSignal` that fires on timeout, session shutdown, or when a new workflow
 or normal user turn starts; stale presentations are discarded. Once a presentation message has
 been queued, another workflow cannot start until that assistant response
@@ -561,13 +600,17 @@ possible. Defaults worth knowing:
   and `running`. `workflow status` and `workflow cancel` accept the run ID before a run bundle
   exists.
 - If deferred activation fails, the queue stores a bounded safe error, releases the session
-  reservation, and sends one follow-up turn to the initiating model. The model can correct the
-  cause and make a new explicit start call. Pi Workflows does not retry blindly.
-- `/workflow cancel` aborts the current node and marks the run `cancelled`.
-  When no run is live but the widget still shows a parked or finished run,
-  the same command clears the widget.
+  reservation, and creates one deferred-turn intent for the initiating session. A workflow that
+  reports `started` and then crashes before its first prompt follows the same path. The model gets
+  one factual follow-up after settlement and can make a new explicit start call. Pi Workflows does
+  not retry blindly.
+- An agent-issued `workflow cancel` aborts the current node and the current Pi turn, then creates
+  one deferred-turn intent. The next natural workflow message resolves it when possible; otherwise
+  one factual fallback starts after settlement. Direct `/workflow cancel` remains quiet because it
+  is explicit user control. When no run is live but the widget still shows a parked or finished run,
+  the command clears the widget.
 - One workflow runs per session at a time.
-- After the workflow tool accepts an agent-step submission, the extension removes any assistant tail text from the rest of that agent run. The next workflow message or notification is the visible continuation. Explicit final presentation remains a separate opt-in response.
+- After the workflow tool accepts an agent-step submission, the extension removes any assistant tail text from the rest of that agent run. The next workflow message is the visible continuation. A deferred intent makes a workflow prompt, presentation, and factual fallback compete to provide one successor turn, so an abort cannot produce two continuation turns.
 - Agent nudges: if the model ends its turn without submitting the pending
   step, it gets a reminder, twice by default, then the step fails.
 

package/examples/workflows/command-batch.workflow.ts

@@ -0,0 +1,50 @@
+import {
+  action,
+  compute,
+  defineWorkflow,
+  runCommandBatch,
+  type CommandBatchRequest,
+} from "@osolmaz/pi-workflows";
+
+type Input = {
+  cwd: string;
+};
+
+export default defineWorkflow({
+  name: "command-batch",
+  input: (value): Input => value as Input,
+  startAt: "prepare",
+  nodes: {
+    prepare: compute({
+      run: ({ input }) =>
+        ({
+          maxConcurrency: 2,
+          items: [
+            {
+              id: "first",
+              command: "printf",
+              args: ["%s", "first"],
+              cwd: (input as Input).cwd,
+              timeoutMs: 10_000,
+              maxOutputChars: 10_000,
+            },
+            {
+              id: "second",
+              command: "printf",
+              args: ["%s", "second"],
+              cwd: (input as Input).cwd,
+              timeoutMs: 10_000,
+              maxOutputChars: 10_000,
+            },
+          ],
+        }) satisfies CommandBatchRequest,
+    }),
+    run: action({
+      run: async (context) =>
+        await runCommandBatch(context.outputs.prepare as CommandBatchRequest, {
+          signal: context.signal,
+        }),
+    }),
+  },
+  edges: [{ from: "prepare", to: "run" }],
+});

package/examples/workflows/sanity-check.workflow.ts

@@ -0,0 +1 @@
+export { sanityCheckWorkflow as default } from "@osolmaz/pi-workflows/builtins";

package/herdr-plugin.toml

@@ -1,8 +1,8 @@
 id = "osolmaz.pi-workflows"
-name = "Pi Workflows"
-version = "0.11.2"
+name = "pi-workflows"
+version = "0.12.0"
 min_herdr_version = "0.7.0"
-description = "Open the active Pi Workflows run in piw from a managed Herdr pane."
+description = "Open the active pi-workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]
 
 [[panes]]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/schemas/decision-presentation-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/decision-presentation-v1.schema.json",
-  "title": "Pi Workflows decision presentation v1",
+  "title": "pi-workflows decision presentation v1",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "summary", "blocks"],

package/schemas/human-decision-accepted-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-accepted-v1.schema.json",
-  "title": "Pi Workflows accepted human decision v1",
+  "title": "pi-workflows accepted human decision v1",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-accepted-v2.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-accepted-v2.schema.json",
-  "title": "Pi Workflows accepted human decision v2",
+  "title": "pi-workflows accepted human decision v2",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-answer-attempt-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-answer-attempt-v1.schema.json",
-  "title": "Pi Workflows human decision answer attempt v1",
+  "title": "pi-workflows human decision answer attempt v1",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-cancellation-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-cancellation-v1.schema.json",
-  "title": "Pi Workflows human decision cancellation v1",
+  "title": "pi-workflows human decision cancellation v1",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "decisionId", "requestDigest", "cancelledAt", "reason"],

package/schemas/human-decision-continuation-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-continuation-v1.schema.json",
-  "title": "Pi Workflows human decision continuation v1",
+  "title": "pi-workflows human decision continuation v1",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "decisionId", "requestDigest", "parentRunId", "runId", "createdAt"],

package/schemas/human-decision-delivery-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-delivery-v1.schema.json",
-  "title": "Pi Workflows human decision delivery v1",
+  "title": "pi-workflows human decision delivery v1",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-delivery-v2.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-delivery-v2.schema.json",
-  "title": "Pi Workflows human decision delivery v2",
+  "title": "pi-workflows human decision delivery v2",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-receipt-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-receipt-v1.schema.json",
-  "title": "Pi Workflows redacted human decision receipt v1",
+  "title": "pi-workflows redacted human decision receipt v1",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-receipt-v2.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-receipt-v2.schema.json",
-  "title": "Pi Workflows redacted human decision receipt v2",
+  "title": "pi-workflows redacted human decision receipt v2",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-request-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-request-v1.schema.json",
-  "title": "Pi Workflows human decision request v1",
+  "title": "pi-workflows human decision request v1",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-request-v2.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-request-v2.schema.json",
-  "title": "Pi Workflows human decision request v2",
+  "title": "pi-workflows human decision request v2",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/schemas/human-decision-resolution-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-resolution-v1.schema.json",
-  "title": "Pi Workflows human decision resolution v1",
+  "title": "pi-workflows human decision resolution v1",
   "oneOf": [
     {
       "type": "object",

package/schemas/human-decision-resolution-v2.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-resolution-v2.schema.json",
-  "title": "Pi Workflows human decision resolution v2",
+  "title": "pi-workflows human decision resolution v2",
   "oneOf": [
     {
       "type": "object",

package/schemas/human-decision-settlement-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-settlement-v1.schema.json",
-  "title": "Pi Workflows human decision settlement v1",
+  "title": "pi-workflows human decision settlement v1",
   "type": "object",
   "additionalProperties": false,
   "required": [

package/skills/autodoc/SKILL.md

@@ -1,12 +1,43 @@
 ---
 name: autodoc
 description: Use when an existing selected solution or clear implementation plan must be recorded or updated in canonical documentation before implementation, including choosing the right repository and applying SimpleDoc conventions.
-compatibility: Requires Pi Workflows and the built-in autodoc workflow.
+compatibility: Requires pi-workflows and the built-in autodoc workflow.
 ---
 
 # Autodoc
 
-Use the built-in `autodoc` Pi Workflow when it is available. At top level, list workflows, then start `autodoc` once with the task, existing plan, repository, known documents, and evidence from the conversation. Do not manually duplicate stages owned by the workflow.
+## Start the workflow
+
+Use the built-in `autodoc` workflow when it is available. At top level, list workflows, build the complete input, and start `autodoc` once. Do not manually duplicate stages owned by the workflow.
+
+Build the input as follows:
+
+- `task`: State what selected plan must be recorded and that this run is documentation-only.
+- `plan`: Pass the complete selected plan. Autodoc does not devise or improve it.
+- `repository`: Use the absolute path of the repository that owns the canonical documentation.
+- `documents`: Include every known canonical specification or plan candidate. Use an empty array when none is known.
+- `evidence`: Include implementation evidence or current-document evidence when it affects whether documentation is current.
+
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "autodoc",
+  "input": {
+    "task": "Record the selected timeout fallback plan without implementing it.",
+    "plan": {
+      "summary": "Add one bounded read-only timeout fallback.",
+      "requirements": ["Keep cancellation terminal."]
+    },
+    "repository": "/absolute/path/to/repository",
+    "documents": ["docs/plans/timeout-fallback-plan.md"],
+    "evidence": {
+      "currentBehavior": "A timeout ends the run."
+    }
+  }
+}
+```
 
 When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract.