@davidorex/pi-workflows 0.3.0 → 0.3.1

package/skills/pi-workflows/SKILL.md

@@ -1,11 +1,14 @@
-# @davidorex/pi-workflows
-
-> Workflow orchestration extension for Pi
-
-## Tools
-
-### workflow
+---
+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*
@@ -15,15 +18,16 @@ Run a named workflow with typed input. Discovers workflows from .workflows/ and
 | `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>
 
-### workflow-list
-
+<tool name="workflow-list">
 List available workflows with names, descriptions, and sources.
 
 *List available workflows with names, descriptions, and sources*
 
-### workflow-agents
+</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*
@@ -31,9 +35,9 @@ List available agents with full specs, or inspect a single agent by name. Return
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `name` | string | no | Agent name to inspect (omit to list all) |
+</tool>
 
-### workflow-validate
-
+<tool name="workflow-validate">
 Validate workflow specs — check agents, schemas, step references, and filters.
 
 *Validate workflow specs — check agents, schemas, step references, filters*
@@ -41,207 +45,141 @@ Validate workflow specs — check agents, schemas, step references, and filters.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `name` | string | no | Workflow name to validate (omit to validate all) |
+</tool>
 
-### workflow-status
-
+<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*
 
-### workflow-init
+</tool>
 
+<tool name="workflow-init">
 Initialize .workflows/ directory for workflow run state.
 
 *Initialize .workflows/ directory for workflow run state*
 
-## Commands
+</tool>
 
-### /workflow
+</tools_reference>
 
+<commands_reference>
+<command name="/workflow">
 List and run workflows
 
 Subcommands: `init`, `run`, `list`, `resume`, `validate`, `status`
+</command>
 
-## Keyboard Shortcuts
+</commands_reference>
 
+<keyboard_shortcuts>
 - **ctrl+h** — Pause running workflow
 - **ctrl+j** — Resume paused workflow
+</keyboard_shortcuts>
 
-## Bundled Resources
-
-### agents/ (21 files)
-
-- `agents/architecture-designer.agent.yaml`
-- `agents/architecture-inferrer.agent.yaml`
-- `agents/audit-fixer.agent.yaml`
-- `agents/code-explorer.agent.yaml`
-- `agents/decomposer.agent.yaml`
-- `agents/gap-identifier.agent.yaml`
-- `agents/handoff-writer.agent.yaml`
-- `agents/investigator.agent.yaml`
-- `agents/pattern-analyzer.agent.yaml`
-- `agents/phase-author.agent.yaml`
-- `agents/plan-creator.agent.yaml`
-- `agents/plan-decomposer.agent.yaml`
-- `agents/project-definer.agent.yaml`
-- `agents/project-inferrer.agent.yaml`
-- `agents/quality-analyzer.agent.yaml`
-- `agents/requirements-gatherer.agent.yaml`
-- `agents/researcher.agent.yaml`
-- `agents/spec-implementer.agent.yaml`
-- `agents/structure-analyzer.agent.yaml`
-- `agents/synthesizer.agent.yaml`
-- `agents/verifier.agent.yaml`
-
-### schemas/ (11 files)
-
-- `schemas/decomposition-specs.schema.json`
-- `schemas/execution-results.schema.json`
-- `schemas/investigation-findings.schema.json`
-- `schemas/pattern-analysis.schema.json`
-- `schemas/phase.schema.json`
-- `schemas/plan-breakdown.schema.json`
-- `schemas/quality-analysis.schema.json`
-- `schemas/research-findings.schema.json`
-- `schemas/structure-analysis.schema.json`
-- `schemas/synthesis.schema.json`
-- `schemas/verifier-output.schema.json`
-
-### workflows/ (14 files)
-
-- `workflows/analyze-existing-project.workflow.yaml`
-- `workflows/create-handoff.workflow.yaml`
-- `workflows/create-phase.workflow.yaml`
-- `workflows/do-gap.workflow.yaml`
-- `workflows/fix-audit.workflow.yaml`
-- `workflows/gap-to-phase.workflow.yaml`
-- `workflows/init-new-project.workflow.yaml`
-- `workflows/parallel-analysis.workflow.yaml`
-- `workflows/parallel-explicit.workflow.yaml`
-- `workflows/pausable-analysis.workflow.yaml`
-- `workflows/plan-from-requirements.workflow.yaml`
-- `workflows/resumable-analysis.workflow.yaml`
-- `workflows/self-implement.workflow.yaml`
-- `workflows/typed-analysis.workflow.yaml`
-
-### templates/ (28 files)
-
-- `templates/analyzers/base-analyzer.md`
-- `templates/analyzers/macros.md`
-- `templates/analyzers/patterns-task.md`
-- `templates/analyzers/patterns.md`
-- `templates/analyzers/quality-task.md`
-- `templates/analyzers/quality.md`
-- `templates/analyzers/structure-task.md`
-- `templates/analyzers/structure.md`
-- `templates/architecture-designer/task.md`
-- `templates/architecture-inferrer/task.md`
-- `templates/audit-fixer/task.md`
-- `templates/decomposer/task.md`
-- `templates/explorer/system.md`
-- `templates/explorer/task.md`
-- `templates/gap-identifier/task.md`
-- `templates/handoff-writer/task.md`
-- `templates/investigator/task.md`
-- `templates/phase-author/task.md`
-- `templates/plan-creator/task.md`
-- `templates/plan-decomposer/task.md`
-- `templates/project-definer/task.md`
-- `templates/project-inferrer/task.md`
-- `templates/requirements-gatherer/task.md`
-- `templates/researcher/task.md`
-- `templates/spec-implementer/task.md`
-- `templates/synthesizer/system.md`
-- `templates/synthesizer/task.md`
-- `templates/verifier/task.md`
-
----
-
-## How It Works
+<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
-
+<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
-
+<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_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_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
-
+<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 and Resume
-
+<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
-
+<output_validation>
 Steps with `output.schema` validate the agent's JSON output against a JSON Schema file. Validation failure marks the step as failed.
 
-### Per-Step Retry
+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
-
+<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 validated against block schemas.
+<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.
 
-### 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. **Schema resolution** — all output schema file paths resolve to existing files
-3. **Step reference validity** — `${{ steps.X }}` expressions reference declared steps
-4. **Step ordering** — referenced steps are declared before the referencing step
-5. **Filter name validity** — `${{ value | filter }}` uses known filter names
+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.*

package/skills/pi-workflows/references/bundled-resources.md

@@ -0,0 +1,87 @@
+# Bundled Resources
+
+## agents/ (21 files)
+
+- `agents/architecture-designer.agent.yaml`
+- `agents/architecture-inferrer.agent.yaml`
+- `agents/audit-fixer.agent.yaml`
+- `agents/code-explorer.agent.yaml`
+- `agents/decomposer.agent.yaml`
+- `agents/gap-identifier.agent.yaml`
+- `agents/handoff-writer.agent.yaml`
+- `agents/investigator.agent.yaml`
+- `agents/pattern-analyzer.agent.yaml`
+- `agents/phase-author.agent.yaml`
+- `agents/plan-creator.agent.yaml`
+- `agents/plan-decomposer.agent.yaml`
+- `agents/project-definer.agent.yaml`
+- `agents/project-inferrer.agent.yaml`
+- `agents/quality-analyzer.agent.yaml`
+- `agents/requirements-gatherer.agent.yaml`
+- `agents/researcher.agent.yaml`
+- `agents/spec-implementer.agent.yaml`
+- `agents/structure-analyzer.agent.yaml`
+- `agents/synthesizer.agent.yaml`
+- `agents/verifier.agent.yaml`
+
+## schemas/ (11 files)
+
+- `schemas/decomposition-specs.schema.json`
+- `schemas/execution-results.schema.json`
+- `schemas/investigation-findings.schema.json`
+- `schemas/pattern-analysis.schema.json`
+- `schemas/phase.schema.json`
+- `schemas/plan-breakdown.schema.json`
+- `schemas/quality-analysis.schema.json`
+- `schemas/research-findings.schema.json`
+- `schemas/structure-analysis.schema.json`
+- `schemas/synthesis.schema.json`
+- `schemas/verifier-output.schema.json`
+
+## workflows/ (14 files)
+
+- `workflows/analyze-existing-project.workflow.yaml`
+- `workflows/create-handoff.workflow.yaml`
+- `workflows/create-phase.workflow.yaml`
+- `workflows/do-gap.workflow.yaml`
+- `workflows/fix-audit.workflow.yaml`
+- `workflows/gap-to-phase.workflow.yaml`
+- `workflows/init-new-project.workflow.yaml`
+- `workflows/parallel-analysis.workflow.yaml`
+- `workflows/parallel-explicit.workflow.yaml`
+- `workflows/pausable-analysis.workflow.yaml`
+- `workflows/plan-from-requirements.workflow.yaml`
+- `workflows/resumable-analysis.workflow.yaml`
+- `workflows/self-implement.workflow.yaml`
+- `workflows/typed-analysis.workflow.yaml`
+
+## templates/ (28 files)
+
+- `templates/analyzers/base-analyzer.md`
+- `templates/analyzers/macros.md`
+- `templates/analyzers/patterns-task.md`
+- `templates/analyzers/patterns.md`
+- `templates/analyzers/quality-task.md`
+- `templates/analyzers/quality.md`
+- `templates/analyzers/structure-task.md`
+- `templates/analyzers/structure.md`
+- `templates/architecture-designer/task.md`
+- `templates/architecture-inferrer/task.md`
+- `templates/audit-fixer/task.md`
+- `templates/decomposer/task.md`
+- `templates/explorer/system.md`
+- `templates/explorer/task.md`
+- `templates/gap-identifier/task.md`
+- `templates/handoff-writer/task.md`
+- `templates/investigator/task.md`
+- `templates/phase-author/task.md`
+- `templates/plan-creator/task.md`
+- `templates/plan-decomposer/task.md`
+- `templates/project-definer/task.md`
+- `templates/project-inferrer/task.md`
+- `templates/requirements-gatherer/task.md`
+- `templates/researcher/task.md`
+- `templates/spec-implementer/task.md`
+- `templates/synthesizer/system.md`
+- `templates/synthesizer/task.md`
+- `templates/verifier/task.md`

package/workflows/analyze-existing-project.workflow.yaml

@@ -41,6 +41,9 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
+      schema: block:architecture
+    retry:
+      maxAttempts: 2
 
   infer-project:
     agent: project-inferrer
@@ -51,6 +54,9 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
+      schema: block:project
+    retry:
+      maxAttempts: 2
 
   identify-gaps:
     agent: gap-identifier
@@ -62,10 +68,24 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
+      schema: block:gaps
+    retry:
+      maxAttempts: 2
+
+artifacts:
+  project:
+    path: .project/project.json
+    from: steps.infer-project.output
+  architecture:
+    path: .project/architecture.json
+    from: steps.infer-architecture.output
+  gaps:
+    path: .project/gaps.json
+    from: steps.identify-gaps.output
 
 completion:
   template: |
-    Existing project analyzed.
+    Existing project analyzed. Results written to .project/ blocks.
 
     **Project:** ${{ steps.infer-project.output.name }} — ${{ steps.infer-project.output.core_value }}
     **Architecture:** ${{ steps.infer-architecture.output.modules | length }} modules, ${{ steps.infer-architecture.output.patterns | length }} patterns

package/workflows/create-handoff.workflow.yaml

@@ -52,6 +52,14 @@ steps:
       path: "."
     output:
       format: json
+      schema: block:handoff
+    retry:
+      maxAttempts: 2
+
+artifacts:
+  handoff:
+    path: .project/handoff.json
+    from: steps.capture.output
 
 completion:
   message: |

package/workflows/create-phase.workflow.yaml

@@ -42,7 +42,7 @@ steps:
       inventory: "${{ steps.load-context.output.inventory }}"
     output:
       format: json
-      schema: ../schemas/phase.schema.json
+      schema: block:phase
 
   write-phase:
     command: |

package/workflows/gap-to-phase.workflow.yaml

@@ -72,7 +72,7 @@ steps:
       inventory: "${{ steps.load-context.output.inventory }}"
     output:
       format: json
-      schema: ../schemas/phase.schema.json
+      schema: block:phase
 
   write-phase:
     command: |

package/workflows/init-new-project.workflow.yaml

@@ -17,6 +17,9 @@ steps:
       vision: ${{ input.vision }}
     output:
       format: json
+      schema: block:project
+    retry:
+      maxAttempts: 2
 
   gather-requirements:
     agent: requirements-gatherer
@@ -25,6 +28,9 @@ steps:
       vision: ${{ input.vision }}
     output:
       format: json
+      schema: block:requirements
+    retry:
+      maxAttempts: 2
 
   design-architecture:
     agent: architecture-designer
@@ -33,6 +39,9 @@ steps:
       requirements: ${{ steps.gather-requirements.output }}
     output:
       format: json
+      schema: block:architecture
+    retry:
+      maxAttempts: 2
 
   create-plan:
     agent: plan-creator
@@ -42,10 +51,27 @@ steps:
       architecture: ${{ steps.design-architecture.output }}
     output:
       format: json
+      schema: block:tasks
+    retry:
+      maxAttempts: 2
+
+artifacts:
+  project:
+    path: .project/project.json
+    from: steps.define-identity.output
+  requirements:
+    path: .project/requirements.json
+    from: steps.gather-requirements.output
+  architecture:
+    path: .project/architecture.json
+    from: steps.design-architecture.output
+  tasks:
+    path: .project/tasks.json
+    from: steps.create-plan.output
 
 completion:
   template: |
-    Project initialized from vision.
+    Project initialized from vision. Results written to .project/ blocks.
 
     **Identity:** ${{ steps.define-identity.output.name }} — ${{ steps.define-identity.output.core_value }}
     **Requirements:** ${{ steps.gather-requirements.output.requirements | length }} captured

package/workflows/plan-from-requirements.workflow.yaml

@@ -42,10 +42,18 @@ steps:
       existing_phases: ${{ steps.load-context.output.existing_phases }}
     output:
       format: json
+      schema: block:tasks
+    retry:
+      maxAttempts: 2
+
+artifacts:
+  tasks:
+    path: .project/tasks.json
+    from: steps.create-plan.output
 
 completion:
   template: |
-    Plan created from requirements.
+    Plan created from requirements. Tasks written to .project/tasks.json.
 
     Use `/project status` to see the phase and task breakdown.
     Use `/project validate` to check cross-block references.