name: compose-stack-change-protocol description: > Modifies Docker Compose definitions for a multi-service stack while preserving service names, volumes, production defaults, and reproducible bring-up. Use when changing infrastructure manifests that impact runtime behavior. compatibility: runners: ["codex-cli", "claude-code", "openclaw"] tools: ["Read", "Grep", "Bash", "Write"] offline_ok: true

Compose Stack Change Protocol

Purpose

Make compose changes safely and reproducibly by enforcing a minimal-diff protocol and required bring-up verification.

Quick start

Goal:

• Change compose safely and prove the stack still boots and passes smoke checks.

Use when (triggers):

• Editing files under infra/compose/
• Adding/removing services or changing ports
• Changing volumes, networks, or env wiring between services

Do NOT use when (non-goals):

• Changing runtime behavior that belongs in app code
• Introducing new infrastructure dependencies without explicit approval

Operating constraints

• No secrets: never embed API keys, tokens, passwords, private URLs.
• Be minimal: smallest diffs; no drive-by refactors unless required.
• Be explicit: state assumptions and verify them where possible.
• Be deterministic: prefer exact commands/checklists over vague guidance.
• Keep SKILL.md short: if you exceed ~500 lines, split details into linked files.

Inputs this Skill expects

Required:

• The exact compose file list used to launch the stack (keep stable across docs/tests)
• The current infra/compose/docker-compose.*.yml you intend to modify

Optional:

• Deployment constraints from README.md
• Smoke checklist results or existing runbooks

If required inputs are missing:

• Ask for the MINIMUM missing info OR proceed with safest defaults and list assumptions.

Output contract

Primary deliverable:

• A minimal compose diff + verified stack bring-up using the standard multi-file invocation.

Secondary deliverables (only if needed):

• Optional: update docs that show compose commands (README/docs)
• Optional: add/adjust healthchecks to make failures obvious

Definition of DONE (objective checks):

• docker compose ... config succeeds (no schema errors)
• Stack comes up (up -d --build) and containers are healthy
• Critical endpoints are reachable locally (or via configured network)

Procedure (copy into working response and tick off)

Progress:

• 1) Confirm scope + constraints
• 2) Locate entrypoints + relevant files
• 3) Plan smallest safe change set
• 4) Implement changes
• 5) Validate locally
• 6) Summarize changes + next steps

1) Confirm scope + constraints

• Restate objective in ONE sentence.
• List constraints (security, offline/LAN-only, no new deps, etc.).
• List assumptions explicitly.

2) Locate entrypoints + relevant files

Run targeted searches:

• Search terms:
  • infra/compose
  • docker-compose
  • healthcheck
  • network_mode
• Files to inspect first (prioritized):
  1. infra/compose/docker-compose.*.yml
  2. docs/ (if they reference compose commands)

3) Plan smallest safe change set

Rules:

• Touch the minimum number of files.
• Prefer additive changes over rewrites.
• If multiple approaches exist, choose the simplest that satisfies DONE checks.
• If risk is medium/high, write a micro-plan artifact before coding.
• Preserve service names used by scripts/tests (treat them as API).
• Prefer adding an override file rather than editing multiple base files.

4) Implement changes

Implementation checklist:

• Follow repo conventions (naming, formatting, module boundaries).
• Add or adjust any needed configuration.
• Update tests where applicable.
• Update docs where user-facing behavior changes.
• Run docker compose ... config and inspect the rendered output for unintended changes.

5) Validate locally (choose what exists in the repo)

Run validations in this order:

1. Fast static checks:
   • docker compose -f infra/compose/<file>.yml config >/dev/null
2. Unit/targeted tests:
   • Run repo-native tests if service wiring changed
3. Integration smoke test:
   • docker compose -f infra/compose/<file1>.yml -f infra/compose/<file2>.yml up -d --build
   • docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' | head

If validation fails:

• Do not guess. Inspect error output, fix, re-run until green.
• If blocked by missing deps or environment, document the exact missing item and minimal install/run step.

6) Summarize changes + next steps

Include:

• What changed (bullets)
• Why (bullets)
• How to verify (exact commands)
• Next steps (1–3 max)

Pitfalls / gotchas (keep this brutally honest)

• Breaking scripts/tests by renaming services → treat names as API; don’t change them casually.
• Silent misconfig via env vars → document any new/changed vars and defaults.
• Accidentally enabling outbound network access → re-run no-egress verification after compose changes.

Progressive disclosure (one level deep)

If this Skill needs detail, link it directly from HERE (avoid chains of references):

• Examples: ./EXAMPLES.md

Verification pattern (recommended for medium/high risk)

Use this when changes touch infra, retrieval logic, licensing, or security:

1. Analyze
2. Write a machine-checkable plan artifact (e.g. report.md / changes.json)
3. Validate assumptions (paths, versions, config)
4. Execute changes
5. Verify DONE checks

Example References (concise summaries only)

How to reference examples:

• Keep summaries SHORT (1-2 sentences max)
• Reference by stable Example ID (line numbers are brittle across editors/formatters)
• Agents will load full examples only when symptoms match

Example summaries:

1. Port change - Change only published port mapping, verify at new port. See EXAMPLES.md (EX-2026-02-04-01)
2. Optional helper service - Add new compose file without altering base stack. See EXAMPLES.md (EX-2026-02-04-02)

Note: Full examples with tags and trigger phrases are in ./EXAMPLES.md.