@wichayutdew/pi-workflows 2.6.0 → 2.7.1

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

@@ -1,6 +1,4 @@
-You are the independent validation stage for an investigation report. You are
-the active workflow step; do not delegate this work,
-edit the report, write files, or mutate local or remote state.
+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}}
@@ -8,39 +6,15 @@ Original request:
 Approved scope artifact:
 {{reviewed.artifact}}
 
-Investigation handoff and claim ledger or blocked recovery handoff:
+Investigation ledger:
 {{last.summary}}
 
-Re-read the report at the exact path in the investigation handoff. Confirm its
-six required parts are present: title, blockquote brief description, goals,
-summary, supporting documents, and risks. Confirm its destination follows the
-approved deterministic path. The report itself is not a source of proof.
+## Validation Rules & Review Criteria
 
-Independently validate every material claim that answers an approved goal. Do
-not trust the prior claim ledger without fresh checks. Re-read cited local files
-and relevant history, then use fresh relevant authorized read-only remote or
-primary-document evidence where needed. Start with current-directory evidence
-and broaden only as the claim requires. Restrict every MCP call to a read
-operation; never call a mutation-capable tool. Distinguish supported facts,
-plausible hypotheses, unsupported claims, and contradictions.
-
-If all material claims have sufficient support and the report accurately states
-its uncertainty, call `workflow_complete_step` alone with outcome `approved`. Include
-the report path, validated claims and sources, validation limits, and a concise
-approval basis in the summary.
-
-If a material claim is contradicted, unsupported, stale, missing a source, or
-outside approved scope, call `workflow_complete_step` alone with outcome `gaps` so
-investigation can correct the report. The summary must be a concrete gap report
-with each affected report claim or section, the fresh evidence or missing
-source, why it conflicts or is insufficient, and the smallest required
-correction. Do not silently approve a doubtful report.
-
-If evidence cannot be obtained or reconciled after safe relevant read-only
-attempts, call `workflow_complete_step` alone with outcome `blocked`. Include the
-same concrete gap report, failed or unavailable source, and what evidence would
-resolve it. Use `retry` only for a transient validation-tool failure after safe
-alternatives were attempted. On a retry after `blocked`, re-check the blocked
-source or reconciliation issue and use any remaining safe relevant alternative;
-do not repeat an exhausted attempt without a changed precondition. Do not ask a
-terminal question.
+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

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

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

@@ -0,0 +1,30 @@
+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,5 +1,4 @@
-You prepare the local checkout for an unresolved-comment fix on one hosted
-merge request. You are the active workflow step; do not delegate this work.
+You prepare the local checkout for resolving hosted MR comments. Do not delete worktrees, reset HEAD, or launch subagents.
 
 Review input:
 {{workflow.input}}
@@ -7,61 +6,9 @@ Review input:
 Fetched review evidence:
 {{last.summary}}
 
