Cabloy Worktree Environment

Cabloy Worktree Environment

Use this skill only for explicit, user-controlled setup of the standard local runtime environment in an already-created linked Git worktree.

Goals

1. validate that the current checkout is a linked Cabloy Basic or Cabloy Start worktree before any write
2. generate a deterministic, secret-safe core environment tuple from Git worktree metadata and fixed port baselines
3. never read, parse, source, expand, display, log, or send .env* file contents to the model
4. write only a new or empty vona/env/.env.local and zova/env/.env.local in the current worktree after explicit confirmation
5. keep Admin and Web as alternative runtime commands that share one generated Zova configuration
6. keep npm run init a separate, opt-in decision

Step 1: Validate the current checkout and edition

Before proposing configuration values or writing files:

1. resolve the current absolute Git top-level directory
2. run git worktree list --porcelain -z and parse its NUL-delimited records without shell word splitting
3. verify that the current root is registered
4. compare absolute git-dir and git-common-dir; equal paths identify the primary checkout, which this skill must reject
5. detect exactly one edition marker at the resolved root
6. verify that vona/env/, zova/env/, and the required root scripts exist

Interpretation:

Stop without edits when both markers are present, neither marker is present, the checkout is primary/unregistered, required environment directories are missing, or the selected edition's required scripts are unavailable.

Read Parallel Worktree Environment as the canonical shared recipe. Edition detection chooses command names and labels; it does not change the two-file environment model. Never change committed defaults, including vona/env/.env and zova/env/.env.

Step 2: Generate the standard environment recommendation

After validation, immediately generate the standard core tuple. Do not ask which processes the user intends to run and do not ask them to select Admin or Web.

For user-facing summaries, write exactly:

Environment isolation: Vona development + Zova development

Admin and Web use this same Zova environment. The user may later run either frontend command, but must not run both concurrently in one worktree. Use another linked worktree for concurrent development of the other flavor. Do not create a flavor-specific local override.

Secret-safe input boundary

Recommendation generation uses Git worktree metadata and the fixed constants below only. It must not inspect any .env, .env.local, .env.*.local, sibling worktree configuration, process environment, listener table, lsof output, process command line, or external service. Do not use Read, cat, grep, source, dotenv, printenv, env, or diagnostics that expose env-file content for this workflow.

This means the proposal is deterministic convenience, not a live port reservation. If an application later reports a port collision, the user may say “Try another batch” before setup or create another linked worktree; the actual application bind remains authoritative.

Deterministic proposal

Treat the primary checkout as ordinal 0. From the validated git worktree list --porcelain -z order, assign each linked worktree the next ordinal: the first linked worktree is 1, the second is 2, and so on. Let batch be 0 for the first proposal, and increase it only when the user says “Try another batch”.

Use one shared offset for every generated listener:

offset = linkedWorktreeOrdinal + batch

Use these fixed baseline ports, which match the committed Cabloy defaults:

Set APP_NAME to the basename of the validated current worktree root. Do not inspect other worktrees’ configurations or append an env-derived suffix. Stop if that basename is empty or cannot be used as an application name without altering it; ask the user to rename/recreate the linked worktree instead.

Always recommend both local files:

# vona/env/.env.local
APP_NAME = <worktree-basename>
SERVER_LISTEN_PORT = <7102 + offset>

# zova/env/.env.local
APP_NAME = <worktree-basename>
API_BASE_URL = http://localhost:<recommended SERVER_LISTEN_PORT>
DEV_SERVER_PORT = <9000 + offset>
DEV_SERVER_HMR_PORT = <24679 + offset>

All generated listener ports must be integers from 1 through 65535 and distinct within the tuple. If a batch would exceed that range, stop and require a different linked-worktree arrangement.

When the user says “Try another batch”, set batch = batch + 1, recompute the entire tuple, and show it again. Every recommended listener advances by exactly +1, and API_BASE_URL is regenerated from the new Vona port. Do not write during a batch change. This deterministic setup does not accept user-substituted values.

A unique APP_NAME separates ordinary framework-managed test database names and framework Redis prefixes. It does not isolate explicitly named databases, unprefixed custom Redis keys, mail, payment, webhooks, object storage, or other external services. Require a separate explicit design before claiming that any of those resources are isolated.

Step 3: Preview and confirm the write

Before making any edit:

1. show Environment isolation: Vona development + Zova development, the worktree ordinal, batch, and exact non-secret identity/port tuple
2. show a file-by-file preview containing only the managed assignments that will be written to both broad local files
3. run one independent git check-ignore -v -- "$target" command for each target and require each command to succeed with a matching ignore rule
4. recheck current root, linked-worktree identity, edition, ordinal, generated port range, tuple uniqueness, and both target states
5. ask for a final affirmative confirmation that includes the proposed identity and port tuple

Do not treat silence as confirmation.