@wichayutdew/pi-workflows 1.0.1 → 2.0.0

package/examples/mr-comments.workflow.yaml

@@ -22,7 +22,13 @@ steps:
       tools: [read, grep, bash]
       mcp: [gitlab/get_merge_request, gitlab/list_merge_request_discussions]
       bash:
-        mode: read-only
+        mode: allow-list
+        allow:
+          - executable: git
+            argsPrefixes:
+              [[status], [diff], [log], [show], [grep], [ls-files], [rev-parse]]
+          - executable: rg
+            argsPrefix: []
     requires:
       tools: [read, bash, mcp]
     transitions:
@@ -42,23 +48,27 @@ steps:
     permissions:
       tools: [read, grep, bash]
       mcp: [gitlab/get_merge_request, gitlab/list_merge_request_discussions]
-      extensions: [plannotator]
       skills: [superpowers:brainstorming]
       bash:
-        mode: read-only
+        mode: allow-list
+        allow:
+          - executable: git
+            argsPrefixes:
+              [[status], [diff], [log], [show], [grep], [ls-files], [rev-parse]]
+          - executable: rg
+            argsPrefix: []
     requires:
       tools: [read, mcp]
-      extensions: [plannotator]
       skills: [superpowers:brainstorming]
     gate:
       provider: plannotator
       submitOutcome: submit
       approvedOutcome: approved
       rejectedOutcome: changes-requested
-      timeoutMs: 5000
+      timeoutMs: 30000
     transitions:
       approved: implement
-      changes-requested: plan
+      changes-requested: $pause
       blocked: $pause
   implement:
     title: Implement the approved plan
@@ -79,7 +89,6 @@ steps:
             argsPrefixes: [[status], [diff]]
           - executable: npm
             argsPrefix: [test]
-        approvedSources: [verification-worker]
     requires:
       tools: [read, edit, bash]
       skills: [superpowers:test-driven-development]
@@ -107,7 +116,6 @@ steps:
             argsPrefixes: [[status], [diff]]
           - executable: npm
             argsPrefix: [test]
-        approvedSources: [verification-reviewer]
     requires:
       tools: [read, bash]
     transitions:

package/examples/prompts/mr-comments/implement.md

@@ -1,13 +1,17 @@
 Implement the approved plan with a small, coherent diff.
 
+Approved review artifact:
+
+{{reviewed.artifact}}
+
 Use repository conventions and the allowed skill. Add or update focused tests
-where practical. Treat the approved plan as the final contract: do not ask a
-terminal question or block solely because a profile or skill prefers an
-unapproved ceremony or command. Apply TDD with the authorized commands when the
-reviewed contract supports it; otherwise implement and record that constraint.
-Run each exact reviewed worker command with its enclosing
-`repositories[].cwd`, plus the static allow-list. Do not perform remote actions.
+where practical. Treat the approved plan as the final contract. Apply TDD with
+commands permitted by this step's declarative Bash allow-list. Do not perform
+remote actions.
 Complete with `ready` when implementation and focused checks are complete;
-include the exact fenced JSON contract in the summary for verification.
-Complete with `blocked` only if the harness, configuration, repository, or
-approved contract must be repaired first.
+include a compact verification handoff in the summary.
+Complete with `retry` when the approved contract remains valid and another
+bounded attempt can safely continue unfinished work. The `replan` outcome is
+unavailable. When the approved contract is missing, stale, contradictory, or
+requires a material change to its targets or authority,
+complete with `blocked` and preserve the existing worktree for follow-up.

package/examples/prompts/mr-comments/plan.md

@@ -1,18 +1,47 @@
-Create a concrete implementation plan from the inspected feedback.
-
-Include scope, exact files or symbols, risks, and verification. Account for prior review feedback:
+Create a concrete, decision-ready implementation plan from the inspected
+feedback. Account for previous Plannotator feedback:
 
 {{gate.feedback}}
 
