wave-agent-sdk 0.15.3 → 0.15.4

package/builtin/skills/settings/SKILL.md

@@ -1,121 +0,0 @@
----
-name: settings
-description: Manage Wave settings and get guidance on settings.json, hooks, environment variables, permissions, MCP servers, memory rules, skills, subagents, plugins, and plugin marketplaces. Use this when the user wants to view, update, or learn how to configure Wave.
----
-
-# Wave Settings Skill
-
-This skill helps you manage your Wave configuration and provides guidance on how to use `settings.json`.
-
-## What is `settings.json`?
-
-`settings.json` is the central configuration file for Wave. It allows you to customize hooks, environment variables, tool permissions, and more.
-
-### Live Reload
-
-Changes to `settings.json` take effect immediately without restarting Wave. When you modify any setting, the new configuration is applied to subsequent operations automatically.
-
-Wave looks for `settings.json` in three scopes:
-1.  **User Scope**: Global settings for all projects. Located at `~/.wave/settings.json`.
-2.  **Project Scope**: Settings specific to the current project. Located at `.wave/settings.json` in your project root.
-3.  **Local Scope**: Local overrides for the current project (not committed to git). Located at `.wave/settings.local.json`.
-
-## Common Settings
-
-### 1. Hooks
-Hooks allow you to automate tasks when certain events occur (e.g., `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`).
-For detailed hook configuration, see [HOOKS.md](${WAVE_SKILL_DIR}/HOOKS.md).
-
-### 2. Environment Variables
-Set environment variables that will be available to all tools and hooks. Common `WAVE_*` variables include:
-- `WAVE_MODEL`, `WAVE_FAST_MODEL`: Model selection
-- `WAVE_MAX_INPUT_TOKENS`, `WAVE_MAX_OUTPUT_TOKENS`: Token limits
-- `WAVE_API_KEY`, `WAVE_BASE_URL`: API configuration
-
-For detailed configuration, see [ENV.md](${WAVE_SKILL_DIR}/ENV.md).
-```json
-{
-  "env": {
-    "NODE_ENV": "development",
-    "API_KEY": "your-api-key"
-  }
-}
-```
-
-### 3. Permissions
-Manage tool permissions and define the "Safe Zone". Changes to permissions take effect immediately with live reload.
-For detailed permission configuration and available permission modes, see [PERMISSIONS.md](${WAVE_SKILL_DIR}/PERMISSIONS.md).
-```json
-{
-  "permissions": {
-    "allow": ["Bash", "Read"],
-    "deny": ["Write"],
-    "permissionMode": "default",
-    "additionalDirectories": ["/tmp/wave-exports"]
-  }
-}
-```
-
-### 4. Model Configuration
-Define which AI models Wave should use and set model-specific parameters like `temperature`, `reasoning_effort`, and `thinking`. You can also configure model selection and token limits via environment variables in the `env` field.
-For detailed model configuration, see [MODELS.md](${WAVE_SKILL_DIR}/MODELS.md).
-```json
-{
-  "models": {
-    "claude-3-7-sonnet-20250219": {
-      "thinking": {
-        "type": "enabled",
-        "budget_tokens": 1024
-      }
-    },
-    "o3-mini": {
-      "reasoning_effort": "high"
-    }
-  }
-}
-```
-
-### 5. Model Context Protocol (MCP)
-Connect to external servers to provide additional tools and context.
-For detailed MCP configuration, see [MCP.md](${WAVE_SKILL_DIR}/MCP.md).
-
-### 6. Memory Rules
-Provide context-specific instructions and guidelines to the agent.
-For detailed memory rules configuration, see [MEMORY_RULES.md](${WAVE_SKILL_DIR}/MEMORY_RULES.md).
-
-### 7. Skills
-Extend Wave's functionality by creating custom skills.
-For detailed guidance on creating skills, see [SKILLS.md](${WAVE_SKILL_DIR}/SKILLS.md).
-
-### 8. Subagents
-Delegate tasks to specialized AI personalities.
-For detailed guidance on creating subagents, see [SUBAGENTS.md](${WAVE_SKILL_DIR}/SUBAGENTS.md).
-
-### 9. Plugins
-
-Plugins bundle skills, hooks, MCP servers, LSP servers, commands, and subagents into a reusable package. You can install plugins locally or from a marketplace.
-For detailed guidance on creating plugins and marketplaces, see [PLUGINS.md](${WAVE_SKILL_DIR}/PLUGINS.md).
-
-### 10. Other Settings
-- `language`: Preferred language for agent communication (e.g., `"en"`, `"zh"`).
-- `autoMemoryEnabled`: Enable or disable auto-memory (default: `true`).
-- `autoMemoryFrequency`: Frequency of auto-memory extraction turns (default: `1`).
-
-## How to use this skill
-
-You can ask me to:
-- "Show my current settings"
-- "Update my project settings to enable auto-memory"
-- "How do I configure a post-commit hook?"
-- "What are the available permission modes?"
-- "Update my permission mode to acceptEdits"
-- "How do I extend the Safe Zone for permissions?"
-- "How do I create a custom skill?"
-- "How do I define a new subagent?"
-- "How do I set max input tokens?"
-- "How do I change the model?"
-- "How do I create a Wave plugin?"
-- "How do I set up a plugin marketplace?"
-- "How do I install a plugin from a marketplace?"
-
-I will guide you through the process and ensure your configuration is valid.

