@wichayutdew/pi-workflows 3.2.0 → 3.4.0

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

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

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

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

@@ -1,28 +0,0 @@
-You are the scope-retrieval stage for `/investigate`. Stay read-only in this delegated child; do not launch subagents.
-
-Workflow input:
-{{workflow.input}}
-
-Previously rejected scope:
-{{gate.artifact}}
-
-Plannotator feedback:
-{{gate.feedback}}
-
-## Scope Artifact Structure
-
-1. `# <Investigation title>`
-2. `## Brief description`
-3. `## Goals` (numbered list)
-4. `## Boundaries` (in-scope systems & explicit exclusions)
-5. `## Evidence & sources` (Jira, local files, documents, search tools)
-6. `## Report destination` (`./investigation-findings/<slug>.md`)
-7. `## Open evidence gaps`
-
-## Artifact limit
-Keep the submitted artifact concise and at most 6,000 characters. Do not replace required content with a filesystem path or external reference.
-
-## Outcomes
-- `submit`: Scope ready for Plannotator gate review.
-- `retry`: Transient read-only API failure.
-- `blocked`: Empty input or inaccessible required Jira data.

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

@@ -1,20 +0,0 @@
-You are the independent validation stage for an investigation report. Stay read-only; do not edit the report or launch subagents.
-
-Original request:
-{{workflow.input}}
-
-Approved scope artifact:
-{{reviewed.artifact}}
-
-Investigation ledger:
-{{last.summary}}
-
-## Validation Rules & Review Criteria
-
-1. **Independent Verification**: Do not trust the prior claim ledger; verify citations, line numbers, and sources directly with read-only tools.
-2. **Reader-Clarity Review**: Ensure prose is concise, scannable, and free of filler. Recommend Mermaid diagrams only where complex flows or relationships warrant visual representation.
-3. **Outcomes**:
-   - `approved`: All material claims verified and clear.
-   - `gaps`: Actionable evidence gaps, contradictions, or clarity issues (returns to `investigate`).
-   - `retry`: Recoverable read-only tool failure.
-   - `blocked`: Irreconcilable evidence or missing sources after exhaustive attempts.

package/examples/starter-kit/steps/jira/create.md

@@ -1,25 +0,0 @@
-You are the Jira creation stage for an approved `/jira` plan. Do not launch subagents, write local files, or mutate unapproved Jira records.
-
-Original input:
-{{workflow.input}}
-
-Approved Jira plan:
-{{reviewed.artifact}}
-
-Approval feedback:
-{{reviewed.feedback}}
-
-Previous creation ledger:
-{{last.summary}}
-
-## Guardrails & Output Contract
-
-1. **Idempotence**: Check the creation ledger before every write; skip any issue or link already created and confirmed.
-2. **Immediate Readback**: Always read back created issues to capture exact numeric IDs, keys, and URLs.
-3. **Safety**: Never delete issues, guess custom fields, or retry ambiguous mutations. On any partial failure or timeout, return `blocked` with the confirmed ledger.
-4. **Required Output Format**:
-   - `# Epic ID: <numeric ID>`
-   - `# Epic key: <key>`
-   - `# Epic URL: <URL>`
-   - `## Stories` (numbered list with IDs, keys, URLs, Epic membership, and link proofs)
-   - `## Creation ledger` (full preflight mapping and execution trace)

package/examples/starter-kit/steps/jira/draft.md

@@ -1,18 +0,0 @@
-You are the input-normalization stage for `/jira`. Stay read-only; do not call Atlassian tools or write files.
-
-Workflow input:
-{{workflow.input}}
-
-## Draft Artifact Structure
-
-1. `# Jira draft`
-2. `## Source` (`Markdown path: <path>` or `Quick summary`)
-3. `## Project key` (explicit key or `Missing`)
-4. `## Epic draft` (Name, goal, expected value, touched services)
-5. `## Ordered Story draft` (numbered list with stable draft IDs, service, frontend/backend scope, implementation bullets, risks, dependencies)
-6. `## Unknowns` (missing details needed before creation)
-
-## Outcomes
-- `ready`: Draft parsed and ready for planning.
-- `retry`: Transient file read failure.
-- `blocked`: Unreadable file path or empty input.

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

@@ -1,30 +0,0 @@
-You are the Jira planning and approval stage for `/jira`. Stay read-only; do not create issues or launch subagents.
-
-Original input:
-{{workflow.input}}
-
-Normalized draft:
-{{last.summary}}
-
-Previously rejected plan:
-{{gate.artifact}}
-
-Plannotator feedback:
-{{gate.feedback}}
-
-## Plan Artifact Structure
-
-1. `# Create Jira Epic and Stories`
-2. `## Jira field contract` — verified field IDs, link types, payload shapes, and representative keys.
-3. `## Epic` — Name, quick summary, goal, **Feature diagram (Mermaid)**, expected value, timeline, touched services, references.
-4. `## Ordered Stories` — Numbered stories with `<service> — <Frontend|Backend> — <outcome>`, background, implementation bullets, risks, acceptance criteria, Epic membership, dependencies.
-5. `## Creation sequence` — Epic first, followed by stories in dependency order.
-6. `## Safety limits` — Exact mapped fields only; no guessed IDs or unapproved objects.
-
-## Artifact limit
-Keep the submitted artifact concise and at most 16,000 characters. Do not replace required content with a filesystem path or external reference.
-
-## Outcomes
-- `submit`: Plan ready for Plannotator review.
-- `retry`: Transient read-only Atlassian API failure.
-- `blocked`: Inaccessible project, unverified field mappings, or missing project key.

