MARKDOWN SOURCE
# 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: <frontmatter description>
body: <factory workflow instructions>
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.
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 thatsoftware-factoryis 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 asset mapping
COPY skills/software-factory/SKILL.md \
/usr/local/share/opencode/skills/software-factory/SKILL.md
// OpenCode user config generated by docker/entrypoint.sh
{
"shell": "/usr/local/bin/mise-shell",
"skills": ["/usr/local/share/opencode/skills"]
}
software-factory skill:
name: "software-factory"
description: <frontmatter description>
body: <factory workflow instructions>
supporting files: none
Call stack
- Image build: Docker build context →
Dockerfilecopies the versioned skill into/usr/local/share/opencode/skills. - Startup/discovery: Compose's empty
/home/opencodetmpfs →docker/entrypoint.shwrites OpenCode config with the baked-in skill source → OpenCode starts and discoverssoftware-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 authenticatedGET /api/skill?directory=/workspaceincludes thesoftware-factoryID/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-shellwhile 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
- Use the existing
GET /api/skillresponse as the image-level verification point; it exercises OpenCode discovery rather than merely checking that a file exists. - 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.
- 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.