moilanik a6eb4da214 nit: ai-superpower initial commit

- .ai/ instruction set (root, behavior, skills, constraints)
- apply.sh workflow documentation (apply.md)
- architecture documentation (docs/architecture.md)
- .github/copilot-instructions.md for VS Code auto-load
- .gitignore (tmp/, .ai-instructions.conf)"

2026-03-02 14:06:36 +02:00

5.0 KiB

Raw Blame History

Agent Capabilities and Limitations

🚫 Kubernetes Cluster Access Restrictions

AI Assistant does NOT have direct access to Kubernetes clusters:

What AI CANNOT Do:

❌ Run kubectl commands against live clusters
❌ Run helm install/upgrade to live clusters
❌ Access cluster directly - no credentials, no connection
❌ Make port-forwards to cluster services

Why:

User manages cluster access and credentials
Prevents accidental changes to production/development clusters
User controls when and how deployments happen

What AI CAN Do:

✅ helm template - Render manifests locally
✅ helm show values - Inspect chart configurations
✅ helm dependency - Manage chart dependencies
✅ curl commands - Make HTTP requests (when user provides port-forward)
✅ Analyze configurations - Review YAML/JSON files
✅ Suggest commands - Show what user should run

👤 User Responsibilities

User Must:

Run all kubectl commands themselves

kubectl get pods -n monitoring
kubectl describe pod ...
kubectl logs ...

Create port-forwards when AI needs to test endpoints

kubectl port-forward -n monitoring svc/prometheus 9090:80
# Then AI can: curl http://localhost:9090/...

Run helm install/upgrade themselves

helm upgrade --install monitoring . -f values.yaml

Verify changes before applying
Control deployment timing
Manage cluster credentials

🎯 Workflow Pattern

When user reports a cluster issue:

AI asks user to run kubectl commands:

"Please run: kubectl get pods -n monitoring"
"Please run: kubectl describe pod [pod-name]"

User provides output
AI analyzes the output
AI suggests fix with commands for user to run
User runs commands themselves

Example:

User: "Prometheus pod failing"

AI: "Please run: kubectl describe pod -n monitoring -l app=prometheus"

User: [provides output]

AI: "I see ImagePullBackOff error. The image registry.k8s.io/busybox:1.28 doesn't exist.
     
     Let me update values.yaml to use working image.
     
     [makes file edit]
     
     After change, please run:
     kubectl delete pod [pod-name] -n monitoring"

User: [runs command]

🛠️ Helm Command Rules

AI Can Run (Local Operations):

# Render templates locally
helm template monitoring . -f values.yaml > tmp/manifests.yaml

# Show chart values
helm show values prometheus-community/prometheus

# Manage dependencies
helm dependency update
helm dependency build

AI CANNOT Run (Cluster Operations):

# ❌ Install to cluster
helm install monitoring . -f values.yaml

# ❌ Upgrade cluster release
helm upgrade monitoring . -f values.yaml

# ❌ List cluster releases
helm list -n monitoring

# ❌ Get release status
helm status monitoring

Instead, AI Should:

Generate and show the command:

"Run this command:
helm upgrade --install monitoring . -f values.yaml -n monitoring"

Explain what it will do
Wait for user to run it
Ask user for results/output if needed

📊 Testing Endpoints

When AI needs to test HTTP endpoints:

Pattern:

AI asks user:

"Please create port-forward:
kubectl port-forward -n monitoring svc/prometheus 9090:80"

User runs port-forward (keeps terminal open)

AI can now run:

curl http://localhost:9090/api/v1/query?query=up

When done, user closes port-forward (Ctrl+C)

Common Services:

# Prometheus
kubectl port-forward -n monitoring svc/prometheus 9090:80

# Grafana
kubectl port-forward -n monitoring svc/grafana 3000:80

# MinIO Console
kubectl port-forward -n monitoring svc/minio 9001:9001

# Loki
kubectl port-forward -n monitoring svc/loki 3100:3100

🔍 Debugging Workflow

For Pod Issues:

AI requests:

1. "kubectl get pods -n [namespace]"
2. "kubectl describe pod [pod-name] -n [namespace]"
3. "kubectl logs [pod-name] -n [namespace]"
4. "kubectl get events -n [namespace] --sort-by='.lastTimestamp'"

User provides output → AI analyzes → AI suggests fix

For Service Issues: