name	branchbox-devcontainer-guardrails
description	Use when modifying BranchBox devcontainer/bootstrap workflows, compose templates, feature env-stash behavior, or manual E2E harness/release docs. Apply issue

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.

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.

branchbox-devcontainer-guardrails