@davidorex/pi-workflows 0.1.0

package/templates/decomposer/task.md

@@ -0,0 +1,56 @@
+## Decomposition Request
+
+**Gap:** {{ gap.id }} — {{ gap.description }}
+
+## Investigation Findings
+
+**Complexity:** {{ investigation.complexity }}
+**Summary:** {{ investigation.summary }}
+
+### Affected Files
+{% for f in investigation.affected_files %}
+- `{{ f.path }}` — {{ f.role }}: {{ f.current_behavior }}
+{% endfor %}
+
+### Constraints
+{% for c in investigation.constraints %}
+- {{ c }}
+{% endfor %}
+
+### Risks
+{% for r in investigation.risks %}
+- {{ r }}
+{% endfor %}
+
+{% if research %}
+## Research Findings
+
+### Patterns
+{% for p in research.patterns %}
+- **{{ p.name }}**: {{ p.description }} — {{ p.applicability }}
+{% endfor %}
+
+### Recommendations
+{% for r in research.recommendations %}
+- {{ r }}
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+Decompose this gap into implementation specs. Each spec is a unit of work for a single implementing agent.
+
+1. Break the work into the smallest meaningful units
+2. Declare file targets for each spec
+3. Set `depends_on` for specs that must be sequential (shared files, interface dependencies)
+4. Mark `parallel_safe` for specs that can run concurrently
+5. Write acceptance criteria that are verifiable (grep patterns, test commands, not "it works")
+6. Estimate complexity per spec
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/explorer/system.md

@@ -0,0 +1,3 @@
+You are a code explorer. Given a path, produce a comprehensive structural overview as JSON.
+
+Include files with their sizes, exports, imports, and line counts. Identify types, interfaces, and key functions. Map dependencies between files.

package/templates/explorer/task.md

@@ -0,0 +1,9 @@
+Explore the code at `{{ path }}`.
+
+Produce a JSON object with:
+- `files`: array of { path, type, language, lines, exports, imports }
+- `types`: array of { name, file, line, kind, definition }
+- `dependencies`: array of { from, to, type }
+- `entryPoints`: array of file paths that serve as entry points
+
+Write your findings as valid JSON.

package/templates/investigator/task.md

@@ -0,0 +1,30 @@
+## Gap to Investigate
+
+**ID:** {{ gap.id }}
+**Description:** {{ gap.description }}
+**Category:** {{ gap.category }}
+**Priority:** {{ gap.priority }}
+{% if gap.details %}
+**Details:** {{ gap.details }}
+{% endif %}
+
+## Instructions
+
+Produce structured findings for this gap. Scope your investigation to the minimum needed:
+
+1. If the gap names specific files, read those. If not, use `find` or `ls` to identify candidates — don't read file contents unless you need to confirm behavior.
+2. For each affected file: what it does, what needs to change.
+3. List hard constraints (existing tests, interfaces, conventions that must not break).
+4. Note risks only if non-obvious.
+5. Set `needs_research` to true only if the solution requires knowledge you don't have. Most gaps don't.
+6. Complexity: `low` = single concern, mechanical. `medium` = multiple files, design choices. `high` = architectural.
+
+Match your depth to the gap's category and priority. A `cleanup/low` gap needs a few lines of findings, not a codebase survey.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/phase-author/task.md

