@wichayutdew/pi-workflows 2.5.1 → 2.7.0

package/examples/starter-kit/steps/work/verify.md

@@ -1,34 +1,23 @@
-You independently verify the approved local-work result. Do not edit files,
-amend commits, change worktrees, or mutate external state.
+You are the independent verification stage for local work. Stay read-only in this delegated child; do not modify files, amend commits, or launch subagents.
 
-Request:
+Original request:
 {{workflow.input}}
 
 Approved plan:
 {{reviewed.artifact}}
 
-Implementation handoff:
-{{last.summary}}
-
-Confirm the current directory and branch are still the bound worktree. Inspect
-the full diff, changed callers, tests, repository instructions, commit and
-working-tree status. Check every approved acceptance criterion independently.
-Run the exact repository-native validation commands named in the approved plan;
-derive any necessary invocation-only correction from current scripts or tool
-help without weakening the check. A skipped, stale, unavailable, or failing
-required check is not passing.
+Approval feedback:
+{{reviewed.feedback}}
 
-Any regression, lint failure, formatting failure, or other actionable local
-verification finding is `failed`; the workflow sends that outcome directly back
-to implementation. Do not use `blocked` for a fixable local finding.
-
-Call `structured_output` alone with:
+Implementation ledger:
+{{last.summary}}
 
-- `passed` only when every criterion and required check passes;
-- `failed` for an actionable implementation defect, with the exact location,
-  evidence, and smallest corrective handoff;
-- `blocked` when verification cannot proceed safely or the approved contract is
-  materially stale.
+## Rules & Verification Criteria
 
-Include fresh commands, results, per-criterion evidence, diff/commit identity,
-and final status in the summary. Do not fix findings yourself.
+1. **Independent Verification**: Re-run all standalone commands under `repositories[0].reviewer[]` (`full-tests`, `lint`, `format`).
+2. **Strict Evidence**: Confirm exact commit title, clean status (or original dirty baseline preserved), and explicit criterion proofs. Any failing or skipped check is non-passing.
+3. **Outcomes**:
+   - `passed`: All acceptance criteria and automated checks verified.
+   - `failed`: Actionable failure or regression. Automatically returns to `implement` stage for fix.
+   - `retry`: Recoverable read-only environment failure.
+   - `blocked`: Corrupted workspace or missing review authority.

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

@@ -1,112 +1,108 @@
 version: 1
 id: ticket
 command: ticket
-description: Prepare a dedicated workspace, approve a ticket plan, implement, and verify
+description: 'Prepare a dedicated workspace, plan, implement, and verify an issue-tracker ticket. Example: /ticket PROJ-123 Fix a missing client-id header'
 start: prepare-workspace
-maxStepVisits: 4
+maxStepVisits: 20
 summaryMaxChars: 30000
 steps:
   prepare-workspace:
-    title: Prepare or reuse a dedicated worktree
+    title: Prepare dedicated branch and worktree
     prompt:
       file: steps/shared/prepare-workspace.md
-    subagent:
-      agent: worker
-      context: fresh
-      timeoutMs: 900000
+    agent: workspace-preparer
     workspace:
-      bindOn: [ready]
-      allowedRoots: ['..']
+      bindOn:
+        - ready
+      allowedRoots:
+        - ~/repositories/worktrees
     permissions:
       tools: [read, ls, bash]
+      mcp: []
+      extensions: [/]
+      skills: [using-git-worktrees, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash]
     transitions:
       ready: plan
+      retry: prepare-workspace
       blocked: $pause
-
   plan:
-    title: Read the ticket and propose a plan
+    title: Read Jira evidence and plan
     prompt:
       file: steps/ticket/plan.md
-    subagent:
-      agent: planner
-      context: fresh
-      timeoutMs: 1200000
+    agent: planner
     permissions:
