Skip to content

MARKDOWN SOURCE

Raw
# 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 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 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 → 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.