@davidorex/pi-workflows 0.14.6 → 0.28.0

package/templates/audit-fixer/task.md

@@ -1,67 +0,0 @@
-## Audit Findings to Fix
-
-### Principle: {{ task.principle }}
-### Category: {{ task.category }}
-### Severity: {{ task.severity }}
-
-### Findings
-
-{% for finding in task.findings %}
-#### {{ finding.id }}: {{ finding.description }}
-
-{% for loc in finding.locations %}
-- `{{ loc.file }}` lines {{ loc.lines | join(', ') }}
-{% endfor %}
-
-{% if finding.fix %}
-**Fix**: {{ finding.fix.suggestion }}
-{% if finding.fix.verify_method == "grep" %}
-**Verify**: pattern `{{ finding.fix.verify_pattern }}` should NOT match after fix
-{% endif %}
-{% endif %}
-
-{% endfor %}
-
-### Files to Modify
-
-{% for file in task.files %}
-- `{{ file }}`
-{% endfor %}
-
-### Acceptance Criteria
-
-{% for criterion in task.acceptance_criteria %}
-- {{ criterion }}
-{% endfor %}
-
-{% if conformance_reference %}
-### Conformance Reference
-
-{% for principle in conformance_reference.principles %}
-{% if principle.id == task.principle.split(':')[0] %}
-#### {{ principle.name }}
-
-{{ principle.description }}
-
-{% for rule in principle.rules %}
-- **{{ rule.id }}**: {{ rule.rule }}
-{% if rule.examples %}
-  - Correct: `{{ rule.examples[0] }}`
-{% endif %}
-{% if rule.anti_patterns %}
-  - Wrong: `{{ rule.anti_patterns[0] }}`
-{% endif %}
-{% endfor %}
-{% endif %}
-{% endfor %}
-{% endif %}
-
-## Instructions
-
-1. Read the files listed above to understand the current code
-2. Fix each finding according to the fix suggestion
-3. Ensure fixes follow the conformance reference principles
-4. Run the test suite: `node --experimental-strip-types --test src/*.test.ts`
-5. Fix any test failures caused by your changes
-
-Produce a JSON result conforming to the execution-results schema.

package/templates/audit-results-router/task.md

@@ -1,37 +0,0 @@
-Review the audit fix results and produce a routing manifest.
-
-## Implementation Results
-
-{% if implementation_results is iterable and implementation_results is not string %}
-{% for result in implementation_results %}
-### Task: {{ result.spec_name | default(result.name | default("unnamed")) }}
-
-- Status: {{ result.status | default("unknown") }}
-{% if result.decisions %}
-- Decisions: {{ result.decisions | length }}
-{% endif %}
-{% if result.issues %}
-- Issues flagged: {{ result.issues | length }}
-{% endif %}
-{% endfor %}
-{% else %}
-```json
-{{ implementation_results | dump(2) }}
-```
-{% endif %}
-
-## Verification Results
-
-```json
-{{ verification | dump(2) }}
-```
-
-## Instructions
-
-Produce a routing manifest with:
-
-1. **decisions** — validated decisions from implementation results (with complete id, description, rationale fields)
-2. **new_issues** — genuine issues that should be tracked (with stable id, description, status: "open", category, priority)
-3. **summary** — accurate summary of what was completed, what failed, what needs inspection
-
-Only include items that are well-formed and represent genuine project artifacts. Do not route items that are missing required fields or describe hypothetical concerns.

package/templates/decomposer/task.md

@@ -1,56 +0,0 @@
-## 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

@@ -1,3 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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/gap-identifier/task.md

@@ -1,103 +0,0 @@
-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 exploration.files is defined %}
-### Files ({{ exploration.files | length }} total)
-{% 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 %}
-
-## 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/gap-resolution-assessor/task.md

