@davidorex/pi-workflows 0.2.0 → 0.3.0

package/templates/plan-creator/task.md

@@ -0,0 +1,143 @@
+## 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"
+    }
+  ]
+}
+```

package/templates/project-definer/task.md

@@ -0,0 +1,67 @@
+## Vision Statement
+
+{{ vision }}
+
+{% if context %}
+## Additional Context
+
+{{ context }}
+{% endif %}
+
+## Instructions
+
+Produce a structured project identity from the vision statement above. Extract, infer, or derive each field — do not leave gaps where the vision provides signal.
+
+### Fields to produce
+
+1. **name** — short, lowercase-hyphenated project identifier
+2. **description** — 1-3 sentences capturing what the project does and why it matters
+3. **core_value** — one sentence a stakeholder outside the project could understand
+4. **target_users** — array of user roles or personas who benefit
+5. **constraints** — array of `{ type, description }` objects reflecting real limitations from the vision
+   - type examples: "technical", "organizational", "timeline", "budget", "regulatory", "compatibility"
+6. **scope_boundaries** — `{ in: [...], out: [...] }` capturing what is and is not in scope
+   - `out` is especially important: document what a reader might assume is in scope but is not
+7. **goals** — array of `{ id, description, success_criteria: [...] }` objects
+   - IDs: G-001, G-002, etc.
+   - success_criteria: measurable or verifiable statements (not aspirational)
+8. **status** — set to `"inception"`
+
+{% if stack %}
+### Stack
+
+The following technology stack has been specified:
+
+{% for item in stack %}
+- {{ item }}
+{% endfor %}
+
+Include these in the output `stack` array.
+{% endif %}
+
+{% if repository %}
+### Repository
+
+Repository: {{ repository }}
+
+Include this in the output `repository` field.
+{% endif %}
+
+### Output format
+
+Produce a single JSON object. Every required field must be present. The object should conform to the project block schema:
+
+```json
+{
+  "name": "string (required)",
+  "description": "string (required)",
+  "core_value": "string (required)",
+  "target_users": ["string"],
+  "constraints": [{ "type": "string", "description": "string" }],
+  "scope_boundaries": { "in": ["string"], "out": ["string"] },
+  "goals": [{ "id": "G-001", "description": "string", "success_criteria": ["string"] }],
+  "status": "inception",
+  "repository": "string (if provided)",
+  "stack": ["string (if provided)"]
+}
+```

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,74 @@
+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
+
+  infer-project:
+    agent: project-inferrer
+    input:
+      analysis:
+        structure: ${{ steps.analyze-structure.output }}
+        patterns: ${{ steps.analyze-patterns.output }}
+      path: ${{ input.path }}
+    output:
+      format: json
+
+  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
+
+completion:
+  template: |
+    Existing project analyzed.
+
+    **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,58 @@
+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
+
+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: ../schemas/phase.schema.json
 
   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: ../schemas/phase.schema.json
 
   write-phase:
     command: |

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

@@ -0,0 +1,55 @@
+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
+
+  gather-requirements:
+    agent: requirements-gatherer
+    input:
+      project: ${{ steps.define-identity.output }}
+      vision: ${{ input.vision }}
+    output:
+      format: json
+
+  design-architecture:
+    agent: architecture-designer
+    input:
+      project: ${{ steps.define-identity.output }}
+      requirements: ${{ steps.gather-requirements.output }}
+    output:
+      format: json
+
+  create-plan:
+    agent: plan-creator
+    input:
+      project: ${{ steps.define-identity.output }}
+      requirements: ${{ steps.gather-requirements.output }}
+      architecture: ${{ steps.design-architecture.output }}
+    output:
+      format: json
+
+completion:
+  template: |
+    Project initialized from vision.
+
+    **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,51 @@
+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
+
+completion:
+  template: |
+    Plan created from requirements.
+
+    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: