@davidorex/pi-project-workflows 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davidorex/pi-project-workflows",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Pi extensions for structured project state, workflow orchestration, and behavior monitoring — single install for all three",
 	"license": "MIT",
 	"author": "David Ryan",
@@ -15,18 +15,22 @@
 	"homepage": "https://github.com/davidorex/pi-project-workflows",
 	"files": [
 		"*.ts",
-		"*.md"
+		"*.md",
+		"skills/"
 	],
 	"pi": {
 		"extensions": [
 			"./project-extension.ts",
 			"./workflows-extension.ts",
 			"./monitors-extension.ts"
+		],
+		"skills": [
+			"./skills"
 		]
 	},
 	"dependencies": {
-		"@davidorex/pi-project": "^0.3.0",
-		"@davidorex/pi-workflows": "^0.3.0",
-		"@davidorex/pi-behavior-monitors": "^0.3.0"
+		"@davidorex/pi-project": "^0.3.2",
+		"@davidorex/pi-workflows": "^0.3.2",
+		"@davidorex/pi-behavior-monitors": "^0.3.2"
 	}
 }

package/skills/pi-behavior-monitors/SKILL.md

@@ -0,0 +1,692 @@
+---
+name: pi-behavior-monitors
+description: >
+  Behavior monitors that watch agent activity and steer corrections when issues
+  are detected. Monitors are JSON files (.monitor.json) in .pi/monitors/ with
+  classify, patterns, actions, and scope blocks. Patterns and instructions are
+  JSON arrays. Use when creating, editing, debugging, or understanding behavior
+  monitors.
+---
+
+<tools_reference>
+<tool name="monitors-status">
+List all behavior monitors with their current state.
+
+*List all behavior monitors with their current state*
+
+</tool>
+
+<tool name="monitors-inspect">
+Inspect a monitor — config, state, pattern count, rule count.
+
+*Inspect a monitor — config, state, pattern count, rule count*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `monitor` | string | yes | Monitor name |
+</tool>
+
+<tool name="monitors-control">
+Control monitors — enable, disable, dismiss, or reset.
+
+*Control monitors — enable, disable, dismiss, or reset*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action` | unknown | yes |  |
+| `monitor` | string | no | Monitor name (required for dismiss/reset) |
+</tool>
+
+<tool name="monitors-rules">
+Manage monitor rules — list, add, remove, or replace calibration rules.
+
+*Manage monitor rules — list, add, remove, or replace calibration rules*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `monitor` | string | yes | Monitor name |
+| `action` | unknown | yes |  |
+| `text` | string | no | Rule text (for add/replace) |
+| `index` | number | no | Rule index, 1-based (for remove/replace) |
+</tool>
+
+<tool name="monitors-patterns">
+List patterns for a behavior monitor.
+
+*List patterns for a behavior monitor*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `monitor` | string | yes | Monitor name |
+</tool>
+
+</tools_reference>
+
+<commands_reference>
+<command name="/monitors">
+Manage behavior monitors
+
+Subcommands: `on`, `off`, `fragility`, `response-style`
+</command>
+
+</commands_reference>
+
+<events>
+`session_start`, `session_switch`, `agent_end`, `turn_start`, `message_end`
+</events>
+
+<bundled_resources>
+2 schemas, 20 examples bundled.
+See references/bundled-resources.md for full inventory.
+</bundled_resources>
+
+<monitor_vocabulary>
+
+**Context Collectors:**
+
+| Collector | Placeholder | Description | Limits |
+|-----------|-------------|-------------|--------|
+| `user_text` | `{user_text}` / `{{ user_text }}` | Most recent user message text | — |
+| `assistant_text` | `{assistant_text}` / `{{ assistant_text }}` | Most recent assistant message text | — |
+| `tool_results` | `{tool_results}` / `{{ tool_results }}` | Tool results with tool name and error status | Last 5, truncated 2000 chars |
+| `tool_calls` | `{tool_calls}` / `{{ tool_calls }}` | Tool calls and results interleaved | Last 20, truncated 2000 chars |
+| `custom_messages` | `{custom_messages}` / `{{ custom_messages }}` | Custom extension messages since last user message | — |
+| `project_vision` | `{project_vision}` / `{{ project_vision }}` | .project/project.json vision, core_value, name | — |
+| `project_conventions` | `{project_conventions}` / `{{ project_conventions }}` | .project/conformance-reference.json principle names | — |
+| `git_status` | `{git_status}` / `{{ git_status }}` | Output of git status --porcelain | 5s timeout |
+
+Any string is accepted in `classify.context`. Unknown collector names produce empty string.
+
+Built-in placeholders (always available, not in `classify.context`):
+- `{{ patterns }}` — patterns JSON as numbered list
+- `{{ instructions }}` — instructions JSON as bulleted list with "follow strictly" preamble
+- `{{ iteration }}` — consecutive steer count (0-indexed)
+
+**When Conditions:**
+
+- `always` — Fire every time the event occurs
+- `has_tool_results` — Fire only if tool results present since last user message
+- `has_file_writes` — Fire only if write or edit tool called since last user message
+- `has_bash` — Fire only if bash tool called since last user message
+- `every(N)` — Fire every Nth activation (counter resets when user text changes)
+- `tool(name)` — Fire only if specific named tool called since last user message
+
+**Events:** `message_end`, `turn_end`, `agent_end`, `command`
+
+**Verdict Types:** `clean`, `flag`, `new`
+
+**Scope Targets:** `main`, `subagent`, `all`, `workflow`
+
+</monitor_vocabulary>
+
+<objective>
+Monitors are autonomous watchdogs that observe agent activity, classify it against a
+JSON pattern library using a side-channel LLM call, and either steer corrections or
+write structured findings to JSON files for downstream consumption.
+</objective>
+
+<monitor_locations>
+Monitors are discovered from two locations, checked in order:
+
+1. **Project**: `.pi/monitors/*.monitor.json` (walks up from cwd to find `.pi/`)
+2. **Global**: `~/.pi/agent/monitors/*.monitor.json` (via `getAgentDir()`)
+
+Project monitors take precedence — if a project monitor has the same `name` as a global
+one, the global monitor is ignored. The extension silently exits if zero monitors are
+discovered after checking both locations.
+</monitor_locations>
+
+<seeding>
+On first run in a project, the extension seeds bundled example monitors into
+`.pi/monitors/` if ALL of the following are true:
+
+- `discoverMonitors()` finds zero monitors (neither project nor global)
+- The `examples/` directory exists in the extension package
+- The target `.pi/monitors/` directory contains no `.monitor.json` files
+
+Seeding copies all `.json` files from `examples/` (monitor definitions, patterns, and
+instructions files) into `.pi/monitors/`. It skips files that already exist at the
+destination. The user is notified: "Edit or delete them to customize."
+
+To customize seeded monitors, edit the copies in `.pi/monitors/` directly. To remove a
+bundled monitor, delete its three files (`.monitor.json`, `.patterns.json`,
+`.instructions.json`). Seeding never re-runs once any monitors exist.
+</seeding>
+
+<file_structure>
+Each monitor is a set of files sharing a name prefix:
+
+```
+.pi/monitors/
+├── fragility.monitor.json       # Monitor definition (classify + patterns + actions + scope)
+├── fragility.patterns.json      # Known patterns (JSON array, grows automatically)
+├── fragility.instructions.json  # User corrections (JSON array, optional)
+├── fragility/
+│   └── classify.md              # Nunjucks template for classification prompt (optional)
+```
+
+The instructions file is optional. If omitted, the extension defaults the path to
+`${name}.instructions.json` and treats a missing file as an empty array.
+
+The classify template is optional. When `classify.promptTemplate` is set in the monitor
+definition, the template is resolved through a three-tier search: `.pi/monitors/` (project),
+`~/.pi/agent/monitors/` (user), then the package `examples/` directory. A user overrides a
+bundled template by placing a file at the same relative path in `.pi/monitors/`.
+</file_structure>
+
+<monitor_definition>
+A `.monitor.json` file conforms to `schemas/monitor.schema.json`:
+
+```json
+{
+  "name": "my-monitor",
+  "description": "What this monitor watches for",
+  "event": "message_end",
+  "when": "has_tool_results",
+  "scope": {
+    "target": "main",
+    "filter": { "agent_type": ["audit-fixer"] }
+  },
+  "classify": {
+    "model": "claude-sonnet-4-20250514",
+    "context": ["tool_results", "assistant_text"],
+    "excludes": ["other-monitor"],
+    "promptTemplate": "my-monitor/classify.md",
+    "prompt": "Inline fallback if template not found. {tool_results} {assistant_text} {patterns} {instructions}\n\nReply CLEAN, FLAG:<desc>, or NEW:<pattern>|<desc>."
+  },
+  "patterns": {
+    "path": "my-monitor.patterns.json",
+    "learn": true
+  },
+  "instructions": {
+    "path": "my-monitor.instructions.json"
+  },
+  "actions": {
+    "on_flag": {
+      "steer": "Fix the issue.",
+      "write": {
+        "path": ".workflow/gaps.json",
+        "merge": "append",
+        "array_field": "gaps",
+        "template": {
+          "id": "monitor-{finding_id}",
+          "description": "{description}",
+          "status": "open",
+          "category": "monitor",
+          "source": "monitor"
+        }
+      }
+    },
+    "on_new": {
+      "steer": "Fix the issue.",
+      "learn_pattern": true,
+      "write": { "...": "same as on_flag" }
+    },
+    "on_clean": null
+  },
+  "ceiling": 5,
+  "escalate": "ask"
+}
+```
+</monitor_definition>
+
+<fields>
+
+**Top-level fields:**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `name` | (required) | Monitor identifier. Must be unique across project and global. |
+| `description` | `""` | Human-readable description. Also used as command description for `event: command` monitors. |
+| `event` | `message_end` | When to fire: `message_end`, `turn_end`, `agent_end`, or `command`. |
+| `when` | `always` | Activation condition (see below). |
+| `ceiling` | `5` | Max consecutive steers before escalation. |
+| `escalate` | `ask` | At ceiling: `ask` (confirm with user) or `dismiss` (silence for session). |
+
+**Scope block:**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `scope.target` | `main` | What to observe: `main`, `subagent`, `all`, `workflow`. |
+| `scope.filter.agent_type` | — | Only monitor agents with these names. |
+| `scope.filter.step_name` | — | Glob pattern for workflow step names. |
+| `scope.filter.workflow` | — | Glob pattern for workflow names. |
+
+Steering (injecting messages into the conversation) only fires for `main` scope.
+Non-main scopes can still write findings to JSON files.
+
+**Classify block:**
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `classify.model` | `claude-sonnet-4-20250514` | Model for classification. Plain model ID uses `anthropic` provider. Use `provider/model` for other providers. |
+| `classify.context` | `["tool_results", "assistant_text"]` | Context collector names. Any string accepted — unknown collectors produce empty string. |
+| `classify.excludes` | `[]` | Monitor names — skip activation if any of these already steered this turn. |
+| `classify.promptTemplate` | — | Path to `.md` Nunjucks template file. Searched in `.pi/monitors/`, `~/.pi/agent/monitors/`, then package `examples/`. Takes precedence over `prompt`. |
+| `classify.prompt` | — | Inline classification prompt with `{placeholder}` substitution. Used when `promptTemplate` is absent. One of `promptTemplate` or `prompt` is required. |
+
+**Actions block** — per verdict (`on_flag`, `on_new`, `on_clean`):
+
+| Field | Description |
+|-------|-------------|
+| `steer` | Message to inject into conversation. `null` = no steering. Only effective for `scope.target: "main"`. |
+| `write.path` | JSON file to write findings to. Relative paths resolve from `process.cwd()`, not from the monitor directory. |
+| `write.merge` | `append` (add to array) or `upsert` (update by matching `id` field). |
+| `write.array_field` | Which field in target JSON holds the array (e.g. `"gaps"`, `"findings"`). |
+| `write.template` | Template mapping with `{finding_id}`, `{description}`, `{severity}`, `{monitor_name}`, `{timestamp}`. |
+| `write.schema` | Optional schema path for documentation. Not enforced at runtime. |
+| `learn_pattern` | If true, add new pattern to patterns file on `new` verdict. |
+
+`on_clean` can be configured with a `write` action to log clean verdicts. Setting it to
+`null` means no action on clean (the default behavior).
+</fields>
+
+<!-- when_conditions and context_collectors tables are generated from code registries — see Monitor Vocabulary section in SKILL.md -->
+
+<patterns_file>
+JSON array conforming to `schemas/monitor-pattern.schema.json`:
+
+```json
+[
+  {
+    "id": "empty-catch",
+    "description": "Silently catching exceptions with empty catch blocks",
+    "severity": "error",
+    "category": "error-handling",
+    "examples": ["try { ... } catch {}"],
+    "source": "bundled"
+  },
+  {
+    "id": "learned-pattern-abc",
+    "description": "Learned pattern from runtime detection",
+    "severity": "warning",
+    "source": "learned",
+    "learned_at": "2026-03-15T02:30:00.000Z"
+  }
+]
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | yes | Stable identifier for dedup. Auto-generated for learned patterns: lowercased, non-alphanumeric replaced with hyphens, truncated to 60 chars. |
+| `description` | yes | What this pattern detects. Used for dedup (exact match) when learning. |
+| `severity` | no | `"error"`, `"warning"`, or `"info"`. Defaults to `"warning"` in prompt formatting. |
+| `category` | no | Grouping key (e.g. `"error-handling"`, `"avoidance"`, `"deferral"`). |
+| `examples` | no | Example manifestations. Stored but not surfaced in classification prompts. |
+| `source` | no | `"bundled"`, `"learned"`, or `"user"`. Learned patterns are tagged `"learned"`. |
+| `learned_at` | no | ISO timestamp for learned patterns. |
+
+Patterns grow automatically when `learn_pattern: true` and a `NEW:` verdict is returned.
+Dedup is by exact `description` match — duplicates are silently skipped.
+
+**Critical**: If the patterns array is empty (file missing, empty array, or unparseable),
+classification is skipped entirely for that activation. A monitor with no patterns does nothing.
+</patterns_file>
+
+<instructions_file>
+JSON array of user rules (called "instructions" on disk, "rules" in the command surface):
+
+```json
+[
+  { "text": "grep exit code 1 is not an error", "added_at": "2026-03-15T02:30:00.000Z" },
+  { "text": "catch-and-log in event handlers is correct for non-critical extensions", "added_at": "2026-03-15T03:00:00.000Z" }
+]
+```
+
+Manage via `/monitors <name> rules` (list), `/monitors <name> rules add <text>` (add),
+`/monitors <name> rules remove <n>` (remove by number), `/monitors <name> rules replace <n> <text>`
+(replace by number). The LLM can also edit the `.instructions.json` file directly.
+
+Rules are injected into the classification prompt under a preamble
+"Operating instructions from the user (follow these strictly):" — only if the array is
+non-empty. An empty array or missing file produces no rules block in the prompt.
+</instructions_file>
+
+<prompt_templates>
+Monitors support two prompt rendering modes:
+
+**Inline prompts** (`classify.prompt`) — simple `{placeholder}` string replacement. Good for
+single-paragraph classifiers. All context collectors and built-in placeholders are available
+as `{name}`.
+
+**Nunjucks templates** (`classify.promptTemplate`) — `.md` files with full Nunjucks syntax:
+conditionals (`{% if %}`), loops (`{% for %}`), template inheritance, filters. Used when
+the classify prompt needs conditional sections (e.g., iteration-aware acknowledgment).
+
+Template variables use `{{ name }}` syntax. All context collectors and built-in placeholders
+are available: `{{ patterns }}`, `{{ instructions }}`, `{{ iteration }}`, plus any collectors
+listed in `classify.context`.
+
+When both `promptTemplate` and `prompt` are set, the template is tried first. If the template
+file is not found or fails to render, the inline prompt is used as fallback.
+
+**Iteration-aware acknowledgment pattern** — templates should include this block to support
+monitor-agent dialogue (the agent acknowledging a steer and stating a plan):
+
+```markdown
+{% if iteration > 0 %}
+NOTE: You have steered {{ iteration }} time(s) already this session.
+The agent's latest response is below. If the agent explicitly acknowledged
+the issue and stated a concrete plan to address it (not just "noted" but
+a specific action), reply CLEAN to allow the agent to follow through.
+Re-flag only if the agent ignored or deflected the steer.
+
+Agent response:
+{{ assistant_text }}
+{% endif %}
+```
+
+This requires `assistant_text` in the `classify.context` array. When the classifier sees
+genuine acknowledgment, it replies CLEAN, which resets `whileCount` to 0 and gives the agent
+a fresh turn without re-flagging.
+
+**Template search order** (first match wins):
+1. `.pi/monitors/<template-path>` — project-level override
+2. `~/.pi/agent/monitors/<template-path>` — user-level
+3. Package `examples/<template-path>` — builtin
+
+All four bundled monitors ship with Nunjucks templates in `examples/<name>/classify.md`.
+</prompt_templates>
+
+<verdict_format>
+The classification LLM must respond with one of:
+
+- `CLEAN` — no issue detected. Resets consecutive steer counter to 0.
+- `FLAG:<description>` — known pattern matched. Triggers `on_flag` action.
+- `NEW:<pattern>|<description>` — novel issue. The text before `|` becomes the learned pattern description; the text after `|` becomes the finding description. If no `|` is present, the full text after `NEW:` is used for both. Triggers `on_new` action.
+
+Any response that does not start with `CLEAN`, `FLAG:`, or `NEW:` is treated as `CLEAN`.
+
+Classification calls use `maxTokens: 150`.
+</verdict_format>
+
+<runtime_behavior>
+
+**Dedup**: A monitor will not re-classify the same user text. Once a user message has been
+classified, the monitor skips until the user text changes. This prevents redundant
+side-channel LLM calls within the same user turn.
+
+**Ceiling and escalation**: After `ceiling` consecutive steers (flag/new verdicts without
+an intervening clean), the monitor escalates. With `escalate: "ask"`, the user is prompted
+to continue or dismiss. With `escalate: "dismiss"`, the monitor is silently dismissed for
+the session. A `CLEAN` verdict resets the consecutive steer counter.
+
+**Turn exclusion**: The `excludes` array prevents double-steering. If monitor A steers in
+a turn, and monitor B has `"excludes": ["A"]`, monitor B skips that turn. Exclusion tracking
+resets at `turn_start`.
+
+**Buffered steer delivery**: Monitors on `message_end` or `turn_end` buffer their steer
+messages and deliver them at `agent_end`. This is because pi's async event queue processes
+extension handlers after the agent loop has already checked for steering messages. The
+buffer is drained at `agent_end` — only the first buffered steer fires per agent run; the
+corrected response re-triggers monitors naturally for any remaining issues. Monitors on
+`agent_end` or `command` events deliver steers immediately (they already run post-loop).
+
+**Abort**: Classification calls are aborted when the agent ends (via `agent_end` event).
+Aborted classifications produce no verdict and no action.
+
+**Write action**: Relative `write.path` values resolve from `process.cwd()`, not from the
+monitor directory. Parent directories are created automatically. If the target file doesn't
+exist or is unparseable, a fresh object is created. The `upsert` merge strategy matches on
+the `id` field of array entries.
+</runtime_behavior>
+
+<commands>
+All monitor management is through the `/monitors` command. Subcommands are
+discoverable via pi's TUI autocomplete — typing `/monitors ` shows available
+monitor names and global commands; selecting a monitor shows its verbs.
+
+| Command | Description |
+|---------|-------------|
+| `/monitors` | List all monitors with global on/off state and per-monitor status |
+| `/monitors on` | Enable all monitoring (session default) |
+| `/monitors off` | Pause all monitoring for this session |
+| `/monitors <name>` | Inspect a monitor: description, event, state, rule count, pattern count |
+| `/monitors <name> rules` | List current rules (numbered) |
+| `/monitors <name> rules add <text>` | Add a rule to calibrate the classifier |
+| `/monitors <name> rules remove <n>` | Remove a rule by number |
+| `/monitors <name> rules replace <n> <text>` | Replace a rule by number |
+| `/monitors <name> patterns` | List current patterns (numbered, with severity and source) |
+| `/monitors <name> dismiss` | Dismiss a monitor for this session |
+| `/monitors <name> reset` | Reset a monitor's state and un-dismiss it |
+
+Monitors with `event: "command"` also register `/<name>` as a programmatic trigger
+for other extensions or workflows to invoke classification directly.
+</commands>
+
+<bundled_monitors>
+Four example monitors ship in `examples/` and are seeded on first run. Each has a
+Nunjucks classify template in `examples/<name>/classify.md` with iteration-aware
+acknowledgment support:
+
+**fragility** (`message_end`, `when: has_tool_results`)
+Watches for unaddressed fragilities after tool use — errors, warnings, or broken state the
+agent noticed but chose not to fix. Steers with "Fix the issue you left behind." Writes
+findings to `.workflow/gaps.json` under `category: "fragility"`. Excludes: none. Ceiling: 5.
+12 bundled patterns across categories: avoidance (dismiss-preexisting, not-my-change,
+blame-environment, workaround-over-root-cause, elaborate-workaround-for-fixable),
+error-handling (empty-catch, happy-path-only, early-return-on-unexpected,
+undocumented-delegation, silent-fallback), deferral (todo-instead-of-fix,
+prose-without-action).
+
+**hedge** (`turn_end`, `when: always`)
+Detects when the assistant deviates from what the user actually said — substituting
+questions, projecting intent, or deflecting instead of answering. Steers with "Address
+what the user actually said." Does not write to files (steer-only). Excludes: `["fragility"]`
+(skips if fragility already steered this turn). Ceiling: 3.
+8 bundled patterns across categories: substitution (rephrase-question, reinterpret-words),
+projection (assume-intent, attribute-position), augmentation (add-questions),
+deflection (ask-permission, qualify-yesno, counter-question).
+
+**work-quality** (`command`, `when: always`)
+On-demand work quality analysis invoked via `/work-quality`. Analyzes user request, tool
+calls, and assistant response for quality issues. Writes findings to `.workflow/gaps.json`
+under `category: "work-quality"`. Ceiling: 3.
+11 bundled patterns across categories: methodology (trial-and-error, symptom-fix,
+double-edit, edit-without-read, insanity-retry, no-plan), verification (no-verify),
+scope (excessive-changes, wrong-problem), quality (copy-paste), cleanup (debug-artifacts).
+
+**commit-hygiene** (`agent_end`, `when: has_file_writes`)
+Fires when the agent finishes a turn that included file writes. Checks tool call history
+for git commit commands. If no commit occurred, steers to commit. If committed with a
+generic or certainty-language message, steers to improve. Does not write findings — commits
+are their own artifact. Ceiling: 3.
+6 bundled patterns across categories: missing-commit (no-commit), message-quality
+(generic-message, certainty-language, no-context), commit-safety (amend-not-new, force-push).
+</bundled_monitors>
+
+<disabling_monitors>
+**Session-level** (temporary):
+- `/monitors off` — pauses all monitoring for the current session
+- `/monitors <name> dismiss` — silences a single monitor for the session
+- `/monitors <name> reset` — un-dismisses and resets a monitor's state
+
+**Permanent**:
+- Delete its `.monitor.json` file (and optionally its `.patterns.json` and `.instructions.json`)
+- Or empty its patterns array — a monitor with zero patterns skips classification entirely
+- To disable all monitoring: remove all `.monitor.json` files from `.pi/monitors/` and
+  `~/.pi/agent/monitors/`. The extension exits silently when zero monitors are discovered.
+
+Monitors also auto-silence at their ceiling. With `escalate: "ask"`, the user is prompted
+to continue or dismiss. With `escalate: "dismiss"`, the monitor silences automatically.
+</disabling_monitors>
+
+<creating_monitors>
+When the user asks to create a monitor — either from a described behavior ("flag responses
+that end with questions") or from a discovered need during conversation ("that response
+did X wrong, make a monitor for it") — follow this workflow:
+
+**Step 1: Determine the detection target.** What specific behavior in the assistant's output
+should trigger a flag? Translate the user's description into concrete, observable patterns.
+
+**Step 2: Choose event and when.** Match the detection target to the right trigger:
+- Response content issues (trailing questions, lazy options, tone) → `turn_end`, `when: always`
+- Tool use issues (no commit, no test, bad edits) → `agent_end`, `when: has_file_writes` or `has_tool_results`
+- Post-action fragility (ignoring errors) → `message_end`, `when: has_tool_results`
+- On-demand analysis → `command`, `when: always`
+
+**Step 3: Choose context collectors.** What data does the classifier need to see?
+- Checking the assistant's final response text → `assistant_text`
+- Checking what the user asked (to compare against response) → `user_text`
+- Checking what tools were called → `tool_calls`
+- Checking tool outputs for errors/warnings → `tool_results`
+- Checking git state → `git_status`
+- Include `assistant_text` if you want iteration-aware acknowledgment (recommended).
+
+**Step 4: Write the patterns file.** Each pattern is a specific, observable anti-pattern.
+Write descriptions that a classifier LLM can match against the collected context. Start with
+3-8 seed patterns. Set `learn: true` so the monitor grows its pattern library from `NEW:`
+verdicts at runtime.
+
+**Step 5: Write the classify template.** Use a Nunjucks `.md` file for anything beyond
+trivial classification. The template must:
+- Present the collected context to the classifier
+- List the patterns to check against
+- Include the verdict format instructions (CLEAN/FLAG/NEW)
+- Include the iteration-aware acknowledgment block if `assistant_text` is collected
+
+**Step 6: Write the monitor definition.** Wire everything together in the `.monitor.json`.
+
+**Step 7: Create empty instructions file.** Write `[]` so the user can add calibration
+rules via `/monitors <name> rules add <text>`.
+
+**Step 8: Activate.** After creating the files, tell the user to run `/reload 3` to
+reload extensions and activate the new monitor without restarting the session.
+
+### Example: response-mandates monitor
+
+User says: "create a monitor that flags responses ending with questions and responses
+that present lazy deferral options."
+
+**Files to create:**
+
+1. `.pi/monitors/response-mandates.monitor.json`:
+
+```json
+{
+  "name": "response-mandates",
+  "description": "Flags responses that violate communication mandates: trailing questions, lazy deferral options, non-optimal solutions",
+  "event": "turn_end",
+  "when": "always",
+  "scope": { "target": "main" },
+  "classify": {
+    "model": "claude-sonnet-4-20250514",
+    "context": ["assistant_text", "user_text"],
+    "excludes": ["fragility"],
+    "promptTemplate": "response-mandates/classify.md"
+  },
+  "patterns": { "path": "response-mandates.patterns.json", "learn": true },
+  "instructions": { "path": "response-mandates.instructions.json" },
+  "actions": {
+    "on_flag": { "steer": "Rewrite your response: report findings and state actions — do not end with a question or present options that defer proper work." },
+    "on_new": { "steer": "Rewrite your response: report findings and state actions — do not end with a question or present options that defer proper work.", "learn_pattern": true },
+    "on_clean": null
+  },
+  "ceiling": 3,
+  "escalate": "ask"
+}
+```
+
+2. `.pi/monitors/response-mandates/classify.md`:
+
+```markdown
+The user said:
+"{{ user_text }}"
+
+The assistant's response:
+"{{ assistant_text }}"
+
+{{ instructions }}
+
+Check the assistant's response against these anti-patterns:
+{{ patterns }}
+
+Specifically check:
+1. Does the response end with a question to the user? The final sentence or paragraph
+   should not be a question unless the user explicitly asked to be consulted. Rhetorical
+   questions, permission-seeking ("shall I...?", "would you like...?"), and steering
+   questions ("what do you think?") are all violations.
+2. Does the response present options where one or more options leave known issues
+   unaddressed? If a problem has been identified, every option presented must address it.
+   Options that defer proper work to a vague future ("we could address this later",
+   "for now we can...") are violations.
+3. Does the response propose a non-durable solution when a durable one is known? Workarounds,
+   temporary fixes, and partial solutions when the root cause is understood are violations.
+
+{% if iteration > 0 %}
+NOTE: You have steered {{ iteration }} time(s) already this session.
+If the agent explicitly acknowledged the mandate violation and rewrote its response
+without the violation, reply CLEAN. Re-flag only if the violation persists.
+
+Agent response:
+{{ assistant_text }}
+{% endif %}
+
+Reply CLEAN if the response follows all mandates.
+Reply FLAG:<description> if a known pattern was matched.
+Reply NEW:<pattern>|<description> if a violation not covered by existing patterns was detected.
+```
+
+3. `.pi/monitors/response-mandates.patterns.json`:
+
+```json
+[
+  { "id": "trailing-question", "description": "Response ends with a question to the user instead of reporting and acting", "severity": "error", "category": "communication", "source": "bundled" },
+  { "id": "permission-seeking", "description": "Asks permission before acting when the user has already given direction", "severity": "warning", "category": "communication", "source": "bundled" },
+  { "id": "steering-question", "description": "Ends with 'what do you think?', 'does that sound right?', or similar steering questions", "severity": "error", "category": "communication", "source": "bundled" },
+  { "id": "lazy-deferral", "description": "Presents options that defer known issues to a vague future ('we can address later', 'for now')", "severity": "error", "category": "anti-laziness", "source": "bundled" },
+  { "id": "fragility-tolerant-option", "description": "Offers an option that leaves identified fragility unaddressed", "severity": "error", "category": "anti-laziness", "source": "bundled" },
+  { "id": "workaround-over-fix", "description": "Proposes workaround when root cause is understood and fixable", "severity": "warning", "category": "anti-laziness", "source": "bundled" }
+]
+```
+
+4. `.pi/monitors/response-mandates.instructions.json`:
+
+```json
+[]
+```
+
+After creating all files, tell the user: "Monitor created. Run `/reload 3` to activate
+it in this session."
+</creating_monitors>
+
+<modifying_monitors>
+**Adding patterns** — When the user identifies a new anti-pattern during conversation
+("that kind of response should also be flagged"), add it to the patterns JSON file.
+Each pattern needs `id`, `description`, `severity`, and `source: "user"`.
+
+**Adding rules** — Use the `monitors-rules` tool or `/monitors <name> rules add <text>`
+to add calibration rules. Rules fine-tune the classifier without changing patterns.
+Example: "responses that end with 'let me know' are not questions."
+
+**Changing the classify prompt** — Edit the Nunjucks template file or the inline prompt.
+For template-based monitors, edit the `.md` file. For inline monitors, edit the `prompt`
+field in the `.monitor.json`.
+
+**Upgrading inline to template** — When a monitor needs conditionals (iteration-aware
+acknowledgment, optional context sections), create a `<name>/classify.md` template file
+in `.pi/monitors/` and add `"promptTemplate": "<name>/classify.md"` to the classify block.
+The inline `prompt` remains as fallback.
+
+**Adjusting sensitivity** — Lower the `ceiling` to escalate sooner if the monitor is
+over-firing. Raise it to give the agent more chances. Set `escalate: "dismiss"` to
+auto-silence without prompting.
+
+After any file changes, tell the user to run `/reload 3` to pick up the changes.
+</modifying_monitors>
+
+<success_criteria>
+- Monitor `.monitor.json` validates against `schemas/monitor.schema.json`
+- Patterns `.patterns.json` validates against `schemas/monitor-pattern.schema.json`
+- Patterns array is non-empty (empty patterns = monitor does nothing)
+- Classification prompt (template or inline) includes `{{ patterns }}` / `{patterns}` and verdict format instructions (CLEAN/FLAG/NEW)
+- If using `promptTemplate`, the `.md` file exists at the declared path relative to one of the template search directories
+- If using templates, `assistant_text` is in `classify.context` for iteration-aware acknowledgment
+- Actions specify `steer` for `scope.target: "main"` monitors, `write` for findings output
+- `write.path` is set relative to project cwd, not monitor directory
+- `excludes` lists monitors that should not double-steer in the same turn
+- Instructions file exists (even if empty `[]`) to enable `/monitors <name> rules add <text>` calibration
+- After creating or modifying monitor files, remind user to run `/reload 3`
+</success_criteria>
+
+*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

package/skills/pi-behavior-monitors/references/bundled-resources.md

@@ -0,0 +1,29 @@
+# Bundled Resources
+
+## schemas/ (2 files)
+
+- `schemas/monitor-pattern.schema.json`
+- `schemas/monitor.schema.json`
+
+## examples/ (20 files)
+
+- `examples/commit-hygiene/classify.md`
+- `examples/commit-hygiene.instructions.json`
+- `examples/commit-hygiene.monitor.json`
+- `examples/commit-hygiene.patterns.json`
+- `examples/fragility/classify.md`
+- `examples/fragility.instructions.json`
+- `examples/fragility.monitor.json`
+- `examples/fragility.patterns.json`
+- `examples/hedge/classify.md`
+- `examples/hedge.instructions.json`
+- `examples/hedge.monitor.json`
+- `examples/hedge.patterns.json`
+- `examples/unauthorized-action/classify.md`
+- `examples/unauthorized-action.instructions.json`
+- `examples/unauthorized-action.monitor.json`
+- `examples/unauthorized-action.patterns.json`
+- `examples/work-quality/classify.md`
+- `examples/work-quality.instructions.json`
+- `examples/work-quality.monitor.json`
+- `examples/work-quality.patterns.json`

package/skills/pi-project/SKILL.md

@@ -0,0 +1,231 @@
+---
+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 (gaps, decisions, or any user-defined block)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `block` | string | yes | Block name (e.g., 'gaps', 'decisions') |
+| `arrayKey` | string | yes | Array key in the block (e.g., 'gaps', '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., 'gaps', 'decisions') |
+| `arrayKey` | string | yes | Array key in the block |
+| `match` | object | yes | Fields to match (e.g., { id: 'gap-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., 'gaps', '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>
+
+</tools_reference>
+
+<commands_reference>
+<command name="/project">
+Project state management
+
+Subcommands: `init`, `status`, `add-work`, `validate`
+</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? |
+| `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) |
+| `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? |
+| `handoff` | Handoff | `current_tasks` |  |
+| `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 |
+| `gaps` | `status` | open, resolved, deferred |
+| `gaps` | `category` | missing, incomplete, defect, improvement, technical-debt, question |
+| `gaps` | `priority` | low, medium, high, critical |
+| `gaps` | `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

@@ -0,0 +1,26 @@
+# Bundled Resources
+
+## defaults/ (22 files)
+
+- `defaults/blocks/conformance-reference.json`
+- `defaults/blocks/decisions.json`
+- `defaults/blocks/domain.json`
+- `defaults/blocks/gaps.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/gaps.schema.json`
+- `defaults/schemas/handoff.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`

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

@@ -0,0 +1,42 @@
+---
+name: pi-project-workflows
+description: >
+  Meta-package re-exporting pi-project (schema-driven project state),
+  pi-workflows (workflow orchestration), and pi-behavior-monitors (autonomous
+  behavior monitoring). Install once to get all three extensions.
+---
+
+<objective>
+This meta-package re-exports all three extensions. Install once to get everything:
+
+```
+pi install npm:@davidorex/pi-project-workflows
+```
+</objective>
+
+<included_extensions>
+<extension name="@davidorex/pi-project">
+Schema-driven project state management for Pi
+
+**Tools:** `append-block-item`, `update-block-item`, `read-block`, `write-block`, `project-status`, `project-validate`, `project-init`
+**Commands:** `/project`
+</extension>
+
+<extension name="@davidorex/pi-workflows">
+Workflow orchestration extension for Pi
+
+**Tools:** `workflow`, `workflow-list`, `workflow-agents`, `workflow-validate`, `workflow-status`, `workflow-init`
+**Commands:** `/workflow`
+**Shortcuts:** ctrl+h (Pause running workflow), ctrl+j (Resume paused workflow)
+</extension>
+
+<extension name="@davidorex/pi-behavior-monitors">
+Behavior monitors for pi that watch agent activity and steer corrections
+
+**Tools:** `monitors-status`, `monitors-inspect`, `monitors-control`, `monitors-rules`, `monitors-patterns`
+**Commands:** `/monitors`
+</extension>
+
+</included_extensions>
+
+*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

package/skills/pi-workflows/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: pi-workflows
+description: >
+  Orchestrates multi-step agent workflows defined in YAML with DAG-based
+  execution, typed data flow, checkpoint/resume, and output validation. Use when
+  running workflows, authoring workflow specs, debugging step failures, or
+  inspecting agent configurations.
+---
+
+<tools_reference>
+<tool name="workflow">
+Run a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/.
+
+*Run a multi-step workflow with typed data flow between agents*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow` | string | yes | Name of the workflow to run |
+| `input` | unknown | no | Input data for the workflow (validated against workflow's input schema) |
+| `fresh` | string | no | Set to 'true' to start a fresh run, ignoring any incomplete prior runs |
+</tool>
+
+<tool name="workflow-list">
+List available workflows with names, descriptions, and sources.
+
+*List available workflows with names, descriptions, and sources*
+
+</tool>
+
+<tool name="workflow-agents">
+List available agents with full specs, or inspect a single agent by name. Returns role, description, model, tools, output format/schema, prompt template paths.
+
+*List available agents with specs, or inspect a single agent by name*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | no | Agent name to inspect (omit to list all) |
+</tool>
+
+<tool name="workflow-validate">
+Validate workflow specs — check agents, schemas, step references, and filters.
+
+*Validate workflow specs — check agents, schemas, step references, filters*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | no | Workflow name to validate (omit to validate all) |
+</tool>
+
+<tool name="workflow-status">
+Get workflow vocabulary — step types, filters, available agents, workflows, schemas, templates.
+
+*Get workflow vocabulary — step types, filters, available agents, workflows, schemas*
+
+</tool>
+
+<tool name="workflow-init">
+Initialize .workflows/ directory for workflow run state.
+
+*Initialize .workflows/ directory for workflow run state*
+
+</tool>
+
+</tools_reference>
+
+<commands_reference>
+<command name="/workflow">
+List and run workflows
+
+Subcommands: `init`, `run`, `list`, `resume`, `validate`, `status`
+</command>
+
+</commands_reference>
+
+<keyboard_shortcuts>
+- **ctrl+h** — Pause running workflow
+- **ctrl+j** — Resume paused workflow
+</keyboard_shortcuts>
+
+<bundled_resources>
+21 agents, 11 schemas, 14 workflows, 28 templates bundled.
+See references/bundled-resources.md for full inventory.
+</bundled_resources>
+
+<objective>
+pi-workflows orchestrates multi-step agent workflows defined in YAML. Workflows are DAGs of typed steps with data flow via `${{ }}` expressions.
+</objective>
+
+<workflow_discovery>
+Workflows are discovered from three locations (first match wins):
+1. `.workflows/*.workflow.yaml` — project-level
+2. `~/.pi/agent/workflows/*.workflow.yaml` — user-level
+3. Package bundled `workflows/` — built-in
+</workflow_discovery>
+
+<step_types>
+| Type | Field | Description |
+|------|-------|-------------|
+| agent | `agent: name` | Dispatch an LLM subprocess via `pi --mode json` |
+| command | `command: "..."` | Run a shell command, capture stdout as output |
+| monitor | `monitor: name` | Run a monitor classification as a verification gate |
+| transform | `transform: { mapping: {...} }` | Pure data transformation via expressions, no LLM |
+| gate | `gate: { check: "..." }` | Shell command exit code as pass/fail boolean |
+| 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 |
+</step_types>
+
+<expression_syntax>
+`${{ expression }}` resolves against scope: `input`, `steps`, `loop`, `forEach`.
+
+Access step outputs: `${{ steps.investigate.output.findings }}`
+Filters: `${{ steps.analyze.output | json }}`, `${{ items | length }}`, `${{ name | upper }}`
+
+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.
+</expression_syntax>
+
+<agent_resolution>
+Agent specs (`.agent.yaml`) are resolved from three locations (first match wins):
+1. `.pi/agents/<name>.agent.yaml` — project-level
+2. `~/.pi/agent/agents/<name>.agent.yaml` — user-level
+3. Package bundled `agents/<name>.agent.yaml` — built-in
+
+Agent specs define: model, thinking level, tools, system prompt (or template), task template, output format/schema.
+</agent_resolution>
+
+<execution_model>
+1. Steps are ordered by YAML declaration order
+2. DAG planner infers parallelism from `${{ steps.X }}` references
+3. Steps without explicit dependencies run after their predecessor (conservative sequential)
+4. Each step's result is persisted atomically to `<runDir>/state.json`
+5. TUI progress widget shows real-time step status, cost, and timing
+</execution_model>
+
+<checkpoint_resume>
+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.
+</checkpoint_resume>
+
+<output_validation>
+Steps with `output.schema` validate the agent's JSON output against a JSON Schema file. Validation failure marks the step as failed.
+
+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.
+</output_validation>
+
+<retry>
+Steps with `retry: { maxAttempts: N }` are re-executed on failure. Between retries:
+- Project block files are rolled back to pre-attempt state
+- Prior error messages are injected into the prompt
+- Optional `steeringMessage` provides custom retry guidance
+</retry>
+
+<completion_messages>
+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).
+</completion_messages>
+
+<artifacts>
+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.
+
+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.
+</artifacts>
+
+<validation>
+`validateWorkflow(spec, cwd)` runs authoring-time checks without executing the workflow:
+
+1. **Agent resolution** — all referenced agents exist in the three-tier search
+2. **Monitor resolution** — all referenced monitors exist in .pi/monitors/ or built-in examples
+3. **Schema resolution** — all output schema file paths resolve to existing files
+4. **Step reference validity** — `${{ steps.X }}` expressions reference declared steps
+5. **Step ordering** — referenced steps are declared before the referencing step
+6. **Filter name validity** — `${{ value | filter }}` uses known filter names
+
+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.
+</validation>
+
+<success_criteria>
+- Workflow completes all steps without unhandled failures
+- Step outputs match declared output schemas
+- State is persisted atomically after each step
+- Completion message is delivered to main conversation
+- `/workflow validate` returns no errors for authored specs
+- Checkpoint/resume recovers from the last completed step
+</success_criteria>
+
+*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

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`