@counterposition/skill-pi 0.1.0

package/skills/pi/references/sdk.md

@@ -0,0 +1,177 @@
+# SDK
+
+The SDK lets you embed Pi programmatically in Node.js applications via `createAgentSession()`.
+
+## Installation
+
+```bash
+npm install @mariozechner/pi-coding-agent
+```
+
+## Quick Start
+
+```typescript
+import { createAgentSession } from "@mariozechner/pi-coding-agent";
+
+const { session } = await createAgentSession();
+
+session.subscribe((event) => {
+  if (event.type === "message_update" && event.delta?.type === "text_delta") {
+    process.stdout.write(event.delta.text);
+  }
+  if (event.type === "agent_end") {
+    console.log("\nDone.");
+  }
+});
+
+await session.prompt("List all TypeScript files in the current directory");
+```
+
+Run with: `npx tsx my-script.ts`
+
+## Factory Options
+
+```typescript
+const { session } = await createAgentSession({
+  // Authentication
+  authStorage: new AuthStorage({ path: "~/.pi/agent/auth.json" }),
+
+  // Model configuration
+  modelRegistry: new ModelRegistry(),
+  model: getModel("anthropic", "claude-sonnet-4-20250514"),
+  thinkingLevel: "medium",
+
+  // Working directory
+  cwd: process.cwd(),
+
+  // Agent config directory
+  agentDir: "~/.pi/agent",
+
+  // Tools (built-in presets or custom)
+  tools: codingTools(),          // Default: read, bash, edit, write
+  // tools: readOnlyTools(),     // read, grep, find, ls
+  // tools: allTools(),          // All seven built-in tools
+
+  // Resource discovery
+  resourceLoader: new DefaultResourceLoader(),
+
+  // Extensions (inline factories)
+  extensionFactories: [
+    (pi) => {
+      pi.on("agent_start", async () => { /* ... */ });
+    },
+  ],
+
+  // Session persistence
+  sessionManager: SessionManager.create("path/to/session.jsonl"),
+  // sessionManager: SessionManager.inMemory(),  // No persistence
+
+  // Settings
+  settings: new SettingsManager({ /* ... */ }),
+
+  // System prompt
+  systemPrompt: "Custom system prompt",
+});
+```
+
+## Key Imports
+
+```typescript
+import {
+  createAgentSession,
+  // Auth & config
+  AuthStorage,
+  ModelRegistry,
+  SettingsManager,
+  SessionManager,
+  DefaultResourceLoader,
+  // Tools
+  codingTools,
+  readOnlyTools,
+  allTools,
+  readTool,
+  bashTool,
+  editTool,
+  writeTool,
+  grepTool,
+  findTool,
+  lsTool,
+  // Models
+  getModel,
+} from "@mariozechner/pi-coding-agent";
+```
+
+## Event Types
+
+```typescript
+session.subscribe((event) => {
+  switch (event.type) {
+    // Streaming
+    case "message_start":     // New assistant message begins
+    case "message_update":    // Text/thinking/tool-call delta
+    case "message_end":       // Assistant message complete (includes full message)
+
+    // Tool execution
+    case "tool_execution_start":  // Tool begins (toolCallId, toolName)
+    case "tool_execution_update": // Partial tool output
+    case "tool_execution_end":    // Tool complete (toolCallId, result)
+
+    // Lifecycle
+    case "agent_start":       // Agent begins processing
+    case "agent_end":         // Agent finishes
+    case "turn_start":        // New LLM turn
+    case "turn_end":          // LLM turn complete
+
+    // System
+    case "auto_compaction_start":
+    case "auto_compaction_end":
+    case "auto_retry_start":
+    case "auto_retry_end":
+  }
+});
+```
+
+## Session Methods
+
+```typescript
+// Send a prompt
+await session.prompt("Do something");
+
+// Queue message during active streaming
+session.steer("Actually, do this instead");   // Interrupts current tool execution
+session.followUp("After you're done, also..."); // Queued until agent finishes
+
+// Control
+session.abort();                    // Cancel current generation
+await session.waitForIdle();        // Wait until agent is idle
+
+// Model
+session.setModel(getModel("openai", "gpt-4o"));
+session.setThinkingLevel("high");
+session.cycleModel();
+
+// Compaction
+await session.compact();
+
+// State
+const messages = session.getMessages();
+const state = session.getState();
+```
+
+## Run Modes
+
+For non-SDK usage, Pi provides run mode functions:
+
+```typescript
+import { runPrintMode, runRpcMode, InteractiveMode } from "@mariozechner/pi-coding-agent";
+
+// Print mode (single-shot)
+await runPrintMode(session, { outputFormat: "text" }); // or "json"
+
+// RPC mode (JSON-RPC over stdin/stdout)
+await runRpcMode(session);
+
+// Interactive mode (full TUI)
+const mode = new InteractiveMode(session);
+await mode.start();
+```