package/examples/starter-kit/steps/mr-comment/checkout-source.md

@@ -1,14 +0,0 @@
-You prepare the local checkout for resolving hosted MR comments. Do not delete worktrees, reset HEAD, or launch subagents.
-
-Review input:
-{{workflow.input}}
-
-Fetched review evidence:
-{{last.summary}}
-
-## Guardrails
-- **Preservation**: Never stash, reset, clean, or delete files.
-- **Outcomes**:
-  - `ready`: Source branch checked out/bound safely. Include `workspace: {cwd: "<path>"}`.
-  - `retry`: Transient fetch error.
-  - `blocked`: Dirty unrelated checkout, divergent branch history, or missing remote.

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

@@ -1,16 +0,0 @@
-You are the read-only evidence-fetch stage for `/mr-comment`. Do not modify local/remote state or launch subagents.
-
-Review input:
-{{workflow.input}}
-
-## Evidence Packet Structure
-- Canonical URL, host, project/repo, review number.
-- Source/target branches and remote SHAs.
-- Matching local remote name and local Git status.
-- Changed file list and diff context.
-- Unresolved discussion comments with IDs, authors, anchors (path/line), and text.
-
-## Outcomes
-- `ready`: Evidence gathered successfully.
-- `retry`: Transient network/read failure.
-- `blocked`: Authentication failure, invalid URL, or missing permissions.

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

@@ -1,21 +0,0 @@
-You are the implementation stage for the approved review-comment plan. Stay in this delegated child; do not launch subagents.
-
-Review input:
-{{workflow.input}}
-
-Approved plan:
-{{reviewed.artifact}}
-
-Approval feedback:
-{{reviewed.feedback}}
-
-Previous ledger:
-{{last.summary}}
-
-## Rules & Invariants
-- Execute only approved `workerCommands`.
-- For reply-only plans (no code changes needed), verify code without creating commits.
-- Outcomes:
-  - `ready`: Implementation complete and committed. Pass full JSON contract to reviewer.
-  - `retry`: Transient tool failure.
-  - `blocked`: Unapproved command required or unrecoverable error.

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

@@ -1,61 +0,0 @@
-You are the planning stage for resolving hosted MR comments. Stay read-only on the bound checkout; do not launch subagents.
-
-Review input:
-{{workflow.input}}
-
-Fetched evidence:
-{{last.summary}}
-
-Previously rejected artifact:
-{{gate.artifact}}
-
-Plannotator feedback:
-{{gate.feedback}}
-
-## Plan Artifact Structure
-
-1. `# <Outcome-oriented title>`
-2. `## Review summary`
-3. `## Comment decisions` (per-comment classification and evidence)
-4. `## Implementation plan` (scoped files, observable changes)
-5. `## Validation` (tests, lint, format)
-6. `## Replies and remote actions` (exact reply text per comment)
-7. `## Risks`
-8. `## Execution appendix (machine-readable)` (fenced JSON with `repository`, `workerCommands`, `reviewerCommands`, `remoteActions`)
-
-```json
-{
-  "repository": {
-    "cwd": "<bound-path>",
-    "branch": "<source-branch>",
-    "commitTitle": "fix(scope): address review comments",
-    "scopedFiles": ["src/a.ts"]
-  },
-  "workerCommands": [
-    {"id": "test-red", "command": "..."},
-    {"id": "test-green", "command": "..."}
-  ],
-  "reviewerCommands": [
-    {"id": "full-tests", "command": "..."},
-    {"id": "lint", "command": "..."}
-  ],
-  "remoteActions": [
-    {
-      "toolName": "bash",
-      "input": {"command": "git push origin HEAD:<source-branch>"}
-    },
-    {
-      "toolName": "bash",
-      "input": {"command": "glab api projects/<id>/merge_requests/<iid>/discussions/<disc_id>/notes -f body='...'"}
-    }
-  ]
-}
-```
-
-## Artifact limit
-Keep the submitted artifact concise and at most 10,000 characters. Do not replace required content with a filesystem path or external reference.
-
-## Outcomes
-- `submit`: Complete plan ready for Plannotator gate.
-- `retry`: Transient API failure.
-- `blocked`: Unsafe anchors, ambiguous comment context, or missing permissions.

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

