@pi-stef/superpowers-adapter 0.2.2

package/README.md

@@ -0,0 +1,106 @@
+# @pi-stef/superpowers-adapter
+
+A [pi](https://pi.dev) extension that bridges the [superpowers](https://github.com/obra/superpowers) skill system to pi's extension API.
+
+## Why This Extension Exists
+
+Pi ships with 4 built-in tools: `read`, `bash`, `edit`, `write`. The superpowers skill system expects additional tools that pi doesn't provide natively:
+
+| Tool | Pi Built-in | Superpowers Needs | Provided By |
+|------|-------------|-------------------|-------------|
+| TodoWrite | No | Yes | This extension |
+| Skill | No | Yes | This extension |
+| Agent | No | Yes | `@tintinweb/pi-subagents` |
+
+The superpowers `using-superpowers` skill explicitly requires:
+1. **"Use the `Skill` tool"** to load skill instructions
+2. **"Never use the Read tool on skill files"** — the Skill tool must be used instead
+
+While pi natively supports skill discovery (listing them in the system prompt), superpowers workflows depend on calling the `Skill` tool directly.
+
+## Installation
+
+```bash
+# 1. Install superpowers (official skill pack)
+pi install https://github.com/obra/superpowers
+
+# 2. Install this extension
+pi install git:github.com/sfiorini/pi-stef#packages/superpowers-adapter
+```
+
+## Tools
+
+### TodoWrite
+
+Track implementation tasks with status progression.
+
+**Parameters:**
+- `todos` (array, required) — Array of todo items, each with:
+  - `id` (string) — Unique identifier
+  - `content` (string) — Task description
+  - `status` (string) — One of: `pending`, `in_progress`, `completed`
+  - `priority` (string, optional) — One of: `high`, `medium`, `low`
+
+**Example:**
+```
+TodoWrite({
+  todos: [
+    { id: "1", content: "Design API", status: "completed" },
+    { id: "2", content: "Implement", status: "in_progress", priority: "high" },
+    { id: "3", content: "Write tests", status: "pending" }
+  ]
+})
+```
+
+### Skill
+
+Load skill instructions by name. Discovers skills from standard pi skill directories.
+
+**Parameters:**
+- `skill` (string, required) — Skill name (e.g., `brainstorming`, `test-driven-development`)
+
+**Discovery paths** (searched in order):
+- `<cwd>/.pi/skills/`
+- `<cwd>/.agents/skills/`
+- `~/.pi/agent/skills/`
+- `~/.agents/skills/`
+- Recursively under `~/.pi/agent/git/` (depth 10)
+
+**Limitation:** The YAML frontmatter parser handles simple `key: value` pairs only. Nested values, multi-line values, and quoted strings with complex escaping are not supported.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/todos` | Display current todo list with progress |
+| `/todo-clear` | Reset all todos |
+
+## Architecture
+
+```
+src/
+  types.ts           — Shared type definitions
+  tools/
+    todo-write.ts    — TodoWrite tool + state management
+    skill.ts         — Skill discovery, parsing, loading
+  commands.ts        — /todos and /todo-clear
+  index.ts           — Extension entry point + lifecycle hooks
+```
+
+The extension auto-injects the `using-superpowers` skill content into the system prompt via the `before_agent_start` lifecycle hook. This ensures the LLM receives superpowers instructions without manual configuration.
+
+## Troubleshooting
+
+**"using-superpowers skill not found"**
+→ Install superpowers: `pi install https://github.com/obra/superpowers`
+
+**Skills not discovered**
+→ Check that skill directories contain `SKILL.md` files with valid YAML frontmatter.
+
+## Security
+
+This extension has read-only filesystem access. It reads `SKILL.md` files from standard pi directories. No network calls, no process execution, no file writes.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@pi-stef/superpowers-adapter",
+  "version": "0.2.2",
+  "description": "Bridges the superpowers skill system to pi's extension API with TodoWrite, Task, and Skill tools.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "superpowers"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/commands.ts

@@ -0,0 +1,19 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { formatTodos, clearTodos } from "./tools/todo-write.js";
+
+export function registerCommands(pi: ExtensionAPI): void {
+  pi.registerCommand("todos", {
+    description: "Show current todo list",
+    handler: async (_args: string, ctx: { ui: { notify: (msg: string, level: "info" | "warning" | "error") => void } }) => {
+      ctx.ui.notify(formatTodos(), "info");
+    },
+  });
+
+  pi.registerCommand("todo-clear", {
+    description: "Clear all todos",
+    handler: async (_args: string, ctx: { ui: { notify: (msg: string, level: "info" | "warning" | "error") => void } }) => {
+      clearTodos();
+      ctx.ui.notify("All todos cleared.", "info");
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+import type { ExtensionAPI, BeforeAgentStartEvent, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { registerTodoWriteTool, clearTodos } from "./tools/todo-write.js";
+import { registerSkillTool, resetSkillCache, readSkillContent, discoverSkills } from "./tools/skill.js";
+import { registerCommands } from "./commands.js";
+
+const USING_SUPERPOWERS_SKILL = "using-superpowers";
+
+export default function (pi: ExtensionAPI): void {
+  registerTodoWriteTool(pi);
+  registerSkillTool(pi);
+  registerCommands(pi);
+
+  pi.on("session_start", async () => {
+    clearTodos();
+    resetSkillCache();
+  });
+
+  pi.on("resources_discover", async () => {
+    resetSkillCache();
+  });
+
+  pi.on(
+    "before_agent_start",
+    async (
+      event: BeforeAgentStartEvent,
+      ctx: ExtensionContext,
+    ) => {
+      const skills = discoverSkills(ctx.cwd);
+      const skill = skills.get(USING_SUPERPOWERS_SKILL);
+
+      if (!skill) {
+        if (ctx.hasUI && ctx.ui) {
+          ctx.ui.notify(
+            `[pi-superpowers-adapter] using-superpowers skill not found. Install superpowers: pi install https://github.com/obra/superpowers`,
+            "warning",
+          );
+        }
+        return;
+      }
+
+      const skillContent = readSkillContent(skill.path);
+      if (!skillContent || skillContent.startsWith("[pi-superpowers-adapter]")) {
+        if (ctx.hasUI && ctx.ui) {
+          ctx.ui.notify(
+            skillContent ?? `[pi-superpowers-adapter] Failed to read using-superpowers skill from ${skill.path}`,
+            "error",
+          );
+        }
+        return;
+      }
+
+      return {
+        systemPrompt: event.systemPrompt + "\n" + skillContent + "\n",
+      };
+    },
+  );
+}

package/src/tools/skill.ts

@@ -0,0 +1,275 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+import { Type, type Static } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Theme } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import type { SkillMeta } from "../types.js";
+
+const SkillSchema = Type.Object({
+  skill: Type.String({
+    description:
+      "Name of the skill to load (e.g., 'brainstorming', 'test-driven-development')",
+  }),
+});
+
+type SkillInput = Static<typeof SkillSchema>;
+
+let skillCache: Map<string, SkillMeta> | null = null;
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n?---\n([\s\S]*)$/;
+
+export function resetSkillCache(): void {
+  skillCache = null;
+}
+
+export function parseSkillFrontmatter(
+  content: string,
+  path: string,
+): SkillMeta | null {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+
+  const frontmatter = match[1];
+  const skillDir = path.replace(/[\\/]?SKILL\.md$/, "");
+  const meta: SkillMeta = { name: basename(skillDir), path };
+
+  for (const line of frontmatter.split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      const value = line
+        .slice(colonIdx + 1)
+        .trim()
+        .replace(/^["']|["']$/g, "");
+      if (key === "name") meta.name = value;
+      if (key === "description") meta.description = value;
+    }
+  }
+
+  return meta;
+}
+
+export function extractSkillContent(content: string): string {
+  const match = content.match(FRONTMATTER_RE);
+  return match ? match[2].trim() : content;
+}
+
+export function readSkillContent(skillPath: string): string | null {
+  try {
+    const content = readFileSync(skillPath, "utf-8");
+    return extractSkillContent(content);
+  } catch (err) {
+    return `[pi-superpowers-adapter] Failed to read skill file "${skillPath}": ${err instanceof Error ? err.message : String(err)}`;
+  }
+}
+
+function findSkillsDirs(
+  basePath: string,
+  results: string[],
+  depth = 0,
+): void {
+  const MAX_DEPTH = 10;
+  const MAX_BREADTH = 200;
+  if (depth > MAX_DEPTH) return;
+  let entries;
+  try {
+    entries = readdirSync(basePath, { withFileTypes: true });
+  } catch (err) {
+    throw new Error(
+      `[pi-superpowers-adapter] Failed to read directory "${basePath}": ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  let visited = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (++visited > MAX_BREADTH) break;
+    const fullPath = join(basePath, entry.name);
+    if (entry.name === "skills") {
+      results.push(fullPath);
+    } else {
+      findSkillsDirs(fullPath, results, depth + 1);
+    }
+  }
+}
+
+export function discoverSkills(cwd: string): Map<string, SkillMeta> {
+  if (skillCache) return skillCache;
+
+  const skills = new Map<string, SkillMeta>();
+  const home = homedir();
+
+  const skillPaths = [
+    join(cwd, ".pi", "skills"),
+    join(cwd, ".agents", "skills"),
+    join(home, ".pi", "agent", "skills"),
+    join(home, ".agents", "skills"),
+  ];
+
+  const gitPackagesDir = join(home, ".pi", "agent", "git");
+  if (existsSync(gitPackagesDir)) {
+    findSkillsDirs(gitPackagesDir, skillPaths);
+  }
+
+  for (const basePath of skillPaths) {
+    if (!existsSync(basePath)) continue;
+    try {
+      const entries = readdirSync(basePath, { withFileTypes: true });
+      for (const entry of entries) {
+        const entryPath = join(basePath, entry.name);
+        // Check if this entry is a skill directory (has SKILL.md) or a container (has subdirs)
+        const skillFile = join(entryPath, "SKILL.md");
+        if (existsSync(skillFile)) {
+          // Entry is a skill directory
+          try {
+            const content = readFileSync(skillFile, "utf-8");
+            const meta = parseSkillFrontmatter(content, skillFile);
+            if (meta?.name && !skills.has(meta.name)) {
+              skills.set(meta.name, meta);
+            }
+          } catch {
+            // Skip unreadable skill files
+          }
+        } else {
+          // Entry might be a container directory of skills (e.g., a symlink to a skills collection)
+          // Try to discover skills one level deeper
+          try {
+            const subEntries = readdirSync(entryPath, { withFileTypes: true });
+            for (const subEntry of subEntries) {
+              const subSkillFile = join(entryPath, subEntry.name, "SKILL.md");
+              if (!existsSync(subSkillFile)) continue;
+              try {
+                const content = readFileSync(subSkillFile, "utf-8");
+                const meta = parseSkillFrontmatter(content, subSkillFile);
+                if (meta?.name && !skills.has(meta.name)) {
+                  skills.set(meta.name, meta);
+                }
+              } catch {
+                // Skip unreadable skill files
+              }
+            }
+          } catch {
+            // Not a directory or unreadable, skip
+          }
+        }
+      }
+    } catch {
+      // Skip unreadable directories
+    }
+  }
+
+  skillCache = skills;
+  return skills;
+}
+
+export function registerSkillTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "Skill",
+    label: "Skill",
+    description:
+      "Load and invoke a skill by name. Skills provide specialized instructions for specific tasks like TDD, debugging, or brainstorming. IMPORTANT: Use this tool instead of read for skill files.",
+    promptSnippet: "Load specialized skill instructions for specific workflows",
+    promptGuidelines: [
+      "Use Skill tool to load skill instructions before starting a task that matches the skill's description.",
+      "Common skills: brainstorming, test-driven-development, systematic-debugging, writing-plans.",
+      "IMPORTANT: Always use Skill tool to load skills, never use read tool on skill files.",
+    ],
+    parameters: SkillSchema,
+    async execute(
+      _toolCallId: string,
+      params: SkillInput,
+      _signal: unknown,
+      _onUpdate: unknown,
+      ctx: { cwd: string },
+    ) {
+      const skills = discoverSkills(ctx.cwd);
+      const skill = skills.get(params.skill);
+
+      if (!skill) {
+        const availableSkills = Array.from(skills.keys()).sort();
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Skill "${params.skill}" not found.\n\nAvailable skills:\n${availableSkills.map((s) => ` - ${s}`).join("\n")}\n\nInstall superpowers: pi install https://github.com/obra/superpowers`,
+            },
+          ],
+          isError: true,
+          details: { requestedSkill: params.skill, availableSkills },
+        };
+      }
+
+      const skillContent = readSkillContent(skill.path);
+      if (!skillContent || skillContent.startsWith("[pi-superpowers-adapter]")) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: skillContent ?? `[pi-superpowers-adapter] Error loading skill "${params.skill}": Failed to read skill file`,
+            },
+          ],
+          isError: true,
+          details: { error: skillContent ?? "Failed to read skill file", skillPath: skill.path },
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Loaded skill: ${skill.name}\n${skill.description ? `\nDescription: ${skill.description}\n` : ""}\n\n${skillContent}`,
+          },
+        ],
+        details: {
+          skillName: skill.name,
+          skillPath: skill.path,
+          skillDescription: skill.description,
+          totalLines: skillContent.split("\n").length,
+        },
+      };
+    },
+    renderResult(
+      result: { content: { type: string; text?: string }[]; details?: Record<string, unknown> },
+      _options: unknown,
+      theme: Theme,
+      context: { isError?: boolean },
+    ) {
+      if (context.isError) {
+        const errorMsg =
+          result.content[0]?.type === "text" && result.content[0].text
+            ? result.content[0].text
+            : "Failed to load skill.";
+        return new Text(theme.fg("error", errorMsg), 0, 0);
+      }
+
+      const details = result.details as
+        | { skillName?: string; totalLines?: number }
+        | undefined;
+
+      if (!details?.skillName || !details?.totalLines) {
+        return new Text(
+          theme.fg("warning", "Skill loaded, but metadata is missing."),
+          0,
+          0,
+        );
+      }
+
+      const label = theme.fg(
+        "customMessageLabel",
+        "\x1b[1m[skill]\x1b[22m",
+      );
+      const name = theme.fg("customMessageText", details.skillName);
+      const lines = theme.fg("dim", ` (${details.totalLines} lines)`);
+      const line = `${label} ${name}${lines}`;
+
+      const box = new Box(
+        1,
+        0,
+        (t: string) => theme.bg("customMessageBg", t),
+      );
+      box.addChild(new Text(line, 0, 0));
+      return box;
+    },
+  });
+}

package/src/tools/todo-write.ts

@@ -0,0 +1,94 @@
+import { Type, type Static } from "@sinclair/typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { TodoItem, TodoStatus } from "../types.js";
+
+const TodoWriteSchema = Type.Object({
+  todos: Type.Array(
+    Type.Object({
+      id: Type.String({ description: "Unique identifier for the todo item" }),
+      content: Type.String({ description: "The content/description of the todo item" }),
+      status: Type.Union(
+        [
+          Type.Literal("pending"),
+          Type.Literal("in_progress"),
+          Type.Literal("completed"),
+        ],
+        { description: "Status of the todo item" },
+      ),
+      priority: Type.Optional(
+        Type.Union(
+          [
+            Type.Literal("high"),
+            Type.Literal("medium"),
+            Type.Literal("low"),
+          ],
+          { description: "Priority level (optional)" },
+        ),
+      ),
+    }),
+  ),
+});
+
+type TodoWriteInput = Static<typeof TodoWriteSchema>;
+
+let todos: TodoItem[] = [];
+
+export function clearTodos(): void {
+  todos = [];
+}
+
+export function getTodos(): readonly TodoItem[] {
+  return todos;
+}
+
+const statusIcon = (s: TodoStatus): string => {
+  switch (s) {
+    case "completed":
+      return "✅";
+    case "in_progress":
+      return "🔄";
+    case "pending":
+      return "⭕";
+  }
+};
+
+const priorityLabel = (p?: "high" | "medium" | "low"): string =>
+  p ? `[${p.toUpperCase()}] ` : "";
+
+export function formatTodos(): string {
+  if (todos.length === 0) return "No todos. Use TodoWrite to create tasks.";
+  const idWidth = todos.length >= 10 ? 2 : 1;
+  const lines = todos.map(
+    (t, i) =>
+      `${String(i + 1).padStart(idWidth)}. ${statusIcon(t.status)} ${priorityLabel(t.priority)}${t.content}`,
+  );
+  const completed = todos.filter((t) => t.status === "completed").length;
+  return `Todos (${completed}/${todos.length} completed):\n${lines.join("\n")}`;
+}
+
+export function registerTodoWriteTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "TodoWrite",
+    label: "TodoWrite",
+    description:
+      "Create, update, or replace the todo list for tracking task progress. Use this to track implementation tasks from plans.",
+    promptSnippet: "Track tasks with status (pending, in_progress, completed)",
+    promptGuidelines: [
+      "Use TodoWrite when starting a multi-step task to track progress.",
+      "Update todo status as you work through tasks: mark in_progress when starting, completed when done.",
+    ],
+    parameters: TodoWriteSchema,
+    async execute(_toolCallId: string, params: TodoWriteInput) {
+      todos = params.todos.map((t) => ({
+        id: t.id,
+        content: t.content,
+        status: t.status,
+        priority: t.priority,
+      }));
+      return {
+        content: [{ type: "text" as const, text: formatTodos() }],
+        details: { todoCount: todos.length },
+      };
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,14 @@
+export type TodoStatus = "pending" | "in_progress" | "completed";
+
+export interface TodoItem {
+  id: string;
+  content: string;
+  status: TodoStatus;
+  priority?: "high" | "medium" | "low";
+}
+
+export interface SkillMeta {
+  name: string;
+  description?: string;
+  path: string;
+}