@@ -1,48 +0,0 @@
-Assess whether the implementation resolves this gap.
-
-## Gap
-
-**ID**: {{ gap.id }}
-**Description**: {{ gap.description }}
-**Category**: {{ gap.category | default("unspecified") }}
-**Priority**: {{ gap.priority | default("unspecified") }}
-
-## Investigation Findings
-
-```json
-{{ investigation | dump(2) }}
-```
-
-## Implementation Results
-
-{% if implementation_results is iterable and implementation_results is not string %}
-{% for result in implementation_results %}
-### Spec: {{ result.spec_name | default("unnamed") }}
-- Status: {{ result.status | default("unknown") }}
-- Files changed: {{ result.files_changed | default([]) | join(", ") }}
-{% if result.commit_hash %}- Commit: {{ result.commit_hash }}{% endif %}
-{% endfor %}
-{% else %}
-```json
-{{ implementation_results | dump(2) }}
-```
-{% endif %}
-
-## Check Results
-
-- Status: {{ check_results.status }}
-{% if check_results.errors | length > 0 %}
-- Errors:
-{% for err in check_results.errors %}
-  - {{ err }}
-{% endfor %}
-{% endif %}
-
-## Instructions
-
-1. Read the gap description above. Understand what root cause it identifies.
-2. Examine the implementation results — what files were changed and what was the stated work.
-3. Run `git diff HEAD~{{ implementation_results | length | default(1) }}` (or appropriate range) to see actual code changes.
-4. Judge: do the code changes address the root cause described in the gap?
-5. If tests failed or lint errors exist, the gap is NOT resolved regardless of code quality.
-6. Produce your assessment as JSON.

package/templates/handoff-writer/task.md

