@wichayutdew/pi-workflows 2.5.1 → 2.6.0

package/examples/starter-kit/agents/planner.md

@@ -0,0 +1,7 @@
+You are the planning role for one workflow step.
+
+Stay within the step's declared permissions. Establish facts before conclusions,
+separate assumptions from evidence, and inspect existing conventions before
+proposing changes. Produce a small, executable plan that maps requirements to
+verification. Do not implement changes or broaden scope before the workflow's
+approval gate.

package/examples/starter-kit/agents/reviewer.md

@@ -0,0 +1,6 @@
+You are the independent review role for one workflow step.
+
+Remain read-only unless the step explicitly grants a different authority.
+Independently verify each requirement, inspect the relevant diff and execution
+evidence, and report only concrete gaps with a precise location and falsifiable
+reason. Do not implement fixes or approve claims without evidence.

package/examples/starter-kit/agents/scout.md

@@ -0,0 +1,6 @@
+You are the investigation role for one workflow step.
+
+Stay read-only. Gather the smallest set of decisive evidence, distinguish facts
+from hypotheses, and name the next check that would falsify an uncertainty.
+Report relevant conventions, risks, and open questions without proposing
+unverified implementation details.

package/examples/starter-kit/agents/worker.md

@@ -0,0 +1,7 @@
+You are the implementation role for one workflow step.
+
+Treat the approved workflow artifact and declared permissions as the complete
+authority. Make the smallest coherent change, preserve unrelated work, and
+validate observable behavior with the declared focused checks. Surface a
+blocker with decisive evidence instead of inventing scope, credentials, or
+external side effects.

package/examples/starter-kit/agents/workspace-preparer.md

@@ -0,0 +1,6 @@
+You are the workspace preparation role for one workflow step.
+
+Inspect the current repository state before mutation. Create or reuse only the
+workflow-owned workspace described by the step, preserve unrelated changes,
+and return the exact absolute workspace path required by the completion
+contract. Stop with decisive evidence when ownership or safety is ambiguous.

package/examples/starter-kit/investigate.workflow.yaml

@@ -0,0 +1,114 @@
+version: 1
+id: investigate
+command: investigate
+description: Derive, approve, investigate, and independently validate an evidence-backed finding
+start: retrieve
+maxStepVisits: 12
+summaryMaxChars: 30000
+steps:
+  retrieve:
+    title: Retrieve investigation scope and Jira evidence
+    prompt:
+      file: steps/investigate/retrieve.md
+    agent: scout
+    permissions:
+      tools: [read, ls, bash]
+      mcp: &jira-read-mcp
+        - atlassian/atlassian_getAccessibleAtlassianResources
+        - atlassian/atlassian_getJiraIssue
+        - atlassian/atlassian_getJiraIssueRemoteIssueLinks
+        - atlassian/atlassian_searchJiraIssuesUsingJql
+      extensions: [pi-web-tools]
+      skills: &retrieve-skills [caveman, coding-standards, brainstorming]
+      bash:
+        mode: allow-list
+        allow: &inspection-bash
+          - executable: grep
+          - executable: head
+          - executable: ls
+          - executable: pwd
+          - executable: rg
+          - executable: stat
+          - executable: tail
+          - executable: wc
+          - executable: git
+            argsPrefixes:
+              [
+                [status],
+                [diff],
+                [grep],
+                [log],
+                [ls-files],
+                [rev-parse],
+                [show],
+                [merge-base],
+                [rev-list],
+                [worktree, list],
+              ]
+    requires:
+      tools: [read, ls, bash]
+      skills: *retrieve-skills
+    gate:
+      provider: plannotator
+      submitOutcome: submit
+      approvedOutcome: approved
+      rejectedOutcome: changes-requested
+      timeoutMs: 30000
+    transitions:
+      approved: investigate
+      changes-requested: retrieve
+      retry: retrieve
+      blocked: $pause
+  investigate:
+    title: Investigate approved scope and write findings
+    prompt:
+      file: steps/investigate/investigate.md
+    agent: worker
+    permissions:
+      tools: [read, ls, bash, edit, write]
+      mcp: &investigation-mcp
+        - atlassian
+        - gitlab
+        - glean
+        - superset
+        - sourcegraph
+        - context7/resolve-library-id
+        - context7/query-docs
+        - gh_grep/searchGitHub
+      extensions: [pi-web-tools]
+      skills: &investigation-skills [caveman, coding-standards]
+      bash:
+        mode: unrestricted
+    requires:
+      tools: [read, ls, bash, edit, write]
+      skills: *investigation-skills
+    transitions:
+      ready: validate
+      retry: investigate
+      blocked: $pause
+  validate:
+    title: Independently validate investigation findings
+    prompt:
+      file: steps/investigate/validate.md
+    agent: reviewer
+    permissions:
+      tools: [read, ls, bash]
+      mcp: *investigation-mcp
+      extensions: [pi-web-tools]
+      skills:
+        &validation-skills [
+          caveman,
+          coding-standards,
+          systematic-debugging,
+          verification-before-completion,
+        ]
+      bash:
+        mode: unrestricted
+    requires:
+      tools: [read, ls, bash]
+      skills: *validation-skills
+    transitions:
+      approved: $done
+      gaps: investigate
+      retry: validate
+      blocked: validate

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

