gsd-pi 2.29.0-dev.49d972f → 2.29.0-dev.4c155ee

package/src/resources/skills/create-gsd-extension/templates/stateful-tool-skeleton.ts

@@ -0,0 +1,143 @@
+/**
+ * {{EXTENSION_NAME}} — Stateful tool with persistence
+ *
+ * State is stored in tool result details for proper branching support.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Text, truncateToWidth, matchesKey, Key } from "@mariozechner/pi-tui";
+
+interface {{ItemType}} {
+  id: number;
+  // Add fields
+}
+
+interface {{ToolDetails}} {
+  action: string;
+  items: {{ItemType}}[];
+  nextId: number;
+  error?: string;
+}
+
+export default function (pi: ExtensionAPI) {
+  let items: {{ItemType}}[] = [];
+  let nextId = 1;
+
+  // Reconstruct state from session
+  const reconstructState = (ctx: ExtensionContext) => {
+    items = [];
+    nextId = 1;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "toolResult") {
+        if (entry.message.toolName === "{{tool_name}}") {
+          const details = entry.message.details as {{ToolDetails}} | undefined;
+          if (details) {
+            items = details.items;
+            nextId = details.nextId;
+          }
+        }
+      }
+    }
+  };
+
+  // Reconstruct on ALL session change events
+  pi.on("session_start", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_switch", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_fork", async (_event, ctx) => reconstructState(ctx));
+  pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
+
+  // Register the tool
+  pi.registerTool({
+    name: "{{tool_name}}",
+    label: "{{Tool Label}}",
+    description: "{{Description for LLM}}",
+    parameters: Type.Object({
+      action: StringEnum(["list", "add", "remove"] as const),
+      text: Type.Optional(Type.String({ description: "Item text" })),
+      id: Type.Optional(Type.Number({ description: "Item ID" })),
+    }),
+
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      if (signal?.aborted) {
+        return { content: [{ type: "text", text: "Cancelled" }] };
+      }
+
+      switch (params.action) {
+        case "list":
+          return {
+            content: [{ type: "text", text: items.length ? JSON.stringify(items) : "No items" }],
+            details: { action: "list", items: [...items], nextId } as {{ToolDetails}},
+          };
+
+        case "add": {
+          if (!params.text) throw new Error("text required for add");
+          const item: {{ItemType}} = { id: nextId++ /* , ... */ };
+          items.push(item);
+          return {
+            content: [{ type: "text", text: `Added #${item.id}` }],
+            details: { action: "add", items: [...items], nextId } as {{ToolDetails}},
+          };
+        }
+
+        case "remove": {
+          if (params.id === undefined) throw new Error("id required for remove");
+          const idx = items.findIndex(i => i.id === params.id);
+          if (idx === -1) throw new Error(`Item #${params.id} not found`);
+          items.splice(idx, 1);
+          return {
+            content: [{ type: "text", text: `Removed #${params.id}` }],
+            details: { action: "remove", items: [...items], nextId } as {{ToolDetails}},
+          };
+        }
+
+        default:
+          throw new Error(`Unknown action: ${params.action}`);
+      }
+    },
+
+    // Custom rendering
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("{{tool_name}} "));
+      text += theme.fg("muted", args.action);
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      const details = result.details as {{ToolDetails}} | undefined;
+      if (!details) return new Text("", 0, 0);
+      if (details.error) return new Text(theme.fg("error", details.error), 0, 0);
+      return new Text(theme.fg("success", `✓ ${details.action} (${details.items.length} items)`), 0, 0);
+    },
+  });
+
+  // User command to view state
+  pi.registerCommand("{{command_name}}", {
+    description: "View {{items}}",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Requires interactive mode", "error");
+        return;
+      }
+      await ctx.ui.custom<void>((_tui, theme, _kb, done) => ({
+        render(width: number): string[] {
+          const lines = [
+            "",
+            truncateToWidth(theme.fg("accent", ` {{Items}} (${items.length}) `), width),
+            "",
+          ];
+          for (const item of items) {
+            lines.push(truncateToWidth(`  #${item.id}`, width));
+          }
+          lines.push("", truncateToWidth(theme.fg("dim", "  Press Escape to close"), width), "");
+          return lines;
+        },
+        handleInput(data: string) {
+          if (matchesKey(data, Key.escape)) done();
+        },
+        invalidate() {},
+      }));
+    },
+  });
+}

