@davidorex/pi-project-workflows 0.14.4 → 0.26.0

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

@@ -0,0 +1,47 @@
+# Bundled Resources
+
+## schemas/ (9 files)
+
+- `schemas/bootstrap.schema.json`
+- `schemas/config.schema.json`
+- `schemas/layer.schema.json`
+- `schemas/priority.schema.json`
+- `schemas/relations.schema.json`
+- `schemas/severity.schema.json`
+- `schemas/source.schema.json`
+- `schemas/status.schema.json`
+- `schemas/verification-method.schema.json`
+
+## samples/ (31 files)
+
+- `samples/blocks/context-contracts.json`
+- `samples/blocks/conventions.json`
+- `samples/blocks/decisions.json`
+- `samples/blocks/features.json`
+- `samples/blocks/framework-gaps.json`
+- `samples/blocks/issues.json`
+- `samples/blocks/layer-plans.json`
+- `samples/blocks/phase.json`
+- `samples/blocks/rationale.json`
+- `samples/blocks/requirements.json`
+- `samples/blocks/research.json`
+- `samples/blocks/spec-reviews.json`
+- `samples/blocks/story.json`
+- `samples/blocks/tasks.json`
+- `samples/blocks/verification.json`
+- `samples/conception.json`
+- `samples/schemas/context-contracts.schema.json`
+- `samples/schemas/conventions.schema.json`
+- `samples/schemas/decisions.schema.json`
+- `samples/schemas/features.schema.json`
+- `samples/schemas/framework-gaps.schema.json`
+- `samples/schemas/issues.schema.json`
+- `samples/schemas/layer-plans.schema.json`
+- `samples/schemas/phase.schema.json`
+- `samples/schemas/rationale.schema.json`
+- `samples/schemas/requirements.schema.json`
+- `samples/schemas/research.schema.json`
+- `samples/schemas/spec-reviews.schema.json`
+- `samples/schemas/story.schema.json`
+- `samples/schemas/tasks.schema.json`
+- `samples/schemas/verification.schema.json`

package/skills/pi-project-workflows/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pi-project-workflows
 description: >
-  Meta-package re-exporting pi-project (schema-driven project state),
+  Meta-package re-exporting pi-context (schema-driven project state),
   pi-workflows (workflow orchestration), and pi-behavior-monitors (autonomous
   behavior monitoring). Install once to get all three extensions.
 ---
@@ -15,17 +15,17 @@ pi install npm:@davidorex/pi-project-workflows
 </objective>
 
 <included_extensions>
-<extension name="@davidorex/pi-project">
+<extension name="@davidorex/pi-context">
 Schema-driven project state management for Pi
 
-**Tools:** `append-block-item`, `update-block-item`, `read-block`, `write-block`, `project-status`, `project-validate`, `project-init`, `complete-task`
-**Commands:** `/project`
+**Tools:** `append-block-item`, `update-block-item`, `append-relation`, `append-block-nested-item`, `update-block-nested-item`, `remove-block-item`, `remove-block-nested-item`, `read-block-dir`, `read-block`, `write-block`, `context-status`, `context-validate`, `read-config`, `list-tools`, `read-samples-catalog`, `context-current-state`, `context-bootstrap-state`, `rename-canonical-id`, `amend-config`, `read-schema`, `write-schema`, `context-init`, `context-accept-all`, `filter-block-items`, `resolve-item-by-id`, `read-block-item`, `read-block-page`, `join-blocks`, `resolve-items-by-id`, `complete-task`, `context-validate-relations`, `context-edges-for-lens`, `context-walk-descendants`, `walk-ancestors`, `find-references`, `gather-execution-context`, `context-roadmap-load`, `context-roadmap-render`, `context-roadmap-validate`, `context-roadmap-list`
+**Commands:** `/context`
 </extension>
 
 <extension name="@davidorex/pi-workflows">
 Workflow orchestration extension for Pi
 
-**Tools:** `workflow`, `workflow-list`, `workflow-agents`, `workflow-validate`, `workflow-status`, `workflow-init`
+**Tools:** `workflow-execute`, `workflow-resume`, `workflow-list`, `workflow-agents`, `workflow-validate`, `workflow-status`, `workflow-init`, `render-item-by-id`, `enforce-budget`
 **Commands:** `/workflow`
 **Shortcuts:** ctrl+h (Pause running workflow), ctrl+j (Resume paused workflow)
 </extension>

package/skills/pi-workflows/SKILL.md

@@ -8,10 +8,10 @@ description: >
 ---
 
 <tools_reference>
-<tool name="workflow">
-Run a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/.
+<tool name="workflow-execute">
+Execute a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/. Auto-resumes the most recent compatible incomplete run unless fresh='true'. Use workflow-resume for explicit-only resume by runId.
 
-*Run a multi-step workflow with typed data flow between agents*
+*Execute a multi-step workflow with typed data flow (auto-resumes compatible incomplete runs)*
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -20,6 +20,18 @@ Run a named workflow with typed input. Discovers workflows from .workflows/ and
 | `fresh` | string | no | Set to 'true' to start a fresh run, ignoring any incomplete prior runs |
 </tool>
 
+<tool name="workflow-resume">
+Explicitly resume an incomplete workflow run by name + runId. Rejects when no incomplete run exists for the workflow OR when runId does not match the most recent incomplete run. Use workflow-execute for default auto-resume; this surface is for explicit-only scenarios where the caller wants to fail loudly if the run is gone or has been superseded.
+
+*Explicitly resume an incomplete workflow run by name + runId (rejects on no-match)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow` | string | yes | Workflow name |
+| `runId` | string | yes | Incomplete run ID — required, no auto-detect |
+| `input` | unknown | no | Optional input override; defaults to the original run's input |
+</tool>
+
 <tool name="workflow-list">
 List available workflows with names, descriptions, and sources.
 
@@ -61,6 +73,29 @@ Initialize .workflows/ directory for workflow run state.
 
 </tool>
 
+<tool name="render-item-by-id">
+Render a project block item by ID through its registered per-item macro. Resolves the item via the cross-block resolver, looks up the macro via the renderer registry, and renders with the supplied depth and depth-aware cross-reference recursion. Returns `[not-found: <id>]` on resolver miss and `[unrendered: <kind>/<id>]` on registry miss — same fallback markers `render_recursive` emits inside agent prompts.
+
+*Render a project block item as prompt text via its per-item macro (with depth-controlled cross-ref recursion)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Kind-prefixed ID, e.g., DEC-0001 / FEAT-001 |
+| `depth` | number | no | 0 = bare-ID refs (default), 1 = inline direct cross-references, 2+ = recurse further |
+</tool>
+
+<tool name="enforce-budget">
+Check rendered text against an `x-prompt-budget` annotation on a schema field. Returns `{ output, warning }` — `output` is the original text passed through when under budget, or tail-truncated text with `[…truncated to budget]` marker when over; `warning` is null when no truncation occurred or a structured BudgetWarning record otherwise. Annotation absence is pass-through (no error). Mirrors the behaviour of the `enforceBudget` Nunjucks global registered by compileAgent.
+
+*Validate rendered text against a schema field's prompt budget — returns truncated output and warning*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rendered` | string | yes | Rendered text to check against the field's prompt budget |
+| `blockName` | string | yes | Block schema name (without .schema.json suffix), e.g. 'decisions' or 'features' |
+| `fieldPath` | string | yes | JSON-pointer-style path to the field, e.g. '/properties/decisions/items/properties/context' |
+</tool>
+
 </tools_reference>
 
 <commands_reference>
@@ -78,7 +113,7 @@ Subcommands: `init`, `list`, `run`, `resume`, `validate`, `status`, `help`
 </keyboard_shortcuts>
 
 <bundled_resources>
-26 agents, 15 schemas, 15 workflows, 33 templates bundled.
+26 agents, 15 schemas, 15 workflows, 48 templates bundled.
 See references/bundled-resources.md for full inventory.
 </bundled_resources>
 
@@ -127,7 +162,7 @@ See references/bundled-resources.md for full inventory.
 </agent_input>
 
 <agent_input name="handoff-writer">
-- `project_state` [required] — Current project state (from projectState() or /project status — includes phases, blocks, gaps, decisions, recent commits)
+- `project_state` [required] — Current project state (from contextState() or /context status — includes phases, blocks, gaps, decisions, recent commits)
 - `path` string [required] — Root path of the project
 </agent_input>
 
@@ -239,7 +274,9 @@ Workflows are discovered from three locations (first match wins):
 | loop | `loop: { maxAttempts, steps }` | Repeat sub-steps until gate breaks or max reached |
 | parallel | `parallel: { a: ..., b: ... }` | Run named sub-steps concurrently |
 | pause | `pause: true` or `pause: "message"` | Pause execution, resumable later |
-| forEach | `forEach: "${{ expr }}"` | Iterate over an array, executing the step per element |
+| block | `block: { op: read\|write\|append\|update\|remove\|… }` | Validated in-process `.project` block I/O via the block API — no LLM, no subprocess |
+
+`forEach: "${{ expr }}"` (iterate the step per array element) and `as:` are step MODIFIERS, not step types — they combine with any type above.
 </step_types>
 
 <expression_syntax>

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

