@davidorex/pi-project-workflows 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -2
- package/monitors-extension.ts +1 -0
- package/package.json +34 -23
- package/project-extension.ts +1 -1
- package/skills/pi-behavior-monitors/SKILL.md +692 -0
- package/skills/pi-behavior-monitors/references/bundled-resources.md +29 -0
- package/skills/pi-project/SKILL.md +231 -0
- package/skills/pi-project/references/bundled-resources.md +26 -0
- package/skills/pi-project-workflows/SKILL.md +42 -0
- package/skills/pi-workflows/SKILL.md +185 -0
- package/skills/pi-workflows/references/bundled-resources.md +87 -0
- package/workflows-extension.ts +1 -1
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Bundled Resources
|
|
2
|
+
|
|
3
|
+
## schemas/ (2 files)
|
|
4
|
+
|
|
5
|
+
- `schemas/monitor-pattern.schema.json`
|
|
6
|
+
- `schemas/monitor.schema.json`
|
|
7
|
+
|
|
8
|
+
## examples/ (20 files)
|
|
9
|
+
|
|
10
|
+
- `examples/commit-hygiene/classify.md`
|
|
11
|
+
- `examples/commit-hygiene.instructions.json`
|
|
12
|
+
- `examples/commit-hygiene.monitor.json`
|
|
13
|
+
- `examples/commit-hygiene.patterns.json`
|
|
14
|
+
- `examples/fragility/classify.md`
|
|
15
|
+
- `examples/fragility.instructions.json`
|
|
16
|
+
- `examples/fragility.monitor.json`
|
|
17
|
+
- `examples/fragility.patterns.json`
|
|
18
|
+
- `examples/hedge/classify.md`
|
|
19
|
+
- `examples/hedge.instructions.json`
|
|
20
|
+
- `examples/hedge.monitor.json`
|
|
21
|
+
- `examples/hedge.patterns.json`
|
|
22
|
+
- `examples/unauthorized-action/classify.md`
|
|
23
|
+
- `examples/unauthorized-action.instructions.json`
|
|
24
|
+
- `examples/unauthorized-action.monitor.json`
|
|
25
|
+
- `examples/unauthorized-action.patterns.json`
|
|
26
|
+
- `examples/work-quality/classify.md`
|
|
27
|
+
- `examples/work-quality.instructions.json`
|
|
28
|
+
- `examples/work-quality.monitor.json`
|
|
29
|
+
- `examples/work-quality.patterns.json`
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pi-project
|
|
3
|
+
description: >
|
|
4
|
+
Schema-driven project state management with typed JSON blocks, schema
|
|
5
|
+
validation, planning lifecycle, and cross-block referential integrity. Use when
|
|
6
|
+
managing .project/ blocks, scaffolding project structure, validating project
|
|
7
|
+
state, or adding work items.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
<tools_reference>
|
|
11
|
+
<tool name="append-block-item">
|
|
12
|
+
Append an item to an array in a project block file. Schema validation is automatic.
|
|
13
|
+
|
|
14
|
+
*Append items to project blocks (gaps, decisions, or any user-defined block)*
|
|
15
|
+
|
|
16
|
+
| Parameter | Type | Required | Description |
|
|
17
|
+
|-----------|------|----------|-------------|
|
|
18
|
+
| `block` | string | yes | Block name (e.g., 'gaps', 'decisions') |
|
|
19
|
+
| `arrayKey` | string | yes | Array key in the block (e.g., 'gaps', 'decisions') |
|
|
20
|
+
| `item` | unknown | yes | Item object to append — must conform to block schema |
|
|
21
|
+
</tool>
|
|
22
|
+
|
|
23
|
+
<tool name="update-block-item">
|
|
24
|
+
Update fields on an item in a project block array. Finds by predicate field match.
|
|
25
|
+
|
|
26
|
+
*Update items in project blocks — change status, add details, mark resolved*
|
|
27
|
+
|
|
28
|
+
| Parameter | Type | Required | Description |
|
|
29
|
+
|-----------|------|----------|-------------|
|
|
30
|
+
| `block` | string | yes | Block name (e.g., 'gaps', 'decisions') |
|
|
31
|
+
| `arrayKey` | string | yes | Array key in the block |
|
|
32
|
+
| `match` | object | yes | Fields to match (e.g., { id: 'gap-123' }) |
|
|
33
|
+
| `updates` | object | yes | Fields to update (e.g., { status: 'resolved' }) |
|
|
34
|
+
</tool>
|
|
35
|
+
|
|
36
|
+
<tool name="read-block">
|
|
37
|
+
Read a project block file as structured JSON.
|
|
38
|
+
|
|
39
|
+
*Read a project block as structured JSON*
|
|
40
|
+
|
|
41
|
+
| Parameter | Type | Required | Description |
|
|
42
|
+
|-----------|------|----------|-------------|
|
|
43
|
+
| `block` | string | yes | Block name (e.g., 'gaps', 'tasks', 'requirements') |
|
|
44
|
+
</tool>
|
|
45
|
+
|
|
46
|
+
<tool name="write-block">
|
|
47
|
+
Write or replace an entire project block with schema validation.
|
|
48
|
+
|
|
49
|
+
*Write or replace a project block with schema validation*
|
|
50
|
+
|
|
51
|
+
| Parameter | Type | Required | Description |
|
|
52
|
+
|-----------|------|----------|-------------|
|
|
53
|
+
| `block` | string | yes | Block name (e.g., 'project', 'architecture') |
|
|
54
|
+
| `data` | unknown | yes | Complete block data — must conform to block schema |
|
|
55
|
+
</tool>
|
|
56
|
+
|
|
57
|
+
<tool name="project-status">
|
|
58
|
+
Get derived project state — source metrics, block summaries, planning lifecycle status.
|
|
59
|
+
|
|
60
|
+
*Get project state — source metrics, block summaries, planning lifecycle status*
|
|
61
|
+
|
|
62
|
+
</tool>
|
|
63
|
+
|
|
64
|
+
<tool name="project-validate">
|
|
65
|
+
Validate cross-block referential integrity — check that IDs referenced across blocks exist.
|
|
66
|
+
|
|
67
|
+
*Validate cross-block referential integrity*
|
|
68
|
+
|
|
69
|
+
</tool>
|
|
70
|
+
|
|
71
|
+
<tool name="project-init">
|
|
72
|
+
Initialize .project/ directory with default schemas and empty block files.
|
|
73
|
+
|
|
74
|
+
*Initialize .project/ directory with default schemas and blocks*
|
|
75
|
+
|
|
76
|
+
</tool>
|
|
77
|
+
|
|
78
|
+
</tools_reference>
|
|
79
|
+
|
|
80
|
+
<commands_reference>
|
|
81
|
+
<command name="/project">
|
|
82
|
+
Project state management
|
|
83
|
+
|
|
84
|
+
Subcommands: `init`, `status`, `add-work`, `validate`
|
|
85
|
+
</command>
|
|
86
|
+
|
|
87
|
+
</commands_reference>
|
|
88
|
+
|
|
89
|
+
<events>
|
|
90
|
+
`session_start`
|
|
91
|
+
</events>
|
|
92
|
+
|
|
93
|
+
<bundled_resources>
|
|
94
|
+
22 defaults bundled.
|
|
95
|
+
See references/bundled-resources.md for full inventory.
|
|
96
|
+
</bundled_resources>
|
|
97
|
+
|
|
98
|
+
<planning_vocabulary>
|
|
99
|
+
|
|
100
|
+
**Block Types:**
|
|
101
|
+
|
|
102
|
+
| Block | Title | Array Key | Item Fields |
|
|
103
|
+
|-------|-------|-----------|-------------|
|
|
104
|
+
| `architecture` | Architecture | `modules` | name, file, responsibility, dependencies? (array), lines? (integer) |
|
|
105
|
+
| `audit` | audit | `checks` | id, description, status (string (pass|fail|warn|skip)), category?, details? |
|
|
106
|
+
| `conformance-reference` | conformance-reference | `principles` | id, name, description?, rules (array) |
|
|
107
|
+
| `decisions` | Decisions | `decisions` | id, decision, rationale, phase? (string|integer), status (string (decided|tentative|revisit|superseded)), context? |
|
|
108
|
+
| `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) |
|
|
109
|
+
| `gaps` | Gaps | `gaps` | id, description, status (string (open|resolved|deferred)), category (string (missing|incomplete|defect|improvement|technical-debt|question)), priority (string (low|medium|high|critical)), phase? (string|integer), resolved_by?, source? (string (human|agent|monitor|workflow)), details? |
|
|
110
|
+
| `handoff` | Handoff | `current_tasks` | |
|
|
111
|
+
| `phase` | Phase | `success_criteria` | criterion, verify_method (string (command|inspect|test)) |
|
|
112
|
+
| `project` | Project Identity | `target_users` | |
|
|
113
|
+
| `rationale` | Design Rationale | `rationales` | id, title, narrative, related_decisions? (array), phase? (string|integer), context? |
|
|
114
|
+
| `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) |
|
|
115
|
+
| `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? |
|
|
116
|
+
| `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) |
|
|
117
|
+
|
|
118
|
+
**Status Enums:**
|
|
119
|
+
|
|
120
|
+
| Block | Field | Values |
|
|
121
|
+
|-------|-------|--------|
|
|
122
|
+
| `audit` | `status` | pass, fail, warn, skip |
|
|
123
|
+
| `audit` | `severity` | error, warning, info |
|
|
124
|
+
| `decisions` | `status` | decided, tentative, revisit, superseded |
|
|
125
|
+
| `domain` | `category` | research, reference, domain-rule, prior-art, constraint |
|
|
126
|
+
| `domain` | `confidence` | high, medium, low |
|
|
127
|
+
| `gaps` | `status` | open, resolved, deferred |
|
|
128
|
+
| `gaps` | `category` | missing, incomplete, defect, improvement, technical-debt, question |
|
|
129
|
+
| `gaps` | `priority` | low, medium, high, critical |
|
|
130
|
+
| `gaps` | `source` | human, agent, monitor, workflow |
|
|
131
|
+
| `phase` | `status` | planned, in-progress, completed |
|
|
132
|
+
| `phase` | `verify_method` | command, inspect, test |
|
|
133
|
+
| `phase` | `status` | planned, in-progress, completed |
|
|
134
|
+
| `project` | `status` | inception, planning, development, maintenance, complete |
|
|
135
|
+
| `requirements` | `type` | functional, non-functional, constraint, integration |
|
|
136
|
+
| `requirements` | `status` | proposed, accepted, deferred, implemented, verified |
|
|
137
|
+
| `requirements` | `priority` | must, should, could, wont |
|
|
138
|
+
| `requirements` | `source` | human, agent, analysis |
|
|
139
|
+
| `tasks` | `status` | planned, in-progress, completed, blocked, cancelled |
|
|
140
|
+
| `verification` | `target_type` | task, phase, requirement |
|
|
141
|
+
| `verification` | `status` | passed, failed, partial, skipped |
|
|
142
|
+
| `verification` | `method` | command, inspect, test |
|
|
143
|
+
|
|
144
|
+
</planning_vocabulary>
|
|
145
|
+
|
|
146
|
+
<objective>
|
|
147
|
+
pi-project manages structured project state in `.project/` — a directory of JSON block files validated against schemas.
|
|
148
|
+
</objective>
|
|
149
|
+
|
|
150
|
+
<block_files>
|
|
151
|
+
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).
|
|
152
|
+
</block_files>
|
|
153
|
+
|
|
154
|
+
<schema_validation>
|
|
155
|
+
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.
|
|
156
|
+
</schema_validation>
|
|
157
|
+
|
|
158
|
+
<project_init>
|
|
159
|
+
`/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.
|
|
160
|
+
</project_init>
|
|
161
|
+
|
|
162
|
+
<project_status>
|
|
163
|
+
`/project status` derives project state dynamically from the filesystem:
|
|
164
|
+
- Source file count and line count (`.ts` files excluding tests)
|
|
165
|
+
- Test count and test file count
|
|
166
|
+
- Schema count, block count, phase count
|
|
167
|
+
- Block summaries with array item counts and status distributions
|
|
168
|
+
- Requirements summary (total, by status, by priority) — from requirements.json
|
|
169
|
+
- Tasks summary (total, by status) — from tasks.json
|
|
170
|
+
- Domain entry count — from domain.json
|
|
171
|
+
- Verification summary (total, passed, failed) — from verification.json
|
|
172
|
+
- Handoff presence — whether handoff.json exists
|
|
173
|
+
- Recent git commits
|
|
174
|
+
- Current phase detection
|
|
175
|
+
</project_status>
|
|
176
|
+
|
|
177
|
+
<project_add_work>
|
|
178
|
+
`/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.
|
|
179
|
+
</project_add_work>
|
|
180
|
+
|
|
181
|
+
<duplicate_detection>
|
|
182
|
+
`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.
|
|
183
|
+
</duplicate_detection>
|
|
184
|
+
|
|
185
|
+
<project_validate>
|
|
186
|
+
`/project validate` checks cross-block referential integrity:
|
|
187
|
+
- task.phase references a valid phase
|
|
188
|
+
- task.depends_on references valid task IDs
|
|
189
|
+
- decision.phase references a valid phase
|
|
190
|
+
- gap.resolved_by references a valid ID
|
|
191
|
+
- requirement.traces_to references valid phase/task IDs
|
|
192
|
+
- requirement.depends_on references valid requirement IDs
|
|
193
|
+
- verification.target references a valid target ID
|
|
194
|
+
- rationale.related_decisions references valid decision IDs
|
|
195
|
+
|
|
196
|
+
Returns errors (broken dependency references) and warnings (unresolved cross-references).
|
|
197
|
+
</project_validate>
|
|
198
|
+
|
|
199
|
+
<planning_lifecycle>
|
|
200
|
+
The default schemas support a full planning lifecycle:
|
|
201
|
+
- **project.json** — identity, vision, goals, constraints, scope, status
|
|
202
|
+
- **domain.json** — research findings, reference material, domain rules
|
|
203
|
+
- **requirements.json** — functional/non-functional requirements with MoSCoW priority and lifecycle states
|
|
204
|
+
- **architecture.json** — modules, patterns, boundaries
|
|
205
|
+
- **phases/** — ordered delivery units with goals, success criteria, inputs/outputs
|
|
206
|
+
- **tasks.json** — standalone task registry with status lifecycle and phase linkage
|
|
207
|
+
- **decisions.json** — choices with rationale and phase association
|
|
208
|
+
- **gaps.json** — open items with priority, category, and resolution tracking
|
|
209
|
+
- **rationale.json** — design rationale with decision cross-references
|
|
210
|
+
- **handoff.json** — session context snapshot (created on-demand, not by /project init)
|
|
211
|
+
- **verification.json** — completion evidence per task/phase/requirement
|
|
212
|
+
- **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.
|
|
213
|
+
- **audit** (schema only, no default block) — structured audit results produced by running conformance checks.
|
|
214
|
+
|
|
215
|
+
All schemas are user-customizable. Edit `.project/schemas/*.schema.json` to add fields, change enums, or restructure blocks without modifying code.
|
|
216
|
+
</planning_lifecycle>
|
|
217
|
+
|
|
218
|
+
<update_check>
|
|
219
|
+
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.
|
|
220
|
+
</update_check>
|
|
221
|
+
|
|
222
|
+
<success_criteria>
|
|
223
|
+
- `.project/` directory exists with schemas and block files after `/project init`
|
|
224
|
+
- Block writes validate against schemas — invalid data rejected with specific error
|
|
225
|
+
- `/project status` returns current derived state without errors
|
|
226
|
+
- `/project validate` returns no errors for well-formed cross-block references
|
|
227
|
+
- `append-block-item` rejects duplicate IDs
|
|
228
|
+
- Schema customizations (field additions, enum changes) take effect on next write
|
|
229
|
+
</success_criteria>
|
|
230
|
+
|
|
231
|
+
*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Bundled Resources
|
|
2
|
+
|
|
3
|
+
## defaults/ (22 files)
|
|
4
|
+
|
|
5
|
+
- `defaults/blocks/conformance-reference.json`
|
|
6
|
+
- `defaults/blocks/decisions.json`
|
|
7
|
+
- `defaults/blocks/domain.json`
|
|
8
|
+
- `defaults/blocks/gaps.json`
|
|
9
|
+
- `defaults/blocks/project.json`
|
|
10
|
+
- `defaults/blocks/rationale.json`
|
|
11
|
+
- `defaults/blocks/requirements.json`
|
|
12
|
+
- `defaults/blocks/tasks.json`
|
|
13
|
+
- `defaults/blocks/verification.json`
|
|
14
|
+
- `defaults/schemas/architecture.schema.json`
|
|
15
|
+
- `defaults/schemas/audit.schema.json`
|
|
16
|
+
- `defaults/schemas/conformance-reference.schema.json`
|
|
17
|
+
- `defaults/schemas/decisions.schema.json`
|
|
18
|
+
- `defaults/schemas/domain.schema.json`
|
|
19
|
+
- `defaults/schemas/gaps.schema.json`
|
|
20
|
+
- `defaults/schemas/handoff.schema.json`
|
|
21
|
+
- `defaults/schemas/phase.schema.json`
|
|
22
|
+
- `defaults/schemas/project.schema.json`
|
|
23
|
+
- `defaults/schemas/rationale.schema.json`
|
|
24
|
+
- `defaults/schemas/requirements.schema.json`
|
|
25
|
+
- `defaults/schemas/tasks.schema.json`
|
|
26
|
+
- `defaults/schemas/verification.schema.json`
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pi-project-workflows
|
|
3
|
+
description: >
|
|
4
|
+
Meta-package re-exporting pi-project (schema-driven project state),
|
|
5
|
+
pi-workflows (workflow orchestration), and pi-behavior-monitors (autonomous
|
|
6
|
+
behavior monitoring). Install once to get all three extensions.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
<objective>
|
|
10
|
+
This meta-package re-exports all three extensions. Install once to get everything:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
pi install npm:@davidorex/pi-project-workflows
|
|
14
|
+
```
|
|
15
|
+
</objective>
|
|
16
|
+
|
|
17
|
+
<included_extensions>
|
|
18
|
+
<extension name="@davidorex/pi-project">
|
|
19
|
+
Schema-driven project state management for Pi
|
|
20
|
+
|
|
21
|
+
**Tools:** `append-block-item`, `update-block-item`, `read-block`, `write-block`, `project-status`, `project-validate`, `project-init`
|
|
22
|
+
**Commands:** `/project`
|
|
23
|
+
</extension>
|
|
24
|
+
|
|
25
|
+
<extension name="@davidorex/pi-workflows">
|
|
26
|
+
Workflow orchestration extension for Pi
|
|
27
|
+
|
|
28
|
+
**Tools:** `workflow`, `workflow-list`, `workflow-agents`, `workflow-validate`, `workflow-status`, `workflow-init`
|
|
29
|
+
**Commands:** `/workflow`
|
|
30
|
+
**Shortcuts:** ctrl+h (Pause running workflow), ctrl+j (Resume paused workflow)
|
|
31
|
+
</extension>
|
|
32
|
+
|
|
33
|
+
<extension name="@davidorex/pi-behavior-monitors">
|
|
34
|
+
Behavior monitors for pi that watch agent activity and steer corrections
|
|
35
|
+
|
|
36
|
+
**Tools:** `monitors-status`, `monitors-inspect`, `monitors-control`, `monitors-rules`, `monitors-patterns`
|
|
37
|
+
**Commands:** `/monitors`
|
|
38
|
+
</extension>
|
|
39
|
+
|
|
40
|
+
</included_extensions>
|
|
41
|
+
|
|
42
|
+
*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pi-workflows
|
|
3
|
+
description: >
|
|
4
|
+
Orchestrates multi-step agent workflows defined in YAML with DAG-based
|
|
5
|
+
execution, typed data flow, checkpoint/resume, and output validation. Use when
|
|
6
|
+
running workflows, authoring workflow specs, debugging step failures, or
|
|
7
|
+
inspecting agent configurations.
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
<tools_reference>
|
|
11
|
+
<tool name="workflow">
|
|
12
|
+
Run a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/.
|
|
13
|
+
|
|
14
|
+
*Run a multi-step workflow with typed data flow between agents*
|
|
15
|
+
|
|
16
|
+
| Parameter | Type | Required | Description |
|
|
17
|
+
|-----------|------|----------|-------------|
|
|
18
|
+
| `workflow` | string | yes | Name of the workflow to run |
|
|
19
|
+
| `input` | unknown | no | Input data for the workflow (validated against workflow's input schema) |
|
|
20
|
+
| `fresh` | string | no | Set to 'true' to start a fresh run, ignoring any incomplete prior runs |
|
|
21
|
+
</tool>
|
|
22
|
+
|
|
23
|
+
<tool name="workflow-list">
|
|
24
|
+
List available workflows with names, descriptions, and sources.
|
|
25
|
+
|
|
26
|
+
*List available workflows with names, descriptions, and sources*
|
|
27
|
+
|
|
28
|
+
</tool>
|
|
29
|
+
|
|
30
|
+
<tool name="workflow-agents">
|
|
31
|
+
List available agents with full specs, or inspect a single agent by name. Returns role, description, model, tools, output format/schema, prompt template paths.
|
|
32
|
+
|
|
33
|
+
*List available agents with specs, or inspect a single agent by name*
|
|
34
|
+
|
|
35
|
+
| Parameter | Type | Required | Description |
|
|
36
|
+
|-----------|------|----------|-------------|
|
|
37
|
+
| `name` | string | no | Agent name to inspect (omit to list all) |
|
|
38
|
+
</tool>
|
|
39
|
+
|
|
40
|
+
<tool name="workflow-validate">
|
|
41
|
+
Validate workflow specs — check agents, schemas, step references, and filters.
|
|
42
|
+
|
|
43
|
+
*Validate workflow specs — check agents, schemas, step references, filters*
|
|
44
|
+
|
|
45
|
+
| Parameter | Type | Required | Description |
|
|
46
|
+
|-----------|------|----------|-------------|
|
|
47
|
+
| `name` | string | no | Workflow name to validate (omit to validate all) |
|
|
48
|
+
</tool>
|
|
49
|
+
|
|
50
|
+
<tool name="workflow-status">
|
|
51
|
+
Get workflow vocabulary — step types, filters, available agents, workflows, schemas, templates.
|
|
52
|
+
|
|
53
|
+
*Get workflow vocabulary — step types, filters, available agents, workflows, schemas*
|
|
54
|
+
|
|
55
|
+
</tool>
|
|
56
|
+
|
|
57
|
+
<tool name="workflow-init">
|
|
58
|
+
Initialize .workflows/ directory for workflow run state.
|
|
59
|
+
|
|
60
|
+
*Initialize .workflows/ directory for workflow run state*
|
|
61
|
+
|
|
62
|
+
</tool>
|
|
63
|
+
|
|
64
|
+
</tools_reference>
|
|
65
|
+
|
|
66
|
+
<commands_reference>
|
|
67
|
+
<command name="/workflow">
|
|
68
|
+
List and run workflows
|
|
69
|
+
|
|
70
|
+
Subcommands: `init`, `run`, `list`, `resume`, `validate`, `status`
|
|
71
|
+
</command>
|
|
72
|
+
|
|
73
|
+
</commands_reference>
|
|
74
|
+
|
|
75
|
+
<keyboard_shortcuts>
|
|
76
|
+
- **ctrl+h** — Pause running workflow
|
|
77
|
+
- **ctrl+j** — Resume paused workflow
|
|
78
|
+
</keyboard_shortcuts>
|
|
79
|
+
|
|
80
|
+
<bundled_resources>
|
|
81
|
+
21 agents, 11 schemas, 14 workflows, 28 templates bundled.
|
|
82
|
+
See references/bundled-resources.md for full inventory.
|
|
83
|
+
</bundled_resources>
|
|
84
|
+
|
|
85
|
+
<objective>
|
|
86
|
+
pi-workflows orchestrates multi-step agent workflows defined in YAML. Workflows are DAGs of typed steps with data flow via `${{ }}` expressions.
|
|
87
|
+
</objective>
|
|
88
|
+
|
|
89
|
+
<workflow_discovery>
|
|
90
|
+
Workflows are discovered from three locations (first match wins):
|
|
91
|
+
1. `.workflows/*.workflow.yaml` — project-level
|
|
92
|
+
2. `~/.pi/agent/workflows/*.workflow.yaml` — user-level
|
|
93
|
+
3. Package bundled `workflows/` — built-in
|
|
94
|
+
</workflow_discovery>
|
|
95
|
+
|
|
96
|
+
<step_types>
|
|
97
|
+
| Type | Field | Description |
|
|
98
|
+
|------|-------|-------------|
|
|
99
|
+
| agent | `agent: name` | Dispatch an LLM subprocess via `pi --mode json` |
|
|
100
|
+
| command | `command: "..."` | Run a shell command, capture stdout as output |
|
|
101
|
+
| monitor | `monitor: name` | Run a monitor classification as a verification gate |
|
|
102
|
+
| transform | `transform: { mapping: {...} }` | Pure data transformation via expressions, no LLM |
|
|
103
|
+
| gate | `gate: { check: "..." }` | Shell command exit code as pass/fail boolean |
|
|
104
|
+
| loop | `loop: { maxAttempts, steps }` | Repeat sub-steps until gate breaks or max reached |
|
|
105
|
+
| parallel | `parallel: { a: ..., b: ... }` | Run named sub-steps concurrently |
|
|
106
|
+
| pause | `pause: true` or `pause: "message"` | Pause execution, resumable later |
|
|
107
|
+
| forEach | `forEach: "${{ expr }}"` | Iterate over an array, executing the step per element |
|
|
108
|
+
</step_types>
|
|
109
|
+
|
|
110
|
+
<expression_syntax>
|
|
111
|
+
`${{ expression }}` resolves against scope: `input`, `steps`, `loop`, `forEach`.
|
|
112
|
+
|
|
113
|
+
Access step outputs: `${{ steps.investigate.output.findings }}`
|
|
114
|
+
Filters: `${{ steps.analyze.output | json }}`, `${{ items | length }}`, `${{ name | upper }}`
|
|
115
|
+
|
|
116
|
+
Available filters: length, keys, filter, json, upper, lower, trim, default, first, last, join, split, replace, includes, map, sum, min, max, sort, unique, flatten, zip, group_by, count_by, chunk, pick, omit, entries, from_entries, merge, values, not, and, or.
|
|
117
|
+
</expression_syntax>
|
|
118
|
+
|
|
119
|
+
<agent_resolution>
|
|
120
|
+
Agent specs (`.agent.yaml`) are resolved from three locations (first match wins):
|
|
121
|
+
1. `.pi/agents/<name>.agent.yaml` — project-level
|
|
122
|
+
2. `~/.pi/agent/agents/<name>.agent.yaml` — user-level
|
|
123
|
+
3. Package bundled `agents/<name>.agent.yaml` — built-in
|
|
124
|
+
|
|
125
|
+
Agent specs define: model, thinking level, tools, system prompt (or template), task template, output format/schema.
|
|
126
|
+
</agent_resolution>
|
|
127
|
+
|
|
128
|
+
<execution_model>
|
|
129
|
+
1. Steps are ordered by YAML declaration order
|
|
130
|
+
2. DAG planner infers parallelism from `${{ steps.X }}` references
|
|
131
|
+
3. Steps without explicit dependencies run after their predecessor (conservative sequential)
|
|
132
|
+
4. Each step's result is persisted atomically to `<runDir>/state.json`
|
|
133
|
+
5. TUI progress widget shows real-time step status, cost, and timing
|
|
134
|
+
</execution_model>
|
|
135
|
+
|
|
136
|
+
<checkpoint_resume>
|
|
137
|
+
Incomplete runs (failed or paused) are detected on next invocation. If the workflow spec hasn't changed incompatibly, execution resumes from the last completed step. Failed steps are re-executed. Use `fresh: "true"` to force a new run.
|
|
138
|
+
</checkpoint_resume>
|
|
139
|
+
|
|
140
|
+
<output_validation>
|
|
141
|
+
Steps with `output.schema` validate the agent's JSON output against a JSON Schema file. Validation failure marks the step as failed.
|
|
142
|
+
|
|
143
|
+
Use `block:<name>` to reference project block schemas portably: `output.schema: block:project` resolves to `.project/schemas/project.schema.json` from cwd. Works across monorepo, npm install, and user-customized schemas. Combined with `retry: { maxAttempts: 2 }`, the agent gets the schema validation error injected into its retry prompt and can self-correct.
|
|
144
|
+
</output_validation>
|
|
145
|
+
|
|
146
|
+
<retry>
|
|
147
|
+
Steps with `retry: { maxAttempts: N }` are re-executed on failure. Between retries:
|
|
148
|
+
- Project block files are rolled back to pre-attempt state
|
|
149
|
+
- Prior error messages are injected into the prompt
|
|
150
|
+
- Optional `steeringMessage` provides custom retry guidance
|
|
151
|
+
</retry>
|
|
152
|
+
|
|
153
|
+
<completion_messages>
|
|
154
|
+
After execution, the workflow result is injected into the main LLM conversation. The `completion` field controls this: either a `template` (full `${{ }}` template) or `message` + `include` (message text plus resolved data paths).
|
|
155
|
+
</completion_messages>
|
|
156
|
+
|
|
157
|
+
<artifacts>
|
|
158
|
+
Workflows can write post-completion files via the `artifacts` field. Paths may contain `${{ }}` expressions. Artifacts targeting `.project/*.json` are routed through `writeBlock()` for schema validation.
|
|
159
|
+
|
|
160
|
+
Block artifact write failures are fatal — if the data doesn't conform to the block's schema, the workflow fails. Non-block artifact failures remain non-fatal (warning). On resume, all steps are preserved; only artifact processing re-runs, so fixing the schema issue or agent output and resuming avoids re-running expensive LLM steps.
|
|
161
|
+
</artifacts>
|
|
162
|
+
|
|
163
|
+
<validation>
|
|
164
|
+
`validateWorkflow(spec, cwd)` runs authoring-time checks without executing the workflow:
|
|
165
|
+
|
|
166
|
+
1. **Agent resolution** — all referenced agents exist in the three-tier search
|
|
167
|
+
2. **Monitor resolution** — all referenced monitors exist in .pi/monitors/ or built-in examples
|
|
168
|
+
3. **Schema resolution** — all output schema file paths resolve to existing files
|
|
169
|
+
4. **Step reference validity** — `${{ steps.X }}` expressions reference declared steps
|
|
170
|
+
5. **Step ordering** — referenced steps are declared before the referencing step
|
|
171
|
+
6. **Filter name validity** — `${{ value | filter }}` uses known filter names
|
|
172
|
+
|
|
173
|
+
Returns `{ valid: boolean, issues: ValidationIssue[] }` where each issue has severity, message, and field path. Use `/workflow validate` or `/workflow validate <name>` to run from the command line.
|
|
174
|
+
</validation>
|
|
175
|
+
|
|
176
|
+
<success_criteria>
|
|
177
|
+
- Workflow completes all steps without unhandled failures
|
|
178
|
+
- Step outputs match declared output schemas
|
|
179
|
+
- State is persisted atomically after each step
|
|
180
|
+
- Completion message is delivered to main conversation
|
|
181
|
+
- `/workflow validate` returns no errors for authored specs
|
|
182
|
+
- Checkpoint/resume recovers from the last completed step
|
|
183
|
+
</success_criteria>
|
|
184
|
+
|
|
185
|
+
*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Bundled Resources
|
|
2
|
+
|
|
3
|
+
## agents/ (21 files)
|
|
4
|
+
|
|
5
|
+
- `agents/architecture-designer.agent.yaml`
|
|
6
|
+
- `agents/architecture-inferrer.agent.yaml`
|
|
7
|
+
- `agents/audit-fixer.agent.yaml`
|
|
8
|
+
- `agents/code-explorer.agent.yaml`
|
|
9
|
+
- `agents/decomposer.agent.yaml`
|
|
10
|
+
- `agents/gap-identifier.agent.yaml`
|
|
11
|
+
- `agents/handoff-writer.agent.yaml`
|
|
12
|
+
- `agents/investigator.agent.yaml`
|
|
13
|
+
- `agents/pattern-analyzer.agent.yaml`
|
|
14
|
+
- `agents/phase-author.agent.yaml`
|
|
15
|
+
- `agents/plan-creator.agent.yaml`
|
|
16
|
+
- `agents/plan-decomposer.agent.yaml`
|
|
17
|
+
- `agents/project-definer.agent.yaml`
|
|
18
|
+
- `agents/project-inferrer.agent.yaml`
|
|
19
|
+
- `agents/quality-analyzer.agent.yaml`
|
|
20
|
+
- `agents/requirements-gatherer.agent.yaml`
|
|
21
|
+
- `agents/researcher.agent.yaml`
|
|
22
|
+
- `agents/spec-implementer.agent.yaml`
|
|
23
|
+
- `agents/structure-analyzer.agent.yaml`
|
|
24
|
+
- `agents/synthesizer.agent.yaml`
|
|
25
|
+
- `agents/verifier.agent.yaml`
|
|
26
|
+
|
|
27
|
+
## schemas/ (11 files)
|
|
28
|
+
|
|
29
|
+
- `schemas/decomposition-specs.schema.json`
|
|
30
|
+
- `schemas/execution-results.schema.json`
|
|
31
|
+
- `schemas/investigation-findings.schema.json`
|
|
32
|
+
- `schemas/pattern-analysis.schema.json`
|
|
33
|
+
- `schemas/phase.schema.json`
|
|
34
|
+
- `schemas/plan-breakdown.schema.json`
|
|
35
|
+
- `schemas/quality-analysis.schema.json`
|
|
36
|
+
- `schemas/research-findings.schema.json`
|
|
37
|
+
- `schemas/structure-analysis.schema.json`
|
|
38
|
+
- `schemas/synthesis.schema.json`
|
|
39
|
+
- `schemas/verifier-output.schema.json`
|
|
40
|
+
|
|
41
|
+
## workflows/ (14 files)
|
|
42
|
+
|
|
43
|
+
- `workflows/analyze-existing-project.workflow.yaml`
|
|
44
|
+
- `workflows/create-handoff.workflow.yaml`
|
|
45
|
+
- `workflows/create-phase.workflow.yaml`
|
|
46
|
+
- `workflows/do-gap.workflow.yaml`
|
|
47
|
+
- `workflows/fix-audit.workflow.yaml`
|
|
48
|
+
- `workflows/gap-to-phase.workflow.yaml`
|
|
49
|
+
- `workflows/init-new-project.workflow.yaml`
|
|
50
|
+
- `workflows/parallel-analysis.workflow.yaml`
|
|
51
|
+
- `workflows/parallel-explicit.workflow.yaml`
|
|
52
|
+
- `workflows/pausable-analysis.workflow.yaml`
|
|
53
|
+
- `workflows/plan-from-requirements.workflow.yaml`
|
|
54
|
+
- `workflows/resumable-analysis.workflow.yaml`
|
|
55
|
+
- `workflows/self-implement.workflow.yaml`
|
|
56
|
+
- `workflows/typed-analysis.workflow.yaml`
|
|
57
|
+
|
|
58
|
+
## templates/ (28 files)
|
|
59
|
+
|
|
60
|
+
- `templates/analyzers/base-analyzer.md`
|
|
61
|
+
- `templates/analyzers/macros.md`
|
|
62
|
+
- `templates/analyzers/patterns-task.md`
|
|
63
|
+
- `templates/analyzers/patterns.md`
|
|
64
|
+
- `templates/analyzers/quality-task.md`
|
|
65
|
+
- `templates/analyzers/quality.md`
|
|
66
|
+
- `templates/analyzers/structure-task.md`
|
|
67
|
+
- `templates/analyzers/structure.md`
|
|
68
|
+
- `templates/architecture-designer/task.md`
|
|
69
|
+
- `templates/architecture-inferrer/task.md`
|
|
70
|
+
- `templates/audit-fixer/task.md`
|
|
71
|
+
- `templates/decomposer/task.md`
|
|
72
|
+
- `templates/explorer/system.md`
|
|
73
|
+
- `templates/explorer/task.md`
|
|
74
|
+
- `templates/gap-identifier/task.md`
|
|
75
|
+
- `templates/handoff-writer/task.md`
|
|
76
|
+
- `templates/investigator/task.md`
|
|
77
|
+
- `templates/phase-author/task.md`
|
|
78
|
+
- `templates/plan-creator/task.md`
|
|
79
|
+
- `templates/plan-decomposer/task.md`
|
|
80
|
+
- `templates/project-definer/task.md`
|
|
81
|
+
- `templates/project-inferrer/task.md`
|
|
82
|
+
- `templates/requirements-gatherer/task.md`
|
|
83
|
+
- `templates/researcher/task.md`
|
|
84
|
+
- `templates/spec-implementer/task.md`
|
|
85
|
+
- `templates/synthesizer/system.md`
|
|
86
|
+
- `templates/synthesizer/task.md`
|
|
87
|
+
- `templates/verifier/task.md`
|
package/workflows-extension.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { default } from "@davidorex/pi-workflows
|
|
1
|
+
export { default } from "@davidorex/pi-workflows";
|