@wichayutdew/pi-workflows 2.2.0 → 2.4.0

package/README.md

@@ -9,6 +9,23 @@ tools, prompts, approvals, and outcomes in YAML; it provides bounded execution,
 durable checkpoints, isolated subagent work, and a live status view without
 dictating your language, framework, or delivery process.
 
+## See it in action
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/wichayutdew/pi-workflows/main/assets/video.mp4">
+    <img src="https://raw.githubusercontent.com/wichayutdew/pi-workflows/main/assets/demo.gif" alt="Animated terminal demonstration of a Pi workflow" width="960">
+  </a>
+</p>
+
+<p align="center"><em>Animated preview — select it to download the full 73-second MP4.</em></p>
+
+## At a glance
+
+| Summary and status                                                                                                                                     | Workflow details                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <img src="https://raw.githubusercontent.com/wichayutdew/pi-workflows/main/assets/Summary.png" alt="Pi Workflows summary and status view" width="100%"> | <img src="https://raw.githubusercontent.com/wichayutdew/pi-workflows/main/assets/Details.png" alt="Pi Workflows detailed workflow view" width="100%"> |
+| See progress, approvals, and outcome at a glance.                                                                                                      | Inspect each workflow step and its execution details.                                                                                                 |
+
 ## Why Pi Workflows
 
 - Turn multi-step agent work into clear, reviewable workflow definitions.

package/agents/step.md

@@ -22,3 +22,11 @@ pi-subagents' `structured_output`; `workflow_complete_step` belongs to
 main-agent workflow steps. Never call `contact_supervisor`,
 `subagent_supervisor`, or `intercom`. The workflow prompt defines artifact
 content and format, acceptance criteria, and the meaning of every outcome.
+
+For a non-success outcome, treat `summary` as an operator handoff, not a
+diagnostic transcript: lead with a plain-language decision, list each
+independent issue with its decisive evidence and the concrete action/owner, and
+end with the safe next move. Omit policy narration, raw logs, successful-check
+or clean-state notes, and assertions that the child lacks authority; state the
+prerequisite that would unblock it. Mention a passed check only when it directly
+explains the remaining issue.

package/dist/index.js

@@ -7000,6 +7000,25 @@ function buildDelegatedCompletionInstructions() {
     "Stay within the configured permissions and do not broaden mutation targets or external side effects."
   ];
 }
+function buildNonSuccessSummaryInstructions(outcomes) {
+  const nonSuccessOutcomes = outcomes.filter((outcome) => ["blocked", "failed", "retry"].includes(outcome));
+  if (nonSuccessOutcomes.length === 0)
+    return [];
+  return [
+    "## Human-readable non-success results",
+    "",
+    `For ${nonSuccessOutcomes.map((outcome) => `\`${outcome}\``).join(", ")}, write a decision-first summary. It is shown verbatim to the operator and handed to a fresh child. Use this format:`,
+    "",
+    "# <Failed | Blocked | Retry>: <one-sentence plain-language decision>",
+    "1. **<short issue>** — <only the decisive evidence, including an exact command/error, path, or identifier when it enables action>.",
+    "   **Action:** <the specific owner or role> must <the concrete evidence, decision, or change needed>.",
+    "2. Repeat only for other independent issues (at most three total).",
+    "**Next:** <the exact safe next move, such as provide the listed evidence and run `/workflow-resume`>.",
+    "",
+    "Do not include a process narrative, raw logs, repeated policy constraints, successful checks, clean-state notes, or statements that merely say the child lacks authority. Mention a passed check only when it directly explains the remaining issue. Name the missing prerequisite and who can supply it. Keep only details needed to make the decision or complete the next action.",
+    ""
+  ];
+}
 
 // src/prompt/template.ts
 function currentStepHandoff(run) {
@@ -7131,6 +7150,7 @@ function buildStepTask(options) {
     ...contract.workspaceLines,
     "",
     "Put a self-contained compact handoff in `summary`; this is the only step context passed to the next fresh child.",
+    ...buildNonSuccessSummaryInstructions(contract.outcomes),
     ...isDelegated ? buildDelegatedCompletionInstructions() : [],
     "Do not call the completion tool alongside other tool calls."
   ].join(`

package/package.json

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

package/src/prompt/step-sections.ts

@@ -85,3 +85,33 @@ export function buildDelegatedCompletionInstructions(): ReadonlyArray<string> {
     'Stay within the configured permissions and do not broaden mutation targets or external side effects.',
   ];
 }
+
+/**
+ * Builds the shared operator-facing format for non-successful step results.
+ *
+ * The summary is posted verbatim to chat and is the only context available to
+ * a fresh child, so it must remain actionable without becoming a transcript.
+ */
+export function buildNonSuccessSummaryInstructions(
+  outcomes: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+  const nonSuccessOutcomes = outcomes.filter((outcome) =>
+    ['blocked', 'failed', 'retry'].includes(outcome),
+  );
+  if (nonSuccessOutcomes.length === 0) return [];
+
+  return [
+    '## Human-readable non-success results',
+    '',
+    `For ${nonSuccessOutcomes.map((outcome) => `\`${outcome}\``).join(', ')}, write a decision-first summary. It is shown verbatim to the operator and handed to a fresh child. Use this format:`,
+    '',
+    '# <Failed | Blocked | Retry>: <one-sentence plain-language decision>',
+    '1. **<short issue>** — <only the decisive evidence, including an exact command/error, path, or identifier when it enables action>.',
+    '   **Action:** <the specific owner or role> must <the concrete evidence, decision, or change needed>.',
+    '2. Repeat only for other independent issues (at most three total).',
+    '**Next:** <the exact safe next move, such as provide the listed evidence and run `/workflow-resume`>.',
+    '',
+    'Do not include a process narrative, raw logs, repeated policy constraints, successful checks, clean-state notes, or statements that merely say the child lacks authority. Mention a passed check only when it directly explains the remaining issue. Name the missing prerequisite and who can supply it. Keep only details needed to make the decision or complete the next action.',
+    '',
+  ];
+}

package/src/prompt/step-task.ts

@@ -4,6 +4,7 @@ import { createStepContract } from './step-contract.ts';
 import {
   buildDelegatedCompletionInstructions,
   buildDelegatedHandoffSection,
+  buildNonSuccessSummaryInstructions,
   buildRestartWorkspaceSection,
   buildResourceSection,
 } from './step-sections.ts';
@@ -149,6 +150,7 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
     ...contract.workspaceLines,
     '',
     'Put a self-contained compact handoff in `summary`; this is the only step context passed to the next fresh child.',
+    ...buildNonSuccessSummaryInstructions(contract.outcomes),
     ...(isDelegated ? buildDelegatedCompletionInstructions() : []),
     'Do not call the completion tool alongside other tool calls.',
   ].join('\n');