@davidorex/pi-workflows 0.2.0 → 0.3.0

package/skills/pi-workflows/SKILL.md

@@ -0,0 +1,247 @@
+# @davidorex/pi-workflows
+
+> Workflow orchestration extension for Pi
+
+## Tools
+
+### 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 |
+
+### workflow-list
+
+List available workflows with names, descriptions, and sources.
+
+*List available workflows with names, descriptions, and sources*
+
+### 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) |
+
+### 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) |
+
+### 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
+
+Initialize .workflows/ directory for workflow run state.
+
+*Initialize .workflows/ directory for workflow run state*
+
+## Commands
+
+### /workflow
+
+List and run workflows
+
+Subcommands: `init`, `run`, `list`, `resume`, `validate`, `status`
+
+## Keyboard Shortcuts
+
+- **ctrl+h** — Pause running workflow
+- **ctrl+j** — Resume paused workflow
+
+## 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
+
+pi-workflows orchestrates multi-step agent workflows defined in YAML. Workflows are DAGs of typed steps with data flow via `${{ }}` expressions.
+
+### 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
+
+### 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 |
+| 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 |
+
+### 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.
+
+### 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.
+
+### 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
+
+### Checkpoint and 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.
+
+### 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
+
+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
+
+### 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).
+
+### Artifacts
+
+Workflows can write post-completion files via the `artifacts` field. Paths may contain `${{ }}` expressions. Artifacts targeting `.project/*.json` are validated against block schemas.
+
+### 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
+
+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.
+
+---
+
+*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

package/templates/architecture-designer/task.md

