@meowlynxsea/koi 0.1.0

package/src/skills/bundled/remember.ts

@@ -0,0 +1,97 @@
+/**
+ * Remember Skill
+ * 
+ * Review and organize session memory and project context.
+ * Adapted from Claude Code's remember skill.
+ */
+
+import { registerBundledSkill } from "../bundled.js";
+
+const REMEMBER_PROMPT = `# Memory Review
+
+## Goal
+
+Review the session memory and project context. Produce a clear report of proposed changes, grouped by action type. Do NOT apply changes — present proposals for user approval.
+
+## Steps
+
+### 1. Gather All Memory Layers
+
+Check for these memory files in the project root:
+
+| File | Purpose | Should Commit |
+|------|---------|---------------|
+| CLAUDE.md | Project conventions for all contributors | Yes |
+| CLAUDE.local.md | Personal preferences, not for others | .gitignore |
+| .claude/commands/ | Custom slash commands | Yes |
+
+**Success criteria**: You have found and read all relevant memory files.
+
+### 2. Classify Each Entry
+
+For each piece of context or memory, determine the best destination:
+
+| Destination | What belongs there | Examples |
+|-------------|-------------------|----------|
+| **CLAUDE.md** | Project-wide conventions | "use bun not npm", "API routes use kebab-case", "test command is bun test" |
+| **CLAUDE.local.md** | Personal preferences for this user only | "I prefer concise responses", "always explain trade-offs" |
+| **.claude/commands/** | Custom slash commands | Custom /deploy, /test commands |
+| **Stay in memory** | Session-specific or temporary | One-time observations, uncertain patterns |
+
+**Important distinctions:**
+- CLAUDE.md and CLAUDE.local.md contain instructions for the agent, not user preferences for external tools
+- Workflow practices (PR conventions, merge strategies) are ambiguous — ask the user if they're personal or team-wide
+- When unsure, ask rather than guess
+
+**Success criteria**: Each entry has a proposed destination or is flagged as ambiguous.
+
+### 3. Identify Cleanup Opportunities
+
+Scan across all layers for:
+
+- **Duplicates**: Memory entries already captured in CLAUDE.md or CLAUDE.local.md
+- **Outdated**: Older entries contradicted by newer information
+- **Conflicts**: Contradictions between any two layers
+- **Stale**: Information that was true before but is no longer relevant
+
+**Success criteria**: All cross-layer issues identified.
+
+### 4. Present the Report
+
+Output a structured report grouped by action type:
+
+**1. Promotions** — entries to move, with destination and rationale
+**2. Cleanup** — duplicates, outdated entries, conflicts to resolve
+**3. Ambiguous** — entries where you need the user's input on destination
+**4. No action needed** — brief note on entries that should stay put
+
+If no memory files exist, say so and offer to help create CLAUDE.md.
+
+**Success criteria**: User can review and approve/reject each proposal individually.
+
+## Rules
+
+- Present ALL proposals before making any changes
+- Do NOT modify files without explicit user approval
+- Do NOT create new files unless the target doesn't exist yet
+- Ask about ambiguous entries — don't guess
+- Focus on actionable, useful memory rather than comprehensive documentation
+`;
+
+export function registerRememberSkill(): void {
+  registerBundledSkill({
+    name: "remember",
+    description:
+      "Review session memory and project context. Propose promotions to CLAUDE.md, CLAUDE.local.md, or custom commands. Also detects outdated, conflicting, and duplicate entries.",
+    whenToUse:
+      "Use when the user wants to review, organize, or persist their session memory. Also useful for cleaning up outdated or conflicting context.",
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      let prompt = REMEMBER_PROMPT;
+      if (args) {
+        prompt += `\n\n## Additional Context\n\n${args}`;
+      }
+      return [{ type: "text", text: prompt }];
+    },
+  });
+}

package/src/skills/bundled/simplify.ts

