Skip to content
Skills Library
DevOps & cloud · Building & coding

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.

Repository
ai-devkit ↗
Licence
MIT
Last repository change
20.10.2026

Assessment and security

90/ 100Class: good
Format15 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

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

set up local devmake dev worktree-safeadd a local stackport conflicts between worktreesheadless dev moderun services locally for agents/CIclean up dangling servicesport already in use
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

  1. Modes
  2. Model
  3. Peers, not a singleton
  4. Service classes and runners
  5. .local/ convention
  6. Global-state prohibition
  7. Lifecycle discipline
  8. Test-infrastructure composition
  9. Where this stops
  10. Verify
Original SKILL.md headings · 146 lines, 1,014 words
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".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.