# Branchbox Devcontainer Guardrails > Use when modifying BranchBox devcontainer/bootstrap workflows, compose templates, feature env-stash behavior, or manual E2E harness/release docs. Apply issue - Skill: `tomevault-io/branchbox-devcontainer-guardrails-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/branchbox-devcontainer-guardrails-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/branchbox-devcontainer-guardrails-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/branchbox-devcontainer-guardrails-2 --- # BranchBox Devcontainer Guardrails Follow this skill for changes in these areas: - `core/src/bootstrap/**` - `core/src/workflows/feature.rs` - `core/src/modules/compose.rs` - `scripts/manual-*.sh` and `scripts/manual-*.md` - `docs/docs/getting-started/manual-*.md` Load references before implementing: - Read `references/gotchas.md` for known failure patterns and fixes. - Read `references/validation-checklist.md` for exact test commands and required scope. ## Classify the change - Identify whether the change impacts auth/signing bootstrap, compose behavior, feature env/stash logic, or harness/docs. - Treat any change in these areas as release-sensitive and run the full validation checklist. ## Implement with guardrails - Keep host secret retrieval in `initializeCommand` and container setup in `postStartCommand`. - Keep 1Password PAT/signing key flow file-based; do not rely on SSH-agent socket forwarding on Docker Desktop macOS. - Ensure mounted secret files exist before compose startup. - Preserve existing secret files on 1Password read failures (temp file + atomic move; never truncate-first). - Treat empty/whitespace secrets from `op read` as failed refreshes and keep existing files. - Create secret temp files with restricted permissions from creation (`umask 077`) before writing. - Enforce owner-only permissions (`0600`) for host-side token/signing files. - Keep secret mount files ignored by git and generated by init/bootstrap flows. - Do not interpolate raw token values into persisted shell snippets; prefer runtime env vars (`GH_TOKEN`) in credential helpers. - Keep compose templates worktree-safe (no fixed compose project/container names). - Keep compose command compatibility (`docker compose` with fallback to `docker-compose`). - Keep feature workflow robust when `.env` is absent and when untracked files exist. - Sanitize untrusted env-derived values before writing generated env files; keep policy-specific allow-lists (`APP_URL`, `GIT_BRANCH`, `COMPOSE_PROJECT_NAME`). - Compute compose identity once and reuse it for process env + generated files to avoid drift. - Keep harness service resolution tolerant of JSONC comments and multi-stack compose templates. - Extract duplicated harness helpers into `scripts/lib/*.sh` instead of copy/paste between scripts. ## Validate before handoff - Run `./scripts/review-preflight.sh` first to catch security/sanitizer/docs-sync regressions early. - Run devcontainer-side Rust checks and harness matrix from `references/validation-checklist.md`. - Run host-side checks when required (docs build, Swift checks, and 1Password E2E harness). - Run security/robustness preflight checks from `references/validation-checklist.md` (secret permissions, no token interpolation, env-write sanitization, compose fallback, JSONC-safe parsing). - Run a duplication check for harness helpers and keep shared docs as plain synchronized files (no symlink-only assumptions). - Treat failing validation as a blocker unless the failure is unrelated and documented with evidence. ## Update docs in the same change - Update `CHANGELOG.md` when behavior changes. - Keep script docs and docs-site pages synchronized for the same harness. - Update `AGENTS.md` when new project-level expectations are introduced. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/branchbox) — claim your Tome and manage your conversions.