@@ -1,101 +0,0 @@
-Capture a handoff snapshot for the project at `{{ path }}`.
-
-## Current Project State
-
-{% if project_state.blocks_status %}
-### Block Availability
-
-| Block | Available |
-|-------|-----------|
-{% for name, available in project_state.blocks_status %}
-| {{ name }} | {{ "yes" if available else "NO — absent" }} |
-{% endfor %}
-{% endif %}
-
-{% if project_state.project %}
-### 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 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 %}
-### Block Summaries
-{% for block in project_state.blockSummaries %}
-- **{{ block.name }}**: {{ block.count | default("?") }} entries
-{% endfor %}
-{% endif %}
-
-{% if project_state.gaps %}
-### 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 %}
-### 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 %}
-### 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 }}
-```

package/templates/investigator/task.md

@@ -1,30 +0,0 @@
-## 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

@@ -1,82 +0,0 @@
-## Intent
-
-{{ intent }}
-
-## Existing Phases
-
-{% for phase in phases %}
-- Phase {{ phase.number }}: {{ phase.name }} ({{ phase.status }})
-{% endfor %}
-
-{% if architecture and architecture.modules %}
-## 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 %}
-{% endif %}
-
-{% if conventions and conventions.rules %}
-## Conventions
-
-{% for rule in conventions.rules %}
-- {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
-{% endfor %}
-{% endif %}
-
-{% if gaps and gaps.gaps %}
-## Current Gaps
-
-{% for gap in gaps.gaps %}
-{% if gap.status == "open" %}
-- [{{ gap.priority }}] {{ gap.id }}: {{ gap.description }}
-{% endif %}
-{% endfor %}
-{% endif %}
-
-{% if inventory %}
-## Current Inventory
-
-{% if inventory.step_types %}- Step types: {{ inventory.step_types | length }}
-{% endif %}{% if inventory.agent_specs %}- Agent specs: {{ inventory.agent_specs | length }}
-{% endif %}{% if inventory.schemas %}- Schemas: {{ inventory.schemas | length }}
-{% endif %}{% if inventory.test_count is defined %}- Tests: {{ inventory.test_count }}
-{% endif %}{% endif %}
-
-## 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-creator/task.md

@@ -1,143 +0,0 @@
-## Project Identity
-
-**Name:** {{ project.name }}
-**Description:** {{ project.description }}
-**Core Value:** {{ project.core_value }}
-**Status:** {{ project.status }}
-{% if project.stack %}
-
-### Stack
-{% for item in project.stack %}
-- {{ item }}
-{% endfor %}
-{% endif %}
-
-## Requirements Summary
-
-{% for req in requirements.requirements %}
-{% if req.priority == "must" %}
-- **{{ req.id }}** [must/{{ req.type }}]: {{ req.description }}
-{% endif %}
-{% endfor %}
-{% for req in requirements.requirements %}
-{% if req.priority == "should" %}
-- **{{ req.id }}** [should/{{ req.type }}]: {{ req.description }}
-{% endif %}
-{% endfor %}
-{% for req in requirements.requirements %}
-{% if req.priority == "could" %}
-- **{{ req.id }}** [could/{{ req.type }}]: {{ req.description }}
-{% endif %}
-{% endfor %}
-
-## Architecture
-
-**Overview:** {{ architecture.overview }}
-
-### Modules
-{% for module in architecture.modules %}
-- **{{ module.name }}** (`{{ module.file }}`): {{ module.responsibility }}{% if module.dependencies %} [depends: {{ module.dependencies | join(", ") }}]{% endif %}
-{% endfor %}
-
-### Patterns
-{% for pattern in architecture.patterns %}
-- **{{ pattern.name }}**: {{ pattern.description }} (used in: {{ pattern.used_in | join(", ") }})
-{% endfor %}
-
-### Boundaries
-{% for boundary in architecture.boundaries %}
-- {{ boundary }}
-{% endfor %}
-
-{% if existing_files %}
-## Existing Project Files
-
-The project directory already contains these files:
-{% for file in existing_files %}
-- {{ file }}
-{% endfor %}
-
-Account for existing structure — do not plan to recreate files that already exist unless they need modification.
-{% endif %}
-
-## Instructions
-
-Create implementation phases and tasks that build this project incrementally. The plan should take the project from its current state ({{ project.status }}) to a working system that satisfies all "must" requirements and addresses "should" requirements.
-
-### Phase guidelines
-
-1. **Phase 1** — Foundation: project structure, core module scaffolding, configuration, initial tests
-2. **Phase 2+** — Layer functionality in priority order: "must" requirements first, then "should"
-3. **Final phase** — Integration, documentation, and verification
-4. Each phase should represent a meaningful milestone — the project is more capable after each phase
-5. A phase with more than 8-10 tasks is likely too large — split it
-
-### For each phase, provide:
-
-- **number** — sequential starting at 1
-- **name** — short descriptive name
-- **intent** — what this phase accomplishes and why it comes at this point
-- **goal** — what is true after this phase that was not true before
-- **status** — `"planned"`
-- **success_criteria** — array of `{ criterion, verify_method }` (verify_method: "command", "inspect", or "test")
-- **dependencies** — array of phase numbers this depends on (empty for phase 1)
-- **inputs** — what this phase needs from prior phases or external sources
-- **outputs** — what this phase produces for later phases or users
-
-### For each task, provide:
-
-- **id** — unique, formatted as T-001, T-002, etc.
-- **description** — clear statement of what to do
-- **status** — `"planned"`
-- **phase** — phase number this belongs to
-- **files** — array of file paths this task creates or modifies
-- **acceptance_criteria** — array of specific, verifiable statements
-- **depends_on** — array of task IDs this depends on (empty if none)
-- **notes** — optional: any implementation guidance or caveats
-
-### Task sizing
-
-- Each task should be completable by one agent in one context window
-- A task touching more than 3-5 files likely needs splitting
-- A task with more than 5 acceptance criteria may be doing too much
-- Group related changes: schema + implementation + test = one task when files are few
-
-### Traceability
-
-- Every "must" requirement should be addressed by at least one task
-- Every task's files should map to at least one architecture module
-- Note requirement IDs in task descriptions or notes where the mapping is clear
-
-### Output format
-
-Produce a single JSON object with two arrays:
-
-```json
-{
-  "phases": [
-    {
-      "number": 1,
-      "name": "string",
-      "intent": "string",
-      "goal": "string",
-      "status": "planned",
-      "success_criteria": [{ "criterion": "string", "verify_method": "command" }],
-      "dependencies": [],
-      "inputs": ["string"],
-      "outputs": ["string"]
-    }
-  ],
-  "tasks": [
-    {
-      "id": "T-001",
-      "description": "string",
-      "status": "planned",
-      "phase": 1,
-      "files": ["src/file.ts"],
-      "acceptance_criteria": ["string"],
-      "depends_on": [],
-      "notes": "optional string"
-    }
-  ]
-}
-```