plugin-lab

Align an existing plugin to the canonical lab/plugin spec

Target path relative to plugin root: `commands/my-plugin/inspect.md`

Scaffold a new lab plugin with a spec-conforming plan

Create or update Docker container config for a lab plugin

Implement or update the full CI/CD pipeline for a lab plugin

Research current plugin/MCP/runtime guidance for lab work

Audit a plugin against the canonical spec and write a report

Initialize homelab environment and configure .env file

Create, review, or update a plugin's MCP tools

CLAUDE.md

Read the relevant agent docs before creating or editing agents here.

CLAUDE.md

Use this agent when the user wants an existing MCP plugin updated to match the homelab canonical plugin spec, wants a review report turned into implementation work, or wants stale scaffolding replaced with the `plugin-templates` repo and canonical patterns. <example> Context: User wants a plugin brought up to current standard. user: "Align this plugin to the current homelab spec." assistant: "I'll use ally-the-aligner to plan and implement the alignment." <commentary> This agent turns review findings into concrete changes while preserving justified deviations. </commentary> </example> <example> Context: User invokes the align command. user: "/align-lab-plugin" assistant: "Spawning ally-the-aligner to update the plugin to spec." <commentary> The command routes to this agent so alignment work uses the same methodology every time. </commentary> </example> <example> Context: User has a review report and wants the fixes implemented. user: "Roddy produced a review report yesterday. Now implement all the fixes." assistant: "I'll have ally-the-aligner read the review report and implement each finding as a targeted change." <commentary> Ally consumes review artifacts as its primary input — it can work from an existing report without re-auditing if the report is recent. </commentary> </example>

Use this agent when the user wants to containerize a lab plugin, create or update a Dockerfile, docker-compose.yaml, or entrypoint.sh, audit existing container config for drift, or plan a deploy strategy for a plugin. <example> Context: User wants Docker config created for a new plugin. user: "Containerize the Gotify plugin and set up Compose." assistant: "I'll launch dex-the-deployer to produce the Dockerfile, entrypoint, and Compose config." <commentary> This is the dedicated containerization agent. It reads the deploy-lab-plugin skill, gathers port and env var inputs, and produces a canonical multi-stage container config. </commentary> </example> <example> Context: User invokes the deploy command. user: "/deploy-lab-plugin" assistant: "Spawning dex-the-deployer to handle the container and deploy work." <commentary> The command routes here so all containerization and deploy work uses the same methodology. </commentary> </example> <example> Context: User needs to roll back a deployed plugin to a prior version. user: "The 1.3.0 release broke something — roll back the Overseerr plugin to 1.2.3." assistant: "I'll use dex-the-deployer to pin the prior image tag in docker-compose.yaml and produce the rollback commands." <commentary> Dex handles rollback via image tag pinning, not scale-to-zero. It's the right agent for any Compose-level deploy operation. </commentary> </example>

<!-- Updated: 2026-04-03T23:36:37Z -->

<!-- Updated: 2026-04-03T23:36:35Z -->

Use this agent when the user wants to implement or update any CI/CD workflow for a lab plugin: the main CI test gate, Docker image publishing, automated releases, pre-commit hooks, or Justfile targets. Also use when Justfile targets and CI steps have diverged. <example> Context: User wants the full CI/CD setup for a new plugin. user: "Set up the full CI pipeline for the Gotify plugin." assistant: "I'll launch petra-the-pipeliner to implement all four workflow files — ci.yaml, publish-image.yaml, release-on-main.yaml — plus lefthook and the Justfile targets." <commentary> This is the dedicated CI/CD agent. It reads the pipeline-lab-plugin skill and produces all workflow files, not just ci.yaml. </commentary> </example> <example> Context: User invokes the pipeline command. user: "/pipeline-lab-plugin" assistant: "Spawning petra-the-pipeliner to handle the pipeline work." <commentary> The command routes here so all CI/CD work uses the same methodology. </commentary> </example> <example> Context: User needs to set up automated releases. user: "I want every push to main to automatically cut a GitHub release if the version changed." assistant: "I'll use petra-the-pipeliner to set up release-on-main.yaml — it reads the version from your manifest, creates a git tag, and cuts a GitHub release. It fails if the tag already exists, which enforces a version bump on every main push." <commentary> Petra handles release-on-main.yaml as a first-class workflow, not just as a sub-step of ci.yaml. </commentary> </example> <example> Context: User notices CI and local Justfile have diverged. user: "My CI tests pass but just test fails locally — something's out of sync." assistant: "I'll use petra-the-pipeliner to audit the pipeline and Justfile targets for divergence and bring them back into sync." <commentary> Petra handles Justfile/CI sync issues as a first-class use case. </commentary> </example>

