@davidorex/pi-workflows 0.2.0 → 0.3.1

package/templates/project-inferrer/task.md

@@ -0,0 +1,56 @@
+Infer the project identity for the project at `{{ path }}`.
+
+## Codebase Analysis
+
+{% if analysis.files is defined %}
+### Files ({{ analysis.files | length }} total)
+{% for file in analysis.files | batch(20) | first %}
+- `{{ file.path }}` ({{ file.language | default("unknown") }})
+{% endfor %}
+{% if analysis.files | length > 20 %}
+... and {{ analysis.files | length - 20 }} more files
+{% endif %}
+{% endif %}
+
+{% if analysis.entryPoints is defined %}
+### Entry Points
+{% for ep in analysis.entryPoints %}
+- `{{ ep }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+Read project metadata and documentation to determine the project's identity. Start with:
+- README.md (or equivalent)
+- Package manifest (package.json, Cargo.toml, pyproject.toml, go.mod, etc.)
+- CLAUDE.md or similar project instructions if present
+- CI/CD configuration if present
+
+Produce a project identity block:
+
+1. **name** — the project's canonical name (from package manifest, not directory name)
+2. **description** — concise summary of what the project does (2-3 sentences max)
+3. **core_value** — single sentence: why does this project exist? What value does it provide?
+4. **target_users** — who uses this? (e.g., "TypeScript developers", "DevOps engineers", "data scientists")
+5. **constraints** — each with `type` and `description`:
+   - Runtime constraints (Node.js version, browser support, etc.)
+   - Language constraints (TypeScript strict mode, ESM-only, etc.)
+   - Compatibility constraints (API stability, backward compat, etc.)
+6. **scope_boundaries**:
+   - `in`: what the project explicitly does
+   - `out`: what the project explicitly does not do (deferred or excluded)
+7. **goals** — each with `id`, `description`, and optional `success_criteria` array
+   - Only include goals evidenced by the codebase (README roadmap, issues, TODO markers)
+8. **status** — one of: inception, planning, development, maintenance, complete
+   - Infer from: version maturity, commit recency, test coverage, presence of CI
+9. **repository** — repository URL if discoverable from package manifest or git remote
+10. **stack** — primary technology choices only (language, framework, key libraries — not every dependency)
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/requirements-gatherer/task.md

@@ -0,0 +1,90 @@
+## Project Identity
+
+**Name:** {{ project.name }}
+**Description:** {{ project.description }}
+**Core Value:** {{ project.core_value }}
+
+### Target Users
+{% for user in project.target_users %}
+- {{ user }}
+{% endfor %}
+
+### 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 %}
+
+### Goals
+{% for goal in project.goals %}
+- **{{ goal.id }}**: {{ goal.description }}
+  {% for criterion in goal.success_criteria %}- {{ criterion }}
+  {% endfor %}
+{% endfor %}
+
+{% if vision %}
+## Original Vision
+
+{{ vision }}
+{% endif %}
+
+## Instructions
+
+Derive requirements from the project identity above. Produce a comprehensive but proportionate set of requirements covering what the system must do (functional), quality attributes it must exhibit (non-functional), hard limits it must respect (constraint), and external connections it must support (integration).
+
+### For each requirement, provide:
+
+1. **id** — unique, formatted as REQ-001, REQ-002, etc.
+2. **description** — clear statement of what is required
+3. **type** — one of: `functional`, `non-functional`, `constraint`, `integration`
+4. **status** — set to `"proposed"` for all
+5. **priority** — MoSCoW: `must`, `should`, `could`, `wont`
+6. **acceptance_criteria** — array of specific, verifiable statements
+7. **source** — set to `"agent"` for all
+8. **depends_on** — array of other requirement IDs this depends on (empty array if none)
+
+### Priority guidance
+
+- **must**: the project fails without this — directly tied to core_value and essential goals
+- **should**: important for target users but the project could ship a minimal version without it
+- **could**: enhances the experience but is clearly secondary
+- **wont**: explicitly excluded — derive these from scope_boundaries.out
+
+### Coverage expectations
+
+- Every goal should map to at least one "must" requirement
+- Every constraint should appear as a "constraint" type requirement
+- Include at least one non-functional requirement for each quality attribute the project implies (performance, security, usability, reliability, etc. — only those that are relevant)
+- Include "wont" requirements for major items in scope_boundaries.out
+
+### Output format
+
+Produce a single JSON object with a `requirements` array:
+
+```json
+{
+  "requirements": [
+    {
+      "id": "REQ-001",
+      "description": "string",
+      "type": "functional",
+      "status": "proposed",
+      "priority": "must",
+      "acceptance_criteria": ["string"],
+      "source": "agent",
+      "depends_on": []
+    }
+  ]
+}
+```

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

@@ -0,0 +1,94 @@
+name: analyze-existing-project
+description: Analyze an existing codebase, infer architecture and conventions, identify gaps, create planning state
+version: "1"
+
+input:
+  type: object
+  properties:
+    path:
+      type: string
+      description: Path to analyze (defaults to current directory)
+
+steps:
+  explore:
+    agent: code-explorer
+    input:
+      path: ${{ input.path }}
+
+  # These two analyze concurrently — no mutual dependencies, both depend only on explore
+  analyze-structure:
+    agent: structure-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+    output:
+      format: json
+
+  analyze-patterns:
+    agent: pattern-analyzer
+    input:
+      exploration: ${{ steps.explore.textOutput }}
+      path: ${{ input.path }}
+    output:
+      format: json
+
+  infer-architecture:
+    agent: architecture-inferrer
+    input:
+      analysis:
+        structure: ${{ steps.analyze-structure.output }}
+        patterns: ${{ steps.analyze-patterns.output }}
+      path: ${{ input.path }}
+    output:
+      format: json
+      schema: block:architecture
+    retry:
+      maxAttempts: 2
+
+  infer-project:
+    agent: project-inferrer
+    input:
+      analysis:
+        structure: ${{ steps.analyze-structure.output }}
+        patterns: ${{ steps.analyze-patterns.output }}
+      path: ${{ input.path }}
+    output:
+      format: json
+      schema: block:project
+    retry:
+      maxAttempts: 2
+
+  identify-gaps:
+    agent: gap-identifier
+    input:
+      analysis:
+        structure: ${{ steps.analyze-structure.output }}
+        patterns: ${{ steps.analyze-patterns.output }}
+      architecture: ${{ steps.infer-architecture.output }}
+      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. 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
+    **Gaps:** ${{ steps.identify-gaps.output.gaps | length }} identified
+
+    Use `/project status` to see the full state. Use `/project validate` to check cross-block references.

package/workflows/create-handoff.workflow.yaml

@@ -0,0 +1,66 @@
+name: create-handoff
+description: Capture current work context for session resume
+version: "1"
+
+steps:
+  load-state:
+    command: |
+      node -e "
+        const fs = require('fs');
+        const path = require('path');
+        const projectDir = '.project';
+        const state = {};
+
+        // Read project identity
+        try { state.project = JSON.parse(fs.readFileSync(path.join(projectDir, 'project.json'), 'utf-8')); } catch {}
+
+        // Read phase files
+        try {
+          const phasesDir = path.join(projectDir, 'phases');
+          state.phases = fs.readdirSync(phasesDir).filter(f => f.endsWith('.json')).map(f => {
+            try { return JSON.parse(fs.readFileSync(path.join(phasesDir, f), 'utf-8')); } catch { return null; }
+          }).filter(Boolean);
+        } catch { state.phases = []; }
+
+        // Read block summaries
+        try {
+          state.gaps = JSON.parse(fs.readFileSync(path.join(projectDir, 'gaps.json'), 'utf-8'));
+        } catch {}
+        try {
+          state.decisions = JSON.parse(fs.readFileSync(path.join(projectDir, 'decisions.json'), 'utf-8'));
+        } catch {}
+        try {
+          state.tasks = JSON.parse(fs.readFileSync(path.join(projectDir, 'tasks.json'), 'utf-8'));
+        } catch {}
+
+        // Recent git activity
+        try {
+          const { execSync } = require('child_process');
+          state.recent_commits = execSync('git log --oneline -10', { encoding: 'utf-8' }).trim().split('\n');
+          state.changed_files = execSync('git diff --name-only HEAD~3 2>/dev/null || echo \"\"', { encoding: 'utf-8' }).trim().split('\n').filter(Boolean);
+        } catch { state.recent_commits = []; state.changed_files = []; }
+
+        console.log(JSON.stringify(state));
+      "
+    output:
+      format: json
+
+  capture:
+    agent: handoff-writer
+    input:
+      project_state: ${{ steps.load-state.output }}
+      path: "."
+    output:
+      format: json
+      schema: block:handoff
+    retry:
+      maxAttempts: 2
+
+artifacts:
+  handoff:
+    path: .project/handoff.json
+    from: steps.capture.output
+
+completion:
+  message: |
+    Handoff captured to .project/handoff.json. Resume context is available for the next session.

package/workflows/create-phase.workflow.yaml

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

package/workflows/do-gap.workflow.yaml

@@ -37,7 +37,7 @@ steps:
       gap: "${{ steps.load.output.gap }}"
     output:
       format: json
-      schema: schemas/investigation-findings.schema.json
+      schema: ../schemas/investigation-findings.schema.json
 
   research:
     when: "${{ steps.investigate.output.needs_research }}"
@@ -47,7 +47,7 @@ steps:
       research_questions: "${{ steps.investigate.output.research_questions }}"
     output:
       format: json
-      schema: schemas/research-findings.schema.json
+      schema: ../schemas/research-findings.schema.json
 
   decompose:
     agent: decomposer
@@ -57,7 +57,7 @@ steps:
       research: "${{ steps.research.output }}"
     output:
       format: json
-      schema: schemas/decomposition-specs.schema.json
+      schema: ../schemas/decomposition-specs.schema.json
 
   implement:
     forEach: "${{ steps.decompose.output.specs }}"
@@ -72,7 +72,7 @@ steps:
       onExhausted: fail
     output:
       format: json
-      schema: schemas/execution-results.schema.json
+      schema: ../schemas/execution-results.schema.json
 
   verify:
     command: |

package/workflows/fix-audit.workflow.yaml

@@ -87,7 +87,7 @@ steps:
       conformance_reference: "${{ steps.load.output.conformance_reference }}"
     output:
       format: json
-      schema: schemas/execution-results.schema.json
+      schema: ../schemas/execution-results.schema.json
       path: .project/fix-audit-results.json
 
   route-results:

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

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

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

@@ -0,0 +1,81 @@
+name: init-new-project
+description: Bootstrap a new project from vision through requirements to initial plan
+version: "1"
+
+input:
+  type: object
+  required: [vision]
+  properties:
+    vision:
+      type: string
+      description: What the project aims to achieve, who it's for, and why it matters
+
+steps:
+  define-identity:
+    agent: project-definer
+    input:
+      vision: ${{ input.vision }}
+    output:
+      format: json
+      schema: block:project
+    retry:
+      maxAttempts: 2
+
+  gather-requirements:
+    agent: requirements-gatherer
+    input:
+      project: ${{ steps.define-identity.output }}
+      vision: ${{ input.vision }}
+    output:
+      format: json
+      schema: block:requirements
+    retry:
+      maxAttempts: 2
+
+  design-architecture:
+    agent: architecture-designer
+    input:
+      project: ${{ steps.define-identity.output }}
+      requirements: ${{ steps.gather-requirements.output }}
+    output:
+      format: json
+      schema: block:architecture
+    retry:
+      maxAttempts: 2
+
+  create-plan:
+    agent: plan-creator
+    input:
+      project: ${{ steps.define-identity.output }}
+      requirements: ${{ steps.gather-requirements.output }}
+      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. 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
+    **Architecture:** ${{ steps.design-architecture.output.modules | length }} modules
+    **Plan:** phases and tasks created
+
+    Use `/project status` to see the full state. Use `/project validate` to check cross-block references.

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

@@ -0,0 +1,59 @@
+name: plan-from-requirements
+description: Decompose accepted requirements into phases and tasks
+version: "1"
+
+steps:
+  load-context:
+    command: |
+      node -e "
+        const fs = require('fs');
+        const path = require('path');
+        const projectDir = '.project';
+        const context = {};
+
+        // Read requirements
+        try { context.requirements = JSON.parse(fs.readFileSync(path.join(projectDir, 'requirements.json'), 'utf-8')); } catch { context.requirements = { requirements: [] }; }
+
+        // Read architecture
+        try { context.architecture = JSON.parse(fs.readFileSync(path.join(projectDir, 'architecture.json'), 'utf-8')); } catch { context.architecture = null; }
+
+        // Read project identity
+        try { context.project = JSON.parse(fs.readFileSync(path.join(projectDir, 'project.json'), 'utf-8')); } catch { context.project = null; }
+
+        // Read existing phases
+        try {
+          const phasesDir = path.join(projectDir, 'phases');
+          context.existing_phases = fs.readdirSync(phasesDir).filter(f => f.endsWith('.json')).map(f => {
+            try { return JSON.parse(fs.readFileSync(path.join(phasesDir, f), 'utf-8')); } catch { return null; }
+          }).filter(Boolean);
+        } catch { context.existing_phases = []; }
+
+        console.log(JSON.stringify(context));
+      "
+    output:
+      format: json
+
+  create-plan:
+    agent: plan-creator
+    input:
+      project: ${{ steps.load-context.output.project }}
+      requirements: ${{ steps.load-context.output.requirements }}
+      architecture: ${{ steps.load-context.output.architecture }}
+      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. Tasks written to .project/tasks.json.
+
+    Use `/project status` to see the phase and task breakdown.
+    Use `/project validate` to check cross-block references.

package/workflows/self-implement.workflow.yaml

@@ -25,7 +25,7 @@ steps:
       conventions: "${{ input.conventions }}"
     output:
       format: json
-      schema: schemas/plan-breakdown.schema.json
+      schema: ../schemas/plan-breakdown.schema.json
 
   implement:
     forEach: "${{ steps.plan.output.plans }}"
@@ -37,7 +37,7 @@ steps:
       conventions: "${{ input.conventions }}"
     output:
       format: json
-      schema: schemas/execution-results.schema.json
+      schema: ../schemas/execution-results.schema.json
 
   verify:
     agent: verifier
@@ -46,7 +46,7 @@ steps:
       step_output: "${{ steps.implement.output }}"
     output:
       format: json
-      schema: schemas/verifier-output.schema.json
+      schema: ../schemas/verifier-output.schema.json
 
   check:
     gate:

package/workflows/typed-analysis.workflow.yaml

@@ -26,7 +26,7 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
-      schema: schemas/structure-analysis.schema.json
+      schema: ../schemas/structure-analysis.schema.json
 
   analyze-quality:
     agent: quality-analyzer
@@ -35,7 +35,7 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
-      schema: schemas/quality-analysis.schema.json
+      schema: ../schemas/quality-analysis.schema.json
 
   analyze-patterns:
     agent: pattern-analyzer
@@ -44,7 +44,7 @@ steps:
       path: ${{ input.path }}
     output:
       format: json
-      schema: schemas/pattern-analysis.schema.json
+      schema: ../schemas/pattern-analysis.schema.json
 
   synthesize:
     agent: synthesizer
@@ -54,7 +54,7 @@ steps:
       patterns: ${{ steps.analyze-patterns.output }}
     output:
       format: json
-      schema: schemas/synthesis.schema.json
+      schema: ../schemas/synthesis.schema.json
 
 completion:
   message: |