@@ -0,0 +1,117 @@
+## Project Identity
+
+**Name:** {{ project.name }}
+**Description:** {{ project.description }}
+**Core Value:** {{ project.core_value }}
+{% if project.stack %}
+
+### Stack
+{% for item in project.stack %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+
+### Constraints
+{% for constraint in project.constraints %}
+- [{{ constraint.type }}] {{ constraint.description }}
+{% endfor %}
+
+### Scope Boundaries
+
+**In scope:**
+{% for item in project.scope_boundaries.in %}
+- {{ item }}
+{% endfor %}
+
+**Out of scope:**
+{% for item in project.scope_boundaries.out %}
+- {{ item }}
+{% endfor %}
+
+## Requirements
+
+### Must
+{% for req in requirements.requirements %}
+{% if req.priority == "must" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+### Should
+{% for req in requirements.requirements %}
+{% if req.priority == "should" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+### Could
+{% for req in requirements.requirements %}
+{% if req.priority == "could" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+## Instructions
+
+Design the initial architecture for this project. Produce modules, patterns, and boundaries that satisfy the requirements above — starting with "must" requirements and ensuring "should" requirements have a clear home.
+
+### For each module, provide:
+
+1. **name** — short identifier (e.g., "api", "auth", "storage", "cli")
+2. **file** — primary file path relative to project root (e.g., "src/api.ts")
+3. **responsibility** — one sentence: what this module owns and what it does not
+4. **dependencies** — array of other module names this depends on (empty if none)
+5. **lines** — estimated lines of code (rough order of magnitude)
+
+### For each pattern, provide:
+
+1. **name** — recognized pattern name (e.g., "Repository Pattern", "Event Sourcing", "Middleware Pipeline")
+2. **description** — why this pattern is appropriate for this project's specific needs
+3. **used_in** — array of module names that implement this pattern
+
+### For boundaries, provide:
+
+An array of strings — each describing a hard architectural constraint. These should be specific to this project, not generic ("All database access goes through the storage module", not "separate concerns").
+
+### Design principles
+
+- Module count should be proportional to requirements — a 5-requirement project needs 3-5 modules, not 15
+- Every "must" functional requirement should map to at least one module's responsibility
+- Every "must" non-functional requirement should be addressed by a pattern or boundary
+- Dependencies should flow in one direction — avoid circular module dependencies
+- If the project has a stated stack, modules should use file extensions and conventions matching that stack
+- Prefer explicit boundaries over implicit conventions
+
+### Overview
+
+Write an `overview` paragraph (required) summarizing:
+- The architectural style (layered, modular, pipeline, etc.)
+- The key structural decisions and why they fit this project
+- How the architecture supports the core_value
+
+### Output format
+
+Produce a single JSON object:
+
+```json
+{
+  "overview": "string (required)",
+  "modules": [
+    {
+      "name": "string (required)",
+      "file": "string (required)",
+      "responsibility": "string (required)",
+      "dependencies": ["string"],
+      "lines": 100
+    }
+  ],
+  "patterns": [
+    {
+      "name": "string (required)",
+      "description": "string (required)",
+      "used_in": ["module-name"]
+    }
+  ],
+  "boundaries": ["string"]
+}
+```

package/templates/architecture-inferrer/task.md

@@ -0,0 +1,61 @@
+Infer the architecture of the project at `{{ path }}`.
+
+## Codebase Analysis
+
+{% if analysis.files is defined %}
+### Files
+{% for file in analysis.files %}
+- `{{ file.path }}` ({{ file.language | default("unknown") }}, {{ file.lines | default("?") }} lines){% if file.exports %} — {{ file.exports | length }} exports{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if analysis.types is defined %}
+### Types
+{% for t in analysis.types %}
+- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}
+{% endif %}
+
+{% if analysis.dependencies is defined %}
+### Dependencies
+{% for d in analysis.dependencies %}
+- `{{ d.from }}` → `{{ d.to }}` ({{ d.type | default("import") }})
+{% endfor %}
+{% endif %}
+
+{% if analysis.entryPoints is defined %}
+### Entry Points
+{% for ep in analysis.entryPoints %}
+- `{{ ep }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+From the analysis above and targeted code reads, produce an architecture block:
+
+1. **Modules** — each cohesive unit with a clear responsibility. For each:
+   - `name`: concise identifier (e.g., "block-api", "expression-engine")
+   - `file`: primary file path relative to project root
+   - `responsibility`: one-sentence description of what this module does
+   - `dependencies`: array of other module names this module depends on
+   - `lines`: approximate line count
+
+2. **Patterns** — design patterns evidenced in the code. For each:
+   - `name`: pattern name (e.g., "registry", "factory", "middleware")
+   - `description`: how this pattern is applied in this codebase
+   - `used_in`: array of module names that use this pattern
+
+3. **Boundaries** — architectural seams where modules interact through defined interfaces (e.g., "block-api validates all writes before persistence", "dispatch spawns subprocesses through a single entry point")
+
+4. **Overview** — one paragraph summarizing the architecture: what the system does, how it's organized, and what the key design decisions are
+
+Read entry points, config files, and module interfaces to confirm the analysis. Do not read every file.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/gap-identifier/task.md

@@ -0,0 +1,103 @@
+Identify gaps in the project at `{{ path }}`.
+
+## Architecture
+
+{% if architecture.overview %}
+{{ architecture.overview }}
+{% endif %}
+
+### Modules
+{% if architecture.modules is defined %}
+{% for m in architecture.modules %}
+- **{{ m.name }}** (`{{ m.file }}`{% if m.lines %}, {{ m.lines }} lines{% endif %}): {{ m.responsibility }}
+{% endfor %}
+{% endif %}
+
+{% if architecture.patterns is defined %}
+### Patterns
+{% for p in architecture.patterns %}
+- **{{ p.name }}**: {{ p.description }}{% if p.used_in %} — used in: {{ p.used_in | join(", ") }}{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if architecture.boundaries is defined %}
+### Boundaries
+{% for b in architecture.boundaries %}
+- {{ b }}
+{% endfor %}
+{% endif %}
+
+## Codebase Analysis
+
+{% if analysis.files is defined %}
+### Files ({{ analysis.files | length }} total)
+{% for file in analysis.files %}
+- `{{ file.path }}` ({{ file.language | default("unknown") }}, {{ file.lines | default("?") }} lines){% if file.exports %} — {{ file.exports | length }} exports{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if analysis.types is defined %}
+### Types
+{% for t in analysis.types %}
+- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+Cross-reference the architecture and analysis to identify gaps. Use targeted reads to verify findings.
+
+### Gap categories to check
+
+1. **missing** — functionality that should exist based on architecture but doesn't
+   - Test files for source modules (find test files, compare against source)
+   - Error handling for public APIs
+   - Documentation for exported interfaces
+   - Schema validation for user-facing inputs
+
+2. **incomplete** — partially implemented functionality
+   - TODO/FIXME/HACK comments (`grep -r "TODO\|FIXME\|HACK"`)
+   - Stub or placeholder implementations
+   - Functions that return hardcoded values or throw "not implemented"
+
+3. **defect** — likely bugs or incorrect behavior
+   - Uncaught promise rejections, missing null checks
+   - Type assertions that bypass safety (`as any`, `!` operator overuse)
+   - Error paths that swallow exceptions silently
+
+4. **technical-debt** — code that works but hampers maintenance
+   - Duplicated logic across modules
+   - Outdated patterns inconsistent with the rest of the codebase
+   - Overly complex functions (high cyclomatic complexity)
+
+5. **improvement** — opportunities to improve existing working code
+   - Performance bottlenecks
+   - Missing caching or memoization for expensive operations
+   - Public APIs that could be more ergonomic
+
+6. **question** — ambiguities requiring human or further investigation
+   - Unclear design decisions without documented rationale
+   - Behavior that could be intentional or accidental
+
+### Gap ID format
+
+Use the pattern: `gap-{abbrev}-{nnn}` where abbrev is:
+- `miss` for missing, `inc` for incomplete, `def` for defect
+- `debt` for technical-debt, `imp` for improvement, `q` for question
+
+### Priority calibration
+
+- **critical**: blocks further development or causes data loss
+- **high**: significant impact on reliability, correctness, or developer experience
+- **medium**: notable but workable; should be addressed in normal development
+- **low**: minor cleanup or cosmetic; address opportunistically
+
+Set `source` to `"agent"` for all gaps. Set `status` to `"open"` for all gaps.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/handoff-writer/task.md

@@ -0,0 +1,91 @@
+Capture a handoff snapshot for the project at `{{ path }}`.
+
+## Current Project State
+
+{% if project_state.project is defined %}
+### Project
+**{{ project_state.project.name | default("unnamed") }}** — {{ project_state.project.description | default("no description") }}
+Status: {{ project_state.project.status | default("unknown") }}
+{% endif %}
+
+{% if project_state.phases is defined and project_state.phases | length > 0 %}
+### Phases
+{% for phase in project_state.phases %}
+- Phase {{ phase.number | default(loop.index) }}: {{ phase.name | default("unnamed") }} ({{ phase.status | default("unknown") }})
+{% endfor %}
+{% endif %}
+
+{% if project_state.blockSummaries is defined %}
+### Block Summaries
+{% for block in project_state.blockSummaries %}
+- **{{ block.name }}**: {{ block.count | default("?") }} entries
+{% endfor %}
+{% endif %}
+
+{% if project_state.gaps is defined %}
+### Open Gaps
+{% for gap in project_state.gaps %}
+{% if gap.status == "open" %}
+- [{{ gap.priority }}] {{ gap.id }}: {{ gap.description }}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if project_state.decisions is defined %}
+### Recent Decisions
+{% for decision in project_state.decisions %}
+- {{ decision.id | default("?") }}: {{ decision.description | default(decision.title | default("no description")) }}
+{% endfor %}
+{% endif %}
+
+{% if project_state.recentCommits is defined %}
+### Recent Commits
+{% for commit in project_state.recentCommits %}
+- `{{ commit.sha | default("?") | truncate(7, true, "") }}` {{ commit.message | default("no message") }}
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+Synthesize the project state above into a handoff block that enables a future agent or human to resume work seamlessly.
+
+1. **context** — Write a paragraph capturing:
+   - What was being worked on (current phase, recent commits, active changes)
+   - The current state of thinking (what decisions were made, what approach is being taken)
+   - Any momentum or direction that should be preserved
+
+2. **timestamp** — Current datetime in ISO 8601 format (e.g., 2026-03-18T14:30:00Z)
+
+3. **current_phase** — The phase currently being worked on (number or name)
+
+4. **current_tasks** — Task IDs currently in progress (from project state if available, otherwise infer from recent activity)
+
+5. **blockers** — Anything preventing progress:
+   - Unresolved decisions that block implementation
+   - Failing tests or broken builds
+   - Missing dependencies or external requirements
+   - Only include genuine blockers, not wishes
+
+6. **next_actions** — Concrete next steps, ordered by priority:
+   - What should the next session do first?
+   - What's the next logical step in the current phase?
+   - Keep to 3-5 actionable items
+
+7. **open_questions** — Genuine unknowns requiring input:
+   - Design decisions that need human judgment
+   - Ambiguities discovered during development
+   - Technical choices with trade-offs that haven't been resolved
+
+8. **key_decisions_pending** — Decision IDs from the project state that need resolution
+
+9. **files_in_flux** — Files with incomplete or in-progress changes (NOT every recently committed file — only files that have partial work)
+
+Read project blocks if needed to get more detail than the summary provides. Focus on in-flight state, not project overview.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```