Use this agent when the user needs current primary-source research on MCP, Claude Code plugins, Codex plugins, language SDKs, package choices, or adjacent runtime guidance that affects plugin scaffolding, review, or alignment. <example> Context: User wants current MCP and SDK guidance before building a plugin. user: "Research the current best setup for a TypeScript MCP plugin." assistant: "I'll launch rex-the-researcher to gather current primary-source guidance." <commentary> This agent is the dedicated research specialist for current docs, protocols, SDKs, and runtime guidance. </commentary> </example> <example> Context: Scaffolding agent needs delegated current-state research. user: "Use the latest docs and packages before scaffolding this plugin." assistant: "Dispatching rex-the-researcher to gather current evidence." <commentary> Other lab agents should delegate to this agent whenever the work depends on information that may have changed. </commentary> </example> <example> Context: User needs to verify whether a specific SDK pattern is still current. user: "Is the FastMCP Python transport pattern we used six months ago still the right approach?" assistant: "I'll have rex-the-researcher check the current FastMCP docs and release notes for any transport changes." <commentary> Rex is the right agent for targeted fact-checking against primary sources, not just broad research sweeps. </commentary> </example>

Use this agent when the user wants an MCP plugin reviewed against the homelab canonical plugin spec, wants all misalignments identified, or wants a detailed plugin review report written to disk. <example> Context: User wants a plugin audited for drift. user: "Review this plugin and tell me everything that's out of spec." assistant: "I'll use roddy-reviewer to run a spec audit and produce a report." <commentary> This is the canonical plugin review agent. It focuses on misalignments, justified deviations, and report-quality findings. </commentary> </example> <example> Context: User invokes the review command. user: "/review-lab-plugin" assistant: "Spawning roddy-reviewer to audit the plugin." <commentary> The command routes to this agent so review logic is consistent and reusable. </commentary> </example> <example> Context: Ally needs a current review before starting alignment work. user: "Align this plugin — it hasn't been touched in six months." assistant: "I'll have roddy-reviewer audit the plugin first so ally-the-aligner has a current findings list to work from." <commentary> Roddy is also invoked by ally-the-aligner when no recent review report exists. The review output becomes the alignment plan input. </commentary> </example>

Use this agent when the user wants to create a new MCP plugin scaffold, turn a service idea into a canonical plugin plan, or synthesize research into a concrete scaffold strategy. <example> Context: User wants a new plugin created from docs and repo links. user: "Create a new plugin for Service X from these docs and repos." assistant: "I'll launch ster-the-scaffolder to gather inputs, coordinate research, and produce the scaffold plan." <commentary> This is the dedicated scaffolding agent. It reads the scaffold-lab-plugin skill, gathers missing inputs, delegates research when needed, and turns the result into a canonical scaffold plan. </commentary> </example> <example> Context: User invokes the create command. user: "/create-lab-plugin" assistant: "Spawning ster-the-scaffolder to drive plugin creation." <commentary> The command routes to this agent so scaffolding logic stays in one place. </commentary> </example> <example> Context: Another agent needs a scaffold plan before implementation. user: "Before we implement, produce a scaffold plan for the Overseerr plugin." assistant: "Dispatching ster-the-scaffolder to produce the scaffold plan. It will delegate research to rex-the-researcher if current SDK behavior needs verification." <commentary> Ster is also invoked by other agents as a planning step before broad file generation begins. </commentary> </example>

