@harms-haus/pi-workflows 1.0.0

package/skills/workflow-generation/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: workflow-generation
+description: Build pi-workflow definitions (workflows, phases, subworkflows, agent-profiles). Use when asked to create or modify a workflow for the pi-workflows extension. Covers the full file-based schema, directory layout, phase frontmatter, subworkflow references, looping, tool blacklists/whitelists, and agent-profile authoring.
+---
+
+# Workflow Generation
+
+This skill teaches how to build **pi-workflows** — file-based workflow definitions loaded from `~/.pi/agent/workflows/` (global) or `.pi/workflows/` (project-local) by the `pi-workflows` extension.
+
+Read this entire file before building any workflow.
+
+## Directory Layout
+
+```
+~/.pi/agent/workflows/
+├── my-workflow/              # One directory per user-facing workflow
+│   └── workflow.yaml         # Entry point: name, commandName, phases list
+├── _shared/                  # Convention: underscore-prefixed dirs hold reusable phases
+│   ├── scouting.md
+│   └── planning.md
+└── my-other-workflow/
+    └── workflow.yaml         # Can reference ../_shared/*.md phases
+```
+
+- Each workflow is a **directory** containing a `workflow.yaml`.
+- Phase instructions live in **`.md` files** with YAML frontmatter.
+- Directories starting with `_` are convention for shared phase libraries (not loaded as standalone workflows since they lack `workflow.yaml`).
+- Phase `.md` files are referenced by **relative path** from the workflow directory.
+
+## Agent Profiles
+
+Agent profiles live in `~/.pi/agent/agent-profiles/` as `.md` files with YAML frontmatter:
+
+```markdown
+---
+name: my-profile
+provider: openai # Provider ID
+model: gpt-4o # Model ID
+thinkingLevel: medium # low | medium | high
+tools: read,bash,edit,write,lsp-diagnostics,lsp-find-references,lsp-goto-definition
+---
+
+System prompt for the agent goes here as free-form markdown.
+```
+
+**Key fields:**
+
+- `name` — must match the filename (without `.md`)
+- `tools` — comma-separated list of tools the subagent can use. Omitting a tool prevents the subagent from using it.
+- `thinkingLevel` — controls reasoning effort
+
+### Designing Profiles
+
+1. **One responsibility per profile.** A scout scouts. A writer writes. A reviewer reviews. Never combine.
+2. **Restrict tools to the minimum needed.** Scouts don't need `edit`/`write`. Writers do. Reviewers only need `read`-family tools.
+3. **Set thinking level appropriately.** Low for fast scouting. Medium for implementation/writing. High for reviewing and planning.
+4. **Reuse before creating.** Check `~/.pi/agent/agent-profiles/` for existing profiles before creating new ones.
+
+## workflow.yaml Schema
+
+```yaml
+name: Human-Readable Workflow Name # Required
+commandName: my-command # Required for user-facing workflows. Used as: /workflow my-command <desc>
+sessionNamePrefix: "Prefix: " # Optional. Shown in TUI session name
+sessionNameMaxLength: 50 # Optional. Default 50
+initialMessage: | # Required for user-facing workflows
+  Start the {workflowName} for: "{description}"
+  Begin with Phase 1 ({firstPhaseName}).
+show: user # Optional. "user" (default) or "workflows" (subworkflow-only)
+phases: # Required. Array of phase file paths or subworkflow references
+  - ../_shared/scouting.md
+  - ../_shared/planning.md
+  - ./implementing.md
+  - { subworkflow: my-sub-workflow } # Delegates to another workflow
+```
+
+**Template variables** available in `initialMessage`:
+
+- `{workflowName}`, `{description}`, `{firstPhaseId}`, `{firstPhaseName}`, `{firstPhaseEmoji}`, `{firstPhaseProfiles}`
+
+**Optional workflow-level fields:**
+
+- `show: "workflows"` — makes the workflow invisible to `/workflow` command; only usable as a subworkflow
+- `loopable: false` — prevents looping (restarting from phase 0). Default is `true`.
+
+## Phase .md File Schema
+
+```markdown
+---
+id: my-phase-id # Required. Unique within the workflow.
+name: My Phase # Required. Display name.
+emoji: "🔍" # Required. Single emoji.
+tools: # Optional. Exactly one of blacklist or whitelist.
+  blacklist:
+    - edit
+    - write
+availableProfiles: # Optional. Profiles the agent may delegate to.
+  - vertical-scout
+  - horizontal-scout
+---
+
+Phase instructions go here as free-form markdown.
+
+These instructions are injected into the agent's context during this phase.
+They tell the agent WHAT to do and HOW to use subagents.
+```
+
+### Tool Configuration
+
+Each phase can restrict tools via `tools`:
+
+- **`blacklist`**: Block these specific tools. Everything else is allowed.
+- **`whitelist`**: Allow ONLY these tools. Everything else is blocked.
+- Cannot use both simultaneously.
+- `workflow_step` is always allowed regardless of configuration.
+
+Common pattern: read-only phases use `blacklist: [edit, write]` so the agent can scout/plan/review but not modify files directly — it must delegate to subagent profiles that have those tools.
+
+### Phase Instructions Best Practices
+
+Phase instructions are the core of your workflow. They must be:
+
+1. **Self-contained** — The agent only sees the current phase's instructions. Include all context the agent needs.
+2. **Actionable** — Tell the agent exactly what to do. Specify when to use `delegate_to_subagents`, `workflow_step next`, `workflow_step loop`.
+3. **Profile-aware** — List which profiles to use and what prompts to send them.
+4. **Terminal** — Every phase MUST end with either `workflow_step next` (advance) or `workflow_step loop` (restart the current workflow scope from phase 0).
+
+Example instruction patterns:
+
+```
+Spawn 1-4 parallel subagents:
+  delegate_to_subagents: [{ name: "scout-N", prompt: "Investigate: [topic]", profile: "vertical-scout" }]
+
+Collect results:
+  get_subagent_output for each sessionId
+
+Advance:
+  workflow_step next
+```
+
+## Subworkflows
+
+A subworkflow delegates a phase to an entire other workflow. In `workflow.yaml`:
+
+```yaml
+phases:
+  - { subworkflow: my-sub-workflow }
+```
+
+This resolves `my-sub-workflow` by its **directory name** in the workflows root. The parent workflow's phase becomes the entire subworkflow's phase sequence.
+
+### Subworkflow Rules
+
+1. The referenced key is the **directory name**, not the workflow's `name` field.
+2. Subworkflows can be marked `show: "workflows"` to hide them from `/workflow`.
+3. Subworkflow nesting is supported (a subworkflow can reference another subworkflow).
+4. **Cycles are detected and rejected** — the reference graph must be a DAG.
+5. If a referenced subworkflow doesn't exist, the parent workflow is skipped with a warning.
+
+### When to Use Subworkflows
+
+Use subworkflows when:
+
+- Multiple top-level workflows share the same phase sequence (e.g., research → plan → implement → review)
+- You want to reuse a "loop" boundary (looping restarts the current scope)
+
+Example — a shared implementation+review loop used by two workflows:
+
+```
+workflows/
+├── rpir-dev/
+│   └── workflow.yaml          # phases: [research, plan, {subworkflow: rpir-implement}]
+├── rpir-improve/
+│   └── workflow.yaml          # phases: [research, plan, {subworkflow: rpir-implement}]
+└── rpir-implement/
+    └── workflow.yaml          # show: workflows
+                                # phases: [implement.md, review.md]  ← loopable unit
+```
+
+## Looping
+
+When a phase calls `workflow_step loop`, the **current workflow scope** restarts from its **phase 0**. This is how iterative refinement works:
+
+1. An "implement" phase writes code
+2. A "review" phase checks it
+3. If review finds issues → `workflow_step loop` → back to implement
+4. If review is clean → `workflow_step next` → advance past the loop
+
+**Loop scope** is determined by the workflow boundary:
+
+- In a flat workflow, `loop` restarts the entire workflow
+- In a subworkflow reference, `loop` restarts only the subworkflow's phases
+
+Set `loopable: false` to prevent looping (useful for planning phases that should run once).
+
+## Phase Reuse Pattern
+
+Avoid copy-pasting phase `.md` files across workflows. Instead:
+
+1. Create a shared directory (convention: `_myshared/` with leading underscore)
+2. Put reusable phases there
+3. Reference them with relative paths: `../_myshared/scouting.md`
+
+```
+workflows/
+├── workflow-a/
+│   └── workflow.yaml       # phases: [../_shared/scouting.md, ./a-specific.md]
+├── workflow-b/
+│   └── workflow.yaml       # phases: [../_shared/scouting.md, ./b-specific.md]
+└── _shared/
+    ├── scouting.md          # Shared phase
+    └── planning.md          # Shared phase
+```
+
+## Building a New Workflow — Checklist
+
+1. **Define the workflow** — What is the goal? What phases does it need?
+2. **Check for reusable phases** — Look in `~/.pi/agent/workflows/` for `_`-prefixed shared directories with phases you can reference.
+3. **Check for reusable profiles** — Look in `~/.pi/agent/agent-profiles/` before creating new ones.
+4. **Create the directory** — `~/.pi/agent/workflows/my-workflow/`
+5. **Write `workflow.yaml`** — name, commandName, initialMessage, phases list
+6. **Write phase `.md` files** — Each with frontmatter (id, name, emoji) and instructions. Place shared phases in a `_shared/` directory and reference with `../_shared/...` paths.
+7. **Create agent profiles** — Only if no existing profile fits. Place in `~/.pi/agent/agent-profiles/`.
+8. **Validate** — Ensure every phase `.md` has `id`, `name`, `emoji`. Ensure all referenced profiles exist. Ensure YAML is valid.
+
+## Common Patterns
+
+### Read-Only Phase (Scouting/Planning/Reviewing)
+
+```yaml
+# frontmatter
+tools:
+  blacklist:
+    - edit
+    - write
+```
+
+The agent delegates to subagent profiles that have write tools. The orchestrator itself cannot modify files.
+
+### Implementation Phase
+
+```yaml
+# frontmatter
+tools:
+  blacklist:
+    - edit
+    - write
+availableProfiles:
+  - task-worker
+```
+
+Same pattern — the orchestrator delegates to `task-worker` which has edit/write tools.
+
+### Skip-if-Clean Phase
+
+In the phase instructions, include:
+
+```
+If there are no issues, immediately perform `workflow_step next` to skip.
+Otherwise, fix issues and use `workflow_step loop` to re-review.
+```
+
+### Parallel Subagent Delegation
+
+```
+Spawn 1-4 parallel subagents:
+  delegate_to_subagents: [
+    { name: "task-1", prompt: "...", profile: "my-profile" },
+    { name: "task-2", prompt: "...", profile: "my-profile" }
+  ]
+Collect results with get_subagent_output for each sessionId.
+```