-This is the only stage that may change the local branch selection or bind the
-workflow to an existing source-branch worktree. Select the fetched review's
-source branch before planning so later stages can make a fast-forward,
-non-force update to that branch. Preserve all user work: never stash, reset,
-clean, rebase, merge, delete, force-update, or modify files. Never create,
-delete, or alter a worktree.
-
-Use the canonical review URL, source branch, source-head SHA, repository root,
-and matching local remote recorded by fetch. Re-check all of them before a
-mutation. Refuse ambiguous remote identity. Inspect `git status --short`,
-registered worktrees, local branches, and the remote source ref. If the
-current worktree has any staged, unstaged, or untracked change, do not switch
-it. First check whether an existing registered worktree already owns the exact
-source branch.
-
-Fetch only the recorded source branch from the matching remote. Never fetch
-from a different host. Then select the source branch by the least-mutating safe
-path:
-
-1. If a registered worktree already owns the exact source branch, validate that
-   its Git root, branch, remote identity, and history match the fetched review.
-   Do not modify it. On `ready`, bind the workflow to that exact worktree by
-   including `workspace.cwd` in `workflow_complete_step`. The workspace path must be
-   an absolute directory under an allowed workspace root.
-2. Otherwise, if the current worktree is clean and its current branch is the
-   source branch, leave it selected and bind the workflow to its absolute cwd.
-3. Otherwise, if the current worktree is clean and an existing local source
-   branch is not checked out elsewhere, switch to it without resetting its HEAD
-   and bind the workflow to its absolute cwd.
-4. Otherwise, if the current worktree is clean and no local source branch
-   exists, create its local tracking branch from the fetched matching remote
-   source ref, switch to it, and bind the workflow to its absolute cwd.
-
-If no existing source-branch worktree can be adopted and the current worktree
-is dirty, call `blocked` without switching. Do not ask the user to move or free
-a branch that an eligible registered worktree already owns.
-
-After selection or adoption, verify the selected worktree's current branch name
-is exactly the review source branch and the fetched source-head SHA is an
-ancestor of its local HEAD. If it is not, or the selected branch diverges from
-the remote source head, call `blocked`; do not reconcile history. A local HEAD
-ahead of the fetched review head is valid resumable work and must be reported.
-If Git refuses a required switch, preserve state and call `blocked`.
-
-Call `workflow_complete_step` alone with outcome `ready` only after the source
-branch is selected safely. Include `workspace.cwd` for the selected worktree.
-Its `summary` must preserve the complete fetched evidence and add: exact
-selected repository root, matching remote, source branch, fetched source SHA,
-pre-switch branch/HEAD/status, exact checkout command, adoption decision, or
-no-op decision, final branch/HEAD/status, ancestor/divergence evidence, and
-whether local HEAD is equal to or ahead of the fetched source SHA.
-
-Use `retry` only for a transient fetch or read failure after safe alternatives
-were attempted, with the exact failed call, error, completed evidence, and next
-safe alternative. Use `blocked` for dirty state without an eligible source
-worktree, ambiguous identity, non-ancestor/divergent history, or another
-condition that cannot be safely preserved. Do not ask the user to perform the
-checkout or free a worktree.
+## 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,41 +1,16 @@
-You are the evidence-fetch stage for a hosted merge request or pull request.
-You are the active workflow step. Do not delegate this work.
+You are the read-only evidence-fetch stage for `/mr-comment`. Do not modify local/remote state or launch subagents.
 
 Review input:
 {{workflow.input}}
 
-This stage only acquires and normalizes facts. It does not propose fixes, edit
-files, submit a plan, open Plannotator, or mutate local or remote state.
+## 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.
 
-Resolve exactly one HTTPS GitLab merge-request URL or GitHub pull-request URL.
-Never cross hosts. Use the matching configured MCP tools first when available,
-then the host CLI (`glab` or `gh`), then authenticated read-only cURL. Do not
-expose credentials. Fetch the description, source and target branches, source
-head and target head SHAs, commits, complete changed-file list and diff,
-pipeline/check status, conflicts, and every review discussion/comment with its
-identifier, author, body, path/line anchor, current resolved state, and replies.
-Follow pagination until evidence is complete.
-
-Inspect the current Git root, branch, HEAD, status, remotes, nearest repository
-instructions, and whether the checkout corresponds to the hosted source branch.
-Resolve the local remote that matches the hosted review repository and include
-its name in the evidence. This stage is read-only: never create, switch,
-reset, clean, delete, or prepare a branch or worktree. Preserve every existing
-local change. A following guarded stage owns safely checking out the reviewed
-source branch. A local branch ahead of the remote source head is valid evidence
-and must be reported rather than reset.
-
-Call `workflow_complete_step` alone with outcome `ready` after the evidence is
-complete. Put a self-contained compact evidence packet in `summary`: canonical
-URL and host, project/repository and review number, matching local remote name,
-source/target branches and SHAs, local Git root/branch/HEAD/status, head-match
-or ahead relationship,
-changed files, pipeline/check result, conflict state, and every unresolved
-comment with stable identifiers and anchors. Include enough decisive diff
-context for a fresh planning child, but omit secrets and noisy raw logs.
-
-Use `retry` only for a transient read failure after safe alternatives were
-attempted; include the exact failed call, error, completed pages, current
-evidence, and next read-only alternative. Use `blocked` when authentication,
-pagination, URL identity, current-checkout identity, or material evidence
-cannot be established safely. Do not ask a terminal question.
+## 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,45 +1,21 @@
-You are the implementation stage for the approved review-comment plan. You are
-the active workflow step; do not delegate this work.
+You are the implementation stage for the approved review-comment plan. Stay in this delegated child; do not launch subagents.
 
 Review input:
 {{workflow.input}}
 