Use this agent when the user wants to create a new MCP tool using the action+subaction pattern, review existing tools for conformance, or update a tool's schema, dispatch table, or handler set. <example> Context: User wants a new tool added to an existing plugin. user: "Add a tool for managing applications to the Gotify plugin." assistant: "I'll launch tilly-the-toolsmith to design the tool contract and implement the action+subaction dispatch." <commentary> This is the dedicated tool design agent. It reads the tool-lab-plugin skill, gathers the operation set, and produces a conforming tool contract with handlers and a help companion. </commentary> </example> <example> Context: User invokes the tool command. user: "/tool-lab-plugin" assistant: "Spawning tilly-the-toolsmith to handle the tool work." <commentary> The command routes here so all tool design and review work uses the same methodology. </commentary> </example> <example> Context: User has an existing plugin with flat tools that need restructuring. user: "This plugin has five separate tools. Refactor them into the action+subaction pattern." assistant: "I'll use tilly-the-toolsmith to audit the existing tools, design the collapsed action+subaction contract, and implement the refactor." <commentary> Tilly handles both net-new tool creation and refactoring of flat tool lists into the canonical dispatch shape. </commentary> </example>

Bring an existing MCP plugin into full alignment with the homelab canonical plugin spec. Use when the user wants to update a plugin to current standards, replace stale scaffolding with the `plugin-templates` repo, reconcile manifest drift, standardize Docker and CI files, or turn a review report into a concrete alignment plan and implementation.

Containerize and deploy a lab plugin using Docker and Docker Compose. Use when the user wants to create or update a Dockerfile, docker-compose.yaml, entrypoint.sh, or health endpoint; audit an existing container config for drift; or plan a deploy strategy for a plugin. Trigger phrases include "Dockerize my Rust plugin", "containerize my Python MCP server", "set up Compose for my TypeScript plugin".

Research current primary-source guidance for MCP, Claude Code plugins, Codex plugins, and the language/runtime stack used by homelab plugins. Use when the user asks "what changed in the MCP SDK", "is this transport pattern still current", "find the latest docs for X", "before I scaffold this plugin I need to know...", or any time up-to-date information about MCP protocol changes, plugin manifests, SDK versions, transport patterns, package choices, Docker guidance, or the latest official docs is needed to scaffold, review, or align a plugin.

Implement or update the full CI/CD pipeline for a lab plugin. Use when the user wants to add or update GitHub Actions workflows (ci.yaml, publish-image.yaml, release-on-main.yaml), configure pre-commit or lefthook, set up automated releases, audit an existing pipeline for drift, or sync Justfile targets with CI steps.

Review an MCP plugin against the homelab canonical plugin spec and identify any and all misalignments. Use when the user wants a plugin audited for spec drift, wants to compare a plugin to canonical manifests and runtime patterns, wants to know whether deviations are documented and justified, or wants a detailed plugin review report.

Create a new MCP plugin scaffold aligned to the homelab canonical plugin spec. Use when the user wants to create a new plugin repo, scaffold a plugin in Python, Rust, or TypeScript, choose manifests and runtime files, define commands/agents/skills, or turn docs and API references into an implementation plan for a new plugin.

Interactive credential setup wizard for claude-homelab. Use when the user wants to configure credentials, set up a new service, update API keys, or run initial setup after installing the homelab-core plugin. Triggers on: 'setup credentials', 'configure plex', 'add my API key', 'I just installed homelab-core', 'setup homelab', or any mention of needing to configure a homelab service credential.

Create, review, or update MCP tools inside a plugin using the action+subaction dispatch pattern. Use when the user wants to add a new tool to an existing plugin, audit existing tools for conformance, refactor a flat tool list into action+subaction shape, or generate the parameter schema and dispatch logic for a tool.

Target path relative to plugin root: `skills/my-plugin/SKILL.md`

Target path relative to plugin root: `skills/my-plugin/SKILL.md`