-      tools: [read, ls, bash]
-      mcp: [atlassian]
-      bash:
-        mode: allow-list
-        allow:
-          - executable: git
-            argsPrefixes:
-              [
-                [status],
-                [diff],
-                [log],
-                [show],
-                [grep],
-                [ls-files],
-                [rev-parse],
-                [merge-base],
-                [rev-list],
-                [worktree, list],
-              ]
-          - executable: rg
-          - executable: grep
-    requires:
       tools: [read, ls, bash, mcp]
+      mcp: [atlassian, context7, sourcegraph, glean, gitlab]
+      extensions: [/]
+      skills:
+        [
+          jira-ticket,
+          coding-standards,
+          writing-plans,
+          search-code-sourcegraph,
+          caveman,
+        ]
+      bash:
+        mode: unrestricted
     gate:
       provider: plannotator
       submitOutcome: submit
       approvedOutcome: approved
       rejectedOutcome: changes-requested
       timeoutMs: 30000
+      artifactContract:
+        maxChars: 10000
+        requiredSubstrings:
+          - '## Review summary'
+          - '## Review focus'
+          - '## Proposed approach'
+          - '## Validation'
+          - '## Risks'
+          - '## Execution appendix (machine-readable)'
+          - '## Publication contract'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
     transitions:
       approved: implement
       changes-requested: plan
       workspace-refresh: prepare-workspace
+      retry: plan
       blocked: $pause
-
   implement:
-    title: Implement the approved ticket plan
+    title: Implement the approved Jira plan
     prompt:
       file: steps/ticket/implement.md
-    subagent:
-      agent: worker
-      context: fresh
-      timeoutMs: 7200000
-      artifacts: true
+    agent: worker
     permissions:
-      tools: [read, ls, bash, edit, write]
-      mcp: [atlassian]
+      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, mcp]
     transitions:
       ready: verify
+      retry: implement
       blocked: $pause
-
   verify:
-    title: Independently verify the ticket work
+    title: Independently verify Jira work
     prompt:
       file: steps/ticket/verify.md
-    subagent:
-      agent: reviewer
-      context: fresh
-      timeoutMs: 3600000
+    agent: reviewer
     permissions:
-      tools: [read, ls, bash]
-      mcp: [atlassian]
+      tools: [read, ls, bash, mcp]
+      mcp: [gitlab]
+      extensions: [/]
+      skills:
+        [verification-before-completion, lint-commands, commit-format, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash, mcp]
     transitions:
       passed: $done
       failed: implement
-      blocked: $pause
+      retry: verify
+      blocked: verify

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

@@ -1,109 +1,101 @@
 version: 1
 id: work
 command: work
-description: Prepare a dedicated workspace, approve a plan, implement, and verify local work
+description: 'Prepare a dedicated workspace, plan, implement, and verify local work. Example: /work Add rate limiting to user registration endpoint'
 start: prepare-workspace
-maxStepVisits: 4
+maxStepVisits: 20
 summaryMaxChars: 30000
 steps:
   prepare-workspace:
-    title: Prepare or reuse a dedicated worktree
+    title: Prepare dedicated branch and worktree
     prompt:
       file: steps/shared/prepare-workspace.md
-    subagent:
-      agent: worker
-      context: fresh
-      timeoutMs: 900000
+    agent: workspace-preparer
     workspace:
-      bindOn: [ready]
-      allowedRoots: ['..']
+      bindOn:
+        - ready
+      allowedRoots:
+        - ~/repositories/worktrees
     permissions:
       tools: [read, ls, bash]
+      mcp: []
+      extensions: [/]
+      skills: [using-git-worktrees, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash]
     transitions:
       ready: plan
+      retry: prepare-workspace
       blocked: $pause
-
   plan:
-    title: Explore and plan the requested work
+    title: Explore and plan local work
     prompt:
       file: steps/work/plan.md
-    subagent:
-      agent: planner
-      context: fresh
-      timeoutMs: 1200000
+    agent: planner
     permissions:
-      tools: [read, ls, bash]
+      tools: [read, ls, bash, mcp]
+      mcp: [context7, sourcegraph, glean, gh_grep]
+      extensions: [/]
+      skills:
+        [coding-standards, writing-plans, search-code-sourcegraph, caveman]
       bash:
