@osolmaz/pi-workflows 0.11.2 → 0.12.1

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-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.
 

package/skills/autoimplement/SKILL.md

@@ -1,10 +1,84 @@
 ---
 name: autoimplement
-description: Use when the user asks to implement a plan end-to-end, test it, run Pi Reviewer against the base branch in a loop until no P0/P1 issues remain, and make sure CI/CD is green before finishing.
+description: Use when the user asks to implement a plan end-to-end, test it, run pi-reviewer against the base branch in a loop until no P0/P1 issues remain, and make sure CI/CD is green before finishing.
 compatibility: Requires Pi Workflows and the built-in autoimplement workflow.
 ---
 
-Use the built-in `autoimplement` Pi Workflow when it is available. At top level, list workflows, then start `autoimplement` once with the task, existing plan, repository, scope, constraints, base branch, and merge policy from the conversation. Set `merge: true` only when the user explicitly requested merge or an applicable standing instruction authorizes it. Otherwise set it to false. Do not manually duplicate stages already owned by the workflow.
+# Autoimplement
+
+## Start the workflow
+
+Use the built-in `autoimplement` workflow when it is available. At top level, list workflows, build the complete input, and start `autoimplement` once. Do not start with a partial input and repair it in later turns.
+
+Build the input as follows:
+
+- `task`: Preserve the user's requested end state.
+- `plan`: Pass the selected plan or the full contents of its canonical plan document. Do not devise a new initial plan.
+- `repository`: Use the absolute path of the repository that owns the work.
+- `scope`: Always include a concrete authority statement. Name every allowed repository and the allowed edit, test, commit, push, pull-request, merge, and release actions. Carry forward exclusions from the conversation. A repository path alone is not a scope.
+- `constraints`: Include all applicable user and repository constraints. Use an empty array when none apply.
+- `baseBranch`: Use the requested base or the repository default branch.
+- `merge`: Set `true` only when the user explicitly requested merge or an applicable standing instruction authorizes it. Otherwise set `false`.
+- `documents`: Include known canonical plan or specification paths. Use an empty array when none are known.
+- `approval`: Omit it for the default behavior: ask on each new plan and continue after 10 minutes without an answer. Use `{ "mode": "required" }` when the user says to block on plan changes. Use `{ "mode": "skip" }` when the user says to continue without asking about plan changes.
+- `concurrency`: Include it only when the conversation gives explicit limits.
+
+When one repository is clearly named, derive the scope without asking the user to restate it. A safe derived scope permits only work needed for the task in that repository, including local verification and normal branch and pull-request publication. It excludes unrelated repositories, merge, release, deployment, credentials, and policy changes unless those actions are explicitly authorized.
+
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "autoimplement",
+  "input": {
+    "task": "Implement the selected timeout fallback plan end to end.",
+    "plan": {
+      "canonicalDocument": "docs/plans/timeout-fallback-plan.md",
+      "summary": "Add a bounded timeout fallback.",
+      "requirements": [
+        "Route supported timeouts to one read-only fallback.",
+        "Keep cancellation terminal."
+      ],
+      "verification": ["npm run check", "npm run test:e2e"]
+    },
+    "repository": "/absolute/path/to/repository",
+    "scope": "Only /absolute/path/to/repository. May edit and test task-related files, create commits, push the task branch, and open or update its pull request. Must not modify other repositories, merge, release, deploy, change credentials, or change repository policy.",
+    "constraints": ["Preserve immediate cancellation.", "Keep deferred-turn work separate."],
+    "baseBranch": "main",
+    "merge": false,
+    "documents": ["docs/plans/timeout-fallback-plan.md"]
+  }
+}
+```
+
+### Plan-change decisions
+
+The workflow gates only plans that it creates or changes after the run starts. A supplied or discovered existing plan does not receive another decision.
+
+Use required approval when the user says to block on plan changes:
+
+```json
+{
+  "approval": {
+    "mode": "required"
+  }
+}
+```
+
+Skip plan decisions when the user says to accept every new plan immediately:
+
+```json
+{
+  "approval": {
+    "mode": "skip"
+  }
+}
+```
+
+Omit `approval` for autonomous mode. It asks the `operator` audience and continues with the exact presented plan after 10 minutes without an accepted answer. The workflow owns this decision. The model must not answer the protected decision through the workflow tool.
+
+Do not manually duplicate stages already owned by the workflow. Autoimplement runs independent pi-reviewer commands, pending CI watches, and local verification commands from separate repositories in bounded batches. It keeps model turns, fixes, pushes, comment changes, merges, and releases ordered. One repository uses the same batch path with concurrency one.
 
 When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract with the available tools.
 
@@ -21,29 +95,36 @@ Outside Pi, or when the workflow is unavailable, do the following in the order t
 
 2. Once you finish implementing, make sure to test it.
    - This will depend on the nature of the problem. If needed, run local smoke tests, spin up dev servers, make requests and such.
+   - Run commands from independent repositories in a bounded batch only when their working directories are distinct and local resources can support the overlap.
+   - Keep one repository's dependent checks in order. Do not batch shell wrappers, remote mutations, package publication, or commands with unclear side effects.
    - Try to test as much as possible, without merging.
    - State explicitly what could not be tested locally and what still needs staging or production verification.
    - Do not put mutation testing on the critical path unless repository policy explicitly requires it; keep the mutation test scripts available.
 
 3. Push your latest commits before running review so the review is always against the current PR head.
-   - Run Pi Reviewer with its configured defaults against the base branch: `pi-reviewer --base <branch_name>`. The model and thinking level come from the reviewer's own config, not from this skill.
-   - Use a 10 minute timeout on the tool call available to the model, not the shell `timeout` program. If Pi Reviewer takes more than 10 minutes, kill it.
-   - Do not silently fall back to `codex review` when Pi Reviewer is unavailable; stop and report the missing command or configuration.
-   - Record every review round with separate P0, P1, P2, and lower findings.
-   - Run Pi Reviewer in a loop and address any P0 or P1 issues until there are none left.
-   - If a round reports only P2 or lower findings, address valid proportionate P2 findings, verify and push them, then move to the next stage without running Pi Reviewer again solely because of that P2 work.
+   - Run pi-reviewer with its configured defaults against the base branch: `pi-reviewer --base <branch_name>`. The model and thinking level come from the reviewer's own config, not from this skill.
+   - Run reviewer commands for independent repositories in one bounded batch. Keep each result tied to its repository, base branch, pushed head, and relevant dependency fingerprint.
+   - In later rounds, rerun only repositories whose pushed head or relevant dependency fingerprint changed.
+   - Use a 10 minute timeout for each reviewer item, not the shell `timeout` program. If pi-reviewer takes more than 10 minutes, stop that item.
+   - Do not silently fall back to `codex review` when pi-reviewer is unavailable; stop and report the missing command or configuration for that repository.
+   - Treat truncated reviewer output as an invalid review, never a clean result.
+   - Record every review round with separate P0, P1, P2, and lower findings for each repository.
+   - Run pi-reviewer in a loop and address any P0 or P1 issues until there are none left.
+   - If a round reports only P2 or lower findings, address valid proportionate P2 findings, verify and push them, then move to the next stage without running pi-reviewer again solely because of that P2 work.
    - Ignore issues about supporting legacy behavior unless the plan requires compatibility.
-   - Look at CI only after Pi Reviewer passes, meaning the last completed run found no issues or only P2 or lower issues.
+   - Look at CI only after pi-reviewer passes, meaning the last completed run found no issues or only P2 or lower issues.
 
-4. Pi Reviewer reports findings locally and does not post them to the pull request.
+4. pi-reviewer reports findings locally and does not post them to the pull request.
    - Separately check existing inline review comments and PR issue comments, and address valid comments.
    - Ignore irrelevant comments and stale comments from before the latest commit unless they still apply.
    - Reply to and resolve each comment either way.
    - Do not wait a fixed five minutes; wait only when a required review is known to be pending, and keep that wait bounded.
 
 5. In the final step, make sure that CI/CD is green.
-   - Inspect CI once before deciding to wait. If waiting is useful, state and run the exact `gh` tracking command.
-   - Bound one CI watch to five minutes. If CI is still pending, use the next model turn for additional useful local tests or smoke tests instead of waiting. Then inspect CI again.
+   - Inspect every pull request once before deciding to wait. If waiting is useful, state the exact `gh` tracking command for each pending pull request.
+   - Run supported pending CI watches in one bounded batch. Keep every result tied to its pull request and current head.
+   - Bound each CI watch to five minutes. If CI is still pending, use the next model turn for additional useful local tests or smoke tests instead of waiting. Then inspect CI again.
+   - Do not invent an ETA when the CI provider does not supply one.
    - Ignore the fails unrelated to your changes, others break stuff sometimes and don't fix it.
    - Make sure whatever changes you did don't break anything.
    - If CI/CD is not fully green, state explicitly which failures are unrelated and why.

package/skills/autoplan/SKILL.md

@@ -1,12 +1,36 @@
 ---
 name: autoplan
 description: Use when the user asks to devise, choose, or plan the most elegant long-term production-ready solution, compare it with the ideal end state, and produce the best practical in-scope implementation plan without asking the user to resolve the gap.
-compatibility: Requires Pi Workflows and the built-in autoplan workflow.
+compatibility: Requires pi-workflows and the built-in autoplan workflow.
 ---
 
 # Autoplan
 
-Use the built-in `autoplan` Pi Workflow when it is available. At top level, list workflows, then start `autoplan` once with the problem, authorized scope, constraints, previous plan, and new evidence from the conversation.
+## Start the workflow
+
+Use the built-in `autoplan` workflow when it is available. At top level, list workflows, build the complete input, and start `autoplan` once.
+
+Build the input as follows:
+
+- `problem`: State the decision or implementation-planning problem and its observable end state.
+- `scope`: Name the repositories, systems, and interfaces that may change. State important exclusions. Derive an unambiguous repository-local scope without asking the user to restate it.
+- `constraints`: Preserve all user, repository, safety, compatibility, cost, and authority limits. Use an empty array when none apply.
+- `previousPlan`: Include it only when revising an existing plan.
+- `newEvidence`: Include it only when evidence caused the revision request.
+
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "autoplan",
+  "input": {
+    "problem": "Choose a production-ready timeout fallback and write its implementation plan.",
+    "scope": "Only /absolute/path/to/repository. Plan changes to its public workflow API, built-in workflow, tests, and documentation. Exclude Pi core, external services, credentials, releases, and unrelated repositories.",
+    "constraints": ["Keep cancellation terminal.", "Use only documented public interfaces."]
+  }
+}
+```
 
 When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract.
 

