@davidorex/pi-workflows 0.2.0 → 0.3.1

package/schemas/structure-analysis.schema.json

@@ -1,42 +1,42 @@
 {
-  "type": "object",
-  "required": ["architecture", "modules", "dependencies"],
-  "properties": {
-    "architecture": {
-      "type": "object",
-      "required": ["patterns", "organization"],
-      "properties": {
-        "patterns": { "type": "array", "items": { "type": "string" } },
-        "organization": { "type": "string" }
-      }
-    },
-    "modules": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["name", "responsibility", "files"],
-        "properties": {
-          "name": { "type": "string" },
-          "responsibility": { "type": "string" },
-          "files": { "type": "array", "items": { "type": "string" } }
-        }
-      }
-    },
-    "dependencies": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["from", "to", "type"],
-        "properties": {
-          "from": { "type": "string" },
-          "to": { "type": "string" },
-          "type": { "type": "string", "enum": ["import", "runtime", "config"] }
-        }
-      }
-    },
-    "entryPoints": {
-      "type": "array",
-      "items": { "type": "string" }
-    }
-  }
+	"type": "object",
+	"required": ["architecture", "modules", "dependencies"],
+	"properties": {
+		"architecture": {
+			"type": "object",
+			"required": ["patterns", "organization"],
+			"properties": {
+				"patterns": { "type": "array", "items": { "type": "string" } },
+				"organization": { "type": "string" }
+			}
+		},
+		"modules": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["name", "responsibility", "files"],
+				"properties": {
+					"name": { "type": "string" },
+					"responsibility": { "type": "string" },
+					"files": { "type": "array", "items": { "type": "string" } }
+				}
+			}
+		},
+		"dependencies": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["from", "to", "type"],
+				"properties": {
+					"from": { "type": "string" },
+					"to": { "type": "string" },
+					"type": { "type": "string", "enum": ["import", "runtime", "config"] }
+				}
+			}
+		},
+		"entryPoints": {
+			"type": "array",
+			"items": { "type": "string" }
+		}
+	}
 }

package/schemas/synthesis.schema.json

@@ -1,33 +1,33 @@
 {
-  "type": "object",
-  "required": ["summary", "findings", "recommendations"],
-  "properties": {
-    "summary": { "type": "string" },
-    "findings": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["category", "description", "severity"],
-        "properties": {
-          "category": { "type": "string", "enum": ["structure", "quality", "patterns"] },
-          "description": { "type": "string" },
-          "severity": { "type": "string", "enum": ["info", "warning", "critical"] },
-          "files": { "type": "array", "items": { "type": "string" } }
-        }
-      }
-    },
-    "recommendations": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["action", "rationale", "priority"],
-        "properties": {
-          "action": { "type": "string" },
-          "rationale": { "type": "string" },
-          "priority": { "type": "string", "enum": ["high", "medium", "low"] },
-          "affectedFiles": { "type": "array", "items": { "type": "string" } }
-        }
-      }
-    }
-  }
+	"type": "object",
+	"required": ["summary", "findings", "recommendations"],
+	"properties": {
+		"summary": { "type": "string" },
+		"findings": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["category", "description", "severity"],
+				"properties": {
+					"category": { "type": "string", "enum": ["structure", "quality", "patterns"] },
+					"description": { "type": "string" },
+					"severity": { "type": "string", "enum": ["info", "warning", "critical"] },
+					"files": { "type": "array", "items": { "type": "string" } }
+				}
+			}
+		},
+		"recommendations": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["action", "rationale", "priority"],
+				"properties": {
+					"action": { "type": "string" },
+					"rationale": { "type": "string" },
+					"priority": { "type": "string", "enum": ["high", "medium", "low"] },
+					"affectedFiles": { "type": "array", "items": { "type": "string" } }
+				}
+			}
+		}
+	}
 }

package/schemas/verifier-output.schema.json

@@ -1,96 +1,96 @@
 {
-  "type": "object",
-  "required": ["status", "score", "truths", "criteria_results"],
-  "properties": {
-    "status": {
-      "type": "string",
-      "enum": ["passed", "gaps_found", "human_needed"]
-    },
-    "score": {
-      "type": "string",
-      "description": "Score in N/M format (e.g. '5/7')"
-    },
-    "truths": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["truth", "status", "evidence"],
-        "properties": {
-          "truth": { "type": "string" },
-          "status": { "type": "string", "enum": ["verified", "failed", "uncertain"] },
-          "evidence": { "type": "string" }
-        }
-      }
-    },
-    "artifacts": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["path", "status"],
-        "properties": {
-          "path": { "type": "string" },
-          "status": { "type": "string", "enum": ["verified", "stub", "missing"] },
-          "exists": { "type": "boolean" },
-          "substantive": { "type": "boolean" },
-          "wired": { "type": "boolean" },
-          "details": { "type": "string" }
-        }
-      }
-    },
-    "requirements_coverage": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["requirement_id", "status"],
-        "properties": {
-          "requirement_id": { "type": "string" },
-          "status": { "type": "string", "enum": ["satisfied", "blocked", "needs_human"] },
-          "supporting_truths": {
-            "type": "array",
-            "items": { "type": "string" }
-          }
-        }
-      }
-    },
-    "criteria_results": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["criterion", "verify_method", "status"],
-        "properties": {
-          "criterion": { "type": "string" },
-          "verify_method": { "type": "string", "enum": ["command", "grep", "inspect"] },
-          "status": { "type": "string", "enum": ["passed", "failed", "uncertain", "skipped"] },
-          "expected_outcome": { "type": "string" },
-          "actual_outcome": { "type": "string" },
-          "evidence": { "type": "string" }
-        }
-      }
-    },
-    "human_verification": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["name", "test", "expected", "why_human"],
-        "properties": {
-          "name": { "type": "string" },
-          "test": { "type": "string" },
-          "expected": { "type": "string" },
-          "why_human": { "type": "string" }
-        }
-      }
-    },
-    "gaps": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["truth", "status", "reason"],
-        "properties": {
-          "truth": { "type": "string" },
-          "status": { "type": "string" },
-          "reason": { "type": "string" }
-        }
-      }
-    }
-  }
+	"type": "object",
+	"required": ["status", "score", "truths", "criteria_results"],
+	"properties": {
+		"status": {
+			"type": "string",
+			"enum": ["passed", "gaps_found", "human_needed"]
+		},
+		"score": {
+			"type": "string",
+			"description": "Score in N/M format (e.g. '5/7')"
+		},
+		"truths": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["truth", "status", "evidence"],
+				"properties": {
+					"truth": { "type": "string" },
+					"status": { "type": "string", "enum": ["verified", "failed", "uncertain"] },
+					"evidence": { "type": "string" }
+				}
+			}
+		},
+		"artifacts": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["path", "status"],
+				"properties": {
+					"path": { "type": "string" },
+					"status": { "type": "string", "enum": ["verified", "stub", "missing"] },
+					"exists": { "type": "boolean" },
+					"substantive": { "type": "boolean" },
+					"wired": { "type": "boolean" },
+					"details": { "type": "string" }
+				}
+			}
+		},
+		"requirements_coverage": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["requirement_id", "status"],
+				"properties": {
+					"requirement_id": { "type": "string" },
+					"status": { "type": "string", "enum": ["satisfied", "blocked", "needs_human"] },
+					"supporting_truths": {
+						"type": "array",
+						"items": { "type": "string" }
+					}
+				}
+			}
+		},
+		"criteria_results": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["criterion", "verify_method", "status"],
+				"properties": {
+					"criterion": { "type": "string" },
+					"verify_method": { "type": "string", "enum": ["command", "grep", "inspect"] },
+					"status": { "type": "string", "enum": ["passed", "failed", "uncertain", "skipped"] },
+					"expected_outcome": { "type": "string" },
+					"actual_outcome": { "type": "string" },
+					"evidence": { "type": "string" }
+				}
+			}
+		},
+		"human_verification": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["name", "test", "expected", "why_human"],
+				"properties": {
+					"name": { "type": "string" },
+					"test": { "type": "string" },
+					"expected": { "type": "string" },
+					"why_human": { "type": "string" }
+				}
+			}
+		},
+		"gaps": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["truth", "status", "reason"],
+				"properties": {
+					"truth": { "type": "string" },
+					"status": { "type": "string" },
+					"reason": { "type": "string" }
+				}
+			}
+		}
+	}
 }

package/skill-narrative.md

@@ -0,0 +1,107 @@
+---
+name: pi-workflows
+description: >
+  Orchestrates multi-step agent workflows defined in YAML with DAG-based execution,
+  typed data flow, checkpoint/resume, and output validation. Use when running workflows,
+  authoring workflow specs, debugging step failures, or inspecting agent configurations.
+---
+
+<objective>
+pi-workflows orchestrates multi-step agent workflows defined in YAML. Workflows are DAGs of typed steps with data flow via `${{ }}` expressions.
+</objective>
+
+<workflow_discovery>
+Workflows are discovered from three locations (first match wins):
+1. `.workflows/*.workflow.yaml` — project-level
+2. `~/.pi/agent/workflows/*.workflow.yaml` — user-level
+3. Package bundled `workflows/` — built-in
+</workflow_discovery>
+
+<step_types>
+| Type | Field | Description |
+|------|-------|-------------|
+| agent | `agent: name` | Dispatch an LLM subprocess via `pi --mode json` |
+| command | `command: "..."` | Run a shell command, capture stdout as output |
+| monitor | `monitor: name` | Run a monitor classification as a verification gate |
+| transform | `transform: { mapping: {...} }` | Pure data transformation via expressions, no LLM |
+| gate | `gate: { check: "..." }` | Shell command exit code as pass/fail boolean |
+| loop | `loop: { maxAttempts, steps }` | Repeat sub-steps until gate breaks or max reached |
+| parallel | `parallel: { a: ..., b: ... }` | Run named sub-steps concurrently |
+| pause | `pause: true` or `pause: "message"` | Pause execution, resumable later |
+| forEach | `forEach: "${{ expr }}"` | Iterate over an array, executing the step per element |
+</step_types>
+
+<expression_syntax>
+`${{ expression }}` resolves against scope: `input`, `steps`, `loop`, `forEach`.
+
+Access step outputs: `${{ steps.investigate.output.findings }}`
+Filters: `${{ steps.analyze.output | json }}`, `${{ items | length }}`, `${{ name | upper }}`
+
+Available filters: length, keys, filter, json, upper, lower, trim, default, first, last, join, split, replace, includes, map, sum, min, max, sort, unique, flatten, zip, group_by, count_by, chunk, pick, omit, entries, from_entries, merge, values, not, and, or.
+</expression_syntax>
+
+<agent_resolution>
+Agent specs (`.agent.yaml`) are resolved from three locations (first match wins):
+1. `.pi/agents/<name>.agent.yaml` — project-level
+2. `~/.pi/agent/agents/<name>.agent.yaml` — user-level
+3. Package bundled `agents/<name>.agent.yaml` — built-in
+
+Agent specs define: model, thinking level, tools, system prompt (or template), task template, output format/schema.
+</agent_resolution>
+
+<execution_model>
+1. Steps are ordered by YAML declaration order
+2. DAG planner infers parallelism from `${{ steps.X }}` references
+3. Steps without explicit dependencies run after their predecessor (conservative sequential)
+4. Each step's result is persisted atomically to `<runDir>/state.json`
+5. TUI progress widget shows real-time step status, cost, and timing
+</execution_model>
+
+<checkpoint_resume>
+Incomplete runs (failed or paused) are detected on next invocation. If the workflow spec hasn't changed incompatibly, execution resumes from the last completed step. Failed steps are re-executed. Use `fresh: "true"` to force a new run.
+</checkpoint_resume>
+
+<output_validation>
+Steps with `output.schema` validate the agent's JSON output against a JSON Schema file. Validation failure marks the step as failed.
+
+Use `block:<name>` to reference project block schemas portably: `output.schema: block:project` resolves to `.project/schemas/project.schema.json` from cwd. Works across monorepo, npm install, and user-customized schemas. Combined with `retry: { maxAttempts: 2 }`, the agent gets the schema validation error injected into its retry prompt and can self-correct.
+</output_validation>
+
+<retry>
+Steps with `retry: { maxAttempts: N }` are re-executed on failure. Between retries:
+- Project block files are rolled back to pre-attempt state
+- Prior error messages are injected into the prompt
+- Optional `steeringMessage` provides custom retry guidance
+</retry>
+
+<completion_messages>
+After execution, the workflow result is injected into the main LLM conversation. The `completion` field controls this: either a `template` (full `${{ }}` template) or `message` + `include` (message text plus resolved data paths).
+</completion_messages>
+
+<artifacts>
+Workflows can write post-completion files via the `artifacts` field. Paths may contain `${{ }}` expressions. Artifacts targeting `.project/*.json` are routed through `writeBlock()` for schema validation.
+
+Block artifact write failures are fatal — if the data doesn't conform to the block's schema, the workflow fails. Non-block artifact failures remain non-fatal (warning). On resume, all steps are preserved; only artifact processing re-runs, so fixing the schema issue or agent output and resuming avoids re-running expensive LLM steps.
+</artifacts>
+
+<validation>
+`validateWorkflow(spec, cwd)` runs authoring-time checks without executing the workflow:
+
+1. **Agent resolution** — all referenced agents exist in the three-tier search
+2. **Monitor resolution** — all referenced monitors exist in .pi/monitors/ or built-in examples
+3. **Schema resolution** — all output schema file paths resolve to existing files
+4. **Step reference validity** — `${{ steps.X }}` expressions reference declared steps
+5. **Step ordering** — referenced steps are declared before the referencing step
+6. **Filter name validity** — `${{ value | filter }}` uses known filter names
+
+Returns `{ valid: boolean, issues: ValidationIssue[] }` where each issue has severity, message, and field path. Use `/workflow validate` or `/workflow validate <name>` to run from the command line.
+</validation>
+
+<success_criteria>
+- Workflow completes all steps without unhandled failures
+- Step outputs match declared output schemas
+- State is persisted atomically after each step
+- Completion message is delivered to main conversation
+- `/workflow validate` returns no errors for authored specs
+- Checkpoint/resume recovers from the last completed step
+</success_criteria>

package/skills/pi-workflows/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: pi-workflows
+description: >
+  Orchestrates multi-step agent workflows defined in YAML with DAG-based
+  execution, typed data flow, checkpoint/resume, and output validation. Use when
+  running workflows, authoring workflow specs, debugging step failures, or
+  inspecting agent configurations.
+---
+
+<tools_reference>
+<tool name="workflow">
+Run a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/.
+
+*Run a multi-step workflow with typed data flow between agents*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow` | string | yes | Name of the workflow to run |
+| `input` | unknown | no | Input data for the workflow (validated against workflow's input schema) |
+| `fresh` | string | no | Set to 'true' to start a fresh run, ignoring any incomplete prior runs |
+</tool>
+
+<tool name="workflow-list">
+List available workflows with names, descriptions, and sources.
+
+*List available workflows with names, descriptions, and sources*
+
+</tool>
+
+<tool name="workflow-agents">
+List available agents with full specs, or inspect a single agent by name. Returns role, description, model, tools, output format/schema, prompt template paths.
+
+*List available agents with specs, or inspect a single agent by name*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | no | Agent name to inspect (omit to list all) |
+</tool>
+
+<tool name="workflow-validate">
+Validate workflow specs — check agents, schemas, step references, and filters.
+
+*Validate workflow specs — check agents, schemas, step references, filters*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | no | Workflow name to validate (omit to validate all) |
+</tool>
+
+<tool name="workflow-status">
+Get workflow vocabulary — step types, filters, available agents, workflows, schemas, templates.
+
+*Get workflow vocabulary — step types, filters, available agents, workflows, schemas*
+
+</tool>
+
+<tool name="workflow-init">
+Initialize .workflows/ directory for workflow run state.
+
+*Initialize .workflows/ directory for workflow run state*
+
+</tool>
+
+</tools_reference>
+
+<commands_reference>
+<command name="/workflow">
+List and run workflows
+
+Subcommands: `init`, `run`, `list`, `resume`, `validate`, `status`
+</command>
+
+</commands_reference>
+
+<keyboard_shortcuts>
+- **ctrl+h** — Pause running workflow
+- **ctrl+j** — Resume paused workflow
+</keyboard_shortcuts>
+
+<bundled_resources>
+21 agents, 11 schemas, 14 workflows, 28 templates bundled.
+See references/bundled-resources.md for full inventory.
+</bundled_resources>
+
+<objective>
+pi-workflows orchestrates multi-step agent workflows defined in YAML. Workflows are DAGs of typed steps with data flow via `${{ }}` expressions.
+</objective>
+
+<workflow_discovery>
+Workflows are discovered from three locations (first match wins):
+1. `.workflows/*.workflow.yaml` — project-level
+2. `~/.pi/agent/workflows/*.workflow.yaml` — user-level
+3. Package bundled `workflows/` — built-in
+</workflow_discovery>
+
+<step_types>
+| Type | Field | Description |
+|------|-------|-------------|
+| agent | `agent: name` | Dispatch an LLM subprocess via `pi --mode json` |
+| command | `command: "..."` | Run a shell command, capture stdout as output |
+| monitor | `monitor: name` | Run a monitor classification as a verification gate |
+| transform | `transform: { mapping: {...} }` | Pure data transformation via expressions, no LLM |
+| gate | `gate: { check: "..." }` | Shell command exit code as pass/fail boolean |
+| loop | `loop: { maxAttempts, steps }` | Repeat sub-steps until gate breaks or max reached |
+| parallel | `parallel: { a: ..., b: ... }` | Run named sub-steps concurrently |
+| pause | `pause: true` or `pause: "message"` | Pause execution, resumable later |
+| forEach | `forEach: "${{ expr }}"` | Iterate over an array, executing the step per element |
+</step_types>
+
+<expression_syntax>
+`${{ expression }}` resolves against scope: `input`, `steps`, `loop`, `forEach`.
+
+Access step outputs: `${{ steps.investigate.output.findings }}`
+Filters: `${{ steps.analyze.output | json }}`, `${{ items | length }}`, `${{ name | upper }}`
+
+Available filters: length, keys, filter, json, upper, lower, trim, default, first, last, join, split, replace, includes, map, sum, min, max, sort, unique, flatten, zip, group_by, count_by, chunk, pick, omit, entries, from_entries, merge, values, not, and, or.
+</expression_syntax>
+
+<agent_resolution>
+Agent specs (`.agent.yaml`) are resolved from three locations (first match wins):
+1. `.pi/agents/<name>.agent.yaml` — project-level
+2. `~/.pi/agent/agents/<name>.agent.yaml` — user-level
+3. Package bundled `agents/<name>.agent.yaml` — built-in
+
+Agent specs define: model, thinking level, tools, system prompt (or template), task template, output format/schema.
+</agent_resolution>
+
+<execution_model>
+1. Steps are ordered by YAML declaration order
+2. DAG planner infers parallelism from `${{ steps.X }}` references
+3. Steps without explicit dependencies run after their predecessor (conservative sequential)
+4. Each step's result is persisted atomically to `<runDir>/state.json`
+5. TUI progress widget shows real-time step status, cost, and timing
+</execution_model>
+
+<checkpoint_resume>
+Incomplete runs (failed or paused) are detected on next invocation. If the workflow spec hasn't changed incompatibly, execution resumes from the last completed step. Failed steps are re-executed. Use `fresh: "true"` to force a new run.
+</checkpoint_resume>
+
+<output_validation>
+Steps with `output.schema` validate the agent's JSON output against a JSON Schema file. Validation failure marks the step as failed.
+
+Use `block:<name>` to reference project block schemas portably: `output.schema: block:project` resolves to `.project/schemas/project.schema.json` from cwd. Works across monorepo, npm install, and user-customized schemas. Combined with `retry: { maxAttempts: 2 }`, the agent gets the schema validation error injected into its retry prompt and can self-correct.
+</output_validation>
+
+<retry>
+Steps with `retry: { maxAttempts: N }` are re-executed on failure. Between retries:
+- Project block files are rolled back to pre-attempt state
+- Prior error messages are injected into the prompt
+- Optional `steeringMessage` provides custom retry guidance
+</retry>
+
+<completion_messages>
+After execution, the workflow result is injected into the main LLM conversation. The `completion` field controls this: either a `template` (full `${{ }}` template) or `message` + `include` (message text plus resolved data paths).
+</completion_messages>
+
+<artifacts>
+Workflows can write post-completion files via the `artifacts` field. Paths may contain `${{ }}` expressions. Artifacts targeting `.project/*.json` are routed through `writeBlock()` for schema validation.
+
+Block artifact write failures are fatal — if the data doesn't conform to the block's schema, the workflow fails. Non-block artifact failures remain non-fatal (warning). On resume, all steps are preserved; only artifact processing re-runs, so fixing the schema issue or agent output and resuming avoids re-running expensive LLM steps.
+</artifacts>
+
+<validation>
+`validateWorkflow(spec, cwd)` runs authoring-time checks without executing the workflow:
+
+1. **Agent resolution** — all referenced agents exist in the three-tier search
+2. **Monitor resolution** — all referenced monitors exist in .pi/monitors/ or built-in examples
+3. **Schema resolution** — all output schema file paths resolve to existing files
+4. **Step reference validity** — `${{ steps.X }}` expressions reference declared steps
+5. **Step ordering** — referenced steps are declared before the referencing step
+6. **Filter name validity** — `${{ value | filter }}` uses known filter names
+
+Returns `{ valid: boolean, issues: ValidationIssue[] }` where each issue has severity, message, and field path. Use `/workflow validate` or `/workflow validate <name>` to run from the command line.
+</validation>
+
+<success_criteria>
+- Workflow completes all steps without unhandled failures
+- Step outputs match declared output schemas
+- State is persisted atomically after each step
+- Completion message is delivered to main conversation
+- `/workflow validate` returns no errors for authored specs
+- Checkpoint/resume recovers from the last completed step
+</success_criteria>
+
+*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*