-Include one fenced `json` verification contract with a top-level
-`repositories` array. Every repository entry must contain its exact absolute
-`cwd`; this workflow requires one distinct repository directory. Put exact
-standalone implementation commands under `worker[].command` and independent
-commands under `reviewer[].command`. Resolve any TDD setup, test selection, or
-command limitation in this reviewed contract; later steps must not invent
-another prerequisite or ask for clarification.
-
-When the plan is ready, call `structured_output` with a `value` whose outcome
-is `submit` and whose `artifact` is the full Markdown plan. The Plannotator gate
-decides the next transition; its reviewed artifact becomes the next step's
-handoff.
+Write the artifact for a human reviewer first. Use this order:
+
+# <Short outcome-oriented title>
+
+## Review summary
+
+In three to five plain-language bullets, explain the desired result, why it
+matters, what is in scope, and what is deliberately out of scope.
+
+## Review focus
+
+List only choices that materially affect behavior, scope, risk, or an
+irreversible action. For each choice, give the recommendation, useful
+alternatives, and consequence. Say `No decisions needed` when there are none.
+
+## Proposed changes
+
+Use a short numbered list. Name the exact file or symbol, state its observable
+change and reason, and give the corresponding acceptance criterion. Use
+checkboxes only for acceptance criteria, not for scope, evidence, risks, or
+every sentence.
+
+## Validation
+
+Explain the focused and independent checks in reviewer language. State what
+each check proves; keep exact shell metadata out of this narrative.
+
+## Risks
+
+List only material risks, with a concrete safeguard or rollback signal for
+each. Cite decisive evidence inline instead of dumping raw exploration logs or
+labeling every bullet `FACT`, `HYPOTHESIS`, or `UNKNOWN`.
+
+Do not leave `UNKNOWN`, `TBD`, or implementation-time research in the plan. If
+the allowed resources cannot resolve required access, provenance, repository
+state, resource identity, or targets, complete with `blocked` instead of
+submitting an incomplete plan. A user choice may remain only in Review focus
+with evidence and an adopted recommendation.
+
+When ready, call `structured_output` with a `value` whose outcome is `submit`
+and whose `artifact` is the full Markdown plan. This format is defined by this
+workflow prompt; Pi Workflows treats the artifact as opaque.

package/examples/prompts/mr-comments/verify.md

@@ -1,8 +1,9 @@
-Review the implementation against the requested merge-request feedback and approved plan.
+Review the implementation against the requested merge-request feedback and
+approved plan:
 
-Inspect the diff and run each exact reviewed reviewer command with its enclosing
-`repositories[].cwd`, plus the static allow-list. Do not ask a terminal
-question. Complete with `passed` only when evidence supports completion.
-Complete with `failed` to return to implementation and preserve the exact
-fenced JSON contract in the summary, or `blocked` when the workflow or
-environment must be repaired.
+{{reviewed.artifact}}
+
+Inspect the diff and run checks permitted by this step's declarative Bash
+allow-list. Complete with `passed` only when evidence supports completion.
+Complete with `failed` to return to implementation with a compact actionable
+summary, or `blocked` when the workflow or environment must be repaired.

package/examples/settings.yaml

@@ -8,7 +8,13 @@ permissionCeiling:
   extensions: []
   skills: []
   bash:
-    mode: read-only
+    mode: allow-list
+    allow:
+      - executable: git
+        argsPrefixes:
+          [[status], [diff], [log], [show], [grep], [ls-files], [rev-parse]]
+      - executable: rg
+        argsPrefix: []
   subagent:
     agents: [scout, planner, worker, reviewer]
     contexts: [fresh]

package/examples/starter-kit/mr-comment.workflow.yaml