package/skills/monitor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: monitor
 description: Use when the user asks to monitor, watch, track, or periodically check a running command, remote Job, CI run, deployment, publication, or other long-running objective. Starts the built-in Pi monitor workflow immediately in the current session and drives the objective autonomously, including routine recovery, until verified completion or a material blocker.
-compatibility: Requires Pi Workflows and the built-in monitor workflow.
+compatibility: Requires pi-workflows and the built-in monitor workflow.
 ---
 
 # Monitor
@@ -10,9 +10,9 @@ Use the built-in Pi `monitor` workflow as an autopilot for the requested objecti
 
 A monitor request authorizes routine, bounded work needed to preserve and finish the stated objective, subject to the conversation and repository approval boundaries. Apply other skills as safety and operating instructions. Do not turn their normal checks into new approval requests when the monitored objective and an existing approval already cover the action. Monitoring does not authorize changing the objective, method, model, data source, production selection, or other consequential contract.
 
-## Prepare and start without delay
+## Start the workflow without delay
 
-As soon as the user invokes this skill:
+Build the complete input and start the workflow in the same turn. As soon as the user invokes this skill:
 
 1. Read the current conversation, active plan, repository instructions, and applicable compute, runtime, credential, deployment, or publication skills.
 2. Preserve the exact objective, immutable execution contract, current identifiers, durable progress, cost already spent, approval ceilings, finish criteria, and known recovery rules in the workflow input. Write or update a durable plan or incident note first only when the work needs one for safe continuation.
