iosm-cli 0.1.0

package/docs/extensions-packages-themes.md

@@ -0,0 +1,415 @@
+# Extensions, Packages, Skills, Themes
+
+`iosm-cli` has a rich customization system supporting extensions (TypeScript modules), skills (Markdown workflows), prompt templates, themes, and package distribution.
+
+---
+
+## Extensions
+
+Extensions are TypeScript modules that can register tools, commands, lifecycle hooks, UI components, and provider integrations.
+
+### Loading Extensions
+
+```bash
+# Via CLI flag (repeatable)
+iosm -e ./my-extension.ts
+iosm -e ./gate.ts -e ./logger.ts
+
+# Disable all auto-discovered extensions
+iosm --no-extensions
+```
+
+### Auto-Discovery Directories
+
+| Location | Scope |
+|----------|-------|
+| `~/.iosm/agent/extensions/` | Global (all projects) |
+| `.iosm/extensions/` | Project-local |
+
+Extensions are auto-loaded from these directories. Use `/reload` in interactive mode to hot-reload after changes.
+
+### Writing an Extension
+
+```typescript
+import type { ExtensionAPI } from "iosm-cli";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+  // Everything goes here: tools, commands, hooks, UI
+}
+```
+
+### Registering Custom Tools
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "weather",
+    label: "Weather",
+    description: "Get current weather for a city",
+    parameters: Type.Object({
+      city: Type.String({ description: "City name" }),
+    }),
+    async execute(toolCallId, params, onUpdate, ctx, signal) {
+      const data = await fetch(`https://api.example.com/weather?city=${params.city}`);
+      const json = await data.json();
+      return {
+        content: [{ type: "text", text: `Weather in ${params.city}: ${json.temp}°C` }],
+        details: { raw: json }, // Persisted in session for fork support
+      };
+    },
+  });
+}
+```
+
+> **Note**: Use `StringEnum` instead of `Type.Union` for string enum parameters (required for Google API compatibility):
+> ```typescript
+> import { StringEnum } from "@mariozechner/pi-ai";
+> action: StringEnum(["add", "remove", "list"] as const)
+> ```
+
+### Registering Commands
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("deploy", {
+    description: "Deploy to staging environment",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Starting deployment...", "info");
+      // Execute deployment logic
+      const result = await ctx.exec("npm", ["run", "deploy:staging"]);
+      ctx.ui.notify(
+        result.exitCode === 0 ? "Deployment successful!" : "Deployment failed!",
+        result.exitCode === 0 ? "info" : "error"
+      );
+    },
+  });
+}
+```
+
+### Lifecycle Hooks
+
+| Hook | Trigger |
+|------|---------|
+| `session_start` | When a session begins or is resumed |
+| `before_agent_start` | Before the agent processes a message |
+| `tool_call` | Before a tool executes (can block/modify) |
+| `tool_result` | After a tool returns results |
+| `turn_start` | When a new conversation turn begins |
+| `turn_end` | When a conversation turn ends |
+| `agent_end` | When the agent finishes responding |
+| `model_select` | When the model is changed |
+| `input` | When user input is received |
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  // Block dangerous commands
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash") {
+      const cmd = event.input.command || "";
+      if (cmd.includes("rm -rf /")) {
+        return { block: true, reason: "Blocked: dangerous command" };
+      }
+    }
+  });
+
+  // Log all tool usage
+  pi.on("tool_result", async (event, ctx) => {
+    console.log(`Tool: ${event.toolName}, Duration: ${event.duration}ms`);
+  });
+
+  // Modify system prompt dynamically
+  pi.on("before_agent_start", async (event, ctx) => {
+    event.systemPromptAppend = "\n\nAlways explain your reasoning step by step.";
+  });
+
+  // React to session start
+  pi.on("session_start", async (event, ctx) => {
+    // Reconstruct state from previous tool results
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.toolName === "weather") {
+        // Rebuild internal state from persisted details
+      }
+    }
+  });
+}
+```
+
+### UI Extensions
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  // Custom footer
+  pi.on("turn_end", async (event, ctx) => {
+    ctx.ui.setFooter("left", `Tokens: ${event.usage?.totalTokens || 0}`);
+  });
+
+  // Custom status
+  pi.on("turn_start", async (event, ctx) => {
+    ctx.ui.setStatus("Thinking...", "info");
+  });
+
+  // Interactive confirmation
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "write") {
+      const ok = await ctx.ui.confirm(
+        "Write Confirmation",
+        `Allow write to ${event.input.file_path}?`
+      );
+      if (!ok) return { block: true, reason: "User denied" };
+    }
+  });
+
+  // Selection dialog
+  pi.registerCommand("pick-model", {
+    description: "Pick a model from a list",
+    handler: async (args, ctx) => {
+      const choice = await ctx.ui.select("Select Model", [
+        { label: "Claude Sonnet", value: "sonnet" },
+        { label: "GPT-4o", value: "gpt-4o" },
+        { label: "Gemini Pro", value: "gemini-pro" },
+      ]);
+      if (choice) {
+        ctx.ui.notify(`Selected: ${choice}`, "info");
+      }
+    },
+  });
+}
+```
+
+### State Persistence Pattern
+
+Store state in tool result `details` for proper session forking support:
+
+```typescript
+let todos: string[] = [];
+
+pi.registerTool({
+  name: "todo",
+  label: "Todo List",
+  description: "Manage a todo list",
+  parameters: Type.Object({
+    action: StringEnum(["add", "list", "remove"] as const),
+    item: Type.Optional(Type.String()),
+  }),
+  async execute(toolCallId, params) {
+    if (params.action === "add" && params.item) {
+      todos.push(params.item);
+    }
+    // State is persisted in details for fork support
+    return {
+      content: [{ type: "text", text: todos.join("\n") }],
+      details: { todos: [...todos] },
+    };
+  },
+});
+
+// Reconstruct state on session resume/fork
+pi.on("session_start", async (_event, ctx) => {
+  todos = [];
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.toolName === "todo") {
+      todos = entry.message.details?.todos || [];
+    }
+  }
+});
+```
+
+### 66 Extension Examples
+
+See [examples/extensions/](../examples/extensions/) for a comprehensive library including:
+
+| Category | Examples |
+|----------|---------|
+| **Safety** | Permission gates, protected paths, destructive action confirmation |
+| **Tools** | Todo lists, SSH delegation, image generation, dynamic tool registration |
+| **UI** | Custom footers/headers, overlays (including DOOM!), modal editors, notifications |
+| **Git** | Checkpoint stashing, auto-commit on exit |
+| **System** | macOS theme sync, file watchers, interactive shell |
+| **Providers** | Custom Anthropic, GitLab Duo, Qwen CLI |
+| **Session** | Named sessions, bookmarks, context handoff |
+
+---
+
+## Skills
+
+Skills are Markdown-based workflow modules that provide structured instructions to the agent.
+
+### Structure
+
+Each skill is a `SKILL.md` file with YAML frontmatter:
+
+```markdown
+---
+name: deploy-workflow
+description: Steps to deploy the application to production
+---
+
+## Deployment Steps
+
+1. Run the test suite: `npm test`
+2. Build production assets: `npm run build`
+3. Deploy to staging: `npm run deploy:staging`
+4. Run smoke tests against staging
+5. If all pass, deploy to production: `npm run deploy:prod`
+6. Monitor error rates for 30 minutes
+```
+
+### Discovery Directories
+
+| Location | Scope |
+|----------|-------|
+| `~/.iosm/agent/skills/` | Global |
+| `.iosm/skills/` | Project-local |
+| `.claude/skills/` | Compatibility |
+| `.opencode/skills/` | Compatibility |
+
+### CLI Flags
+
+```bash
+# Load specific skill
+iosm --skill ./my-workflow.md
+
+# Disable auto-discovery
+iosm --no-skills
+```
+
+---
+
+## Prompt Templates
+
+Prompt templates are reusable Markdown snippets invoked as slash commands.
+
+### Structure
+
+Create files in the prompts directory:
+
+```markdown
+<!-- ~/.iosm/agent/prompts/code-review.md -->
+---
+name: code-review
+description: Thorough code review template
+---
+
+Please review the following code for:
+1. Security vulnerabilities
+2. Performance issues
+3. Code style and readability
+4. Error handling completeness
+5. Test coverage gaps
+```
+
+### Discovery Directories
+
+| Location | Scope |
+|----------|-------|
+| `~/.iosm/agent/prompts/*.md` | Global |
+| `.iosm/prompts/*.md` | Project-local |
+
+### Usage
+
+```bash
+# In interactive mode
+/code-review src/auth.ts
+```
+
+### CLI Flags
+
+```bash
+iosm --prompt-template ./my-template.md
+iosm --no-prompt-templates
+```
+
+---
+
+## Themes
+
+Theme files customize the TUI (Terminal User Interface) appearance.
+
+### Structure
+
+Themes are JSON files:
+
+```json
+{
+  "name": "dark-ocean",
+  "colors": {
+    "primary": "#0ea5e9",
+    "secondary": "#6366f1",
+    "success": "#22c55e",
+    "warning": "#f59e0b",
+    "error": "#ef4444",
+    "background": "#0f172a",
+    "foreground": "#e2e8f0"
+  }
+}
+```
+
+### Discovery Directories
+
+| Location | Scope |
+|----------|-------|
+| Built-in themes | Default |
+| `~/.iosm/agent/themes/*.json` | Global |
+| `.iosm/themes/*.json` | Project-local |
+
+### CLI Flags
+
+```bash
+iosm --theme ./my-theme.json
+iosm --no-themes
+```
+
+---
+
+## Package Management
+
+Distribute and install extensions, skills, themes, and prompts as packages.
+
+### Commands
+
+```bash
+iosm install <source> [-l|--local]    # Install a package
+iosm remove <source> [-l|--local]     # Remove a package
+iosm update [source]                   # Update package(s)
+iosm list                              # List installed packages
+```
+
+### Source Formats
+
+| Format | Example |
+|--------|---------|
+| **npm** | `npm:@my-org/iosm-tools@1.0.0` |
+| **git** | `git:github.com/user/repo@main` |
+| **HTTPS** | `https://github.com/user/repo.git` |
+| **SSH** | `ssh://git@github.com/user/repo.git` |
+| **Local** | `./local-path`, `/absolute/path` |
+
+### Project vs Global Install
+
+```bash
+# Global (available in all projects)
+iosm install npm:@my-org/security-tools
+
+# Project-local (only this project)
+iosm install npm:@my-org/security-tools --local
+```
+
+### Package Manifest
+
+Packages should include a manifest in `package.json`:
+
+```json
+{
+  "name": "@my-org/iosm-security-tools",
+  "version": "1.0.0",
+  "iosm": {
+    "extensions": ["./extensions"],
+    "skills": ["./skills"],
+    "prompts": ["./prompts"],
+    "themes": ["./themes"]
+  }
+}
+```
+
+This tells `iosm-cli` which resources to load from the package.

