@pi-unipi/workflow 0.1.16 → 2.0.0

package/README.md

@@ -1,10 +1,8 @@
 # @pi-unipi/workflow
 
-Structured development workflow commands for Pi coding agent.
+20 slash commands that take work from idea to shipped code. Each command loads a skill file that tells the agent exactly what to do — brainstorm, plan, execute, review, or fix.
 
-## Overview
-
-19 slash commands that guide work from idea to completion. Each command maps to a skill that instructs the agent on what to do.
+The core loop: brainstorm an idea, plan the implementation, execute in a worktree, review the result, consolidate what you learned. Everything else supports this cycle.
 
 ## Commands
 
@@ -30,17 +28,14 @@ Structured development workflow commands for Pi coding agent.
 | `/unipi:chore-create` | Create reusable chore definition | `<string>` |
 | `/unipi:chore-execute` | Execute a saved chore | `chore:<path> <string>` |
 
-## Workflow
+## Typical Flow
 
 ```
 brainstorm → plan → work → review-work → consolidate
     ↑                                        │
     └────────────────────────────────────────┘
-                    (loop)
 ```
 
-### Typical Flow
-
 ```bash
 # 1. Brainstorm an idea
 /unipi:brainstorm redesign auth system
@@ -60,34 +55,26 @@ brainstorm → plan → work → review-work → consolidate
 
 ### Quick Tasks
 
+For small tasks that skip the full flow:
+
 ```bash
-# For small tasks that don't need full flow
 /unipi:quick-work fix typo in README
 ```
 
-### Research & Advisory
+### Research and 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
-
-# Deep research with bash access
 /unipi:research TypeScript 5.0 migration path
-
-# Find issues (passive scan)
 /unipi:scan-issues focus on security
 ```
 
 ### Bug Fixing
 
 ```bash
-# Debug and fix a bug (full flow)
+# Full debug flow
 /unipi:debug TypeError in auth middleware
 /unipi:fix debug:2026-04-28-auth-typeerror-debug
 
@@ -98,28 +85,47 @@ brainstorm → plan → work → review-work → consolidate
 ### Chores
 
 ```bash
-# Create reusable chores
 /unipi:chore-create push to github main
-/unipi:chore-create publish package to npm
-
-# Execute saved chores
 /unipi:chore-execute chore:push-github-main
-/unipi:chore-execute chore:publish-npm
 ```
 
 ### 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
+/unipi:worktree-merge feat/new-feature
 ```
 
+## Special Triggers
+
+Workflow skills detect installed packages and enhance their behavior automatically. This is the coexists system — each package adds capabilities without requiring configuration.
+
+| Package Present | Skills Affected | What Changes |
+|-----------------|-----------------|--------------|
+| `@pi-unipi/ask-user` | All skills | Structured user input for decisions |
+| `@pi-unipi/subagents` | brainstorm, document, gather-context, review-work, scan-issues, work | Parallel execution with file locking |
+| `@pi-unipi/mcp` | All skills | MCP server tools available |
+| `@pi-unipi/web-api` | research, gather-context, consultant | Web search and page reading |
+| `@pi-unipi/compactor` | All skills (main agent) | Context tools available |
+| `@pi-unipi/ralph` | work, review-work | Ralph loop for 3+ tasks |
+
+When `@pi-unipi/ask-user` is installed, skills use `ask_user` for decision gates — presenting options instead of guessing. When `@pi-unipi/subagents` is installed, investigation skills spawn parallel agents to explore code faster.
+
+The footer package subscribes to workflow events (`WORKFLOW_START`, `WORKFLOW_END`) to show current command and duration. Info-screen displays workflow state in its dashboard.
+
+## How Skills Work
+
+Each command maps to a skill file in `packages/workflow/skills/{name}/SKILL.md`. When you run `/unipi:brainstorm`, Pi loads the brainstorm skill and follows its instructions.
+
+Skills define:
+- What the agent should do step by step
+- What tools to use (subagents, web search, ask-user)
+- What output to produce (specs, plans, reviews)
+- Where to save results (`.unipi/docs/`)
+
+The agent reads the skill, executes the steps, and produces artifacts in the `.unipi/` directory.
+
 ## Directory Structure
 
 ```
@@ -140,31 +146,9 @@ brainstorm → plan → work → review-work → consolidate
     └── fix/login-bug/
 ```
 
