@pi-unipi/workflow 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# @unipi/workflow
+
+Structured development workflow commands for Pi coding agent.
+
+## Overview
+
+13 slash commands that guide work from idea to completion. Each command maps to a skill that instructs the agent on what to do.
+
+## Commands
+
+| Command | Description | Format |
+|---------|-------------|--------|
+| `/unipi:brainstorm` | Collaborative discovery, write design spec | `<string>` |
+| `/unipi:plan` | Create implementation plan from specs | `specs:<path> <string>` |
+| `/unipi:work` | Execute plan in worktree | `worktree:<branch> specs:<path> <string>` |
+| `/unipi:review-work` | Review work, run checks, mark remarks | `plan:<path> <string>` |
+| `/unipi:consolidate` | Save learnings, craft skills | `<string>` |
+| `/unipi:worktree-create` | Create git worktree | `<string>` |
+| `/unipi:worktree-list` | List all unipi worktrees | — |
+| `/unipi:worktree-merge` | Merge worktrees to main | `<branch> <string>` |
+| `/unipi:consultant` | Expert advisory | `<string>` |
+| `/unipi:quick-work` | Fast single-task execution | `<string>` |
+| `/unipi:gather-context` | Research codebase, prepare for brainstorm | `<string>` |
+| `/unipi:document` | Generate documentation | `<string>` |
+| `/unipi:scan-issues` | Find bugs, anti-patterns, security issues | `<string>` |
+
+## Workflow
+
+```
+brainstorm → plan → work → review-work → consolidate
+    ↑                                        │
+    └────────────────────────────────────────┘
+                    (loop)
+```
+
+### Typical Flow
+
+```bash
+# 1. Brainstorm an idea
+/unipi:brainstorm redesign auth system
+
+# 2. Create implementation plan
+/unipi:plan specs:2026-04-26-auth-redesign-design
+
+# 3. Execute plan in worktree
+/unipi:work worktree:feat/auth specs:2026-04-26-auth-redesign-plan
+
+# 4. Review what was built
+/unipi:review-work plan:2026-04-26-auth-redesign-plan
+
+# 5. Consolidate learnings
+/unipi:consolidate
+```
+
+### Quick Tasks
+
+```bash
+# For small tasks that don't need full flow
+/unipi:quick-work fix typo in README
+```
+
+### Research & Advisory
+
+```bash
+# Gather context before brainstorming
+/unipi:gather-context how we handle errors
+
+# Get expert advice
+/unipi:consultant should we use GraphQL or REST?
+
+# Generate documentation
+/unipi:document the auth module
+
+# Find issues
+/unipi:scan-issues focus on security
+```
+
+### Worktree Management
+
+```bash
+# Create worktree
+/unipi:worktree-create feat/new-feature
+
+# List worktrees
+/unipi:worktree-list
+
+# Merge back to main
+/ununi:worktree-merge feat/new-feature
+```
+
+## Directory Structure
+
+```
+.unipi/
+├── docs/
+│   ├── specs/          ← brainstorm output (design specs)
+│   ├── plans/          ← plan output (implementation plans)
+│   ├── generated/      ← document output (docs, guides)
+│   └── reviews/        ← review remarks (in plan docs)
+├── memory/             ← consolidate memory
+├── quick-work/         ← quick-work summaries
+└── worktrees/          ← git worktrees
+    ├── feat/auth/
+    └── fix/login-bug/
+```
+
+## Integration
+
+- **@unipi/core** — shared constants, events, utilities
+- **@unipi/memory** — memory hooks for consolidate (optional)
+- **@unipi/registry** — skill crafting for consolidate (optional)
+- **@unipi/subagents** — parallel research for gather-context, scan-issues (optional)
+- **@unipi/ralph** — loop integration for long-running tasks (optional)
+
+## Installation
+
+```bash
+npm install @unipi/workflow
+```
+
+Add to pi settings:
+```json
+{
+  "extensions": ["@unipi/workflow"]
+}
+```
+
+## License
+
+MIT

package/commands.ts

