@davidorex/pi-workflows 0.11.3 → 0.12.0

package/skills/pi-workflows/SKILL.md

@@ -82,6 +82,141 @@ Subcommands: `init`, `list`, `run`, `resume`, `validate`, `status`, `help`
 See references/bundled-resources.md for full inventory.
 </bundled_resources>
 
+<agent_vocabulary>
+
+| Agent | Role | Tools | Input (required) | Output | Context Blocks |
+|-------|------|-------|------------------|--------|----------------|
+| `architecture-designer` | reasoning | read | — | json | — |
+| `architecture-inferrer` | sensor | read, bash, grep, find | analysis, path | json | — |
+| `audit-finding-verifier` | quality | read, bash, grep, find | — | json | — |
+| `audit-fixer` | action | read, write, edit, bash, grep, find | — | json | — |
+| `audit-results-router` | reasoning | read | — | json | — |
+| `code-explorer` | sensor | read, bash, ls | — | json | — |
+| `decomposer` | decomposer | — | — | json | — |
+| `gap-identifier` | sensor | read, bash, grep, find | analysis, architecture, path | json | — |
+| `gap-resolution-assessor` | quality | read, bash, grep, find | — | json | — |
+| `handoff-writer` | reasoning | read | project_state, path | json | — |
+| `investigator` | investigator | read, bash, grep, find | — | json | — |
+| `pattern-analyzer` | sensor | read, bash, ls | exploration, path | json | — |
+| `phase-author` | reasoning | read, bash, grep, find | — | json | — |
+| `plan-creator` | reasoning | read, bash, grep, find | — | json | — |
+| `plan-decomposer` | reasoning | read, bash, grep, find | — | json | — |
+| `project-definer` | reasoning | read | — | json | — |
+| `project-inferrer` | sensor | read, bash, grep, find | analysis, path | json | — |
+| `quality-analyzer` | sensor | read, bash, ls | exploration, path | json | — |
+| `requirements-gatherer` | reasoning | read | — | json | — |
+| `researcher` | researcher | — | — | json | — |
+| `spec-implementer` | action | read, write, edit, bash, grep, find | — | json | — |
+| `structure-analyzer` | sensor | read, bash, ls | exploration, path | json | — |
+| `synthesizer` | reasoning | read | structure, quality, patterns | json | — |
+| `task-verifier` | quality | read, bash, glob, grep | task_id, acceptance_criteria, changes | json | — |
+| `task-worker` | action | read, write, edit, bash, grep, glob, ls | task | json | — |
+| `verifier` | quality | read, bash, grep, find | — | json | — |
+
+**Agent Input Schemas:**
+
+<agent_input name="architecture-inferrer">
+- `analysis` [required] — Prior codebase analysis output (structure, patterns, dependencies)
+- `path` string [required] — Root path of the project being analyzed
+</agent_input>
+
+<agent_input name="gap-identifier">
+- `analysis` [required] — Prior codebase analysis output (structure, patterns, dependencies)
+- `architecture` [required] — Architecture block (modules, patterns, boundaries)
+- `path` string [required] — Root path of the project being analyzed
+</agent_input>
+
+<agent_input name="handoff-writer">
+- `project_state` [required] — Current project state (from projectState() or /project status — includes phases, blocks, gaps, decisions, recent commits)
+- `path` string [required] — Root path of the project
+</agent_input>
+
+<agent_input name="pattern-analyzer">
+- `exploration` [required] — Prior exploration output (typed JSON)
+- `path` string [required]
+</agent_input>
+
+<agent_input name="project-inferrer">
+- `analysis` [required] — Prior codebase analysis output (structure, patterns, dependencies)
+- `path` string [required] — Root path of the project being analyzed
+</agent_input>
+
+<agent_input name="quality-analyzer">
+- `exploration` [required] — Prior exploration output (typed JSON)
+- `path` string [required]
+</agent_input>
+
+<agent_input name="structure-analyzer">
+- `exploration` [required] — Prior exploration output (typed JSON)
+- `path` string [required]
+</agent_input>
+
+<agent_input name="synthesizer">
+- `structure` [required] — Structure analysis (typed JSON)
+- `quality` [required] — Quality analysis (typed JSON)
+- `patterns` [required] — Pattern analysis (typed JSON)
+</agent_input>
+
+<agent_input name="task-verifier">
+- `task_id` string [required] — ID of the task being verified
+- `acceptance_criteria` array [required] — Acceptance criteria from the task block
+- `changes` [required] — Implementation summary or diff from the worker agent
+</agent_input>
+
+<agent_input name="task-worker">
+- `task` object [required] — Task block entry with description, acceptance_criteria, files
+- `context` string [optional] — Narrative context from prior steps
+</agent_input>
+
+**Template References:**
+
+- `architecture-designer`: task: `architecture-designer/task.md`
+- `architecture-inferrer`: task: `architecture-inferrer/task.md`
+- `audit-finding-verifier`: task: `audit-finding-verifier/task.md`
+- `audit-fixer`: task: `audit-fixer/task.md`
+- `audit-results-router`: task: `audit-results-router/task.md`
+- `code-explorer`: system: `explorer/system.md`, task: `explorer/task.md`
+- `decomposer`: task: `decomposer/task.md`
+- `gap-identifier`: task: `gap-identifier/task.md`
+- `gap-resolution-assessor`: task: `gap-resolution-assessor/task.md`
+- `handoff-writer`: task: `handoff-writer/task.md`
+- `investigator`: task: `investigator/task.md`
+- `pattern-analyzer`: system: `analyzers/patterns.md`, task: `analyzers/patterns-task.md`
+- `phase-author`: task: `templates/phase-author/task.md`
+- `plan-creator`: task: `plan-creator/task.md`
+- `plan-decomposer`: task: `plan-decomposer/task.md`
+- `project-definer`: task: `project-definer/task.md`
+- `project-inferrer`: task: `project-inferrer/task.md`
+- `quality-analyzer`: system: `analyzers/quality.md`, task: `analyzers/quality-task.md`
+- `requirements-gatherer`: task: `requirements-gatherer/task.md`
+- `researcher`: task: `researcher/task.md`
+- `spec-implementer`: task: `spec-implementer/task.md`
+- `structure-analyzer`: system: `analyzers/structure.md`, task: `analyzers/structure-task.md`
+- `synthesizer`: system: `synthesizer/system.md`, task: `synthesizer/task.md`
+- `task-verifier`: task: `task-verifier/task.md`
+- `task-worker`: task: `task-worker/task.md`
+- `verifier`: task: `verifier/task.md`
+
+</agent_vocabulary>
+
+<validation_vocabulary>
+
+| Check | Severity | Description |
+|-------|----------|-------------|
+| `agent-resolution` | error | Referenced agents exist in search paths |
+| `monitor-resolution` | warning | Referenced monitors exist in search paths |
+| `schema-existence` | error | Referenced schema files exist on disk |
+| `step-references` | error | Expression step references point to declared steps |
+| `step-ordering` | error | Steps do not forward-reference later steps |
+| `context-references` | error | context[] entries point to declared steps |
+| `filter-names` | warning | Expression filters are recognized |
+| `steptype-metadata` | error | retry/input/output declarations match step type capabilities |
+| `inputschema-required` | error | Agent required input keys are provided by step |
+| `contextblocks-existence` | warning | Declared context blocks exist in .project/ |
+| `template-alignment` | error | Template variables match step inputs and source schemas |
+
+</validation_vocabulary>
+
 <objective>
 pi-workflows orchestrates multi-step agent workflows defined in YAML. Workflows are DAGs of typed steps with data flow via `${{ }}` expressions.
 </objective>

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