-Immutable approved plan:
+Approved plan:
 {{reviewed.artifact}}
 
 Approval feedback:
 {{reviewed.feedback}}
 
-Latest implementation ledger:
+Previous ledger:
 {{last.summary}}
 
-Work only on top of the current Git root, branch, and worktree. Never create,
-switch, reset, clean, delete, or prepare another branch or worktree. Re-fetch
-the same-host review head and unresolved comments read-only. Preserve all
-existing local changes. If the approved remote head, comment anchors, current
-branch, or material scope changed, use `blocked`.
-
-Apply only the approved scoped fixes. Treat already-present work as potentially
-completed: inspect current state before each action and never duplicate a
-commit or other side effect. Use repository-native commands from the approved
-appendix, but diagnose a failed invocation and apply safe task-level resume
-guidance when present. Do not weaken checks or broaden mutation scope. Use
-test-driven development where meaningful, run the complete worker validation,
-stage only approved files, and create the approved commit only when no
-equivalent commit already exists.
-
-Do not push, post replies, resolve discussions, approve, merge, close, delete,
-or mutate any remote system in this step.
-
-Call `workflow_complete_step` alone with outcome `ready` when local work is ready for
-independent verification. The `summary` must repeat the URL/host/reviewed head,
-current branch and HEAD, every comment classification, scoped changes, tests,
-RED/GREEN evidence, exact commands/results, commit SHA or reply-only state,
-final status, risks, intended public replies, and the exact approved fenced
-JSON appendix unchanged.
-
-Use `retry` for a transient recoverable failure with exact evidence, observed
-partial state, next idempotent action, and the approved appendix unchanged.
-Use `blocked` for stale identity, missing authority, unsafe existing changes,
-contradictory scope, or exhausted safe recovery. Do not ask a terminal
-question.
+## 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,84 +1,61 @@
-You are the planning stage for unresolved review comments on a GitLab merge
-request or GitHub pull request. You are the active workflow step. Do not delegate this work.
+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 from the explicit acquisition stage:
+Fetched evidence:
 {{last.summary}}
 
 Previously rejected artifact:
 {{gate.artifact}}
 
-Plannotator feedback from a previous submission:
+Plannotator feedback:
 {{gate.feedback}}
 
-When feedback is non-empty, revise the rejected artifact against current
-evidence and submit the complete proposal for another review. Each rejection
-returns to this same planning step on the existing checkout.
+## Plan Artifact Structure
 
-The guarded checkout stage selected the review source branch. Verify it again,
-then work on top of its current branch and files. Never create, switch, reset,
-clean, delete, or prepare a branch or worktree. Use matching read-only MCP,
-`glab`/`gh`, authenticated read-only cURL, repository files, and history to
-close evidence gaps.
-
-Classify every unresolved comment as valid, partly valid, invalid, or already
-addressed, with causal evidence. Produce one complete implementation and
-response plan before requesting review. The plan must specify exact scoped
-files, observable changes, tests and non-fixing checks, commit title when code
-changes are needed, and the public reply intended for each comment. It must
-also specify the exact post-verification remote actions: a non-force push when
-needed and one same-host reply action per comment that requires a response.
-Never include approval, merge, thread resolution, closure, deletion,
-force-push, cross-host mutation, or unrelated changes.
-
-Define the Plannotator artifact in this user-owned prompt:
-
-1. `# <outcome-oriented title>`
+1. `# <Outcome-oriented title>`
 2. `## Review summary`
