ai-superpower/.ai/instructions/constraints/agent-capabilities.instructions.md

# 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:
1. **Run all kubectl commands** themselves
   ```bash
   kubectl get pods -n monitoring
   kubectl describe pod ...
   kubectl logs ...
   ```

2. **Create port-forwards** when AI needs to test endpoints
   ```bash
   kubectl port-forward -n monitoring svc/prometheus 9090:80
   # Then AI can: curl http://localhost:9090/...
   ```

3. **Run helm install/upgrade** themselves
   ```bash
   helm upgrade --install monitoring . -f values.yaml
   ```

4. **Verify changes** before applying
5. **Control deployment timing**
6. **Manage cluster credentials**

---

## 🎯 Workflow Pattern

**When user reports a cluster issue:**

1. **AI asks user to run kubectl commands:**
   ```
   "Please run: kubectl get pods -n monitoring"
   "Please run: kubectl describe pod [pod-name]"
   ```

2. **User provides output**

3. **AI analyzes** the output

4. **AI suggests fix** with commands for user to run

5. **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):

```bash
# 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):

```bash
# ❌ 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:

1. **Generate and show** the command:
   ```
   "Run this command:
   helm upgrade --install monitoring . -f values.yaml -n monitoring"
   ```

2. **Explain** what it will do

3. **Wait** for user to run it

4. **Ask user** for results/output if needed

---

## 📊 Testing Endpoints

**When AI needs to test HTTP endpoints:**

### Pattern:

1. **AI asks user:**
   ```
   "Please create port-forward:
   kubectl port-forward -n monitoring svc/prometheus 9090:80"
   ```

2. **User runs port-forward** (keeps terminal open)

3. **AI can now run:**
   ```bash
   curl http://localhost:9090/api/v1/query?query=up
   ```

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

### Common Services:

```bash
# 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:

**AI requests:**
```
1. "kubectl get svc -n [namespace]"
2. "kubectl describe svc [service-name] -n [namespace]"
3. "kubectl get endpoints [service-name] -n [namespace]"
```

### For Configuration Issues:

**AI can:**
- Read files directly (values.yaml, templates, etc.)
- Use helm template to render manifests
- Analyze configurations
- Suggest changes

---

## 💡 Remember

- **AI = Analysis + File editing + Suggestions**
- **User = Cluster access + Command execution + Deployment control**
- **Communication is key** - AI asks, user provides, AI analyzes
- **Safety first** - No direct cluster access prevents accidents

---

**Last Updated:** 2026-01-19
**Purpose:** Define clear boundaries between AI capabilities and user responsibilities