align-lab-plugin

Align Lab Plugin

Align an existing plugin to the current homelab canonical spec.

Default Assumptions

When the user does not provide full context, assume:

• If no review report exists, perform a quick structural audit of all canonical surfaces before writing a plan
• The canonical source of truth for shared plugin-contract files is ~/workspace/plugin-templates/
• Language-specific files come from ~/workspace/plugin-templates/py/, ~/workspace/plugin-templates/rs/, or ~/workspace/plugin-templates/ts/ depending on the plugin's runtime
• Preserve any deviation that is clearly intentional, documented, and still valid — do not erase differences simply because they differ from the template
• If the user says "align my plugin," treat all 10 surfaces as in scope unless they narrow the request

Start From Evidence

Do not begin editing from vague assumptions.

Start with one of:

• a fresh plugin review (run review-lab-plugin if no report exists)
• an existing review report from docs/reports/plugin-reviews/
• a concrete list of files the user wants aligned

If no review exists, perform a quick audit of the canonical surfaces before planning edits. Check that the key files are present and structurally sound before committing to a full alignment plan.

Alignment Targets

Prioritize these ten surfaces in order:

1. Manifests and Version Sync

Correct alignment means plugin.json (or Cargo.toml / pyproject.toml / package.json) carries the same version string as the Git tag and as any version field in CHANGELOG.md. The name, description, and mcp_version fields match the canonical schema. Drift looks like a plugin.json version frozen at 0.1.0 while the package manifest is at 1.3.0, or a mcp_version field referencing a superseded protocol revision.

2. .env.example and Runtime Contract

Correct alignment means every environment variable the plugin reads at runtime appears in .env.example with a descriptive placeholder value and an inline comment explaining what it does. Drift looks like variables present in entrypoint.sh or application code that are absent from .env.example, or stale variables in .env.example that the application no longer reads.

3. Dockerfile

Correct alignment means a two-stage build: a builder stage that compiles or installs dependencies, and a minimal runtime stage that copies only the production artifact and runs as a non-root user. Drift looks like a single-stage build that ships compilers and dev dependencies into the final image, a USER root in the runtime stage, or base images pinned to latest instead of a digest or minor-version tag.

4. docker-compose.yaml

Correct alignment means the service stanza references env_file: .env, defines a healthcheck with the canonical interval/timeout/retries defaults, exposes only the required port, and uses named volumes for any persistent data. Drift looks like inline environment: blocks that duplicate .env.example values, a missing healthcheck, or bind-mounts to absolute host paths that break portability.

5. entrypoint.sh

Correct alignment means the script validates every variable listed in .env.example before starting the server, exits with a non-zero code and a clear error message for any missing variable, and ends with exec "$@" or an equivalent direct handoff to the server process. Drift looks like missing variable checks, silent failures when a required var is unset, or a sleep-loop health-wait that masks startup errors.

6. Justfile

Correct alignment means the canonical targets exist: build, up, down, logs, test, lint, and clean. Each target delegates to the correct underlying tool (Docker Compose, the language test runner, etc.) with no hardcoded project-specific paths that would break in another repo. Drift looks like missing targets, targets that call docker-compose (v1 binary) instead of docker compose (v2 plugin), or targets with inline logic that belongs in a script.

7. Hook Scripts and Hook Config

Correct alignment means hooks.json (or lefthook.yml) references only scripts that exist under hooks/scripts/, every referenced script is executable, and the hooks cover at minimum: env-file permission check, no-baked-env check, and ignore-file sync. Drift looks like hook entries pointing to deleted scripts, hooks that are defined but never triggered because the glob is wrong, or missing hooks that allow .env to be committed.

8. CI Workflows

Correct alignment means .github/workflows/ci.yaml runs lint, test, and build on every pull request, uses the canonical job structure from ~/workspace/plugin-templates/ts/ (or py/ or rs/), and pins action versions to a SHA or tagged release. Drift looks like workflows that only run on push to main, unpinned @main action references, or a workflow that skips the build step and ships untested code.

9. Live Tests

Correct alignment means tests/test_live.sh (or the language-equivalent) exercises at least one real tool call against a running container, asserts a non-error HTTP response from /health, and exits non-zero on failure. Drift looks like a test file that is present but contains only echo "TODO", tests that require manual env setup with no documented steps, or tests that always pass because they never assert anything.

10. README, CLAUDE, Commands, Agents, and Skills

Correct alignment means README.md covers installation, configuration (referencing .env.example), and usage; CLAUDE.md describes the plugin's tools and any gotchas for AI assistants; any slash commands in commands/ have correct frontmatter; agents in agents/ reference real tool names. Drift looks like a README that describes a different plugin's setup flow, a CLAUDE.md that lists tool names that no longer exist, or command files with stale allowed-tools entries.

Use Canonical Sources

When aligning files:

• prefer ~/workspace/plugin-templates/ for shared plugin-contract files (hooks, CI structure, check scripts)
• prefer ~/workspace/plugin-templates/py/, ~/workspace/plugin-templates/rs/, or ~/workspace/plugin-templates/ts/ for runtime and language-toolchain files
• keep justified plugin-specific differences
• remove stale or duplicated custom scaffolding that duplicates template content without adding value

Do not erase a deviation just because it differs. Preserve it when it is clearly intentional and still valid. Document preserved deviations in the alignment report.

Plan Before Editing

Write a concrete alignment plan before making broad edits.

The plan must separate:

• required fixes — gaps that would cause the plugin to fail validation or behave incorrectly
• optional improvements — style or consistency issues that are low-risk
• justified deviations to preserve — intentional differences with a documented reason
• open questions requiring user input — ambiguities that cannot be resolved from the files alone

Implement Safely

Make changes in an order that reduces churn:

1. manifests and config contract
2. runtime and Docker files
3. tests and CI
4. docs and AI-facing files

Do not claim full alignment unless the final files and verification steps support it.

Produce an Alignment Report

Write the alignment summary to:

• docs/reports/plugin-alignments/YYYYMMDD-HHMMSS.md

Use the template at skills/align-lab-plugin/references/alignment-report-template.md. Include:

• source plugin path
• canonical sources used
• files changed (table with file, change, reason)
• preserved deviations
• follow-up work
• verification commands run and their output

Verification

Run the strongest available local checks after alignment. Use the concrete commands in skills/align-lab-plugin/references/verification-commands.md.

Required checks:

# Validate plugin manifest JSON is well-formed
jq . .claude-plugin/plugin.json

# Check version appears consistently
grep -r "\"version\"" plugin.json package.json pyproject.toml Cargo.toml 2>/dev/null

# Shell syntax check on all shell scripts
bash -n entrypoint.sh hooks/scripts/*.sh

# YAML lint on CI workflow
yamllint .github/workflows/ci.yaml

# Docker Compose config validation
docker compose config --quiet

# Env var coverage check (vars in entrypoint but not in .env.example)
grep -oE 'required_var "[A-Z_]+"' entrypoint.sh | sort
grep -oE '^[A-Z_]+=' .env.example | sort

State clearly what was and was not verified. If a check requires a running container or network access, note it as deferred.

Related Skills

• review-lab-plugin — run before aligning; produces the review report this skill consumes
• scaffold-lab-plugin — canonical surface reference; use to understand what a greenfield plugin looks like
• deploy-lab-plugin — for Docker and Compose alignment specifically
• pipeline-lab-plugin — for CI workflow alignment specifically