@davidorex/pi-workflows 0.2.0 → 0.3.1

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

@@ -0,0 +1,87 @@
+# Bundled Resources
+
+## agents/ (21 files)
+
+- `agents/architecture-designer.agent.yaml`
+- `agents/architecture-inferrer.agent.yaml`
+- `agents/audit-fixer.agent.yaml`
+- `agents/code-explorer.agent.yaml`
+- `agents/decomposer.agent.yaml`
+- `agents/gap-identifier.agent.yaml`
+- `agents/handoff-writer.agent.yaml`
+- `agents/investigator.agent.yaml`
+- `agents/pattern-analyzer.agent.yaml`
+- `agents/phase-author.agent.yaml`
+- `agents/plan-creator.agent.yaml`
+- `agents/plan-decomposer.agent.yaml`
+- `agents/project-definer.agent.yaml`
+- `agents/project-inferrer.agent.yaml`
+- `agents/quality-analyzer.agent.yaml`
+- `agents/requirements-gatherer.agent.yaml`
+- `agents/researcher.agent.yaml`
+- `agents/spec-implementer.agent.yaml`
+- `agents/structure-analyzer.agent.yaml`
+- `agents/synthesizer.agent.yaml`
+- `agents/verifier.agent.yaml`
+
+## schemas/ (11 files)
+
+- `schemas/decomposition-specs.schema.json`
+- `schemas/execution-results.schema.json`
+- `schemas/investigation-findings.schema.json`
+- `schemas/pattern-analysis.schema.json`
+- `schemas/phase.schema.json`
+- `schemas/plan-breakdown.schema.json`
+- `schemas/quality-analysis.schema.json`
+- `schemas/research-findings.schema.json`
+- `schemas/structure-analysis.schema.json`
+- `schemas/synthesis.schema.json`
+- `schemas/verifier-output.schema.json`
+
+## workflows/ (14 files)
+
+- `workflows/analyze-existing-project.workflow.yaml`
+- `workflows/create-handoff.workflow.yaml`
+- `workflows/create-phase.workflow.yaml`
+- `workflows/do-gap.workflow.yaml`
+- `workflows/fix-audit.workflow.yaml`
+- `workflows/gap-to-phase.workflow.yaml`
+- `workflows/init-new-project.workflow.yaml`
+- `workflows/parallel-analysis.workflow.yaml`
+- `workflows/parallel-explicit.workflow.yaml`
+- `workflows/pausable-analysis.workflow.yaml`
+- `workflows/plan-from-requirements.workflow.yaml`
+- `workflows/resumable-analysis.workflow.yaml`
+- `workflows/self-implement.workflow.yaml`
+- `workflows/typed-analysis.workflow.yaml`
+
+## templates/ (28 files)
+
+- `templates/analyzers/base-analyzer.md`
+- `templates/analyzers/macros.md`
+- `templates/analyzers/patterns-task.md`
+- `templates/analyzers/patterns.md`
+- `templates/analyzers/quality-task.md`
+- `templates/analyzers/quality.md`
+- `templates/analyzers/structure-task.md`
+- `templates/analyzers/structure.md`
+- `templates/architecture-designer/task.md`
+- `templates/architecture-inferrer/task.md`
+- `templates/audit-fixer/task.md`
+- `templates/decomposer/task.md`
+- `templates/explorer/system.md`
+- `templates/explorer/task.md`
+- `templates/gap-identifier/task.md`
+- `templates/handoff-writer/task.md`
+- `templates/investigator/task.md`
+- `templates/phase-author/task.md`
+- `templates/plan-creator/task.md`
+- `templates/plan-decomposer/task.md`
+- `templates/project-definer/task.md`
+- `templates/project-inferrer/task.md`
+- `templates/requirements-gatherer/task.md`
+- `templates/researcher/task.md`
+- `templates/spec-implementer/task.md`
+- `templates/synthesizer/system.md`
+- `templates/synthesizer/task.md`
+- `templates/verifier/task.md`

package/templates/architecture-designer/task.md