package/docs/getting-started.md

@@ -0,0 +1,246 @@
+# Getting Started
+
+Welcome to `iosm-cli` — an AI-powered engineering agent with the IOSM (Improve → Optimize → Shrink → Modularize) methodology built in.
+
+## Requirements
+
+- **Node.js** `>=20.6.0` (check with `node --version`)
+- **npm** (bundled with Node.js)
+- At least one LLM provider API key
+
+## Installation
+
+### Option 1: Global Install (recommended)
+
+```bash
+npm install -g iosm-cli
+iosm --version
+```
+
+### Option 2: Run Without Installing
+
+```bash
+npx iosm-cli --version
+```
+
+### Option 3: Build from Source
+
+```bash
+git clone https://github.com/rokoss21/iosm-cli.git
+cd iosm-cli
+npm install
+npm run build
+npm link    # Makes `iosm` available globally
+```
+
+## Provider Setup
+
+You need at least one LLM provider. Set the API key as an environment variable:
+
+### Anthropic (Claude)
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-api03-..."
+```
+
+### OpenAI
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+### Google Gemini
+
+```bash
+export GEMINI_API_KEY="AI..."
+```
+
+### Other Providers
+
+```bash
+export GROQ_API_KEY="gsk_..."
+export XAI_API_KEY="xai-..."
+export OPENROUTER_API_KEY="sk-or-..."
+export MISTRAL_API_KEY="..."
+```
+
+You can also use `/login` in interactive mode for OAuth providers (including free Qwen OAuth) and OpenRouter API key setup:
+
+```bash
+iosm
+# Inside interactive mode:
+/login
+```
+
+> **Tip**: Add your API key exports to `~/.zshrc` or `~/.bashrc` so they persist across sessions.
+
+## First Run
+
+### Interactive Mode
+
+Start the agent in interactive mode:
+
+```bash
+iosm
+```
+
+You'll see a prompt where you can type messages. The agent has access to your filesystem and shell tools.
+
+**Useful first commands inside the agent:**
+
+| Command | What it does |
+|---------|-------------|
+| `/model` | Pick or change the active model |
+| `/login` | Authenticate with OAuth providers (including Qwen) or add OpenRouter API key |
+| `/init` | Bootstrap IOSM artifacts for the current project |
+| `/agents` | View available custom/system agents |
+| `/settings` | View and modify settings |
+| `/hotkeys` | View keyboard shortcuts |
+
+### Example First Interaction
+
+```
+You: Review the project structure and summarize the architecture
+
+Agent: I'll analyze the project structure for you.
+
+[Tool: ls] Listing directory...
+[Tool: read] Reading key files...
+
+Based on my analysis, here's the project architecture:
+...
+```
+
+### One-Shot Usage
+
+Run a single prompt without entering interactive mode:
+
+```bash
+# Quick code review
+iosm -p "Review src/ and list the top 5 refactoring opportunities"
+
+# Read-only audit
+iosm --tools read,grep,find,ls -p "Audit src/ for dead code"
+
+# With a specific model
+iosm --model openai/gpt-4o -p "Explain the auth module"
+
+# With file attachments
+iosm @README.md @src/main.ts -p "How does the CLI entry point work?"
+```
+
+## Initialize IOSM Workspace
+
+If you want to use the IOSM methodology for systematic improvement:
+
+```bash
+# Bootstrap in current project
+iosm init
+
+# Bootstrap in a specific path
+iosm init ../service-a
+
+# Force re-initialization
+iosm init --force
+
+# Skip post-init agent verification
+iosm init --no-agent-verify
+```
+
+This creates:
+
+- `iosm.yaml` — methodology configuration (thresholds, weights, policies)
+- `IOSM.md` — operator/agent playbook
+- `.iosm/` — workspace with cycle artifacts, metrics history, decision log
+
+## Typical Daily Workflow
+
+```bash
+# 1. Open your project and start the agent
+cd my-project
+iosm
+
+# 2. Initialize IOSM (first time only)
+/init
+
+# 3. Plan improvement cycles
+/cycle-plan reduce checkout latency
+
+# 4. Work on tasks via natural language
+# "Implement the cache optimization from hypothesis hyp-latency-001"
+
+# 5. Check cycle progress
+/cycle-status
+
+# 6. Export or share your session
+/export
+/share
+```
+
+## Choosing a Model
+
+Select a model at startup or switch during a session:
+
+```bash
+# At startup
+iosm --model sonnet                    # Claude Sonnet
+iosm --model openai/gpt-4o            # GPT-4o
+iosm --model gemini-2.5-pro           # Gemini Pro
+iosm --model sonnet:high              # With high thinking level
+
+# Model rotation (cycles through models)
+iosm --models "sonnet,gpt-4o,gemini-2.5-pro"
+
+# During interactive session
+/model                                 # Opens model selector
+Ctrl+P                                 # Next model in rotation
+Shift+Ctrl+P                           # Previous model
+```
+
+## Troubleshooting
+
+### "No model available"
+
+Ensure you have at least one valid API key:
+
+```bash
+echo $ANTHROPIC_API_KEY   # Should show your key
+echo $OPENAI_API_KEY
+```
+
+### "Permission denied" when running tools
+
+The agent respects tool permissions. Use `/permissions` or `/yolo on` to adjust:
+
+```bash
+/permissions                           # View current permissions
+/yolo on                               # Enable auto-approve for tool calls
+/yolo off                              # Disable auto-approve
+```
+
+### Network issues
+
+Run in offline mode to skip startup network operations:
+
+```bash
+iosm --offline
+# or
+IOSM_OFFLINE=1 iosm
+```
+
+### Session recovery
+
+If a session was interrupted:
+
+```bash
+iosm --continue                        # Continue the last session
+iosm --resume                          # Pick from recent sessions
+```
+
+## Next Steps
+
+- [CLI Reference](./cli-reference.md) — Complete flag documentation
+- [Interactive Mode](./interactive-mode.md) — All slash commands and keybindings
+- [IOSM Init & Cycles](./iosm-init-and-cycles.md) — IOSM methodology guide
+- [Extensions](./extensions-packages-themes.md) — Build custom tools and integrations
+- [Configuration](./configuration.md) — Settings, env vars, profiles