@@ -29,15 +29,73 @@ Derive the workflow input from the full conversation:
 - `task`: State the complete objective, the exact current target and stable identifiers, authoritative status sources, durable progress and final-output surfaces, routine actions authorized by the monitor request, other recorded approvals, immutable boundaries, cost and credential rules, and required validation or downstream operations.
 - `everyMinutes`: Use the user's interval when present. Use `30` when the user gives no interval. The built-in workflow accepts intervals from 1 minute through 24 hours.
 - `stopWhen`: Infer verified completion from the full conversation. Describe completion of the complete objective, not only the end of one physical process. Also name material blockers that require human intervention.
-- `repair`: Include this object only when the request or an existing approval authorizes mutation. Set `authorized: true` and record the repository, scope, base branch, merge policy, and constraints that apply. Omit it for observation-only work.
+- `repair`: Include this object only when the request or an existing approval authorizes mutation. Set `authorized: true` and record the repository, scope, base branch, merge policy, and constraints that apply. Omit it for observation-only work. Omit `repair.approval` for the default behavior: ask on each new repair plan and continue after 10 minutes without an answer. Use `{ "mode": "required" }` to block on plan changes or `{ "mode": "skip" }` to continue without asking.
+
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "monitor",
+  "input": {
+    "task": "Monitor GitHub Actions run 123456 in owner/repository. Inspect the run and its artifacts, retry only transient status reads, and report each check. Do not change code or repository state.",
+    "everyMinutes": 5,
+    "stopWhen": "Stop when run 123456 completes and its required artifacts are verified, or when a material external blocker prevents truthful verification.",
+    "checkTimeoutMinutes": 10
+  }
+}
+```
+
+For authorized repair, add a complete `repair` object instead of leaving mutation authority implicit:
+
+```json
+{
+  "repair": {
+    "authorized": true,
+    "repository": "/absolute/path/to/repository",
+    "scope": "Only /absolute/path/to/repository. May diagnose and fix failures related to the monitored objective, test, commit, push, and update its pull request. Must not modify other repositories, merge, release, deploy, change credentials, or change repository policy.",
+    "constraints": ["Keep the monitored objective and method unchanged."],
+    "baseBranch": "main",
+    "merge": false
+  }
+}
+```
 
 When the conversation gives no clear finish criterion, set `stopWhen` to `Stop only when the user explicitly asks to stop.` Do not use that fallback when a broader implementation, repair, publication, or deployment objective is clear from context.
 
 Do not invent a finite check count. Omit `maxChecks` unless the user explicitly requests one. The workflow host can apply its own safety upper bound. Disclose that bound if it appears.
 
-When repair is authorized, route a concrete code or design defect through the monitor's composed repair path. Supply the problem, observed evidence, and a stable fingerprint of the issue plus target state. The workflow runs outer `autoplan`, standalone `autodoc`, optional `plan-approval`, `autoimplement`, and internal redesign when needed, then checks the target again. Do not copy their prompts into the monitor task.
+When repair is authorized, route a concrete code or design defect through the monitor's shared plan-change path. Supply the problem, observed evidence, and a stable fingerprint of the issue plus target state. The path runs Autoplan, Autodoc, the configured plan decision, and Autoimplement, then checks the target again. Autoimplement does not ask again for the plan selected by Monitor. It uses the same shared path if later evidence requires another plan. Do not copy their prompts into the monitor task.
+
+### Repair plan decisions
+
+Omit `repair.approval` for autonomous mode. It asks the `operator` audience and continues with the exact presented plan after 10 minutes without an accepted answer.
+
+Block until the operator answers:
+
+```json
+{
+  "repair": {
+    "approval": {
+      "mode": "required"
+    }
+  }
+}
+```
 
-Add `repair.approval` only when the user requests a human plan decision. Set its named `audience` and a bounded `maxReplans`. A verified continue answer starts implementation. Stop ends the repair truthfully. Replan preserves the exact operator text, sends it back to autoplan, documents the revised plan, and asks again. The model-facing workflow answer tool cannot answer this gate.
+Continue without asking:
+
+```json
+{
+  "repair": {
+    "approval": {
+      "mode": "skip"
+    }
+  }
+}
+```
+
+`continue` starts implementation. `stop` ends the repair truthfully. `replan` preserves the exact operator text, sends it through the shared plan-change workflow, records the revised plan, and asks again. The model-facing workflow answer tool cannot answer this gate.
 
 ## Keep routine work moving
 
@@ -60,23 +118,7 @@ When the paid action remains within the approved method, hardware, concurrency,
 
 The monitor may use a credential only when the conversation or repository has already authorized that credential's source, destination, and purpose. It may reuse that authorization for retries and replacement attempts under the same objective. It must not discover unrelated credentials, broaden scopes, copy credentials to a new store, or print secret values.
 
-## Start the workflow
-
-Start the built-in workflow in the current session with this shape:
-
-```text
-workflow({
-  action: "start",
-  workflow: "monitor",
-  input: {
-    task: "<complete objective, contract, recovery authority, and verification task>",
-    everyMinutes: 30,
-    stopWhen: "<derived finish criterion or explicit-user-stop fallback>"
-  }
-})
-```
-
-Use the user-supplied interval instead of `30` when present. Add `maxChecks` only when the user explicitly supplies that limit. Do not send `reportWhen`; the current monitor reports every accepted check.
+Use the user-supplied interval instead of the example value when present. Add `maxChecks` only when the user explicitly supplies that limit. Do not send `reportWhen`; the current monitor reports every accepted check.
 
 Do not start a second monitor for the same objective while one is active. Update or replace the run only when the objective or contract changes. A replacement must preserve the previous accepted observation and durable recovery state.
 
@@ -115,7 +157,7 @@ Submit observed facts. The workflow computes rates, confidence, remaining work,
 
 For several concurrent processes, publish one stable track per process. The Pi widget and viewers show them separately and keep each ETA independent.
 
-Keep the monitored target independent of Pi Workflows. Do not require a target Job or application to import Pi Workflows, emit a Pi schema, write a Pi progress file, expose a Pi endpoint, create a progress store, or add a progress reader command solely for monitoring. Do not add provider-specific clients or credentials to Pi Workflows. Target-specific observation belongs in the check task and is performed by the regular Pi model with already authorized tools.
+Keep the monitored target independent of pi-workflows. Do not require a target Job or application to import pi-workflows, emit a Pi schema, write a Pi progress file, expose a Pi endpoint, create a progress store, or add a progress reader command solely for monitoring. Do not add provider-specific clients or credentials to pi-workflows. Target-specific observation belongs in the check task and is performed by the regular Pi model with already authorized tools.
 
 Before proposing a new progress API, transport, schema, or persistence layer, prove that the model cannot observe the needed facts and publish them through the existing `workflow update` and `submit` path. If the target does not expose enough facts for ETA, report `ETA unavailable`. Application telemetry changes require separate scope and should expose normal operational facts rather than a Pi-specific protocol.
 

package/skills/pi-workflows/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: pi-workflows
-description: Use when creating, reviewing, debugging, starting, inspecting, or controlling Pi Workflows; authoring .workflow.ts files; using the workflow tool; handling workflow step contracts, checkpoints, updates, or progress; or deciding how a task should compose workflow primitives.
-compatibility: Requires the Pi Workflows extension.
+description: Use when creating, reviewing, debugging, starting, inspecting, or controlling pi-workflows; authoring .workflow.ts files; using the workflow tool; handling workflow step contracts, checkpoints, updates, or progress; or deciding how a task should compose workflow primitives.
+compatibility: Requires the pi-workflows extension.
 ---
 
-# Pi Workflows
+# pi-workflows
 
-Use Pi Workflows for durable multi-step work that needs explicit routing, retries, checkpoints, scheduled waits, or progress. Keep simple one-turn work outside a workflow.
+Use pi-workflows for durable multi-step work that needs explicit routing, retries, checkpoints, scheduled waits, or progress. Keep simple one-turn work outside a workflow.
 
 The `workflow` tool schema is the authority for call shapes. A workflow step message is the authority for its current step id, attempt id, and expected output. Do not guess these values from an earlier attempt.
 
@@ -22,7 +22,21 @@ Use the smallest applicable action:
 - `update` publishes a non-completing durable update for the active step attempt.
 - `submit` completes the active agent step with its required output.
 
-Use `start` only once for one requested run. Do not build a manual polling loop around a workflow that already schedules its own work. Use the `monitor` skill for monitoring requests.
+Use `start` only once for one requested run. Before starting, load the matching workflow skill when one exists and build its complete input. Include scope, authority, constraints, identifiers, and finish criteria required by that skill. Do not start with placeholders that still need user or model repair.
+
+For a workflow without a specialized skill, inspect its input contract and make one complete call. For example:
+
+```json
+{
+  "action": "start",
+  "workflow": "examples/workflows/echo.workflow.ts",
+  "input": {
+    "task": "Summarize this repository in one sentence."
+  }
+}
+```
+
+Do not build a manual polling loop around a workflow that already schedules its own work. Use the `monitor` skill for monitoring requests.
 
 ## Complete agent steps
 
@@ -57,7 +71,8 @@ Follow these rules:
 - Give included workflows named exits, map their input explicitly, and keep parent edges out of child internals.
 - Keep `compute` pure. Put external effects in agent, function-action, or shell-action nodes.
 - Use structured node outputs for routing.
-- Use an ordinary checkpoint for external continuation data that the model may submit. Use `humanDecision()` for a verified human choice, and use the included `plan-approval` workflow for standard continue, stop, and exact-text replan routing.
+- Use an ordinary checkpoint for external continuation data that the model may submit. Use `humanDecision()` for a verified human choice. Use its typed `onTimeout` policy only when the workflow may supply a named automatic response after a durable deadline. A timeout response is recorded as policy provenance, not as a human answer.
+- Use the shared internal plan-change workflow for Autoplan, Autodoc, plan approval, and bounded exact-text replanning. Do not copy that sequence into Autoimplement, Monitor, or another workflow.
 - Set explicit step and command timeouts.
 - Bound ordinary loops with `maxSteps` or another clear finish rule.
 - Use a controller instead of a workflow for indefinite resource reconciliation.

package/skills/sanity-check/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: sanity-check
+description: Use when the user asks for a read-only sanity check of a repository contribution, including whether it is necessary, duplicates existing code, adds justified contracts, or has proportionate scope and tests. Starts the built-in sanity-check workflow and returns an evidence-backed keep, simplify, refactor, drop, or needs-evidence verdict.
+compatibility: Requires pi-workflows and the built-in sanity-check workflow.
+---
+
+# Sanity Check
+
+## Start the workflow
+
+Use the built-in `sanity-check` workflow when it is available. At top level, list workflows, build the complete input, and start `sanity-check` once.
+
+The workflow reviews the repository of the current Pi session. Before starting, confirm that Pi's current working directory is inside the repository that owns the contribution. Do not claim to check a different repository. If the current directory is wrong, start or use a Pi session in the correct repository first.
+
+Build the input as follows:
+
+- `mode`: Use `serial` unless the user explicitly requests parallel review. Serial mode reviews all four areas in one isolated session. Parallel mode runs one isolated review per area with concurrency four. Both modes run a separate verification review.
+- `baseRef`: Use the requested base Git reference. When the base is clear, pass it explicitly, such as `origin/main`. Omit it only when the workflow should derive the base from `origin/HEAD`, the current branch upstream, or `HEAD^`.
+
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "sanity-check",
+  "input": {
+    "mode": "serial",
+    "baseRef": "origin/main"
+  }
+}
+```
+
+The workflow is read-only. It collects committed and working-tree evidence, reads matching pull-request metadata when available, runs isolated reviews, verifies their claims, and reports one verdict. It does not edit files, post comments, or fix findings.
+
+When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract.
+
+Outside Pi, or when the workflow is unavailable:
+
+1. Collect the committed diff from the selected base through `HEAD`, the working-tree diff, untracked files, and matching pull-request context.
+2. Review necessity, duplication, contracts, and scope and tests.
+3. For each area, report pass, concern, or unclear with exact file and symbol evidence.
+4. State the strongest evidence-based case for accepting the contribution.
+5. Verify the findings, remove unsupported claims, and return keep, simplify, refactor, drop, or needs evidence.
+6. Stay read-only unless the user separately asks to implement the required changes.