# Program Design: Ship the Factory Skill in the OpenCode Agent Image ## Files - `skills/software-factory/SKILL.md` — versioned copy of the factory skill to ship. - `Dockerfile` — copy the skill asset into the immutable image at `/usr/local/share/opencode/skills/software-factory/`. - `docker/entrypoint.sh` — include the baked-in skills directory in the generated OpenCode config, alongside the current shell setting. - `README.md` — document that `software-factory` is available in the image. - `docs/plans/factory-skill-image/00-status.md` — gate approvals and slice progress. - `docs/plans/factory-skill-image/01-product.md` — approved product statement. - `docs/plans/factory-skill-image/02-architecture.md` — approved system fit and runtime flow. - `docs/plans/factory-skill-image/03-program-design.md` — this implementation contract. - `docs/plans/factory-skill-image/04-slices.md` — approved slice sequence. ## Types & signatures ```dockerfile # Dockerfile asset mapping COPY skills/software-factory/SKILL.md \ /usr/local/share/opencode/skills/software-factory/SKILL.md ``` ```json // OpenCode user config generated by docker/entrypoint.sh { "shell": "/usr/local/bin/mise-shell", "skills": ["/usr/local/share/opencode/skills"] } ``` ```text software-factory skill: name: "software-factory" description: body: supporting files: none ``` ## Call stack - Image build: Docker build context → `Dockerfile` copies the versioned skill into `/usr/local/share/opencode/skills`. - Startup/discovery: Compose's empty `/home/opencode` tmpfs → `docker/entrypoint.sh` writes OpenCode config with the baked-in skill source → OpenCode starts and discovers `software-factory` → skill tool/API exposes it to the agent. - Skill use: agent selects `software-factory` → OpenCode loads the skill Markdown from the immutable image path. ## Test plan - `factory skill is advertised by the running image` — build and start the image with the normal temporary-home mount, then assert authenticated `GET /api/skill?directory=/workspace` includes the `software-factory` ID/name. The location must match the agent's project directory. - `factory skill instructions are loadable` — assert the discovered skill response includes its description and expected workflow heading/body, not just a placeholder name. - `existing OpenCode shell configuration remains intact` — confirm the generated config retains `/usr/local/bin/mise-shell` while adding the skill source. - `factory skill remains available after container restart` — restart with a fresh home tmpfs and confirm discovery still lists the baked-in skill. ## Least confident decisions 1. Use the existing `GET /api/skill` response as the image-level verification point; it exercises OpenCode discovery rather than merely checking that a file exists. 2. Keep the skill's source in the repository and copy its current definition verbatim; updates to the upstream/local skill should be intentionally synchronized rather than silently fetched during image builds. 3. Configure the baked-in source through the startup-generated OpenCode config; this relies on the image's normal clean home at startup, as provided by Compose's tmpfs mount.