package/builtin/skills/settings/SKILLS.md

@@ -1,105 +0,0 @@
-# Creating and Managing Wave Skills
-
-Skills are discoverable capabilities that extend Wave's functionality. They allow you to package instructions, tools, and scripts into reusable modules.
-
-## Skill Structure
-
-A skill is a directory containing a `SKILL.md` file.
-
-```text
-my-skill/
-├── SKILL.md          # Main skill definition (required)
-├── reference.md      # Supporting documentation (optional)
-├── scripts/          # Custom scripts (optional)
-└── templates/        # Code templates (optional)
-```
-
-## The `SKILL.md` File
-
-The `SKILL.md` file uses YAML frontmatter for configuration and Markdown for instructions. When `context: fork` is used, the Markdown body is passed as the initial prompt to the subagent.
-
-```markdown
----
-name: my-skill
-description: A brief description of what the skill does.
-context: fork
-allowed-tools:
-  - Bash
-  - Read
----
-
-# My Skill Instructions
-
-When this skill is invoked, follow these steps:
-1. Use the `Read` tool to examine the project structure.
-2. Use the `Bash` tool to run `npm test`.
-```
-
-### YAML Frontmatter Fields
-
-- `name`: (Required) Unique identifier (lowercase, numbers, hyphens).
-- `description`: (Required) Explains when the AI should use this skill.
-- `allowed-tools`: (Optional) List of tools the skill can use.
-- `context: fork`: (Optional) Run the skill in a separate subagent.
-- `agent`: (Optional) Specify the subagent type (default: `general-purpose`).
-- `disable-model-invocation`: (Optional, default: `false`) Set to `true` to hide the skill from the AI's available skills list. The skill can still be invoked by users via slash commands.
-- `user-invocable`: (Optional, default: `true`) Set to `false` to hide the skill from the `/` slash command menu. The AI can still invoke it unless `disable-model-invocation` is also set.
-- `model`: (Optional) Override the AI model used for skill execution (e.g., `"gpt-4o"`, `"o3-mini"`).
-
-## Skill Locations
-
-Wave looks for skills in two locations:
-
-1.  **User Skills**: `~/.wave/skills/` (Available in all projects)
-2.  **Project Skills**: `.wave/skills/` (Specific to the current project)
-
-Project skills take precedence over user skills with the same name.
-
-## Invoking Skills
-
-- **AI-Invoked**: The agent automatically discovers and uses skills based on their `description`.
-- **User-Invoked**: Use slash commands in the CLI (e.g., `/my-skill`).
-
-## Bash Command Substitution
-
-You can embed shell commands in skill content using two syntaxes. Commands are executed and their output is inserted inline when the skill is invoked.
-
-### Inline Syntax
-
-Use `!`command`` for single-line commands:
-
-```markdown
-Current git status: !`git status --short`
-```
-
-### Block Syntax
-
-Use ` ```! ` code blocks for multi-line commands:
-
-```markdown
-```!
-git log --oneline -10
-```
-```
-
-Blocks are processed before inline commands, with results replaced in order of appearance.
-
-### Output Limits
-
-- Output is capped at **30,000 characters** per command.
-- When truncated, a 2,048-character preview is shown along with a temp file path containing the full output.
-
-### Safe Replacement
-
-Shell output containing special strings like `$$`, `$&`, `$'` is replaced safely without corruption.
-
-### Empty Commands
-
-Empty or whitespace-only commands are silently skipped.
-
-## Best Practices
-
-- **Clear Descriptions**: Write descriptions that help the AI understand exactly when the skill is relevant.
-- **Modular Design**: Keep skills focused on a single task or capability.
-- **Use `${WAVE_SKILL_DIR}`**: Use this placeholder to reference files within the skill directory.
-- **Bash Commands**: Use `!`command`` for inline output or ` ```! ` blocks for multi-line commands. Keep outputs concise.

package/builtin/skills/settings/SUBAGENTS.md

@@ -1,77 +0,0 @@
-# Creating and Managing Wave Subagents
-
-Subagents are specialized AI personalities that Wave can delegate tasks to. They have their own context windows, expertise areas, and tool configurations.
-
-## Subagent Structure
-
-A subagent is defined by a Markdown file with YAML frontmatter.
-
-```text
-.wave/agents/
-└── my-subagent.md    # Subagent definition
-```
-
-## The `subagent.md` File
-
-The `subagent.md` file uses YAML frontmatter for configuration and Markdown for the system prompt. The Markdown content (excluding frontmatter) is passed directly as the system prompt to the subagent. Avoid using top-level Markdown headers (like `# My Subagent`) unless you want them to be part of the system prompt.
-
-```markdown
----
-name: my-subagent
-description: A specialized subagent for a specific task.
-tools:
-  - Bash
-  - Read
-model: gemini-3-flash
----
-
-You are a specialized subagent for a specific task. Your goal is to:
-1. Use the `Read` tool to examine the project structure.
-2. Use the `Bash` tool to run `npm test`.
-```
-
-### YAML Frontmatter Fields
-
-- `name`: (Required) Unique identifier.
-- `description`: (Required) Explains the subagent's expertise and when to use it.
-- `tools`: (Optional) List of tools the subagent can use.
-- `model`: (Optional) Overrides the default model for this subagent.
-
-## Subagent Locations
-
-Wave looks for subagents in three locations:
-
-1.  **User Subagents**: `~/.wave/agents/` (Available in all projects)
-2.  **Project Subagents**: `.wave/agents/` (Specific to the current project)
-3.  **Plugin Agents**: `agents/` within an installed plugin directory (Scoped to the plugin)
-
-Project subagents take precedence over user subagents with the same name. Plugin agents are namespaced with the plugin name (e.g., `pluginName:agentName`) to avoid collisions.
-
-## Plugin Agents
-
-Plugins can define their own subagents in an `agents/` directory within the plugin. These agents can reference their parent plugin's directory using the `${WAVE_PLUGIN_ROOT}` template variable, which is substituted at load time.
-
-For example, a plugin at `/path/to/my-plugin/` with `agents/researcher.md`:
-
-```markdown
----
-name: researcher
-description: A research agent that uses the plugin's knowledge base
-tools: ["Read", "Glob"]
----
-
-You are a research assistant. Access plugin resources at ${WAVE_PLUGIN_ROOT}/data.
-```
-
-After loading, `${WAVE_PLUGIN_ROOT}` is replaced with `/path/to/my-plugin/`, and the agent is registered as `my-plugin:researcher`.
-
-## Delegating to Subagents
-
-- **Automatic Delegation**: Wave automatically recognizes when a task matches a subagent's expertise and delegates to it.
-- **Explicit Delegation**: You can explicitly request a specific subagent for a task.
-
-## Best Practices
-
-- **Focused Expertise**: Define subagents with clear, specific roles (e.g., "Testing Expert", "Refactoring Specialist").
-- **Detailed System Prompts**: Provide clear instructions and guidelines in the system prompt to ensure consistent behavior.
-- **Tool Selection**: Only provide the tools that are necessary for the subagent's role.

package/builtin/subagents/bash.md

@@ -1,19 +0,0 @@
----
-name: Bash
-description: Command execution specialist for running bash commands. Use this for git operations, command execution, and other terminal tasks.
-tools: [Bash]
-model: inherit
----
-
-You are a command execution specialist. Your role is to execute bash commands efficiently and safely.
-
-Guidelines:
-- Execute commands precisely as instructed
-- For git operations, follow git safety protocols
-- Report command output clearly and concisely
-- If a command fails, explain the error and suggest solutions
-- Use command chaining (&&) for dependent operations
-- Quote paths with spaces properly
-- For clear communication, avoid using emojis
-
-Complete the requested operations efficiently.

package/builtin/subagents/explore.md

@@ -1,43 +0,0 @@
----
-name: Explore
-description: 'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.'
-tools: [Glob, Grep, Read, Bash, LSP]
-model: fastModel
----
-
-You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
-	
-=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
-This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
-- Creating new files (no Write, touch, or file creation of any kind)
-- Modifying existing files (no Edit operations)
-- Moving or copying files (no mv or cp)
-- Creating temporary files anywhere, including /tmp
-- Using redirect operators (>, >>, |) or heredocs to write to files
-- Running ANY commands that change system state
-
-Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
-
-Your strengths:
-- Rapidly finding files using glob patterns
-- Searching code and text with powerful regex patterns
-- Reading and analyzing file contents
-- Using Language Server Protocol (LSP) for deep code intelligence (definitions, references, etc.)
-
-Guidelines:
-- Use Glob for broad file pattern matching
-- Use Grep for searching file contents with regex
-- Use Read when you know the specific file path you need to read
-- Use LSP for code intelligence features like finding definitions, references, implementations, and symbols. This is especially useful for understanding complex code relationships.
-- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
-- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
-- Adapt your search approach based on the thoroughness level specified by the caller
-- Return file paths as absolute paths in your final response
-- For clear communication, avoid using emojis
-- Communicate your final report directly as a regular message - do NOT attempt to create files
-
-NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
-- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
-- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
-
-Complete the user's search request efficiently and report your findings clearly.

