@rashidee/co2 1.3.17 → 1.3.19

package/plugin/skills/util-plancicd/SKILL.md

@@ -1,312 +1,319 @@
----
-name: util-plancicd
-model: claude-opus-4-8
-effort: high
-description: >
-  Infer a local-deployment plan for every custom application of a CO2 project and write it to
-  cicd/CICD_PLAN.md for human review in Compound Context Studio. Reads the project's
-  ENVIRONMENT.md and DEVTOOL.md, CLAUDE.md (# Custom Applications, # Port Allocation) and each
-  application's context/specification/SPECIFICATION.md, then decides per application: deployment
-  method (container vs bare process), build command (e.g. Spring Boot jar vs Docker image),
-  start command, stop mechanism, deploy method + command (none / web-server copy / docker run /
-  kubectl apply — only when the environment calls for one), port and health-check URL, plus a
-  port for the generated CI/CD app itself. When Docker AND a docker repo/registry are both
-  configured (DEVTOOL.md + ENVIRONMENT.md), it additionally plans the docker-image build path:
-  per-application image names under the repo, Build commands extended with
-  `docker build -t <image>:{VERSION}` (the {VERSION} token is auto-resolved by the generated
-  CI/CD app to the project's current version), and a managed Dockerfile authored into the plan's
-  `## Dockerfiles` section for any dockerized application lacking one (materialized before
-  Build, never overwriting an existing file). It also infers each application's RUNTIME CONFIG — the
-  config files its start command reads (e.g. `.env`), deciding per file whether the values come
-  from ENVIRONMENT.md or from an existing `.env` / `.env-*` file already in the app folder, listing
-  the required keys and, for ENVIRONMENT.md-sourced files, the resolved content — so the generated
-  CI/CD app can complete the config before start (guaranteeing the app comes up) and show it in a
-  per-application Config modal for troubleshooting. It also enumerates the project's supporting
-  infrastructure (3rd-party services from CLAUDE.md's `# Supporting 3rd Party Applications` and
-  ENVIRONMENT.md — host, port and optional console URL) into an `## Infrastructure` section so
-  the generated CI/CD app can surface a status-only Infrastructure page. The plan carries a
-  top-level
-  `**Status**: IN PROGRESS` header flipped to `COMPLETED` when done — the studio's watcher reads
-  it. This skill NEVER generates the CI/CD app (that is util-gencicdscript, which runs only
-  after the studio stamps an **Approved**: line into the plan). Trigger on keywords: "plan
-  cicd", "plan deployment", "cicd plan", "infer deployment", "deployment plan", "plan ci/cd".
-  Accepts one MANDATORY argument: the project-relative path of the plan-request markdown the
-  studio generated (e.g., /util-plancicd execution/cicd-plan-3-1753000000000.md).
----
-
-# Util Plan CI/CD
-
-## Inputs
-
-```
-/util-plancicd <path-to-plan-request-md>
-```
-
-| Argument | Required | Description |
-|---|---|---|
-| path | yes | Project-relative path of the studio-generated plan-request markdown under `execution/` |
-
-If the argument is missing or the file does not exist, STOP and tell the user to click
-**Plan deployment** in the studio's CI/CD screen first.
-
-### Auto-Resolved Paths
-
-| Logical file | Path |
-|---|---|
-| Plan request | `<argument>` |
-| Environment | `ENVIRONMENT.md` (project root) |
-| Dev tools | `DEVTOOL.md` (project root) |
-| Project context | `CLAUDE.md` (project root; `source/CLAUDE.md` fallback) |
-| App specification | `<app_folder>/context/specification/SPECIFICATION.md` |
-| App config files | `<app_folder>/.env`, `<app_folder>/.env-*` (and stack-conventional config files) |
-| Infrastructure | `CLAUDE.md` `# Supporting 3rd Party Applications` + `ENVIRONMENT.md` |
-| Output plan | `cicd/CICD_PLAN.md` |
-
-## Phase 1 — Gather
-
-1. Read the plan-request markdown; its `## Applications` list is the authoritative application set.
-2. Read `ENVIRONMENT.md` (registries, credentials, external services) and `DEVTOOL.md`
-   (installed tools + paths: node/pnpm/docker/kubectl/python versions).
-2a. **Docker facts**: record whether Docker is installed (DEVTOOL.md) AND whether
-   ENVIRONMENT.md names a **docker repo/registry** — a registry URL or namespace the images
-   are tagged for (e.g. `registry.example.com/team`, a Docker Hub org, an ECR/GCR path).
-   The docker-image build path (below) activates ONLY when BOTH are present; Docker without
-   a configured repo keeps today's behavior (no image builds).
-3. Read `CLAUDE.md`: `# Custom Applications` (folder names, Depends on), `# Port Allocation`
-   (per-application ports), and `# Supporting 3rd Party Applications` (the infrastructure the
-   applications depend on — databases, caches, object storage, SSO, mail, message brokers, etc.).
-4. For each application, read its SPECIFICATION.md tech-stack section if present; otherwise
-   infer the stack from build files (`package.json` → node, `pom.xml` → spring-boot,
-   `composer.json` → laravel).
-4a. For each application, discover its RUNTIME CONFIG files: list any existing `.env` / `.env-*`
-   in the application folder AND the stack-conventional config the start command reads (node/
-   laravel → `.env`; Spring Boot → `application.properties` / `application-<profile>.yml` or a
-   `.env` when the app loads one). Read the content of each existing file (values may be reused).
-   Cross-reference ENVIRONMENT.md for the per-application config values (DB/cache/broker hosts and
-   ports, external-service URLs, credentials, secrets, the app's own PORT) and the Infrastructure
-   list from step 5 for the hosts/ports the app must point at.
-5. Build the **infrastructure list**: one entry per supporting 3rd-party service the project
-   declares. For each, resolve `host` (default `127.0.0.1`), `port` and — when it exposes a web
-   console/UI — a `url`, cross-referencing ENVIRONMENT.md for the actual host/port/endpoint. A
-   service with no host:port to probe (or a purely external SaaS with no local endpoint) is
-   omitted. If the project declares no supporting 3rd-party services, the infrastructure list is
-   empty and the plan's `## Infrastructure` section is written empty.
-
-## Phase 2 — Decide (per application)
-
-- **Working directory (CRITICAL)**: the generated CI/CD app executes every command with the
-  **application folder** (`<project>/<folder>`) as its working directory — NEVER the project
-  root. All paths inside build/start/stop/deploy commands must therefore be relative to the
-  application folder (`mvn -q package`, `java -jar target\app.jar`) — never prefixed with the
-  application folder itself (`skolafund_middleware\target\...` is WRONG).
-- **Method**: `container` only when Docker appears in DEVTOOL.md AND the stack has a sensible
-  container path; otherwise `process` (bare local process — the default for a dev VM).
-- **Build command**: from the stack (e.g. `pnpm install && pnpm build`, `mvn -q package`,
-  `composer install`). Use tool paths from DEVTOOL.md when the tool is not on PATH.
-- **Start command**: the stack's production-ish local start (e.g. `node dist/index.js`,
-  `java -jar target/<artifact>.jar`, `php artisan serve --port <port>`); `docker build`/
-  `docker run` pair when method=container. For jar-based stacks, resolve the EXACT artifact
-  filename — read the pom/gradle build config: a Maven `<finalName>` means
-  `target/<finalName>.jar` with NO version suffix (Spring Boot repackage keeps that name and
-  leaves a `.jar.original` beside it — never reference the `.original`). Never guess
-  `<app>-<version>.jar` and never use a `target/*.jar` glob (shell-dependent, breaks on
-  Windows cmd).
-- **Stop**: `process-kill` for bare processes; `docker stop <name>` for containers.
-- **Deploy** (method + command): only when ENVIRONMENT.md/DEVTOOL.md show a deployment target —
-  `kubernetes` (`kubectl apply -f <app>/k8s/` when kubectl + a cluster/kubeconfig appear),
-  `docker` (`docker run`/`docker compose up -d` when the image is the deliverable),
-  `web-server` (copy the built artifact into the configured web/app server, e.g. nginx html
-  root or Tomcat webapps, when one is configured). Default **`none`** — a bare local process
-  needs no deploy step beyond Start; never invent a target the config does not name.
-- **Docker image** (only when Gather 2a found Docker + a docker repo — otherwise skip this
-  bullet entirely):
-  - **Image name**: `<repo>/<app_folder>` — the application folder name, lowercased, with
-    any character docker rejects replaced by `-` (keep a leading `<number>_` prefix as-is;
-    e.g. `registry.example.com/team/skolafund_web`).
-  - **Build**: append the image build to the app build —
-    `<app build> && docker build -t <image>:{VERSION} .` The literal `{VERSION}` token is
-    the contract: the generated CI/CD app substitutes the project's CURRENT version
-    (semver without the `v` prefix; `latest` fallback) into commands at execution time —
-    there is no user-facing version selector; only the current codebase is ever built.
-    Build never pushes — pushing belongs to a `docker` Deploy method.
-  - **Container start/deploy**: when method=container, reference `<image>:{VERSION}` in the
-    start/deploy commands too, so the current version's tag is what runs.
-  - **Dockerfile**: if the application folder already has a `Dockerfile`, use it as-is
-    (`existing`). Otherwise author a stack-appropriate Dockerfile (node / spring-boot /
-    laravel — same stack detection as depgen-k8s) into the plan's `## Dockerfiles` section
-    (`managed`); the generated CI/CD app materializes it before Build only when the file is
-    still missing on disk.
-- **Port**: from `# Port Allocation`; if absent, assign sequentially from 3000 avoiding
-  collisions with the studio (3001) and the CI/CD app port.
-- **Health / running-detection**: the endpoint the generated CI/CD app uses to tell whether the
-  application is already running. Detection is a **raw TCP connect to the app's port on loopback**
-  — the generated app probes BOTH IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback, plus the host
-  named in this Health value — so it does not matter which family the framework binds. This
-  matters because dev servers differ: Spring Boot binds `127.0.0.1`, but **Vite / Next preview
-  servers bind IPv6 `::1` (localhost) only** and are invisible to an IPv4-only probe. Therefore
-  set the Health host to **`localhost`** (not `127.0.0.1`) for any Node/Vite/Next dev-server app
-  so the detection host set includes the interface it actually binds; use `127.0.0.1` for JVM
-  apps. Value form: `http://localhost:<port>/` or a documented health path from the spec (the
-  path is informational — detection keys on the port, not the path).
-- **CI/CD app port**: 5000 unless taken in `# Port Allocation`; record it in the plan.
-
-### Application config (per application)
-
-Decide the runtime config the application needs so it STARTS SUCCESSFULLY, and where each value
-comes from. For every config file the start command reads (`path`, relative to the application
-folder):
-
-- **source** — classify each file:
-  - `env-file` — an existing `.env` / `.env-*` in the app folder already holds the runtime values;
-    use it as-is on disk (do NOT re-materialize it). Set `managed: no`, no resolved content.
-  - `environment` — there is no complete runtime file; resolve the required values from
-    ENVIRONMENT.md (and the Infrastructure hosts/ports) and record the fully-resolved file content.
-    Set `managed: yes` so the CI/CD app writes it before Build/Start when missing.
-  - `derived` — the runtime file is chosen/combined from existing material (e.g. copy the target
-    env's `.env-<env>` to the canonical `.env` the start command reads, or merge an existing
-    `.env-*` with ENVIRONMENT.md values). Set `managed: yes` and record the resolved content.
-- **required keys** — enumerate every key the app must have to boot: its own PORT, datastore/cache/
-  broker connection strings, external-service URLs, credentials/secrets. Cross-check them against
-  ENVIRONMENT.md and the Infrastructure list.
-- **completeness (the point of this)** — every required key MUST be satisfiable from ENVIRONMENT.md
-  or an existing env file. If a required key cannot be resolved, still emit the config entry but
-  call out the unresolved key in that application's Rationale as a GAP (so the human fixes
-  ENVIRONMENT.md before approving) — never silently drop it.
-- **managed content** — for a `managed: yes` file, write the resolved body verbatim into the plan
-  as a fenced block (`path=<file>`). Values (including credentials) are emitted verbatim under the
-  dev-environment plaintext rule; they must never appear in the Rationale narrative.
-
-Only list files the app actually reads at runtime — do not invent config files. An app that needs
-no config file gets an empty config list.
-
-### Infrastructure (status-only)
-
-Supporting 3rd-party services are **not** built/started/deployed by the CI/CD app — they are
-surfaced status-only. For each service resolved in Gather step 5, decide:
-
-- **id**: a stable kebab-case key unique within the plan (e.g. `postgres-main`, `keycloak`).
-- **name**: display name (e.g. `PostgreSQL (skf_main)`, `Keycloak`).
-- **host** / **port**: the address the CI/CD app TCP-probes for reachability; default host
-  `127.0.0.1`. Use the values ENVIRONMENT.md documents.
-- **url**: the web console/UI opened in a new tab, when the service has one (Keycloak admin,
-  MinIO console, Mailcatcher inbox); `-` for headless services (PostgreSQL, Redis).
-- **description**: a short blurb (e.g. `Shared app database`, `S3-compatible object storage`).
-
-Never emit credentials into the infrastructure entries — status and links only.
-
-## Phase 3 — Write the plan
-
-Create `cicd/` if missing and write `cicd/CICD_PLAN.md` (shown here in a 4-backtick fence so the
-inner ```env config block renders — the plan file itself uses a normal 3-backtick env fence):
-
-````markdown
-# CI/CD Deployment Plan — <Project Name>
-
-**Generated**: <ISO date>
-**Status**: IN PROGRESS
-
-## CI/CD App
-
-- **Port**: <port>
-- **Folder**: cicd/app
-
-## Deployment Decisions
-
-| Application | Folder | Method | Port | Build | Start | Stop | Deploy Method | Deploy | Health |
-|---|---|---|---|---|---|---|---|---|---|
-| <name> | <folder> | process|container | <port> | `<cmd>` | `<cmd>` | process-kill|docker stop | none|web-server|docker|kubernetes | `<cmd or ->` | <url> |
-
-> **Running-detection**: the generated CI/CD app determines "is it running?" by a TCP connect to
-> each application's **Port** on both IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback plus the
-> **Health** host — so an app is detected whichever family it binds. Use a `localhost` Health host
-> for Node/Vite/Next apps (they bind IPv6 `::1`) and `127.0.0.1` for JVM apps.
-
-> **`{VERSION}` token**: Build/Start/Deploy commands may contain the literal `{VERSION}`;
-> the generated CI/CD app replaces it with the project's CURRENT version (semver without
-> the `v` prefix, `latest` when unknown) at execution time — no user-facing selector.
-> Used by the docker-image path to tag images; tag-only — the code built is always the
-> working tree.
-
-## Docker
-
-Written only from Gather 2a. When Docker or a docker repo is absent, write the section as:
-`_Not dockerized — Docker and/or a docker repo are not configured in DEVTOOL.md/ENVIRONMENT.md._`
-
-**Registry**: <repo, e.g. `registry.example.com/team`>
-
-| Application | Image | Dockerfile |
-|---|---|---|
-| <name> | `<repo>/<app_folder>` | existing \| managed |
-
-## Dockerfiles
-
-One fenced block per `managed` Dockerfile (omit the section body — `_All Dockerfiles exist._`
-— when every dockerized app already has one; `_Not dockerized._` when the Docker section is
-inactive). The generated CI/CD app writes each body to `<app_folder>/Dockerfile` before Build
-only when the file is missing on disk — an existing Dockerfile is never overwritten.
-
-```dockerfile path=<app_folder>/Dockerfile
-FROM node:22-slim
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --omit=dev
-COPY . .
-EXPOSE <port>
-CMD ["node", "dist/index.js"]
-```
-
-## Application Configs
-
-The runtime config each application needs to START SUCCESSFULLY. The generated CI/CD app writes any
-`managed=yes` file into the application folder before Build/Start when it is missing, and shows
-every file (source, status, required keys, live content) in the per-application Config modal for
-troubleshooting. One table per application; `Path` is relative to the application folder.
-
-### <App Name> (<folder>)
-
-| Path | Source | Managed | Required Keys |
-|---|---|---|---|
-| .env | environment | yes | DATABASE_URL, REDIS_HOST, PORT |
-| .env-uat | env-file | no | DATABASE_URL, REDIS_HOST |
-
-For each `Managed=yes` row, follow it with the resolved file body (verbatim — credentials allowed
-under the dev-plaintext rule):
-
-```env path=.env
-DATABASE_URL=postgres://app:app@127.0.0.1:5432/appdb
-REDIS_HOST=127.0.0.1
-PORT=3000
-```
-
-Omit the fenced block for `env-file` rows (the file is used as-is on disk). If an application needs
-no config file, write `_No runtime config files._` under its heading.
-
-## Infrastructure
-
-Supporting 3rd-party services shown status-only (TCP reachability) on the CI/CD app's
-Infrastructure page. Leave the table body empty when the project declares no supporting services.
-
-| Id | Service | Host | Port | Console URL | Description |
-|---|---|---|---|---|---|
-| <id> | <name> | <host> | <port> | `<url or ->` | <blurb> |
-
-## Rationale
-
-- <per-application: why this method/commands, citing ENVIRONMENT.md/DEVTOOL.md evidence>
-````
-
-Then flip `**Status**: IN PROGRESS` to `**Status**: COMPLETED`. The studio watcher advances
-only on COMPLETED.
-
-## STOP — Hand Back to the Human
-
-Print a one-paragraph summary and STOP. Never invoke util-gencicdscript or any other skill —
-the human reviews and approves the plan in the studio's CI/CD screen first.
-
-## Important Rules
-
-- Never write the CI/CD app; never modify PRD.md/CLAUDE.md/BUG.md.
-- Never delete an existing `**Approved**:` line if re-planning over a previous plan — overwrite
-  the whole file WITHOUT any Approved line (a re-plan always requires fresh approval).
-- Credentials from ENVIRONMENT.md may be referenced in commands verbatim (dev-environment
-  plaintext rule) but never echoed into the Rationale narrative.
+---
+name: util-plancicd
+model: claude-opus-4-8
+effort: high
+description: >
+  Infer a local-deployment plan for every custom application of a CO2 project and write it to
+  cicd/CICD_PLAN.md for human review in Compound Context Studio. Reads the project's
+  ENVIRONMENT.md and DEVTOOL.md, CLAUDE.md (# Custom Applications, # Port Allocation) and each
+  application's context/specification/SPECIFICATION.md, then decides per application: deployment
+  method (container vs bare process), build command (e.g. Spring Boot jar vs Docker image),
+  start command, stop mechanism, deploy method + command (none / web-server copy / docker run /
+  kubectl apply — only when the environment calls for one), port and health-check URL, plus a
+  port for the generated CI/CD app itself. When Docker AND a docker repo/registry are both
+  configured (DEVTOOL.md + ENVIRONMENT.md), it additionally plans the docker-image build path:
+  per-application image names under the repo, Build commands extended with
+  `docker build --no-cache -t <image>:latest` (clean image build, no version token — the generated
+  CI/CD app runs commands verbatim on the current working tree), and a managed Dockerfile authored into the plan's
+  `## Dockerfiles` section for any dockerized application lacking one (materialized before
+  Build, never overwriting an existing file). It also infers each application's RUNTIME CONFIG — the
+  config files its start command reads (e.g. `.env`), deciding per file whether the values come
+  from ENVIRONMENT.md or from an existing `.env` / `.env-*` file already in the app folder, listing
+  the required keys and, for ENVIRONMENT.md-sourced files, the resolved content — so the generated
+  CI/CD app can complete the config before start (guaranteeing the app comes up) and show it in a
+  per-application Config modal for troubleshooting. It also enumerates the project's supporting
+  infrastructure (3rd-party services from CLAUDE.md's `# Supporting 3rd Party Applications` and
+  ENVIRONMENT.md — host, port and optional console URL) into an `## Infrastructure` section so
+  the generated CI/CD app can surface a status-only Infrastructure page. The plan carries a
+  top-level
+  `**Status**: IN PROGRESS` header flipped to `COMPLETED` when done — the studio's watcher reads
+  it. This skill NEVER generates the CI/CD app (that is util-gencicdscript, which runs only
+  after the studio stamps an **Approved**: line into the plan). Trigger on keywords: "plan
+  cicd", "plan deployment", "cicd plan", "infer deployment", "deployment plan", "plan ci/cd".
+  Accepts one MANDATORY argument: the project-relative path of the plan-request markdown the
+  studio generated (e.g., /util-plancicd execution/cicd-plan-3-1753000000000.md).
+---
+
+# Util Plan CI/CD
+
+## Inputs
+
+```
+/util-plancicd <path-to-plan-request-md>
+```
+
+| Argument | Required | Description |
+|---|---|---|
+| path | yes | Project-relative path of the studio-generated plan-request markdown under `execution/` |
+
+If the argument is missing or the file does not exist, STOP and tell the user to click
+**Plan deployment** in the studio's CI/CD screen first.
+
+### Auto-Resolved Paths
+
+| Logical file | Path |
+|---|---|
+| Plan request | `<argument>` |
+| Environment | `ENVIRONMENT.md` (project root) |
+| Dev tools | `DEVTOOL.md` (project root) |
+| Project context | `CLAUDE.md` (project root; `source/CLAUDE.md` fallback) |
+| App specification | `<app_folder>/context/specification/SPECIFICATION.md` |
+| App config files | `<app_folder>/.env`, `<app_folder>/.env-*` (and stack-conventional config files) |
+| Infrastructure | `CLAUDE.md` `# Supporting 3rd Party Applications` + `ENVIRONMENT.md` |
+| Output plan | `cicd/CICD_PLAN.md` |
+
+## Phase 1 — Gather
+
+1. Read the plan-request markdown; its `## Applications` list is the authoritative application set.
+2. Read `ENVIRONMENT.md` (registries, credentials, external services) and `DEVTOOL.md`
+   (installed tools + paths: node/pnpm/docker/kubectl/python versions).
+2a. **Docker facts**: record whether Docker is installed (DEVTOOL.md) AND whether
+   ENVIRONMENT.md names a **docker repo/registry** — a registry URL or namespace the images
+   are tagged for (e.g. `registry.example.com/team`, a Docker Hub org, an ECR/GCR path).
+   The docker-image build path (below) activates ONLY when BOTH are present; Docker without
+   a configured repo keeps today's behavior (no image builds).
+3. Read `CLAUDE.md`: `# Custom Applications` (folder names, Depends on), `# Port Allocation`
+   (per-application ports), and `# Supporting 3rd Party Applications` (the infrastructure the
+   applications depend on — databases, caches, object storage, SSO, mail, message brokers, etc.).
+4. For each application, read its SPECIFICATION.md tech-stack section if present; otherwise
+   infer the stack from build files (`package.json` → node, `pom.xml` → spring-boot,
+   `composer.json` → laravel).
+4a. For each application, discover its RUNTIME CONFIG files: list any existing `.env` / `.env-*`
+   in the application folder AND the stack-conventional config the start command reads (node/
+   laravel → `.env`; Spring Boot → `application.properties` / `application-<profile>.yml` or a
+   `.env` when the app loads one). Read the content of each existing file (values may be reused).
+   Cross-reference ENVIRONMENT.md for the per-application config values (DB/cache/broker hosts and
+   ports, external-service URLs, credentials, secrets, the app's own PORT) and the Infrastructure
+   list from step 5 for the hosts/ports the app must point at.
+5. Build the **infrastructure list**: one entry per supporting 3rd-party service the project
+   declares. For each, resolve `host` (default `127.0.0.1`), `port` and — when it exposes a web
+   console/UI — a `url`, cross-referencing ENVIRONMENT.md for the actual host/port/endpoint. A
+   service with no host:port to probe (or a purely external SaaS with no local endpoint) is
+   omitted. If the project declares no supporting 3rd-party services, the infrastructure list is
+   empty and the plan's `## Infrastructure` section is written empty.
+
+## Phase 2 — Decide (per application)
+
+- **Working directory (CRITICAL)**: the generated CI/CD app executes every command with the
+  **application folder** (`<project>/<folder>`) as its working directory — NEVER the project
+  root. All paths inside build/start/stop/deploy commands must therefore be relative to the
+  application folder (`mvn -q package`, `java -jar target\app.jar`) — never prefixed with the
+  application folder itself (`skolafund_middleware\target\...` is WRONG).
+- **Method**: `container` only when Docker appears in DEVTOOL.md AND the stack has a sensible
+  container path; otherwise `process` (bare local process — the default for a dev VM).
+- **Build command (ALWAYS a CLEAN build)**: the Build button must produce a from-scratch build so
+  no stale artifact from a previous run can ever be started or shipped — use the stack's CLEAN
+  lifecycle, never an incremental one:
+  - Maven → `mvn -q clean package` (never bare `package` — it reuses stale compiled classes in `target/`).
+  - Gradle → `./gradlew clean bootJar` (or `clean build`).
+  - Node (pnpm/npm/yarn) → wipe the build output the Start command runs from, THEN install and build:
+    `rm -rf <outdir> && pnpm install && pnpm build`, where `<outdir>` is the directory the Start
+    artifact lives in (`dist`, `build`, `.next`, `.output`, …). Keep the explicit wipe even when the
+    bundler normally empties its own outDir — it is the guarantee against a stale artifact.
+  - Laravel/PHP with a front-end build → `rm -rf public/build && composer install && npm ci && npm run build`;
+    plain PHP with no build step → `composer install`.
+  Use tool paths from DEVTOOL.md when the tool is not on PATH.
+- **Start command**: the stack's production-ish local start (e.g. `node dist/index.js`,
+  `java -jar target/<artifact>.jar`, `php artisan serve --port <port>`); `docker build`/
+  `docker run` pair when method=container. For jar-based stacks, resolve the EXACT artifact
+  filename — read the pom/gradle build config: a Maven `<finalName>` means
+  `target/<finalName>.jar` with NO version suffix (Spring Boot repackage keeps that name and
+  leaves a `.jar.original` beside it — never reference the `.original`). Never guess
+  `<app>-<version>.jar` and never use a `target/*.jar` glob (shell-dependent, breaks on
+  Windows cmd).
+- **Stop**: `process-kill` for bare processes; `docker stop <name>` for containers.
+- **Deploy** (method + command): only when ENVIRONMENT.md/DEVTOOL.md show a deployment target —
+  `kubernetes` (`kubectl apply -f <app>/k8s/` when kubectl + a cluster/kubeconfig appear),
+  `docker` (`docker run`/`docker compose up -d` when the image is the deliverable),
+  `web-server` (copy the built artifact into the configured web/app server, e.g. nginx html
+  root or Tomcat webapps, when one is configured). Default **`none`** — a bare local process
+  needs no deploy step beyond Start; never invent a target the config does not name.
+- **Docker image** (only when Gather 2a found Docker + a docker repo — otherwise skip this
+  bullet entirely):
+  - **Image name**: `<repo>/<app_folder>` — the application folder name, lowercased, with
+    any character docker rejects replaced by `-` (keep a leading `<number>_` prefix as-is;
+    e.g. `registry.example.com/team/skolafund_web`).
+  - **Build**: append the image build to the app build —
+    `<app build> && docker build --no-cache -t <image>:latest .` — `--no-cache` keeps the image a
+    clean build too, so no stale layer survives. Commands carry NO `{VERSION}` token or
+    any other placeholder — the generated CI/CD app runs them verbatim; only the current
+    working tree is ever built and images are always tagged `latest`.
+    Build never pushes — pushing belongs to a `docker` Deploy method.
+  - **Container start/deploy**: when method=container, reference `<image>:latest` in the
+    start/deploy commands too, so the freshly built tag is what runs.
+  - **Dockerfile**: if the application folder already has a `Dockerfile`, use it as-is
+    (`existing`). Otherwise author a stack-appropriate Dockerfile (node / spring-boot /
+    laravel — same stack detection as depgen-k8s) into the plan's `## Dockerfiles` section
+    (`managed`); the generated CI/CD app materializes it before Build only when the file is
+    still missing on disk.
+- **Port**: from `# Port Allocation`; if absent, assign sequentially from 3000 avoiding
+  collisions with the studio (3001) and the CI/CD app port.
+- **Health / running-detection**: the endpoint the generated CI/CD app uses to tell whether the
+  application is already running. Detection is a **raw TCP connect to the app's port on loopback**
+  — the generated app probes BOTH IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback, plus the host
+  named in this Health value — so it does not matter which family the framework binds. This
+  matters because dev servers differ: Spring Boot binds `127.0.0.1`, but **Vite / Next preview
+  servers bind IPv6 `::1` (localhost) only** and are invisible to an IPv4-only probe. Therefore
+  set the Health host to **`localhost`** (not `127.0.0.1`) for any Node/Vite/Next dev-server app
+  so the detection host set includes the interface it actually binds; use `127.0.0.1` for JVM
+  apps. Value form: `http://localhost:<port>/` or a documented health path from the spec (the
+  path is informational — detection keys on the port, not the path).
+- **CI/CD app port**: 5000 unless taken in `# Port Allocation`; record it in the plan.
+
+### Application config (per application)
+
+Decide the runtime config the application needs so it STARTS SUCCESSFULLY, and where each value
+comes from. For every config file the start command reads (`path`, relative to the application
+folder):
+
+- **source** — classify each file:
+  - `env-file` — an existing `.env` / `.env-*` in the app folder already holds the runtime values;
+    use it as-is on disk (do NOT re-materialize it). Set `managed: no`, no resolved content.
+  - `environment` — there is no complete runtime file; resolve the required values from
+    ENVIRONMENT.md (and the Infrastructure hosts/ports) and record the fully-resolved file content.
+    Set `managed: yes` so the CI/CD app writes it before Build/Start when missing.
+  - `derived` — the runtime file is chosen/combined from existing material (e.g. copy the target
+    env's `.env-<env>` to the canonical `.env` the start command reads, or merge an existing
+    `.env-*` with ENVIRONMENT.md values). Set `managed: yes` and record the resolved content.
+- **required keys** — enumerate every key the app must have to boot: its own PORT, datastore/cache/
+  broker connection strings, external-service URLs, credentials/secrets. Cross-check them against
+  ENVIRONMENT.md and the Infrastructure list.
+- **completeness (the point of this)** — every required key MUST be satisfiable from ENVIRONMENT.md
+  or an existing env file. If a required key cannot be resolved, still emit the config entry but
+  call out the unresolved key in that application's Rationale as a GAP (so the human fixes
+  ENVIRONMENT.md before approving) — never silently drop it.
+- **managed content** — for a `managed: yes` file, write the resolved body verbatim into the plan
+  as a fenced block (`path=<file>`). Values (including credentials) are emitted verbatim under the
+  dev-environment plaintext rule; they must never appear in the Rationale narrative.
+
+Only list files the app actually reads at runtime — do not invent config files. An app that needs
+no config file gets an empty config list.
+
+### Infrastructure (status-only)
+
+Supporting 3rd-party services are **not** built/started/deployed by the CI/CD app — they are
+surfaced status-only. For each service resolved in Gather step 5, decide:
+
+- **id**: a stable kebab-case key unique within the plan (e.g. `postgres-main`, `keycloak`).
+- **name**: display name (e.g. `PostgreSQL (skf_main)`, `Keycloak`).
+- **host** / **port**: the address the CI/CD app TCP-probes for reachability; default host
+  `127.0.0.1`. Use the values ENVIRONMENT.md documents.
+- **url**: the web console/UI opened in a new tab, when the service has one (Keycloak admin,
+  MinIO console, Mailcatcher inbox); `-` for headless services (PostgreSQL, Redis).
+- **description**: a short blurb (e.g. `Shared app database`, `S3-compatible object storage`).
+
+Never emit credentials into the infrastructure entries — status and links only.
+
+## Phase 3 — Write the plan
+
+Create `cicd/` if missing and write `cicd/CICD_PLAN.md` (shown here in a 4-backtick fence so the
+inner ```env config block renders — the plan file itself uses a normal 3-backtick env fence):
+
+````markdown
+# CI/CD Deployment Plan — <Project Name>
+
+**Generated**: <ISO date>
+**Status**: IN PROGRESS
+
+## CI/CD App
+
+- **Port**: <port>
+- **Folder**: cicd/app
+
+## Deployment Decisions
+
+| Application | Folder | Method | Port | Build | Start | Stop | Deploy Method | Deploy | Health |
+|---|---|---|---|---|---|---|---|---|---|
+| <name> | <folder> | process|container | <port> | `<cmd>` | `<cmd>` | process-kill|docker stop | none|web-server|docker|kubernetes | `<cmd or ->` | <url> |
+
+> **Running-detection**: the generated CI/CD app determines "is it running?" by a TCP connect to
+> each application's **Port** on both IPv4 (`127.0.0.1`) and IPv6 (`::1`) loopback plus the
+> **Health** host — so an app is detected whichever family it binds. Use a `localhost` Health host
+> for Node/Vite/Next apps (they bind IPv6 `::1`) and `127.0.0.1` for JVM apps.
+
+## Docker
+
+Written only from Gather 2a. When Docker or a docker repo is absent, write the section as:
+`_Not dockerized — Docker and/or a docker repo are not configured in DEVTOOL.md/ENVIRONMENT.md._`
+
+**Registry**: <repo, e.g. `registry.example.com/team`>
+
+| Application | Image | Dockerfile |
+|---|---|---|
+| <name> | `<repo>/<app_folder>` | existing \| managed |
+
+## Dockerfiles
+
+One fenced block per `managed` Dockerfile (omit the section body — `_All Dockerfiles exist._`
+— when every dockerized app already has one; `_Not dockerized._` when the Docker section is
+inactive). The generated CI/CD app writes each body to `<app_folder>/Dockerfile` before Build
+only when the file is missing on disk — an existing Dockerfile is never overwritten.
+
+```dockerfile path=<app_folder>/Dockerfile
+FROM node:22-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+EXPOSE <port>
+CMD ["node", "dist/index.js"]
+```
+
+## Application Configs
+
+The runtime config each application needs to START SUCCESSFULLY. The generated CI/CD app writes any
+`managed=yes` file into the application folder before Build/Start when it is missing, and shows
+every file (source, status, required keys, live content) in the per-application Config modal for
+troubleshooting. One table per application; `Path` is relative to the application folder.
+
+### <App Name> (<folder>)
+
+| Path | Source | Managed | Required Keys |
+|---|---|---|---|
+| .env | environment | yes | DATABASE_URL, REDIS_HOST, PORT |
+| .env-uat | env-file | no | DATABASE_URL, REDIS_HOST |
+
+For each `Managed=yes` row, follow it with the resolved file body (verbatim — credentials allowed
+under the dev-plaintext rule):
+
+```env path=.env
+DATABASE_URL=postgres://app:app@127.0.0.1:5432/appdb
+REDIS_HOST=127.0.0.1
+PORT=3000
+```
+
+Omit the fenced block for `env-file` rows (the file is used as-is on disk). If an application needs
+no config file, write `_No runtime config files._` under its heading.
+
+## Infrastructure
+
+Supporting 3rd-party services shown status-only (TCP reachability) on the CI/CD app's
+Infrastructure page. Leave the table body empty when the project declares no supporting services.
+
+| Id | Service | Host | Port | Console URL | Description |
+|---|---|---|---|---|---|
+| <id> | <name> | <host> | <port> | `<url or ->` | <blurb> |
+
+## Rationale
+
+- <per-application: why this method/commands, citing ENVIRONMENT.md/DEVTOOL.md evidence>
+````
+
+Then flip `**Status**: IN PROGRESS` to `**Status**: COMPLETED`. The studio watcher advances
+only on COMPLETED.
+
+## STOP — Hand Back to the Human
+
+Print a one-paragraph summary and STOP. Never invoke util-gencicdscript or any other skill —
+the human reviews and approves the plan in the studio's CI/CD screen first.
+
+## Important Rules
+
+- Every Build command is a CLEAN build — clean lifecycle (`mvn clean`, `gradlew clean`), a wiped
+  output dir before a Node/asset build, and `docker build --no-cache` — never an incremental build
+  that could start or ship a stale artifact.
+- Never write the CI/CD app; never modify PRD.md/CLAUDE.md/BUG.md.
+- Never delete an existing `**Approved**:` line if re-planning over a previous plan — overwrite
+  the whole file WITHOUT any Approved line (a re-plan always requires fresh approval).
+- Credentials from ENVIRONMENT.md may be referenced in commands verbatim (dev-environment
+  plaintext rule) but never echoed into the Rationale narrative.