@@ -0,0 +1,100 @@
+/**
+ * Simplify Skill
+ * 
+ * Review changed code for reuse, quality, and efficiency.
+ * Adapted from Claude Code's simplify skill.
+ */
+
+import { registerBundledSkill } from "../bundled.js";
+
+const SIMPLIFY_PROMPT = `# Simplify: Code Review and Cleanup
+
+Review changed files for reuse, quality, and efficiency. Fix any issues found.
+
+## Phase 1: Identify Changes
+
+Use \`git diff\` (or \`git diff HEAD\` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that were edited earlier in this conversation.
+
+## Phase 2: Code Review
+
+For each change, review for the following issues:
+
+### Code Reuse
+- **Search for existing utilities** that could replace newly written code
+- Look in common locations: utility directories, shared modules, adjacent files
+- **Flag duplicate functionality** - suggest using existing functions instead
+- **Flag inline logic** that could use existing utilities:
+  - String manipulation
+  - Path handling
+  - Environment checks
+  - Type guards
+  - Custom helpers
+
+### Code Quality
+- **Redundant state**: duplicate state, cached values that could be derived
+- **Parameter sprawl**: adding parameters instead of generalizing
+- **Copy-paste with variation**: near-duplicate blocks that should be unified
+- **Leaky abstractions**: exposing internal details that should be encapsulated
+- **Stringly-typed code**: raw strings where constants, enums, or branded types exist
+- **Unnecessary nesting**: wrapper elements/components that add no value
+- **Unnecessary comments**: comments explaining WHAT (well-named code does that) - delete; keep only non-obvious WHY comments
+
+### Efficiency
+- **Unnecessary work**: redundant computations, repeated reads, duplicate calls, N+1 patterns
+- **Missed concurrency**: sequential operations that could run in parallel
+- **Hot-path bloat**: blocking work added to startup or per-request paths
+- **Recurring no-op updates**: state updates in loops/intervals that fire unconditionally
+- **Unnecessary existence checks**: pre-checking before operating (TOCTOU anti-pattern)
+- **Memory issues**: unbounded data structures, missing cleanup, event listener leaks
+- **Overly broad operations**: reading entire files when only part is needed
+
+## Phase 3: Fix Issues
+
+Fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on.
+
+When done, briefly summarize what was fixed (or confirm the code was already clean).
+
+## Guidelines
+
+- Focus on substantive improvements, not style preferences
+- Preserve the original behavior - this is refactoring, not rewriting
+- Make one logical change at a time
+- Run tests after changes if available
+- Keep commits focused
+
+## Output Format
+
+Present findings in this format:
+
+\`\`\`
+## Issues Found
+
+### [Category] - File:path
+**Problem**: Description of the issue
+**Fix**: What was changed
+\`\`\`
+
+Or if no issues:
+
+\`\`\`
+## Summary
+
+No significant issues found. The code is clean.
+\`\`\`
+`;
+
+export function registerSimplifySkill(): void {
+  registerBundledSkill({
+    name: "simplify",
+    description:
+      "Review changed code for reuse, quality, and efficiency, then fix any issues found.",
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      let prompt = SIMPLIFY_PROMPT;
+      if (args) {
+        prompt += `\n\n## Additional Focus\n\n${args}`;
+      }
+      return [{ type: "text", text: prompt }];
+    },
+  });
+}

package/src/skills/bundled/skillify.ts