package/skills/pi/references/settings.md

@@ -0,0 +1,170 @@
+# Settings
+
+Pi uses hierarchical JSON configuration. Project settings (`.pi/settings.json`) merge over global settings (`~/.pi/agent/settings.json`). Nested objects are deep-merged; project values override global for the same key.
+
+Edit settings directly or use `/settings` in interactive mode.
+
+## Complete Settings Reference
+
+### Model & Thinking
+
+```json
+{
+  "provider": "anthropic",           // Default provider name
+  "model": "claude-sonnet-4-20250514", // Default model ID
+  "thinkingLevel": "medium",         // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
+  "thinkingLevelBudget": null,       // Custom token budget per thinking level (overrides defaults)
+  "modelCyclePatterns": ["claude-*", "gpt-4o"]  // Glob patterns for Ctrl+P model cycling
+}
+```
+
+### Compaction
+
+```json
+{
+  "compaction": {
+    "enabled": true,                 // Enable auto-compaction
+    "reserveTokens": 16384,          // Tokens to reserve for new responses
+    "keepRecentTokens": 20000        // Recent tokens to keep uncompacted
+  }
+}
+```
+
+### Branch Summary
+
+```json
+{
+  "branchSummary": {
+    "enabled": true,                 // Summarize when switching branches via /tree
+    "maxTokens": 4096,              // Max tokens for summary
+    "skipPrompt": false              // Skip confirmation prompt
+  }
+}
+```
+
+### Retry
+
+```json
+{
+  "retry": {
+    "maxRetries": 3,                 // Max automatic retries on transient errors
+    "initialDelayMs": 2000,          // First retry delay
+    "maxDelayMs": 60000              // Max delay (exponential backoff)
+  }
+}
+```
+
+### Message Delivery
+
+```json
+{
+  "steeringMode": "all",            // "all" | "one-at-a-time" — how steer messages are delivered
+  "followUpMode": "all",            // "all" | "one-at-a-time" — how follow-up messages are delivered
+  "transport": "auto"               // "sse" | "websocket" | "auto"
+}
+```
+
+### Terminal & Images
+
+```json
+{
+  "terminal": {
+    "showImages": true,              // Display images in terminal
+    "maxImageWidth": 2000,           // Max image dimensions for resizing
+    "maxImageHeight": 2000
+  },
+  "image": {
+    "autoResize": true               // Auto-resize large images before sending to LLM
+  }
+}
+```
+
+### Shell
+
+```json
+{
+  "shellPath": "/bin/bash",          // Custom shell path (Windows: "C:\\...\\bash.exe")
+  "shellCommandPrefix": "",          // Prefix prepended to every bash command
+  "npmCommand": "npm"                // npm, pnpm, yarn, bun
+}
+```
+
+### UI
+
+```json
+{
+  "theme": "dark",                   // "dark" | "light" | custom theme name
+  "showStartupBanner": true,         // Show banner on startup
+  "editorPadding": 1,               // Lines of padding in editor
+  "showAutoComplete": true,          // Show autocomplete suggestions
+  "cursorStyle": "block"            // "block" | "underline" | "bar"
+}
+```
+
+### Sessions
+
+```json
+{
+  "sessionDir": null                 // Custom session storage path (default: ~/.pi/agent/sessions/)
+}
+```
+
+### Resources
+
+Load extensions, skills, prompts, and themes from paths or packages:
+
+```json
+{
+  "extensions": [
+    "~/.pi/agent/extensions/my-ext.ts",
+    "npm:@foo/pi-extensions"
+  ],
+  "skills": [
+    ".pi/skills/my-skill",
+    "npm:@foo/pi-skills"
+  ],
+  "prompts": [
+    "~/.pi/agent/prompts/"
+  ],
+  "themes": [
+    "npm:@foo/pi-themes"
+  ],
+  "customPackages": [
+    "npm:@foo/pi-package@1.0.0",
+    "git:github.com/user/repo",
+    "./local/path"
+  ]
+}
+```
+
+### Resource Pattern Matching
+
+Resources support include/exclude patterns:
+
+```json
+{
+  "skills": [
+    "npm:@foo/pi-skills",      // Include all skills from package
+    "!secret-skill",            // Exclude by name
+    "+override-skill",          // Force-include (overrides exclusions)
+    "-unwanted-skill"           // Force-exclude (overrides inclusions)
+  ]
+}
+```
+
+## Environment Variables
+
+| Variable | Effect |
+|----------|--------|
+| `PI_CODING_AGENT_DIR` | Override global config directory (default: `~/.pi/agent/`) |
+| `PI_OFFLINE` | Disable package updates and tool downloads |
+| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `OPENAI_API_KEY` | OpenAI API key |
+| Additional provider env vars | See `references/providers.md` |
+
+## Editing Tips
+
+- Use `/settings` in interactive mode for a guided editor
+- Project settings are committed to version control (`.pi/settings.json`) for team sharing
+- Global settings (`~/.pi/agent/settings.json`) are personal
+- Settings reload on next agent start — no restart needed for most changes

