@pi-unipi/unipi 0.1.1

package/packages/workflow/README.md

@@ -0,0 +1,129 @@
+# @pi-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
+
+- **@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)
+
+## Installation
+
+```bash
+npm install @pi-unipi/workflow
+```
+
+Add to pi settings:
+```json
+{
+  "extensions": ["@unipi/workflow"]
+}
+```
+
+## License
+
+MIT

package/packages/workflow/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 "@pi-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/packages/workflow/skills/brainstorm/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: brainstorm
+description: "Collaborative discovery — explore problem space, evaluate approaches, write design spec. Use before any creative work."
+---
+
+# Brainstorming Ideas Into Designs
+
+Turn ideas into fully formed designs through collaborative dialogue.
+
+## Boundaries
+
+**This skill MAY:** research (read-only), discuss, ask questions, write the brainstorm document.
+**This skill MAY NOT:** edit code, create files beyond the brainstorm document, run tests, deploy, implement anything.
+
+**NEVER write code during this skill. This is a discussion, not implementation.**
+
+## Command Format
+
+```
+/unipi:brainstorm <string(greedy)>
+```
+
+- `string(greedy)` — the topic or problem to brainstorm about
+- No worktree args — brainstorm runs in current session on current branch
+- No visual companion — text-only brainstorming
+
+## Hard Gate
+
+Do NOT write any code, scaffold any project, or take any implementation action until design is presented and user approved. This applies to EVERY project regardless of perceived simplicity.
+
+## Anti-Pattern: "Too Simple For Design"
+
+Every project goes through this process. A todo list, a utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause wasted work. Design can be short, but MUST present and get approval.
+
+## Output Path
+
+```
+.unipi/docs/specs/YYYY-MM-DD-<topic>-design.md
+```
+
+Committed to current branch. Accessible across worktrees via git.
+
+---
+
+## Phase 1: Explore Project Context
+
+1. Check files, docs, recent commits to understand current state
+2. Assess scope: if request describes multiple independent subsystems, flag immediately
+3. If too large for single spec, help decompose into sub-projects
+
+**Exit:** Context gathered. Ready to ask questions.
+
+---
+
+## Phase 2: Ask Clarifying Questions
+
+Ask **one question at a time**. Don't dump a questionnaire.
+
+Start with:
+1. "What problem are we actually solving?" — strip assumptions, get root need
+2. "Who has this problem and when?" — context changes solutions
+3. "What does success look like?" — outcomes, not features
+
+Prefer multiple choice when natural options exist. Validate assumptions explicitly.
+
+**Exit:** Problem statement clear and reframed. Both agree on what solving.
+
+---
+
+## Phase 3: Propose Approaches
+
+Propose 2-3 different approaches with trade-offs:
+- What each optimizes for (speed, flexibility, simplicity)
+- What each costs (complexity, maintenance, time, risk)
+- Prior art in codebase or industry
+
+Present conversationally with recommendation and reasoning.
+
+**If open questions emerge:** MUST ask user about each one. Don't assume.
+
+**Exit:** Approach chosen. User signals decision.
+
+---
+
+## Phase 4: Present Design
+
+Once approach chosen, present design in sections:
+- Scale each section to complexity (few sentences if straightforward, 200-300 words if nuanced)
+- Ask after each section whether it looks right
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify
+
+**Design for isolation and clarity:**
+- Break into smaller units with one clear purpose
+- Each unit communicates through well-defined interfaces
+- Can someone understand unit without reading internals?
+
+**Exit:** Design approved by user.
+
+---
+
+## Phase 5: Write Design Document
+
+Write to `.unipi/docs/specs/YYYY-MM-DD-<topic>-design.md`:
+
+```markdown
+---
+title: "{Topic}"
+type: brainstorm
+date: YYYY-MM-DD
+---
+
+# {Topic}
+
+## Problem Statement
+{The actual problem, reframed}
+
+## Context
+{Key findings — what exists, what's been tried}
+
+## Chosen Approach
+{High-level description}
+
+## Why This Approach
+{Decision rationale, alternatives rejected}
+
+## Design
+{Architecture, components, data flow}
+
+## Implementation Checklist
+- [ ] Task 1 — description
+- [ ] Task 2 — description
+- [ ] Task 3 — description
+
+## Open Questions
+{Questions for planning phase}
+
+## Out of Scope
+{Explicitly excluded}
+```
+
+### Checklist Items
+
+The `## Implementation Checklist` section uses `- [ ]` markdown checkboxes. These are critical:
+
+- **`[ ]` = unplanned** — not yet covered by a plan
+- **`[x]` = planned** — marked when `/unipi:plan` covers this item
+- Agent MUST fill in checklist items based on the design
+- Each item should be a discrete, implementable task
+- Items should be ordered by dependency (earlier items don't depend on later ones)
+
+---
+
+## Phase 6: Spec Self-Review
+
+After writing, review with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections? Fix them.
+2. **Internal consistency:** Do sections contradict each other?
+3. **Scope check:** Focused enough for single implementation plan?
+4. **Ambiguity check:** Could any requirement be interpreted two ways? Pick one.
+
+Fix issues inline. No need to re-review — fix and move on.
+
+---
+
+## Phase 7: User Review Gate
+
+After self-review passes:
+
+> "Spec written and committed to `.unipi/docs/specs/YYYY-MM-DD-<topic>-design.md`. Please review and let me know if you want changes before we plan."
+
+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
+
+If user selects "Proceed to /unipi:plan", suggest:
+```
+/unipi:plan specs:YYYY-MM-DD-<topic>-design
+```
+
+---
+
+## Validate
+
+Before delivering, verify:
+
+- [ ] Problem was reframed — not accepted at face value
+- [ ] At least 2 approaches explored with tradeoffs
+- [ ] Every decision has rationale and rejected alternatives documented
+- [ ] Implementation checklist has concrete, discrete tasks with `[ ]` markers
+- [ ] Open questions listed — nothing swept under rug
+- [ ] No code was written — only brainstorm document created
+- [ ] `/unipi:plan` can start from this document without asking "what did you decide about X?"

package/packages/workflow/skills/consolidate/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: consolidate
+description: "Consolidate — save learnings to memory, craft skills if reusable. Use at end of work session or to summarize current state."
+---
+
+# Consolidating Learnings
+
+Capture what was learned, update memory, and craft skills when patterns emerge.
+
+## Boundaries
+
+**This skill MAY:** read/write `.unipi/memory/`, read session context, read plans/specs, write skill files if user approves.
+**This skill MAY NOT:** edit production code, run tests, deploy.
+
+## Command Format
+
+```
+/unipi:consolidate <string(greedy)>(optional)
+```
+
+- `string(greedy)` — optional focus (e.g., "focus on auth patterns" or "summarize what we learned about testing")
+- Two modes: **end-of-work** (memory + registry hooks) or **start/middle** (read context, consolidate ideas)
+
+---
+
+## Mode 1: End of Work Session
+
+Triggered when run after `/unipi:review-work` marks work as done.
+
+### Phase 1: Gather Learnings
+
+1. Read session context — what was discussed, decided, built
+2. Read the plan and spec — what was the goal, what was achieved
+3. Identify key learnings:
+   - Patterns discovered
+   - Decisions made and why
+   - Problems encountered and solutions
+   - Things that would be done differently
+   - Reusable approaches
+
+**Exit:** Learnings identified.
+
+### Phase 2: Update Memory
+
+1. Check if `@unipi/memory` extension is installed
+2. If not installed → skip memory, note to user
+3. If installed:
+   - Read existing `.unipi/memory/` files
+   - Find relevant memory files (by topic, date, or tag)
+   - **Update in place** — don't always create new files
+   - Merge new learnings with existing knowledge
+   - Prevent stale data by updating, not appending
+
+**Memory file format:**
+```markdown
+---
+topic: {topic}
+updated: YYYY-MM-DD
+tags: [tag1, tag2]
+---
+
+# {Topic}
+
+## Key Learnings
+- {Learning 1}
+- {Learning 2}
+
+## Patterns
+- {Pattern description}
+
+## Decisions
+- {Decision} — {Rationale}
+```
+
+**Exit:** Memory updated.
+
+### Phase 3: Skill Crafting
+
+1. Check if `@unipi/registry` extension is installed
+2. If not installed → skip, note to user
+3. If installed, assess if learnings are reusable:
+
+**Auto-create skill if:**
+- Pattern will definitely be used in future runs
+- Solution applies to recurring problem
+- Workflow could be standardized
+
+**Ask user if uncertain:**
+> "I discovered a pattern that might be worth capturing as a skill: {description}. Should I create a skill for this?"
+
+**Skip if:**
+- One-off solution, unlikely to recur
+- Too specific to current context
+- User declines
+
+**Exit:** Skill created or skipped.
+
+### Phase 4: Summary
+
+Report to user:
+- What was saved to memory
+- What skills were created (if any)
+- Suggest next steps if any work remains
+
+---
+
+## Mode 2: Start / Middle of Session
+
+Triggered when run without prior work session context.
+
+### Phase 1: Read Context
+
+1. Read session conversation so far
+2. OR read latest brainstorm/spec/plan
+3. Understand current state — what's been discussed, what's decided
+
+### Phase 2: Consolidate Ideas
+
+1. Summarize key points from context
+2. Identify open questions
+3. Identify decisions made
+4. Identify next steps
+
+### Phase 3: Write Summary
+
+Write consolidation to `.unipi/memory/` — same format as Mode 1.
+
+### Phase 4: Present
+
+Present summary to user. Ask:
+1. **Continue to brainstorm** — if ideas need formalizing
+2. **Continue to plan** — if decisions are clear
+3. **Done** — summary captured, return later
+
+---
+
+## Notes
+
+- Memory files are living documents — update, don't always create new
+- Skill creation is opportunistic — only when pattern is clearly reusable
+- Both modes write to `.unipi/memory/` — consistent location
+- Respects extension availability — graceful degradation if extensions not installed