pi-superpowers 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 coctostan
+Copyright (c) 2025 Jesse Vincent (original skill content from obra/superpowers)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# pi-superpowers
+
+![pi-superpowers banner](banner.jpg)
+
+Structured workflow skills for [pi](https://github.com/badlogic/pi-mono), adapted from [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent.
+
+Brainstorming → Planning → TDD → Debugging → Code Review → Finishing — as composable skills your coding agent loads on demand.
+
+## Install
+
+```bash
+pi install git:github.com/coctostan/pi-superpowers
+```
+
+Or add to `.pi/settings.json` (project-level) or `~/.pi/agent/settings.json` (global):
+
+```json
+{
+  "packages": ["git:github.com/coctostan/pi-superpowers"]
+}
+```
+
+## What's Inside
+
+### Skills
+
+| Skill | Description | Invoke |
+|-------|-------------|--------|
+| **brainstorming** | Socratic design refinement — questions, alternatives, incremental validation | `/skill:brainstorming` |
+| **writing-plans** | Detailed implementation plans with bite-sized TDD tasks | `/skill:writing-plans` |
+| **executing-plans** | Batch execution with checkpoints for architect review | `/skill:executing-plans` |
+| **subagent-driven-development** | Fresh subagent per task with two-stage review | `/skill:subagent-driven-development` |
+| **test-driven-development** | RED-GREEN-REFACTOR cycle (includes anti-patterns reference) | `/skill:test-driven-development` |
+| **systematic-debugging** | 4-phase root cause investigation | `/skill:systematic-debugging` |
+| **verification-before-completion** | Evidence before claims, always | `/skill:verification-before-completion` |
+| **requesting-code-review** | Pre-merge review with severity categories | `/skill:requesting-code-review` |
+| **receiving-code-review** | Technical evaluation of review feedback | `/skill:receiving-code-review` |
+| **dispatching-parallel-agents** | Concurrent subagent workflows | `/skill:dispatching-parallel-agents` |
+| **using-git-worktrees** | Isolated development branches | `/skill:using-git-worktrees` |
+| **finishing-a-development-branch** | Merge/PR decision workflow | `/skill:finishing-a-development-branch` |
+
+### Plan Tracker
+
+The `plan_tracker` tool replaces file-based task tracking. It stores state in the session and shows progress in the TUI:
+
+```
+Tasks: ✓✓→○○ (2/5)  Task 3: Recovery modes
+```
+
+Usage by the agent:
+```
+plan_tracker({ action: "init", tasks: ["Task 1: Setup", "Task 2: Core", ...] })
+plan_tracker({ action: "update", index: 0, status: "complete" })
+plan_tracker({ action: "status" })
+plan_tracker({ action: "clear" })
+```
+
+## The Workflow
+
+1. **Brainstorm** — `/skill:brainstorming` refines your idea into a design document
+2. **Isolate** — `/skill:using-git-worktrees` creates a clean workspace
+3. **Plan** — `/skill:writing-plans` breaks work into bite-sized TDD tasks
+4. **Execute** — `/skill:executing-plans` or `/skill:subagent-driven-development` works through the plan
+5. **Verify** — `/skill:verification-before-completion` proves it works
+6. **Review** — `/skill:requesting-code-review` catches issues
+7. **Finish** — `/skill:finishing-a-development-branch` merges or creates a PR
+
+Each skill cross-references related skills so the agent knows what to use next.
+
+## Subagent Dispatch
+
+Skills that reference subagent dispatch (subagent-driven-development, requesting-code-review, dispatching-parallel-agents) work with any dispatch mechanism:
+
+- **With pi-superteam:** The agent uses the `team` tool automatically
+- **Without pi-superteam:** Run `pi -p "prompt"` in another terminal, or use tmux panes for parallel tasks
+
+## Attribution
+
+Skill content adapted from [Superpowers](https://github.com/obra/superpowers) by Jesse Vincent, licensed under MIT.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/extensions/plan-tracker.ts

@@ -0,0 +1,324 @@
+/**
+ * Plan Tracker Extension
+ *
+ * A native pi tool for tracking plan progress.
+ * State is stored in tool result details for proper branching support.
+ * Shows a persistent TUI widget above the editor.
+ */
+
+import { StringEnum } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, ExtensionContext, Theme } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type, type Static } from "@sinclair/typebox";
+
+type TaskStatus = "pending" | "in_progress" | "complete";
+
+interface Task {
+  name: string;
+  status: TaskStatus;
+}
+
+interface PlanTrackerDetails {
+  action: "init" | "update" | "status" | "clear";
+  tasks: Task[];
+  error?: string;
+}
+
+const PlanTrackerParams = Type.Object({
+  action: StringEnum(["init", "update", "status", "clear"] as const, {
+    description: "Action to perform",
+  }),
+  tasks: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Task names (for init)",
+    })
+  ),
+  index: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      description: "Task index, 0-based (for update)",
+    })
+  ),
+  status: Type.Optional(
+    StringEnum(["pending", "in_progress", "complete"] as const, {
+      description: "New status (for update)",
+    })
+  ),
+});
+
+export type PlanTrackerInput = Static<typeof PlanTrackerParams>;
+
+function formatWidget(tasks: Task[], theme: Theme): string {
+  if (tasks.length === 0) return "";
+
+  const complete = tasks.filter((t) => t.status === "complete").length;
+  const icons = tasks
+    .map((t) => {
+      switch (t.status) {
+        case "complete":
+          return theme.fg("success", "✓");
+        case "in_progress":
+          return theme.fg("warning", "→");
+        default:
+          return theme.fg("dim", "○");
+      }
+    })
+    .join("");
+
+  // Find current task (first in_progress, or first pending)
+  const current =
+    tasks.find((t) => t.status === "in_progress") ??
+    tasks.find((t) => t.status === "pending");
+  const currentName = current ? `  ${current.name}` : "";
+
+  return `${theme.fg("muted", "Tasks:")} ${icons} ${theme.fg("muted", `(${complete}/${tasks.length})`)}${currentName}`;
+}
+
+function formatStatus(tasks: Task[]): string {
+  if (tasks.length === 0) return "No plan active.";
+
+  const complete = tasks.filter((t) => t.status === "complete").length;
+  const inProgress = tasks.filter((t) => t.status === "in_progress").length;
+  const pending = tasks.filter((t) => t.status === "pending").length;
+
+  const lines: string[] = [];
+  lines.push(`Plan: ${complete}/${tasks.length} complete (${inProgress} in progress, ${pending} pending)`);
+  lines.push("");
+  for (let i = 0; i < tasks.length; i++) {
+    const t = tasks[i];
+    const icon =
+      t.status === "complete" ? "✓" : t.status === "in_progress" ? "→" : "○";
+    lines.push(`  ${icon} [${i}] ${t.name}`);
+  }
+  return lines.join("\n");
+}
+
+export default function (pi: ExtensionAPI) {
+  let tasks: Task[] = [];
+
+  const reconstructState = (ctx: ExtensionContext) => {
+    tasks = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "message") continue;
+      const msg = entry.message;
+      if (msg.role !== "toolResult" || msg.toolName !== "plan_tracker") continue;
+      const details = msg.details as PlanTrackerDetails | undefined;
+      if (details && !details.error) {
+        tasks = details.tasks;
+      }
+    }
+  };
+
+  const updateWidget = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    if (tasks.length === 0) {
+      ctx.ui.setWidget("plan_tracker", undefined);
+    } else {
+      ctx.ui.setWidget("plan_tracker", (_tui, theme) => {
+        return new Text(formatWidget(tasks, theme), 0, 0);
+      });
+    }
+  };
+
+  // Reconstruct state + widget on session events
+  for (const event of [
+    "session_start",
+    "session_switch",
+    "session_fork",
+    "session_tree",
+  ] as const) {
+    pi.on(event, async (_event, ctx) => {
+      reconstructState(ctx);
+      updateWidget(ctx);
+    });
+  }
+
+  pi.registerTool({
+    name: "plan_tracker",
+    label: "Plan Tracker",
+    description:
+      "Track implementation plan progress. Actions: init (set task list), update (change task status), status (show current state), clear (remove plan).",
+    parameters: PlanTrackerParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      switch (params.action) {
+        case "init": {
+          if (!params.tasks || params.tasks.length === 0) {
+            return {
+              content: [{ type: "text", text: "Error: tasks array required for init" }],
+              details: {
+                action: "init",
+                tasks: [...tasks],
+                error: "tasks required",
+              } as PlanTrackerDetails,
+            };
+          }
+          tasks = params.tasks.map((name) => ({ name, status: "pending" as TaskStatus }));
+          updateWidget(ctx);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Plan initialized with ${tasks.length} tasks.\n${formatStatus(tasks)}`,
+              },
+            ],
+            details: { action: "init", tasks: [...tasks] } as PlanTrackerDetails,
+          };
+        }
+
+        case "update": {
+          if (params.index === undefined || !params.status) {
+            return {
+              content: [
+                { type: "text", text: "Error: index and status required for update" },
+              ],
+              details: {
+                action: "update",
+                tasks: [...tasks],
+                error: "index and status required",
+              } as PlanTrackerDetails,
+            };
+          }
+          if (tasks.length === 0) {
+            return {
+              content: [{ type: "text", text: "Error: no plan active. Use init first." }],
+              details: {
+                action: "update",
+                tasks: [],
+                error: "no plan active",
+              } as PlanTrackerDetails,
+            };
+          }
+          if (params.index < 0 || params.index >= tasks.length) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Error: index ${params.index} out of range (0-${tasks.length - 1})`,
+                },
+              ],
+              details: {
+                action: "update",
+                tasks: [...tasks],
+                error: `index ${params.index} out of range`,
+              } as PlanTrackerDetails,
+            };
+          }
+          tasks[params.index].status = params.status;
+          updateWidget(ctx);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Task ${params.index} "${tasks[params.index].name}" → ${params.status}\n${formatStatus(tasks)}`,
+              },
+            ],
+            details: { action: "update", tasks: [...tasks] } as PlanTrackerDetails,
+          };
+        }
+
+        case "status": {
+          return {
+            content: [{ type: "text", text: formatStatus(tasks) }],
+            details: { action: "status", tasks: [...tasks] } as PlanTrackerDetails,
+          };
+        }
+
+        case "clear": {
+          const count = tasks.length;
+          tasks = [];
+          updateWidget(ctx);
+          return {
+            content: [
+              {
+                type: "text",
+                text: count > 0 ? `Plan cleared (${count} tasks removed).` : "No plan was active.",
+              },
+            ],
+            details: { action: "clear", tasks: [] } as PlanTrackerDetails,
+          };
+        }
+
+        default:
+          return {
+            content: [{ type: "text", text: `Unknown action: ${params.action}` }],
+            details: {
+              action: "status",
+              tasks: [...tasks],
+              error: `unknown action`,
+            } as PlanTrackerDetails,
+          };
+      }
+    },
+
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("plan_tracker "));
+      text += theme.fg("muted", args.action);
+      if (args.action === "update" && args.index !== undefined) {
+        text += ` ${theme.fg("accent", `[${args.index}]`)}`;
+        if (args.status) text += ` → ${theme.fg("dim", args.status)}`;
+      }
+      if (args.action === "init" && args.tasks) {
+        text += ` ${theme.fg("dim", `(${args.tasks.length} tasks)`)}`;
+      }
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as PlanTrackerDetails | undefined;
+      if (!details) {
+        const text = result.content[0];
+        return new Text(text?.type === "text" ? text.text : "", 0, 0);
+      }
+
+      if (details.error) {
+        return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+      }
+
+      const taskList = details.tasks;
+      switch (details.action) {
+        case "init":
+          return new Text(
+            theme.fg("success", "✓ ") +
+              theme.fg("muted", `Plan initialized with ${taskList.length} tasks`),
+            0,
+            0
+          );
+        case "update": {
+          const complete = taskList.filter((t) => t.status === "complete").length;
+          return new Text(
+            theme.fg("success", "✓ ") +
+              theme.fg("muted", `Updated (${complete}/${taskList.length} complete)`),
+            0,
+            0
+          );
+        }
+        case "status": {
+          if (taskList.length === 0) {
+            return new Text(theme.fg("dim", "No plan active"), 0, 0);
+          }
+          const complete = taskList.filter((t) => t.status === "complete").length;
+          let text = theme.fg("muted", `${complete}/${taskList.length} complete`);
+          for (const t of taskList) {
+            const icon =
+              t.status === "complete"
+                ? theme.fg("success", "✓")
+                : t.status === "in_progress"
+                  ? theme.fg("warning", "→")
+                  : theme.fg("dim", "○");
+            text += `\n${icon} ${theme.fg("muted", t.name)}`;
+          }
+          return new Text(text, 0, 0);
+        }
+        case "clear":
+          return new Text(
+            theme.fg("success", "✓ ") + theme.fg("muted", "Plan cleared"),
+            0,
+            0
+          );
+        default:
+          return new Text(theme.fg("dim", "Done"), 0, 0);
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pi-superpowers",
+  "version": "0.1.0",
+  "description": "Superpowers workflow skills adapted for pi",
+  "keywords": ["pi-package"],
+  "license": "MIT",
+  "author": "coctostan",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/coctostan/pi-superpowers.git"
+  },
+  "files": [
+    "extensions/",
+    "skills/",
+    "banner.jpg",
+    "LICENSE",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": ["extensions/plan-tracker.ts"],
+    "skills": ["skills"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+---
+
+> **Related skills:** Consider `/skill:using-git-worktrees` to set up an isolated workspace, then `/skill:writing-plans` for implementation planning.
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+## The Process
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation:**
+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Commit the design document to git
+
+**Implementation (if continuing):**
+- Ask: "Ready to set up for implementation?"
+- Use `/skill:using-git-worktrees` to create isolated workspace
+- Use `/skill:writing-plans` to create detailed implementation plan
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense