@osolmaz/pi-workflows 0.10.0 → 0.11.0

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

@@ -0,0 +1,59 @@
+{
+  "$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",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "runId",
+    "workflowName",
+    "nodeId",
+    "attemptId",
+    "audience",
+    "title",
+    "body",
+    "choices",
+    "createdAt"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-request.v1" },
+    "decisionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "runId": { "type": "string" },
+    "workflowName": { "type": "string" },
+    "nodeId": { "type": "string" },
+    "attemptId": { "type": "string" },
+    "audience": { "type": "string" },
+    "title": { "type": "string", "minLength": 1 },
+    "body": true,
+    "choices": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string", "minLength": 1 },
+          "input": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "name", "prompt", "minLength", "maxLength"],
+            "properties": {
+              "kind": { "const": "text" },
+              "name": { "type": "string" },
+              "prompt": { "type": "string", "minLength": 1 },
+              "minLength": { "type": "integer", "minimum": 0 },
+              "maxLength": { "type": "integer", "minimum": 1 }
+            }
+          }
+        }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" }
+  }
+}

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

@@ -0,0 +1,69 @@
+{
+  "$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",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "decisionId",
+    "requestDigest",
+    "subjectDigest",
+    "presentationDigest",
+    "runId",
+    "workflowName",
+    "nodeId",
+    "attemptId",
+    "audience",
+    "title",
+    "subject",
+    "presentation",
+    "revision",
+    "choices",
+    "createdAt"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-request.v2" },
+    "decisionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "runId": { "type": "string" },
+    "workflowName": { "type": "string" },
+    "nodeId": { "type": "string" },
+    "attemptId": { "type": "string" },
+    "audience": { "type": "string" },
+    "title": { "type": "string", "minLength": 1 },
+    "subject": true,
+    "presentation": {
+      "$ref": "decision-presentation-v1.schema.json"
+    },
+    "revision": { "type": "integer", "minimum": 1 },
+    "choices": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string", "minLength": 1 },
+          "input": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind", "name", "prompt", "minLength", "maxLength"],
+            "properties": {
+              "kind": { "const": "text" },
+              "name": { "type": "string" },
+              "prompt": { "type": "string", "minLength": 1 },
+              "minLength": { "type": "integer", "minimum": 0 },
+              "maxLength": { "type": "integer", "minimum": 1 }
+            }
+          }
+        }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" }
+  }
+}

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

@@ -0,0 +1,27 @@
+{
+  "$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",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "outcome", "decision"],
+      "properties": {
+        "schema": { "const": "pi-workflows.human-decision-resolution.v1" },
+        "outcome": { "const": "accepted" },
+        "decision": { "$ref": "human-decision-accepted-v1.schema.json" }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "outcome", "cancellation"],
+      "properties": {
+        "schema": { "const": "pi-workflows.human-decision-resolution.v1" },
+        "outcome": { "const": "cancelled" },
+        "cancellation": { "$ref": "human-decision-cancellation-v1.schema.json" }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "$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",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "outcome", "decision"],
+      "properties": {
+        "schema": { "const": "pi-workflows.human-decision-resolution.v2" },
+        "outcome": { "const": "accepted" },
+        "decision": { "$ref": "human-decision-accepted-v2.schema.json" }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "outcome", "cancellation"],
+      "properties": {
+        "schema": { "const": "pi-workflows.human-decision-resolution.v2" },
+        "outcome": { "const": "cancelled" },
+        "cancellation": { "$ref": "human-decision-cancellation-v1.schema.json" }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "$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",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "attemptId",
+    "decisionId",
+    "requestDigest",
+    "channel",
+    "state",
+    "createdAt",
+    "finishedAt"
+  ],
+  "properties": {
+    "schema": { "const": "pi-workflows.human-decision-settlement.v1" },
+    "attemptId": { "type": "string" },
+    "decisionId": { "type": "string" },
+    "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "channel": { "type": "string" },
+    "state": { "enum": ["confirmed", "failed"] },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": "string", "format": "date-time" },
+    "errorCode": { "type": "string" }
+  }
+}

package/skills/autodoc/SKILL.md