@@ -0,0 +1,149 @@
+version: 1
+id: mr-comment
+command: mr-comment
+description: Fetch review comments, approve fixes, edit the current checkout, verify, push, and reply
+start: fetch
+maxStepVisits: 4
+summaryMaxChars: 50000
+steps:
+  fetch:
+    title: Fetch merge-request or pull-request comments
+    prompt:
+      file: steps/mr-comment/fetch.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 1800000
+    permissions:
+      tools: [read, ls, bash]
+      mcp: [gitlab, github]
+      bash:
+        mode: allow-list
+        allow:
+          - executable: git
+            argsPrefixes:
+              [
+                [status],
+                [diff],
+                [log],
+                [show],
+                [grep],
+                [ls-files],
+                [remote, -v],
+                [remote, get-url],
+                [rev-parse],
+              ]
+          - executable: glab
+            argsPrefixes: [[mr, view], [mr, diff], [api]]
+          - executable: gh
+            argsPrefixes: [[pr, view], [pr, diff], [pr, checks], [api]]
+          - executable: curl
+    requires:
+      tools: [read, ls, bash]
+    transitions:
+      ready: plan
+      blocked: $pause
+
+  plan:
+    title: Propose a complete comment-fix plan
+    prompt:
+      file: steps/mr-comment/plan.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 1800000
+    permissions:
+      tools: [read, ls, bash]
+      mcp: [gitlab, github]
+      bash:
+        mode: allow-list
+        allow:
+          - executable: git
+            argsPrefixes:
+              [[status], [diff], [log], [show], [grep], [ls-files], [rev-parse]]
+          - executable: glab
+            argsPrefixes: [[mr, view], [mr, diff], [api]]
+          - executable: gh
+            argsPrefixes: [[pr, view], [pr, diff], [pr, checks], [api]]
+          - executable: curl
+    requires:
+      tools: [read, ls, bash]
+    gate:
+      provider: plannotator
+      submitOutcome: submit
+      approvedOutcome: approved
+      rejectedOutcome: changes-requested
+      timeoutMs: 30000
+    transitions:
+      approved: implement
+      changes-requested: $pause
+      blocked: $pause
+
+  implement:
+    title: Implement the approved comment fixes
+    prompt:
+      file: steps/mr-comment/implement.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 7200000
+      artifacts: true
+    permissions:
+      tools: [read, ls, bash, edit, write]
+      mcp: [gitlab, github]
+      bash:
+        mode: unrestricted
+    requires:
+      tools: [read, ls, bash, edit, write]
+    transitions:
+      ready: verify
+      blocked: $pause
+
+  verify:
+    title: Independently verify comment handling
+    prompt:
+      file: steps/mr-comment/verify.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 3600000
+    permissions:
+      tools: [read, ls, bash]
+      mcp: [gitlab, github]
+      bash:
+        mode: unrestricted
+    requires:
+      tools: [read, ls, bash]
+    transitions:
+      ready: publish
+      no-actions: $done
+      failed: implement
+      blocked: $pause
+
+  publish:
+    title: Push verified work and reply to comments
+    prompt:
+      file: steps/mr-comment/publish.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 1800000
+    permissions:
+      tools: [read, ls, bash]
+      mcp: [gitlab, github]
+      bash:
+        mode: allow-list
+        allow:
+          - executable: git
+            argsPrefixes: [[status], [rev-parse], [show], [ls-remote], [push]]
+          - executable: glab
+            argsPrefixes: [[mr, view], [api]]
+          - executable: gh
+            argsPrefixes: [[pr, view], [api]]
+          - executable: curl
+    requires:
+      tools: [read, ls, bash]
+    transitions:
+      published: $done
+      no-actions: $done
+      blocked: $pause

package/examples/starter-kit/mr-review.workflow.yaml

