Add deploy-selfmanaged skill and slash command

[EngHabu]

Summary

• Adds a Claude Code skill at .claude/skills/deploy-selfmanaged/ that guides users through deploying a Union self-managed (BYOC) data plane end-to-end. Captures intent (cloud, mode, control-plane URL, cluster name, region), verifies prereqs, then runs the deterministic path for the chosen cloud:
  • AWS / GCP — drives the existing scripts/selfmanaged_{aws,gcp}_e2e.py flyte e2e scripts (full 4-phase flow: infra → helm → smoke → optional teardown).
  • Azure / OCI / CoreWeave / generic K8s — guided walkthroughs that mirror each cloud's prepare-infra.md → deploy-dataplane.md, with cloud-specific gotchas surfaced.
• Adds /deploy-selfmanaged slash command (.claude/commands/deploy-selfmanaged.md) for explicit invocation, with optional [cloud] [mode] args.
• Whitelists .claude/skills/ and .claude/commands/ in .gitignore so team-shared skills are checked in while personal Claude state (settings, transcripts) stays ignored.
• Drive-by fix to scripts/README.md — the GCP e2e script is fully implemented (not a stub); README is updated to reflect that and to call out that remote credential stashing is AWS-only today.

What the user experience looks like

The skill is designed to be intuitive, guiding, deterministic. A typical AWS deploy session looks like this:

1. Trigger

The user either says something natural ("deploy a self-managed Union cluster on AWS") and the skill auto-engages from its description, or they run the slash command:

/deploy-selfmanaged aws deploy

2. Intent capture (Step 1 in SKILL.md)

Claude asks two button-pick questions via AskUserQuestion:

• Cloud — aws | gcp | azure | oci | coreweave | generic
• Mode — deploy | teardown | smoke-only

Then prompts in plain text for the three free-form fields:

• Control plane URL (e.g. https://myorg.union.ai)
• Cluster name (registered with the control plane)
• Region (script default shown but never silently assumed)

Skipped questions if the user already volunteered the answer in their initial message. Then echoes a Plan: block back so the user can sanity-check before anything runs:

Plan:
  cloud:             aws
  mode:              deploy
  control plane:     https://myorg.union.ai
  cluster name:      my-test-cluster
  region:            us-east-2

3. Prereq verification (Step 2 + cloud-specific)

Claude runs the prereq checks as a single batch and reports a pass/fail table:

Check	Result
helm version --short	✅ v4.1.1
kubectl version --client	✅ v1.35.1
uctl version	✅ v0.1.20
uv	✅ installed
aws --version	✅ aws-cli/2.31.10
eksctl version	✅ 0.225.0
aws sts get-caller-identity	✅ account 479…192
AWS_ACCESS_KEY_ID env var	❌ not set
scripts/.venv	✅ exists, flyte 2.2.2 importable

Any failure halts the flow with the exact remediation command — no "let me try a workaround." For SSO-authenticated users, the skill specifically catches the gap between aws sts get-caller-identity succeeding (via SSO) and the e2e script needing AWS_ACCESS_KEY_ID exported, and tells the user to run aws configure export-credentials --profile <sso-profile> --format env.

4. Deploy command, shown before run

Claude composes the exact command, displays it, and asks for explicit yes before running anything cloud-mutating. For AWS/GCP, the deploy is long-running (~25–40 min) and the recommendation is to run in the user's own terminal with --tui:

cd scripts && source .venv/bin/activate && \
flyte run --local --tui selfmanaged_aws_e2e.py main \
    --control_plane_url https://myorg.union.ai \
    --cluster_name my-test-cluster \
    --aws_region us-east-2

The user sees Phase 1/4 → 2/4 → 3/4 → (4/4 teardown) in a live TUI tree with timings, logs, and links to each running cloud resource. For Azure/OCI/CoreWeave/generic, Claude walks prepare-infra.md → deploy-dataplane.md step by step, asking before each cloud-mutating command and showing the values-file diff before saving.

5. Verify

Once helm install completes, Claude runs:

• kubectl get pods -n union — every pod must reach Running/Completed
• kubectl get events -n union --sort-by=.lastTimestamp | tail -20
• AWS/GCP: smoke suite ran in Phase 3 — Claude reports the TUI summary
• Other clouds: optional python -m smoke_tests invocation against the new cluster

6. Teardown is first-class

mode=teardown is a real entry point, not an afterthought. AWS/GCP invoke the script's teardown_cluster task (resolves account/project from ambient identity, deletes everything cluster_name implied). Manual clouds get a reverse-order delete with per-resource confirmation — the skill never bulk-deletes a resource group, project, or subscription.

Operating rules the skill enforces

These appear at the top of SKILL.md and govern every cloud path:

1. Never run a cloud-mutating command without showing it first and getting explicit "yes." Read-only commands run without prompting.
2. Never invent values. Missing cluster_name, region, or credentials → ask, don't guess.
3. Failed prereq → halt with the fix command. No silent workarounds.
4. One cluster, one run. No batching across clusters in a single skill invocation.
5. Re-runnable end to end — scripts are idempotent, manual paths note "skip if already created."

Test plan

• Invoke /deploy-selfmanaged and confirm intent capture works (cloud + mode via questions, free-form for URL/name/region).
• Run the universal prereq checks on a clean machine and confirm they catch missing helm/kubectl/uctl/uv.
• AWS path: confirm the SSO-vs-STS-env-var check correctly halts SSO-only sessions and unblocks once aws configure export-credentials is eval'd.
• AWS path: end-to-end deploy on a throwaway cluster (cost ~$1.30/hr) and confirm teardown completes cleanly.
• AWS path: teardown mode against a --skip_teardown cluster.
• GCP path: end-to-end deploy on a throwaway project; confirm gke-gcloud-auth-plugin prereq check catches its absence.
• Azure / OCI / CoreWeave / generic walkthroughs: spot-read each <cloud>.md against the corresponding content/deployment/selfmanaged/<cloud>/ doc to confirm gates and command order match.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	3f06fa5
Status:	✅  Deploy successful!
Preview URL:	https://58a4766b.docs-dog.pages.dev
Branch Preview URL:	https://add-deploy-selfmanaged-skill.docs-dog.pages.dev

View logs

[Copilot]

Pull request overview

This PR introduces a team-shared Claude skill and slash command to guide end-to-end Union self-managed (BYOC) dataplane deployments across multiple clouds, and updates repo hygiene/docs to support it.

Changes:

• Add the deploy-selfmanaged Claude skill with per-cloud deployment/teardown walkthroughs and universal prereq gating.
• Add /deploy-selfmanaged slash command for explicit invocation with optional [cloud] [mode] arguments.
• Update .gitignore to keep team-shared .claude/skills/ + .claude/commands/ tracked, and update scripts/README.md to reflect GCP E2E script support.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
scripts/README.md	Updates E2E scripts README to reflect AWS + GCP support and credential stashing limitations.
.gitignore	Adjusts ignore rules to allow sharing Claude skills/commands while keeping other Claude state ignored.
.claude/skills/deploy-selfmanaged/SKILL.md	Defines the top-level skill flow, intent capture, universal prereqs, and verification/teardown rules.
.claude/skills/deploy-selfmanaged/aws.md	AWS-specific prereqs and script-driven deploy/teardown instructions.
.claude/skills/deploy-selfmanaged/gcp.md	GCP-specific prereqs and script-driven deploy/teardown instructions.
.claude/skills/deploy-selfmanaged/azure.md	Azure guided walkthrough aligned to self-managed Azure docs (with some command/flag divergences noted).
.claude/skills/deploy-selfmanaged/oci.md	OCI guided walkthrough aligned to self-managed OCI docs (with some command/flag divergences noted).
.claude/skills/deploy-selfmanaged/coreweave.md	CoreWeave guided walkthrough (currently has several critical mismatches vs source-of-truth docs).
.claude/skills/deploy-selfmanaged/generic.md	Generic Kubernetes guided walkthrough (currently has provider mismatch vs source-of-truth docs).
.claude/commands/deploy-selfmanaged.md	Adds the /deploy-selfmanaged command entrypoint wiring into the skill.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ppiegaze]

@EngHabu Can you resolve the copilot comments?

[ppiegaze]

Please check the copilot comments. Probably false positives but worth checking

[github-actions]

GHA build & deploy preview

Built by .github/workflows/build-and-deploy.yml and deployed to the docs CF Pages project.

Branch alias	https://pr-982-add-deploy-selfmanage.docs-dog.pages.dev
This commit	https://134bab76.docs-dog.pages.dev
Commit SHA	afd1ee54813bcc8ce295e6bdbc13b1fcd5b26e06

Updated automatically on every push.