{
  "id": "page:docs-plugins",
  "_kind": "Page",
  "_file": "wiki/docs/plugins.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/plugins.md",
    "sourceKind": "repo-docs",
    "title": "Babysitter Plugins",
    "displayName": "Babysitter Plugins",
    "slug": "docs/plugins",
    "articlePath": "wiki/docs/plugins.md",
    "article": "\n# Babysitter Plugins\n\n## What Makes This Plugin System Different\n\nMost plugin systems work like this: there's a host application with predefined extension points (hooks, APIs, lifecycle events), and plugins slot into those points. The plugin can only do what the host lets it do.\n\nBabysitter plugins don't work like that.\n\nA babysitter plugin is a **set of natural language instructions** (markdown files) or **deterministic coded processes** (js files) -- that an AI agent reads and executes to install or configure a modular set of capabilities. The SDK doesn't \"run\" the plugin. It stores, versions, and distributes the instructions. The AI agent is the runtime.\n\nThis means a plugin can do *anything an AI agent can do*:\n\n- **Modify your project** -- install npm packages, add ESLint rules, create Terraform configs, set up Playwright, generate Helm charts, write CI/CD pipelines\n- **Modify your environment** -- configure Claude Code hooks, set up git hooks, install sound effects, change how Claude talks to you\n- **Modify your workflow** -- copy babysitter processes, skills, and agents into your project so future babysitter runs use them\n- **Research and adapt** -- web search for theme resources, analyze your codebase to pick the right testing framework, detect your cloud provider from existing configs\n\nThere are no predefined extension points, no plugin API, no sandboxing. The `install.md` (or `install.js`) for a plugin is a prompt or autonomous process. The \"integration\" is whatever the AI agent does after reading it.\n\n### What the SDK Actually Manages\n\nThe SDK handles the parts that need to be deterministic and reliable:\n\n| Concern | How the SDK handles it |\n|---------|----------------------|\n| **Distribution** | Marketplaces are git repos cloned with `--depth 1`. The SDK reads `marketplace.json` to list available plugins. |\n| **Versioning** | The registry tracks installed versions. Migration files (`1.0.0_to_1.1.0.md`) describe upgrade steps -- the SDK finds the shortest upgrade path via BFS. |\n| **Registry** | A JSON file (`plugin-registry.json`) tracks what's installed, where it came from, and when. Atomic writes for crash safety. |\n| **Instruction delivery** | The CLI reads `install.md`, `configure.md`, or `uninstall.md` from the plugin package and hands them to the AI agent. |\n\nEverything else -- the actual installation, configuration, project modification -- is done by the AI agent interpreting the instructions.\n\n### The Two Scopes\n\nPlugins can be stored globally (`~/.a5c/`) or per-project (`<project>/.a5c/`). But even globally-installed plugins often create project-level artifacts. The themes plugin, for example, writes to `.a5c/themes/`, `.claude/settings.json`, and `CLAUDE.md` -- all project-level. The scope mostly determines where the registry and marketplace clones live.\n\n---\n\n<!-- supported-harness-plugins:start -->\n## Supported harness plugin packages\n\n`plugins/babysitter-unified/` is the only maintained source tree in this repo.\nHarness-specific bundles are generated from it and published as npm packages or\nexternal plugin repos; they are not maintained as checked-in directories here.\n\nUse this table when you need the canonical entrypoint for a specific Babysitter harness/plugin package rather than the broader plugin-system explanation.\n\n| Surface | Canonical docs home | Status note |\n| --- | --- | --- |\n| `plugins/babysitter-unified` | [plugins/babysitter-unified/per-harness/claude-code/README.md](../plugins/babysitter-unified/per-harness/claude-code/README.md) | Canonical authoring source plus Claude Code surface. |\n| `@a5c-ai/babysitter-codex` | [plugins/babysitter-unified/per-harness/codex/README.md](../plugins/babysitter-unified/per-harness/codex/README.md) | Generated from the unified source; README is the canonical package-level contract. |\n| `@a5c-ai/babysitter-cursor` | [plugins/babysitter-unified/per-harness/cursor/README.md](../plugins/babysitter-unified/per-harness/cursor/README.md) | Generated from the unified source; README is the canonical package-level contract. |\n| `babysitter-gemini` | [plugins/babysitter-unified/per-harness/gemini/README.md](../plugins/babysitter-unified/per-harness/gemini/README.md) | Generated from the unified source; README is the canonical package-level contract. |\n| `babysitter-github` | [plugins/babysitter-unified/per-harness/github/README.md](../plugins/babysitter-unified/per-harness/github/README.md) | Generated from the unified source; README is the canonical package-level contract. |\n| `@a5c-ai/babysitter-omp` | [plugins/babysitter-unified/per-harness/omp/README.md](../plugins/babysitter-unified/per-harness/omp/README.md) | Generated from the unified source; README is the canonical package-level contract. |\n| `@a5c-ai/babysitter-openclaw` | [plugins/babysitter-unified/per-harness/openclaw/README.md](../plugins/babysitter-unified/per-harness/openclaw/README.md) | Generated from the unified source; README is the canonical package-level contract. |\n| `@a5c-ai/babysitter-opencode` | [plugins/babysitter-unified/per-harness/opencode/README.md](../plugins/babysitter-unified/per-harness/opencode/README.md) | Generated from the unified source; README is the canonical package-level contract. |\n| `@a5c-ai/babysitter-pi` | [plugins/babysitter-unified/per-harness/pi/README.md](../plugins/babysitter-unified/per-harness/pi/README.md) | Generated from the unified source; README is the canonical package-level contract. |\n<!-- supported-harness-plugins:end -->\n\n## Bridge Flags for amux Launch\n\nWhen launching agents through `amux launch`, two bridge flags control how babysitter hooks and interactive orchestration integrate with the harness:\n\n- **`--bridge-interactive`** enables an interactive bridge layer that proxies stdin/stdout through an intermediary capable of injecting babysitter hook responses and orchestration signals while preserving the harness's native TUI.\n- **`--bridge-hooks`** enables hook bridging: the bridge intercepts hook lifecycle events (SessionStart, Stop, PreToolUse, etc.) and forwards them to the babysitter session-start hook. This is how the session-start hook writes a bare run ID into session state, enabling `instructions:babysit-skill` to discover and assign a process to the run.\n\nThe `hookSupport` and `bridgeCapabilities` attributes in the atlas graph agent version nodes describe which harnesses support these flags natively. See the [amux CLI reference](agent-mux/reference/10-cli-reference.md) for the full flag table.\n\n---\n\n## How a Plugin Install Actually Works\n\nHere's what happens when you run `babysitter plugin:install testing-suite`:\n\n1. The CLI finds the `testing-suite` package in the marketplace\n2. It reads `install.md` from the package directory\n3. The AI agent receives the markdown instructions\n4. The agent **analyzes your project** -- reads `package.json`, checks for existing test configs, detects your framework\n5. The agent **interviews you** -- asks which testing layers you want, which frameworks to use, what coverage thresholds to set\n6. The agent **installs frameworks** -- runs `npm install -D vitest @playwright/test`, generates config files\n7. The agent **sets up linting** -- creates or updates `eslint.config.mjs`, adds test-specific rules\n8. The agent **configures git hooks** -- installs husky, creates pre-commit and pre-push hooks\n9. The agent **creates CI/CD pipelines** -- writes `.github/workflows/test.yml` with lint, test, and coverage jobs\n10. The agent **copies babysitter processes** -- puts TDD and quality gate processes in `.a5c/processes/testing/`\n11. The agent **runs an initial check** -- executes the test suite, reports coverage\n12. The agent **registers the plugin** -- calls `babysitter plugin:update-registry`\n\nSteps 4-11 are the agent interpreting markdown. The SDK was only involved in steps 1-3 and 12.\n\nCompare this to a conventional plugin system where \"install\" means \"load a module and call its `activate()` function.\" Here, \"install\" means \"restructure this project's testing infrastructure based on an AI agent's understanding of the codebase and the user's preferences.\"\n\n---\n\n## The Marketplace Plugins\n\nThe official a5c.ai marketplace includes seven plugins. Each one illustrates a different way plugins can reshape a project.\n\n### basic-security\n\nAdds security processes, skills, agents, lint rules, and git hooks to your project.\n\n**What the AI agent does during install:**\n- Interviews you about which security categories to install (DevSecOps, Compliance, Incident Response, Infrastructure Security, etc.)\n- Copies selected process files from the babysitter library to `.a5c/processes/security/`\n- Copies matching skills and agents to `.a5c/skills/security/` and `.a5c/agents/security/`\n- Installs security ESLint plugins (`eslint-plugin-security`, `eslint-plugin-no-secrets`) and configures rules -- different rules for React vs Express vs Python vs Go projects\n- Sets up gitleaks as a pre-commit hook for secrets detection\n- Adds sensitive file patterns to `.gitignore`\n- Creates slash commands (`.a5c/commands/security-commands.md`) for running security scans\n- Runs an initial codebase security audit and presents findings\n\n**What this means for the project:** After installation, every commit is scanned for secrets, every push audits dependencies, and you have `/security-audit`, `/pentest`, `/threat-model`, and other commands available for on-demand security processes.\n\n### testing-suite\n\nSets up comprehensive testing infrastructure tailored to your stack.\n\n**What the AI agent does during install:**\n- Detects your language, framework, and existing test setup\n- Interviews you across 8 stages: testing scope, framework selection, coverage requirements, CI/CD integration, linting, git hooks, test strategy\n- Installs the right frameworks for your stack (Vitest/Jest, Playwright/Cypress, pytest, Storybook 8+, etc.)\n- Generates config files (`vitest.config.ts`, `playwright.config.ts`, `.eslintrc`, `.prettierrc`)\n- Creates git hooks: pre-commit runs lint-staged, pre-push runs the full test suite\n- Writes a complete CI/CD pipeline with lint, typecheck, unit test, E2E, Storybook, and coverage gate jobs\n- Creates example test files as working templates\n- Copies QA processes and TDD methodology from the babysitter library\n\n**What this means for the project:** You get a fully configured test pyramid with enforcement at every level -- staged files are linted on commit, tests run on push, coverage is gated in CI.\n\n### project-deployment\n\nSets up deployment infrastructure, CI/CD, and cloud provisioning.\n\n**What the AI agent does during install:**\n- Analyzes your project for existing deployment configs (Docker, Terraform, Helm, Vercel, etc.)\n- Interviews you about deployment approach (Enterprise Cloud / Managed Platform / Container / Serverless), cloud provider, CI/CD platform, environment strategy\n- Generates infrastructure config: Terraform files, Kubernetes manifests, Helm charts, Dockerfiles, `vercel.json`, `serverless.yml` -- whatever matches your choices\n- Creates CI/CD pipelines with build, push, and deploy stages per environment\n- Copies relevant DevOps processes and skills from the babysitter library\n- Runs validation (Terraform plan, kubectl dry-run) to verify the generated configs\n\n**What this means for the project:** Your project gets production-ready deployment infrastructure -- IaC, container orchestration, multi-environment pipelines -- generated from an interview rather than weeks of manual setup.\n\n### themes\n\nApplies a complete thematic identity to your project -- sounds, design system, conversational personality, and decorative assets.\n\n**What the AI agent does during install:**\n- Asks you to name *any* concept -- \"Blade Runner\", \"Art Deco\", \"cozy autumn\", \"GLaDOS\", literally anything\n- Researches the theme: web searches for visual language, color palettes, typography, sound effects, speech patterns\n- Discovers existing UI frameworks that match (Arwes for sci-fi, NES.css for retro gaming, Augmented UI for cyberpunk)\n- Downloads themed sound effects for Claude Code lifecycle events\n- Writes a complete design system document with palette, typography, component guidelines, and immersive UI instructions\n- Modifies `CLAUDE.md` to give Claude a themed conversational personality and design awareness\n- Sets up sound hooks in `.claude/settings.json`\n- Creates a symlink-based theme system (`.a5c/theme` -> `.a5c/themes/<name>/`) for switching between themes\n\n**What this means for the project:** Claude speaks in the theme's voice, generates UI using the themed design system, and plays thematic sounds on every action. Your dev environment *feels* different.\n\n### github-actions-cicd\n\nSets up babysitter-powered GitHub Actions workflows.\n\n**What the AI agent does:** Interviews you about which workflow triggers to enable (issue comments, PR events, schedules, manual dispatch), creates up to 8 workflow templates in `.github/workflows/`, configures GitHub secrets, and sets up artifact preservation.\n\n### rate-limit-handler\n\nConfigures hooks to detect and handle API rate limits with exponential backoff.\n\n**What the AI agent does:** Interviews you about backoff strategy (exponential-jitter, linear, fixed), creates detection and retry scripts, integrates them as Claude Code hooks that trigger on PostToolUseFailure and Notification events.\n\n---\n\n## Using Plugins\n\n### Quick Start\n\n```bash\n# Add the official marketplace\nbabysitter plugin:add-marketplace \\\n  --marketplace-url https://github.com/a5c-ai/babysitter \\\n  --marketplace-path plugins/a5c/marketplace \\\n  --global\n\n# See what's available\nbabysitter plugin:list-plugins --marketplace-name babysitter --global\n\n# Install a plugin (starts the AI-driven interview)\nbabysitter plugin:install testing-suite --global\n\n# Reconfigure later\nbabysitter plugin:configure testing-suite --project\n\n# Remove it\nbabysitter plugin:uninstall testing-suite --global\n```\n\n### CLI Commands Reference\n\nAll commands accept `--json` for machine-readable output.\n\n**Marketplace management:**\n\n```bash\nbabysitter plugin:add-marketplace --marketplace-url <url> [--marketplace-path <path>] --global\nbabysitter plugin:update-marketplace --marketplace-name <name> --global\nbabysitter plugin:list-plugins --marketplace-name <name> --global\n```\n\n**Plugin lifecycle:**\n\n```bash\nbabysitter plugin:install <name> [--marketplace-name <mp>] --global\nbabysitter plugin:update <name> [--marketplace-name <mp>] --global\nbabysitter plugin:configure <name> [--marketplace-name <mp>] --global\nbabysitter plugin:uninstall <name> --global\n```\n\nFor `plugin:install`, `plugin:update`, and `plugin:configure`, `--marketplace-name` is optional when the selected scope has a single configured marketplace and the CLI can auto-resolve it.\n\n**Registry management:**\n\n```bash\nbabysitter plugin:list-installed --global\nbabysitter plugin:update-registry <name> --plugin-version <ver> --marketplace-name <mp> --global\nbabysitter plugin:remove-from-registry <name> --global\n```\n\nReplace `--global` with `--project` for project-scoped operations.\n\n---\n\n## Creating Plugins\n\n### Plugin Package Structure\n\nA plugin is a directory with markdown instruction files:\n\n```\nmy-plugin/\n  install.md           # What the AI agent does when someone installs this plugin\n  uninstall.md         # How to reverse the installation\n  configure.md         # How to reconfigure after install\n  plugin.json          # Optional manifest (name, version)\n  migrations/          # Version upgrade instructions\n    1.0.0_to_1.1.0.md\n    1.1.0_to_2.0.0.md\n  process/             # Optional babysitter process definitions\n```\n\nOnly `install.md` is required.\n\n### Writing install.md\n\nThis is the core of your plugin. It's a markdown document that an AI agent will read and execute. Write it as instructions for the agent, not documentation for a human.\n\n**Effective patterns from the built-in plugins:**\n\n1. **Start with project analysis.** Have the agent inspect the codebase before asking questions. The testing-suite plugin checks for existing test configs, linters, CI/CD, and git hooks *before* presenting options.\n\n2. **Interview in stages.** Don't dump all questions at once. The project-deployment plugin asks about deployment approach first, then cloud provider (only if relevant), then CI/CD, then environments, then add-ons.\n\n3. **Be stack-aware.** Provide different instructions for different stacks. The basic-security plugin has separate ESLint rule blocks for React, Express, Python (ruff), and Go (gosec).\n\n4. **Copy from the babysitter library.** Plugins typically copy processes, skills, and agents from the built-in `library/` tree, such as `library/specializations/` or `library/methodologies/gsd/`, into the project's `.a5c/` directories. This seeds the project with project-local overrides and domain-specific Babysitter capabilities.\n\n5. **Modify project config files.** Plugins routinely edit `.eslintrc`, `tsconfig.json`, `package.json`, `.gitignore`, `CLAUDE.md`, `.claude/settings.json`, and CI/CD pipelines. Use merge semantics (append, don't overwrite) and check for existing content.\n\n6. **Verify at the end.** Run the installed tools, check that hooks work, confirm configs are valid. The testing-suite plugin runs the full test suite and reports coverage.\n\n7. **Register the plugin.** Always end with `babysitter plugin:update-registry` so the system tracks what was installed.\n\n### Writing Migration Files\n\nWhen you release a new version, add migration files to `migrations/`:\n\n```\nmigrations/\n  1.0.0_to_1.1.0.md    # Markdown instructions for the upgrade\n  1.1.0_to_2.0.0.md    # Another step\n```\n\n**Filename format:** `<from>_to_<to>.md` (or `.js` for executable process files)\n\nThe SDK builds a directed graph of all migrations and uses BFS to find the shortest path from the user's current version to the target. If you have `1.0.0 -> 1.1.0` and `1.1.0 -> 2.0.0`, a user on 1.0.0 upgrading to 2.0.0 gets both in sequence automatically.\n\n### Publishing to a Marketplace\n\nCreate a `marketplace.json` in a git repository:\n\n```json\n{\n  \"name\": \"My Marketplace\",\n  \"description\": \"A collection of plugins\",\n  \"url\": \"https://github.com/org/repo\",\n  \"owner\": \"org\",\n  \"plugins\": {\n    \"my-plugin\": {\n      \"name\": \"my-plugin\",\n      \"description\": \"Does something useful\",\n      \"latestVersion\": \"1.0.0\",\n      \"versions\": [\"1.0.0\"],\n      \"packagePath\": \"plugins/my-plugin\",\n      \"tags\": [\"utility\"],\n      \"author\": \"org\"\n    }\n  }\n}\n```\n\nThe `packagePath` is relative to the directory containing `marketplace.json`. Users add your marketplace with:\n\n```bash\nbabysitter plugin:add-marketplace --marketplace-url <url> --global\n```\n\n---\n\n## Under the Hood\n\n### Registry Format\n\n```json\n{\n  \"schemaVersion\": \"2026.01.plugin-registry-v1\",\n  \"updatedAt\": \"2026-01-15T10:00:00.000Z\",\n  \"plugins\": {\n    \"testing-suite\": {\n      \"name\": \"testing-suite\",\n      \"version\": \"1.0.0\",\n      \"marketplace\": \"babysitter\",\n      \"scope\": \"project\",\n      \"installedAt\": \"2026-01-10T08:00:00.000Z\",\n      \"updatedAt\": \"2026-01-15T10:00:00.000Z\",\n      \"packagePath\": \"/path/to/package\",\n      \"metadata\": {}\n    }\n  }\n}\n```\n\nAll writes use the SDK's atomic write protocol (temp file + fsync + rename).\n\n### Marketplace Resolution\n\nWhen reading a marketplace manifest, the SDK searches in order:\n1. Custom path from `.babysitter-manifest-path` (set via `--marketplace-path` at clone time)\n2. Root `marketplace.json`\n3. `.claude-plugin/marketplace.json` (legacy)\n\nA legacy array-format manifest is auto-normalized.\n\n### SDK Module Map\n\n| Module | What it does |\n|--------|-------------|\n| `types.ts` | Interfaces: `PluginRegistry`, `MarketplaceManifest`, `MigrationDescriptor`, `PluginPackageInfo` |\n| `paths.ts` | Resolves filesystem paths based on scope (`~/.a5c/` vs `<project>/.a5c/`) |\n| `registry.ts` | CRUD on the registry JSON with atomic writes |\n| `marketplace.ts` | Git clone/pull, manifest reading, plugin path resolution |\n| `packageReader.ts` | Reads `install.md`, `configure.md`, `uninstall.md`, collects process files |\n| `migrations.ts` | Parses migration filenames, builds version graph, BFS shortest path |\n\n---\n\n## Further Reading\n\n- [CLI Reference](plugins/cli-reference.md) -- Complete command syntax, flags, and output schemas\n- [Marketplace Format](plugins/marketplace-format.md) -- Full `marketplace.json` specification\n- [Migration Guide](plugins/migration-guide.md) -- Detailed migration system documentation\n- [Plugin Author Guide](plugins/plugin-author-guide.md) -- Step-by-step plugin creation guide\n- [SDK Plugin Module](../packages/sdk/src/plugins/PLUGINS.md) -- Internal developer reference\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}