@@ -1,73 +1,119 @@
 version: 1
 id: mr-comment
 command: mr-comment
-description: Fetch review comments, approve fixes, edit the current checkout, verify, push, and reply
+description: Fetch unresolved MR or PR comments, approve a fix plan, implement, verify, push, and reply
 start: fetch
-maxStepVisits: 4
-summaryMaxChars: 50000
+maxStepVisits: 10
+summaryMaxChars: 30000
 steps:
   fetch:
-    title: Fetch merge-request or pull-request comments
+    title: Fetch merge-request or pull-request evidence
     prompt:
       file: steps/mr-comment/fetch.md
-    subagent:
-      agent: scout
-      context: fresh
-      timeoutMs: 1800000
+    agent: scout
     permissions:
       tools: [read, ls, bash]
-      mcp: [gitlab, github]
+      mcp: &comment-mcp
+        - gitlab/gitlab_get_merge_request
+        - gitlab/gitlab_get_merge_request_commits
+        - gitlab/gitlab_get_merge_request_diffs
+        - gitlab/gitlab_get_merge_request_pipelines
+        - gitlab/gitlab_get_pipeline_jobs
+        - gitlab/gitlab_get_merge_request_conflicts
+        - gitlab/gitlab_search
+        - context7/resolve-library-id
+        - context7/query-docs
+        - sourcegraph/code_finder
+        - sourcegraph/commit_search
+        - sourcegraph/diff_search
+        - sourcegraph/keyword_search
+        - sourcegraph/list_files
+        - sourcegraph/list_repos
+        - sourcegraph/nls_search
+        - sourcegraph/read_file
+        - gh_grep/searchGitHub
+      extensions: [pi-web-tools]
+      skills:
+        &comment-fetch-skills [caveman, receiving-code-review, coding-standards]
       bash:
         mode: allow-list
-        allow:
+        allow: &comment-inspection-bash
+          - executable: grep
+          - executable: head
+          - executable: ls
+          - executable: pwd
+          - executable: rg
+          - executable: stat
+          - executable: tail
+          - executable: wc
           - executable: git
             argsPrefixes:
               [
                 [status],
                 [diff],
-                [log],
-                [show],
                 [grep],
+                [log],
                 [ls-files],
                 [remote, -v],
                 [remote, get-url],
                 [rev-parse],
+                [show],
               ]
           - executable: glab
             argsPrefixes: [[mr, view], [mr, diff], [api]]
           - executable: gh
-            argsPrefixes: [[pr, view], [pr, diff], [pr, checks], [api]]
+            argsPrefixes: [[pr, view], [pr, diff], [api]]
           - executable: curl
     requires:
       tools: [read, ls, bash]
+      skills: *comment-fetch-skills
+    transitions:
+      ready: checkout-source
+      retry: fetch
+      blocked: $pause
+  checkout-source:
+    title: Check out the reviewed source branch
+    prompt:
+      file: steps/mr-comment/checkout-source.md
+    agent: worker
+    workspace:
+      bindOn: [ready]
+      allowedRoots: ['~/repositories/worktrees', '.']
+    permissions:
+      tools: [read, ls, bash]
+      mcp: *comment-mcp
+      skills: [caveman, receiving-code-review, coding-standards]
+      bash:
+        mode: unrestricted
+    requires:
+      tools: [read, ls, bash]
+      skills: [caveman, receiving-code-review, coding-standards]
     transitions:
       ready: plan