-        mode: allow-list
-        allow:
-          - executable: git
-            argsPrefixes:
-              [
-                [status],
-                [diff],
-                [log],
-                [show],
-                [grep],
-                [ls-files],
-                [rev-parse],
-                [merge-base],
-                [rev-list],
-                [worktree, list],
-              ]
-          - executable: rg
-          - executable: grep
-    requires:
-      tools: [read, ls, bash]
+        mode: unrestricted
     gate:
       provider: plannotator
       submitOutcome: submit
       approvedOutcome: approved
       rejectedOutcome: changes-requested
       timeoutMs: 30000
+      artifactContract:
+        maxChars: 8000
+        requiredSubstrings:
+          - '## Review summary'
+          - '## Review focus'
+          - '## Proposed approach'
+          - '## Validation'
+          - '## Risks'
+          - '## Execution appendix (machine-readable)'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
     transitions:
       approved: implement
       changes-requested: plan
       workspace-refresh: prepare-workspace
+      retry: plan
       blocked: $pause
-
   implement:
-    title: Implement the approved plan
+    title: Implement the approved local plan
     prompt:
       file: steps/work/implement.md
-    subagent:
-      agent: worker
-      context: fresh
-      timeoutMs: 7200000
-      artifacts: true
+    agent: worker
     permissions:
-      tools: [read, ls, bash, edit, write]
+      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 the result
+    title: Independently verify local work
     prompt:
       file: steps/work/verify.md
-    subagent:
-      agent: reviewer
-      context: fresh
-      timeoutMs: 3600000
+    agent: reviewer
     permissions:
       tools: [read, ls, bash]
+      mcp: []
+      extensions: [/]
+      skills:
+        [verification-before-completion, lint-commands, commit-format, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash]
     transitions:
       passed: $done
       failed: implement
-      blocked: $pause
+      retry: verify
+      blocked: verify

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {
@@ -21,32 +21,29 @@
   "files": [
     "dist",
     "src",
-    "agents",
     "examples",
     "schemas",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [
-      "./src/index.ts"
-    ],
-    "subagents": {
-      "agents": [
-        "./agents"
-      ]
-    }
+      "./src/index.ts",
+      "./src/herdr-workflow-state.ts"
+    ]
   },
   "scripts": {
     "build": "bun build ./src/index.ts --outdir=dist --target=node --format=esm --packages=external",
+    "patch:herdr": "node ./scripts/patch-herdr-agent-state.mjs",
     "format": "bunx --bun prettier . --write",
     "format:check": "bunx --bun prettier . --check",
     "lint": "bun --bun eslint .",
     "lint:fix": "bun --bun eslint . --fix",
     "test": "bun test --no-orphans --reporter=dots",
+    "test:e2e": "bun --config=bunfig.e2e.toml test --no-orphans ./test/e2e/direct-worker-runtime.test.ts --reporter=dots",
     "test:coverage": "bun --config=bunfig.coverage.toml test --no-orphans --reporter=dots && bun run coverage:check",
     "coverage:check": "bun .github/scripts/check-coverage.mjs coverage/full/lcov.info",
-    "test:e2e": "bun --config=bunfig.e2e.toml test --no-orphans test/e2e/workflow-runtime.test.ts --reporter=dots",
     "typecheck": "tsc --noEmit",
     "check": "bun run lint && bun run format:check && bun run typecheck && bun run test:coverage && bun run test:e2e && bun run build"
   },
@@ -56,29 +53,22 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
-    "pi-subagents": ">=0.36.0",
     "typebox": "*"
   },
-  "peerDependenciesMeta": {
-    "pi-subagents": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.81.1",
     "@earendil-works/pi-tui": "^0.81.1",
     "@eslint/js": "^10.0.1",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "@types/node": "^24.0.0",
     "eslint": "^10.7.0",
     "globals": "^17.7.0",
-    "pi-subagents": "0.36.0",
     "prettier": "^3.9.5",
     "typebox": "^1.1.38",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.64.0"
   },
