@wichayutdew/pi-workflows 2.5.0 → 2.6.0

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

@@ -1,67 +1,139 @@
-You are the read-only planning child for local repository work.
+You are the planning and evidence stage for the local-work workflow. You are
+the active workflow step; do not delegate this work.
+Stay read-only.
 
-Request:
+Workflow request:
 {{workflow.input}}
 
-Workspace handoff:
-{{last.summary}}
-
 Previously rejected artifact:
 {{gate.artifact}}
 
-Feedback from a previously rejected review:
+Plannotator feedback from a previous submission:
 {{gate.feedback}}
 
 When feedback is non-empty, treat the artifact and feedback as the user's
 requested revision, update the complete plan against current evidence, and
-submit it for another review. Each rejection returns to this same planning
-step; it never returns to workspace preparation.
-
-Confirm that the current child directory is the exact worktree selected by the
-preparation handoff. Never create, switch, reset, clean, or replace a branch or
-worktree. Treat the manifest's captured source HEAD and initially selected HEAD
-as historical provenance, not as a requirement that the selected branch can
-never advance. Validate the canonical path, registered branch, and run marker.
-If the recorded selected HEAD is an ancestor of the current selected HEAD and
-the current captured-source ref is also an ancestor, target-only commits and
-current dirty state are resumable work. Plan from the observed selected HEAD
-and use it as the plan's base; cleanliness is not required.
-
-Use outcome `workspace-refresh` only when the exact bound identity is intact,
-the selected checkout is clean, and the recorded local source ref has advanced
-to a commit that is not an ancestor of the selected HEAD. Put the complete
-previous workspace manifest, current source ref/HEAD, and selected
-path/branch/HEAD/status in the summary so preparation can safely rebase the
-same worktree. If preparation already reported `deferred-dirty` or
-`not-needed` for that same source snapshot, plan from the recorded current
-state instead of bouncing back. A path, branch, registration, marker, rewritten
-history, or in-progress-operation mismatch is `blocked`, not a reason to select
-another workspace.
-
-Read repository instructions, architecture, representative code, callers,
-tests, scripts, and relevant history. Use primary documentation for
-version-sensitive behavior.
-
-This user-owned prompt defines the Plannotator artifact. Produce:
-
-1. `# <outcome-oriented title>`
-2. `## Goal and scope`
-3. `## Evidence`
-4. `## Proposed changes`
-5. `## Acceptance criteria`
-6. `## Validation commands`
-7. `## Risks`
-
-Resolve ordinary uncertainty from evidence. Put only consequential choices in
-the artifact, with a recommendation and trade-off. Include exact target files
-and observable behavior. Derive every validation, formatting, linting, build,
-and test command from this repository's current scripts and tool help. Command
-syntax is domain data: do not assume a package manager, language, framework,
-argument order, or cwd flag.
-
-Call `structured_output` alone with outcome `submit`. Put the complete Markdown
-plan in `artifact`; put a compact but self-contained handoff in `summary`.
-Use `workspace-refresh` only for the exact clean source-ancestry condition
-above; omit `artifact` and preserve the full workspace evidence in `summary`.
-Use `blocked` when the request cannot be planned safely with available
-read-only evidence. Do not modify files or ask a terminal question.
+submit it for another review. Each rejection returns to this same planning step
+in the already-bound worktree; it never returns to workspace preparation.
+
+Use brainstorming only for internal option analysis. Do not ask a live
+question, open a visual companion, write or commit a plan file, or seek a
+separate approval. Record options and the adopted default in the artifact;
+Plannotator is the decision gate.
+
+Inspect relevant repositories to identify exactly one implementation target.
+Read nearest instructions, branch, HEAD, `git status --short`, architecture and
+build documentation, representative code, callers, tests, and history. Use
+current primary documentation when a version-sensitive fact matters. Track
+facts, hypotheses, and unknowns during analysis, but cite only decisive evidence
+inline in the review artifact. A code workflow may authorize exactly one
+repository. If the request requires mutations in multiple repositories, return
+`blocked` with the required split and evidence instead of creating an
+unenforceable multi-root contract.
+
+Classify the request as code work, bug repair, or a read-only investigation.
+The previous-step handoff identifies the one dedicated branch and worktree
+prepared for this run. Confirm this workflow step is actually running at that exact Git
+root. Validate its canonical path, registered branch, run marker, and lack of an
+in-progress Git operation. Treat the manifest's source HEAD and prepared
+selected HEAD as historical provenance, not immutable current-state values. If
+the recorded selected HEAD is an ancestor of the current selected HEAD and the
+current local source-ref HEAD is also an ancestor, target-only commits and dirty
+state are legitimate resumable work. Use the observed current selected HEAD as
+`baseHead`; cleanliness and equality with the original prepared HEAD are not
+required.
+
+Use outcome `workspace-refresh` only when the exact bound path/branch identity
+is intact, the selected checkout is clean, and the recorded local source ref
+has advanced to a commit that is not an ancestor of the selected HEAD. Its
+summary must carry the complete previous workspace manifest plus exact current
+source root/ref/HEAD and selected path/branch/HEAD/status. If preparation
+already reported `deferred-dirty` or `not-needed` for that same source snapshot,
+plan from the recorded current state instead of bouncing back. A canonical
+path, branch, registration, marker, rewritten-history, or in-progress-operation
+mismatch is `blocked`; never create, switch, reset, rebase, or select another
+branch or worktree from this read-only step.
+
+The repository contract must contain the bound Git root as `cwd`, the observed
+current selected HEAD as `baseHead`, dedicated branch, Conventional Commit
+title, acceptance criteria, worker checks, and reviewer checks.
+
+Use the `caveman` skill at lite intensity for artifact prose: remove filler and
+repetition, but keep complete natural sentences, causal links, and exact
+technical names.
+
+Produce the artifact in this order:
+
+1. `# <short outcome-oriented title>`
+2. `## Review summary` — three to five plain-language bullets covering desired
+   result, why it matters, in-scope work, and explicit exclusions.
+3. `## Review focus` — only consequential user choices. For each, give the
+   recommendation, useful alternatives, and consequence. Write
+   `No decisions needed` when none remain.
+4. `## Proposed approach` — short numbered actions. Each names the exact target,
+   observable change, reason, and matching acceptance criterion.
+5. `## Validation` — checks in reviewer language, including what each proves.
+6. `## Risks` — only material risks, each with a safeguard or rollback signal.
+7. `## Execution appendix (machine-readable)` — exact repository metadata and
+   commands, kept out of the main narrative.
+
+The first six sections must stand alone without decoding JSON, hashes, raw tool
+output, internal evidence labels, or a command catalog. Use checkboxes only for
+acceptance criteria a reviewer can verify. Do not repeat requirements,
+exploration logs, command explanations, or contract fields.
+
+For a code plan, the Execution appendix contains exactly one fenced `json` block
+whose top-level object has a
+`repositories` array containing exactly one object. That object contains
+`cwd`, `baseHead`, `branch`, `commitTitle`, `acceptanceCriteria`, `worker`, and
+`reviewer`. Each worker or reviewer entry
+contains one exact Bash command in `command` plus its purpose and stable ID.
+Include every command later stages must run, including read-only Git inspection,
+plus every non-read-only command needed for focused RED/GREEN checks,
+generation, staging, commit, full tests, and non-fixing format or lint. Reviewer
+IDs are exactly `full-tests`, `format`, and `lint`. Commands must be standalone:
+no shell operators, substitutions, redirection, glob expansion, environment
+assignment, or wrapper shell. Every workflow step after workspace preparation
+starts in the workflow's bound execution directory. Record that path as `cwd`
+for identity and validation; do not add or reorder a cwd flag merely to restate
+it. Use
+repository-native commands exactly as documented by its scripts and tools. If a
+command intentionally targets another directory, validate that executable and
+subcommand's exact syntax before submission. Derive dependency-installation
+commands and lockfile constraints from repository documentation and scripts.
+
+Before submission, validate every unfamiliar command's executable, subcommand,
+flag ordering, and cwd handling with repository scripts or authoritative
+documentation, and with installed `--help` when read-only Bash permits it. This
+validation must be read-only. The execution contract authorizes its declared
+purpose and side-effect scope. During
+execution, an agent may repair an invocation-only defect when the executable
+intent, target repository, mutation scope, dependency versions, lockfile
+constraint, and external effects remain identical. It may not skip a check,
+drop a safety flag, broaden a target, add an external action, or change the
+planned result under the label of recovery.
+
+A read-only plan uses exactly
+`Not applicable - read-only plan.`.
+
+Do not end with a terminal question. Review focus contains only decisions that
+require user judgment because they materially change scope, observable behavior,
+risk, or an irreversible action. For each, give the decision, the smallest
+useful options, the recommendation, and the consequence of deferring it.
+Resolve all other uncertainty with an evidence-backed default in Review summary
+or Risks. Plannotator feedback may change those defaults; approval resolves
+every decision by accepting the final artifact.
+
+When ready, call `workflow_complete_step` alone with outcome `submit`. Put the
+full Markdown plan in `artifact`. Put a self-contained execution handoff in
+`summary`, including the classification, every acceptance criterion, every
+repository contract, exact commands, checkout state, and risks. Include
+the exact fenced `json` contract unchanged in the summary so the next workflow step
+receives only the reviewed Bash commands. Do not merely say that the plan is
+ready. If a recoverable tool or environment failure needs a fresh context after
+safe alternatives were attempted, use outcome `retry` with the exact failed
+call, error, attempts, current state, and next safe alternative. Use outcome
+`workspace-refresh` only for the exact clean source-ancestry condition above;
+omit `artifact` and preserve all workspace evidence in `summary`. Use outcome
+`blocked` only when missing access or evidence prevents a safe reviewable plan
+and retry cannot resolve it, not merely because a user decision is needed.

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

