{
  "id": "page:docs-plugins-plugin-author-guide",
  "_kind": "Page",
  "_file": "wiki/docs/plugins/plugin-author-guide.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/plugins/plugin-author-guide.md",
    "sourceKind": "repo-docs",
    "title": "Plugin Author Guide",
    "displayName": "Plugin Author Guide",
    "slug": "docs/plugins/plugin-author-guide",
    "articlePath": "wiki/docs/plugins/plugin-author-guide.md",
    "article": "\n# Plugin Author Guide\n\nThis guide explains how to create plugin packages for the babysitter SDK. A babysitter plugin is not a conventional software plugin. Instead, it is a version-managed package of contextual instructions that an AI agent reads and executes to install, uninstall, configure, or migrate between versions of a tool or integration.\n\n## Concepts\n\n- **Plugin package** -- A directory within a marketplace repository containing instruction files and optional babysitter process files.\n- **Marketplace** -- A Git repository with a `marketplace.json` manifest that indexes available plugins.\n- **Registry** -- A local JSON file (`plugin-registry.json`) that tracks which plugins are installed and at what version.\n- **Scope** -- Plugins can be installed at `global` scope (`~/.babysitter/`) or `project` scope (`<projectDir>/.babysitter/`).\n\n## Plugin Package Directory Structure\n\nA plugin package is a directory with the following layout:\n\n```\nmy-plugin/\n  install.md              # Agent-readable installation instructions\n  uninstall.md            # Agent-readable uninstallation instructions\n  configure.md            # Agent-readable configuration instructions\n  install-process.js      # Optional babysitter process for automated install\n  uninstall-process.js    # Optional babysitter process for automated uninstall\n  configure-process.js    # Optional babysitter process for automated configuration\n  migrations/             # Version migration files\n    1.0.0_to_1.1.0.md\n    1.1.0_to_1.2.0.md\n    1.2.0_to_2.0.0.js\n```\n\nAll files are optional. The SDK reads whichever files are present and returns their content to the agent.\n\n## Writing install.md\n\nThe `install.md` file contains markdown instructions that an AI agent reads and follows to install the plugin into a project or user environment. Write the instructions as if speaking to a capable developer agent.\n\nGuidelines:\n\n- Use numbered steps for sequential operations.\n- Be explicit about file paths, configuration keys, and expected values.\n- Reference environment-specific locations using placeholders like `<project-root>` or `<home-dir>`.\n- If the install requires running a babysitter process, note that the process file is `install-process.js` in the same directory.\n- Include any prerequisites (required tools, environment variables, permissions).\n\n### Example install.md\n\n```markdown\n# Install my-plugin\n\n## Prerequisites\n- Node.js 18 or later\n- Access to the project's `.claude/settings.json`\n\n## Steps\n\n1. Add the plugin entry to `.claude/settings.json` under the `permissions.allow` array:\n   ```json\n   {\n     \"permissions\": {\n       \"allow\": [\"my-plugin@my-org\"]\n     }\n   }\n   ```\n\n2. Create the configuration directory:\n   ```\n   mkdir -p .a5c/plugins/my-plugin\n   ```\n\n3. Copy the default configuration:\n   ```\n   cp <plugin-package-dir>/defaults/config.json .a5c/plugins/my-plugin/config.json\n   ```\n\n4. Run the install process for automated setup:\n   - The babysitter process file `install-process.js` in this directory handles\n     remaining setup steps including API key validation.\n```\n\n## Writing uninstall.md\n\nThe `uninstall.md` file contains instructions for removing the plugin. It should reverse the steps performed during installation.\n\n### Example uninstall.md\n\n```markdown\n# Uninstall my-plugin\n\n1. Remove the plugin entry from `.claude/settings.json` under `permissions.allow`.\n2. Delete the plugin configuration directory:\n   ```\n   rm -rf .a5c/plugins/my-plugin\n   ```\n3. Remove any environment variables set during installation.\n```\n\n## Writing configure.md\n\nThe `configure.md` file contains instructions for configuring or reconfiguring the plugin after installation. This is useful for changing settings, updating API keys, or adjusting plugin behavior.\n\n### Example configure.md\n\n```markdown\n# Configure my-plugin\n\n## Available Settings\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `apiKey` | (none) | API key for the external service |\n| `timeout` | `30000` | Request timeout in milliseconds |\n| `logLevel` | `info` | Logging verbosity (debug, info, warn, error) |\n\n## Steps\n\n1. Open `.a5c/plugins/my-plugin/config.json`\n2. Update the desired settings\n3. Validate the configuration by running:\n   ```\n   babysitter health --json\n   ```\n```\n\n## Babysitter Process Files\n\nProcess files (`install-process.js`, `uninstall-process.js`, `configure-process.js`) are standard babysitter process definitions. They export an `async function process(inputs, ctx)` and use `defineTask` to define steps that the orchestrator executes.\n\nThese process files enable automated, multi-step operations that go beyond what static markdown instructions can describe. Common uses:\n\n- Validating external service connectivity\n- Running database migrations\n- Generating configuration files from templates\n- Performing health checks after installation\n\nThe SDK detects process files by checking for their existence at conventional paths within the plugin package directory. When present, the `processFile` field in the command output contains the absolute path to the file.\n\n## Creating Migration Files\n\nMigration files live in the `migrations/` subdirectory of the plugin package. They describe how to move from one version to another.\n\n### Naming Convention\n\n```\n<fromVersion>_to_<toVersion>.<ext>\n```\n\nWhere:\n\n- `<fromVersion>` -- The source version (semver with dots, dashes, and pre-release identifiers allowed)\n- `<toVersion>` -- The target version\n- `<ext>` -- Either `md` (markdown instructions) or `js` (babysitter process file)\n\nExamples:\n\n```\n1.0.0_to_1.1.0.md\n1.1.0_to_1.2.0.md\n1.2.0_to_2.0.0.js\n2.0.0-beta_to_2.0.0.md\n```\n\n### Markdown Migration Files (.md)\n\nContain agent-readable instructions for performing the migration:\n\n```markdown\n# Migration from 1.0.0 to 1.1.0\n\n## Breaking Changes\n- The `timeout` config key has moved from top-level to `settings.timeout`\n\n## Steps\n\n1. Open `.a5c/plugins/my-plugin/config.json`\n2. Move the `timeout` value:\n   - Remove `\"timeout\": <value>` from the top level\n   - Add `\"settings\": { \"timeout\": <value> }` if the `settings` key does not exist\n3. Verify the configuration is valid by running `babysitter health`\n```\n\n### JavaScript Migration Files (.js)\n\nStandard babysitter process files that automate the migration. The SDK returns the absolute path to the file in the `processFile` field so the agent can execute it.\n\n## Example Complete Plugin Package\n\n```\nexample-plugin/\n  install.md\n  uninstall.md\n  configure.md\n  install-process.js\n  migrations/\n    1.0.0_to_1.1.0.md\n    1.1.0_to_2.0.0.md\n    2.0.0_to_2.1.0.js\n```\n\nWith a corresponding marketplace.json entry:\n\n```json\n{\n  \"name\": \"example-plugin\",\n  \"description\": \"An example babysitter plugin\",\n  \"latestVersion\": \"2.1.0\",\n  \"versions\": [\"2.1.0\", \"2.0.0\", \"1.1.0\", \"1.0.0\"],\n  \"packagePath\": \"plugins/example-plugin\",\n  \"tags\": [\"example\", \"tutorial\"],\n  \"author\": \"my-org\"\n}\n```\n\n## Plugin Lifecycle\n\nThe complete lifecycle for a plugin from the agent's perspective:\n\n1. **Discovery** -- `plugin:list-plugins` to browse available plugins in a marketplace.\n2. **Install** -- `plugin:install` returns instructions from `install.md`. Agent executes them. Then `plugin:update-registry` records the version.\n3. **Configure** -- `plugin:configure` returns instructions from `configure.md`. Agent executes them.\n4. **Update** -- `plugin:update` resolves the migration chain and returns ordered migration instructions. Agent executes each migration step. Then `plugin:update-registry` records the new version.\n5. **Uninstall** -- `plugin:uninstall` returns instructions from `uninstall.md`. Agent executes them. Then `plugin:remove-from-registry` cleans up the registry.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}