@@ -68,7 +68,6 @@
 ## templates/ (33 files)
 
 - `templates/analyzers/base-analyzer.md`
-- `templates/analyzers/macros.md`
 - `templates/analyzers/patterns-task.md`
 - `templates/analyzers/patterns.md`
 - `templates/analyzers/quality-task.md`
@@ -94,6 +93,7 @@
 - `templates/project-inferrer/task.md`
 - `templates/requirements-gatherer/task.md`
 - `templates/researcher/task.md`
+- `templates/shared/macros.md`
 - `templates/spec-implementer/task.md`
 - `templates/synthesizer/system.md`
 - `templates/synthesizer/task.md`

package/templates/shared/macros.md

@@ -0,0 +1,152 @@
+{#- Block rendering macros — one per schema with agent prompt use cases.
+    Import via: {% from "shared/macros.md" import render_project, render_architecture %}
+    Each macro: null guard, markdown heading, field rendering. Missing data renders nothing. -#}
+
+{% macro render_project(data) %}
+{% if data %}
+## Project
+**{{ data.name }}** — {{ data.description }}
+{% if data.core_value %}Core value: {{ data.core_value }}{% endif %}
+{% if data.vision %}
+Vision: {{ data.vision }}{% endif %}
+{% if data.status %}Status: {{ data.status }}{% endif %}
+{% if data.target_users %}
+Target users: {{ data.target_users | join(", ") }}{% endif %}
+{% if data.constraints %}
+### Constraints
+{% for c in data.constraints %}- [{{ c.type }}] {{ c.description }}
+{% endfor %}{% endif %}
+{% if data.scope_boundaries %}
+### Scope
+**In:** {% for s in data.scope_boundaries.in %}{{ s }}{% if not loop.last %}, {% endif %}{% endfor %}
+
+**Out:** {% for s in data.scope_boundaries.out %}{{ s }}{% if not loop.last %}, {% endif %}{% endfor %}
+{% endif %}
+{% if data.goals %}
+### Goals
+{% for g in data.goals %}- **{{ g.id }}**: {{ g.description }}{% if g.success_criteria %} — criteria: {{ g.success_criteria | join("; ") }}{% endif %}
+{% endfor %}{% endif %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_architecture(data) %}
+{% if data %}
+## Architecture
+{% if data.overview %}{{ data.overview }}
+{% endif %}
+{% if data.modules %}
+### Modules
+{% for m in data.modules %}- **{{ m.name }}** (`{{ m.file }}`{% if m.lines %}, {{ m.lines }} lines{% endif %}): {{ m.responsibility }}{% if m.dependencies %} — deps: {{ m.dependencies | join(", ") }}{% endif %}
+{% endfor %}{% endif %}
+{% if data.patterns %}
+### Patterns
+{% for p in data.patterns %}- **{{ p.name }}**: {{ p.description }}{% if p.used_in %} — used in: {{ p.used_in | join(", ") }}{% endif %}
+{% endfor %}{% endif %}
+{% if data.boundaries %}
+### Boundaries
+{% for b in data.boundaries %}- {{ b }}
+{% endfor %}{% endif %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_requirements(data) %}
+{% if data and data.requirements and data.requirements | length > 0 %}
+## Requirements
+{% for r in data.requirements %}- **{{ r.id }}** [{{ r.priority }}] ({{ r.type }}, {{ r.status }}): {{ r.description }}{% if r.acceptance_criteria %}
+  Criteria: {{ r.acceptance_criteria | join("; ") }}{% endif %}
+{% endfor %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_conformance(data) %}
+{% if data and data.principles %}
+## Conformance Reference
+{% if data.name %}**{{ data.name }}**{% endif %}
+{% for p in data.principles %}
+### {{ p.id }}: {{ p.name }}
+{% if p.description %}{{ p.description }}{% endif %}
+{% for r in p.rules %}- **{{ r.id }}**: {{ r.rule }}{% if r.severity %} [{{ r.severity }}]{% endif %}{% if r.check_method %} — check: {{ r.check_method }}{% endif %}
+{% if r.anti_patterns %}  Anti-patterns: {{ r.anti_patterns | join("; ") }}
+{% endif %}{% endfor %}
+{% endfor %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_domain(data) %}
+{% if data and data.entries %}
+## Domain Knowledge
+{% for e in data.entries %}- **{{ e.id }}** [{{ e.category }}]: {{ e.title }}
+  {{ e.content }}{% if e.tags %} — tags: {{ e.tags | join(", ") }}{% endif %}
+{% endfor %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_decisions(data) %}
+{% if data and data.decisions %}
+## Decisions
+{% for d in data.decisions %}- **{{ d.id }}** ({{ d.status }}): {{ d.decision }}
+  Rationale: {{ d.rationale }}{% if d.context %} — context: {{ d.context }}{% endif %}
+{% endfor %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_tasks(data) %}
+{% if data and data.tasks %}
+## Tasks
+{% for t in data.tasks %}- **{{ t.id }}** [{{ t.status }}]: {{ t.description }}{% if t.phase %} (phase {{ t.phase }}){% endif %}{% if t.files %} — files: {{ t.files | join(", ") }}{% endif %}
+{% endfor %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_issues(data) %}
+{% if data and data.issues %}
+## Issues
+{% for i in data.issues %}- **{{ i.id }}** [{{ i.priority }}, {{ i.status }}]: {{ i.title }}
+  {{ i.body }}{% if i.location %} — {{ i.location }}{% endif %}{% if i.package %} ({{ i.package }}){% endif %}
+{% endfor %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_exploration(exploration) %}
+{% if exploration %}
+{% if exploration.files is defined %}
+## Prior Exploration
+{% for file in exploration.files %}- `{{ file.path }}` ({{ file.lines | default("?") }} lines){% if file.exports %}: {{ file.exports | length }} exports{% endif %}
+{% endfor %}{% endif %}
+{% if exploration.types is defined %}
+### Known Types
+{% for t in exploration.types %}- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}{% endif %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_exploration_full(exploration) %}
+{% if exploration %}
+{% if exploration.files is defined %}
+### Files{% if exploration.files | length > 20 %} ({{ exploration.files | length }} total){% endif %}
+{% for file in exploration.files %}- `{{ file.path }}` ({{ file.language | default("unknown") }}, {{ file.lines | default("?") }} lines){% if file.exports %} — {{ file.exports | length }} exports{% endif %}
+{% endfor %}{% endif %}
+{% if exploration.types is defined %}
+### Types
+{% for t in exploration.types %}- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}{% endif %}
+{% if exploration.dependencies is defined %}
+### Dependencies
+{% for d in exploration.dependencies %}- `{{ d.from }}` → `{{ d.to }}` ({{ d.type | default("import") }})
+{% endfor %}{% endif %}
+{% if exploration.entryPoints is defined %}
+### Entry Points
+{% for ep in exploration.entryPoints %}- `{{ ep }}`
+{% endfor %}{% endif %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_gap(gap) %}
+{% if gap %}
+**ID:** {{ gap.id }}
+**Description:** {{ gap.description }}
+**Category:** {{ gap.category | default("unspecified") }}
+**Priority:** {{ gap.priority | default("unspecified") }}
+{% if gap.details %}**Details:** {{ gap.details }}{% endif %}
+{% endif %}
+{% endmacro %}

package/templates/analyzers/macros.md

@@ -1 +0,0 @@
-{% macro cite_instruction(level) %}{% if level == "files" %}Be specific — cite files and directories.{% elif level == "lines" %}Be specific — cite files and line ranges.{% else %}Be specific — cite examples.{% endif %}{% endmacro %}