| name | docker-runtime-workspace-parity |
| description | Prevents workspace package omissions in Docker images by verifying runtime-stage COPY coverage for every app dependency. Use when editing Dockerfiles, debugging ERR_MODULE_NOT_FOUND in containers, or changing workspace dependencies. |
Docker Runtime Workspace Parity (Metaboost)
Use this skill when editing Metaboost Dockerfiles or workspace dependencies.
Why
Builder stages can compile successfully while runtime stages fail if a workspace package is not copied into the final image.
Typical failures:
ERR_MODULE_NOT_FOUND- Missing package like
@metaboost/orm at container startup
Slim runtime stage (selective COPY)
When a Dockerfile uses selective COPY --from=builder (not full packages/):
- Identify all
@metaboost/* dependencies in the target app's package.json.
- In the runtime stage, verify each dependency package has both:
COPY --from=builder .../package.json ...COPY --from=builder .../dist/ ...
- If a dependency is missing, add both COPY lines.
- Rebuild the image and confirm runtime startup/module import works.
Local Docker layout (infra/docker/local/**)
Metaboost local Dockerfiles generally COPY packages/ ./packages/ (whole tree). That still requires:
- Root
package.json workspaces includes the new package path.
package-lock.json updated after dependency changes.npm run build:packages includes the new package in dependency-safe order — see build-order skill and .llm/context/architecture.md.
If a Dockerfile does not copy all of packages/, apply the slim runtime checklist above.
Scope
Primary paths:
Also apply to any new Metaboost Dockerfile or CI image that builds from this monorepo.
Fast verification pattern
From monorepo root, after Dockerfile edits:
docker build -f infra/docker/local/api/Dockerfile -t metaboost-api:test .
Use the Dockerfile path for the app you changed.
