@harms-haus/pi-workflows 1.0.0

package/docs/template-variables.md

@@ -0,0 +1,383 @@
+# Template Variables Reference
+
+## Overview
+
+Pi-workflows uses a `{varName}` template syntax throughout its configurable strings — phase instructions, role instructions, block reasons, completion messages, and more. Templates are resolved by `resolveTemplate()` in `src/config/templates.ts`.
+
+**Resolution rules:**
+
+| Rule                 | Behavior                                                            |
+| -------------------- | ------------------------------------------------------------------- |
+| Matching `{varName}` | Replaced with the corresponding value from the variables map        |
+| Unknown `{varName}`  | **Left as-is** — the literal text `{varName}` remains in the output |
+| No curly braces      | Plain text passes through unchanged                                 |
+
+```typescript
+// Simplified from src/config/templates.ts
+function resolveTemplate(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{(\w+)\}/g, (_match, key: string) => {
+    return Object.hasOwn(vars, key) ? vars[key] : `{${key}}`;
+  });
+}
+```
+
+> **Where to use templates:** Any configurable string in a workflow definition can contain template variables — `initialMessage`, `roleInstruction`, `advanceReminder`, `blockReasonTemplate`, `completionMessage`, `notDoneReminder`, and each phase's `instructions` frontmatter body. See [Configuration Reference](configuration-reference.md) for where each field lives.
+
+---
+
+## Variable Availability by Context
+
+Variables are resolved in different contexts with different sets available. The table below summarizes which variables exist in each context; detailed tables follow.
+
+| Variable               | `initialMessage` | Phase Instructions / Context Prompt | `blockReasonTemplate` | `completionMessage` | Cancel case | `notDoneReminder` |
+| ---------------------- | :--------------: | :---------------------------------: | :-------------------: | :-----------------: | :---------: | :---------------: |
+| `{workflowName}`       |        ✅        |                 ✅                  |          ✅           |         ✅          |     ✅      |        ✅         |
+| `{workflowKey}`        |        ✅        |                 ✅                  |           —           |          —          |      —      |        ✅         |
+| `{description}`        |        ✅        |                 ✅                  |           —           |          —          |      —      |         —         |
+| `{taskDescription}`    |        —         |                  —                  |           —           |         ✅          |     ✅      |        ✅         |
+| `{taskId}`             |        —         |                 ✅                  |           —           |         ✅          |     ✅      |        ✅         |
+| `{phaseId}`            |        —         |                 ✅                  |           —           |          —          |      —      |         —         |
+| `{phaseName}`          |        —         |                 ✅                  |          ✅           |          —          |      —      |        ✅         |
+| `{previousPhaseName}`  |        —         |                 ✅                  |           —           |          —          |      —      |         —         |
+| `{nextPhaseName}`      |        —         |                 ✅                  |           —           |          —          |      —      |         —         |
+| `{blockedToolsList}`   |        —         |                 ✅                  |           —           |          —          |      —      |         —         |
+| `{toolName}`           |        —         |                 ✅                  |          ✅           |          —          |      —      |         —         |
+| `{breadcrumbPath}`     |        —         |                 ✅                  |           —           |          —          |      —      |         —         |
+| `{globalStepCount}`    |        —         |                 ✅                  |           —           |          —          |      —      |         —         |
+| `{phaseEmoji}`         |        —         |                  —                  |           —           |          —          |      —      |        ✅         |
+| `{phaseInstructions}`  |        —         |                  —                  |           —           |          —          |      —      |        ✅         |
+| `{phaseCount}`         |        —         |                  —                  |           —           |         ✅          |     ✅      |         —         |
+| `{allowedTools}`       |        —         |                  —                  |          ✅           |          —          |      —      |         —         |
+| `{firstPhaseId}`       |        ✅        |                  —                  |           —           |          —          |      —      |         —         |
+| `{firstPhaseName}`     |        ✅        |                  —                  |           —           |          —          |      —      |         —         |
+| `{firstPhaseEmoji}`    |        ✅        |                  —                  |           —           |          —          |      —      |         —         |
+| `{firstPhaseProfiles}` |        ✅        |                  —                  |           —           |          —          |      —      |         —         |
+
+> **Note:** There is no separate `cancelledMessage` field on `WorkflowDefinition`. The cancellation path reuses `completionMessage` with `DEFAULT_CANCELLED_MESSAGE` as fallback. See [Cancelled Message](#cancelled-message) below.
+
+---
+
+## `initialMessage` Variables
+
+Resolved once when the workflow starts (in `src/command.ts`). The `initialMessage` field is defined in `workflow.yaml`.
+
+| Variable               | Source                                                        | Example Value                     |
+| ---------------------- | ------------------------------------------------------------- | --------------------------------- |
+| `{workflowName}`       | `definition.name`                                             | `Refine, Plan, Implement, Review` |
+| `{workflowKey}`        | Definition map key                                            | `rpir`                            |
+| `{description}`        | User's description argument (trimmed)                         | `Add login page`                  |
+| `{firstPhaseId}`       | First concrete phase's `id`                                   | `refine`                          |
+| `{firstPhaseName}`     | First concrete phase's `name`                                 | `Refine Requirements`             |
+| `{firstPhaseEmoji}`    | First concrete phase's `emoji`                                | `🔍`                              |
+| `{firstPhaseProfiles}` | First phase's `availableProfiles` joined by `, `, or `(none)` | `planner, researcher`             |
+
+**Example template:**
+
+```yaml
+# workflow.yaml
+initialMessage: |
+  Starting {workflowName} ({workflowKey}).
+  Task: {description}
+  First phase: {firstPhaseEmoji} {firstPhaseName} ({firstPhaseId})
+  Available profiles: {firstPhaseProfiles}
+```
+
+**Resolved output:**
+
+```
+Starting Refine, Plan, Implement, Review (rpir).
+Task: Add login page
+First phase: 🔍 Refine Requirements (refine)
+Available profiles: planner, researcher
+```
+
+> **Note:** If the first phase entry is a subworkflow reference, resolution drills into it to find the first concrete phase.
+
+---
+
+## Phase Instructions Variables
+
+Available inside every phase's `instructions` body (the markdown content in each `.md` phase file). Also available in `roleInstruction` and `advanceReminder` — see [Context Prompt Variables](#context-prompt-variables) below.
+
+Resolved per-turn in `buildContextPrompt()` (`src/prompts.ts`).
+
+| Variable              | Source                                         | Example Value                     |
+| --------------------- | ---------------------------------------------- | --------------------------------- |
+| `{workflowName}`      | Top-level workflow `name`                      | `Refine, Plan, Implement, Review` |
+| `{workflowKey}`       | `state.workflowKey`                            | `rpir`                            |
+| `{description}`       | User's original description                    | `Add login page`                  |
+| `{taskId}`            | Generated task ID                              | `wf-1747234567890-a3f2k1`         |
+| `{phaseId}`           | Current phase `id`                             | `implement`                       |
+| `{phaseName}`         | Current phase `name`                           | `Implementation`                  |
+| `{previousPhaseName}` | Previous phase's `name`, or `(start)` if first | `Planning`                        |
+| `{nextPhaseName}`     | Next phase's `name`, or `DONE` if last         | `Review`                          |
+| `{blockedToolsList}`  | Blocked tools joined by `, `, or `(none)`      | `edit, write`                     |
+| `{toolName}`          | Always `"workflow_step"`                       | `workflow_step`                   |
+| `{breadcrumbPath}`    | Breadcrumb trail joined by `>`                 | `RPIR > Implementation`           |
+| `{globalStepCount}`   | Monotonically increasing step counter          | `3`                               |
+
+**Example phase instructions:**
+
+```markdown
+---
+id: implement
+name: Implementation
+emoji: ⚙️
+---
+
+You are in phase **{phaseName}** of **{workflowName}** (step {globalStepCount}).
+
+Task: {description} (ID: {taskId})
+
+The previous phase ({previousPhaseName}) produced a plan. Now implement it.
+When done, use `{toolName}` to advance to {nextPhaseName}.
+
+Blocked tools: {blockedToolsList}
+```
+
+**Resolved output (inside context prompt):**
+
+```
+You are in phase **Implementation** of **Refine, Plan, Implement, Review** (step 3).
+
+Task: Add login page (ID: wf-1747234567890-a3f2k1)
+
+The previous phase (Planning) produced a plan. Now implement it.
+When done, use `workflow_step` to advance to Review.
+
+Blocked tools: edit, write
+```
+
+---
+
+## Context Prompt Variables
+
+The **context prompt** is injected as a hidden message before every agent turn via `buildContextPrompt()` in `src/prompts.ts`. It composes several template strings together using the **same variable map** as phase instructions.
+
+The following configurable templates all receive the full phase instructions variable set:
+
+| Template Field       | Purpose                                                         |
+| -------------------- | --------------------------------------------------------------- |
+| `roleInstruction`    | Prepended to every context injection — defines the agent's role |
+| `advanceReminder`    | Appended to every context injection — reminds agent to advance  |
+| Phase `instructions` | The main body of what the agent should do this phase            |
+
+All three are resolved with the identical variable map documented in [Phase Instructions Variables](#phase-instructions-variables) above.
+
+---
+
+## Block Reason Variables
+
+Resolved when a tool call is blocked during a phase (in `src/hooks.ts`, `handleToolCall()`). Used by the `blockReasonTemplate` field.
+
+| Variable         | Source                           | Example Value                               |
+| ---------------- | -------------------------------- | ------------------------------------------- |
+| `{workflowName}` | `definition.name`                | `Refine, Plan, Implement, Review`           |
+| `{phaseName}`    | Current phase `name`             | `Refine Requirements`                       |
+| `{toolName}`     | The tool name that was blocked   | `edit`                                      |
+| `{allowedTools}` | Description of what _is_ allowed | `all except: edit, write` or `read, search` |
+
+The `{allowedTools}` value depends on the tool restriction mode:
+
+- **Blacklist mode:** `"all except: " + blockedTools.join(", ")` → e.g. `all except: edit, write`
+- **Whitelist mode:** `whitelist.join(", ")` → e.g. `read, search`
+
+> **Note:** `workflow_step` is always allowed regardless of blacklist or whitelist configuration, but it is **not** included in the `{allowedTools}` value for whitelist mode. It will never appear in the resolved template.
+
+**Example:**
+
+Template:
+
+```
+[workflow] "{toolName}" is blocked during {phaseName}.
+Allowed: {allowedTools}. Use workflow_step when done.
+```
+
+Resolved (blacklist):
+
+```
+[workflow] "edit" is blocked during Refine Requirements.
+Allowed: all except: edit, write. Use workflow_step when done.
+```
+
+---
+
+## Completion & Reminder Variables
+
+### Completion Message (`completionMessage`)
+
+Resolved when the workflow reaches the DONE state.
+
+| Variable            | Source                                 | Example Value                     |
+| ------------------- | -------------------------------------- | --------------------------------- |
+| `{workflowName}`    | `definition.name`                      | `Refine, Plan, Implement, Review` |
+| `{taskDescription}` | User's original description            | `Add login page`                  |
+| `{taskId}`          | Generated task ID                      | `wf-1747234567890-a3f2k1`         |
+| `{phaseCount}`      | Total phases in the top-level workflow | `4`                               |
+
+### Cancelled Message
+
+There is **no separate** `cancelledMessage` field on `WorkflowDefinition`. The cancellation path reuses the same `completionMessage` field, but with a different fallback.
+
+**Two cancellation paths exist:**
+
+1. **`/cancel-workflow` command** (`src/command.ts`) — Sends a **hardcoded message** with no template resolution at all:
+
+   ```
+   ❌ **Workflow Cancelled**
+
+   **Task:** {taskDescription}
+   **Task ID:** {taskId}
+   ```
+
+   This command also unloads the workflow state immediately, so the `agent_end` hook sees null state and does nothing further.
+
+2. **`agent_end` hook** (`src/hooks.ts`) — When `state.cancelled === true` and `state.completionNotified === false`, resolves `definition.completionMessage` if set, otherwise falls back to `DEFAULT_CANCELLED_MESSAGE` (not `DEFAULT_COMPLETION_MESSAGE`). Uses the same variable set as the completion message: `{workflowName}`, `{taskDescription}`, `{taskId}`, `{phaseCount}`.
+
+**Default cancelled message** (`DEFAULT_CANCELLED_MESSAGE` from `src/prompts.ts`):
+
+```
+❌ **{workflowName} Cancelled**
+
+**Task:** {taskDescription}
+**Task ID:** {taskId}
+```
+
+### Not-Done Reminder (`notDoneReminder`)
+
+Resolved when the agent tries to stop while the workflow is still active. Forces the agent to continue.
+
+| Variable              | Source                                 | Example Value                     |
+| --------------------- | -------------------------------------- | --------------------------------- |
+| `{workflowName}`      | `definition.name`                      | `Refine, Plan, Implement, Review` |
+| `{taskDescription}`   | User's original description            | `Add login page`                  |
+| `{taskId}`            | Generated task ID                      | `wf-1747234567890-a3f2k1`         |
+| `{workflowKey}`       | `state.workflowKey`                    | `rpir`                            |
+| `{phaseName}`         | Current phase `name`                   | `Implementation`                  |
+| `{phaseEmoji}`        | Current phase `emoji`                  | `⚙️`                              |
+| `{phaseInstructions}` | Current phase's full instructions text | _(the raw instructions string)_   |
+
+---
+
+## Default Templates
+
+All configurable template fields have sensible defaults defined in `src/prompts.ts` and `src/hooks.ts`. If a field is omitted from the workflow definition, the corresponding default is used.
+
+### `DEFAULT_ROLE_INSTRUCTION`
+
+Used when `roleInstruction` is not set in the workflow definition.
+
+```
+You are the ORCHESTRATOR for this workflow. You must NOT use the edit or write tools directly.
+All implementation work must be delegated to subagents via the delegate_to_subagents tool.
+Follow the phase instructions precisely.
+```
+
+### `DEFAULT_ADVANCE_REMINDER`
+
+Used when `advanceReminder` is not set.
+
+```
+When you finish this phase, call the workflow_step tool with action='next' to advance to the next phase. If you need to restart the current scope from the beginning, use action='loop'.
+```
+
+### `DEFAULT_BLOCK_REASON`
+
+Used when `blockReasonTemplate` is not set. Defined in `src/hooks.ts`.
+
+```
+[workflow] The tool "{toolName}" is blocked during the {phaseName} phase.
+Refer to the current phase instructions for allowed tools and approaches.
+When finished, call workflow_step to advance to the next phase.
+```
+
+### `DEFAULT_COMPLETION_MESSAGE`
+
+Used when `completionMessage` is not set.
+
+```
+✅ **{workflowName} Complete**
+
+**Task:** {taskDescription}
+**Task ID:** {taskId}
+**Phases completed:** {phaseCount}
+```
+
+### `DEFAULT_NOT_DONE_REMINDER`
+
+Used when `notDoneReminder` is not set.
+
+```
+⚠️ The {workflowName} is still active. Current phase: {phaseEmoji} {phaseName}.
+
+You must NOT stop yet. The workflow requires you to complete the current phase
+and call workflow_step to advance.
+
+Current phase instructions:
+{phaseInstructions}
+
+Continue working on the current phase and call workflow_step when done.
+```
+
+### `DEFAULT_CANCELLED_MESSAGE`
+
+Fallback for the cancellation path in `handleAgentEnd` when `completionMessage` is not set on the workflow definition. Note: the `/cancel-workflow` command sends its own hardcoded message and does not use this constant.
+
+```
+❌ **{workflowName} Cancelled**
+
+**Task:** {taskDescription}
+**Task ID:** {taskId}
+```
+
+---
+
+## Resolution Examples
+
+### Full lifecycle trace
+
+Given a workflow with `name: "Code Review"`, `commandName: "review"`, and two phases (`gather` → `report`):
+
+**1. `/workflow review Check auth module`** — `initialMessage` resolved:
+
+```
+{workflowName}        → Code Review
+{workflowKey}         → code-review
+{description}         → Check auth module
+{firstPhaseId}        → gather
+{firstPhaseName}      → Gather Context
+{firstPhaseEmoji}     → 📋
+{firstPhaseProfiles}  → (none)
+```
+
+**2. Agent turn during `gather` phase** — phase `instructions` resolved:
+
+```
+{workflowName}        → Code Review
+{description}        → Check auth module
+{taskId}              → wf-1747234567890-b2c4d6
+{phaseId}             → gather
+{phaseName}           → Gather Context
+{previousPhaseName}   → (start)
+{nextPhaseName}       → Report Findings
+{blockedToolsList}    → (none)
+{globalStepCount}     → 0
+```
+
+**3. Agent calls `edit` during a phase with `blacklist: [edit]`** — `blockReasonTemplate` resolved:
+
+```
+{workflowName}  → Code Review
+{phaseName}     → Gather Context
+{toolName}      → edit
+{allowedTools}  → all except: edit
+```
+
+**4. Workflow completes** — `completionMessage` resolved:
+
+```
+{workflowName}      → Code Review
+{taskDescription}   → Check auth module
+{taskId}            → wf-1747234567890-b2c4d6
+{phaseCount}        → 2
+```