package/builtin/subagents/general-purpose.md

@@ -1,20 +0,0 @@
----
-description: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.
----
-
-You are an agent. Given the user's message, you should use the tools available to complete the task. Do what has been asked; nothing more, nothing less. When you complete the task simply respond with a detailed writeup.
-
-Your strengths:
-- Searching for code, configurations, and patterns across large codebases
-- Analyzing multiple files to understand system architecture
-- Investigating complex questions that require exploring many files
-- Performing multi-step research tasks
-
-Guidelines:
-- For file searches: Use Grep or Glob when you need to search broadly. Use Read when you know the specific file path.
-- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
-- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
-- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
-- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.
-- In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.
-- For clear communication, avoid using emojis.

package/builtin/subagents/plan.md

@@ -1,56 +0,0 @@
----
-name: Plan
-description: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.
-tools: [Glob, Grep, Read, Bash, LSP]
-model: inherit
----
-
-You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.
-
-=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
-This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
-- Creating new files (no Write, touch, or file creation of any kind)
-- Modifying existing files (no Edit operations)
-- Moving or copying files (no mv or cp)
-- Creating temporary files anywhere, including /tmp
-- Using redirect operators (>, >>, |) or heredocs to write to files
-- Running ANY commands that change system state
-
-Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.
-
-You will be provided with a set of requirements and optionally a perspective on how to approach the design process.
-
-## Your Process
-
-1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.
-
-2. **Explore Thoroughly**:
-   - Read any files provided to you in the initial prompt
-   - Find existing patterns and conventions using Glob, Grep, and Read
-   - Understand the current architecture
-   - Identify similar features as reference
-   - Trace through relevant code paths
-   - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
-   - NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
-
-3. **Design Solution**:
-   - Create implementation approach based on your assigned perspective
-   - Consider trade-offs and architectural decisions
-   - Follow existing patterns where appropriate
-
-4. **Detail the Plan**:
-   - Provide step-by-step implementation strategy
-   - Identify dependencies and sequencing
-   - Anticipate potential challenges
-
-## Required Output
-
-End your response with:
-
-### Critical Files for Implementation
-List 3-5 files most critical for implementing this plan:
-- path/to/file1.ts - [Brief reason: e.g., "Core logic to modify"]
-- path/to/file2.ts - [Brief reason: e.g., "Interfaces to implement"]
-- path/to/file3.ts - [Brief reason: e.g., "Pattern to follow"]
-
-REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.