@@ -0,0 +1,74 @@
+## Intent
+
+{{ intent }}
+
+## Existing Phases
+
+{% for phase in phases %}
+- Phase {{ phase.number }}: {{ phase.name }} ({{ phase.status }})
+{% endfor %}
+
+## Current Architecture
+
+{% for module in architecture.modules %}
+- **{{ module.name }}** ({{ module.file }}, {{ module.lines }} lines): {{ module.responsibility }}
+{% endfor %}
+
+{% if architecture.compilation_pipeline %}
+### Compilation Pipeline
+{% for stage in architecture.compilation_pipeline %}
+{{ loop.index }}. **{{ stage.stage }}**: {{ stage.description }}
+{% endfor %}
+{% endif %}
+
+## Conventions
+
+{% for rule in conventions.rules %}
+- {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
+{% endfor %}
+
+## Current Gaps
+
+{% for gap in gaps %}
+{% if gap.status == "open" %}
+- [{{ gap.priority }}] {{ gap.id }}: {{ gap.description }}
+{% endif %}
+{% endfor %}
+
+## Current Inventory
+
+- Step types: {{ inventory.step_types | length }}
+- Agent specs: {{ inventory.agent_specs | length }}
+- Schemas: {{ inventory.schemas | length }}
+- Tests: {{ inventory.test_count }}
+
+## Instructions
+
+Convert the intent above into a structured phase spec. Read the codebase to understand what exists and what the intent requires.
+
+1. **Determine the phase number** — next after the highest existing phase number
+2. **Write a clear intent statement** — what this phase accomplishes and why
+3. **Define success criteria** — each with a verify_method:
+   - `command`: can be verified by running a shell command (test suite, grep, validate)
+   - `inspect`: requires reading files and assessing content
+   - `human`: requires human judgment
+4. **Decompose into specs** — each spec is a focused unit of work:
+   - Sequential numbering continuing from the last spec in the previous phase
+   - Clear intent per spec
+   - Concrete acceptance criteria (strings, each independently checkable)
+   - Specs should be ordered by dependency — earlier specs don't depend on later ones
+5. **Identify dependencies** — which phase numbers this phase depends on
+6. **List artifacts produced** — file paths this phase will create or modify
+
+### Sizing guidance
+
+- Each spec should be completable by one agent in one context window
+- If a spec needs more than ~5 files changed, split it
+- If a spec has more than ~5 acceptance criteria, it might be doing too much
+- Group related changes (e.g., schema + instance + validation test = one spec)
+
+### Cross-reference gaps
+
+Check if any existing open gaps are addressed by this phase. If so, note that in the spec intent — the gap can be marked resolved when the spec completes.
+
+Produce a JSON object conforming to the phase schema.

package/templates/plan-decomposer/task.md

@@ -0,0 +1,46 @@
+## Phase: {{ phase.name }}
+
+### Intent
+{{ phase.intent }}
+
+### Success Criteria
+{% for criterion in phase.success_criteria %}
+- {{ criterion.criterion }} (verify: {{ criterion.verify_method }})
+{% endfor %}
+
+### Specs
+{% if phase.specs %}
+{% for spec in phase.specs %}
+- **{{ spec.id }}**: {{ spec.name }}
+{% endfor %}
+{% endif %}
+
+### Current Architecture
+{% for module in architecture.modules %}
+- **{{ module.name }}** ({{ module.file }}): {{ module.responsibility }}
+{% endfor %}
+
+### Conventions
+{% for rule in conventions.rules %}
+- {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
+{% endfor %}
+
+## Instructions
+
+Decompose this phase into implementation plans. Each plan should be a focused unit of work that one agent can complete in a single context window.
+
+Before creating plans:
+1. Read source files referenced in the architecture to understand existing patterns
+2. Identify logical boundaries — which specs or features are independent
+3. Determine which plans can run in parallel (independent file sets)
+
+For each plan, produce:
+- **name**: short identifier for the plan
+- **intent**: what this plan accomplishes and why
+- **tasks**: concrete list of things to do (create files, add tests, wire up)
+- **files_to_change**: paths that will be created or modified
+- **acceptance_criteria**: how to know the plan is done
+- **context_needed**: files or modules the implementing agent should read first
+- **parallel_group**: group name — plans in the same group can run concurrently (independent file sets get the same group; dependent plans get different groups)
+
+Output a JSON object with a `plans` array conforming to the plan-breakdown schema.

package/templates/researcher/task.md

@@ -0,0 +1,26 @@
+## Research Request
+
+**Gap:** {{ gap.id }} — {{ gap.description }}
+
+## Questions
+
+{% for q in research_questions %}
+{{ loop.index }}. {{ q }}
+{% endfor %}
+
+## Instructions
+
+For each question:
+1. Answer based on known software engineering patterns, best practices, and established solutions
+2. Rate your confidence: `high` (well-known, widely used), `medium` (established but context-dependent), `low` (best guess)
+3. List sources where possible — documentation, known projects, pattern names
+
+Also identify applicable patterns and concrete recommendations.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/spec-implementer/task.md

@@ -0,0 +1,53 @@
+## Plan: {{ plan.name }}
+
+### Intent
+{{ plan.intent }}
+
+### Tasks
+{% for task in plan.tasks %}
+{{ loop.index }}. {{ task }}
+{% endfor %}
+
+### Files to Change
+{% for f in plan.files_to_change %}
+- `{{ f }}`
+{% endfor %}
+
+### Acceptance Criteria
+{% for criterion in plan.acceptance_criteria %}
+- {{ criterion }}
+{% endfor %}
+
+{% if plan.context_needed %}
+### Context to Read First
+{% for ctx in plan.context_needed %}
+- `{{ ctx }}`
+{% endfor %}
+{% endif %}
+
+### Architecture Reference
+{% for module in architecture.modules %}
+- **{{ module.name }}** ({{ module.file }}): {{ module.responsibility }}
+{% endfor %}
+
+### Conventions
+{% for rule in conventions.rules %}
+- {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
+{% endfor %}
+
+## Instructions
+
+Implement this plan. Follow these steps:
+
+1. **Read context first**: Read the files listed under "Context to Read First" and any related source files to understand existing patterns
+2. **Implement each task**: Work through the task list in order, writing code that follows the project conventions
+3. **Run tests**: After implementation, run the relevant test suite to verify your changes work
+4. **Validate acceptance criteria**: Confirm each acceptance criterion is met
+
+Produce a JSON result conforming to the execution-results schema with:
+- **status**: "complete", "partial", or "failed"
+- **tasks**: array of task results with name, status, files_modified
+- **decisions**: any design decisions made during implementation
+- **issues**: any problems encountered (with severity)
+- **test_count**: number of tests passing after your changes
+- **commit_hash**: empty string (commits are handled externally)

package/templates/synthesizer/system.md

@@ -0,0 +1,3 @@
+You are a report synthesizer. You receive typed analysis data from three independent reviewers (structure, quality, patterns) and produce a unified synthesis as structured JSON.
+
+Every finding must trace to specific data from the input analyses. Do not invent findings that aren't grounded in the input data.

package/templates/synthesizer/task.md

@@ -0,0 +1,38 @@
+Synthesize the following analyses into a unified report.
+
+## Structure Analysis
+Architecture: {{ structure.architecture.organization }}
+Patterns: {% for p in structure.architecture.patterns %}{{ p }}{% if not loop.last %}, {% endif %}{% endfor %}
+
+### Modules
+{% for m in structure.modules %}
+- **{{ m.name }}**: {{ m.responsibility }} ({{ m.files | length }} files)
+{% endfor %}
+
+### Dependencies
+{% for d in structure.dependencies %}
+- `{{ d.from }}` → `{{ d.to }}` ({{ d.type }})
+{% endfor %}
+
+## Quality Analysis
+{% for c in quality.concerns %}
+- [{{ c.severity }}] {{ c.description }}{% if c.file %} in `{{ c.file }}`{% endif %}
+{% endfor %}
+
+### Test Coverage
+- Tested: {% for t in quality.testCoverage.tested %}`{{ t }}`{% if not loop.last %}, {% endif %}{% endfor %}
+- Untested: {% for t in quality.testCoverage.untested %}`{{ t }}`{% if not loop.last %}, {% endif %}{% endfor %}
+
+### Maintainability: {{ quality.maintainability.score }}
+
+## Pattern Analysis
+{% for p in patterns.patterns %}
+- **{{ p.name }}**: {{ p.usage }}{% if not p.correct %} ⚠️{% endif %}
+{% endfor %}
+
+### Recommendations
+{% for r in patterns.recommendations %}
+- [{{ r.priority }}] **{{ r.pattern }}**: {{ r.suggestion }}
+{% endfor %}
+
+Write your synthesis as JSON conforming to the output schema.

package/templates/verifier/task.md

@@ -0,0 +1,57 @@
+You are verifying the output of a prior step against declared success criteria.
+
+## Success Criteria
+
+{% for criterion in criteria %}
+- {{ criterion }}
+{% endfor %}
+
+## Step Output to Verify
+
+```json
+{{ step_output | dump(2) }}
+```
+
+{% if files_to_check %}
+## Files to Check
+
+{% for f in files_to_check %}
+- `{{ f }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+For each criterion, choose the appropriate verification method and execute it:
+
+1. **command** — Run a shell command (test suite, build, lint) and report exit code + output as evidence
+2. **grep** — Search for specific patterns in files and report matches as evidence
+3. **inspect** — Read files and assess their content (use your judgment)
+4. **human** — Flag items that require human eyes and explain why automation cannot verify them
+
+### Process
+
+1. Evaluate each success criterion using the most appropriate verify method
+2. For `command` criteria: actually run the command and capture the output
+3. For `grep` criteria: search the relevant files and report what you find
+4. For `inspect` criteria: read the files and assess whether they meet the criterion
+5. For `human` criteria: describe what needs to be checked and why it needs a person
+6. Build truth claims from your observations, marking each as `verified`, `failed`, or `uncertain`
+7. Check that all referenced artifacts exist and are substantive (not stubs)
+8. Compute an overall score as "N/M" where N = passed criteria, M = total criteria
+9. Set status: `passed` if all criteria pass, `gaps_found` if any fail, `human_needed` if any require human review
+
+### Output Format
+
+Produce JSON conforming to the verifier-output schema with these fields:
+
+- `status`: "passed" | "gaps_found" | "human_needed"
+- `score`: "N/M" format
+- `truths[]`: observable claims with status and evidence
+- `criteria_results[]`: one entry per criterion with verify_method, status, expected/actual outcome, evidence
+- `artifacts[]`: (optional) file paths checked with existence/substance status
+- `requirements_coverage[]`: (optional) requirement satisfaction mapping
+- `human_verification[]`: (optional) items needing human review
+- `gaps[]`: (optional) failed or uncertain truths with reasons
+
+Be thorough. Run actual commands. Read actual files. Report what you observe, not what you assume.

package/workflows/create-phase.workflow.yaml

@@ -0,0 +1,67 @@
+name: create-phase
+description: Convert unstructured intent into a structured phase spec
+version: "1"
+
+input:
+  type: object
+  required: [intent]
+  properties:
+    intent:
+      type: string
+      description: Unstructured intent from conversation — what needs to be built and why
+
+steps:
+  load-context:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        import { readBlock } from './src/block-api.ts';
+        import { PROJECT_DIR } from './src/project-dir.ts';
+        import path from 'path';
+        const phasesDir = path.join(PROJECT_DIR, 'phases');
+        const phases = fs.readdirSync(phasesDir)
+          .filter(f => f.endsWith('.json'))
+          .map(f => JSON.parse(fs.readFileSync(path.join(phasesDir, f), 'utf8')));
+        const arch = readBlock('.', 'architecture');
+        const conv = readBlock('.', 'conventions');
+        const gapsData = readBlock('.', 'gaps');
+        const inv = readBlock('.', 'inventory');
+        console.log(JSON.stringify({ phases, architecture: arch, conventions: conv, gaps: gapsData.gaps, inventory: inv }));
+      "
+    output:
+      format: json
+
+  author:
+    agent: phase-author
+    input:
+      intent: "${{ input.intent }}"
+      phases: "${{ steps.load-context.output.phases }}"
+      architecture: "${{ steps.load-context.output.architecture }}"
+      conventions: "${{ steps.load-context.output.conventions }}"
+      gaps: "${{ steps.load-context.output.gaps }}"
+      inventory: "${{ steps.load-context.output.inventory }}"
+    output:
+      format: json
+      schema: ../../.project/schemas/phase.schema.json
+
+  write-phase:
+    command: |
+      node --experimental-strip-types -e "
+        import fs from 'fs';
+        import { validateFromFile } from './src/schema-validator.ts';
+        const phase = JSON.parse(process.argv[1]);
+        validateFromFile('.project/schemas/phase.schema.json', phase, 'phase');
+        const filename = '.project/phases/' + String(phase.number).padStart(2, '0') + '-' + phase.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/-+$/, '') + '.json';
+        fs.writeFileSync(filename, JSON.stringify(phase, null, 2) + '\n');
+        console.log(JSON.stringify({ path: filename, phase_number: phase.number, spec_count: phase.specs.length }));
+      " '${{ steps.author.output | json }}'
+    output:
+      format: json
+
+completion:
+  message: |
+    Phase ${{ steps.write-phase.output.phase_number }} created at ${{ steps.write-phase.output.path }}
+    Contains ${{ steps.write-phase.output.spec_count }} specs.
+  include:
+    - steps.author.output.success_criteria
+    - steps.author.output.specs

package/workflows/do-gap.workflow.yaml

@@ -0,0 +1,153 @@
+name: do-gap
+description: Standard path from gap to implementation — investigate, research, decompose, implement, verify, route
+version: "1"
+
+input:
+  type: object
+  required: [gap_id]
+  properties:
+    gap_id:
+      type: string
+      description: ID of the gap to work on
+      source:
+        file: .project/gaps.json
+        array: gaps
+        filter: { status: open }
+        label: id
+        value: id
+
+steps:
+  load:
+    command: |
+      node --experimental-strip-types -e "
+        import { readBlock } from './src/block-api.ts';
+        const gapId = process.argv[1];
+        const data = readBlock('.', 'gaps');
+        const gap = data.gaps.find(g => g.id === gapId);
+        if (!gap) { console.error('Gap not found: ' + gapId); process.exit(1); }
+        if (gap.status === 'resolved') { console.error('Gap already resolved: ' + gapId); process.exit(1); }
+        console.log(JSON.stringify({ gap }));
+      " '${{ input.gap_id }}'
+    output:
+      format: json
+
+  investigate:
+    agent: investigator
+    input:
+      gap: "${{ steps.load.output.gap }}"
+    output:
+      format: json
+      schema: schemas/investigation-findings.schema.json
+
+  research:
+    when: "${{ steps.investigate.output.needs_research }}"
+    agent: researcher
+    input:
+      gap: "${{ steps.load.output.gap }}"
+      research_questions: "${{ steps.investigate.output.research_questions }}"
+    output:
+      format: json
+      schema: schemas/research-findings.schema.json
+
+  decompose:
+    agent: decomposer
+    input:
+      gap: "${{ steps.load.output.gap }}"
+      investigation: "${{ steps.investigate.output }}"
+      research: "${{ steps.research.output }}"
+    output:
+      format: json
+      schema: schemas/decomposition-specs.schema.json
+
+  implement:
+    forEach: "${{ steps.decompose.output.specs }}"
+    as: spec
+    agent: spec-implementer
+    input:
+      spec: "${{ spec }}"
+      gap: "${{ steps.load.output.gap }}"
+      investigation: "${{ steps.investigate.output }}"
+    retry:
+      maxAttempts: 2
+      onExhausted: fail
+    output:
+      format: json
+      schema: schemas/execution-results.schema.json
+
+  verify:
+    command: |
+      node --experimental-strip-types -e "
+        import { execSync } from 'child_process';
+        const errors = [];
+
+        // Run tests
+        try {
+          execSync('node --experimental-strip-types --test src/*.test.ts', { stdio: 'pipe', timeout: 120000 });
+        } catch (e) {
+          errors.push('Tests failed: ' + (e.stderr?.toString().slice(-500) || 'unknown error'));
+        }
+
+        // Run linter on changed files
+        try {
+          const diff = execSync('git diff --name-only HEAD', { encoding: 'utf8' }).trim();
+          const srcFiles = diff.split('\n').filter(f => f.startsWith('src/') && f.endsWith('.ts') && !f.endsWith('.test.ts'));
+          for (const f of srcFiles) {
+            try {
+              execSync('/Users/david/Projects/pi-extension-linter/pi-extension-lint.sh ' + f, { stdio: 'pipe' });
+            } catch (e) {
+              const stderr = e.stderr?.toString() || e.stdout?.toString() || '';
+              if (stderr.includes('error')) errors.push('Lint errors in ' + f);
+            }
+          }
+        } catch {}
+
+        // Validate blocks
+        try {
+          const fs = await import('fs');
+          const schemasDir = '.project/schemas';
+          const schemas = fs.readdirSync(schemasDir).filter(f => f.endsWith('.schema.json'));
+          for (const s of schemas) {
+            const blockName = s.replace('.schema.json', '');
+            const blockPath = '.project/' + blockName + '.json';
+            if (fs.existsSync(blockPath)) {
+              try {
+                execSync('node --experimental-strip-types -e \"import{validateFromFile}from' + String.fromCharCode(39) + './src/schema-validator.ts' + String.fromCharCode(39) + ';import fs from' + String.fromCharCode(39) + 'fs' + String.fromCharCode(39) + ';validateFromFile(' + String.fromCharCode(39) + schemasDir + '/' + s + String.fromCharCode(39) + ',JSON.parse(fs.readFileSync(' + String.fromCharCode(39) + blockPath + String.fromCharCode(39) + ',' + String.fromCharCode(39) + 'utf8' + String.fromCharCode(39) + ')),' + String.fromCharCode(39) + blockName + String.fromCharCode(39) + ')\"', { stdio: 'pipe' });
+              } catch { errors.push('Block validation failed: ' + blockPath); }
+            }
+          }
+        } catch {}
+
+        const passed = errors.length === 0;
+        console.log(JSON.stringify({ status: passed ? 'passed' : 'failed', errors, passed }));
+      "
+    output:
+      format: json
+
+  route:
+    when: "${{ steps.verify.output.passed }}"
+    command: |
+      node --experimental-strip-types -e "
+        import { updateItemInBlock } from './src/block-api.ts';
+        const gapId = process.argv[1];
+        updateItemInBlock('.', 'gaps', 'gaps',
+          (g) => g.id === gapId,
+          { status: 'resolved', resolved_by: 'do-gap-workflow' }
+        );
+        console.log(JSON.stringify({ routed: true, gap_id: gapId, status: 'resolved' }));
+      " '${{ input.gap_id }}'
+    output:
+      format: json
+
+  check:
+    when: "${{ steps.route.output.routed }}"
+    gate:
+      check: "test '${{ steps.verify.output.status }}' = 'passed'"
+      onFail: fail
+
+completion:
+  message: |
+    Gap ${{ input.gap_id }} — ${{ steps.verify.output.status }}
+    Investigation complexity: ${{ steps.investigate.output.complexity }}
+    Specs implemented: ${{ steps.decompose.output.specs | length }}
+  include:
+    - steps.verify.output