@wichayutdew/pi-workflows 2.5.1 → 2.7.0

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

@@ -0,0 +1,11 @@
+---
+thinking: high
+---
+
+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,10 @@
+---
+thinking: xhigh
+---
+
+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,10 @@
+---
+thinking: medium
+---
+
+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,11 @@
+---
+thinking: high
+---
+
+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,10 @@
+---
+thinking: low
+---
+
+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,84 @@
+version: 1
+id: investigate
+command: investigate
+description: 'Derive, approve, investigate, and independently validate an evidence-backed finding. Example: /investigate PROJ-123 Root cause of elevated 500 error rates in checkout service'
+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]
+      mcp: [atlassian, context7, sourcegraph, glean, grafana]
+      extensions: [/]
+      skills: [jira-ticket, start-triage, search-code-sourcegraph, caveman]
+      bash:
+        mode: unrestricted
+    gate:
+      provider: plannotator
+      submitOutcome: submit
+      approvedOutcome: approved
+      rejectedOutcome: changes-requested
+      timeoutMs: 30000
+      artifactContract:
+        maxChars: 6000
+        requiredSubstrings:
+          - '## Brief description'
+          - '## Goals'
+          - '## Boundaries'
+          - '## Evidence & sources'
+          - '## Report destination'
+          - '## Open evidence gaps'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
+    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, write, mcp]
+      mcp: [atlassian, context7, sourcegraph, glean, grafana, gitlab]
+      extensions: [/]
+      skills:
+        [
+          coding-standards,
+          systematic-debugging,
+          start-triage,
+          grafana-logs,
+          search-code-sourcegraph,
+          caveman,
+        ]
+      bash:
+        mode: unrestricted
+    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]
+      mcp: [atlassian, sourcegraph, glean, gitlab]
+      extensions: [/]
+      skills: [verification-before-completion, caveman]
+      bash:
+        mode: unrestricted
+    transitions:
+      approved: $done
+      gaps: investigate
+      retry: validate
+      blocked: validate

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

@@ -0,0 +1,75 @@
+version: 1
+id: jira
+command: jira
+description: 'Draft, approve, and create a Jira Epic with ordered Stories. Example: /jira ACTB Implement multi-region failover for pricing service'
+start: draft
+maxStepVisits: 12
+summaryMaxChars: 30000
+steps:
+  draft:
+    title: Normalize Epic and Story input
+    prompt:
+      file: steps/jira/draft.md
+    agent: scout
+    permissions:
+      tools: [read, ls, bash]
+      mcp: []
+      extensions: [/]
+      skills: [jira-ticket, caveman]
+      bash:
+        mode: unrestricted
+    transitions:
+      ready: plan
+      retry: draft
+      blocked: $pause
+  plan:
+    title: Validate Jira schema and approve Epic and Story plan
+    prompt:
+      file: steps/jira/plan.md
+    agent: planner
+    permissions:
+      tools: [read, ls, bash, mcp]
+      mcp: [atlassian]
+      extensions: [/]
+      skills: [jira-ticket, caveman]
+      bash:
+        mode: unrestricted
+    gate:
+      provider: plannotator
+      submitOutcome: submit
+      approvedOutcome: approved
+      rejectedOutcome: changes-requested
+      timeoutMs: 30000
+      artifactContract:
+        maxChars: 16000
+        requiredSubstrings:
+          - '# Create Jira Epic and Stories'
+          - '## Jira field contract'
+          - '## Epic'
+          - '## Ordered Stories'
+          - '## Creation sequence'
+          - '## Safety limits'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
+    transitions:
+      approved: create
+      changes-requested: plan
+      retry: plan
+      blocked: $pause
+  create:
+    title: Create approved Jira Epic and Stories
+    prompt:
+      file: steps/jira/create.md
+    agent: worker
+    permissions:
+      tools: [read, ls, bash, mcp]
+      mcp: [atlassian]
+      extensions: [/]
+      skills: [jira-ticket, caveman]
+      bash:
+        mode: unrestricted
+    transitions:
+      ready: $done
+      retry: create
+      blocked: $pause

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

@@ -1,149 +1,142 @@
 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. Example: /mr-comment https://gitlab.com/org/repo/-/merge_requests/123'
 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]
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab, context7]
+      extensions: [/]
+      skills: [caveman]
       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:
+        mode: unrestricted
+    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: []
+      extensions: [/]
+      skills: [using-git-worktrees, caveman]
+      bash:
+        mode: unrestricted
     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]
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab, sourcegraph, context7]
+      extensions: [/]
+      skills:
+        [
+          coding-standards,
+          writing-plans,
+          receiving-code-review,
+          search-code-sourcegraph,
+          caveman,
+        ]
       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]
