DeepWorkPlan — Devcontainer Addon
Add a reproducible, isolated dev container to the target repo so any human or
AI agent gets the same environment, with AI-CLI auth that survives rebuilds.
This is the methodology's first opt-in addon — it is never required for a
repo to be AI-first.
The rule that overrides everything: REASON about the repo, then generate
~85% of every Dailybot devcontainer is identical — that common skeleton is
the stable part you carry forward. ~15% is repo-specific — base image, user,
workspaceFolder, supporting services, ports, secrets — and that part you
reason out from the target repo's actual stack, never by copying one
reference repo. The one near-verbatim exception is the AI-CLI persistence
entrypoint (templates/entrypoint.md): it is stable enough to copy with only
the home-path / user adjusted.
Read these first (all relative inside the skill)
SPEC.md — the normative (RFC-2119) contract: common skeleton,
per-repo reasoning checklist, project-identity precedence, validation rule,
public-OSS variant.
templates/presets.md — the 7 reasoning presets
(node-web, node-service, node-lambda, python-service, python-cli-oss,
static-site, orchestrator-hub). Match one as a starting checklist, then
verify every assumption against the real repo — detected reality wins.
- The other
templates/*.md — reasoning guides for each file you generate.
../README.md — the addon mechanism (opt-in, reconcile-don't-clobber, contract).
When this runs
- From
onboard Phase 7b — after the core AI-first scaffolding, onboard
offers this addon; if accepted it reads this SKILL and runs the flow below.
- Directly —
/deepworkplan-addon-devcontainer on an already-onboarded repo
to add or reconcile a devcontainer.
Trust boundary (write scope)
allowed-tools includes write-capable Edit, Write, and Bash. Exactly what
this addon may write — and what it MUST NOT — is enumerated below. Skills.sh /
Gen Agent Trust Hub treat allowed-tools as a trust boundary; this section is
the human-readable contract for that field. Anything not listed here does not
happen.
Reads (always allowed, no consent needed): the target repo's tree (stack
detection, existing .devcontainer/ / docker/ files, lockfiles, RECON notes),
Docker metadata where available.
Writes (only after the developer accepts the addon offer, per file):
.devcontainer/devcontainer.json, docker/local/** (compose, Dockerfile,
entrypoint, custom commands), and — for public repos — .dockerignore +
secret-free .env.example. Reconcile mode: existing values are preserved;
replacing or deleting anything the developer already has requires explicit
approval.
- Optional docs notes describing the devcontainer (only on an accepted
docs-update prompt).
It MUST NOT:
- Put secrets in images, compose files, or
.env.example — ever.
- Enable SSH key seeding (the
~/.ssh read-only mount + SEED_SSH_KEYS=1
pair) without the developer's explicit opt-in, or pre-set that flag in
generated files.
- Generate AI-CLI wrappers that inject permission-bypass flags — wrappers are
pass-through; the developer opts into elevated modes themselves.
- Add services the app does not actually depend on, publish host ports on the
devcontainer service, or run network installers (installs go through package
managers or the verified two-step flow in
templates/Dockerfile.md).
- Push, commit, or mutate anything on the host outside the repo checkout.
The flow
Step 0 — Consent + reconcile check
- Confirm the developer wants a devcontainer (skip silently if declined — the
repo stays baseline-conformant).
- Detect existing setup. Look for
.devcontainer/, docker/,
docker-compose.{yml,yaml}, a Dockerfile. If any exist, you are in
reconcile mode: you MUST preserve working values and MUST NOT overwrite or
delete files without explicit approval (see SPEC §Reconcile).
Step 1 — Reason about the stack (reuse onboard's RECON)
If onboard already produced .dwp/onboard/RECON.md, read it. Otherwise detect:
language/runtime, package manager (from the lockfile that exists), build/test/
lint/typecheck commands, supporting services implied by the app's dependencies
(DB / cache / queue / emulators), exposed ports, and whether the repo is
public (OSS) or private. Pick the matching preset from
templates/presets.md as a checklist.
Step 2 — Decide the reasoned ~15% (SPEC §3 checklist)
- Base image + user +
workspaceFolder from the language (Node vs Python; a
node vs created dev-user; /app vs /workspace vs /code/js).
- Supporting services from real dependencies — only those the app actually
uses (postgres / pgvector / redis / mailpit / dynamodb / localstack / chromium).
- Ports, secrets handling (public vs private), multi-stage build need,
locales, extra CLIs (AWS, Lighthouse/chromium).
Step 3 — Generate / reconcile the files
Using the templates, produce or reconcile:
.devcontainer/devcontainer.json, docker/local/docker-compose.{yaml,yml},
docker/local/{service}/Dockerfile, docker/local/{service}/entrypoint.sh
(the near-verbatim AI-CLI persistence piece), docker/custom_commands.sh, and —
for public repos — .dockerignore + a secret-free .env.example. Always:
keep the common skeleton (AI-CLI persistence volumes, dailybot-project-network,
DOCKER_DEV_ENV=vscode→sleep infinity, codecheck/check/fix/test).
Two security-shaped decisions to surface explicitly: (a) SSH key seeding is
opt-in — offer the read-only ~/.ssh mount + SEED_SSH_KEYS=1 pair only when
the developer needs git-over-SSH, never enable it silently (see
templates/entrypoint.md § Blast radius); (b) AI-CLI wrappers are
pass-through — they forward flags verbatim and never inject a
permission-bypass flag (see templates/custom_commands.md).
Step 4 — Project identity
Set identity by the precedence in SPEC §4
(.dailybot/profile.json → DAILYBOT_PROJECT_NAME → devcontainer.json name).
Do not invent a new name if one already resolves.
Step 5 — Validate (SPEC §6)
Run the validation checklist. Report what was created/reconciled, the chosen
base image + services + ports, identity source, and any deferred items. If a
container build/smoke test cannot run here, say why (don't silently skip).
Failure-mode guardrails
- Never required, never blocking. If the developer declines, stop cleanly.
- No clobber. Existing devcontainer/docker files are reconciled or
backed-up-and-asked, never silently overwritten.
- No phantom services. Only add a service the app actually depends on.
- No secrets in images or in
.env.example — especially for public repos.
- Reason wins over preset. If the preset and the real repo disagree,
re-derive from the repo.
1---2name: deepworkplan-addon-devcontainer-43description: Optional DeepWorkPlan addon that adds (or reconciles) a compose-based devcontainer to a repo — base image and supporting services reasoned from the detected stack, with persistent AI-CLI auth, the dailybot-project-network, the DOCKER_DEV_ENV=vscode convention, and project-identity precedence. Opt-in, never required, reconciles existing setups instead of clobbering them. Use when the developer wants a reproducible isolated dev container for an AI-first repo.4version: "2.17.0"5documentation_url: https://deepworkplan.com6user-invocable: true7allowed-tools: Bash, Read, Grep, Glob, Edit, Write8metadata:9 source: https://skillmd.com/skills/dailybothq/deepworkplan-addon-devcontainer-410 openclaw:11 emoji: 📦12 homepage: https://deepworkplan.com13 requires:14 anyBins:15 - docker16 - git17---1819# DeepWorkPlan — Devcontainer Addon2021Add a **reproducible, isolated dev container** to the target repo so any human or22AI agent gets the same environment, with **AI-CLI auth that survives rebuilds**.23This is the methodology's **first opt-in addon** — it is **never** required for a24repo to be AI-first.2526> ## The rule that overrides everything: REASON about the repo, then generate27>28> ~85% of every Dailybot devcontainer is identical — that **common skeleton** is29> the stable part you carry forward. ~15% is repo-specific — base image, user,30> `workspaceFolder`, supporting services, ports, secrets — and that part you31> **reason out from the target repo's actual stack**, never by copying one32> reference repo. The one near-verbatim exception is the **AI-CLI persistence33> entrypoint** (`templates/entrypoint.md`): it is stable enough to copy with only34> the home-path / user adjusted.3536## Read these first (all relative inside the skill)3738- [`SPEC.md`](SPEC.md) — the normative (RFC-2119) contract: common skeleton,39 per-repo reasoning checklist, project-identity precedence, validation rule,40 public-OSS variant.41- [`templates/presets.md`](templates/presets.md) — the **7 reasoning presets**42 (node-web, node-service, node-lambda, python-service, python-cli-oss,43 static-site, orchestrator-hub). Match one as a *starting checklist*, then44 verify every assumption against the real repo — **detected reality wins**.45- The other `templates/*.md` — reasoning guides for each file you generate.46- `../README.md` — the addon mechanism (opt-in, reconcile-don't-clobber, contract).4748## When this runs4950- From **`onboard` Phase 7b** — after the core AI-first scaffolding, `onboard`51 offers this addon; if accepted it reads this SKILL and runs the flow below.52- **Directly** — `/deepworkplan-addon-devcontainer` on an already-onboarded repo53 to add or reconcile a devcontainer.5455## Trust boundary (write scope)5657`allowed-tools` includes write-capable `Edit`, `Write`, and `Bash`. Exactly what58this addon may write — and what it MUST NOT — is enumerated below. Skills.sh /59Gen Agent Trust Hub treat `allowed-tools` as a trust boundary; this section is60the human-readable contract for that field. Anything not listed here does not61happen.6263**Reads (always allowed, no consent needed):** the target repo's tree (stack64detection, existing `.devcontainer/` / `docker/` files, lockfiles, RECON notes),65Docker metadata where available.6667**Writes (only after the developer accepts the addon offer, per file):**6869- `.devcontainer/devcontainer.json`, `docker/local/**` (compose, Dockerfile,70 entrypoint, custom commands), and — for public repos — `.dockerignore` +71 secret-free `.env.example`. Reconcile mode: existing values are preserved;72 replacing or deleting anything the developer already has requires explicit73 approval.74- Optional docs notes describing the devcontainer (only on an accepted75 docs-update prompt).7677**It MUST NOT:**7879- Put secrets in images, compose files, or `.env.example` — ever.80- Enable SSH key seeding (the `~/.ssh` read-only mount + `SEED_SSH_KEYS=1`81 pair) without the developer's explicit opt-in, or pre-set that flag in82 generated files.83- Generate AI-CLI wrappers that inject permission-bypass flags — wrappers are84 pass-through; the developer opts into elevated modes themselves.85- Add services the app does not actually depend on, publish host ports on the86 devcontainer service, or run network installers (installs go through package87 managers or the verified two-step flow in `templates/Dockerfile.md`).88- Push, commit, or mutate anything on the host outside the repo checkout.8990## The flow9192### Step 0 — Consent + reconcile check931. Confirm the developer wants a devcontainer (skip silently if declined — the94 repo stays baseline-conformant).952. **Detect existing setup.** Look for `.devcontainer/`, `docker/`,96 `docker-compose.{yml,yaml}`, a `Dockerfile`. If any exist, you are in97 **reconcile mode**: you MUST preserve working values and MUST NOT overwrite or98 delete files without explicit approval (see SPEC §Reconcile).99100### Step 1 — Reason about the stack (reuse onboard's RECON)101If `onboard` already produced `.dwp/onboard/RECON.md`, read it. Otherwise detect:102language/runtime, package manager (from the lockfile that exists), build/test/103lint/typecheck commands, supporting services implied by the app's dependencies104(DB / cache / queue / emulators), exposed ports, and whether the repo is105**public** (OSS) or private. Pick the matching **preset** from106`templates/presets.md` as a checklist.107108### Step 2 — Decide the reasoned ~15% (SPEC §3 checklist)109- **Base image + user + `workspaceFolder`** from the language (Node vs Python; a110 `node` vs created `dev-user`; `/app` vs `/workspace` vs `/code/js`).111- **Supporting services** from real dependencies — only those the app actually112 uses (postgres / pgvector / redis / mailpit / dynamodb / localstack / chromium).113- **Ports**, **secrets handling** (public vs private), **multi-stage** build need,114 locales, extra CLIs (AWS, Lighthouse/chromium).115116### Step 3 — Generate / reconcile the files117Using the templates, produce or reconcile:118`.devcontainer/devcontainer.json`, `docker/local/docker-compose.{yaml,yml}`,119`docker/local/{service}/Dockerfile`, `docker/local/{service}/entrypoint.sh`120(the near-verbatim AI-CLI persistence piece), `docker/custom_commands.sh`, and —121**for public repos** — `.dockerignore` + a secret-free `.env.example`. Always:122keep the **common skeleton** (AI-CLI persistence volumes, `dailybot-project-network`,123`DOCKER_DEV_ENV=vscode`→`sleep infinity`, `codecheck`/`check`/`fix`/`test`).124Two security-shaped decisions to surface explicitly: (a) **SSH key seeding is125opt-in** — offer the read-only `~/.ssh` mount + `SEED_SSH_KEYS=1` pair only when126the developer needs git-over-SSH, never enable it silently (see127`templates/entrypoint.md` § Blast radius); (b) **AI-CLI wrappers are128pass-through** — they forward flags verbatim and never inject a129permission-bypass flag (see `templates/custom_commands.md`).130131### Step 4 — Project identity132Set identity by the precedence in SPEC §4133(`.dailybot/profile.json` → `DAILYBOT_PROJECT_NAME` → `devcontainer.json name`).134Do not invent a new name if one already resolves.135136### Step 5 — Validate (SPEC §6)137Run the validation checklist. Report what was created/reconciled, the chosen138base image + services + ports, identity source, and any deferred items. If a139container build/smoke test cannot run here, say why (don't silently skip).140141## Failure-mode guardrails142143- **Never required, never blocking.** If the developer declines, stop cleanly.144- **No clobber.** Existing devcontainer/docker files are reconciled or145 backed-up-and-asked, never silently overwritten.146- **No phantom services.** Only add a service the app actually depends on.147- **No secrets in images or in `.env.example`** — especially for public repos.148- **Reason wins over preset.** If the preset and the real repo disagree,149 re-derive from the repo.