package/src/TimerManager.ts

@@ -0,0 +1,67 @@
+/**
+ * TimerManager: tracks a single active setInterval and setTimeout.
+ *
+ * Prevents stale callbacks by verifying the stored handle still matches
+ * the one that was set at the time the callback was scheduled.
+ */
+export class TimerManager {
+  private intervalHandle: ReturnType<typeof setInterval> | null = null;
+  private timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * Start a new interval. Any previously tracked interval is cleared first.
+   */
+  startInterval(delay: number, callback: () => void): void {
+    this.clearInterval();
+
+    const handle = setInterval(() => {
+      // Only execute if the handle hasn't been replaced since scheduling
+      if (this.intervalHandle === handle) {
+        callback();
+      }
+    }, delay);
+
+    this.intervalHandle = handle;
+  }
+
+  /**
+   * Start a new timeout. Any previously tracked timeout is cleared first.
+   */
+  startTimeout(delay: number, callback: () => void): void {
+    this.clearTimeout();
+
+    const handle = setTimeout(() => {
+      // Only execute if the handle hasn't been replaced since scheduling
+      if (this.timeoutHandle === handle) {
+        callback();
+      }
+    }, delay);
+
+    this.timeoutHandle = handle;
+  }
+
+  /**
+   * Clear all tracked timers and set handles to null.
+   */
+  clearAll(): void {
+    this.clearInterval();
+    this.clearTimeout();
+  }
+
+  private clearInterval(): void {
+    if (this.intervalHandle !== null) {
+      clearInterval(this.intervalHandle);
+      this.intervalHandle = null;
+    }
+  }
+
+  private clearTimeout(): void {
+    if (this.timeoutHandle !== null) {
+      clearTimeout(this.timeoutHandle);
+      this.timeoutHandle = null;
+    }
+  }
+}
+
+/** Module-level singleton. */
+export const timerManager = new TimerManager();