@@ -65,7 +65,7 @@
 - `workflows/self-implement.workflow.yaml`
 - `workflows/typed-analysis.workflow.yaml`
 
-## templates/ (33 files)
+## templates/ (48 files)
 
 - `templates/analyzers/base-analyzer.md`
 - `templates/analyzers/patterns-task.md`
@@ -86,6 +86,20 @@
 - `templates/gap-resolution-assessor/task.md`
 - `templates/handoff-writer/task.md`
 - `templates/investigator/task.md`
+- `templates/items/architecture.md`
+- `templates/items/conformance.md`
+- `templates/items/conventions.md`
+- `templates/items/decisions.md`
+- `templates/items/domain.md`
+- `templates/items/features.md`
+- `templates/items/framework-gaps.md`
+- `templates/items/issues.md`
+- `templates/items/layer-plans.md`
+- `templates/items/project.md`
+- `templates/items/requirements.md`
+- `templates/items/research.md`
+- `templates/items/spec-reviews.md`
+- `templates/items/tasks.md`
 - `templates/phase-author/task.md`
 - `templates/plan-creator/task.md`
 - `templates/plan-decomposer/task.md`
@@ -94,6 +108,7 @@
 - `templates/requirements-gatherer/task.md`
 - `templates/researcher/task.md`
 - `templates/shared/macros.md`
+- `templates/shared/render-helpers.md`
 - `templates/spec-implementer/task.md`
 - `templates/synthesizer/system.md`
 - `templates/synthesizer/task.md`

package/skills/pi-project/SKILL.md

@@ -1,242 +0,0 @@
----
-name: pi-project
-description: >
-  Schema-driven project state management with typed JSON blocks, schema
-  validation, planning lifecycle, and cross-block referential integrity. Use when
-  managing .project/ blocks, scaffolding project structure, validating project
-  state, or adding work items.
----
-
-<tools_reference>
-<tool name="append-block-item">
-Append an item to an array in a project block file. Schema validation is automatic.
-
-*Append items to project blocks (issues, decisions, or any user-defined block)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'issues', 'decisions') |
-| `arrayKey` | string | yes | Array key in the block (e.g., 'issues', 'decisions') |
-| `item` | unknown | yes | Item object to append — must conform to block schema |
-</tool>
-
-<tool name="update-block-item">
-Update fields on an item in a project block array. Finds by predicate field match.
-
-*Update items in project blocks — change status, add details, mark resolved*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'issues', 'decisions') |
-| `arrayKey` | string | yes | Array key in the block |
-| `match` | object | yes | Fields to match (e.g., { id: 'issue-123' }) |
-| `updates` | object | yes | Fields to update (e.g., { status: 'resolved' }) |
-</tool>
-
-<tool name="read-block">
-Read a project block file as structured JSON.
-
-*Read a project block as structured JSON*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'issues', 'tasks', 'requirements') |
-</tool>
-
-<tool name="write-block">
-Write or replace an entire project block with schema validation.
-
-*Write or replace a project block with schema validation*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'project', 'architecture') |
-| `data` | unknown | yes | Complete block data — must conform to block schema |
-</tool>
-
-<tool name="project-status">
-Get derived project state — source metrics, block summaries, planning lifecycle status.
-
-*Get project state — source metrics, block summaries, planning lifecycle status*
-
-</tool>
-
-<tool name="project-validate">
-Validate cross-block referential integrity — check that IDs referenced across blocks exist.
-
-*Validate cross-block referential integrity*
-
-</tool>
-
-<tool name="project-init">
-Initialize .project/ directory with default schemas and empty block files.
-
-*Initialize .project/ directory with default schemas and blocks*
-
-</tool>
-
-<tool name="complete-task">
-Complete a task with verification gate — requires a passing verification entry targeting the task.
-
-*Complete a task — gates on passing verification before updating status*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskId` | string | yes | Task ID to complete |
-| `verificationId` | string | yes | Verification entry ID (must target this task with status 'passed') |
-</tool>
-
-</tools_reference>
-
-<commands_reference>
-<command name="/project">
-Project state management
-
-Subcommands: `init`, `status`, `add-work`, `validate`, `help`
-</command>
-
-</commands_reference>
-
-<events>
-`session_start`
-</events>
-
-<bundled_resources>
-22 defaults bundled.
-See references/bundled-resources.md for full inventory.
-</bundled_resources>
-
-<planning_vocabulary>
-
-**Block Types:**
-
-| Block | Title | Array Key | Item Fields |
-|-------|-------|-----------|-------------|
-| `architecture` | Architecture | `modules` | name, file, responsibility, dependencies? (array), lines? (integer) |
-| `audit` | Audit | `checks` | id, description, status (string (pass|fail|warn|skip)), category?, details? |
-| `conformance-reference` | Conformance Reference | `principles` | id, name, description?, rules (array) |
-| `decisions` | Decisions | `decisions` | id, decision, rationale, phase? (string|integer), status (string (decided|tentative|revisit|superseded)), context?, task? |
-| `domain` | Domain Knowledge | `entries` | id, title, content, category (string (research|reference|domain-rule|prior-art|constraint)), source?, confidence? (string (high|medium|low)), related_requirements? (array), tags? (array) |
-| `handoff` | Handoff | `current_tasks` |  |
-| `issues` | Issues | `issues` | id, title, body, location, status (string (open|resolved|deferred)), category (string (primitive|issue|cleanup|capability|composition)), priority (string (low|medium|high|critical)), package, source? (string (human|agent|monitor|workflow)), resolved_by? |
-| `phase` | Phase | `success_criteria` | criterion, verify_method (string (command|inspect|test)) |
-| `project` | Project Identity | `target_users` |  |
-| `rationale` | Design Rationale | `rationales` | id, title, narrative, related_decisions? (array), phase? (string|integer), context? |
-| `requirements` | Requirements | `requirements` | id, description, type (string (functional|non-functional|constraint|integration)), status (string (proposed|accepted|deferred|implemented|verified)), priority (string (must|should|could|wont)), acceptance_criteria? (array), source? (string (human|agent|analysis)), traces_to? (array), depends_on? (array) |
-| `tasks` | Tasks | `tasks` | id, description, status (string (planned|in-progress|completed|blocked|cancelled)), phase? (string|integer), files? (array), acceptance_criteria? (array), depends_on? (array), assigned_agent?, verification?, notes? |
-| `verification` | Verification | `verifications` | id, target, target_type (string (task|phase|requirement)), status (string (passed|failed|partial|skipped)), method (string (command|inspect|test)), evidence?, timestamp?, criteria_results? (array) |
-
-**Status Enums:**
-
-| Block | Field | Values |
-|-------|-------|--------|
-| `audit` | `status` | pass, fail, warn, skip |
-| `audit` | `severity` | error, warning, info |
-| `decisions` | `status` | decided, tentative, revisit, superseded |
-| `domain` | `category` | research, reference, domain-rule, prior-art, constraint |
-| `domain` | `confidence` | high, medium, low |
-| `issues` | `status` | open, resolved, deferred |
-| `issues` | `category` | primitive, issue, cleanup, capability, composition |
-| `issues` | `priority` | low, medium, high, critical |
-| `issues` | `source` | human, agent, monitor, workflow |
-| `phase` | `status` | planned, in-progress, completed |
-| `phase` | `verify_method` | command, inspect, test |
-| `phase` | `status` | planned, in-progress, completed |
-| `project` | `status` | inception, planning, development, maintenance, complete |
-| `requirements` | `type` | functional, non-functional, constraint, integration |
-| `requirements` | `status` | proposed, accepted, deferred, implemented, verified |
-| `requirements` | `priority` | must, should, could, wont |
-| `requirements` | `source` | human, agent, analysis |
-| `tasks` | `status` | planned, in-progress, completed, blocked, cancelled |
-| `verification` | `target_type` | task, phase, requirement |
-| `verification` | `status` | passed, failed, partial, skipped |
-| `verification` | `method` | command, inspect, test |
-
-</planning_vocabulary>
-
-<objective>
-pi-project manages structured project state in `.project/` — a directory of JSON block files validated against schemas.
-</objective>
-
-<block_files>
-Blocks are JSON files in `.project/` (e.g., `gaps.json`, `decisions.json`). Each block has a corresponding schema in `.project/schemas/`. When you write to a block via the tools, the data is validated against its schema before persisting. Writes are atomic (tmp file + rename).
-</block_files>
-
-<schema_validation>
-Every block write validates against `.project/schemas/<blockname>.schema.json`. If the schema file doesn't exist, writes proceed without validation. Validation errors include the specific JSON Schema violations.
-</schema_validation>
-
-<project_init>
-`/project init` scaffolds the `.project/` directory with default schemas and empty block files from the package's `defaults/` directory. Idempotent — skips files that already exist.
-</project_init>
-
-<project_status>
-`/project status` derives project state dynamically from the filesystem:
-- Source file count and line count (`.ts` files excluding tests)
-- Test count and test file count
-- Schema count, block count, phase count
-- Block summaries with array item counts and status distributions
-- Requirements summary (total, by status, by priority) — from requirements.json
-- Tasks summary (total, by status) — from tasks.json
-- Domain entry count — from domain.json
-- Verification summary (total, passed, failed) — from verification.json
-- Handoff presence — whether handoff.json exists
-- Recent git commits
-- Current phase detection
-</project_status>
-
-<project_add_work>
-`/project add-work` discovers appendable blocks (blocks with array schemas), reads their schemas, and sends a structured instruction to the LLM to extract items from the conversation into the typed blocks. This is a follow-up message that triggers the LLM to use the `append-block-item` tool.
-</project_add_work>
-
-<duplicate_detection>
-`append-block-item` checks for duplicate items by `id` field before appending. If an item with the same `id` already exists in the target array, it returns a message instead of appending.
-</duplicate_detection>
-
-<project_validate>
-`/project validate` checks cross-block referential integrity:
-- task.phase references a valid phase
-- task.depends_on references valid task IDs
-- decision.phase references a valid phase
-- gap.resolved_by references a valid ID
-- requirement.traces_to references valid phase/task IDs
-- requirement.depends_on references valid requirement IDs
-- verification.target references a valid target ID
-- rationale.related_decisions references valid decision IDs
-
-Returns errors (broken dependency references) and warnings (unresolved cross-references).
-</project_validate>
-
-<planning_lifecycle>
-The default schemas support a full planning lifecycle:
-- **project.json** — identity, vision, goals, constraints, scope, status
-- **domain.json** — research findings, reference material, domain rules
-- **requirements.json** — functional/non-functional requirements with MoSCoW priority and lifecycle states
-- **architecture.json** — modules, patterns, boundaries
-- **phases/** — ordered delivery units with goals, success criteria, inputs/outputs
-- **tasks.json** — standalone task registry with status lifecycle and phase linkage
-- **decisions.json** — choices with rationale and phase association
-- **gaps.json** — open items with priority, category, and resolution tracking
-- **rationale.json** — design rationale with decision cross-references
-- **handoff.json** — session context snapshot (created on-demand, not by /project init)
-- **verification.json** — completion evidence per task/phase/requirement
-- **conformance-reference.json** — executable code conventions with principles, rules, check methods (grep/command/ast/inspect), and check patterns. Ships empty, populated per-project by agents or users.
-- **audit** (schema only, no default block) — structured audit results produced by running conformance checks.
-
-All schemas are user-customizable. Edit `.project/schemas/*.schema.json` to add fields, change enums, or restructure blocks without modifying code.
-</planning_lifecycle>
-
-<update_check>
-On `session_start`, checks npm registry for newer versions of `@davidorex/pi-project-workflows` and notifies via UI if an update is available. Non-blocking — failures are silently ignored.
-</update_check>
-
-<success_criteria>
-- `.project/` directory exists with schemas and block files after `/project init`
-- Block writes validate against schemas — invalid data rejected with specific error
-- `/project status` returns current derived state without errors
-- `/project validate` returns no errors for well-formed cross-block references
-- `append-block-item` rejects duplicate IDs
-- Schema customizations (field additions, enum changes) take effect on next write
-</success_criteria>
-
-*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

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

@@ -1,26 +0,0 @@
-# Bundled Resources
-
-## defaults/ (22 files)
-
-- `defaults/blocks/conformance-reference.json`
-- `defaults/blocks/decisions.json`
-- `defaults/blocks/domain.json`
-- `defaults/blocks/issues.json`
-- `defaults/blocks/project.json`
-- `defaults/blocks/rationale.json`
-- `defaults/blocks/requirements.json`
-- `defaults/blocks/tasks.json`
-- `defaults/blocks/verification.json`
-- `defaults/schemas/architecture.schema.json`
-- `defaults/schemas/audit.schema.json`
-- `defaults/schemas/conformance-reference.schema.json`
-- `defaults/schemas/decisions.schema.json`
-- `defaults/schemas/domain.schema.json`
-- `defaults/schemas/handoff.schema.json`
-- `defaults/schemas/issues.schema.json`
-- `defaults/schemas/phase.schema.json`
-- `defaults/schemas/project.schema.json`
-- `defaults/schemas/rationale.schema.json`
-- `defaults/schemas/requirements.schema.json`
-- `defaults/schemas/tasks.schema.json`
-- `defaults/schemas/verification.schema.json`