@amsterdamdatalabs/enact-extensions 0.1.0

package/spec/enact.md

@@ -0,0 +1,204 @@
+# Plugins
+
+## Overview
+
+Plugins bundle skills, slash commands, MCP servers, and app integrations into reusable
+workflows for Enact agents.
+
+Extend what Enact can do, for example:
+
+- Install the enact-context plugin to give agents deep code intelligence and semantic search.
+- Install the enact-wiki plugin to persist knowledge across sessions and projects.
+- Install the enact-operator plugin to unlock factory workflows, team orchestration, and operator oversight.
+
+A plugin can contain:
+
+- **Skills:** reusable instructions for specific kinds of work. Agents load
+  them on demand so they follow the right steps and use the right references
+  or helper scripts for a task.
+- **Slash commands:** named commands invoked directly by the user (e.g. `/enact-operator:setup`)
+  to trigger specific workflows without relying on automatic skill selection.
+- **MCP servers:** services that give agents access to additional tools or
+  shared information, often from systems outside the local project.
+- **Apps:** connections to external tools like GitHub, Azure DevOps, or Slack, so
+  agents can read information from those tools and take actions in them.
+- **Hooks:** event handlers that run automatically on session lifecycle events
+  (SessionStart, PreToolUse, Stop, etc.) to inject context or enforce guardrails.
+
+More plugin capabilities are coming soon.
+
+## Use and install plugins
+
+### Plugin directory in the CLI
+
+In the Enact CLI, run the following command to open the plugins list:
+
+```text
+enact
+/plugins
+```
+
+The CLI plugin browser groups plugins by marketplace. Use the marketplace tabs
+to switch sources, open a plugin to inspect details, install or uninstall
+marketplace entries, and press <kbd>Space</kbd> on an installed plugin to toggle
+its enabled state.
+
+### Install and use a plugin
+
+Once you open the plugin directory:
+
+1. Search or browse for a plugin, then open its details.
+2. Select `Install plugin`.
+3. If the plugin requires an MCP server, it starts automatically on the next session.
+4. After installation, start a new session and invoke the plugin by skill or slash command.
+
+After you install a plugin, invoke it in two ways:
+
+**Describe the task directly** — ask for the outcome you want, such as
+"Set up the Enact Factory environment" or "Run the doctor check on this project."
+Use this when you want the agent to choose the right installed skill for the task.
+
+**Use a slash command** — type `/plugin-name:command-name` to invoke a specific
+workflow explicitly. Use this when you want precise control over which skill or
+command runs.
+
+### How permissions and data sharing work
+
+Installing a plugin makes its workflows available to Enact agents, but your
+existing approval settings still apply. Connected external services remain
+subject to their own authentication, privacy, and data-sharing policies.
+
+- Bundled skills and slash commands are available as soon as you install the plugin.
+- If a plugin includes MCP servers, they may require additional setup or
+  authentication before first use.
+- If a plugin includes apps, the agent may prompt you to authenticate during
+  setup or the first time you use them.
+- Hook scripts run automatically within the session process and have access to
+  the same environment as the agent.
+
+### Remove or turn off a plugin
+
+To remove a plugin, reopen it from the plugin browser and select
+**Uninstall plugin**.
+
+If you want to keep a plugin installed but turn it off, set its entry in
+`~/.enact/config.toml` to `enabled = false`, then restart the agent:
+
+```toml
+[plugins."enact-operator@enact-curated"]
+enabled = false
+```
+
+## Build your own plugin
+
+Plugins live in a directory containing an `.agents/` folder with a `plugin.json`
+manifest. All other components (skills, commands, hooks, MCP servers, apps) sit
+at the plugin root alongside `.agents/`.
+
+### Plugin structure
+
+```text
+my-plugin/
+├── .agents/
+│   └── plugin.json
+├── skills/
+│   └── my-skill/
+│       └── SKILL.md
+├── commands/
+│   └── my-command.md
+├── hooks/
+│   └── hooks.json
+├── .mcp.json
+├── .app.json
+└── assets/
+    ├── icon.png
+    └── logo.png
+```
+
+### Plugin manifest
+
+The manifest at `.agents/plugin.json` declares the plugin identity and points
+to its components. `name` is the only required field; all component paths
+default to the conventional locations shown above.
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "A plugin that does something useful",
+  "author": {
+    "name": "Your Name"
+  },
+  "skills": "./skills/",
+  "commands": "./commands/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "My Plugin",
+    "shortDescription": "Does something useful for Enact agents.",
+    "category": "Developer Tools",
+    "logo": "./assets/logo.png",
+    "capabilities": [
+      "skill workflows",
+      "slash commands"
+    ]
+  }
+}
+```
+
+| Field         | Required | Purpose                                                                                                   |
+| :------------ | :------- | :-------------------------------------------------------------------------------------------------------- |
+| `name`        | Yes      | Unique identifier and namespace prefix for skills and slash commands.                                     |
+| `version`     | No       | Semantic version. If omitted, the git commit SHA is used.                                                 |
+| `description` | No       | Short description shown in the plugin registry.                                                           |
+| `author`      | No       | Attribution. Requires at minimum `author.name`.                                                           |
+| `skills`      | No       | Path to skills directory (default: `./skills/`).                                                          |
+| `commands`    | No       | Path to slash commands directory (default: `./commands/`).                                                |
+| `hooks`       | No       | Path to hooks configuration file (default: `./hooks/hooks.json`).                                        |
+| `mcpServers`  | No       | Path to `.mcp.json` MCP server configuration (default: `./.mcp.json`).                                   |
+| `apps`        | No       | Path to `.app.json` app connections file (default: `./.app.json`).                                       |
+| `interface`   | No       | Display metadata for the Enact plugin registry. `displayName` and `shortDescription` required if present. |
+
+For the full manifest schema and field reference, see [enact.json](./enact.json).
+
+### Slash commands
+
+Slash commands are named entry points defined in the plugin's `commands/` directory.
+Each Markdown file becomes one command, prefixed with the plugin namespace:
+
+```text
+commands/
+├── setup.md       →  /my-plugin:setup
+├── doctor.md      →  /my-plugin:doctor
+└── reset.md       →  /my-plugin:reset
+```
+
+Users invoke them directly:
+
+```text
+/my-plugin:setup
+/my-plugin:doctor production
+```
+
+Commands differ from skills in one key way: skills are selected automatically
+by the agent based on context; slash commands are always user-initiated. Both
+accept arguments via the `$ARGUMENTS` placeholder in the Markdown file.
+
+### Test your plugin locally
+
+Load a plugin directly without installing it:
+
+```bash
+enact --plugin-dir ./my-plugin
+```
+
+As you make changes, run `/reload-plugins` to pick up updates without
+restarting. Test skills with `/my-plugin:skill-name` and slash commands with
+`/my-plugin:command-name`.
+
+### Distribute your plugin
+
+When your plugin is ready to share, add a `README.md`, choose a versioning
+strategy, and submit it to the Enact plugin registry. Internal team plugins can
+be hosted in a private repository and referenced directly.