@@ -0,0 +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.
+---
+
+# 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.
+
+When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract.
+
+Autodoc records an existing selected solution or clear plan. It does not choose, devise, improve, or revise the solution. If no clear plan exists in the input, conversation, or referenced canonical documents, stop as blocked and use `autoplan` separately.
+
+Outside Pi, or when the workflow is unavailable:
+
+- Prepare or update the canonical plan and documentation without changing the selected solution.
+- Do not take longer than necessary.
+- Preserve the entropy and information in the user's request, including its intent, when writing the plan. Keep the user's concern and any specific wording that carries important meaning near the start of the document, in an introduction that clearly states its intended purpose or goal.
+- Read the relevant code and existing docs before writing. Update the canonical document instead of creating competing sources of truth.
+- Separate user requirements from assumptions and unresolved questions.
+- In plans, state the scope, non-goals, acceptance criteria, and exact verification steps.
+- If there is no plan Markdown document for the task, create one. Do not implement from this skill.
+- Create or update documentation in repositories that the user authorized for documentation changes.
+- For a repository outside the authorized scope, keep the plan in an approved scratch location unless the user explicitly asks to track it in that repository.
+- Create or update the requisite amount of documentation in either existing files or new files in the relevant repos.
+- Avoid unnecessary duplication and keep the relevant existing documentation up to date.
+- When work spans repositories, keep one canonical explanation and link to it rather than copying the same text.
+- After implementation, update the docs to match what actually shipped and record meaningful departures from the plan.
+- Do not spend a long time updating a large set of docs only for this purpose.
+- Use the `plain-writing` skill for all documentation.
+- Read the SimpleDoc specification from the local checkout at `~/repos/SimpleDoc/docs/SIMPLEDOC_SPEC.md`. Do not fetch the specification or related SimpleDoc documentation from online sources.
+- If `~/repos/SimpleDoc` is missing, clone `https://github.com/osolmaz/SimpleDoc.git` there, then read the specification from the local checkout. If the checkout exists, do not switch its branch or modify it only to read the specification.
+- Use the `simpledoc` skill and follow the locally read SimpleDoc convention when creating or updating documentation.
+- Use capitalized filenames for evergreen, long-term documentation and specifications, and dated SimpleDoc filenames for time-bound documents tied to a certain time.
+- Name specification files after the feature itself without `spec` or `specification` in the filename. The document title may include `Spec` or `Specification`.
+- End filenames for non-evergreen implementation plans with `-plan.md`, not `-implementation-plan.md`.
+- Use `cutover` only to describe replacement behavior in prose. Do not use `cutover` or `cutover plan` in filenames, document titles, headings, plan names, issue titles, pull request titles, commit subjects, test names, or other identifiers. Name the target capability directly, adding `plan` only when a plan suffix is useful.
+- Use the `kill-ai-smell` skill for capitalized evergreen documents. AI smell may remain in one-off implementation plans.
+- Test commands and examples when practical.
+- Never place secrets, credentials, private data, or accidental machine-specific paths in tracked documentation.
+- Use `[skip ci]` in the commit message for documentation-only changes.
+- Run `npx -y @simpledoc/simpledoc check` (or `simpledoc check`) locally in each repo where documentation changed.

package/skills/autoimplement/SKILL.md

@@ -0,0 +1,58 @@
+---
+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.
+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.
+
+When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract with the available tools.
+
+Outside Pi, or when the workflow is unavailable, do the following in the order that makes sense. Choose the most efficient order for dependencies, and parallelize independent work.
+
+0. Find the clear existing plan in the user's input, conversation, or referenced canonical documents. Do not devise an initial plan. If no clear plan exists, stop as blocked. If the plan exists but its canonical documentation is missing or stale, use `autodoc` to record it before implementation.
+
+1. Implement the given plan end-to-end.
+   - Implement the most elegant and long-term production-ready solution, but do not take longer than necessary.
+   - When implementation, verification, review, or CI produces evidence that invalidates the plan, use `autoplan` with the previous plan and new evidence, then continue from the revised plan. Keep local implementation bugs in the normal fix loop.
+   - Context compaction might happen during implementation or review. If not enough of the plan was preserved after compaction, re-read the written plan to stay on track with the plan.
+   - Finish to completion. If there is a PR open for the implementation plan, do it in the same PR. If there is no PR already, open PR.
+   - Before finishing, commit and push any new or changed documentation, specification, or plan file in the relevant repo or repos, including the `~/scratch` repo when used, unless the user asked not to.
+
+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.
+   - 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.
+   - 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.
+
+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.
+   - 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.
+   - For documentation-only changes, including SimpleDoc changes, relevant local checks are enough; do not wait for CI/CD after they pass.
+
+6. Once CI/CD is green, or the relevant local checks have passed for a documentation-only change, decide whether merge is authorized.
+   - Merge only when the user explicitly requested it or an applicable standing instruction authorizes it. Otherwise leave the PR ready.
+   - Then finish and give a summary with the PR link.
+   - Include the exact validation commands you ran and their outcomes.
+   - Also comment a final report on the PR.
+
+If this skill is queued many times, treat that as a reminder to make sure the work is fully finished. Once the work is fully finished, you can ignore the repeated instructions. If the work is not finished, continue working.