@@ -0,0 +1,123 @@
+/**
+ * Skillify Skill
+ * 
+ * Capture this session's repeatable process into a reusable skill.
+ * Adapted from Claude Code's skillify skill.
+ */
+
+import { registerBundledSkill } from "../bundled.js";
+
+const SKILLIFY_PROMPT = `# Skillify
+
+Capture this session's repeatable process as a reusable skill.
+
+## Your Task
+
+### Step 1: Analyze the Session
+
+Before asking questions, analyze what happened in this session:
+- What repeatable process was performed?
+- What were the inputs/parameters?
+- What were the distinct steps (in order)?
+- What tools and permissions were needed?
+- What proved the process succeeded?
+
+### Step 2: Interview the User
+
+Use AskUserQuestion to understand what they want to automate.
+
+**Round 1: High-level confirmation**
+- Suggest a name and description based on your analysis
+- Confirm the goal and success criteria
+
+**Round 2: Details**
+- Present the high-level steps you identified
+- Suggest arguments if the skill needs parameters
+- Ask where to save: repo-specific (\`.claude/skills/\`) or personal (\`~/.config/koi/skills/\`)
+
+**Round 3: Step details**
+For each major step, clarify:
+- What does this step produce that later steps need?
+- What proves this step succeeded?
+- Should the user confirm before proceeding?
+- Are any steps independent and could run in parallel?
+
+**Round 4: Final questions**
+- Confirm when this skill should be invoked
+- Ask for trigger phrases (e.g., "cherry-pick to release", "hotfix")
+
+### Step 3: Write the SKILL.md
+
+Create the skill file at the chosen location.
+
+Use this format:
+
+\`\`\`markdown
+---
+name: skill-name
+description: One-line description of what this skill does
+allowed-tools:
+  - ToolName
+  - Bash(specific:command)
+when_to_use: When to auto-invoke this skill
+argument-hint: "<arg1> <arg2>"
+---
+
+# Skill Title
+
+Description of skill
+
+## Goal
+Clearly stated goal
+
+## Steps
+
+### 1. Step Name
+What to do
+
+**Success criteria**: How to know this step is done
+
+### 2. Step Name
+...
+
+## Notes
+- Gotchas to watch out for
+- User corrections from this session
+\`\`\`
+
+### Step 4: Confirm and Save
+
+Before writing, output the complete SKILL.md for review. Ask for confirmation using AskUserQuestion.
+
+After writing, tell the user:
+- Where the skill was saved
+- How to invoke it: \`/skill-name [arguments]\`
+- That they can edit the SKILL.md directly to refine it
+`;
+
+export function registerSkillifySkill(): void {
+  registerBundledSkill({
+    name: "skillify",
+    description:
+      "Capture this session's repeatable process into a reusable skill.",
+    allowedTools: [
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep",
+      "AskUserQuestion",
+      "Bash(mkdir:*)",
+    ],
+    userInvocable: true,
+    disableModelInvocation: true,
+    argumentHint: "[description of the process to capture]",
+    async getPromptForCommand(args) {
+      let prompt = SKILLIFY_PROMPT;
+      if (args) {
+        prompt += `\n\n## User Description\n\nThe user wants to capture: "${args}"`;
+      }
+      return [{ type: "text", text: prompt }];
+    },
+  });
+}

package/src/skills/bundled/stuck.ts

@@ -0,0 +1,101 @@
+/**
+ * Stuck Skill
+ * 
+ * Diagnose frozen or slow Koi sessions.
+ */
+
+import { registerBundledSkill } from "../bundled.js";
+
+const STUCK_PROMPT = `# /stuck — Diagnose Frozen/Slow Sessions
+
+The user thinks a Koi session is frozen, stuck, or very slow. Investigate and diagnose.
+
+## What to Look For
+
+Signs of a stuck session:
+- **High CPU (≥90%) sustained** — likely an infinite loop or heavy processing
+- **High Memory (≥4GB)** — possible memory leak
+- **Network timeout** — API requests taking too long
+- **Process not responding** — UI frozen but process running
+
+## Investigation Steps
+
+### 1. Check Running Processes
+\`\`\`
+ps aux | grep -E "(koi|node)" | grep -v grep
+\`\`\`
+
+### 2. Check System Resources
+\`\`\`
+top -l 1 | head -20
+\`\`\`
+
+### 3. Check Network Activity
+\`\`\`
+# Is the API responding?
+curl -s --max-time 5 https://api.openai.com/v1/models 2>&1 || echo "API timeout or error"
+\`\`\`
+
+### 4. Check Logs
+Look for error messages in:
+- Terminal output
+- Any log files
+
+### 5. Common Causes
+
+**High CPU:**
+- Model is generating a very long response
+- Infinite loop in tool execution
+- Heavy regex or processing
+
+**High Memory:**
+- Context window getting full
+- Large file being processed
+- Memory leak in process
+
+**Not Responding:**
+- API rate limiting
+- Network connectivity issues
+- Model taking too long to respond
+
+## Report
+
+Present findings in this format:
+
+\`\`\`
+## Diagnosis
+
+**Issue**: [What appears to be wrong]
+**Cause**: [Likely reason]
+**Impact**: [Effect on session]
+
+## Recommendations
+
+1. [Action to take]
+2. [Action to take]
+\`\`\`
+
+## Suggested Fixes
+
+Based on the diagnosis:
+- If API timeout: Try again or switch to a faster model
+- If memory issue: Start a new session
+- If infinite loop: Cancel current operation and try different approach
+- If rate limited: Wait and retry, or use different API key
+`;
+
+export function registerStuckSkill(): void {
+  registerBundledSkill({
+    name: "stuck",
+    description:
+      "Diagnose frozen, stuck, or slow Koi sessions. Investigate CPU, memory, network, and API issues.",
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      let prompt = STUCK_PROMPT;
+      if (args) {
+        prompt += `\n\n## User Context\n\n${args}`;
+      }
+      return [{ type: "text", text: prompt }];
+    },
+  });
+}