@@ -0,0 +1,130 @@
+version: 1
+id: mr-review
+command: mr-review
+description: Fetch, approve, publish, and verify one hosted code review
+start: fetch
+maxStepVisits: 3
+summaryMaxChars: 50000
+steps:
+  fetch:
+    title: Fetch complete hosted-review evidence
+    prompt:
+      file: steps/mr-review/fetch.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 1800000
+    permissions:
+      tools: [read, ls, bash]
+      mcp: [gitlab, github]
+      bash:
+        mode: allow-list
+        allow:
+          - executable: git
+            argsPrefixes:
+              [
+                [status],
+                [diff],
+                [log],
+                [show],
+                [grep],
+                [ls-files],
+                [remote, -v],
+                [remote, get-url],
+                [rev-parse],
+              ]
+          - executable: glab
+            argsPrefixes: [[mr, view], [mr, diff], [api]]
+          - executable: gh
+            argsPrefixes: [[pr, view], [pr, diff], [pr, checks], [api]]
+          - executable: curl
+    requires:
+      tools: [read, ls, bash]
+    transitions:
+      fetched: review
+      blocked: $pause
+
+  review:
+    title: Produce and approve a complete review
+    prompt:
+      file: steps/mr-review/review.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 1800000
+    permissions:
+      tools: [read, ls, bash]
+      mcp: [gitlab, github]
+      bash:
+        mode: allow-list
+        allow:
+          - executable: git
+            argsPrefixes:
+              [[status], [diff], [log], [show], [grep], [ls-files], [rev-parse]]
+          - executable: glab
+            argsPrefixes: [[mr, view], [mr, diff], [api]]
+          - executable: gh
+            argsPrefixes: [[pr, view], [pr, diff], [pr, checks], [api]]
+          - executable: curl
+    requires:
+      tools: [read, ls, bash]
+    gate:
+      provider: plannotator
+      submitOutcome: submit
+      approvedOutcome: approved
+      rejectedOutcome: changes-requested
+      timeoutMs: 30000
+    transitions:
+      approved: publish
+      changes-requested: $pause
+      blocked: $pause
+
+  publish:
+    title: Publish the approved review
+    prompt:
+      file: steps/mr-review/publish.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 900000
+    permissions:
+      tools: [bash]
+      mcp: [gitlab, github]
+      bash:
+        mode: allow-list
+        allow:
+          - executable: glab
+            argsPrefixes: [[mr, view], [api]]
+          - executable: gh
+            argsPrefixes: [[pr, view], [api]]
+          - executable: curl
+    requires:
+      tools: [bash]
+    transitions:
+      published: verify
+      blocked: $pause
+
+  verify:
+    title: Verify the review is observable remotely
+    prompt:
+      file: steps/mr-review/verify.md
+    subagent:
+      agent: pi-workflows.step
+      context: fresh
+      timeoutMs: 900000
+    permissions:
+      tools: [bash]
+      mcp: [gitlab, github]
+      bash:
+        mode: allow-list
+        allow:
+          - executable: glab
+            argsPrefixes: [[mr, view], [api]]
+          - executable: gh
+            argsPrefixes: [[pr, view], [api]]
+          - executable: curl
+    requires:
+      tools: [bash]
+    transitions:
+      verified: $done
+      blocked: $pause

package/examples/starter-kit/steps/mr-comment/fetch.md

@@ -0,0 +1,33 @@
+You are the initial evidence-acquisition child for unresolved GitLab merge
+request or GitHub pull request comments. Do not propose fixes, edit files, or
+mutate remote state.
+
+Review input:
+{{workflow.input}}
+
+Resolve exactly one canonical HTTPS review URL. Fetch through the matching
+configured MCP server first, then the matching host CLI (`glab` or `gh`), then
+authenticated read-only cURL when a required read is unavailable. Stay on the
+same host and never expose credentials.
+
+Collect title and description, source/target branches and SHAs, commits,
+complete diff, checks/pipelines, conflicts, and every discussion/comment with
+stable ID, author, body, replies, current resolution, and path/line anchor.
+Follow pagination to completion.
+
+Inspect the current Git root, registered worktree, branch, HEAD, status,
+remotes, and repository instructions. This current checkout is the only
+workspace the entire workflow may use. Never create, switch, reset, clean,
+delete, or prepare another branch or worktree. Preserve all local changes. A
+local branch ahead of the hosted head is evidence, not a reason to reset it.
+Run Git inspection from the current child directory with the subcommand first
+(`git status`, `git rev-parse`, and so on); the YAML allow-list does not permit
+a dynamic `git -C` prefix. For machine-readable GitLab evidence, prefer
+`glab api` and do not assume the installed `glab mr view` supports `--json`.
+
+Call `structured_output` alone with outcome `ready` and a self-contained
+evidence packet in `summary`: canonical URL/host, review identity, branches and
+SHAs, current Git root/worktree/branch/HEAD/status, head relationship, changed
+files, checks/conflicts, every unresolved comment and anchor, pagination, and
+acquisition mechanisms. Use `blocked` when review identity, authentication,
+pagination, checkout identity, or material evidence cannot be made safe.