package/src/resources/skills/create-gsd-extension/workflows/add-capability.md

@@ -0,0 +1,57 @@
+<required_reading>
+Read the reference file for the specific capability being added:
+- Tools → references/custom-tools.md
+- Commands → references/custom-commands.md
+- Events → references/events-reference.md
+- UI → references/custom-ui.md
+- Rendering → references/custom-rendering.md
+- State → references/state-management.md
+- System prompt → references/system-prompt-modification.md
+</required_reading>
+
+<process>
+
+## Step 1: Identify the Extension
+
+Locate the existing extension file. Check:
+- `~/.gsd/agent/extensions/` (global)
+- `.gsd/extensions/` (project-local)
+
+Read the current extension code to understand its structure.
+
+## Step 2: Add the Capability
+
+Add the new registration/hook inside the existing `export default function (pi: ExtensionAPI)` body. Follow the patterns in the relevant reference file.
+
+If the extension needs new imports, add them at the top of the file.
+
+## Step 3: Handle Structural Changes
+
+**Single file → Directory**: If the extension is outgrowing a single file:
+1. Create `~/.gsd/agent/extensions/my-extension/`
+2. Move the file to `index.ts`
+3. Extract helpers to separate files
+
+**Adding npm dependencies**: If new packages are needed:
+1. Create `package.json` in the extension directory
+2. Add dependencies
+3. Run `npm install`
+4. Add `"pi": { "extensions": ["./index.ts"] }` to package.json
+
+## Step 4: Test
+
+```bash
+/reload
+```
+
+Verify the new capability works alongside existing ones.
+
+</process>
+
+<success_criteria>
+Capability addition is complete when:
+- [ ] New capability added without breaking existing functionality
+- [ ] All new imports resolve
+- [ ] `/reload` succeeds
+- [ ] New tool/command/hook tested with real invocation
+</success_criteria>

package/src/resources/skills/create-gsd-extension/workflows/create-extension.md