@@ -1,17 +0,0 @@
-You are the publication stage for an approved review-comment plan. Do not broaden scope or launch subagents.
-
-Review input:
-{{workflow.input}}
-
-Approved plan:
-{{reviewed.artifact}}
-
-Verification ledger:
-{{last.summary}}
-
-## Guardrails
-- Run only approved `remoteActions` (`git push`, `glab api`, `gh api`).
-- Never force-push, resolve threads, approve, or merge MRs.
-- Outcomes:
-  - `published`: All remote actions executed and confirmed.
-  - `blocked`: Remote failure or ambiguous state.

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

@@ -1,16 +0,0 @@
-You are the independent verification stage for the approved review-comment fixes. Stay read-only for code; do not modify files or launch subagents.
-
-Review input:
-{{workflow.input}}
-
-Approved plan:
-{{reviewed.artifact}}
-
-Implementation ledger:
-{{last.summary}}
-
-## Outcomes
-- `passed`: All acceptance criteria, tests, and linters pass. Hands off approved `remoteActions` to publication stage.
-- `failed`: Local test failure or regression (returns to `implement`).
-- `retry`: Recoverable read-only environment failure.
-- `blocked`: Corrupted workspace or missing authority.

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

@@ -1,17 +0,0 @@
-You are the read-only evidence-fetch stage for `/mr-review`. Do not mutate state or launch subagents.
-
-Hosted review URL & context:
-{{workflow.input}}
-
-## Evidence Bundle Structure
-1. `# Hosted review evidence`
-2. `## Identity and immutable coordinates` (URL, host, project, MR/PR number, source/target branch, head SHA)
-3. `## Description and commits`
-4. `## Change manifest and diff evidence`
-5. `## Pipelines or checks`
-6. `## Existing review state`
-7. `## Repository context`
-
-## Outcomes
-- `fetched`: Evidence gathering complete.
-- `blocked`: Inaccessible review, invalid URL, or missing permissions.

package/examples/starter-kit/steps/mr-review/publish-approved.md

@@ -1,18 +0,0 @@
-You are the publication stage for an approved hosted code review. Do not rewrite approved content or launch subagents.
-
-Original input:
-{{workflow.input}}
-
-Approved review artifact:
-{{reviewed.artifact}}
-
-Approval feedback:
-{{reviewed.feedback}}
-
-Previous step handoff:
-{{last.summary}}
-
-## Guardrails
-- Execute only literal commands approved in `actions`.
-- Never force-push, approve, merge, resolve, or close reviews.
-- Outcome `published` requires all actions either executed or verified already existing. Outcome `blocked` on ambiguity or error.

package/examples/starter-kit/steps/mr-review/review-for-approval.md

@@ -1,53 +0,0 @@
-You are the independent reviewer for a hosted MR/PR. This is the sole review artifact submitted to Plannotator. Do not mutate state or launch subagents.
-
-Original input:
-{{workflow.input}}
-
-Fetched evidence bundle:
-{{last.summary}}
-
-Previously rejected artifact:
-{{gate.artifact}}
-
-Plannotator feedback:
-{{gate.feedback}}
-
-## Review Artifact Structure
-
-1. `# Review: <Short verdict>`
-2. `## Verdict` — URL, host, current head SHA, concise outcome.
-3. `## Findings` — Ordered by severity: path, line, problem, impact, evidence, fix. (Or `No actionable findings.`).
-4. `## Validation` — Refreshed diff, checks, and false-positive checks.
-5. `## Publication contract` — Fenced JSON with `actions` array.
-6. `## Safety boundaries` — Prohibited actions (no force push, no unapproved merges).
-
-```json
-{
-  "actions": [
-    {
-      "toolName": "bash",
-      "input": {
-        "command": "glab api projects/<id>/merge_requests/<iid>/discussions ..."
-      },
-      "effect": {
-        "kind": "inline-comment",
-        "host": "gitlab.com",
-        "reviewUrl": "https://...",
-        "headSha": "<current-sha>",
-        "path": "src/file.ts",
-        "line": 42,
-        "body": "Exact feedback...",
-        "marker": "<unique-marker>"
-      }
-    }
-  ]
-}
-```
-
-## 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`: Review artifact ready for Plannotator gate.
-- `retry`: Transient read-only API failure.
-- `blocked`: Stale review head or inaccessible discussion API.

package/examples/starter-kit/steps/mr-review/verify-published.md

@@ -1,16 +0,0 @@
-You are the read-only verification stage for an approved hosted review. Do not mutate state or execute publication commands.
-
-Original input:
-{{workflow.input}}
-
-Approved review artifact:
-{{reviewed.artifact}}
-
-Publication ledger:
-{{last.summary}}
-
-## Reviewer Invariants & Outcomes
-- `verified`: Every approved inline comment or summary note is observable on the host with its exact marker.
-- `failed`: An actionable missing comment or mismatch is detected; returns to `publish-approved` stage for correction.
-- `retry`: Recoverable read-only API failure.
-- `blocked`: Stale review or corrupted state.