package/skills/autoimplement/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Autoimplement"
+  short_description: "Finish a plan and ready its PR"
+  default_prompt: "Use $autoimplement to implement the approved plan end-to-end, test it, run `codex review --base <branch>` until no P0/P1 findings remain, clear valid PR feedback, and confirm CI/CD is green without merging."

package/skills/autoplan/SKILL.md

@@ -0,0 +1,25 @@
+---
+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.
+---
+
+# 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.
+
+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. Frame the problem, observable success criteria, scope, constraints, and interfaces under our control.
+2. Devise the most elegant long-term production-ready solution within that scope.
+3. Describe the holy grail separately. Name every dependency outside our authority.
+4. Choose the right option without asking the user to decide between them.
+   - Choose the ideal when it is proportionate, production-ready, in scope, and implementable through interfaces we control.
+   - Otherwise choose the strongest practical in-scope solution with a clear path toward the ideal.
+   - Do not block only because the ideal requires an upstream or external change.
+5. Write a detailed implementation plan. For each step, state what changes, where it changes, and how to verify it.
+6. Stop as blocked only when no truthful in-scope solution can meet the success criteria.
+
+When revising a plan, preserve the previous plan and new evidence. State whether the plan changed and why. Do not implement unless the user also requested implementation.

package/skills/monitor/SKILL.md

@@ -35,7 +35,9 @@ When the conversation gives no clear finish criterion, set `stopWhen` to `Stop o
 
 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 `autodevise`, `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 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.
+
+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.
 
 ## Keep routine work moving
 

package/skills/pi-workflows/SKILL.md

@@ -18,7 +18,7 @@ Use the smallest applicable action:
 - `start` starts a discovered workflow name or workflow file path with structured input.
 - `status` reads the active run, or the named run when `runId` is supplied.
 - `pause`, `resume`, and `cancel` control the current active run.
-- `answer` supplies input to a waiting checkpoint.
+- `answer` supplies input to an ordinary waiting checkpoint. It cannot satisfy a protected `humanDecision()` gate.
 - `update` publishes a non-completing durable update for the active step attempt.
 - `submit` completes the active agent step with its required output.
 
@@ -57,14 +57,14 @@ 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 a checkpoint when progress requires human input.
+- 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.
 - 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.
 - Keep presentation separate from execution. Use `presentationPrompt` only when a final assistant response is needed.
 - Preserve the single active workflow rule in one Pi session.
 
-Read [../../docs/workflows.md](../../docs/workflows.md) before creating or changing a workflow. Read [../../docs/WORKFLOW_COMPOSITION.md](../../docs/WORKFLOW_COMPOSITION.md) for nested workflows. Read [../../docs/DESIGN_PHILOSOPHY.md](../../docs/DESIGN_PHILOSOPHY.md) before adding public primitives. Use the examples under [../../examples/workflows](../../examples/workflows) as starting points.
+Read [../../docs/workflows.md](../../docs/workflows.md) before creating or changing a workflow. Read [../../docs/WORKFLOW_COMPOSITION.md](../../docs/WORKFLOW_COMPOSITION.md) for nested workflows. Read [../../docs/HUMAN_DECISIONS.md](../../docs/HUMAN_DECISIONS.md) before adding a human gate or channel. Read [../../docs/DESIGN_PHILOSOPHY.md](../../docs/DESIGN_PHILOSOPHY.md) before adding public primitives. Use the examples under [../../examples/workflows](../../examples/workflows) as starting points.
 
 ## Verify changes