-## Integration
-
-- **@pi-unipi/core** — shared constants, events, utilities
-- **@pi-unipi/memory** — memory hooks for consolidate (optional)
-- **@pi-unipi/subagents** — parallel research for gather-context, scan-issues (optional)
-- **@pi-unipi/ralph** — loop integration for long-running tasks (optional)
-- **@pi-unipi/ask-user** — structured user input for all skills (optional)
-- **@pi-unipi/mcp** — MCP server tools for all skills (optional)
-- **@pi-unipi/web-api** — web research for research-type skills (optional)
-- **@pi-unipi/compactor** — compactor tools for main agent (optional)
+## Configuration
 
-See [docs/coexist-triggers.md](docs/coexist-triggers.md) for detailed integration behavior.
-
-## Installation
-
-```bash
-npm install @pi-unipi/workflow
-```
-
-Add to pi settings:
-```json
-{
-  "extensions": ["@unipi/workflow"]
-}
-```
+Workflow has no configuration. Skills are static files — the agent follows them as-is. Behavior changes come from which packages are installed (see Special Triggers above).
 
 ## License
 

package/commands.ts

@@ -388,7 +388,7 @@ export function registerWorkflowCommands(
         // Apply sandbox — save current tools, set command's tools
         const currentTools = options.getActiveTools();
         options.saveTools(currentTools);
-        const sandboxTools = getToolsForCommand(cmd.name);
+        const sandboxTools = getToolsForCommand(cmd.name, currentTools);
         const sandboxLevel = getSandboxLevel(cmd.name);
         options.setActiveTools([...sandboxTools], sandboxLevel);
 

package/index.ts

@@ -16,7 +16,7 @@ import {
   getPackageVersion,
   initUnipiDirs,
   type SandboxLevel,
-  getToolsForLevel,
+  getBlockedToolsForLevel,
 } from "@pi-unipi/core";
 import { registerWorkflowCommands } from "./commands.js";
 
@@ -35,6 +35,9 @@ let sandboxActive = false;
 /** Current sandbox level (null = no sandbox) */
 let currentSandboxLevel: SandboxLevel | null = null;
 
+/** Current active tools after sandbox filtering */
+let currentSandboxTools: string[] | null = null;
+
 export default function (pi: ExtensionAPI) {
   // Register skills directory with pi's resource loader
   const skillsDir = new URL("./skills", import.meta.url).pathname;
@@ -52,6 +55,7 @@ export default function (pi: ExtensionAPI) {
       pi.setActiveTools(tools);
       sandboxActive = true;
       currentSandboxLevel = level;
+      currentSandboxTools = tools;
     },
     saveTools: (tools: string[]) => {
       savedTools = tools;
@@ -62,7 +66,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_call", async (event, _ctx) => {
     if (!sandboxActive || !currentSandboxLevel) return;
 
-    const allowed = getToolsForLevel(currentSandboxLevel);
+    const allowed = currentSandboxTools ?? [];
     if (!allowed.includes(event.toolName)) {
       return {
         block: true,
@@ -75,11 +79,13 @@ export default function (pi: ExtensionAPI) {
   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 allowed = currentSandboxTools ?? pi.getActiveTools();
+    const blocked = getBlockedToolsForLevel(currentSandboxLevel);
 
-    const base = `\n\n<sandbox>\nSandbox mode: ${currentSandboxLevel}.\nAvailable tools: ${allowed.join(", ")}.\nBlocked tools: ${blocked.join(", ")} — removed from your tool list.`;
+    const blockedLine = blocked.length > 0
+      ? `\nBlocked tools: ${blocked.join(", ")} — removed from your tool list.`
+      : "\nNo tools were blocked by this sandbox.";
+    const base = `\n\n<sandbox>\nSandbox mode: ${currentSandboxLevel}.\nAvailable tools: ${allowed.join(", ")}.${blockedLine}`;
 
     if (currentSandboxLevel === "brainstorm") {
       return {
@@ -114,6 +120,7 @@ export default function (pi: ExtensionAPI) {
       savedTools = null;
       sandboxActive = false;
       currentSandboxLevel = null;
+      currentSandboxTools = null;
     }
   });
 
@@ -149,7 +156,8 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Listen for ralph module ready event
-  pi.events.on(UNIPI_EVENTS.MODULE_READY, (event: any) => {
+  pi.events.on(UNIPI_EVENTS.MODULE_READY, (data) => {
+    const event = data as { name?: string };
     if (event?.name === MODULES.RALPH) {
       ralphDetected = true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/workflow",
-  "version": "0.1.16",
+  "version": "2.0.0",
   "description": "Structured development workflow commands for Pi coding agent",
   "type": "module",
   "license": "MIT",

package/skills/brainstorm/SKILL.md

@@ -177,13 +177,27 @@ Wait for user response. If changes requested, make them and re-run self-review.
 
 ## Phase 8: Handoff
 
-Ask user what to do next:
-
-1. **Proceed to /unipi:plan** — Turn decisions into implementation plan
-2. **Keep exploring** — More questions or refine decisions
-3. **Done for now** — Return later
+Ask user what to do next. If `ask_user` is available, prefer structured options so the plan handoff can run automatically:
+
+```ts
+ask_user({
+  question: "What would you like to do next?",
+  options: [
+    {
+      label: "Proceed to /unipi:plan",
+      description: "Turn decisions into an implementation plan",
+      value: "plan",
+      action: "new_session",
+      prefill: "/unipi:plan specs:YYYY-MM-DD-<topic>-design",
+    },
+    { label: "Keep exploring", description: "Refine questions or decisions", value: "explore" },
+    { label: "Done for now", description: "Return later", value: "done", action: "end_turn" },
+  ],
+  allowFreeform: false,
+})
+```
 
-If user selects "Proceed to /unipi:plan", suggest:
+If `ask_user` is unavailable, ask conversationally with the same options. Keep this copyable fallback command visible:
 ```
 /unipi:plan specs:YYYY-MM-DD-<topic>-design
 ```

package/skills/debug/SKILL.md

@@ -12,6 +12,8 @@ Active investigation to reproduce, diagnose, and root-cause bugs. Produces a str
 **This skill MAY:** read codebase, run diagnostic commands, spawn subagents, write debug report to `.unipi/docs/debug/`.
 **This skill MAY NOT:** edit code, fix issues, run tests that modify state, deploy.
 
+**Write-permission clarification:** "Read-only" means source/project code is read-only for diagnosis. It does **not** prohibit creating or updating the debug report. The agent should use available file-writing tools to write exactly the report under `.unipi/docs/debug/`. If writing that report fails, report the write failure explicitly.
+
 **This is diagnosis only — not fixing.**
 
 ## Command Format
@@ -21,7 +23,7 @@ Active investigation to reproduce, diagnose, and root-cause bugs. Produces a str
 ```
 
 - `string(greedy)` — bug description, error message, or reproduction steps
-- Read-only sandbox + write to `.unipi/docs/debug/`
+- Source/code read-only sandbox, with explicit permission to write the debug report to `.unipi/docs/debug/`
 - Spawns subagents if `@unipi/subagents` extension is installed
 
 ## Output Path
@@ -104,7 +106,7 @@ Deep dive into root cause:
 
 ### Phase 4: Document Findings
 
-Write debug report to `.unipi/docs/debug/YYYY-MM-DD-<topic>-debug.md`:
+Write debug report to `.unipi/docs/debug/YYYY-MM-DD-<topic>-debug.md` using the available file-writing tool. Do not skip this because the investigation is otherwise read-only:
 
 ```markdown
 ---

package/skills/plan/SKILL.md

@@ -179,22 +179,45 @@ Do NOT re-read or re-edit the spec checkboxes — Phase 4 already wrote them.
 
 ## Phase 6: Present & Handoff
 
-Present plan summary to user. Then ask:
-
-1. **Proceed to /unipi:work** — Start implementing in a worktree
-2. **Proceed to /unipi:auto** — Run full pipeline (work → review → merge)
-3. **Revise plan** — Adjust tasks or scope
-4. **Done for now** — Return later
+Present plan summary to user. Then ask what to do next. If `ask_user` is available, prefer structured handoff options using `action: "new_session"` so the selected workflow can be queued automatically:
+
+```ts
+ask_user({
+  question: "What would you like to do next?",
+  options: [
+    {
+      label: "Proceed to /unipi:work",
+      description: "Start implementing the plan",
+      value: "work",
+      action: "new_session",
+      prefill: "<work-command>",
+    },
+    {
+      label: "Proceed to /unipi:auto",
+      description: "Run full pipeline (work → review → merge)",
+      value: "auto",
+      action: "new_session",
+      prefill: "/unipi:auto plan:YYYY-MM-DD-<topic>-plan.md",
+    },
+    { label: "Revise plan", description: "Adjust tasks or scope", value: "revise" },
+    { label: "Done for now", description: "Return later", value: "done", action: "end_turn" },
+  ],
+  allowFreeform: false,
+})
+```
 
-If user selects "Proceed to /unipi:work":
-- **Worktree branch** → suggest: `/unipi:work worktree:<branch-name> specs:YYYY-MM-DD-<topic>-plan`
-- **Main branch** → suggest: `/unipi:work specs:YYYY-MM-DD-<topic>-plan` (no worktree arg)
+Use the correct `<work-command>`:
+- **Worktree branch** → `/unipi:work worktree:<branch-name> specs:YYYY-MM-DD-<topic>-plan`
+- **Main branch** → `/unipi:work specs:YYYY-MM-DD-<topic>-plan` (no worktree arg)
 
-If user selects "Proceed to /unipi:auto":
-- **Worktree branch** → suggest: `/unipi:auto plan:YYYY-MM-DD-<topic>-plan.md`
-- **Main branch** → suggest: `/unipi:auto plan:YYYY-MM-DD-<topic>-plan.md` (same — auto reads workbranch from plan)
+Copyable fallback commands when `ask_user` is unavailable:
+```
+/unipi:work worktree:<branch-name> specs:YYYY-MM-DD-<topic>-plan
+/unipi:work specs:YYYY-MM-DD-<topic>-plan
+/unipi:auto plan:YYYY-MM-DD-<topic>-plan.md
+```
 
-Recommend starting a **new session** for work if using a worktree.
+Recommend starting a **new session** for work if using a worktree; the ask_user launcher handles compact/direct queuing when available.
 
 ---
 

package/skills/review-work/SKILL.md

@@ -117,18 +117,34 @@ Followed by description explaining the status.
 
 ## Phase 5: Handoff
 
-Based on review results:
+Based on review results, use `ask_user` `new_session` options when available so the selected next workflow command can be queued automatically. If `ask_user` is unavailable, present the same choices conversationally and keep copyable commands visible.
 
 **If all tasks done and checks pass:**
 
 *If `workbranch` is set (worktree):*
 > "All tasks complete and verified. Ready to merge back to main."
+
+Offer:
+```ts
+ask_user({
+  question: "Merge this worktree now?",
+  options: [
+    { label: "Proceed to /unipi:worktree-merge", value: "merge", action: "new_session", prefill: "/unipi:worktree-merge" },
+    { label: "Consolidate learnings", value: "consolidate", action: "new_session", prefill: "/unipi:consolidate" },
+    { label: "Done for now", value: "done", action: "end_turn" },
+  ],
+  allowFreeform: false,
+})
+```
+Copyable fallback:
 ```
 /unipi:worktree-merge
 ```
 
 *If `workbranch` is empty (main branch):*
 > "All tasks complete and verified. Changes already on main — no merge needed."
+
+Offer `/unipi:consolidate` as a `new_session` handoff when available. Copyable fallback:
 ```
 /unipi:consolidate
 ```
@@ -141,6 +157,8 @@ Either way, user can consolidate learnings:
 **If tasks incomplete or checks fail:**
 > "Tasks remaining and/or checks failing. Continue work?"
 
+Offer the applicable `/unipi:work ...` command as a `new_session` handoff when available.
+
 *If `workbranch` is set:*
 ```
 /unipi:work worktree:<branch> specs:<plan-path>
@@ -153,6 +171,8 @@ Either way, user can consolidate learnings:
 
 **If scoped review complete:**
 > "Scoped review complete. Run full review or continue work?"
+
+Offer both commands as `new_session` options when available:
 ```
 /unipi:review-work plan:<plan-path>  (full review)
 /unipi:work specs:<plan-path>        (continue work)

package/skills/work/SKILL.md

@@ -163,13 +163,34 @@ When all tasks are `completed:`:
 
 **If working in worktree:**
 > "All tasks complete. Worktree: `{branch}`. Recommend reviewing before merge."
+
+If `ask_user` is available, offer an automatic handoff:
+```ts
+ask_user({
+  question: "Review this work now?",
+  options: [
+    {
+      label: "Proceed to /unipi:review-work",
+      description: "Review before merge",
+      value: "review",
+      action: "new_session",
+      prefill: "/unipi:review-work plan:<plan-path>",
+    },
+    { label: "Done for now", value: "done", action: "end_turn" },
+  ],
+  allowFreeform: false,
+})
+```
+Copyable fallback:
 ```
 /unipi:review-work plan:<plan-path>
 ```
-**Recommend starting a new session** for review.
+**Recommend starting a new session** for review; the ask_user launcher can compact/direct queue the command.
 
 **If working on main branch:**
 > "All tasks complete. All changes committed directly on main."
+
+If `ask_user` is available, offer the same review handoff with `prefill: "/unipi:review-work plan:<plan-path>"`. Copyable fallback:
 ```
 /unipi:review-work plan:<plan-path>
 ```