musonda 1.0.0

package/plugins/plugin-builder/skills/create-plugin/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: create-plugin
+description: Comprehensive workflow and architectural guide for creating, packaging, and dynamically registering new Agent Plugins, Agent Skills, and MCP tools in Musonda.
+license: MIT
+metadata:
+  author: Musonda Team
+  version: "1.0.0"
+---
+
+# Agent Plugin & Skill Creation Guide
+
+Use this skill whenever the user asks you to:
+- Create, scaffold, or add a new plugin.
+- Create new Agent Skills or teach Musonda new workflows.
+- Integrate Model Context Protocol (MCP) servers or tools.
+- Reload, manage, or inspect plugins in the live runtime.
+
+---
+
+## 1. Plugin Architecture & Structure
+
+Every Musonda plugin is a self-contained directory containing a manifest, optional skills, and optional MCP servers according to the open [agent-plugins.org](https://agent-plugins.org) standard:
+
+```text
+plugins/<plugin-name>/
+├── plugin.json                 # Required: Plugin manifest ($schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json)
+├── mcp.json                    # Optional: MCP server definitions ($schema: https://agent-plugins.org/schemas/1.0.0/mcp.schema.json)
+└── skills/                     # Optional: Agent Skills directory
+    └── <skill-name>/           # Subdirectory matching the skill name exactly
+        ├── SKILL.md            # Required: Markdown with YAML frontmatter
+        ├── scripts/            # Optional: Bundled executable scripts
+        └── references/         # Optional: Reference documents or examples
+```
+
+---
+
+## 2. Plugin Manifest Specifications (`plugin.json`)
+
+The manifest file must follow the [agent-plugins.org](https://agent-plugins.org) specification:
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "Clear explanation of what the plugin does.",
+  "author": {
+    "name": "Your Name",
+    "email": "user@example.com"
+  },
+  "license": "MIT",
+  "keywords": ["tools", "automation"]
+}
+```
+
+### Critical Rules:
+1. **`name`**: Must be 1–64 characters, lowercase alphanumeric with single hyphens or dots (regex: `^[a-z0-9]+([.-][a-z0-9]+)*$`). Cannot contain uppercase, consecutive hyphens (`--`), consecutive dots (`..`), or leading/trailing hyphens.
+2. **`$schema`**: Must be `"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"`.
+3. **Closed Top-Level**: Unknown fields will generate non-fatal warnings. Client-specific fields must be placed under `extensions`.
+
+---
+
+## 3. Designing Agent Skills (`SKILL.md`)
+
+Each skill lives under `skills/<skill-name>/SKILL.md`. The directory name **must match** the `name` property in the frontmatter:
+
+```markdown
+---
+name: my-skill
+description: Concise description used by Musonda for progressive disclosure. Explain WHEN to invoke this skill.
+license: MIT
+metadata:
+  author: Musonda
+  version: "1.0.0"
+---
+
+# My Skill Instructions
+
+Detailed step-by-step instructions for the assistant.
+
+### Guidelines
+1. Step-by-step reasoning or rules.
+2. What tools to call (e.g., connected MCP tools or file tools).
+3. Output format expectations.
+```
+
+### Progressive Disclosure:
+- Musonda automatically registers all discovered skills into the runtime.
+- The assistant can browse available skills with `skill_list` and read full instructions on-demand with `skill_read(name: "my-skill")`.
+- Bundled scripts in `scripts/` can be executed using `skill_run_script`.
+
+---
+
+## 4. Model Context Protocol (MCP) Integration (`mcp.json`)
+
+MCP servers must be configured in `mcp.json` at the plugin root:
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "my-service": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./server.mjs"],
+      "cwd": "${PLUGIN_ROOT}",
+      "env": {
+        "DATA_PATH": "${PLUGIN_DATA}"
+      }
+    }
+  }
+}
+```
+
+### Standard Environment Variables & Placeholder Expansion (agent-plugins.org):
+- `${PLUGIN_ROOT}`: Absolute filesystem path to the plugin root directory.
+- `${PLUGIN_DATA}`: Dedicated writable persistent storage directory (`./data/plugin_data/<plugin-name>`).
+
+Transports supported: `stdio`, `streamable-http`, and `sse`.
+When Musonda connects the MCP server, each MCP tool is automatically registered in Musonda's runtime and prefixed as:
+`mcp_<plugin-name>_<server-name>_<tool-name>`
+
+---
+
+## 5. Finding, Installing, Creating, and Removing Plugins
+
+Musonda provides a complete suite of tools to manage Agent Plugins dynamically:
+
+### Finding Plugins:
+- Call `plugin_find(query: "...")` to search locally and across the ecosystem (GitHub topic `agent-plugin`, official `agentplugins` org, and npm).
+- Inspect specifications and compatible clients at `https://agent-plugins.org/`.
+
+### Installing Plugins:
+- Call `plugin_install(source: "https://github.com/agentplugins/agent-plugins-example.git")` to clone, validate, install dependencies, and immediately activate in the live runtime.
+- You can also install from local folders: `plugin_install(source: "./my-plugin")` or GitHub shorthand `plugin_install(source: "agentplugins/agent-plugins-example")`.
+
+### Authoring New Plugins:
+- Call `plugin_create(name, description, skills, mcp)` to scaffold and activate a brand-new plugin instantly.
+
+### Inspecting Plugins:
+- Call `plugin_list()` to inspect all currently loaded plugins, skills, and tools.
+- Call `plugin_info(pluginName: "...")` for deep inspection of manifests, skills summaries, and server configurations.
+
+### Removing / Uninstalling Plugins:
+- Call `plugin_remove(pluginName: "...", deleteFiles: true, purgeData: false)` to cleanly shut down MCP subprocesses, deregister tools and skills, and remove files from disk.
+
+### Reloading:
+- Call `plugin_reload(pluginName: "...")` or `plugin_reload()` to refresh plugins from disk without restarting Musonda Gateway.
+

package/plugins/plugin-builder/skills/manage-plugins/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: manage-plugins
+description: Comprehensive operational guide for finding, evaluating, installing, using, and removing Agent Plugins conforming to https://agent-plugins.org/
+license: MIT
+metadata:
+  author: Musonda Team
+  version: "1.0.0"
+---
+
+# Agent Plugins Management & Operational Guide
+
+This skill guides Musonda on how to find, evaluate, install, use, and remove portable **Agent Plugins** conforming to version 1.0.0 of the open standard defined at [https://agent-plugins.org/](https://agent-plugins.org/).
+
+---
+
+## 1. Core Principles of Agent Plugins (v1.0.0)
+
+Agent Plugins is an open, vendor-neutral specification (maintained by Amazon, Cursor, Microsoft, OpenAI, and Vercel maintainers) designed to package reusable components into portable plugins:
+
+- **Directory-Based Package Unit**: Plugins live in self-contained directories.
+- **Root Manifest (`plugin.json`)**: Required. Identified by canonical `$schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json"`. Name must be 1–64 lowercase alphanumeric characters, dots, or single hyphens (`^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$`).
+- **Fixed Component Locations**:
+  - `skills/`: Contains Agent Skills (each in a subfolder with `SKILL.md`).
+  - `mcp.json`: Defines Model Context Protocol servers (`stdio`, `streamable-http`, `sse`).
+  - Reverse-domain extension namespaces (e.g. `com.example.client/`) for client-specific enhancements.
+- **Containment Security**: Files supplied by the package must not resolve outside the plugin root.
+- **Narrow Failure Boundaries**: If one skill or MCP server fails, siblings and other plugins continue operating safely.
+
+---
+
+## 2. How to Find Agent Plugins
+
+When the user asks for new capabilities, integrations, or tools (e.g. database access, GitHub operations, weather forecasts, PDF processing, search engines):
+
+1. **Use `plugin_find(query: "...")`**:
+   - Searches local directories (`./plugins`, `./data/plugins`) for installed or available plugins.
+   - Searches official and community ecosystem registries:
+     - Curated official reference plugins from `https://agent-plugins.org/`.
+     - GitHub search across repositories tagged with topic `agent-plugin` or query `agent-plugin`.
+     - npm registry for packages published with keyword `agent-plugin`.
+
+2. **Official & Trusted Sources**:
+   - **`https://github.com/agentplugins`**: Official GitHub organization.
+     - `agentplugins/agent-plugins-example`: Canonical reference implementation.
+     - `agentplugins/agent-plugins-spec`: Normative specifications and JSON schemas.
+     - `agentplugins/agent-plugins-site`: Documentation and compatible clients list.
+   - **`https://agent-plugins.org/compatible-clients`**: Index of compliant tools and frameworks.
+   - **GitHub Discussions**: `https://github.com/agentplugins/agent-plugins-spec/discussions` for proposals and ecosystem plugins.
+
+3. **Web Search**:
+   - Use `web_search(query: "agent plugins github <keyword>")` or `web_search(query: "agent-plugin mcp <keyword>")` when looking for specific community integrations.
+
+---
+
+## 3. How to Inspect & Evaluate Plugins
+
+Before or after installing, always inspect the plugin's metadata and structure:
+
+- Call `plugin_info(pluginName: "...")`:
+  - Shows manifest metadata (name, version, author, license, description).
+  - Lists discovered Agent Skills and their summary instructions.
+  - Lists configured MCP servers (stdio commands, URLs, transports).
+  - Shows active bridged tools and directory paths.
+- Verify security and containment:
+  - Plugins should not attempt to access paths outside their root, except persistent data in `data/plugin_data/<name>`.
+
+---
+
+## 4. How to Add & Install Plugins
+
+Musonda can install plugins dynamically into the live Gateway without restarting:
+
+1. **Install from Git Repository (GitHub, GitLab, etc.)**:
+   ```json
+   {
+     "source": "https://github.com/agentplugins/agent-plugins-example.git"
+   }
+   ```
+   Or use GitHub shorthand:
+   ```json
+   {
+     "source": "agentplugins/agent-plugins-example"
+   }
+   ```
+   Musonda clones the repository into `./plugins/<name>`, validates the manifest, installs dependencies (`npm install --omit=dev`), and mounts skills and MCP servers immediately.
+
+2. **Install from a Local Directory**:
+   ```json
+   {
+     "source": "./path/to/my-plugin"
+   }
+   ```
+   Musonda copies the directory into the active plugins search path and loads it into runtime.
+
+3. **Scaffold a Custom Plugin with `plugin_create`**:
+   If no existing plugin fits the user's needs, author a brand-new one:
+   ```json
+   {
+     "name": "custom-tools",
+     "description": "Custom automated tools for project tasks",
+     "skills": [
+       {
+         "name": "review-workflow",
+         "description": "Steps for reviewing pull requests",
+         "content": "Follow these steps when reviewing pull requests..."
+       }
+     ]
+   }
+   ```
+
+---
+
+## 5. How to Use Discovered Plugins
+
+Once installed, a plugin's capabilities are accessible via two mechanisms:
+
+### A. Using Agent Skills (Progressive Disclosure)
+1. **Browse Skills**: Use `skill_list` to see all available skills across loaded plugins.
+2. **Read Full Instructions**: Use `skill_read(name: "<skill-name>")` to load detailed workflow instructions and step-by-step guidance into context.
+3. **Execute Skill Scripts**: If a skill bundles helper scripts in `scripts/`, execute them with `skill_run_script(skillName: "...", scriptName: "...")`.
+
+### B. Using MCP Tools
+- MCP servers declared in `mcp.json` are automatically started or connected.
+- For `stdio` servers, Musonda provides:
+  - `PLUGIN_ROOT`: Root path of the plugin.
+  - `PLUGIN_DATA`: Persistent writable data directory (`./data/plugin_data/<plugin-name>`).
+- Bridged tools are available directly in your tool registry, prefixed with `mcp_<plugin>_<server>_<tool>`.
+- Simply call the tool with required arguments like any native tool.
+
+---
+
+## 6. How to Remove Plugins
+
+When a plugin is no longer needed or requested to be removed by the user:
+
+1. Call `plugin_remove`:
+   ```json
+   {
+     "pluginName": "unneeded-plugin",
+     "deleteFiles": true,
+     "purgeData": false
+   }
+   ```
+2. **What Happens**:
+   - MCP subprocesses are gracefully closed with `SIGTERM`.
+   - Bridged MCP tools are unregistered from the tool registry.
+   - Discovered Agent Skills are removed from memory.
+   - The plugin folder in `./plugins/<name>` is deleted from disk.
+   - Persistent storage in `data/plugin_data/<name>` is preserved by default (or deleted if `purgeData: true`).
+
+---
+
+## 7. Troubleshooting & Resilience
+
+- **Narrow Failure Boundaries**: If an MCP server fails to start, its error is logged, but sibling servers and skills in the same plugin remain active.
+- **Reloading**: If files are edited manually on disk, run `plugin_reload(pluginName: "...")` to refresh runtime state without restarting the server.
+- **Diagnostics**: Use `plugin_list` and `plugin_info` to inspect loaded status and check for missing dependencies.