-  "packageManager": "bun@1.3.14",
+  "packageManager": "bun@1.4.0",
   "engines": {
     "node": ">=22.19.0"
   }

package/schemas/workflow.schema.json

@@ -514,6 +514,61 @@
         }
       }
     },
+    "artifactContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "maxChars",
+        "requiredSubstrings",
+        "forbiddenSubstrings",
+        "equalOccurrenceGroups"
+      ],
+      "properties": {
+        "maxChars": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 200000
+        },
+        "requiredSubstrings": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          }
+        },
+        "forbiddenSubstrings": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          }
+        },
+        "equalOccurrenceGroups": {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "array",
+            "minItems": 2,
+            "maxItems": 32,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024
+            }
+          }
+        },
+        "onValidationFailure": {
+          "const": "retry"
+        }
+      }
+    },
     "gate": {
       "oneOf": [
         {
@@ -533,6 +588,9 @@
             },
             "rejectedOutcome": {
               "$ref": "#/$defs/identifier"
+            },
+            "artifactContract": {
+              "$ref": "#/$defs/artifactContract"
             }
           }
         },
@@ -563,6 +621,9 @@
               "minimum": 1000,
               "maximum": 30000,
               "default": 30000
+            },
+            "artifactContract": {
+              "$ref": "#/$defs/artifactContract"
             }
           }
         }
@@ -597,19 +658,6 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["prompt", "transitions"],
-      "allOf": [
-        {
-          "if": {
-            "required": ["workspace"]
-          },
-          "then": {
-            "required": ["subagent"],
-            "not": {
-              "required": ["gate"]
-            }
-          }
-        }
-      ],
       "properties": {
         "title": {
           "type": "string",
@@ -618,8 +666,8 @@
         "prompt": {
           "$ref": "#/$defs/prompt"
         },
-        "subagent": {
-          "$ref": "#/$defs/subagent"
+        "agent": {
+          "$ref": "#/$defs/subagentRuntimeName"
         },
         "permissions": {
           "$ref": "#/$defs/permissions"

package/scripts/patch-herdr-agent-state.mjs

@@ -0,0 +1,36 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const target =
+  process.env.HERDR_PI_EXTENSION_PATH ??
+  join(homedir(), '.pi', 'agent', 'extensions', 'herdr-agent-state.ts');
+const source = await readFile(target, 'utf8');
+if (source.includes('pi-workflows-herdr-lifecycle-patch:start')) {
+  console.log(`Herdr workflow patch already present: ${target}`);
+  process.exit(0);
+}
+const state =
+  '  // pi-workflows-herdr-lifecycle-patch:start\n  let workflowActive = false;\n  let workflowMessage: string | undefined;\n  // pi-workflows-herdr-lifecycle-patch:end\n';
+const listener =
+  '  // pi-workflows-herdr-lifecycle-patch:start\n  pi.events.on("pi-workflows:state", (data) => {\n    if (!rootSession || !data || typeof data !== "object") return;\n    const event = data as { state?: string; message?: string };\n    workflowActive = event.state === "working";\n    workflowMessage = event.message;\n    publishState();\n  });\n  // pi-workflows-herdr-lifecycle-patch:end\n\n';
+let patched = source.replace(
+  '  let blockedCount = 0;',
+  `${state}  let blockedCount = 0;`,
+);
+patched = patched.replace(
+  '    if (agentActive) {\n      return { state: "working" as const, message: undefined };',
+  '    if (agentActive || workflowActive) {\n      return { state: "working" as const, message: workflowMessage };',
+);
+patched = patched.replace(
+  '    return { state: "idle" as const, message: undefined };',
+  '    return { state: "idle" as const, message: workflowMessage };',
+);
+patched = patched.replace(
+  '  pi.events.on("herdr:blocked",',
+  `${listener}  pi.events.on("herdr:blocked",`,
+);
+if (patched === source)
+  throw new Error(`Unsupported Herdr integration layout: ${target}`);
+await writeFile(target, patched);
+console.log(`Patched Herdr workflow lifecycle reporting: ${target}`);