@@ -0,0 +1,156 @@
+<required_reading>
+**Read these reference files before proceeding:**
+1. references/extension-lifecycle.md
+2. references/custom-tools.md (if building tools)
+3. references/custom-commands.md (if building commands)
+4. references/events-reference.md (if building event hooks)
+5. references/key-rules-gotchas.md (always)
+</required_reading>
+
+<process>
+
+## Step 1: Determine Scope and Placement
+
+Ask the user:
+- **Global** (`~/.gsd/agent/extensions/`) — Available in all GSD sessions
+- **Project-local** (`.gsd/extensions/`) — Available only in this project
+
+## Step 2: Determine Extension Capabilities
+
+Identify what the extension needs from the user's description:
+
+| Capability | API | When |
+|------------|-----|------|
+| Custom tool (LLM-callable) | `pi.registerTool()` | LLM needs to perform new actions |
+| Slash command | `pi.registerCommand()` | User needs direct actions |
+| Event interception | `pi.on("event", ...)` | Block/modify tool calls, inject context, react to lifecycle |
+| Custom UI | `ctx.ui.custom()` | Complex interactive displays |
+| System prompt modification | `before_agent_start` event | Add per-turn instructions |
+| Context filtering | `context` event | Modify messages sent to LLM |
+| State persistence | `details` in tool results or `pi.appendEntry()` | Stateful behavior |
+| Custom rendering | `renderCall` / `renderResult` | Control how tools appear in TUI |
+| Provider management | `pi.registerProvider()` | Custom model endpoints |
+| Keyboard shortcut | `pi.registerShortcut()` | Hotkey triggers |
+
+## Step 3: Choose Extension Structure
+
+**Single file** — for small extensions (1-2 tools/commands, simple hooks):
+```
+~/.gsd/agent/extensions/my-extension.ts
+```
+
+**Directory with index.ts** — for multi-file extensions:
+```
+~/.gsd/agent/extensions/my-extension/
+├── index.ts
+├── tools.ts
+└── utils.ts
+```
+
+**Package with dependencies** — when npm packages are needed:
+```
+~/.gsd/agent/extensions/my-extension/
+├── package.json
+├── src/index.ts
+└── node_modules/
+```
+
+For packages, `package.json` needs:
+```json
+{
+  "name": "my-extension",
+  "dependencies": { ... },
+  "pi": { "extensions": ["./src/index.ts"] }
+}
+```
+
+## Step 4: Write the Extension
+
+Start with the skeleton:
+
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  // Register events, tools, commands here
+}
+```
+
+Then add capabilities based on Step 2. Reference the appropriate reference files for each capability.
+
+**Tool registration pattern:**
+```typescript
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+
+pi.registerTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "What this tool does (shown to LLM)",
+  parameters: Type.Object({
+    action: StringEnum(["list", "add"] as const),
+    text: Type.Optional(Type.String({ description: "Item text" })),
+  }),
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    if (signal?.aborted) return { content: [{ type: "text", text: "Cancelled" }] };
+    return {
+      content: [{ type: "text", text: "Result for LLM" }],
+      details: { data: "for rendering and state" },
+    };
+  },
+});
+```
+
+**Command registration pattern:**
+```typescript
+pi.registerCommand("mycommand", {
+  description: "What this command does",
+  handler: async (args, ctx) => {
+    ctx.ui.notify(`Running with args: ${args}`, "info");
+  },
+});
+```
+
+**Event hook pattern:**
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+    return { block: true, reason: "Blocked dangerous command" };
+  }
+});
+```
+
+## Step 5: Test the Extension
+
+```bash
+# Quick test without installing
+gsd -e ./path/to/my-extension.ts
+
+# Or place in extensions dir and reload
+/reload
+```
+
+Verify:
+- Extension loads without errors (check GSD startup output)
+- Tools appear when LLM is asked to use them
+- Commands respond to `/mycommand`
+- Event hooks trigger at expected points
+
+## Step 6: Iterate
+
+Fix issues, add features, refine. Use `/reload` for hot-reload during development.
+
+</process>
+
+<success_criteria>
+Extension creation is complete when:
+- [ ] Extension file(s) written to correct location
+- [ ] All imports resolve (TypeBox, pi-ai, pi-coding-agent, pi-tui as needed)
+- [ ] Tools use `StringEnum` for string enums (not `Type.Union`/`Type.Literal`)
+- [ ] Tool output is truncated if variable-length
+- [ ] State stored in `details` if extension is stateful
+- [ ] `ctx.hasUI` checked before dialog methods
+- [ ] Extension loads on `/reload` without errors
+- [ ] Tools callable by LLM, commands by user
+- [ ] Tested with at least one real invocation
+</success_criteria>

package/src/resources/skills/create-gsd-extension/workflows/debug-extension.md

