@wichayutdew/pi-workflows 3.3.0 → 3.4.0

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

@@ -1,5 +1,5 @@
 ---
-thinking: xhigh
+thinking: high
 ---
 
 You are the independent review role for one workflow step.

package/examples/starter-kit/settings.yaml

@@ -1,4 +1,3 @@
-# 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/work/implement.md

@@ -17,6 +17,7 @@ Latest ledger:
 1. **Workspace Integrity**: Operate strictly in `repositories[0].cwd`. Never switch branches, create workspaces, or touch unrelated files.
 2. **Execution Authority**: Run only commands listed in `worker` array. No unapproved commands or external pushes.
 3. **Resumable State**: If pre-existing dirty files were recorded in preparation, leave them intact; do not commit or stash them.
+4. **No External Writes**: Never push, create or update reviews, or mutate Jira from this stage.
 4. **Outcomes**:
    - `ready`: Implementation complete, RED/GREEN evidence logged, commit created. Pass unchanged `json` contract to reviewer.
    - `retry`: Recoverable transient tool/environment issue.

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

@@ -0,0 +1,5 @@
+You are the read-only intake stage. Normalize `{{workflow.input}}` before any branch or worktree exists.
+
+If exactly one Jira key is present, retrieve it with Atlassian and return `blocked` if it is malformed, inaccessible, ambiguous, or contradictory. Otherwise use the user requirement. Select a safe Conventional Commit type and concise semantic summary; block rather than guess.
+
+Return `ready` with a compact JSON handoff: `mode` (`jira` or `requirement`), `jiraTicket` (observed key or null), `summary`, `branchType`, `acceptanceCriteria`, and evidence. On `{{restart.workspace}}`, preserve the existing run-owned branch identity; block if the new input contradicts its verified Jira key. Never mutate Jira, Git, branches, worktrees, or remotes.

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

@@ -1,51 +1,17 @@
-You are the planning and evidence stage for local work. Stay read-only in this child workspace; do not launch subagents.
-
-Workflow request:
-{{workflow.input}}
-
-Previously rejected artifact:
-{{gate.artifact}}
-
-Plannotator feedback:
-{{gate.feedback}}
-
-## Plan Artifact Structure
-
-Format the artifact in order:
-1. `# <Outcome-oriented title>`
-2. `## Review summary` — 3-5 bullets: result, scope, exclusions.
-3. `## Review focus` — Consequential user choices (or `No decisions needed`).
-4. `## Proposed approach` — Numbered actions with target, change, reason, and criterion.
-5. `## Validation` — Verification checks and expected proofs.
-6. `## Risks` — Material risks with mitigation/rollback signals.
-7. `## Execution appendix (machine-readable)` — Fenced JSON with `repositories` array (`cwd`, `baseHead`, `branch`, `commitTitle`, `acceptanceCriteria`, `worker`, `reviewer`).
-
-```json
-{
-  "repositories": [
-    {
-      "cwd": "<bound absolute path>",
-      "baseHead": "<observed selected HEAD>",
-      "branch": "<dedicated branch>",
-      "commitTitle": "type(scope): subject",
-      "acceptanceCriteria": ["AC 1", "AC 2"],
-      "worker": [
-        {"id": "test-red", "command": "...", "purpose": "prove failing test"},
-        {"id": "test-green", "command": "...", "purpose": "prove passing test"}
-      ],
-      "reviewer": [
-        {"id": "full-tests", "command": "...", "purpose": "run full test suite"},
-        {"id": "lint", "command": "...", "purpose": "run linter"}
-      ]
-    }
-  ]
-}
-```
-
-## Artifact limit
-Keep the submitted artifact concise and at most 8,000 characters. Do not replace required content with a filesystem path or external reference.
-
-## Outcomes
-- `submit`: Plan ready for Plannotator review. Pass the **complete Markdown text content** directly in the `artifact` parameter.
-- `workspace-refresh`: Source ref advanced unexpectedly and workspace is clean.
-- `blocked`: Unsafe multi-repo requirement or unrecoverable workspace state.
+You are the read-only planning stage. Use the normalized intake handoff in `{{last.summary}}`; inspect the source checkout, origin, base HEAD, target branch, and description template without creating a branch or worktree.
+
+Submit exactly:
+# <Outcome title>
+## Goal/Acceptance Criteria
+## Non Goal
+## Implementation Steps and Tests
+List concise add/remove steps and only tests with an assessable benefit.
+## Validation
+List exact independent Bash commands and expected proof.
+## Risks/Decisions Needed
+## Publications Contract/Metadata
+Record observed provider/repository/target, proposed deterministic source branch, semantic title, template evidence, traceability mode, and Jira key or null. Jira mode requires exactly one matching `[KEY]` title key; requirement mode forbids bracketed keys.
+## Execution appendix (machine-readable)
+Include JSON with `repositories` (sourceRoot, baseHead, branch, worker, reviewer), `traceability`, and `publication` (provider, repository, sourceBranch, targetBranch, title, descriptionTemplate, managedDescription).
+
+Propose `<type>/<KEY>` for verified Jira or `<type>/<semantic-kebab-summary>` otherwise. No random suffix, run ID, or future worktree path. `submit` only after all metadata is observed.