+      retry: checkout-source
       blocked: $pause
-
   plan:
-    title: Propose a complete comment-fix plan
+    title: Propose a complete review-comment fix plan
     prompt:
       file: steps/mr-comment/plan.md
-    subagent:
-      agent: planner
-      context: fresh
-      timeoutMs: 1800000
+    agent: planner
     permissions:
       tools: [read, ls, bash]
-      mcp: [gitlab, github]
+      mcp: *comment-mcp
+      extensions: [pi-web-tools]
+      skills:
+        &comment-plan-skills [
+          caveman,
+          receiving-code-review,
+          coding-standards,
+          brainstorming,
+        ]
       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
+        allow: *comment-inspection-bash
     requires:
       tools: [read, ls, bash]
+      skills: *comment-plan-skills
     gate:
       provider: plannotator
       submitOutcome: submit
@@ -77,60 +123,71 @@ steps:
     transitions:
       approved: implement
       changes-requested: plan
+      retry: plan
       blocked: $pause
-
   implement:
-    title: Implement the approved comment fixes
+    title: Implement approved review-comment fixes
     prompt:
       file: steps/mr-comment/implement.md
-    subagent:
-      agent: worker
-      context: fresh
-      timeoutMs: 7200000
-      artifacts: true
+    agent: worker
     permissions:
       tools: [read, ls, bash, edit, write]
-      mcp: [gitlab, github]
+      mcp: *comment-mcp
+      skills:
+        &comment-implement-skills [
+          caveman,
+          receiving-code-review,
+          coding-standards,
+          systematic-debugging,
+          test-driven-development,
+          verification-before-completion,
+        ]
       bash:
         mode: unrestricted
     requires:
       tools: [read, ls, bash, edit, write]
+      skills: *comment-implement-skills
     transitions:
       ready: verify
+      retry: implement
       blocked: $pause
-
   verify:
-    title: Independently verify comment handling
+    title: Independently verify review-comment handling
     prompt:
       file: steps/mr-comment/verify.md
-    subagent:
-      agent: reviewer
-      context: fresh
-      timeoutMs: 3600000
+    agent: reviewer
     permissions:
       tools: [read, ls, bash]
-      mcp: [gitlab, github]
+      mcp: *comment-mcp
+      skills:
+        &comment-verify-skills [
+          caveman,
+          receiving-code-review,
+          coding-standards,
+          caveman-review,
+          systematic-debugging,
+          verification-before-completion,
+        ]
       bash:
         mode: unrestricted
     requires:
       tools: [read, ls, bash]
+      skills: *comment-verify-skills
     transitions:
-      ready: publish
+      ready: deliver
       no-actions: $done
       failed: implement
-      blocked: $pause
-
-  publish:
-    title: Push verified work and reply to comments
+      retry: verify
+      blocked: verify
+  deliver:
+    title: Push the verified commit and reply to review comments
     prompt:
       file: steps/mr-comment/publish.md
-    subagent:
-      agent: worker
-      context: fresh
-      timeoutMs: 1800000
+    agent: worker
     permissions:
       tools: [read, ls, bash]
-      mcp: [gitlab, github]
+      mcp: *comment-mcp
+      skills: [caveman, receiving-code-review]
       bash:
         mode: allow-list
         allow:
@@ -143,7 +200,10 @@ steps:
           - executable: curl
     requires:
       tools: [read, ls, bash]
+      skills: [caveman, receiving-code-review]
     transitions:
       published: $done
       no-actions: $done
+      retry: deliver
+      superseded: $pause
       blocked: $pause

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

@@ -3,71 +3,100 @@ id: mr-review
 command: mr-review
 description: Fetch, approve, publish, and verify one hosted code review
 start: fetch
-maxStepVisits: 3
+maxStepVisits: 10
 summaryMaxChars: 50000
 steps:
   fetch:
     title: Fetch complete hosted-review evidence
     prompt:
       file: steps/mr-review/fetch.md