@@ -0,0 +1,74 @@
+<required_reading>
+1. references/key-rules-gotchas.md
+2. references/extension-lifecycle.md
+</required_reading>
+
+<process>
+
+## Step 1: Identify the Symptom
+
+| Symptom | Likely Cause |
+|---------|--------------|
+| Extension not loading | File not in discovery path, syntax error, missing export default |
+| Tool not appearing for LLM | Tool not registered, `pi.setActiveTools()` excluding it, tool name conflict |
+| Command not responding | Command not registered, name collision with built-in |
+| Event not firing | Wrong event name, handler returning too early, handler error (logged but swallowed) |
+| UI not rendering | `ctx.hasUI` is false (print mode), render lines exceed width, component not returning lines |
+| State lost on restart | State not stored in `details` or `appendEntry`, not reconstructing on `session_start` |
+| Google API errors | Using `Type.Union`/`Type.Literal` instead of `StringEnum` |
+| Context overflow | Tool output not truncated |
+| Deadlock/hang | Session control methods called from event handler (must be in command handler only) |
+| Render garbage | Theme imported directly instead of from callback, missing `truncateToWidth()` |
+
+## Step 2: Check Extension Loading
+
+```bash
+# Test in isolation
+gsd -e ./path/to/extension.ts
+
+# Check GSD startup output for errors
+# Extension errors are logged but don't crash GSD
+```
+
+## Step 3: Verify File Location
+
+Extensions must be in auto-discovery paths:
+- `~/.gsd/agent/extensions/*.ts`
+- `~/.gsd/agent/extensions/*/index.ts`
+- `.gsd/extensions/*.ts`
+- `.gsd/extensions/*/index.ts`
+
+The file must `export default function(pi: ExtensionAPI) { ... }`.
+
+## Step 4: Check for Common Mistakes
+
+Read `references/key-rules-gotchas.md` and verify each rule against the extension code.
+
+## Step 5: Add Debugging
+
+```typescript
+// Temporary: log to stderr (visible in GSD output)
+console.error("[my-ext] Loading...");
+
+pi.on("session_start", async (_event, ctx) => {
+  console.error("[my-ext] Session started");
+  ctx.ui.notify("Extension loaded", "info");
+});
+```
+
+## Step 6: Fix and Reload
+
+Apply the fix and test:
+```
+/reload
+```
+
+</process>
+
+<success_criteria>
+Debugging is complete when:
+- [ ] Root cause identified
+- [ ] Fix applied
+- [ ] Extension loads and functions correctly after `/reload`
+- [ ] No regression in existing functionality
+</success_criteria>