package/examples/starter-kit/steps/work/prepare-workspace.md

@@ -0,0 +1,8 @@
+You prepare the approved branch after the plan gate. Do not launch subagents.
+
+Approved plan: {{reviewed.artifact}}
+Restart workspace: {{restart.workspace}}
+
+Create or reuse only the approved `publication.sourceBranch` at approved `repositories[0].baseHead`. The run ID is for ownership/idempotence lookup only and must never be appended to a branch name. Branches are `<type>/<JIRA-KEY>` for verified Jira or `<type>/<semantic-kebab-summary>` otherwise; reject random numbers, timestamps, hashes, and recomputed names.
+
+If `{{restart.workspace}}` is set, rebind that exact worktree and existing branch; block if it differs from the approved branch. Preserve user changes and unrelated worktrees. If source HEAD advanced from approved baseHead, return `workspace-refresh` without mutation. Return `ready` with bound workspace path and manifest, `retry` only for transient failures, and `blocked` for unsafe state.

package/examples/starter-kit/steps/work//363/260/215/224 publish-remote.md"

@@ -0,0 +1,16 @@
+You publish verified work only. Original request: {{workflow.input}}
+Approved plan: {{reviewed.artifact}}
+
+Derive provider, repository, and target branch from observed `origin`; block unsupported or ambiguous hosts. Validate the approved Conventional Commit title before remote action. Use traceability mode/jiraTicket from the artifact, never workflow command identity. Push only with non-force `git push --set-upstream origin <sourceBranch>`.
+
+Use GitHub MCP (`pull_request_read`, `create_pull_request`, `update_pull_request`) or GitLab MCP; use matching `gh pr`/`glab mr` fallback only when required MCP operations are unavailable or fail. Resolve repository-file, gitlab-server-default, or "none" descriptionTemplate with validated sha256/template rules.
+
+## Existing review safety
+Check for one existing open review. Its title is immutable: never update it. Preserve every byte outside one valid workflow-owned region. Valid matching pairs are:
+
+<!-- ai-only-start -->
+<!-- ai-only-end -->
+
+For an existing valid pair, replace only its interior with approved managed implementation/test content; skip update when unchanged. With no markers, append exactly one approved pair and preserve existing body. mixed, duplicated, reversed, or malformed markers are `blocked`; never replace the full body. For a new review, preserve the resolved template/static body and append the approved managed region. Do not approve, merge, or close reviews.
+
+Return `published` only after push and permitted creation/update; otherwise `retry` before mutation or `blocked` with evidence.

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

@@ -1,43 +1,37 @@
 version: 1
 id: work
 command: work
-description: 'Prepare a dedicated workspace, plan, implement, and verify local work. Example: /work Add rate limiting to user registration endpoint'
-start: prepare-workspace
+description: 'Plan, implement, verify, and publish Pull Request'
+start: intake
 maxStepVisits: 20
 summaryMaxChars: 30000
 steps:
-  prepare-workspace:
-    title: Prepare dedicated branch and worktree
+  intake:
+    title: Normalize requirement and optional Jira evidence
     prompt:
-      file: steps/shared/prepare-workspace.md
-    agent: workspace-preparer
-    workspace:
-      bindOn:
-        - ready
-      allowedRoots:
-        - ~/repositories/worktrees
+      file: steps/work/intake.md
+    agent: planner
     permissions:
-      tools: [read, ls, bash]
+      tools: [read, ls, bash, mcp]
       mcp: []
       extensions: [/]
-      skills: [using-git-worktrees, caveman]
+      skills: []
       bash:
         mode: unrestricted
     transitions:
       ready: plan
-      retry: prepare-workspace
+      retry: intake
       blocked: $pause
   plan:
-    title: Explore and plan local work
+    title: Explore and approve local work
     prompt:
       file: steps/work/plan.md
     agent: planner
     permissions:
       tools: [read, ls, bash, mcp]
-      mcp: [context7, sourcegraph, glean, gh_grep]
+      mcp: []
       extensions: [/]
-      skills:
-        [coding-standards, writing-plans, search-code-sourcegraph, caveman]
+      skills: []
       bash:
         mode: unrestricted
     gate:
@@ -47,34 +41,53 @@ steps:
       rejectedOutcome: changes-requested
       timeoutMs: 30000
       artifactContract:
-        maxChars: 8000
+        maxChars: 10000
         requiredSubstrings:
-          - '## Review summary'
-          - '## Review focus'
-          - '## Proposed approach'
+          - '## Goal/Acceptance Criteria'
+          - '## Non Goal'
+          - '## Implementation Steps and Tests'
           - '## Validation'
-          - '## Risks'
+          - '## Risks/Decisions Needed'
+          - '## Publications Contract/Metadata'
           - '## Execution appendix (machine-readable)'
         forbiddenSubstrings:
           - 'The complete gate artifact is the exact Markdown saved at'
         onValidationFailure: retry
     transitions:
-      approved: implement
+      approved: prepare-workspace
       changes-requested: plan
-      workspace-refresh: prepare-workspace
       retry: plan
       blocked: $pause
+  prepare-workspace:
+    title: Prepare approved branch and worktree
+    prompt:
+      file: steps/work/prepare-workspace.md
+    agent: workspace-preparer
+    workspace:
+      bindOn: [ready]
+      allowedRoots: [~/repositories/worktrees]
+    permissions:
+      tools: [read, ls, bash]
+      mcp: []
+      extensions: [/]
+      skills: []
+      bash:
+        mode: unrestricted
+    transitions:
+      ready: implement
+      workspace-refresh: plan
+      retry: prepare-workspace
+      blocked: $pause
   implement:
-    title: Implement the approved local plan
+    title: Implement approved work
     prompt:
       file: steps/work/implement.md
     agent: worker
     permissions:
       tools: [read, ls, bash, edit, write, mcp]
-      mcp: [context7]
+      mcp: []
       extensions: [/]
-      skills:
-        [coding-standards, test-driven-development, lint-commands, caveman]
+      skills: []
       bash:
         mode: unrestricted
     transitions:
@@ -90,12 +103,27 @@ steps:
       tools: [read, ls, bash]
       mcp: []
       extensions: [/]
-      skills:
-        [verification-before-completion, lint-commands, commit-format, caveman]
+      skills: []
       bash:
         mode: unrestricted
     transitions:
-      passed: $done
+      passed: publish
       failed: implement
       retry: verify
       blocked: verify
+  publish:
+    title: Publish verified branch and open review
+    prompt:
+      file: steps/work/publish-remote.md
+    agent: worker
+    permissions:
+      tools: [read, ls, bash, mcp]
+      mcp: []
+      extensions: [/]
+      skills: []
+      bash:
+        mode: unrestricted
+    transitions:
+      published: $done
+      retry: publish
+      blocked: $pause

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {

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

@@ -1,84 +0,0 @@
-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

@@ -1,75 +0,0 @@
-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,142 +0,0 @@
-version: 1
-id: mr-comment
-command: mr-comment
-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: 10
-summaryMaxChars: 30000
-steps:
-  fetch:
-    title: Fetch merge-request or pull-request evidence
-    prompt:
-      file: steps/mr-comment/fetch.md
-    agent: scout
-    permissions:
-      tools: [read, ls, bash, mcp]
-      mcp: [gitlab, context7]
-      extensions: [/]
-      skills: [caveman]
-      bash:
-        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 review-comment fix plan
-    prompt:
-      file: steps/mr-comment/plan.md
-    agent: planner
-    permissions:
-      tools: [read, ls, bash, mcp]
-      mcp: [gitlab, sourcegraph, context7]
-      extensions: [/]
-      skills:
-        [
-          coding-standards,
-          writing-plans,
-          receiving-code-review,
-          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'
-          - '## 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 approved review-comment fixes
-    prompt:
-      file: steps/mr-comment/implement.md
-    agent: worker
-    permissions:
-      tools: [read, ls, bash, edit, write, mcp]
-      mcp: [context7]
-      extensions: [/]
-      skills:
-        [coding-standards, test-driven-development, lint-commands, caveman]
-      bash:
-        mode: unrestricted
-    transitions:
-      ready: verify
-      retry: implement
-      blocked: $pause
-  verify:
-    title: Independently verify review-comment handling
-    prompt:
-      file: steps/mr-comment/verify.md
-    agent: reviewer
-    permissions:
-      tools: [read, ls, bash]
-      mcp: []
-      extensions: [/]
-      skills: [verification-before-completion, lint-commands, caveman]
-      bash:
-        mode: unrestricted
-    transitions:
-      ready: deliver
-      no-actions: $done
-      failed: implement
-      retry: verify
-      blocked: verify
-  deliver:
-    title: Push the verified commit and reply to review comments
-    prompt:
-      file: steps/mr-comment/publish.md
-    agent: worker
-    permissions:
-      tools: [read, ls, bash, mcp]
-      mcp: [gitlab]
-      extensions: [/]
-      skills: [commit-format, caveman]
-      bash:
-        mode: unrestricted
-    transitions:
-      published: $done
-      no-actions: $done
-      retry: deliver
-      superseded: $pause
-      blocked: $pause

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

@@ -1,96 +0,0 @@
-version: 1
-id: mr-review
-command: mr-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: 10
-summaryMaxChars: 50000
-steps:
-  fetch:
-    title: Fetch complete hosted-review evidence
-    prompt:
-      file: steps/mr-review/fetch.md
-    agent: scout
-    permissions:
-      tools: [read, ls, bash, mcp]
-      mcp: [gitlab, context7]
-      extensions: [/]
-      skills: [caveman]
-      bash:
-        mode: unrestricted
-    transitions:
-      fetched: review
-      blocked: $pause
-  review:
-    title: Produce and approve the complete hosted review
-    prompt:
-      file: steps/mr-review/review-for-approval.md
-    agent: reviewer
-    permissions:
-      tools: [read, ls, bash, mcp]
-      mcp: [gitlab, sourcegraph, context7]
-      extensions: [/]
-      skills:
-        [
-          coding-standards,
-          requesting-code-review,
-          search-code-sourcegraph,
-          caveman,
-        ]
-      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 hosted review
-    prompt:
-      file: steps/mr-review/publish-approved.md
-    agent: worker
-    permissions:
-      tools: [read, ls, bash, mcp]
-      mcp: [gitlab]
-      extensions: [/]
-      skills: [caveman]
-      bash:
-        mode: unrestricted
-    transitions:
-      published: verify
-      blocked: $pause
-  verify:
-    title: Verify or return the approved review for publication repair
-    prompt:
-      file: steps/mr-review/verify-published.md
-    agent: reviewer
-    permissions:
-      tools: [read, ls, bash, mcp]
-      mcp: [gitlab]
-      extensions: [/]
-      skills: [verification-before-completion, caveman]
-      bash:
-        mode: unrestricted
-    transitions:
-      verified: $done
-      failed: publish
-      retry: verify
-      blocked: verify