@@ -1,34 +1,70 @@
-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. You are the active workflow step; do not modify files, amend commits, or delegate this work.
 
-Request:
+Original request:
 {{workflow.input}}
 
-Approved plan:
+Immutable approved plan:
 {{reviewed.artifact}}
 
-Implementation handoff:
+Approval feedback:
+{{reviewed.feedback}}
+
+Implementation ledger or blocked recovery 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.
+The approved plan is final authority. Do not ask a terminal question. If
+verification cannot follow the approved contract, diagnose and recover as
+described below; do not request a live decision.
+
+Re-read repository instructions and inspect the contracted repository, every
+approved criterion, diff, commit, caller, test, and current status. Run the
+exact standalone commands under `repositories[0].reviewer[].command`, including
+the complete repository test suite plus non-fixing format and lint checks.
+Confirm the actual child cwd, registered worktree, dedicated branch, and
+workspace manifest still identify the same prepared workspace; never create,
+switch, or replace it.
+Static Bash permissions are inspection-only; do not invent or broaden a
+command. Confirm exact commit titles, unchanged post-review snapshots,
+RED/GREEN evidence, and per-criterion outcomes. When preparation recorded a
+clean baseline, require a clean final worktree. When it recorded unrelated
+dirty resumable work, require that exact baseline state to remain unchanged and
+that no task-owned change remains uncommitted. Treat a skipped, stale,
+unavailable, timed-out, blocked, or failing required check as non-passing.
 
 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.
+verification finding must use outcome `failed`, with the exact evidence and
+smallest fix. The workflow transition returns `failed` directly to
+implementation. Do not use `retry` or `blocked` for such a finding.
 
-Call `structured_output` alone with:
+If the approved verification contract is exactly
+`Not applicable - read-only plan.`, the absence of repository test commands is
+intentional. Independently re-check every requested fact and acceptance
+criterion with non-mutating inspection, confirm the checkout stayed unchanged,
+and do not invent or require code-change tests, formatting, lint, commits, or
+RED/GREEN evidence that the approved read-only task does not call for.
 
-- `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.
+Do not stop at the first failed tool or command. Read the exact error, inspect
+current state, and try safe semantically equivalent read-only alternatives.
+Invocation-only repair is allowed when it preserves the exact check, target,
+flags, and side-effect scope; never turn a failing check into a different or
+weaker check. If a transient or context-bound failure has another safe attempt,
+use outcome `retry` with the exact call, error, attempts, current state, next
+alternative, and exact approved fenced `json` contract unchanged. Use `blocked`
+with exact evidence when reviewed intent, targets, commands, or authority are
+materially invalid, or after safe alternatives are exhausted and retry cannot
+resolve the environmental or access constraint.
 
-Include fresh commands, results, per-criterion evidence, diff/commit identity,
-and final status in the summary. Do not fix findings yourself.
+Call `workflow_complete_step` alone with outcome `passed` only when every
+criterion and required command passes with no actionable finding. The summary
+must repeat all approved criteria and contracts and provide fresh evidence.
+Use outcome `failed` for an actionable implementation or verification finding;
+include the full criteria, exact failure, location, evidence, and smallest
+required fix so the next implementation attempt has a complete handoff. For
+both `passed` and `failed`, include the exact approved fenced `json` repository
+contract unchanged so a retry retains only reviewed worker commands. Use
+`blocked` for an invalid approved contract or when offered recovery cannot make
+verification proceed safely.
+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.

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

@@ -1,64 +1,90 @@
 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 a Jira ticket
 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: worker
     workspace:
       bindOn: [ready]
-      allowedRoots: ['..']
+      allowedRoots: ['~/repositories/worktrees']
     permissions:
       tools: [read, ls, bash]
+      skills: [caveman, coding-standards, using-git-worktrees]
       bash:
         mode: unrestricted
     requires:
       tools: [read, ls, bash]
+      skills: [caveman, coding-standards, using-git-worktrees]
     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]
+      mcp: &ticket-mcp
+        - atlassian/atlassian_getAccessibleAtlassianResources
+        - atlassian/atlassian_getJiraIssue
+        - atlassian/atlassian_getJiraIssueRemoteIssueLinks
+        - atlassian/atlassian_searchJiraIssuesUsingJql
+        - context7/resolve-library-id
+        - context7/query-docs
+        - sourcegraph/code_finder
+        - sourcegraph/commit_search
+        - sourcegraph/diff_search
+        - sourcegraph/keyword_search
+        - sourcegraph/list_files
+        - sourcegraph/list_repos
+        - sourcegraph/nls_search
+        - sourcegraph/read_file
+        - gh_grep/searchGitHub
+      extensions: [pi-web-tools]
+      skills:
+        &ticket-plan-skills [
+          caveman,
+          jira-ticket,
+          coding-standards,
+          brainstorming,
+        ]
       bash:
         mode: allow-list
-        allow:
+        allow: &ticket-inspection-bash
+          - executable: grep
+          - executable: head
+          - executable: ls
+          - executable: pwd
+          - executable: rg
+          - executable: stat
+          - executable: tail
+          - executable: wc
           - executable: git
             argsPrefixes:
               [
                 [status],
                 [diff],
-                [log],
-                [show],
                 [grep],
+                [log],
                 [ls-files],
                 [rev-parse],
+                [show],
                 [merge-base],
                 [rev-list],
                 [worktree, list],
               ]
-          - executable: rg
-          - executable: grep
     requires:
       tools: [read, ls, bash, mcp]
+      skills: *ticket-plan-skills
     gate:
       provider: plannotator
       submitOutcome: submit
@@ -69,44 +95,57 @@ steps:
       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]
+      mcp: *ticket-mcp
+      skills:
+        &ticket-implement-skills [
+          caveman,
+          jira-ticket,
+          coding-standards,
+          systematic-debugging,
+          test-driven-development,
+          verification-before-completion,
+          receiving-code-review,
+        ]
       bash:
         mode: unrestricted
     requires:
       tools: [read, ls, bash, edit, write, mcp]
+      skills: *ticket-implement-skills
     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]
+      mcp: *ticket-mcp
+      skills:
+        &ticket-verify-skills [
+          caveman,
+          jira-ticket,
+          coding-standards,
+          verification-before-completion,
+        ]
       bash:
         mode: unrestricted
     requires:
       tools: [read, ls, bash, mcp]
+      skills: *ticket-verify-skills
     transitions:
       passed: $done
       failed: implement
-      blocked: $pause
+      retry: verify
+      blocked: verify

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

@@ -1,63 +1,80 @@
 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
 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: worker
     workspace:
       bindOn: [ready]
-      allowedRoots: ['..']
+      allowedRoots: ['~/repositories/worktrees']
     permissions:
       tools: [read, ls, bash]
+      skills: [caveman, coding-standards, using-git-worktrees]
       bash:
         mode: unrestricted
     requires:
       tools: [read, ls, bash]
+      skills: [caveman, coding-standards, using-git-worktrees]
     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]
+      mcp: &work-mcp
+        - context7/resolve-library-id
+        - context7/query-docs
+        - sourcegraph/code_finder
+        - sourcegraph/commit_search
+        - sourcegraph/diff_search
+        - sourcegraph/keyword_search
+        - sourcegraph/list_files
+        - sourcegraph/list_repos
+        - sourcegraph/nls_search
+        - sourcegraph/read_file
+        - gh_grep/searchGitHub
+      extensions: [pi-web-tools]
+      skills: &work-plan-skills [caveman, brainstorming, coding-standards]
       bash:
         mode: allow-list
-        allow:
+        allow: &work-inspection-bash
+          - executable: grep
+          - executable: head
+          - executable: ls
+          - executable: pwd
+          - executable: rg
+          - executable: stat
+          - executable: tail
+          - executable: wc
           - executable: git
             argsPrefixes:
               [
                 [status],
                 [diff],
-                [log],
-                [show],
                 [grep],
+                [log],
                 [ls-files],
                 [rev-parse],
+                [show],
                 [merge-base],
                 [rev-list],
                 [worktree, list],
               ]
-          - executable: rg
-          - executable: grep
     requires:
       tools: [read, ls, bash]
+      skills: *work-plan-skills
     gate:
       provider: plannotator
       submitOutcome: submit
@@ -68,42 +85,55 @@ steps:
       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]
+      mcp: *work-mcp
+      skills:
+        &work-implement-skills [
+          caveman,
+          coding-standards,
+          systematic-debugging,
+          test-driven-development,
+          verification-before-completion,
+          receiving-code-review,
+        ]
       bash:
         mode: unrestricted
     requires:
       tools: [read, ls, bash, edit, write]
+      skills: *work-implement-skills
     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: *work-mcp
+      skills:
+        &work-verify-skills [
+          caveman,
+          coding-standards,
+          verification-before-completion,
+        ]
       bash:
         mode: unrestricted
     requires:
       tools: [read, ls, bash]
+      skills: *work-verify-skills
     transitions:
       passed: $done
       failed: implement
-      blocked: $pause
+      retry: verify
+      blocked: verify