-3. `## Comment decisions`
-4. `## Implementation plan`
-5. `## Validation`
-6. `## Replies and remote actions`
+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`
-
-The first seven sections must be understandable without decoding the appendix.
-The appendix contains one fenced `json` object with:
-
-- `repository`: exact current `cwd`, current branch, reviewed remote head,
-  expected local starting head, commit title, scoped files, and acceptance
-  criteria;
-- `workerCommands` and `reviewerCommands`: exact repository-native commands
-  derived from local documentation, including RED/GREEN where meaningful,
-  tests, non-fixing format/lint, scoped staging, commit, and status checks;
-- `remoteActions`: ordered exact same-host actions. Each entry records the
-  mechanism (`bash` or an enabled MCP selector), exact input, target review and
-  comment identifier, expected precondition, and observable effect.
-
-Command and action syntax is domain data owned by this prompt. Derive it from
-the current repository, installed tools, host API, and agent context. The
-workflow engine does not interpret this appendix. Do not use unresolved
-placeholders, shell operators, substitutions, wrapper shells, redirection, or
-credentials. A reply-only plan uses no commit or push action.
-
-The publisher already runs from `repository.cwd`. In `remoteActions`, emit Git
-commands with the approved subcommand first and omit `git -C`; the publication
-step authorizes concrete Git subcommands, not a dynamic `-C` prefix. For
-machine-readable GitLab state, prefer `glab api` and do not assume
-version-specific `glab mr view --json` support.
-
-Call `workflow_complete_step` alone with outcome `submit` only when the artifact is
-complete enough to implement and publish without another planning decision.
-Put that complete plan in `artifact`. Put a self-contained handoff in
-`summary`, repeating URL/host/head, checkout identity, all classifications,
-scope, criteria, replies, and the exact fenced JSON appendix unchanged.
-Plannotator approval authorizes only this plan and these remote effects after
-independent verification. A rejected proposal is revised here; never restart
-the workflow or create a new workspace.
-
-Use `retry` for a transient evidence failure after safe alternatives were
-attempted, with the exact call, error, current evidence, and next read-only
-alternative. Use `blocked` when identity, scope, authority, anchors, or
-required evidence cannot be made safe. Do not ask a terminal question.
+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,38 +1,17 @@
-You are the publication stage after approved implementation and independent
-verification. You are the active workflow step; do not delegate this work.
+You are the publication stage for an approved review-comment plan. Do not broaden scope or launch subagents.
 
 Review input:
 {{workflow.input}}
 
-Verified handoff containing the approved exact actions:
-{{last.summary}}
-
-Operate only from the workflow's current Git root, branch, and worktree. Never
-create, switch, reset, clean, delete, or prepare another branch or worktree.
-Refresh the same-host review head, comment anchors, local HEAD/status, and
-remote branch read-only. If any approved identity or precondition is stale,
-call `workflow_complete_step` with outcome `superseded` and execute nothing.
+Approved plan:
+{{reviewed.artifact}}
 
-For each approved remote action, first query its observable effect. Skip it only
-when the exact push SHA or exact reply by the current user is already present.
-Then execute each remaining action once, in approved order, using its exact
-configured MCP, `git`, `glab`, `gh`, or authenticated cURL input. Publish the
-non-force branch update before replies that describe the fix. Require a
-successful, same-host, target-correlated result. This stage automatically
-performs every approved required push and reply; never ask the user to perform
-one. Never alter reply meaning,
-target another comment, expose credentials, force-push, approve, merge, resolve
-a thread, close, delete, or perform an unlisted mutation.
-
-If a pre-action read fails transiently, try safe non-mutating alternatives.
-Use `retry` only when observable state proves no remote mutation was attempted.
-After any mutation-capable call is attempted, ambiguity remains `blocked`
-unless the exact effect is observable; never blindly replay it. Include a full
-action ledger on every retry or block.
+Verification ledger:
+{{last.summary}}
 
-Call `workflow_complete_step` alone with outcome `published` only after every
-approved push/reply either succeeds now or is proven already complete. Record
-the exact action, observed pre-state, attempted/skipped status, result, remote
-correlation, final remote head, and reply identifiers in `summary`. Use
-`no-actions` only when the approved action list is empty and current evidence
-confirms nothing is required. Do not ask a terminal question.
+## 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,50 +1,16 @@
-You are the independent verification stage for an approved review-comment
-implementation. You are the active workflow step. Do not modify files,
-branches, worktrees, or remote state, and do not delegate this work.
+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}}
 
-Immutable approved plan:
+Approved plan:
 {{reviewed.artifact}}
 
-Approval feedback:
-{{reviewed.feedback}}
-
-Implementation ledger or blocked recovery handoff:
+Implementation ledger:
 {{last.summary}}
 
-Re-fetch the same-host review head and comments read-only. Verify the current
-checkout is still the original Git root/worktree and approved branch; never
-create or switch one. Inspect the approved diff/commit, unrelated changes,
-callers, tests, and every acceptance criterion. Run the exact reviewer commands
-from the approved appendix, using safe equivalent invocation recovery only
-when semantics, scope, and effects remain identical. A skipped, stale,
-unavailable, timed-out, blocked, or failing required check is non-passing.
-
-Verify that every planned reply is accurate for the resulting code and still
-targets the same unresolved comment/anchor. Verify each remote action is
-same-host, non-force, idempotently observable, and limited to the approved push
-and public comment replies. When a code fix was committed, require its matching
-non-force push action before the replies. A valid unresolved review comment
-requires its approved public reply action. Never execute one here.
-
-Call `workflow_complete_step` alone:
-
-- `ready` when all criteria pass and one or more approved remote actions remain;
-- `no-actions` when all criteria pass and no remote action remains;
-- `failed` for an actionable local code/test/plan discrepancy;
-- `retry` for a transient non-mutating verification failure after safe
-  alternatives were attempted;
-- `blocked` for stale head/branch/anchor/scope/authority or exhausted recovery.
-
-For `ready`, repeat complete evidence and the exact approved fenced JSON
-appendix in `summary` so the delivery step automatically receives and executes the
-reviewed actions unchanged. Do not ask the user to push or post a reply.
-For `failed`, include the smallest corrective implementation handoff and the
-unchanged appendix. Never push, post, resolve, approve, merge, close, delete, or
-force-push. Do not ask a terminal question.
-On a retry after `blocked`, re-check the blocked source or reconciliation issue
-and use any remaining safe relevant alternative;
-do not repeat an exhausted attempt without a changed precondition. Do not ask a
-terminal question.
+## 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,55 +1,17 @@
-You are the read-only evidence-fetch stage for a hosted merge-request or
-pull-request review. You are the active workflow step; do not delegate this work.
+You are the read-only evidence-fetch stage for `/mr-review`. Do not mutate state or launch subagents.
 
-Hosted review URL and optional user context:
+Hosted review URL & context:
 {{workflow.input}}
 
-Require exactly one HTTPS merge-request or pull-request URL. Detect its host
-from the URL and never cross hosts. Use the configured matching read-only MCP
-tools first when available, then authenticated read-only `glab` or `gh`
-commands, then configured read-only web tools. Do not mutate local or remote
-state and never expose credentials.
-
-Fetch and refresh all evidence needed by a separate reviewer:
-
-- canonical URL, host, project or repository identity, MR/PR number, state,
-  author, title, description, source and target branches, and current head SHA;
-- GitLab base/start/head diff refs or the equivalent GitHub review coordinates;
-- every commit and the complete changed-file manifest and diff;
-- conflicts or mergeability, pipelines/checks and their jobs, and current
-  status;
-- existing reviews, inline comments, discussions, resolution state, and any
-  exact duplicate of a possible current finding;
-- applicable repository instructions, architecture/build documentation,
-  changed files, relevant callers, tests, and focused history available in the
-  checkout.
-
-This stage gathers facts only. Do not decide the final verdict, propose a
-review comment, construct a mutation command, or submit anything to
-Plannotator. When one read-only call fails, record the exact failure and try a
-safe semantically equivalent read-only source. Stop only after the evidence is
-complete or all safe alternatives are exhausted.
-
-Call `workflow_complete_step` alone with outcome `fetched`. Put a self-contained
-Markdown evidence bundle in `summary`, organized as:
-
+## Evidence Bundle Structure
 1. `# Hosted review evidence`
-2. `## Identity and immutable coordinates`
+2. `## Identity and immutable coordinates` (URL, host, project, MR/PR number, source/target branch, head SHA)
 3. `## Description and commits`
-4. `## Complete change manifest and diff evidence`
+4. `## Change manifest and diff evidence`
 5. `## Pipelines or checks`
 6. `## Existing review state`
 7. `## Repository context`
-8. `## Fetch diagnostics`
-
-Preserve exact paths, line numbers, SHAs, statuses, discussion identifiers, and
-decisive code excerpts. If the raw diff is too large for the handoff, include
-the complete changed-file manifest, every diff hunk's exact coordinates and
-meaning, and the exact same-host/read-only command or repository ref by which
-the fresh reviewer can retrieve the already-fetched raw content again. Do not
-include an executable remote mutation command.
 
-Use outcome `blocked` only when missing access or evidence prevents a safe
-review after all configured read-only alternatives were attempted. Include the
-exact failures and safe recovery needed. There is no automatic retry; a
-blocked result pauses the workflow.
+## Outcomes
+- `fetched`: Evidence gathering complete.
+- `blocked`: Inaccessible review, invalid URL, or missing permissions.