+        mode: unrestricted
     gate:
       provider: plannotator
       submitOutcome: submit
       approvedOutcome: approved
       rejectedOutcome: changes-requested
       timeoutMs: 30000
+      artifactContract:
+        maxChars: 10000
+        requiredSubstrings:
+          - '## Review summary'
+          - '## Comment decisions'
+          - '## Implementation plan'
+          - '## Validation'
+          - '## Replies and remote actions'
+          - '## Risks'
+          - '## Execution appendix (machine-readable)'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
     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]
+      tools: [read, ls, bash, edit, write, mcp]
+      mcp: [context7]
+      extensions: [/]
+      skills:
+        [coding-standards, test-driven-development, lint-commands, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash, edit, write]
     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: []
+      extensions: [/]
+      skills: [verification-before-completion, lint-commands, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash]
     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]
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab]
+      extensions: [/]
+      skills: [commit-format, caveman]
       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]
+        mode: unrestricted
     transitions:
       published: $done
       no-actions: $done
+      retry: deliver
+      superseded: $pause
       blocked: $pause

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

@@ -1,132 +1,96 @@
 version: 1
 id: mr-review
 command: mr-review
-description: Fetch, approve, publish, and verify one hosted code review
+description: 'Fetch, approve, publish, and verify one hosted code review. Example: /mr-review https://gitlab.com/org/repo/-/merge_requests/123'
 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]
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab, context7]
+      extensions: [/]
+      skills: [caveman]
       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]
+        mode: unrestricted
     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]
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab, sourcegraph, context7]
+      extensions: [/]
+      skills:
+        [
+          coding-standards,
+          requesting-code-review,
+          search-code-sourcegraph,
+          caveman,
+        ]
       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]
+        mode: unrestricted
     gate:
       provider: plannotator
       submitOutcome: submit
       approvedOutcome: approved
       rejectedOutcome: changes-requested
       timeoutMs: 30000
+      artifactContract:
+        maxChars: 8000
+        requiredSubstrings:
+          - '# Review:'
+          - '## Verdict'
+          - '## Findings'
+          - '## Validation'
+          - '## Publication contract'
+          - '## Safety boundaries'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
     transitions:
       approved: publish
       changes-requested: review
+      retry: 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]
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab]
+      extensions: [/]
+      skills: [caveman]
       bash:
-        mode: allow-list
-        allow:
-          - executable: glab
-            argsPrefixes: [[mr, view], [api]]
-          - executable: gh
-            argsPrefixes: [[pr, view], [api]]
-          - executable: curl
-    requires:
-      tools: [bash]
+        mode: unrestricted
     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]
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab]
+      extensions: [/]
+      skills: [verification-before-completion, caveman]
       bash:
-        mode: allow-list
-        allow:
-          - executable: glab
-            argsPrefixes: [[mr, view], [api]]
-          - executable: gh
-            argsPrefixes: [[pr, view], [api]]
-          - executable: curl
-    requires:
-      tools: [bash]
+        mode: unrestricted
     transitions:
       verified: $done
       failed: publish
       retry: verify
-      blocked: $pause
+      blocked: verify

package/examples/starter-kit/settings.yaml

@@ -0,0 +1,4 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/wichayutdew/pi-workflows/main/schemas/settings.schema.json
+version: 1
+allowProjectWorkflows: false
+statusShortcut: ctrl+alt+c

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

@@ -0,0 +1,40 @@
+You are the evidence-collection and report-writing stage for an approved investigation. Do not launch subagents.
+
+Original request:
+{{workflow.input}}
+
+Approved scope artifact:
+{{reviewed.artifact}}
+
+Plannotator feedback:
+{{reviewed.feedback}}
+
+## Report Template (`~/repositories/investigation-findings/<slug>.md`)
+
+```markdown
+# {Investigation Title}
+
+> {Brief summary description}
+
+# Goal of the investigation
+1. {Goal 1}
+2. {Goal 2}
+
+# Investigation summary that satisfy the goal
+{Evidence-backed findings, concise bullets, and Mermaid diagrams for flows}
+
+# Supporting documents
+{Exact file paths with line ranges, permanent links, and code citations}
+
+# Risks
+1. {Material risk 1 with safeguard}
+2. {Open uncertainty or limitation}
+```
+
+## Rules & Boundaries
+1. **Read-Only Inspection**: Gather evidence across code, docs, and search tools. Never edit repo code or mutate external systems.
+2. **Single Output File**: Write/replace only the approved report file under `~/repositories/investigation-findings/`. Never stage or commit.
+3. **Outcomes**:
+   - `ready`: Report written with structured claim ledger.
+   - `retry`: Transient tool or file-write issue.
+   - `blocked`: Inaccessible required evidence or unachievable scope.