package/src/resources/skills/create-skill/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: create-skill
+description: Expert guidance for creating, writing, building, and refining GSD skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
+---
+
+<essential_principles>
+## How Skills Work
+
+Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills.
+
+### 1. Skills Are Prompts
+
+All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.
+
+### 2. SKILL.md Is Always Loaded
+
+When a skill is invoked, Claude reads SKILL.md. Use this guarantee:
+- Essential principles go in SKILL.md (can't be skipped)
+- Workflow-specific content goes in workflows/
+- Reusable knowledge goes in references/
+
+### 3. Router Pattern for Complex Skills
+
+```
+skill-name/
+├── SKILL.md              # Router + principles
+├── workflows/            # Step-by-step procedures (FOLLOW)
+├── references/           # Domain knowledge (READ)
+├── templates/            # Output structures (COPY + FILL)
+└── scripts/              # Reusable code (EXECUTE)
+```
+
+SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read.
+
+**When to use each folder:**
+- **workflows/** - Multi-step procedures Claude follows
+- **references/** - Domain knowledge Claude reads for context
+- **templates/** - Consistent output structures Claude copies and fills (plans, specs, configs)
+- **scripts/** - Executable code Claude runs as-is (deploy, setup, API calls)
+
+### 4. Pure XML Structure
+
+No markdown headings (#, ##, ###) in skill body. Use semantic XML tags:
+```xml
+<objective>...</objective>
+<process>...</process>
+<success_criteria>...</success_criteria>
+```
+
+Keep markdown formatting within content (bold, lists, code blocks).
+
+### 5. Progressive Disclosure
+
+SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow.
+</essential_principles>
+
+<routing>
+## Understanding User Intent
+
+Based on the user's message, route directly to the appropriate workflow:
+
+**Creating new skills:**
+- Domain expertise (exhaustive knowledge base) → **Use `create-domain-expertise` skill instead** (separate skill with batched subagent orchestration)
+- Task-execution skill (does specific things) → workflows/create-new-skill.md
+
+**Working with existing skills:**
+- Audit, review, check → workflows/audit-skill.md
+- Verify content is current → workflows/verify-skill.md
+- Add workflow → workflows/add-workflow.md
+- Add reference → workflows/add-reference.md
+- Add template → workflows/add-template.md
+- Add script → workflows/add-script.md
+- Upgrade to router pattern → workflows/upgrade-to-router.md
+
+**Need help deciding:**
+- General guidance → workflows/get-guidance.md
+
+**If user intent is unclear, ask minimal clarifying questions:**
+- "Create a MIDI skill" → "Task-execution skill (does MIDI tasks) or domain expertise (complete MIDI knowledge base)?"
+- "Work on my skill" → "Which skill? What do you want to do with it?"
+
+Then proceed directly to the workflow.
+</routing>
+
+<quick_reference>
+## Skill Structure Quick Reference
+
+**Skill directories:**
+- Global: `~/.gsd/agent/skills/{skill-name}/`
+- Project-local: `.pi/agent/skills/{skill-name}/`
+
+**Simple skill (single file):**
+```yaml
+---
+name: skill-name
+description: What it does and when to use it.
+---
+
+<objective>What this skill does</objective>
+<quick_start>Immediate actionable guidance</quick_start>
+<process>Step-by-step procedure</process>
+<success_criteria>How to know it worked</success_criteria>
+```
+
+**Complex skill (router pattern):**
+```
+SKILL.md:
+  <essential_principles> - Always applies
+  <intake> - Question to ask
+  <routing> - Maps answers to workflows
+
+workflows/:
+  <required_reading> - Which refs to load
+  <process> - Steps
+  <success_criteria> - Done when...
+
+references/:
+  Domain knowledge, patterns, examples
+
+templates/:
+  Output structures Claude copies and fills
+  (plans, specs, configs, documents)
+
+scripts/:
+  Executable code Claude runs as-is
+  (deploy, setup, API calls, data processing)
+```
+</quick_reference>
+
+<reference_index>
+## Domain Knowledge
+
+All in `references/`:
+
+**Structure:** recommended-structure.md, skill-structure.md
+**Principles:** core-principles.md, be-clear-and-direct.md, use-xml-tags.md
+**Patterns:** common-patterns.md, workflows-and-validation.md
+**Assets:** using-templates.md, using-scripts.md
+**Advanced:** executable-code.md, api-security.md, iteration-and-testing.md
+**GSD-specific:** gsd-skill-ecosystem.md
+</reference_index>
+
+<workflows_index>
+## Workflows
+
+All in `workflows/`:
+
+| Workflow | Purpose |
+|----------|---------|
+| create-new-skill.md | Build a task-execution skill from scratch |
+| audit-skill.md | Analyze skill against best practices |
+| verify-skill.md | Check if content is still accurate |
+| add-workflow.md | Add a workflow to existing skill |
+| add-reference.md | Add a reference to existing skill |
+| add-template.md | Add a template to existing skill |
+| add-script.md | Add a script to existing skill |
+| upgrade-to-router.md | Convert simple skill to router pattern |
+| get-guidance.md | Help decide what kind of skill to build |
+</workflows_index>
+
+<yaml_requirements>
+## YAML Frontmatter
+
+Required fields:
+```yaml
+---
+name: skill-name          # lowercase-with-hyphens, matches directory
+description: ...          # What it does AND when to use it (third person)
+---
+```
+
+Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*`
+</yaml_requirements>
+
+<success_criteria>
+A well-structured skill:
+- Has valid YAML frontmatter
+- Uses pure XML structure (no markdown headings in body)
+- Has essential principles inline in SKILL.md
+- Routes directly to appropriate workflows based on user intent
+- Keeps SKILL.md under 500 lines
+- Asks minimal clarifying questions only when truly needed
+- Has been tested with real usage
+</success_criteria>