cmk:local-stack
/cmk:local-stack
Use when the user asks to "set up local dev", "make dev worktree-safe", "add a local stack", "port conflicts between worktrees", "headless dev mode", "run services locally for agents/CI", "clean up dangling services", or hits orphaned containers/processes, "port already in use" from leftover runs, stale state from a deleted worktree, or needs worktree-isolated local development stacks with deterministic identity, coherence validation, and interactive/headless runners.
- Author
- commandosslabs ↗
- Repository
- ai-devkit ↗
- Licence
- MIT
- Last repository change
- 20.10.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when the user asks to "set up local dev", "make dev worktree-safe", "add a local stack", "port conflicts between worktrees", "headless dev mode", "run services locally for agents/CI", "clean up dangling services", or hits orphaned containers/processes, "port already in use" from leftover runs, stale state from a deleted worktree, or needs worktree-isolated local development stacks with deterministic identity, coherence validation, and interactive/headless runners.
Triggers from the description
Original author description
Use when the user asks to "set up local dev", "make dev worktree-safe", "add a local stack", "port conflicts between worktrees", "headless dev mode", "run services locally for agents/CI", "clean up dangling services", or hits orphaned containers/processes, "port already in use" from leftover runs, stale state from a deleted worktree, or needs worktree-isolated local development stacks with deterministic identity, coherence validation, and interactive/headless runners.
How it works
- Modes
- Model
- Peers, not a singleton
- Service classes and runners
- .local/ convention
- Global-state prohibition
- Lifecycle discipline
- Test-infrastructure composition
- Where this stops
- Verify
SKILL.md preview
--- name: cmk:local-stack description: Use when the user asks to "set up local dev", "make dev worktree-safe", "add a local stack", "port conflicts between worktrees", "headless dev mode", "run services locally for agents/CI", "clean up dangling services", or hits orphaned containers/processes, "port already in use" from leftover runs, stale state from a deleted worktree, or needs worktree-isolated local development stacks with deterministic identity, coherence validation, and interactive/headless runners. version: 0.4.4 --- # Local Stack Set up or improve a worktree-isolated local stack: a system where multiple git worktrees of the same repo run local service topologies simultaneously, on the same machine, without port collisions, stale config, or cross-worktree contamination. Serves three audiences: human developers, AI agents running headless, and CI. ## Modes **Init** (default) — derive the worktree identity, install the coherence guard, and stand up the first stack config with both runner modes. **Update** — add a stack, config, instance, or runner mode as needs grow; never touch another worktree's or instance's state. **Verify** — report-only audit against the checks under `## Verify`; never mutates. ## Model Two independent axes compose to make this work. ### Axis 1 — between worktrees: identity and coherence Every worktree derives a deterministic **identity** from its own state: a normalized branch label, a normalized worktree label (the primary checkout gets a fixed label; others derive from directory name), and a short hash of the absolute repo path. That identity feeds everything else — the compose project name, the base of every port range, env-file naming, and the root of all state directories — so two worktrees on the same machine never land on the same values. A **coherence guard** runs before anything starts: it recomputes the identity fresh, compares it against what was last written to disk, and checks that every env file's recorded ports and paths match the freshly computed ones. On any mismatch it fails loudly and says exactly what's wrong and how to fix it (normally: re-run init) — it never silently "fixes" a stale file itself. Read `references/identity-and-coherence.md` for the derivation recipe, what it feeds, the guard's checks, and the init-script shape. ### Axis 2 — within a worktree: the (worktree, config, instance) primitive A single worktree may run several stacks, and any one stack may run several parallel materializations. A **config** is owned by whichever package needs a stack (an e2e test group, a benchmark harness, day-to-day dev) and declares its topology. An **instance** is one running materialization of that config, with an explicit state/home root at `.local/<stack>/<config>/<instance>/` and ports assigned by a broker rather than hand-carved arithmetic. Consumers join a shared instance by default; an invoking coordination layer — never the config or the instance mechanism itself — decides when to select distinct instances instead (parallel e2e shards, a disposable test instance beside a persistent dev one, comparing two topologies). Read `references/instance-primitive.md` for ownership, layout, broker responsibilities, and lifecycle. ## Peers, not a singleton A repo may own several purpose-specific local stacks side by side — different topologies for different jobs (a lightweight dev stack, a heavier e2e stack, a production-mirroring benchmark stack). Each is its own package: it owns its config, its runner entry point, and its tests. There is no single blessed "the local stack" every job must fit. ## Service classes and runners Every stack manages some mix of: compose-managed infra (database, cache, object store), application processes, and heavyweight components (e.g. a local chain node or similar out-of-process runtime). Two runner modes cover both audiences: - **Interactive** (mprocs-style): one command brings up infra and apps together in a single terminal, live-reloading, for a human. Heavy or rarely-needed processes are opt-in, not on by default. - **Headless persistent** (`stack start|status|logs [service]|stop`): idempotent, no-TTY, for agents and CI. Logs and PIDs live under `.local/`. Read `references/runners.md` for the contract each mode must satisfy, log hygiene, and when to reach for which. ## `.local/` convention The single git-ignored per-worktree root for all ephemeral state and scratch, shared by humans and every agent vendor: ``` .local/ ├── tmp/ # scratch (instead of /tmp or ad-hoc tmp/) ├── logs/ # service + stack logs ├── pids/ ├── <stack>/ # per-stack state and instances └── env files # worktree-derived env, ports ``` ## Global-state prohibition No home-directory state (`~/.<tool>` singletons), no global processes, no fixed ports. Never source another worktree's env files. Never wipe a stack other than the one explicitly selected instance — no global prune, no deleting `.local/<stack>` wholesale. ## Lifecycle discipline Whoever starts a stack owns stopping it: an agent or CI job stops what it brought up when its task ends — a dangling stack silently starves the next run's ports, memory, and CPU. Only a deliberately persistent instance other sessions are meant to join outlives its starter, through its own explicit lifecycle — never by accident, and never blanket-killed by another session. Cooperative `stop` reaches only what this worktree's `.local/` records still account for, and `.local/` dies with a deleted worktree — so reclamation rests on the identity stamped on each started resource (compose project/labels, process command paths, state roots), never on process ancestry: one agent session spans many worktrees. Reclaim only this worktree or identities whose worktree directory is gone; report, never kill, the unattributable — no global prune. `references/runners.md` owns the contract. ## Test-infrastructure composition Test groups join a shared instance by default. Select distinct instances to isolate parallel shards or to avoid one group's teardown affecting another's fixtures. Declare Docker-backed tests as such so CI can gate on the daemon being present. ## Where this stops Remote environments and IaC are `cmk:infra`'s; CI composition is `cmk:cicd`'s; an attested boundary is `cmk:enclave`'s. Local materializes the same package without TEE evidence, never a raw-env fork. Local is a profile of the same production-quality path, not a second product — it may be the debug or rollout host when those scripts run here. Stay worktree-safe regardless of what the stack mirrors. ## Verify Report-only — never mutate: - `.gitignore` covers `.local/`. - An identity derivation exists and is worktree-deterministic (same inputs → same identity, no hidden shared state). - No fixed/hardcoded ports appear in stack configs — all derive from the worktree identity or a broker. - A coherence guard exists and runs on the init path before anything starts. - No env file references another worktree's absolute path. - Each stack's state root lives under `.local/`, not elsewhere. - Started resources carry the identity stamp; reclaim attributes strays by stamp, never ancestry, scoped to one worktree or deleted-worktree identities.
Files in this package (5)
- SKILL.md 7 KB
- eval.json 9 KB
- references/identity-and-coherence.md 6 KB
- references/instance-primitive.md 5 KB
- references/runners.md 7 KB
Versions
The database has no other skills named cmk:local-stack.
Database snapshot: 13.11.2026 · package version dc6ee1a64651 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 87worktree-devproxy
Set up and operate a git-worktree parallel web-dev environment behind a shared Traefik proxy — every worktree runs its own docker compose stack, reachable at http://<worktree>.<repo>.localhost:8000 by Host-header routing, with zero host-port publishing, zero DNS, zero TLS, zero… - 100devstack
Per-worktree dev environment lifecycle for Mazarbul. USE WHEN user says "start the stack", "spin up devstack", "bring it up", "start the dev environment", "is the stack running", "shut it down", "tear it down", "what's running", "create a new worktree for X", "clean up old… - 100ywc-docker-isolate
(ywc) Use when parallel Git worktrees each run their own Docker stack and collide on host ports ("port is already allocated") — derives a deterministic per-worktree host-port block + COMPOSE_PROJECT_NAME, tears down only that worktree's stack, and audits stale stacks. Delegated… - 100harper-local-dev
Guidelines for running Harper on a developer machine, covering isolated dev instances, parallel instances across git worktrees, loopback address allocation, and per-instance data roots. Triggers on tasks involving local Harper dev servers, running several Harper instances at… - 90openrag_dev_stack
Start, monitor, restart, or stop the local OpenRAG dev stack (Docker infra + host backend + host frontend). Use when the user says "start the dev stack", "run the app locally", "restart the backend/frontend", "factory-reset", "is the stack up?", or asks to bring services up/down… - 90local-dev-environment
Start, stop, or check status of local dev environment using Podman Compose. Database, app services, migrations, health checks. Use when user says "start local env", "podman compose up", "dev environment status".