package/skills/pi/references/skills.md

@@ -0,0 +1,111 @@
+# Skills
+
+Skills are self-contained capability packages that Pi's agent loads on demand. They follow the [Agent Skills standard](https://github.com/anthropics/agent-skills).
+
+## How Skills Work
+
+1. At startup, Pi discovers all skills and loads their **name + description** into the system prompt as XML.
+2. When the agent encounters a task matching a skill's description, it uses the `read` tool to load the full `SKILL.md`.
+3. The skill body contains detailed instructions, and may reference additional files in subdirectories.
+
+This progressive disclosure keeps the system prompt lean while making deep knowledge available when needed.
+
+## Directory Structure
+
+```text
+my-skill/
+├── SKILL.md                    # Required — frontmatter + instructions
+├── scripts/                    # Optional — executable helper scripts
+│   └── build.sh
+├── references/                 # Optional — docs loaded into context as needed
+│   └── api-reference.md
+└── assets/                     # Optional — templates, icons, fonts
+    └── template.html
+```
+
+## SKILL.md Format
+
+```markdown
+---
+name: my-skill
+description: "What this skill does and when to use it. Be specific about trigger phrases and contexts — Pi tends to under-trigger skills, so make descriptions slightly assertive."
+license: MIT
+compatibility: "Requires bash and node tools"
+---
+
+# My Skill
+
+Instructions for the agent go here. Write in imperative form.
+Use markdown formatting. Reference supporting files with relative paths.
+
+## Step 1: Do the thing
+
+Read `references/api-reference.md` for the full API spec, then...
+```
+
+## Frontmatter Fields
+
+| Field | Required | Constraints | Notes |
+|-------|----------|------------|-------|
+| `name` | Yes | 1–64 chars, lowercase `[a-z0-9-]` | Should match directory name |
+| `description` | Yes | Max 1024 chars | Primary trigger mechanism — include trigger phrases |
+| `license` | No | String | License identifier |
+| `compatibility` | No | String | Tool/dependency requirements |
+| `allowed-tools` | No | List | Restrict which tools the skill can use |
+| `disable-model-invocation` | No | Boolean | If true, agent cannot auto-invoke this skill |
+
+## Discovery Locations
+
+Skills are discovered from (in priority order — first wins on name collision):
+
+1. `.pi/skills/` — project-local
+2. `~/.pi/agent/skills/` — global
+3. Installed packages (via `pi install`)
+4. `settings.json` → `skills` array
+5. `pi --skills <path>` CLI argument
+
+Discovery respects `.gitignore`, `.ignore`, and `.fdignore` patterns.
+
+## Invocation
+
+- **Manual:** User types `/skill:my-skill` in the editor
+- **Automatic:** Agent reads the skill when it matches the task (progressive disclosure)
+- **Disable auto-invoke:** Set `disable-model-invocation: true` in frontmatter
+
+## Writing Good Skills
+
+### Descriptions
+
+The description is the **primary trigger mechanism**. Make it assertive and specific:
+
+**Bad:** `"A tool for working with Docker"`
+
+**Good:** `"How to build, run, and debug Docker containers and docker-compose setups. Use this skill whenever the user mentions Docker, containers, docker-compose, Dockerfiles, container orchestration, or asks about building/deploying containerized applications."`
+
+### Body Structure
+
+- Keep SKILL.md under 500 lines. If approaching this limit, split detail into `references/` files with clear pointers.
+- Write in imperative form: "Run the build script" not "You should run the build script."
+- Explain **why** behind instructions so the model can adapt to edge cases.
+- Include concrete examples with input/output pairs.
+- For multi-domain skills, organize by variant in `references/` and let SKILL.md route to the right one.
+
+### Reference Files
+
+- Reference with relative paths: `Read references/aws.md for AWS-specific steps.`
+- For files over 300 lines, include a table of contents at the top.
+- The model reads these with the `read` tool — they don't go into the system prompt.
+
+### Helper Scripts
+
+Place in `scripts/`. The model can execute them via the `bash` tool. This avoids the model reinventing the wheel for deterministic operations.
+
+## Validation
+
+Pi validates skills at load time:
+
+- Missing `description` → skill not loaded
+- Name > 64 chars → warning
+- Description > 1024 chars → warning
+- Name-directory mismatch → warning
+- Duplicate names → first discovered wins, warning issued