@@ -0,0 +1,281 @@
+/**
+ * @unipi/workflow — Command registration and dispatch
+ *
+ * Each workflow command maps to a skill. The extension registers
+ * slash commands that load and invoke the appropriate skill.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { readFileSync, readdirSync, existsSync } from "fs";
+import { join, basename } from "path";
+import { UNIPI_PREFIX, WORKFLOW_COMMANDS, getToolsForCommand, getSandboxLevel, type SandboxLevel } from "@unipi/core";
+
+/** Options for command registration */
+export interface WorkflowCommandOptions {
+  /** Check if ralph module is detected */
+  isRalphDetected: () => boolean;
+  /** Get current active tool names */
+  getActiveTools: () => string[];
+  /** Set active tools with sandbox level */
+  setActiveTools: (tools: string[], level: SandboxLevel) => void;
+  /** Save tools for later restore */
+  saveTools: (tools: string[]) => void;
+}
+
+/** Command definition */
+interface WorkflowCommand {
+  name: string;
+  description: string;
+  skillName: string;
+  /** Argument hint shown in autocomplete */
+  argumentHint?: string;
+  /** Extra context to inject when ralph is available */
+  ralphHint?: string;
+}
+
+/**
+ * Suggest spec files from .unipi/docs/specs/ for plan command.
+ */
+function suggestSpecFiles(prefix: string): { value: string; label: string; description: string }[] {
+  const specsDir = join(process.cwd(), ".unipi", "docs", "specs");
+  if (!existsSync(specsDir)) return [];
+
+  try {
+    const files = readdirSync(specsDir).filter((f) => f.endsWith(".md"));
+    return files
+      .filter((f) => !prefix || f.includes(prefix))
+      .map((f) => ({
+        value: `specs:${f}`,
+        label: basename(f, ".md"),
+        description: `Spec: ${f}`,
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Suggest existing worktree names for merge/list commands.
+ */
+function suggestWorktrees(): { value: string; label: string; description: string }[] {
+  const worktreesDir = join(process.cwd(), ".unipi", "worktrees");
+  if (!existsSync(worktreesDir)) return [];
+
+  try {
+    const dirs = readdirSync(worktreesDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+    return dirs.map((d) => ({
+      value: d,
+      label: d,
+      description: `Worktree: ${d}`,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/** All workflow commands with their skill mappings */
+const COMMANDS: WorkflowCommand[] = [
+  {
+    name: WORKFLOW_COMMANDS.BRAINSTORM,
+    description:
+      "Collaborative discovery — explore problem space, evaluate approaches, write design spec",
+    skillName: "brainstorm",
+    argumentHint: "<topic>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.PLAN,
+    description:
+      "Strategic planning — tasks, dependencies, acceptance criteria from specs",
+    skillName: "plan",
+    argumentHint: "specs:<file> <description>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.WORK,
+    description:
+      "Execute plan — implement in worktree, test, commit on done",
+    skillName: "work",
+    argumentHint: "<task description>",
+    ralphHint: "Ralph detected. Use /unipi:ralph-start for long-running tasks.",
+  },
+  {
+    name: WORKFLOW_COMMANDS.REVIEW_WORK,
+    description:
+      "Review work — check task completion, run lint/build, mark reviewer remarks",
+    skillName: "review-work",
+    argumentHint: "<worktree>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.CONSOLIDATE,
+    description:
+      "Consolidate — save learnings to memory, craft skills if reusable",
+    skillName: "consolidate",
+    argumentHint: "<what to consolidate>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.WORKTREE_CREATE,
+    description: "Create git worktree for parallel work",
+    skillName: "worktree-create",
+    argumentHint: "<branch-name>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.WORKTREE_LIST,
+    description: "List all unipi worktrees",
+    skillName: "worktree-list",
+  },
+  {
+    name: WORKFLOW_COMMANDS.WORKTREE_MERGE,
+    description: "Merge worktrees back to main branch",
+    skillName: "worktree-merge",
+    argumentHint: "<worktree>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.CONSULTANT,
+    description:
+      "Expert consultation — advisory with framework-based analysis",
+    skillName: "consultant",
+    argumentHint: "<question>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.QUICK_WORK,
+    description: "Fast single-task execution — one shot, summary recorded",
+    skillName: "quick-work",
+    argumentHint: "<task>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.GATHER_CONTEXT,
+    description:
+      "Research codebase — surface patterns, find prior art, prepare for brainstorm",
+    skillName: "gather-context",
+    argumentHint: "<topic>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.DOCUMENT,
+    description: "Generate documentation — README, API docs, guides",
+    skillName: "document",
+    argumentHint: "<target>",
+  },
+  {
+    name: WORKFLOW_COMMANDS.SCAN_ISSUES,
+    description:
+      "Deep investigation — find bugs, anti-patterns, security issues",
+    skillName: "scan-issues",
+    argumentHint: "<scope>",
+  },
+];
+
+/**
+ * Register all workflow commands with pi.
+ */
+export function registerWorkflowCommands(
+  pi: ExtensionAPI,
+  options: WorkflowCommandOptions,
+): void {
+  for (const cmd of COMMANDS) {
+    const fullCommand = `${UNIPI_PREFIX}${cmd.name}`;
+
+    pi.registerCommand(fullCommand, {
+      description: cmd.description,
+      getArgumentCompletions: (prefix: string) => {
+        // Plan command: suggest spec files
+        if (cmd.name === WORKFLOW_COMMANDS.PLAN) {
+          return suggestSpecFiles(prefix);
+        }
+
+        // Worktree merge: suggest existing worktrees
+        if (cmd.name === WORKFLOW_COMMANDS.WORKTREE_MERGE) {
+          return suggestWorktrees();
+        }
+
+        // Worktree create: suggest existing worktrees as reference
+        if (cmd.name === WORKFLOW_COMMANDS.WORKTREE_CREATE) {
+          return suggestWorktrees();
+        }
+
+        // Other commands: no dynamic completions (free-text args)
+        return null;
+      },
+      handler: async (args, ctx) => {
+        // Apply sandbox — save current tools, set command's tools
+        const currentTools = options.getActiveTools();
+        options.saveTools(currentTools);
+        const sandboxTools = getToolsForCommand(cmd.name);
+        const sandboxLevel = getSandboxLevel(cmd.name);
+        options.setActiveTools([...sandboxTools], sandboxLevel);
+
+        // Load skill content from SKILL.md
+        let skillContent = "";
+        try {
+          const skillPath = join(
+            new URL("./skills", import.meta.url).pathname,
+            cmd.skillName,
+            "SKILL.md",
+          );
+          skillContent = readFileSync(skillPath, "utf-8");
+        } catch {
+          // Skill file not found — continue without it
+        }
+
+        // Build skill invocation message
+        let message = `Execute the ${cmd.skillName} workflow.`;
+
+        // Add args if provided
+        if (args?.trim()) {
+          message += `\n\nArguments: ${args.trim()}`;
+        }
+
+        // Add ralph hint if applicable
+        if (cmd.ralphHint && options.isRalphDetected()) {
+          message += `\n\n💡 ${cmd.ralphHint}`;
+        }
+
+        // Inject skill content as context
+        if (skillContent) {
+          message += `\n\n<skill_content>\n${skillContent}\n</skill_content>`;
+        }
+
+        // Send as user message to trigger skill processing
+        pi.sendUserMessage(message, { deliverAs: "followUp" });
+
+        if (ctx.hasUI) {
+          ctx.ui.notify(`Running /${fullCommand}`, "info");
+        }
+      },
+    });
+  }
+
+  // Register the ralph integration command if ralph is detected
+  pi.registerCommand(`${UNIPI_PREFIX}ralph-start`, {
+    description: "Start a ralph loop for the current task",
+    handler: async (args, ctx) => {
+      if (!options.isRalphDetected()) {
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            "Ralph module not detected. Install @unipi/ralph first.",
+            "warning",
+          );
+        }
+        return;
+      }
+
+      // Delegate to ralph's start command
+      const taskContent = args?.trim() || "Continue current task in a ralph loop.";
+      pi.sendUserMessage(
+        `Start a ralph loop with this task:\n\n${taskContent}`,
+        { deliverAs: "followUp" },
+      );
+
+      if (ctx.hasUI) {
+        ctx.ui.notify("Starting ralph loop...", "info");
+      }
+    },
+  });
+}
+
+/**
+ * Get list of all registered workflow command names.
+ */
+export function getWorkflowCommandNames(): string[] {
+  return COMMANDS.map((c) => `${UNIPI_PREFIX}${c.name}`);
+}

package/index.ts

@@ -0,0 +1,155 @@
+/**
+ * @unipi/workflow — Structured development workflow commands
+ *
+ * Registers 13 commands that dispatch to skills for LLM instruction.
+ * Emits MODULE_READY event for inter-module discovery.
+ * Detects @unipi/ralph presence for loop integration.
+ * Applies sandbox (tool filtering) per command.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  WORKFLOW_COMMANDS,
+  emitEvent,
+  getPackageVersion,
+  initUnipiDirs,
+  type SandboxLevel,
+  getToolsForLevel,
+} from "@unipi/core";
+import { registerWorkflowCommands } from "./commands.js";
+
+/** Package version (read from package.json at load time) */
+const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
+
+/** Whether ralph module is detected */
+let ralphDetected = false;
+
+/** Saved tools before sandbox was applied (for restore) */
+let savedTools: string[] | null = null;
+
+/** Whether sandbox is currently active */
+let sandboxActive = false;
+
+/** Current sandbox level (null = no sandbox) */
+let currentSandboxLevel: SandboxLevel | null = null;
+
+export default function (pi: ExtensionAPI) {
+  // Register skills directory with pi's resource loader
+  const skillsDir = new URL("./skills", import.meta.url).pathname;
+  pi.on("resources_discover", async (_event, _ctx) => {
+    return {
+      skillPaths: [skillsDir],
+    };
+  });
+
+  // Register all workflow commands
+  registerWorkflowCommands(pi, {
+    isRalphDetected: () => ralphDetected,
+    getActiveTools: () => pi.getActiveTools(),
+    setActiveTools: (tools: string[], level: SandboxLevel) => {
+      pi.setActiveTools(tools);
+      sandboxActive = true;
+      currentSandboxLevel = level;
+    },
+    saveTools: (tools: string[]) => {
+      savedTools = tools;
+    },
+  });
+
+  // Block tool calls that violate sandbox
+  pi.on("tool_call", async (event, _ctx) => {
+    if (!sandboxActive || !currentSandboxLevel) return;
+
+    const allowed = getToolsForLevel(currentSandboxLevel);
+    if (!allowed.includes(event.toolName)) {
+      return {
+        block: true,
+        reason: `Tool "${event.toolName}" is not allowed in ${currentSandboxLevel} sandbox. Allowed: ${allowed.join(", ")}`,
+      };
+    }
+  });
+
+  // Inject sandbox constraints into system prompt so LLM knows its limits
+  pi.on("before_agent_start", async (event, _ctx) => {
+    if (!sandboxActive || !currentSandboxLevel) return;
+
+    const allowed = getToolsForLevel(currentSandboxLevel);
+    const blocked = ["read", "write", "edit", "bash", "grep", "find", "ls"]
+      .filter((t) => !allowed.includes(t));
+
+    const base = `\n\n<sandbox>\nSandbox mode: ${currentSandboxLevel}.\nAvailable tools: ${allowed.join(", ")}.\nBlocked tools: ${blocked.join(", ")} — removed from your tool list.`;
+
+    if (currentSandboxLevel === "brainstorm") {
+      return {
+        systemPrompt:
+          event.systemPrompt +
+          base +
+          `\nThe write tool is available but restricted to .unipi/docs/specs/ only.\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requests an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
+      };
+    }
+
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        base +
+        `\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requests an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
+    };
+  });
+
+  // Restore tools when agent finishes
+  pi.on("agent_end", async (_event, _ctx) => {
+    if (sandboxActive && savedTools) {
+      pi.setActiveTools(savedTools);
+      savedTools = null;
+      sandboxActive = false;
+      currentSandboxLevel = null;
+    }
+  });
+
+  // Announce module presence on session start
+  pi.on("session_start", async (_event, ctx) => {
+    // Initialize .unipi directory structure
+    initUnipiDirs();
+
+    // Emit MODULE_READY
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.WORKFLOW,
+      version: VERSION,
+      commands: Object.values(WORKFLOW_COMMANDS),
+      tools: [],
+    });
+
+    // Listen for ralph module
+    if (!ralphDetected) {
+      try {
+        // Check if ralph tools exist (indicates @unipi/ralph is loaded)
+        const allTools = pi.getAllTools();
+        ralphDetected = allTools.some((t) => t.name === "ralph_start");
+      } catch {
+        // Ignore — ralph not present
+      }
+    }
+
+    // Show workflow status in UI
+    if (ctx.hasUI) {
+      const ralphStatus = ralphDetected ? "✓ ralph" : "○ ralph";
+      ctx.ui.setStatus("unipi-workflow", `⚡ workflow ${ralphStatus}`);
+    }
+  });
+
+  // Listen for ralph module ready event
+  pi.on(UNIPI_EVENTS.MODULE_READY as any, (event: any) => {
+    if (event?.name === MODULES.RALPH) {
+      ralphDetected = true;
+    }
+  });
+
+  // Clean up on shutdown
+  pi.on("session_shutdown", async () => {
+    ralphDetected = false;
+    savedTools = null;
+    sandboxActive = false;
+  });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@pi-unipi/workflow",
+  "version": "0.1.0",
+  "description": "Structured development workflow commands for Pi coding agent",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/workflow"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "unipi",
+    "workflow"
+  ],
+  "files": [
+    "*.ts",
+    "skills/**/*",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}