package/examples/starter-kit/steps/mr-comment/implement.md

@@ -0,0 +1,38 @@
+You implement the approved hosted-review comment fixes on top of the current
+checkout.
+
+Review input:
+{{workflow.input}}
+
+Approved plan:
+{{reviewed.artifact}}
+
+Approval feedback:
+{{reviewed.feedback}}
+
+Previous attempt handoff:
+{{last.summary}}
+
+Refresh the same-host review head and comments read-only. Confirm the current
+Git root, registered worktree, branch, HEAD, and existing files still match the
+approved contract. This checkout is the only workspace. Never create, switch,
+reset, clean, delete, or prepare another branch or worktree. Preserve unrelated
+local work and inspect already-present changes before each action.
+
+Apply only the approved scoped fixes. Derive command syntax from the repository
+and current tool documentation; the harness does not know the language,
+framework, package manager, argument order, or cwd syntax. Diagnose a failed
+invocation and current state before trying a semantically identical repair.
+Never weaken checks, broaden mutation scope, or duplicate an existing commit.
+
+Run all approved worker validation and commit only when the contract requires
+it. Do not push, reply, resolve, approve, merge, close, delete, or otherwise
+mutate remote state.
+
+Call `structured_output` alone with outcome `ready` when local work is ready for
+independent verification. Repeat review/head/checkout identity, comment
+classifications, changed files, exact commands/results, criteria evidence,
+commit or reply-only state, current status, intended replies, risks, and the
+unchanged Execution contract in `summary`. Use `blocked` for stale identity,
+missing authority, unsafe scope, or exhausted recovery. Do not create a new
+plan or workspace.

package/examples/starter-kit/steps/mr-comment/plan.md

@@ -0,0 +1,62 @@
+You are the planning child for unresolved hosted-review comments.
+
+Review input:
+{{workflow.input}}
+
+Fetched evidence:
+{{last.summary}}
+
+Feedback from a previously rejected review:
+{{gate.feedback}}
+
+Re-verify the same review and the current Git root, registered worktree,
+branch, HEAD, and status. Work on top of this checkout exactly as it exists.
+Never create, switch, reset, clean, delete, or prepare another branch or
+worktree. Use matching read-only MCP/CLI/cURL calls and repository inspection
+to close evidence gaps.
+
+Classify every unresolved comment as valid, partly valid, invalid, or already
+addressed, with causal evidence. Define scoped code changes, exact
+repository-native checks, an optional commit, and the public reply for each
+comment. Include a non-force push only when verified local code must reach the
+host. Never include approval, merge, resolution, closure, deletion,
+force-push, cross-host mutation, or unrelated work.
+
+This user-owned prompt defines the Plannotator artifact:
+
+1. `# <outcome-oriented title>`
+2. `## Review summary`
+3. `## Comment decisions`
+4. `## Implementation plan`
+5. `## Acceptance criteria and validation`
+6. `## Replies and remote actions`
+7. `## Risks`
+8. `## Execution contract`
+
+The Execution contract is one fenced `json` object containing:
+
+- `repository`: exact current root, worktree, branch, starting HEAD, hosted
+  head, scoped files, optional commit title, and acceptance criteria;
+- `workerCommands` and `reviewerCommands`: exact repository-native commands
+  derived from current scripts and documentation;
+- `remoteActions`: ordered non-force push and same-host reply actions, each
+  with an exact configured MCP tool/input or standalone `git`, `glab`, `gh`, or
+  cURL command, stable review/comment identity, precondition, effect, and
+  unique marker.
+
+Command shape is domain data owned by this prompt. Verify executable,
+subcommand, argument ordering, and cwd behavior from repository context or
+current tool help. Do not assume a language, framework, package manager, or
+flag order. All Git actions run from `repository.cwd`: emit `git <subcommand>`
+with the approved subcommand first and never add a dynamic `git -C` prefix,
+because the publisher's YAML allow-list authorizes concrete subcommands. For
+machine-readable GitLab state, prefer `glab api` and do not assume the installed
+`glab mr view` supports `--json`. Use no unresolved placeholders, credentials,
+shell composition, or wrapper shells.
+
+Call `structured_output` alone with outcome `submit` only when the complete
+plan can be implemented and published without another planning decision. Put
+the Markdown plan in `artifact` and a self-contained handoff, including the
+unchanged JSON contract, in `summary`. Use `blocked` when identity, scope,
+authority, anchors, or evidence cannot be made safe. Rejection pauses through
+the YAML transition; never automatically replan or create a new workspace.