package/src/skills/bundled/updateConfig.ts

@@ -0,0 +1,228 @@
+/**
+ * Update Config Skill
+ * 
+ * Configure Koi settings via settings.json.
+ * Adapted from Claude Code's update-config skill to fit Koi's architecture.
+ */
+
+import { registerBundledSkill } from "../bundled.js";
+
+const UPDATE_CONFIG_PROMPT = `# Update Config Skill
+
+Modify Koi configuration by editing settings.json files.
+
+## Settings File Locations
+
+| File | Scope | Purpose |
+|------|-------|---------|
+| \`~/.config/koi/settings.json\` | Global | Koi user settings (providers, models) |
+| \`~/.config/koi/pi/settings.json\` | Global | Pi agent runtime settings |
+| \`~/.config/koi/pi/models.json\` | Global | Pi model registry |
+| \`~/.config/koi/pi/auth.json\` | Global | Pi authentication storage |
+
+## Koi Settings Schema
+
+\`\`\`json
+{
+  "version": 1,
+  "sessionTitle": "Session Name",
+  "providers": {
+    "provider-name": {
+      "provider": "provider-name",
+      "authMethod": "apikey" | "oauth",
+      "credential": "sk-..." 
+    }
+  },
+  "currentModel": {
+    "provider": "openai",
+    "modelId": "gpt-4o"
+  },
+  "auxiliaryModel": {
+    "provider": "anthropic", 
+    "modelId": "claude-sonnet-4-7-20250514"
+  }
+}
+\`\`\`
+
+## Available Configuration Options
+
+### Provider Configuration
+\`\`\`json
+{
+  "providers": {
+    "provider-name": {
+      "provider": "provider-name",
+      "authMethod": "apikey" | "oauth",
+      "credential": "your-api-key-or-token"
+    }
+  }
+}
+\`\`\`
+
+Supported providers: openai, anthropic, google, ollama, groq, mistral, etc.
+
+### Model Configuration
+\`\`\`json
+{
+  "currentModel": {
+    "provider": "openai",
+    "modelId": "gpt-4o"
+  },
+  "auxiliaryModel": {
+    "provider": "anthropic",
+    "modelId": "claude-sonnet-4-7-20250514"
+  }
+}
+\`\`\`
+
+The auxiliary model is used for secondary tasks like reflection or critique.
+
+### Session Configuration
+\`\`\`json
+{
+  "sessionTitle": "My Project"
+}
+\`\`\`
+
+## CRITICAL: Read Before Write
+
+**Always read the existing settings file before making changes.** Merge new settings with existing ones - never replace the entire file unless explicitly asked.
+
+## Workflow
+
+1. **Read existing file** - Use Read tool on the target settings file
+2. **Analyze current state** - Understand what's already configured
+3. **Merge carefully** - Preserve existing settings, especially nested objects
+4. **Edit file** - Use Edit tool for modifications
+5. **Confirm** - Tell user what was changed
+
+## Merging Objects (Important!)
+
+When adding new fields to existing objects, **merge with existing**, don't replace:
+
+**WRONG** (replaces existing providers):
+\`\`\`json
+{ "providers": { "openai": { ... } } }
+\`\`\`
+
+**RIGHT** (preserves existing + adds new):
+\`\`\`json
+{
+  "providers": {
+    "existing-provider": { ... },
+    "openai": { ... }
+  }
+}
+\`\`\`
+
+## Common Tasks
+
+### Adding a Provider
+
+User: "add OpenAI provider" or "configure OpenAI"
+
+1. Read \`~/.config/koi/settings.json\`
+2. Add provider to the providers object
+3. Validate by attempting a test request
+
+### Switching the Current Model
+
+User: "switch to gpt-4o" or "use claude as the main model"
+
+1. Read current settings
+2. Update the currentModel field with new provider and modelId
+3. Confirm the switch
+
+### Configuring an Auxiliary Model
+
+User: "set up auxiliary model" or "add a critique model"
+
+1. Read current settings
+2. Add or update auxiliaryModel field
+3. The auxiliary model will be used for secondary tasks
+
+### Changing Session Title
+
+User: "rename this session"
+
+1. Read settings file
+2. Update sessionTitle field
+
+## File Paths Reference
+
+- Koi Settings: \`~/.config/koi/settings.json\`
+- Pi Settings: \`~/.config/koi/pi/settings.json\`
+- Pi Models: \`~/.config/koi/pi/models.json\`
+- Pi Auth: \`~/.config/koi/pi/auth.json\`
+
+## Troubleshooting
+
+If configuration changes don't take effect:
+
+1. **Check JSON syntax** - Invalid JSON silently fails
+2. **Verify provider name** - Must match exactly (case-sensitive)
+3. **Validate API key** - Try a simple API request
+4. **Check file permissions** - Settings file should be readable
+5. **Restart if needed** - Some settings require a new session
+
+## Example Workflows
+
+### Adding a New Provider
+
+User: "add the anthropic provider with my API key"
+
+1. Read \`~/.config/koi/settings.json\`
+2. Merge new provider with existing providers:
+\`\`\`json
+{
+  "providers": {
+    "existing-provider": { ... },
+    "anthropic": {
+      "provider": "anthropic",
+      "authMethod": "apikey",
+      "credential": "sk-ant-..."
+    }
+  }
+}
+\`\`\`
+3. Tell user the provider was added
+
+### Switching Models
+
+User: "use claude-sonnet as my main model"
+
+1. Read settings
+2. Update currentModel:
+\`\`\`json
+{
+  "currentModel": {
+    "provider": "anthropic",
+    "modelId": "claude-sonnet-4-7-20250514"
+  }
+}
+\`\`\`
+
+## Notes
+
+- Provider names are case-sensitive
+- Model IDs must match the exact format returned by the provider
+- Changes to settings.json take effect immediately for new operations
+- Some changes may require starting a new session
+`;
+
+export function registerUpdateConfigSkill(): void {
+  registerBundledSkill({
+    name: "update-config",
+    description:
+      "Configure Koi settings including providers, models, and Pi agent settings. Use for: adding API providers, switching models, configuring auxiliary models, changing session title, or modifying settings.json files.",
+    allowedTools: ["Read"],
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      let prompt = UPDATE_CONFIG_PROMPT;
+      if (args) {
+        prompt += `\n\n## User Request\n\n${args}`;
+      }
+      return [{ type: "text", text: prompt }];
+    },
+  });
+}

