@rashidee/co2 1.2.5

package/plugin/skills/tracegen-matrix/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: tracegen-matrix
+model: claude-sonnet-4-6
+effort: medium
+description: >
+  Requirement-to-code traceability generator — links every PRD requirement ID (User Stories,
+  Non-Functional Requirements, Constraints) and bug code from a module's SPEC.md to the source
+  code that implements it, and writes a per-application context/TRACEABILITY.md matrix. Resolves
+  links primarily from the in-source CO2 traceability comments written by conductor-feature-develop
+  and conductor-defect (e.g. `Implements: USHM00003`, `Bug fixes: [BUG-024]`), with a name-based
+  source-scan fallback, and OPTIONAL precision enrichment from the codebase-memory knowledge graph
+  when that MCP server is installed. Works fully WITHOUT codebase-memory. Takes an application name
+  (mandatory), with optional version and module filters. Use when the user asks to "generate
+  traceability", "update the traceability matrix", "link requirements to code", "regenerate
+  TRACEABILITY.md", or when invoked as a sub-step by the feature/defect conductors after code or
+  bug-fix changes.
+---
+
+# Tracegen — Traceability Matrix
+
+Generate / update `<app_folder>/context/TRACEABILITY.md` — a per-application matrix linking every
+PRD requirement ID (and bug code) to the source code that implements it. Two layers per module:
+**module-level** (every ID of a module → that module's implementing code, complete coverage) and
+**symbol-level** (specific ID → the specific file/symbol that implements it, where derivable).
+
+This skill is **codebase-memory-OPTIONAL**. It resolves links from in-source traceability comments
+and source scanning, and only uses the codebase-memory MCP for extra precision when present. It must
+NEVER fail or produce an empty file just because codebase-memory is not installed.
+
+## When to Use This Skill
+
+- Automatically, as the final traceability step of `conductor-feature-develop` (after all modules
+  for a version are implemented) and `conductor-defect` (after all bugs for a version are fixed).
+- Manually, when a user asks to (re)generate or refresh the traceability matrix for an application.
+
+## Prerequisites
+
+- `<app_folder>/context/PRD.md` — tagged requirement IDs (run `util-ustagger` first if untagged).
+- `<app_folder>/context/specification/<module>/SPEC.md` — per-module specs with a Traceability
+  section listing the module's requirement IDs (and, for backends, the implementing package).
+- Application source code under `<app_folder>/` (or the resolved `source:` path). If no source code
+  exists yet, the skill still produces a forward-traceability stub (see Workflow step 6c).
+
+## Version Gate
+
+Before starting any work, resolve the application folder first (see Input Resolution), then check
+`CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
+
+1. If `<app_folder>/CHANGELOG.md` does not exist, skip this check (first-ever execution).
+2. If it exists, scan all `## vX.Y.Z` headings and determine the **highest version** via semantic
+   version comparison.
+3. If a `version:` argument was provided and the requested version **<** highest version → **STOP
+   immediately**. Print: `"Version {requested} is lower than the current application version
+   {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."`
+4. If no `version:` argument was provided (regenerating against the current state), skip the gate.
+
+## Input Resolution
+
+```
+/tracegen-matrix <application> [version:<version>] [module:<module>] [source:<source-code-path>]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<application>` | Yes | Application name OR an already-resolved `<app_folder>` path. Matched against root-level application folders. |
+| `version:<version>` | No | Single version (e.g. `version:v1.2.0`). Used for the Version Gate and to label the changelog row and the file header. Does NOT filter which IDs are linked — the matrix always reflects the full current PRD + code. |
+| `module:<module>` | No | If provided, (re)generate ONLY that module's section in TRACEABILITY.md, preserving all other sections. If omitted, regenerate the whole file. |
+| `source:<path>` | No | Path where source code resides. Defaults to `<app_folder>` (same convention as the conductors). |
+
+### Application Folder Resolution
+
+1. If `<application>` is already a path to an existing folder containing a `context/` subfolder,
+   use it directly as `<app_folder>` (this is how the conductors pass it).
+2. Otherwise, list root-level application folders; strip any leading `<number>_` prefix; match the
+   provided name case-insensitively (accept snake_case, kebab-case, or title-case).
+3. If no match is found, list available applications and **stop**.
+
+### Auto-Resolved Paths
+
+| Item | Resolved Path |
+|------|---------------|
+| PRD.md | `<app_folder>/context/PRD.md` |
+| Specifications | `<app_folder>/context/specification/<module>/SPEC.md` |
+| Develop tracking | `<app_folder>/context/develop/<module>/IMPLEMENTATION_MODULE.md` |
+| Source code | `<source-code-path>/` (defaults to `<app_folder>/`) |
+| Output | `<app_folder>/context/TRACEABILITY.md` |
+
+## Resolution Strategy (codebase-memory is OPTIONAL)
+
+Pick code references for each requirement ID using the following cascade. Combine the layers — do
+not stop at the first that yields a hit.
+
+1. **In-source traceability comments (PRIMARY — no MCP, deterministic).**
+   `conductor-feature-develop` stamps every source file it creates with a top-of-file comment
+   listing the requirement codes it implements, and `conductor-defect` appends bug codes:
+   ```
+   Implements: USHM00003, USHM00006
+   NFR: NFRHM0003
+   Constraints: CONSHM003
+   Bug fixes: [BUG-024]
+   ```
+   For each requirement / bug code, scan the source tree for that exact code. Every file whose
+   top-of-file comment contains the code is an implementer of it. Map file → symbol using the
+   primary declared type/function in that file (class/interface/component name, usually = filename).
+   - Recommended scan: ripgrep over source files, excluding `context/`, build output, dependencies,
+     and tests — e.g. search the codes within the first ~20 lines / comment blocks of each file.
+
+2. **Name-based source scan (FALLBACK — no MCP).**
+   When a module's IDs produce NO comment hits (e.g. legacy code authored before the traceability-
+   comment rule, as in pre-existing applications), resolve at module granularity instead:
+   - Backend: read the module's `SPEC.md` `Package` (e.g. `my.app.module.foo`) and locate the
+     matching source directory; collect its controller / service / repository / entity / mapper /
+     DTO files.
+   - Frontend: read the module's `SPEC.md` named pages/components/hooks/api and `Mockup Screens`,
+     then locate the matching source files by name under the app's `src/`.
+   Every ID of the module links to this resolved set (module-level layer).
+
+3. **codebase-memory enrichment (OPTIONAL — only if the MCP is installed).**
+   If the `codebase-memory` MCP tools (`search_graph`, `search_code`) are available in this session,
+   resolve each matched file to its exact graph `qualified_name` for precise, navigable anchors, and
+   use the graph to discover additional same-module symbols. If the MCP is NOT available, skip this
+   step entirely and use **file-path references** instead (see Reference Format). The matrix content
+   and structure are identical either way; only the anchor precision differs.
+
+**Hard rule:** never invent a reference. A reference must come from a real comment hit, a real
+source file located on disk, or (when present) a real codebase-memory node. If a specific symbol
+cannot be resolved, leave the symbol-level cell as `—`; the module-level layer still covers it.
+
+### Reference Format
+
+- **codebase-memory present** → use the full graph `qualified_name` (exact node anchor).
+- **codebase-memory absent** → use a repo-relative path with optional symbol suffix:
+  `path/to/File.java#ClassName` (or `src/features/foo/pages/FooPage.tsx#FooPage`).
+
+Record which mode was used in the file header so readers know how to interpret the anchors.
+
+## Workflow
+
+1. **Resolve inputs** — application folder, source path, optional version/module (Input Resolution).
+   Apply the Version Gate.
+2. **Detect capabilities** — record: (a) is the codebase-memory MCP available? (b) do source files
+   carry in-source traceability comments? (sample a few known IDs). These two booleans select the
+   active resolution layers and the Reference Format.
+3. **Enumerate modules** — glob `<app_folder>/context/specification/*/SPEC.md`. If `module:` was
+   provided, restrict to that module.
+4. **Extract requirement IDs per module** — from each `SPEC.md` Traceability section: User Story,
+   NFR, and Constraint IDs with their version tags. Also collect the module's `Package` (backend)
+   or named components (frontend), and any `[BUG-XXX]` codes recorded for the module in PRD.md's
+   `### Bug` section. Cross-check `<app_folder>/context/develop/<module>/IMPLEMENTATION_MODULE.md`
+   when present for explicit ID→symbol hints.
+5. **Resolve code references** — apply the Resolution Strategy cascade to build, per module:
+   - the **module-level** set (the module's implementing files/symbols), and
+   - **symbol-level** links for the specific IDs where a comment hit or SPEC/IMPLEMENTATION naming
+     pins a specific file/symbol. Mark symbol-level links inferred when derived from naming rather
+     than an explicit comment hit.
+6. **Write TRACEABILITY.md** using the Output structure below.
+   - a. Whole-file regeneration when no `module:` filter.
+   - b. Single-module update when `module:` is given — replace only that module's `## <Module>`
+     section, preserving every other section and the file header/summary (recompute the summary).
+   - c. If NO source code exists for the app yet, still write the file: list every module's full ID
+     inventory with all symbol cells `—`, plus the module's *intended* SPEC-named symbols as plain
+     (non-anchor) references, and a prominent NOT-YET-IMPLEMENTED banner. This preserves forward
+     traceability and is regenerated to real anchors once code exists.
+7. **Changelog Append** — see below.
+8. **Print a summary** — modules processed, total IDs linked (US/NFR/CON counts), symbol-level link
+   count, resolution mode used (comments / name-based / graph-enriched), and any unresolved IDs.
+
+## Output
+
+A single file: `<app_folder>/context/TRACEABILITY.md`.
+
+```markdown
+# Traceability — <Application Display Name>
+
+> **Purpose**: links every PRD requirement ID (User Stories, NFRs, Constraints) and bug code from
+> `context/PRD.md` + `context/specification/*/SPEC.md` to the source code that implements it.
+> **Resolution mode**: <in-source comments | name-based scan | graph-enriched> — anchors are
+> <codebase-memory qualified_names | repo-relative file paths>.
+> **Two layers**: _module-level_ — every ID of a module maps to that module's implementing code
+> (complete); _symbol-level_ — specific ID → the specific file/symbol where derivable (partial,
+> `(inferred)` when from naming rather than an in-source comment).
+> **Maintenance**: regenerated by `tracegen-matrix` at the end of `conductor-feature-develop` and
+> `conductor-defect`; re-run manually after significant code moves.
+
+---
+
+## <Module Name>  ·  prefix `<PFX>`  ·  package `<package or n/a>`
+
+**Module-level code** (every ID below maps to these):
+- `<reference>` — <role e.g. Controller / Page>
+- `<reference>` — <role e.g. ServiceImpl / Hook>
+- …
+
+**Requirement links:**
+
+| ID | Type | Ver | Symbol-level implementation |
+|----|------|-----|-----------------------------|
+| USHM00003 | US | v1.0.0 | `<reference>` |
+| NFRHM0003 | NFR | v1.0.0 | — |
+| CONSHM003 | CON | v1.0.0 | `<reference>` (inferred) |
+| BUG-024 | BUG | v1.0.1 | `<reference>` |
+
+---
+
+(repeat per module)
+
+## Summary
+- Modules: <N>
+- IDs linked: <N> (US <a>, NFR <b>, CON <c>, BUG <d>)
+- Symbol-level links: <N>
+- Resolution mode: <comments | name-based | graph-enriched>
+- Unresolved: <short list or "none">
+```
+
+Type abbreviations: US = User Story, NFR = Non-Functional Requirement, CON = Constraint, BUG = bug
+fix code.
+
+## Changelog Append
+
+After the matrix is successfully written, append an entry to `<app_folder>/CHANGELOG.md`:
+
+1. If `<app_folder>/CHANGELOG.md` does not exist, create it with the standard CO2 changelog header.
+2. Determine the version label: the `version:` argument if provided, else the highest version in
+   the changelog, else `v1.0.0`.
+3. Search for a `## {version}` heading. If it exists, append a new row; if not, insert a new section
+   after the `---` below the header and before any existing `## vX.Y.Z` section (newest-first).
+4. Row format: `| {YYYY-MM-DD} | {application_name} | tracegen-matrix | {module or "All"} | Regenerated TRACEABILITY.md — {N} IDs linked ({fine} symbol-level), mode: {resolution-mode} |`
+5. **Never modify or delete existing rows.**
+
+## Constraints
+
+- **codebase-memory is OPTIONAL.** The skill MUST complete and produce a useful TRACEABILITY.md
+  when the codebase-memory MCP is absent, using in-source comments and source scanning. Treat the
+  graph purely as an enrichment for anchor precision.
+- **Never fabricate a reference.** Every anchor must trace to a real in-source comment, a real file
+  on disk, or a real graph node. Unresolved symbol-level cells are `—`.
+- **Preserve unrelated sections.** With a `module:` filter, only that module's section may change.
+- **Do not modify source code, PRD.md, SPEC.md, or any other artifact.** This skill only writes
+  `TRACEABILITY.md` and appends one `CHANGELOG.md` row.
+- **Preserve requirement tags verbatim.** Use the 9-character `util-ustagger` codes and `[BUG-XXX]`
+  codes exactly as they appear; never reformat or invent codes.
+- **Idempotent.** Re-running with the same inputs reproduces the same matrix (modulo newly added
+  code or requirements).

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

@@ -0,0 +1,422 @@
+---
+name: util-preparek8senv
+model: claude-sonnet-4-6
+effort: medium
+description: >
+  Prepare Kubernetes environment infrastructure by generating K8s manifests for all 3rd party
+  supporting applications for a single target environment defined in CLAUDE.md. Creates/updates
+  ENVIRONMENT.md with per-environment configs and credentials, then generates persistent
+  StatefulSet-based K8s manifests for each 3rd party application (databases, message queues,
+  caches, SSO, API gateways, etc.) directly in the `environment/` folder. Since the
+  `environment/` folder is gitignored, each machine maintains its own independent copy.
+  Ensures all services are remotely accessible using tools from DEVTOOL.md.
+  Trigger on keywords: "prepare k8s environment", "prepare kubernetes", "setup k8s infra",
+  "generate k8s manifests for 3rd party", "prepare environment", "setup infrastructure",
+  "prepare k8s", "init k8s environment", "scaffold k8s environment".
+  Accepts an optional environment argument to select which Kubernetes environment to generate for.
+---
+
+# Util Prepare K8s Environment
+
+Prepare Kubernetes infrastructure by generating K8s manifests for all 3rd party supporting
+applications for a **single target environment**. Manifests are generated directly in the
+`environment/` folder (no per-environment subfolders). Since the `environment/` folder is
+gitignored, each machine maintains its own independent copy of the manifests.
+
+## Input Resolution
+
+This skill accepts an optional `<environment>` argument:
+
+```
+/util-preparek8senv [environment]
+```
+
+| Argument | Required | Example | Description |
+|----------|----------|---------|-------------|
+| `<environment>` | No | `home_server` | Target environment name — must match a Kubernetes environment in CLAUDE.md |
+
+If omitted:
+- If CLAUDE.md defines exactly **one** Kubernetes environment → auto-select it.
+- If CLAUDE.md defines **multiple** Kubernetes environments → list them and ask the user to specify.
+
+The environment name is matched **case-insensitively** against the environment headings in CLAUDE.md, accepting snake_case, kebab-case, or title-case input (e.g., `home_server`, `home-server`, `Home Server` all match `## Home Server`).
+
+All other configuration is read from the project root:
+
+| File | Purpose | Required |
+|------|---------|----------|
+| `CLAUDE.md` | Project detail, environments, 3rd party applications, rules | Yes |
+| `ENVIRONMENT.md` | Per-environment configs and credentials for 3rd party apps | Created if missing |
+| `DEVTOOL.md` | Local development tools (CLI paths for kubectl, mysql, mongosh, etc.) | Yes |
+
+## Workflow
+
+### 1. Parse CLAUDE.md
+
+Read CLAUDE.md from the project root and extract:
+
+- **Project Code**: From `# Project Detail` → Project Code (e.g., `URP`). Used as K8s namespace (lowercase: `urp`).
+- **Environment list**: Each `## <Environment Name>` heading under `# Environment` is an environment. Extract:
+  - Environment name (e.g., "Localhost", "Home Server")
+  - Snake_case identifier for folder name (e.g., `localhost`, `home_server`)
+  - Domain name (e.g., `localhost`, `home.server`) — from the `- Domain:` field
+  - Deployment Type (e.g., `Manual`, `Kubernetes`) — from the `- Deployment Type:` field
+  - Operating system, Kubernetes distribution/version (for Kubernetes environments)
+  - SSH configuration (IP, port) — for remote environments
+  - Kube config reference — if mentioned
+- **3rd Party Application list**: Each `## <Application Name>` heading under `# Supporting 3rd Party Applications`. Extract:
+  - Application name (e.g., "Hub Cache", "Hub Core Database")
+  - Technology and version (e.g., "Redis version 7.2.1", "MongoDB version 7.0.6")
+  - Databases/database names if applicable
+  - Dependencies (`- Depends on:` list)
+- **Credential rules**: From `# Rules` section — standard username/password format for new accounts.
+
+**Stop conditions:**
+- If `# Environment` section is missing or has no environments → stop with error
+- If `# Supporting 3rd Party Applications` section is missing or has no entries → stop with error
+- If `DEVTOOL.md` does not exist → stop with error
+- If no environment has `Deployment Type: Kubernetes` → stop with error: "No Kubernetes environments found in CLAUDE.md. This skill only generates manifests for environments with Deployment Type: Kubernetes."
+
+### 1b. Target Environment Selection
+
+After parsing all environments, identify Kubernetes environments and select the target:
+
+1. Filter environments to those with `Deployment Type: Kubernetes`.
+2. If the user provided an `<environment>` argument, match it against the Kubernetes environments (case-insensitively, accepting snake_case, kebab-case, or title-case).
+   - If matched → use it as the target environment.
+   - If not matched → list available Kubernetes environments and stop.
+3. If no argument was provided:
+   - If exactly **one** Kubernetes environment exists → auto-select it.
+   - If **multiple** exist → list them and ask the user to specify.
+
+The selected environment is the **target environment** used for Step 2 (ENVIRONMENT.md sync) and Step 3 (K8s manifest generation). Only this one environment is processed.
+
+### 2. Sync ENVIRONMENT.md
+
+#### 2a. ENVIRONMENT.md Does Not Exist
+
+Create a new `ENVIRONMENT.md` at the project root using the template structure below.
+
+#### 2b. ENVIRONMENT.md Already Exists
+
+Treat as **append-only**:
+1. Parse the existing ENVIRONMENT.md to identify which environment sections (`# <Environment Name>`) and which service subsections (`## <Service Name>`) exist.
+2. Compare against CLAUDE.md:
+   - **Missing environment section**: Append the entire environment section with all 3rd party app subsections.
+   - **Missing service subsection** under an existing environment: Append the missing service subsection at the end of that environment section.
+   - **Missing config keys** under an existing service: Append the missing key lines with `TODO` placeholder values.
+   - **Existing config keys**: Do **nothing** — leave existing values as-is, even if they differ from defaults.
+3. **Never remove, modify, or reorder** existing sections, headings, or values.
+
+#### 2c. ENVIRONMENT.md Template
+
+```markdown
+# Context
+- This document contains environment-specific variables and credentials for all 3rd party
+  supporting applications used in this project.
+- Organized by environment as defined in CLAUDE.md.
+- **This file must NOT be committed to version control.**
+
+---
+
+# {{Environment Name}}
+{{For localhost:}}
+- Kube Config: `{{path to kube config or TODO}}`
+{{For remote environments:}}
+- SSH Credentials:
+  - Username: `{{username or TODO}}`
+  - Password: `{{password or TODO}}`
+- Kube Config: `{{path to kube config or TODO}}`
+
+## {{3rd Party Application Name}}
+- {{Technology}} version {{version}}
+{{Technology-specific fields — see Section 2d}}
+
+---
+```
+
+#### 2d. Technology-Specific Config Fields
+
+For each 3rd party application, include config fields based on its technology type.
+Use credential rules from CLAUDE.md `# Rules` section for default username/password values.
+Use `TODO` for any value not yet known.
+
+| Technology | Config Fields |
+|-----------|---------------|
+| MongoDB | Host, Port, Username, Password, Databases (list) |
+| MySQL | Host, Port, Username, Password, Databases (list) |
+| Redis | Host, Port, Password, Database Index |
+| RabbitMQ | Host, AMQP Port, Admin Port, Username, Password, Vhost |
+| Keycloak | Host, HTTP Port, Admin Username, Admin Password, Realm, Client IDs |
+| Meilisearch | Host, Port, Master Key |
+| Kong | Proxy Host, Proxy Port, Admin Host, Admin Port |
+| Mailcatcher | SMTP Host, SMTP Port, HTTP Port |
+
+#### 2e. Custom Docker Image Override
+
+Any service in ENVIRONMENT.md may optionally specify a custom Docker image using the `Docker Image`
+field:
+
+- **`Docker Image`**: A Docker image reference (registry, name, and tag).
+  Format: `- Docker Image: <image-reference>`
+  Example: `- Docker Image: gilacode/hub_single_sign_on:26.5.4`
+  The image will be used as-is in the K8s manifest with `imagePullPolicy: IfNotPresent`.
+
+When the `Docker Image` field is not present, the skill falls back to the **official Docker Hub
+image** with the exact version from CLAUDE.md (default behavior).
+
+This field is **per-environment** in ENVIRONMENT.md — one environment may use a custom image
+while another uses the official image. The skill reads the target environment's section.
+
+**Default values:**
+- Host: use the **Domain** from the environment's `- Domain:` field in CLAUDE.md (e.g., `localhost`, `home.server`). If no Domain is specified, fall back to `localhost` for localhost environments or the SSH IP for remote environments. If neither is available, use `TODO`.
+- Ports: technology defaults (MongoDB: `27017`, MySQL: `3306`, Redis: `6379`, RabbitMQ AMQP: `5672`, RabbitMQ Admin: `15672`, Keycloak: `8180`, Meilisearch: `7700`, Kong Proxy: `8000`, Kong Admin: `8001`, Mailcatcher SMTP: `1025`, Mailcatcher HTTP: `1080`)
+- Username/Password: from CLAUDE.md rules section (default: `bestrnd` / `B3st1n3t@2025`), or technology defaults (e.g., RabbitMQ: `guest`/`guest`, MongoDB: no auth)
+
+### 3. Generate K8s Manifests
+
+#### 3a. Ensure Folder Structure
+
+1. Check if `environment/` folder exists at the project root. If not, create it.
+
+Resulting structure (all manifests directly in `environment/`):
+```
+environment/
+  namespace.yaml
+  smtp_server.yaml
+  hub_cache_pvc.yaml
+  hub_cache.yaml
+  hub_core_database_pvc.yaml
+  hub_core_database.yaml
+  ...
+```
+
+#### 3b. Generate Namespace Manifest
+
+Create `environment/namespace.yaml`:
+- Namespace name: project code in lowercase (e.g., `urp`)
+- Identical regardless of environment
+
+#### 3c. Generate PVC Manifests (Separate Files)
+
+For each 3rd party application that requires data persistence (databases, message queues, caches),
+generate a **separate** PVC file: `environment/<service_snake_case>_pvc.yaml`.
+
+**Why separate files:** If the PVC is bundled inside the service manifest, running
+`kubectl delete -f <service>.yaml` followed by `kubectl apply -f <service>.yaml` would delete
+and recreate the PVC, destroying all persisted data. Keeping the PVC in its own file ensures
+that `kubectl delete -f <service>.yaml` only removes the StatefulSet, ConfigMap, Secret, and
+Services — the PVC (and its data) remains untouched.
+
+The PVC file contains only the PersistentVolumeClaim resource:
+
+```yaml
+# ==============================================================================
+# {{Application Name}} ({{Technology}}) — PersistentVolumeClaim
+# ==============================================================================
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{service-name}}-pvc
+  namespace: {{namespace}}
+  labels:
+    app: {{service-name}}
+    project: {{project-code}}
+    environment: {{environment}}
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: {{size — see Section 3d for defaults per technology}}
+```
+
+#### 3d-svc. Generate Per-Service Manifests
+
+For each 3rd party application, generate `environment/<service_snake_case>.yaml` containing a multi-document YAML (separated by `---`) with:
+
+1. **ConfigMap** — non-sensitive configuration (hostnames, ports, database names, vhosts)
+2. **Secret** — sensitive configuration (passwords, admin credentials), base64-encoded. Read actual values from ENVIRONMENT.md for the matching environment.
+3. **StatefulSet** (NOT Deployment) — ensures persistent identity, stable network IDs, and ordered scaling:
+   - **Image resolution** (checked in ENVIRONMENT.md for the target environment — see Section 2e):
+     1. If `Docker Image` is specified → use the exact image reference as-is. Set `imagePullPolicy: IfNotPresent`. Do NOT include `args` or `command` — the custom image's `ENTRYPOINT`/`CMD` handles startup.
+     2. Otherwise → use the official Docker Hub image with the exact version from CLAUDE.md (e.g., `mongo:7.0.6`, `mysql:8.4`). Include `args`/`command` as needed by the technology.
+   - `volumeMounts` referencing the PVC (defined in the separate `_pvc.yaml` file) for data persistence
+   - `env` or `envFrom` referencing ConfigMap and Secret
+   - Resource requests/limits (sensible defaults per technology)
+   - Readiness and liveness probes (technology-appropriate)
+   - `serviceName` matching the headless Service name
+4. **Service** — two services per StatefulSet:
+   - **Headless Service** (`clusterIP: None`) — for StatefulSet stable DNS
+   - **NodePort Service** — for remote access from developer machines and CLI tools.
+     Use a deterministic NodePort assignment strategy to avoid conflicts:
+     - Base port = `30000 + (index * 10)` where index is the service's position in alphabetical order
+     - Map each technology's primary port to the NodePort
+5. **Init containers** (if the service depends on another service):
+   - E.g., Keycloak depends on Hub Support Database — add an init container that waits for MySQL to be ready before starting Keycloak
+
+**Important:** The service manifest must NOT contain the PersistentVolumeClaim. It only references the PVC by `claimName` in the StatefulSet's `volumes` section.
+
+#### 3d. Technology-Specific Manifest Details
+
+**MongoDB:**
+- Image: `mongo:{version}`
+- PVC: 5Gi default
+- Ports: 27017
+- Env: `MONGO_INITDB_ROOT_USERNAME`, `MONGO_INITDB_ROOT_PASSWORD` (from Secret, or skip if no auth)
+- Init script: create databases listed in CLAUDE.md via ConfigMap-mounted init script
+- Probe: `mongosh --eval "db.adminCommand('ping')"`
+
+**MySQL:**
+- Image: `mysql:{version}`
+- PVC: 5Gi default
+- Ports: 3306
+- Env: `MYSQL_ROOT_PASSWORD` (from Secret)
+- Init script: create databases listed in CLAUDE.md via ConfigMap-mounted `/docker-entrypoint-initdb.d/` script
+- Probe: `mysqladmin ping -h localhost`
+
+**Redis:**
+- Image: `redis:{version}`
+- PVC: 1Gi default
+- Ports: 6379
+- Env: `REDIS_PASSWORD` (from Secret, optional — skip if no auth)
+- Probe: `redis-cli ping`
+
+**RabbitMQ:**
+- Image: `rabbitmq:{version}-management` (include management plugin for admin UI)
+- PVC: 2Gi default
+- Ports: 5672 (AMQP), 15672 (Management UI)
+- Env: `RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS`, `RABBITMQ_DEFAULT_VHOST` (from Secret/ConfigMap)
+- Probe: `rabbitmq-diagnostics -q ping`
+
+**Keycloak:**
+- Image resolution: check ENVIRONMENT.md for `Docker Image` first (see Section 2e).
+  - If custom image (e.g., `gilacode/hub_single_sign_on:26.5.4`): use the specified image name; do NOT add `args: ["start-dev"]` (custom image handles startup). Use HTTP Port from ENVIRONMENT.md (typically `8180` for custom builds) for containerPort, probes, and services. Add `KC_HTTP_PORT` to ConfigMap.
+  - If no custom image: `quay.io/keycloak/keycloak:{version}` with `args: ["start-dev"]`. Default port `8080`.
+- PVC: none (stateless — state is in the database)
+- Env: `KC_DB`, `KC_DB_URL`, `KC_DB_USERNAME`, `KC_DB_PASSWORD`, `KC_HEALTH_ENABLED`, `KC_HTTP_ENABLED`, `KC_HOSTNAME_STRICT`, `KC_HTTP_PORT`, `KEYCLOAK_ADMIN`, `KEYCLOAK_ADMIN_PASSWORD` (from Secret/ConfigMap)
+- Init container: wait for MySQL (Hub Support Database) to be ready
+- Probe: HTTP GET `/health/ready` on the configured HTTP port
+
+**Kong API Gateway:**
+- Image: `kong:{version}`
+- PVC: none (stateless — DB-less mode or state in database)
+- Ports: 8000 (Proxy), 8001 (Admin API)
+- Env: `KONG_DATABASE=off`, `KONG_PROXY_LISTEN=0.0.0.0:8000`, `KONG_ADMIN_LISTEN=0.0.0.0:8001`
+- Probe: HTTP GET `/status` on admin port
+
+**Mailcatcher (SMTP):**
+- Image: `schickling/mailcatcher:{version}` or `sj26/mailcatcher:latest` (if specific version unavailable)
+- PVC: none (ephemeral — mail is not persisted)
+- Ports: 1025 (SMTP), 1080 (HTTP UI)
+- Probe: TCP check on port 1025
+
+**Meilisearch:**
+- Image: `getmeili/meilisearch:v{version}`
+- PVC: 2Gi default
+- Ports: 7700
+- Env: `MEILI_MASTER_KEY` (from Secret)
+- Probe: HTTP GET `/health`
+
+#### 3e. Create or Update Logic
+
+For each service, there are up to two files to manage in `environment/`:
+- `<service_snake_case>_pvc.yaml` — PVC file (only for services that require persistence)
+- `<service_snake_case>.yaml` — service manifest (ConfigMap, Secret, StatefulSet, Services)
+
+For each file:
+
+1. **If the file does not exist** (CREATE mode): Generate and write the manifest.
+2. **If it already exists** (UPDATE mode):
+   - Read the existing manifest
+   - Compare against current CLAUDE.md/ENVIRONMENT.md values for the target environment:
+     - Version changed → update image tag
+     - New databases added → update init scripts
+     - Credentials changed in ENVIRONMENT.md → update Secret values
+     - New dependencies → add init containers
+     - Storage size changed → update PVC (in `_pvc.yaml` only)
+   - Preserve any resources marked with `# CUSTOM:` comments
+   - Update only the parts that changed
+   - Log what was changed
+
+#### 3f. Remote Accessibility
+
+All NodePort Services must be accessible from the developer's machine using the CLI tools
+specified in DEVTOOL.md. Include a comment block at the top of each service manifest with
+connection instructions:
+
+```yaml
+# Service: {{Application Name}} ({{Technology}} {{version}})
+# Environment: {{Environment Name}}
+#
+# Connect from local machine:
+#   {{CLI tool from DEVTOOL.md}} {{connection command using NodePort}}
+#
+# Example:
+#   mysql -h {{host}} -P {{nodeport}} -u {{username}} -p{{password}}
+#   mongosh mongodb://{{host}}:{{nodeport}}/{{database}}
+#   rdcli -h {{host}} -p {{nodeport}}
+#   rabbitmqadmin -H {{host}} -P {{nodeport}} list queues
+---
+```
+
+Use the **Domain** from the target environment's `- Domain:` field in CLAUDE.md as host with NodePort (e.g., `localhost`, `home.server`). If no Domain is specified, fall back to `localhost` for localhost environments or the SSH IP for remote environments.
+
+### 4. Output Summary
+
+Print a summary of all actions taken:
+
+```
+## K8s Environment Preparation Summary
+
+### Target Environment
+| Environment | Deployment Type | Output Folder |
+|-------------|----------------|---------------|
+| Home Server | Kubernetes | environment/ |
+
+### ENVIRONMENT.md
+| Action | Details |
+|--------|---------|
+| Created/Updated | Synced Home Server environment, 11 services |
+
+### K8s Manifests Generated
+| Service | File | Status |
+|---------|------|--------|
+| SMTP Server | environment/smtp_server.yaml | Created |
+| Hub Cache (PVC) | environment/hub_cache_pvc.yaml | Created |
+| Hub Cache | environment/hub_cache.yaml | Created |
+| Hub Core Database (PVC) | environment/hub_core_database_pvc.yaml | Created |
+| Hub Core Database | environment/hub_core_database.yaml | Created |
+| ... | ... | ... |
+
+### NodePort Assignments
+| Service | Primary Port | NodePort |
+|---------|-------------|----------|
+| HC Adapter Message Queue | 5672 | 30000 |
+| HC Database | 3306 | 30010 |
+| Hub Cache | 6379 | 30020 |
+| Hub Core Database | 27017 | 30030 |
+| Hub Single Sign On | 8180 (custom) / 8080 (official) | 30040 |
+| Hub Support Database | 3306 | 30050 |
+| SC API Gateway | 8000 | 30060 |
+| SC Adapter Message Queue | 5672 | 30070 |
+| SC Database | 3306 | 30080 |
+| SMTP Server | 1025 | 30090 |
+```
+
+## Important Rules
+
+- **NEVER remove, modify, or delete existing values** in ENVIRONMENT.md. Only add missing sections, services, and config keys.
+- **StatefulSet over Deployment** — all 3rd party services use StatefulSet to ensure persistent identity, stable network IDs, and data persistence across pod restarts.
+- **PersistentVolumeClaim in separate files** — PVCs MUST be generated in their own `<service>_pvc.yaml` files, never bundled inside the service manifest. This prevents accidental data loss when recreating services with `kubectl delete -f` / `kubectl apply -f`. The service manifest references the PVC by `claimName` only.
+- **PersistentVolumeClaim** is mandatory for any service that stores data (databases, message queues, caches). Ephemeral services (Mailcatcher, Kong DB-less) are exempt.
+- **NodePort for remote access** — every service must have a NodePort Service so developers can connect using local CLI tools from DEVTOOL.md.
+- **Deterministic NodePort assignment** — use alphabetical ordering of service names to assign NodePorts starting from 30000 with interval of 10. This ensures consistent ports across environments and avoids conflicts.
+- **Init containers for dependencies** — if a 3rd party app depends on another (e.g., Keycloak → MySQL), add an init container that waits for the dependency to be ready.
+- **Image resolution precedence** — for each service, check ENVIRONMENT.md for the target environment's `Docker Image` field first (see Section 2e). If present, use the exact image reference with `imagePullPolicy: IfNotPresent` and do not add `args`/`command`. If absent, fall back to the official Docker Hub image with the exact version from CLAUDE.md (never use `latest`).
+- **Namespace isolation** — all manifests use the project namespace (project code lowercase). The namespace manifest is generated once.
+- **Credential rules from CLAUDE.md** — when generating default credentials for new services, follow the `# Rules` section in CLAUDE.md for standard username/password format.
+- **Idempotent execution** — safe to re-run. Existing manifests are updated only where values changed. Manual customizations marked with `# CUSTOM:` are preserved.
+- **ENVIRONMENT.md is the credential source** — K8s Secret values come from ENVIRONMENT.md, not hardcoded. If a value is `TODO` in ENVIRONMENT.md, use `TODO` (base64-encoded) in the Secret and log a warning.
+- This skill only generates manifests for **3rd party supporting applications** — NOT for custom applications (those are handled by `depgen-k8s`).