package/src/command.ts

@@ -0,0 +1,199 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { WorkflowState, SetState, ReloadDefinitions, WorkflowDefinition } from "./types";
+import { isSubworkflowRef } from "./types";
+import {
+  createInitialState,
+  persistState,
+  isActive,
+  resolveActive,
+  autoEnterSubworkflowRefs,
+  resolveFirstPhase,
+} from "./state";
+import { loadWorkflows, findWorkflowByCommandName, resolveTemplate } from "./config";
+
+/** Show available workflows to the user. */
+function showAvailableWorkflows(ctx: ExtensionCommandContext): void {
+  const workflows = loadWorkflows(ctx.cwd);
+  const entries = Object.entries(workflows)
+    .filter(([_key, def]) => (def.show ?? "user") === "user")
+    .map(([_key, def]) => `  ${def.commandName} — ${def.name}`);
+  ctx.ui.notify(
+    "Usage: /workflow {name} {description}\n\nAvailable workflows:\n" + entries.join("\n"),
+    "info",
+  );
+}
+
+/** Set the session name and send the initial workflow message. */
+function startWorkflowSession(
+  pi: ExtensionAPI,
+  definition: WorkflowDefinition,
+  workflowKey: string,
+  description: string,
+): void {
+  const prefix = definition.sessionNamePrefix ?? "Workflow: ";
+  const maxLen = definition.sessionNameMaxLength ?? 50;
+  pi.setSessionName(
+    `${prefix}${description.slice(0, maxLen)}${description.length > maxLen ? "…" : ""}`,
+  );
+  const firstPhase = resolveFirstPhase(definition.phases);
+  if (!firstPhase) return;
+  const initialMessage = resolveTemplate(definition.initialMessage, {
+    workflowName: definition.name,
+    workflowKey,
+    description,
+    firstPhaseId: firstPhase.id,
+    firstPhaseName: firstPhase.name,
+    firstPhaseEmoji: firstPhase.emoji,
+    firstPhaseProfiles: firstPhase.availableProfiles?.join(", ") ?? "(none)",
+  });
+  pi.sendUserMessage(initialMessage);
+}
+
+/**
+ * Register the /workflow command.
+ * Usage: /workflow {commandName} {description}
+ */
+export function registerWorkflowCommand(
+  pi: ExtensionAPI,
+  getState: () => WorkflowState | null,
+  reloadDefinitions: ReloadDefinitions,
+  setState: SetState,
+): void {
+  pi.registerCommand("workflow", {
+    description: "Start a configured workflow. Usage: /workflow {name} {description}",
+    getArgumentCompletions(prefix: string) {
+      const workflows = loadWorkflows();
+      const names = Object.values(workflows)
+        .filter((w) => (w.show ?? "user") === "user")
+        .map((w) => w.commandName);
+      const filtered = names.filter((n) => n.startsWith(prefix));
+      return filtered.length > 0 ? filtered.map((n) => ({ value: n, label: n })) : null;
+    },
+    handler: async (args, ctx) => {
+      // Parse: split on first whitespace to get commandName and description
+      const input = typeof args === "string" ? args : "";
+      const parts = input.trim().match(/^(\S+)\s*(.*)/s);
+      if (!parts) {
+        showAvailableWorkflows(ctx);
+        return;
+      }
+
+      const commandName = parts[1];
+      const description = parts[2];
+      if (commandName === undefined || description === undefined) {
+        showAvailableWorkflows(ctx);
+        return;
+      }
+      if (!description || description.trim() === "") {
+        ctx.ui.notify(`Usage: /workflow ${commandName} {description}`, "warning");
+        return;
+      }
+
+      // Reload definitions to get latest
+      const definitions = await reloadDefinitions(ctx.cwd);
+
+      // Find the workflow
+      const match = findWorkflowByCommandName(definitions, commandName);
+      if (!match) {
+        const available = Object.values(definitions)
+          .map((d) => d.commandName)
+          .join(", ");
+        ctx.ui.notify(
+          `Unknown workflow: "${commandName}". Available: ${available || "(none)"}`,
+          "error",
+        );
+        return;
+      }
+
+      const [workflowKey, definition] = match;
+
+      // Safety check: reject workflows not shown to users
+      if (definition.show === "workflows") {
+        ctx.ui.notify(
+          `"${commandName}" is a subworkflow that can only run as part of another workflow. It cannot be started directly.`,
+          "error",
+        );
+        return;
+      }
+      const state = getState();
+
+      // Check for existing active workflow
+      if (isActive(state)) {
+        const active = resolveActive(state, definitions);
+        const phaseName = active ? active.currentPhase.name : "unknown";
+        const existingDesc = state.taskDescription;
+        const ok = await ctx.ui.confirm(
+          "Workflow already active",
+          `Phase: ${phaseName}\nTask: ${existingDesc}\n\nStart a new one?`,
+        );
+        if (!ok) return;
+      }
+
+      // Create new state
+      const newState = createInitialState(workflowKey, description.trim());
+
+      // Auto-enter subworkflow if first phase is a SubworkflowRef
+      const firstEntry = definition.phases[0];
+      let stateToSet = newState;
+      if (isSubworkflowRef(firstEntry)) {
+        const { newState: enteredState } = autoEnterSubworkflowRefs(newState, firstEntry);
+        stateToSet = enteredState;
+      }
+
+      setState(stateToSet);
+      persistState(pi, stateToSet);
+      ctx.ui.setStatus("workflow", undefined);
+      startWorkflowSession(pi, definition, workflowKey, description.trim());
+    },
+  });
+}
+
+/**
+ * Register the /cancel-workflow command.
+ * Immediately jumps the active workflow to DONE, bypassing the not-done reminder loop.
+ */
+export function registerCancelWorkflowCommand(
+  pi: ExtensionAPI,
+  getState: () => WorkflowState | null,
+  setState: (s: WorkflowState | null) => void,
+): void {
+  pi.registerCommand("cancel-workflow", {
+    description:
+      "Cancel the active workflow and jump to DONE. Bypasses the not-done reminder loop.",
+    handler: (_args, ctx) => {
+      const state = getState();
+      if (!state || !state.active) {
+        ctx.ui.notify("No active workflow to cancel.", "info");
+        return Promise.resolve();
+      }
+
+      // Jump straight to DONE state
+      const doneState: WorkflowState = {
+        ...state,
+        currentPath: state.currentPath.map((seg) => ({ ...seg })),
+        active: false,
+        cancelled: true,
+        completionNotified: false,
+      };
+
+      // Persist so session resume knows it was cancelled
+      persistState(pi, doneState);
+
+      // Clear the status
+      ctx.ui.setStatus("workflow", undefined);
+
+      // Send cancellation notification immediately (bypass agent_end hook)
+      const msg = `❌ **Workflow Cancelled**\n\n**Task:** ${state.taskDescription}\n**Task ID:** ${state.taskId}`;
+      pi.sendMessage(
+        { customType: "workflow:complete", content: msg, display: true },
+        { triggerTurn: false },
+      );
+
+      // Unload immediately so agent_end hook sees null state and does nothing
+      setState(null);
+
+      ctx.ui.notify("Workflow cancelled.", "info");
+      return Promise.resolve();
+    },
+  });
+}

package/src/config/index.ts

@@ -0,0 +1,11 @@
+// Barrel file — re-exports the public API from config modules.
+// All existing imports from "./config" or "../config" resolve through this file.
+
+export { resolveTemplate, getBlockedTools, getWhitelist } from "./templates";
+export { validateWorkflowDefinition, detectCycles, VALID_COMMAND_NAME_RE } from "./validation";
+export {
+  findWorkflowByCommandName,
+  loadWorkflowFromDir,
+  loadWorkflowsFromDir,
+  loadWorkflows,
+} from "./loading";