@@ -0,0 +1,117 @@
+## Project Identity
+
+**Name:** {{ project.name }}
+**Description:** {{ project.description }}
+**Core Value:** {{ project.core_value }}
+{% if project.stack %}
+
+### Stack
+{% for item in project.stack %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+
+### 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 %}
+
+## Requirements
+
+### Must
+{% for req in requirements.requirements %}
+{% if req.priority == "must" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+### Should
+{% for req in requirements.requirements %}
+{% if req.priority == "should" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+### Could
+{% for req in requirements.requirements %}
+{% if req.priority == "could" %}
+- **{{ req.id }}** [{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+## Instructions
+
+Design the initial architecture for this project. Produce modules, patterns, and boundaries that satisfy the requirements above — starting with "must" requirements and ensuring "should" requirements have a clear home.
+
+### For each module, provide:
+
+1. **name** — short identifier (e.g., "api", "auth", "storage", "cli")
+2. **file** — primary file path relative to project root (e.g., "src/api.ts")
+3. **responsibility** — one sentence: what this module owns and what it does not
+4. **dependencies** — array of other module names this depends on (empty if none)
+5. **lines** — estimated lines of code (rough order of magnitude)
+
+### For each pattern, provide:
+
+1. **name** — recognized pattern name (e.g., "Repository Pattern", "Event Sourcing", "Middleware Pipeline")
+2. **description** — why this pattern is appropriate for this project's specific needs
+3. **used_in** — array of module names that implement this pattern
+
+### For boundaries, provide:
+
+An array of strings — each describing a hard architectural constraint. These should be specific to this project, not generic ("All database access goes through the storage module", not "separate concerns").
+
+### Design principles
+
+- Module count should be proportional to requirements — a 5-requirement project needs 3-5 modules, not 15
+- Every "must" functional requirement should map to at least one module's responsibility
+- Every "must" non-functional requirement should be addressed by a pattern or boundary
+- Dependencies should flow in one direction — avoid circular module dependencies
+- If the project has a stated stack, modules should use file extensions and conventions matching that stack
+- Prefer explicit boundaries over implicit conventions
+
+### Overview
+
+Write an `overview` paragraph (required) summarizing:
+- The architectural style (layered, modular, pipeline, etc.)
+- The key structural decisions and why they fit this project
+- How the architecture supports the core_value
+
+### Output format
+
+Produce a single JSON object:
+
+```json
+{
+  "overview": "string (required)",
+  "modules": [
+    {
+      "name": "string (required)",
+      "file": "string (required)",
+      "responsibility": "string (required)",
+      "dependencies": ["string"],
+      "lines": 100
+    }
+  ],
+  "patterns": [
+    {
+      "name": "string (required)",
+      "description": "string (required)",
+      "used_in": ["module-name"]
+    }
+  ],
+  "boundaries": ["string"]
+}
+```

package/templates/architecture-inferrer/task.md

@@ -0,0 +1,61 @@
+Infer the architecture of the project at `{{ path }}`.
+
+## Codebase Analysis
+
+{% if analysis.files is defined %}
+### Files
+{% for file in analysis.files %}
+- `{{ file.path }}` ({{ file.language | default("unknown") }}, {{ file.lines | default("?") }} lines){% if file.exports %} — {{ file.exports | length }} exports{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if analysis.types is defined %}
+### Types
+{% for t in analysis.types %}
+- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}
+{% endif %}
+
+{% if analysis.dependencies is defined %}
+### Dependencies
+{% for d in analysis.dependencies %}
+- `{{ d.from }}` → `{{ d.to }}` ({{ d.type | default("import") }})
+{% endfor %}
+{% endif %}
+
+{% if analysis.entryPoints is defined %}
+### Entry Points
+{% for ep in analysis.entryPoints %}
+- `{{ ep }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+From the analysis above and targeted code reads, produce an architecture block:
+
+1. **Modules** — each cohesive unit with a clear responsibility. For each:
+   - `name`: concise identifier (e.g., "block-api", "expression-engine")
+   - `file`: primary file path relative to project root
+   - `responsibility`: one-sentence description of what this module does
+   - `dependencies`: array of other module names this module depends on
+   - `lines`: approximate line count
+
+2. **Patterns** — design patterns evidenced in the code. For each:
+   - `name`: pattern name (e.g., "registry", "factory", "middleware")
+   - `description`: how this pattern is applied in this codebase
+   - `used_in`: array of module names that use this pattern
+
+3. **Boundaries** — architectural seams where modules interact through defined interfaces (e.g., "block-api validates all writes before persistence", "dispatch spawns subprocesses through a single entry point")
+
+4. **Overview** — one paragraph summarizing the architecture: what the system does, how it's organized, and what the key design decisions are
+
+Read entry points, config files, and module interfaces to confirm the analysis. Do not read every file.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/gap-identifier/task.md

@@ -0,0 +1,103 @@
+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 analysis.files is defined %}
+### Files ({{ analysis.files | length }} total)
+{% for file in analysis.files %}
+- `{{ file.path }}` ({{ file.language | default("unknown") }}, {{ file.lines | default("?") }} lines){% if file.exports %} — {{ file.exports | length }} exports{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if analysis.types is defined %}
+### Types
+{% for t in analysis.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/handoff-writer/task.md

@@ -0,0 +1,91 @@
+Capture a handoff snapshot for the project at `{{ path }}`.
+
+## Current Project State
+
+{% if project_state.project is defined %}
+### 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 is defined 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 is defined %}
+### Block Summaries
+{% for block in project_state.blockSummaries %}
+- **{{ block.name }}**: {{ block.count | default("?") }} entries
+{% endfor %}
+{% endif %}
+
+{% if project_state.gaps is defined %}
+### 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 is defined %}
+### 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 is defined %}
+### 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/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)"]
+}
+```