cluster-install

cozystack:cluster-install

Work in reasoning mode. Use the phrasing cozystack:cluster-install (not "the skill") in user-facing messages. Announce phase transitions: cozystack:cluster-install Phase N — <name>.

Note on language in this SKILL.md — every operator-facing prompt below is written in English for clarity. At runtime the skill matches the operator's natural language detected from prior conversation messages (or read from <config-dir>/.state.yaml operator_language when the wizard chain is in progress). Code identifiers, commands, file paths, and any text destined for GitHub stay canonical.

Entry point note: cozystack:wizard is the recommended way to reach this skill. The wizard runs node-bootstrap (talos-bootstrap / ubuntu-bootstrap) before handing off here when needed. This skill is also callable directly when the operator already has a ready cluster with prepared nodes.

Source of truth, in priority order:

1. Live cluster state — kubectl --context $CTX ....
2. Upstream chart values: ~/git/github.com/cozystack/cozystack/packages/core/{installer,platform}/values.yaml and the variant overlays.
3. Install guide for the major matching --installer-version: https://cozystack.io/docs/v<X.Y>/install/kubernetes/generic/ (or talos/, air-gapped, etc.).
4. Ansible reference: ~/git/github.com/cozystack/ansible-cozystack/roles/cozystack/{defaults,tasks}/main.yml.

Never guess versions, IPs, label values, or CIDRs — read them from the cluster or ask.

Core principles

• Match the operator's natural language. Read from <config-dir>/.state.yaml operator_language (set by cozystack:wizard Phase 0) or detect from prior messages when invoked directly. Use it in prompts, AskUserQuestion options, summaries, and gates. Code identifiers, commands, file paths, and GitHub-public text stay in their canonical form.
• One valid path → just do it. After the operator approved the consolidated plan in Phase 5 (STOP GATE 2), the skill runs helm install + Platform Package apply + Tenant patch + HR wait + verification back-to-back without re-prompting. Approval gates remain only for (a) multi-option questions in Phase 4 (storage layout, network values, publishing host), (b) destructive operations (Phase 5.5 per-node storage provisioning — each zpool create is a real choice with data implications), (c) STOP GATEs 1/2/3 themselves. No "are you ready to continue?" between phases that have one valid outcome.
• Front-load the interview. Every question the skill might ask in any phase is collected upfront in Phase 4. That includes per-node storage devices (Phase 5.5), per-node provisioning approvals (Phase 5.5), extractedprism opt-out (Phase 5.6), Tenant ingress patch confirmation (Phase 8, inline), and HR stuck-state recovery preferences (Phase 8). Phase 2 cluster lookup + Phase 0 intent_hints from <config-dir>/.state.yaml must fill every slot they can before any question fires. Phase 4 presents one consolidated summary with every slot filled (defaults marked) and quick-edit affordances. Phases 5.5 onward execute against the collected answers — no re-prompts mid-flow except destructive STOP GATEs that have to ask by their nature (e.g. zpool destroy on an existing pool the operator chose to wipe).
• Layer-pure operator output. The skill never says "returning control to wizard", "the wizard will dispatch next", or any other orchestration commentary in the operator-facing summary. Whoever invoked the skill (a human running /cozystack:cluster-install directly, or the wizard's dispatch loop) figures out what's next on their own. Internal SKILL.md references to cozystack:wizard are fine for documentation; wizard does not appear in any text shown to the operator.
• The user is click-ops. Show what you're about to do, in plain language, before doing it. Wait for Continue.
• Three non-negotiable gates: cluster fits, values gathered, all HRs Ready. None can be skipped.
• Read-only lookups (get, describe, logs, ephemeral debug pods) need no approval. Mutating actions (apply, patch, helm install, label) need explicit user approval each time.
• Errors are not the user's fault. When a check fails, explain what's wrong, why it matters, and offer concrete next steps (with commands). Don't leave the user staring at a Helm stack trace.
• On a fatal failure that looks upstream: stop, assemble a diagnostic bundle (references/issue-templates.md), draft an issue body, hand it to the user.