Agnostic Cluster Refactor Skill for Antigrafity CLI: Building an AI Agent that Migrates Apps from AWS to GKE (Subagents, HITL Gate & Workload Identity)

A developer built an AI agent skill for the Antigravity CLI that migrates applications from AWS to GKE. The agent scans cloud dependencies, spawns parallel subagents to refactor code and infrastructure, and validates changes on local Kubernetes before deploying with keyless Workload Identity, with mandatory human oversight before any production mutation.

Have you ever inherited a codebase where import boto3 appears in 47 different files? Where AWS credentials live in hardcoded environment variables and file storage is a file.save "/tmp/..." that will blow up the moment it hits an ephemeral Kubernetes pod? I did. And instead of refactoring everything by hand, I built an AI agent to do it for me — with mandatory human oversight before any production mutation. This article documents what I built: a skill for the Antigravity CLI agy that scans cloud dependencies, spawns parallel subagents to refactor code and infrastructure, and validates everything on local Kubernetes before deploying to GKE with keyless Workload Identity. boto3 is the AWS SDK for Python. It seems harmless at first: python Innocent on day 1 import boto3 s3 = boto3.client 's3', region name='us-east-1' s3.upload fileobj file, bucket name, filename Six months later: python examples/legacy-app/app.py — the real state after it grows import os import boto3 from flask import Flask, request, jsonify app = Flask name "Temporary" hardcoded since 2022 DB PASSWORD = os.getenv "DB PASSWORD", "default-insecure-password" S3 BUCKET = os.getenv "AWS S3 BUCKET NAME" AWS REGION = os.getenv "AWS DEFAULT REGION", "us-east-1" s3 client = boto3.client 's3', aws access key id=os.getenv "AWS ACCESS KEY ID" , aws secret access key=os.getenv "AWS SECRET ACCESS KEY" , region name=AWS REGION @app.route "/upload", methods= "POST" def upload file : file = request.files 'file' filename = file.filename if S3 BUCKET: s3 client.upload fileobj file, S3 BUCKET, filename return jsonify {"message": f"Uploaded to AWS S3: {S3 BUCKET}"} else: Fallback to local disk — will break in K8s ephemeral pods local path = os.path.join "/tmp", filename file.save local path return jsonify {"message": f"Saved locally at {local path}"} Three coupling problems in a single file: proprietary SDK boto3 , AWS-specific credentials, and local disk storage that doesn't survive ephemeral Kubernetes pods. Now multiply that by 10 services. A skill for the Antigravity CLI that adds two commands to the agent chat: /agnostic-cluster-refactor:scan-deps /agnostic-cluster-refactor:spawn-refactor The complete flow: But before diving into the code, let me introduce the players. agy is not a script. It's an LLM-powered agent — you describe what you want in the chat and it decides how to do it, using a toolset: read file , write to file , run command , invoke subagent . The difference from a web chatbot: agy has access to your local filesystem, runs terminal commands, and operates in autonomous loops. It's an engineer working on your machine. | Script | Agent | |---|---| sed 's/boto3/gcs/g' across all files | Analyzes the semantic context of each import and replaces it with the correct equivalent API | | Fails if the environment changed | Adapts to the current state | | Deterministic | Probabilistic + adaptive | A skill is a SKILL.md file with YAML frontmatter that defines when and how the agent uses that capability. The agent reads the description field and decides whether the skill is relevant to the current task. --- name: scan-deps description: Scans the project for cloud-provider dependencies and generates dependency-map.json. Use when the user wants to map vendor lock-in before migrating to GKE. --- Steps 1. Ask which directory to scan 2. Run: python3 .agents/skills/.../scan deps.py <PATH 3. Present the DAG summary 💡 Key distinction:skills in .agents/skills/ are injected silently into context. To appear as a /command in autocomplete, you need aplugininstalled at ~/.gemini/config/plugins/<plugin / . More on that in Part 6. A subagent is a child agent with completely isolated context. It doesn't "see" the parent's history or the other subagent's — exactly what we want: the Backend agent can't get confused by the YAML the Infra agent is writing. Pseudocode — how agy orchestrates this invoke subagent name="backend-engine", system prompt="You are an expert in migrating boto3 to GCS...", toolset= "read file", "write to file", "run command" , workspace="/path/to/shadow-worktree-backend", message="Refactor the files from dependency-map.json" Subagent B is invoked in parallel — no blocking invoke subagent name="infra-engine", toolset= "write to file" , write only — principle of least privilege workspace="/path/to/shadow-worktree-infra", message="Generate serviceaccount.yaml, deployment.yaml, ingress.yaml for GKE" Each subagent operates in an isolated Git Worktree — a physical copy of the repository in a separate directory, on a different branch. If Subagent A introduces a bug, main stays untouched. The first step is mapping the problem. scan deps.py walks the project with os.walk , applies regex patterns by category, and generates a DAG Directed Acyclic Graph as JSON. scripts/scan deps.py patterns = { "storage": r"google\.cloud\.storage", r"boto3. s3", AWS-coupled r"aws-sdk. s3" , "messaging": r"google\.cloud\.pubsub", r"boto3. sqs", AWS-coupled r"kafka-python", , "secrets": r"boto3. secretsmanager", r"python-dotenv", , "databases": r"psycopg2", r"pymongo" } for root, dirs, files in os.walk path : dirs : = d for d in dirs if not d.startswith '.' and d not in 'venv', 'node modules', ' pycache ' for file in files: if not file.endswith '.py', '.js', '.yaml', '.tf' : continue with open os.path.join root, file as f: content = f.read for dep type, pattern list in patterns.items : for pattern in pattern list: if re.search pattern, content, re.IGNORECASE : dependencies dep type .append { "file": os.path.relpath file path, path , "matched pattern": pattern } The output is a dependency-map.json with the full dependency graph: { "dependencies": { "storage": { "file": "examples/legacy-app/app.py", "matched pattern": "boto3. s3" }, { "file": "examples/legacy-app/api.py", "matched pattern": "boto3. s3" } , "messaging": { "file": "examples/legacy-app/worker.py", "matched pattern": "boto3. sqs" } }, "architectural dag": { "nodes": { "id": "application", "type": "component" }, { "id": "dep-storage", "files": "app.py", "api.py" }, { "id": "provider-aws", "type": "cloud-provider" } , "edges": { "source": "application", "target": "dep-storage", "relation": "uses storage" }, { "source": "dep-storage", "target": "provider-aws", "relation": "coupled to aws" } }, "recommended action": "Execute '/spawn-refactor' targeting GCP GKE" } ❓ Why a DAG and not a plain list?The graph reveals transitive relationships: app.py and worker.py both depend on AWS via boto3 — so they need to be refactored together. A list would only say "these files have boto3." This was the most important design decision: how do I ensure the agent doesn't refactor the wrong file without me seeing what's happening first? The answer lives in two places. The .agents/hooks.json file registers a PreToolUse hook — a command that runs before any write to file the agent attempts: { "hitl-production-gate": { "enabled": true, "PreToolUse": { "matcher": "write to file|replace file content|multi replace file content", "hooks": { "type": "command", "command": "python3 .agents/skills/agnostic-cluster-refactor/scripts/scan deps.py --check-only", "timeout": 5 } } } } The hook receives a JSON payload via stdin and responds with a decision: scan deps.py — --check-only mode SAFE WRITE PREFIXES = "examples/", "terraform/", ".agents/" def check only hook : payload = json.load sys.stdin target = payload.get "toolCall", {} .get "args", {} .get "TargetFile", "" workspace root = payload.get "workspacePaths", "." 0 rel path = os.path.relpath target, workspace root if not any rel path.startswith p for p in SAFE WRITE PREFIXES : print json.dumps { "decision": "force ask", "reason": f" HITL Gate '{rel path}' is outside safe directories. Confirm before proceeding." } else: print json.dumps {"decision": "allow"} Three possible decisions the hook can return: | Decision | Effect | |---|---| "allow" | Agent proceeds automatically | "force ask" | agy pauses and asks the human | "deny" | Completely blocked, no prompt | Testing it from the command line: File OUTSIDE safe directories echo '{"toolCall":{"name":"write to file","args":{"TargetFile":"/project/src/app.py"}}, "workspacePaths": "/project" }' | python3 scripts/scan deps.py --check-only → {"decision": "force ask", "reason": " HITL Gate 'src/app.py' is outside safe directories..."} File INSIDE safe directories echo '{"toolCall":{"name":"write to file","args":{"TargetFile":"/project/examples/k8s/deployment.yaml"}}, "workspacePaths": "/project" }' | python3 scripts/scan deps.py --check-only → {"decision": "allow"} Beyond the automatic hook, the /spawn-refactor SKILL.md instructs the agent to always ask for explicit confirmation before spawning subagents: HITL Gate — mandatory before any mutation Display the list of files that will be changed and ask: The following files will be modified: - examples/legacy-app/app.py replace boto3 → GCS - examples/legacy-app/worker.py replace SQS → Pub/Sub Type YES to confirm or NO to abort. Halt if the user does not confirm with YES. 🛡️ Two layers of protection: the hook catches any write automatically, and the SKILL.md forces you to see the full plan before anything moves. After Subagent A runs, app.py goes from the boto3 mess above to this: python examples/refactored-app/app.py import os from flask import Flask, request, jsonify app = Flask name DB PASSWORD = os.getenv "DB PASSWORD" if not DB PASSWORD: raise RuntimeError "DB PASSWORD environment variable is required " GCS BUCKET NAME = os.getenv "GCS BUCKET NAME", "local-mock" LOCAL MOCK=true → bypasses GCS; useful for K8s plumbing tests without real credentials LOCAL MOCK = os.getenv "LOCAL MOCK", "false" .lower == "true" if LOCAL MOCK: storage client = None print " LOCAL MOCK GCS disabled. Uploads will be simulated." else: from google.cloud import storage import only when we actually need GCS storage client = storage.Client zero credentials — ADC via Workload Identity mock store: dict str, bytes = {} @app.route "/health", methods= "GET" def health : return jsonify { "status": "healthy", "platform": "local-k8s" if LOCAL MOCK else "gcp-gke", "gcs bucket": GCS BUCKET NAME, "mock mode": LOCAL MOCK, } @app.route "/upload", methods= "POST" def upload file : file = request.files "file" filename = file.filename if LOCAL MOCK: data = file.read mock store filename = data return jsonify { "message": f" LOCAL MOCK {filename} stored in memory {len data } bytes ", "gcs uri": f"gs://local-mock/{filename}", "files in mock": list mock store.keys , } bucket = storage client.bucket GCS BUCKET NAME blob = bucket.blob filename blob.upload from file file return jsonify { "message": f"Uploaded {filename} to {GCS BUCKET NAME}", "gcs uri": f"gs://{GCS BUCKET NAME}/{filename}", } @app.route "/files", methods= "GET" def list files : if LOCAL MOCK: return jsonify {"files": list mock store.keys , "source": "local-mock"} blobs = storage client.list blobs GCS BUCKET NAME return jsonify {"files": b.name for b in blobs , "source": f"gs://{GCS BUCKET NAME}"} if name == " main ": app.run host="0.0.0.0", port=8080, debug=LOCAL MOCK What changed: | Before | After | |---|---| import boto3 | from google.cloud import storage conditional | boto3.client 's3', aws access key id=... | storage.Client — zero credentials | file.save "/tmp/..." | blob.upload from file file | DB PASSWORD with insecure default | RuntimeError if missing | ❌ Wrong — crashes at startup without GCP credentials from google.cloud import storage storage client = storage.Client RuntimeError before any request is handled ✅ Correct — import only happens when we actually need it if LOCAL MOCK: storage client = None else: from google.cloud import storage ← inside the else block storage client = storage.Client from google.cloud import storage executes when Python loads the module — before serving any request. Without GCP credentials, the app crashes at startup. Moving the import inside else fixes it: with LOCAL MOCK=true , the module is never imported. I wanted to validate the entire K8s stack Deployment, ConfigMap, Secret, Service, health checks, routing locally using Docker Desktop — without needing real GCP credentials. The solution was LOCAL MOCK=true combined with a Docker Desktop quirk that catches a lot of people off guard. Docker Desktop uses two completely separate runtimes that don't share images: ┌──────────────────────────────────────┐ │ Docker daemon │ ← docker build, docker images │ images here are NOT visible to K8s │ └──────────────────────────────────────┘ ┌──────────────────────────────────────┐ │ containerd │ ← used by the Kubernetes cluster │ separate namespace │ └──────────────────────────────────────┘ When you run docker build -t my-image . , the image exists in the Docker daemon but not in containerd. With imagePullPolicy: Never , K8s looks in containerd and fails: Failed to pull image "my-image:local": ErrImageNeverPull The fix: a local registry as the bridge between both runtimes. registry:2 on port 5001 port 5000 is taken by macOS AirPlay docker run -d -p 5001:5000 --restart=always --name local-registry registry:2 Now the flow works end-to-end: docker build → Docker daemon ↓ docker tag + push → localhost:5001 → registry:2 ↓ containerd pulls from registry:2 ← K8s Pod starts successfully The Makefile handles all of this in a single command: REGISTRY = localhost:5001 REGISTRY IMAGE = $ REGISTRY /agnostic-cluster-refactor:local registry-start: @docker ps --filter name=local-registry --filter status=running | grep local-registry || \ docker run -d -p 5001:5000 --restart=always --name local-registry registry:2 build: registry-start docker build -t agnostic-cluster-refactor:local . docker tag agnostic-cluster-refactor:local $ REGISTRY IMAGE docker push $ REGISTRY IMAGE @echo "Image available to K8s: $ REGISTRY IMAGE " local-up: kubectl config use-context docker-desktop kubectl apply -f examples/k8s/local/secret-db.yaml kubectl apply -f examples/k8s/local/configmap.local.yaml kubectl apply -f examples/k8s/local/deployment.local.yaml kubectl apply -f examples/k8s/local/service.local.yaml kubectl rollout status deployment/agnostic-cluster-app --timeout=60s @echo "Access: http://localhost:8080/health" examples/k8s/local/deployment.local.yaml apiVersion: apps/v1 kind: Deployment metadata: name: agnostic-cluster-app spec: replicas: 1 template: spec: containers: - name: app image: localhost:5001/agnostic-cluster-refactor:local imagePullPolicy: Always always pull from local registry envFrom: - configMapRef: name: app-config-local injects LOCAL MOCK=true env: - name: DB PASSWORD valueFrom: secretKeyRef: name: app-secrets key: db-password readinessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 5 examples/k8s/local/configmap.local.yaml apiVersion: v1 kind: ConfigMap metadata: name: app-config-local data: GCS BUCKET NAME: "local-mock" GCP PROJECT ID: "local-dev" LOCAL MOCK: "true" ← activates the in-memory store Running it: make build build + push to local registry make local-up apply all manifests curl http://localhost:8080/health {"status":"healthy","platform":"local-k8s","mock mode":true,"gcs bucket":"local-mock"} curl -X POST http://localhost:8080/upload -F "file=@package.json" {"message":" LOCAL MOCK package.json stored in memory 842 bytes ", "gcs uri":"gs://local-mock/package.json"} curl http://localhost:8080/files {"files": "package.json" ,"source":"local-mock"} make local-down teardown ✅ Entire K8s stack validated — Deployment, ConfigMap, Secret, Service, health checks, routing — without a single GCP token. On GKE, the story is completely different. The naive approach: os.environ "GOOGLE APPLICATION CREDENTIALS" = "/app/sa-key.json" storage client = storage.Client This requires a JSON key file inside the container, which means: The Workload Identity approach: annotate a Kubernetes Service Account KSA with a Google Service Account GSA email: examples/k8s/serviceaccount.yaml apiVersion: v1 kind: ServiceAccount metadata: name: refactored-app-ksa annotations: iam.gke.io/gcp-service-account: "gke-app-sa@MY PROJECT.iam.gserviceaccount.com" GKE's internal metadata server intercepts ADC calls from Pods, verifies the annotation, and returns a short-lived OAuth2 token: The application code becomes: Zero credentials — works automatically on GKE storage client = storage.Client Terraform provisions the IAM binding automatically: terraform/iam.tf resource "google service account iam member" "workload identity" { service account id = google service account.app.name role = "roles/iam.workloadIdentityUser" member = "serviceAccount:${var.project id}.svc.id.goog default/refactored-app-ksa " } 🔐 This binding is the handshake between the Kubernetes world and GCP IAM. Without it, no token is issued — storage.Client returns a 403. When I first tested, /scan-deps and /spawn-refactor did not appear in the agy autocomplete. I spent a good chunk of time debugging this. The discovery: agy has three distinct skill-loading mechanisms: | Mechanism | Location | Shows in / autocomplete? | |---|---|---| | Project skill | .agents/skills/<name /SKILL.md | ❌ No | | Global contextual skill | ~/.gemini/antigravity-cli/skills/ | ❌ No | Plugin with namespace | ~/.gemini/config/plugins/<plugin / | ✅ Yes | To make the commands appear, create the plugin structure: mkdir -p ~/.gemini/config/plugins/agnostic-cluster-refactor/skills/scan-deps mkdir -p ~/.gemini/config/plugins/agnostic-cluster-refactor/skills/spawn-refactor cat ~/.gemini/config/plugins/agnostic-cluster-refactor/plugin.json << 'EOF' { "name": "agnostic-cluster-refactor", "version": "1.0.0", "description": "Migrates apps from AWS to GCP GKE with Workload Identity." } EOF After restarting agy , the autocomplete shows: /agnostic-cluster-refactor:scan-deps /agnostic-cluster-refactor:spawn-refactor The namespace prevents collisions — two different plugins can both have a skill named scan-deps and they'll appear as /plugin-a:scan-deps and /plugin-b:scan-deps . When I ran /agnostic-cluster-refactor:spawn-refactor and confirmed the HITL Gate, Gemini the agy engine orchestrated: Subagent A Backend — in shadow-worktree-backend: dependency-map.json to identify boto3 files import boto3 → from google.cloud import storage, pubsub v1 in each file boto3.client 's3', ... → storage.Client .bucket ... with semantically equivalent calls boto3.client 'sqs', ... → pubsub v1.SubscriberClient requirements.txt : removed boto3==1.28.0 , added google-cloud-storage==2.10.0 and google-cloud-pubsub==2.18.0 Subagent B Infra — in shadow-worktree-infra: serviceaccount.yaml with the iam.gke.io/gcp-service-account annotation deployment.yaml with env vars via ConfigMap/Secret — no hardcoded credentials ingress.yaml with ingressClassName: gce the current format, not the deprecated annotation All in isolated Git Worktrees, in parallel, without touching main . 1. The conditional import is intentional, not lazy. When LOCAL MOCK=true , from google.cloud import storage must not run at module level. Without GCP credentials, it throws at startup before any request is served. Import conditionally. 2. Docker Desktop K8s and the Docker daemon live in separate worlds. imagePullPolicy: Never breaks with Docker Desktop because K8s uses containerd, not the daemon. Use a local registry on port 5001 5000 is taken by macOS and imagePullPolicy: Always . 3. .agents/workflows/ does not create slash commands in agy. Skills in .agents/skills/ are context injections, not interactive commands. The / autocomplete requires a plugin installed in ~/.gemini/config/plugins/ . 4. The HITL Gate needs two independent layers. A hook catches unexpected writes automatically. But for /spawn-refactor — which modifies multiple files in parallel — explicit plan confirmation in the SKILL.md is non-negotiable. Without both layers, the agent can act before you understand the blast radius. 5. Workload Identity eliminates an entire security problem class. No JSON keys in containers means no credential leaks in logs, no manual rotation, no hardcoded keys in Dockerfiles, and no Secret volumes mounted on Pod disk. The Metadata Server's short-lived tokens are genuinely safer. Clone git clone https://github.com/carlosrgomes/agnostic-cluster-refactor cd agnostic-cluster-refactor Test locally without GCP Docker Desktop K8s make build build + push to local registry make local-up apply manifests to docker-desktop context curl http://localhost:8080/health Scan your own project's dependencies python3 scripts/scan deps.py /path/to/your/project cat dependency-map.json | python3 -m json.tool Validate the HITL Gate hook echo '{"toolCall":{"name":"write to file","args":{"TargetFile":"/project/src/main.py"}}, "workspacePaths": "/project" }' | python3 scripts/scan deps.py --check-only → {"decision": "force ask", ...} Teardown make local-down For the full GKE deployment with Workload Identity, the project README includes the Terraform that provisions all the infrastructure. The project started from a real problem boto3 everywhere and ended up with a surprisingly complete solution: automatic dependency scanning, parallel subagent refactoring, mandatory human oversight, local K8s testing without cloud credentials, and keyless production auth. What impressed me most wasn't the AI doing the refactoring — it was the supervision system design : hooks intercepting any write outside safe directories, SKILL.md with an explicit gate before destructive actions, and Git Worktrees ensuring main is never touched without human review. An autonomous agent without oversight is a chaotic script. An agent with a well-designed HITL Gate is a trustworthy teammate. Tutorial técnico completo: migração autônoma de aplicações acopladas à AWS para o Google Kubernetes Engine GKE usando o Antigravity CLI com Workload Identity, subagentes paralelos e HITL gate. /scan-deps /spawn-refactor Aplicações legadas acumulam acoplamentos…