package/examples/starter-kit/steps/mr-comment/publish.md

@@ -0,0 +1,36 @@
+You publish the independently verified comment fixes and replies. Operate only
+from the current Git root, branch, and worktree; never create, switch, reset,
+clean, delete, or prepare another one.
+
+Review input:
+{{workflow.input}}
+
+Verified handoff:
+{{last.summary}}
+
+Refresh the same-host review head, comment anchors, local HEAD/status, and
+remote branch through read-only calls. Require every identity and precondition
+in the approved Execution contract to remain current.
+Run Git from the current child directory with the approved subcommand first;
+do not add `git -C`. Use `glab api` for machine-readable GitLab reads instead of
+assuming `glab mr view --json` support.
+
+For each approved remote action, query its observable effect first. Skip only
+an exact already-present non-force push SHA or an exact reply by the current
+user with the approved marker. Execute each remaining action once, in approved
+order, through its exact configured MCP tool/input or standalone `git`, `glab`,
+`gh`, or authenticated cURL command. Push before replies that describe the
+code fix.
+
+Require a successful same-host, target-correlated response. Never change reply
+meaning, target another comment, expose credentials, force-push, approve,
+merge, resolve, close, delete, or perform an unlisted mutation. After any
+mutation-capable call is attempted, ambiguity is `blocked`; never blindly
+replay it.
+
+Call `structured_output` alone with outcome `published` only after every
+approved push/reply succeeds now or is proven already complete. Record each
+pre-state, attempted/skipped action, exact result, remote identifier/URL, final
+remote head, and remaining work in `summary`. Use `no-actions` only when the
+approved list is empty and current evidence confirms nothing is required. Use
+`blocked` with the full ledger on stale or ambiguous state.

package/examples/starter-kit/steps/mr-comment/verify.md

@@ -0,0 +1,35 @@
+You independently verify the approved review-comment implementation. Do not
+edit files, change branches or worktrees, or mutate remote state.
+
+Review input:
+{{workflow.input}}
+
+Approved plan:
+{{reviewed.artifact}}
+
+Implementation handoff:
+{{last.summary}}
+
+Refresh the same-host review and unresolved comments read-only. Confirm the
+current Git root, registered worktree, branch, HEAD, and status still identify
+the original checkout and approved scope. Never create or switch a workspace.
+
+Inspect the diff/commit, affected callers, tests, unrelated changes, and every
+acceptance criterion. Run all exact reviewer commands from the approved
+contract. A skipped, stale, unavailable, or failing required check is not
+passing. Verify every planned reply remains accurate and targets the same
+comment/anchor. Verify every remote action is same-host, non-force,
+idempotently observable, and limited to the approved push and replies. Do not
+execute remote actions here.
+
+Call `structured_output` alone with:
+
+- `ready` when all criteria pass and approved remote actions remain;
+- `no-actions` when all criteria pass and no remote action is needed;
+- `failed` for an actionable local defect, with exact evidence and the smallest
+  corrective handoff;
+- `blocked` for stale head, checkout, anchor, scope, authority, or verification
+  that cannot proceed safely.
+
+For `ready` and `failed`, include complete fresh evidence and the unchanged
+Execution contract in `summary`.