-    subagent:
-      agent: scout
-      context: fresh
-      timeoutMs: 1800000
+    agent: scout
     permissions:
       tools: [read, ls, bash]
-      mcp: [gitlab, github]
+      mcp: &review-mcp
+        - gitlab/gitlab_get_merge_request
+        - gitlab/gitlab_get_merge_request_commits
+        - gitlab/gitlab_get_merge_request_diffs
+        - gitlab/gitlab_get_merge_request_pipelines
+        - gitlab/gitlab_get_pipeline_jobs
+        - gitlab/gitlab_get_merge_request_conflicts
+        - gitlab/gitlab_search
+        - context7/resolve-library-id
+        - context7/query-docs
+        - sourcegraph/code_finder
+        - sourcegraph/commit_search
+        - sourcegraph/diff_search
+        - sourcegraph/keyword_search
+        - sourcegraph/list_files
+        - sourcegraph/list_repos
+        - sourcegraph/nls_search
+        - sourcegraph/read_file
+        - gh_grep/searchGitHub
+      extensions: [pi-web-tools]
+      skills:
+        &review-fetch-skills [
+          caveman,
+          coding-standards,
+          caveman-review,
+          brainstorming,
+        ]
       bash:
         mode: allow-list
-        allow:
+        allow: &review-inspection-bash
+          - executable: grep
+          - executable: head
+          - executable: ls
+          - executable: pwd
+          - executable: rg
+          - executable: stat
+          - executable: tail
+          - executable: wc
           - executable: git
             argsPrefixes:
               [
                 [status],
                 [diff],
-                [log],
-                [show],
                 [grep],
+                [log],
                 [ls-files],
                 [remote, -v],
                 [remote, get-url],
                 [rev-parse],
+                [show],
               ]
-          - executable: glab
-            argsPrefixes: [[mr, view], [mr, diff], [api]]
           - executable: gh
             argsPrefixes: [[pr, view], [pr, diff], [pr, checks], [api]]
-          - executable: curl
+          - executable: glab
+            argsPrefixes: [[mr, view], [mr, diff], [api]]
     requires:
       tools: [read, ls, bash]
+      skills: *review-fetch-skills
     transitions:
       fetched: review
       blocked: $pause
-
   review:
-    title: Produce and approve a complete review
+    title: Produce and approve the complete hosted review
     prompt:
-      file: steps/mr-review/review.md
-    subagent:
-      agent: reviewer
-      context: fresh
-      timeoutMs: 1800000
+      file: steps/mr-review/review-for-approval.md
+    agent: reviewer
     permissions:
       tools: [read, ls, bash]
-      mcp: [gitlab, github]
+      mcp: *review-mcp
+      extensions: [pi-web-tools]
+      skills:
+        &review-skills [
+          caveman,
+          coding-standards,
+          caveman-review,
+          systematic-debugging,
+          verification-before-completion,
+        ]
       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
+        allow: *review-inspection-bash
     requires:
       tools: [read, ls, bash]
+      skills: *review-skills
     gate:
       provider: plannotator
       submitOutcome: submit
@@ -78,55 +107,47 @@ steps:
       approved: publish
       changes-requested: review
       blocked: $pause
-
   publish:
-    title: Publish the approved review
+    title: Publish the approved hosted review
     prompt:
-      file: steps/mr-review/publish.md
-    subagent:
-      agent: worker
-      context: fresh
-      timeoutMs: 900000
+      file: steps/mr-review/publish-approved.md
+    agent: worker
     permissions:
       tools: [bash]
-      mcp: [gitlab, github]
+      skills:
+        &publish-skills [
+          caveman,
+          caveman-review,
+          verification-before-completion,
+        ]
       bash:
-        mode: allow-list
-        allow:
-          - executable: glab
-            argsPrefixes: [[mr, view], [api]]
-          - executable: gh
-            argsPrefixes: [[pr, view], [api]]
-          - executable: curl
+        mode: unrestricted
     requires:
       tools: [bash]
+      skills: *publish-skills
     transitions:
       published: verify
       blocked: $pause
-
   verify:
-    title: Verify or return the review for publication repair
+    title: Verify or return the approved review for publication repair
     prompt:
-      file: steps/mr-review/verify.md
-    subagent:
-      agent: reviewer
-      context: fresh
-      timeoutMs: 900000
+      file: steps/mr-review/verify-published.md
+    agent: reviewer
     permissions:
       tools: [bash]
-      mcp: [gitlab, github]
+      skills: *publish-skills
       bash:
         mode: allow-list
         allow:
-          - executable: glab
-            argsPrefixes: [[mr, view], [api]]
           - executable: gh
             argsPrefixes: [[pr, view], [api]]
-          - executable: curl
+          - executable: glab
+            argsPrefixes: [[mr, view], [api]]
     requires:
       tools: [bash]
+      skills: *publish-skills
     transitions:
       verified: $done
       failed: publish
       retry: verify
-      blocked: $pause
+      blocked: verify

package/examples/starter-kit/settings.yaml

@@ -0,0 +1,3 @@
+version: 1
+allowProjectWorkflows: false
+statusShortcut: ctrl+alt+w

package/examples/starter-kit/steps/investigate/investigate.md

@@ -0,0 +1,77 @@
+You are the evidence-collection and report-writing stage for an approved
+investigation. You are the active workflow step. Do not delegate this work.
+
+Original request:
+{{workflow.input}}
+
+Approved scope artifact:
+{{reviewed.artifact}}
+
+Plannotator feedback:
+{{reviewed.feedback}}
+
+Investigate only the approved scope. Begin in the current directory: read
+applicable instructions, identify relevant code, tests, configuration, history,
+and documents with read-only inspection. Broaden only when evidence requires it
+to relevant authorized local repositories, internal documents, and primary
+external documentation. Use `rg`, `fd`, and other read-only Bash inspection
+commands where available. Never mutate a repository, issue, merge request,
+remote system, or source document.
+
+Use configured remote sources only when relevant to a goal. Restrict every MCP
+call to a read operation: Atlassian for Jira evidence; GitLab for hosted source
+and review evidence; Glean for indexed documents; Superset for published data
+metadata; Sourcegraph and GitHub search for code; Context7 for version-specific
+library documentation; and web sources for current primary documentation. A
+configured server can expose mutation tools, but never call one. Record an
+unavailable, inaccessible, or irrelevant source as a limitation; never invent
+its findings.
+
+Separate facts, hypotheses, and unknowns while investigating. Material facts
+need an exact local path and line range, a stable remote link, or an identified
+primary document. Hypotheses need confidence and a falsifier. Reconcile
+conflicting evidence before reporting it; when it cannot be reconciled, report
+the conflict as a risk or open uncertainty rather than choosing a conclusion.
+
+Write one Markdown report to the approved deterministic destination:
+`~/repositories/investigation-findings/<jira-id-or-summary-slug>.md`. Use the
+lowercase Jira key when scope has one; otherwise derive the lowercase ASCII
+summary slug by joining words with hyphens. Announce the path before writing.
+Create `~/repositories/investigation-findings` only when absent. You may replace
+only that deterministic report file. Never commit, stage, or otherwise modify
+any repository file.
+
+The report must contain exactly this requested structure, with each section
+substantive or explicitly limited by unavailable evidence:
+
+```md
+# {Investigation title}
+
+> {Brief description}
+
+# Goal of the investigation
+1. {goal 1}
+2. {goal 2}
+
+# Investigation summary that satisfy the goal
+{Evidence-backed summary, bullets, numbered list, or Mermaid diagram.}
+
+# Supporting documents
+{Links, local paths with line ranges, relevant code blocks, and source limits.}
+
+# Risks
+1. {risk 1}
+2. {risk 2}
+```
+
+Do not add claims without support. Do not add report sections beyond this
+structure. Supporting documents must distinguish direct evidence from context.
+Risks must include contradictory, unavailable, stale, security, or scope
+limitations when relevant.
+
+Call `workflow_complete_step` alone with outcome `ready` only after writing the
+report. Its summary must include the exact report path and a claim ledger: each
+material claim, its supporting source, confidence, and unresolved limitation.
+Use `retry` for a transient evidence or report-write failure after safe recovery
+attempts. Use `blocked` when the approved scope cannot be investigated safely or
+the report cannot be written. Do not ask a terminal question.