package/src/skills/bundled.ts

@@ -0,0 +1,46 @@
+/**
+ * Bundled Skills Registry
+ *
+ * Built-in skills that are always available.
+ * Ported from Claude Code's skills system, adapted for Koi.
+ */
+
+import {
+  registerBundledSkill as registerSkill,
+  getBundledSkillDefinitions,
+} from "./loader.js";
+import type { BundledSkillDefinition } from "./types.js";
+
+// Re-export for bundled skill files
+export function registerBundledSkill(definition: BundledSkillDefinition): void {
+  registerSkill(definition);
+}
+
+export { getBundledSkillDefinitions };
+
+// =============================================================================
+// Bundled Skills
+// =============================================================================
+
+import { registerUpdateConfigSkill } from "./bundled/updateConfig.js";
+import { registerDebugSkill } from "./bundled/debug.js";
+import { registerLoremIpsumSkill } from "./bundled/loremIpsum.js";
+import { registerSkillifySkill } from "./bundled/skillify.js";
+import { registerRememberSkill } from "./bundled/remember.js";
+import { registerSimplifySkill } from "./bundled/simplify.js";
+import { registerBatchSkill } from "./bundled/batch.js";
+import { registerStuckSkill } from "./bundled/stuck.js";
+
+/**
+ * Initialize all bundled skills.
+ */
+export function initBundledSkills(): void {
+  registerUpdateConfigSkill();
+  registerDebugSkill();
+  registerLoremIpsumSkill();
+  registerSkillifySkill();
+  registerRememberSkill();
+  registerSimplifySkill();
+  registerBatchSkill();
+  registerStuckSkill();
+}