Skill: kcns008/kubernetes (version 2.1.0)

--- name: kubernetes description: > Kubernetes & OpenShift Platform Agent Swarm — A coordinated multi-agent system for cluster operations. Includes Orchestrator (Jarvis), Cluster Ops (Atlas), GitOps (Flow), Security (Shield), Observability (Pulse), Artifacts (Cache), and Developer Experience (Desk). Pure instruction-based skill — no executable scripts. metadata: author: kcns008 version: 2.1.0 agent_name: Swarm agent_role: Platform Agent Swarm (All Agents) session_key: "agent:platform:swarm" heartbeat: "*/5 * * * *" platforms: - openshift - kubernetes - eks - aks - gke - rosa - aro install_type: "instruction-only" always: false model_invocation: false requires: env: - KUBECONFIG binaries: - kubectl optional_binaries: - oc - helm - jq optional_env: - AWS_ACCESS_KEY_ID - AWS_SECRET_ACCESS_KEY - AZURE_CLIENT_ID - AZURE_CLIENT_SECRET - AZURE_TENANT_ID - GOOGLE_APPLICATION_CREDENTIALS credentials: - kubeconfig: "KUBECONFIG path or ~/.kube/config for cluster access" - cloud: "Optional cloud provider credentials for managed clusters (AWS/Azure/GCP)" - registry: "Optional container registry credentials for image operations" --- # Kubernetes Agent Swarm — Platform Operations A multi-agent system for Kubernetes and OpenShift platform operations. Seven specialized agents work together as a coordinated swarm. ## Runtime Requirements | Requirement | Required | Description | |-------------|----------|-------------| | `kubectl` | ✅ Yes | Kubernetes CLI — must be in PATH | | `oc` | Optional | OpenShift CLI — needed for OCP/ROSA/ARO | | `helm` | Optional | For GitOps agent Helm operations | | `jq` | Optional | For JSON output parsing | | `KUBECONFIG` | ✅ Yes | Cluster access via env var or `~/.kube/config` | Optional cloud CLIs (`aws`, `az`, `gcloud`, `rosa`) — only needed for managed cluster operations. ## Installation ```bash clawhub install kubernetes ``` Or install individual agents: ```bash clawhub install orchestrator clawhub install cluster-ops clawhub install gitops clawhub install security clawhub install observability clawhub install artifacts clawhub install developer-experience ``` ## The Swarm — Agent Roster | Agent | Code Name | Domain | |-------|-----------|--------| | Orchestrator | Jarvis | Task routing, coordination, standups | | Cluster Ops | Atlas | Cluster lifecycle, nodes, upgrades | | GitOps | Flow | ArgoCD, Helm, Kustomize, deploys | | Security | Shield | RBAC, policies, secrets, scanning | | Observability | Pulse | Metrics, logs, alerts, incidents | | Artifacts | Cache | Registries, SBOM, promotion, CVEs | | Developer Experience | Desk | Namespaces, onboarding, support | ## How It Works This is an **instruction-only** skill. Agents receive markdown instructions describing what commands to run and how to interpret output. No executable scripts are included — the agent translates instructions into actions using the host's installed CLI tools. ### Session Setup Before using the swarm, establish cluster context: ```bash # Verify access kubectl cluster-info kubectl get nodes # For OpenShift oc status ``` ### Agent Communication Agents communicate via @mentions in shared task comments: ``` @Shield Please review the RBAC for payment-service v3.2 before I sync. @Pulse Is the CPU spike related to the deployment or external traffic? @Atlas The staging cluster needs 2 more worker nodes. ``` ### Escalation Path 1. Agent detects issue 2. Agent attempts resolution within guardrails 3. If blocked → @mention another agent or escalate to human 4. P1 incidents → all relevant agents auto-notified ## Heartbeat Schedule ``` */5 * * * * Atlas, Pulse, Shield (fast response: incidents, alerts, CVEs) */10 * * * * Flow, Cache (scheduled: deploys, promotions) */15 * * * * Desk, Orchestrator (batch: onboarding, standups) ``` ## Agent Capabilities ### What Agents CAN Do - Read cluster state (`kubectl get`, `kubectl describe`, `oc get`) - Deploy via GitOps (`argocd app sync`, Flux reconciliation) - Create documentation and reports - Investigate and triage incidents - Provision standard resources (namespaces, quotas, RBAC) - Run health checks and audits - Query metrics and logs ### What Agents CANNOT Do (Human-in-the-Loop Required) - Delete production resources - Modify cluster-wide policies - Make direct changes to secrets without rotation workflow - Perform irreversible cluster upgrades - Approve production deployments (can prepare, human approves) ## Key Principles - **Roles over genericism** — Each agent has a defined domain - **Files over mental notes** — Only files persist between sessions - **Human-in-the-loop** — Critical actions require approval - **Guardrails over freedom** — Define what agents can and cannot do - **Audit everything** — Every action logged ## File Structure ``` kubernetes/ ├── SKILL.md # This file — combined swarm ├── AGENTS.md # Swarm configuration and protocols ├── skills/ │ ├── orchestrator/SKILL.md # Jarvis — task routing │ ├── cluster-ops/SKILL.md # Atlas — cluster operations │ ├── gitops/SKILL.md # Flow — GitOps │ ├── security/SKILL.md # Shield — security │ ├── observability/SKILL.md # Pulse — monitoring │ ├── artifacts/SKILL.md # Cache — artifacts │ └── developer-experience/SKILL.md # Desk — DevEx ├── memory/MEMORY.md # Long-term agent memory ├── working/WORKING.md # Session progress └── logs/LOGS.md # Action audit trail ``` ## Detailed Agent Documentation See individual SKILL.md files for each agent's full capabilities, personality, and workflow instructions.

path: AGENTS.md
content: # AGENTS.md — Swarm Configuration & Protocols

## Overview

This is a **multi-agent swarm** for Kubernetes/OpenShift platform operations. Seven agents work together, each with a defined domain and personality.

## Agent Protocols

### Communication
- Agents communicate via @mentions in shared task context
- Commenting on a task → auto-subscribe to thread
- Being @mentioned → auto-subscribe
- Once subscribed → receive ALL future comments on heartbeat

### Coordination
1. Orchestrator (Jarvis) routes tasks to the right agent
2. Agents execute within their domain guardrails
3. Cross-domain issues → @mention relevant agent
4. P1 incidents → all relevant agents auto-notified

### File Structure Convention

```
skills/<agent-name>/
├── SKILL.md       # Agent personality, capabilities, workflows
└── (no scripts)   # Instruction-only — no executable code
```

### Workflow Patterns

#### Task Routing (Orchestrator)
- Analyze incoming request
- Match to agent domain
- Route with context
- Track completion

#### Daily Standup (Orchestrator)
- Compile status from all agents
- Summarize cluster health, deployments, incidents
- Flag items needing human attention

#### SLA Monitoring (Orchestrator)
- Track time since task assignment
- Alert if approaching SLA threshold
- Escalate to human if breached

#### Skill Improvement (Orchestrator)
- Monitor agent logs for errors and inefficiencies
- Suggest improvements to SKILL.md files
- Create PR for human review

## Environment Detection

Before operating, detect the cluster platform:

```bash
# Check if OpenShift
kubectl api-resources | grep openshift

# Check if EKS
kubectl get nodes -o jsonpath='{.items[0].metadata.labels}' | grep eks

# Check if AKS  
kubectl get nodes -o jsonpath='{.items[0].metadata.labels}' | grep aks

# Check if GKE
kubectl get nodes -o jsonpath='{.items[0].metadata.labels}' | grep gke
```

## Shared Context Files

| File | Purpose |
|------|---------|
| `working/WORKING.md` | Current session progress |
| `logs/LOGS.md` | Action audit trail |
| `memory/MEMORY.md` | Long-term learnings |
| `incidents/INCIDENTS.md` | Active incidents |
| `troubleshooting/TROUBLESHOOTING.md` | Known issues and resolutions |

## Safety Rules

- **Production changes**: Always require human approval
- **Destructive operations**: Never run without explicit confirmation
- **Credential access**: Use least-privilege service accounts
- **Audit trail**: Log every action to LOGS.md
- **Rollback plans**: Always prepare a rollback before any change


path: QUICKREF.md
content: # QUICK REFERENCE — Agent Operating Rules

> Print or keep open. Reference before ANY action.

---

## 🚫 NEVER Do Without Human Approval

| Action | Example |
|--------|---------|
| **DELETE anything** | `kubectl delete pod x` |
| **Modify secrets** | Create/rotate secrets |
| **Change RBAC** | Create roles, bindings |
| **Cluster-wide changes** | CRDs, webhooks, namespaces |
| **Production changes** | Deploy to prod, scale beyond limits |
| **Rollback** | Revert production |
| **Apply unknown YAML** | Unreviewed manifests |

---

## ✅ Always Do

| Action | Why |
|--------|-----|
| **Log to LOGS.md** | Every action must be traceable |
| **Read before modify** | Know current state |
| **Check impact** | What breaks if this fails? |
| **Have rollback plan** | How to undo? |
| **Update agent status** | In agents/AGENTS.md |
| **Escalate when blocked** | Better safe than sorry |

---

## 🔴 Stop & Escalate If

- Error persists after 3 retry attempts
- Cluster availability drops below 99.9%
- Security policy violation detected
- Data integrity concern
- Human denies approval request

---

## 📋 Before Any Cluster Action

```
1. READ: kubectl get <resource> -n <ns>
2. CHECK: Impact assessment
3. LOG: Intent to LOGS.md
4. APPROVE: If required, wait for human OK
5. EXECUTE: Apply change
6. VERIFY: Confirm success
7. LOG: Result to LOGS.md
```

---

## Emergency Contacts

| Issue | Agent | Human |
|-------|-------|-------|
| Cluster down | @Atlas | Escalate immediately |
| Security breach | @Shield | Escalate immediately |
| Data loss | @Atlas | Escalate immediately |
| Other | Relevant agent | Team lead |

---

## Log Locations

| Log | Purpose |
|-----|---------|
| `logs/LOGS.md` | Action audit trail |
| `memory/MEMORY.md` | Long-term learnings |
| `incidents/INCIDENTS.md` | Failures & issues |
| `troubleshooting/TROUBLESHOOTING.md` | Debug knowledge |
| `agents/AGENTS.md` | Agent status |

---

## Severity Levels

| Level | Response | Example |
|-------|----------|---------|
| CRITICAL | Immediate | Cluster down, breach |
| HIGH | < 15 min | Major feature broken |
| MEDIUM | < 1 hour | Degraded performance |
| LOW | Next day | Documentation fix |

---

*Last updated: 2026-02-24*


path: README.md
content: # Kubernetes Agent Swarm

A coordinated multi-agent system for Kubernetes and OpenShift platform operations. Seven specialized agents work together as a swarm.

## Agents

| Agent | Code Name | Domain |
|-------|-----------|--------|
| Orchestrator | Jarvis | Task routing, coordination, daily standups |
| Cluster Ops | Atlas | Cluster lifecycle, nodes, upgrades, etcd |
| GitOps | Flow | ArgoCD, Helm, Kustomize, deployments |
| Security | Shield | RBAC, policies, secrets, CVE scanning |
| Observability | Pulse | Metrics, logs, alerts, incident response |
| Artifacts | Cache | Registries, SBOM, image promotion |
| Developer Experience | Desk | Namespace provisioning, onboarding |

## Installation

```bash
clawhub install kubernetes
```

## How It Works

**Instruction-only** — no executable scripts. Each agent receives markdown instructions that describe what kubectl/oc commands to run and how to interpret output. The host's installed CLI tools do the actual work.

## Requirements

- `kubectl` (required)
- `oc` (optional, for OpenShift)
- `helm` (optional, for GitOps agent)
- `KUBECONFIG` cluster access

## Architecture

```
kubernetes/
├── SKILL.md                          # Root — combined swarm
├── skills/
│   ├── orchestrator/SKILL.md         # Jarvis
│   ├── cluster-ops/SKILL.md          # Atlas
│   ├── gitops/SKILL.md               # Flow
│   ├── security/SKILL.md             # Shield
│   ├── observability/SKILL.md        # Pulse
│   ├── artifacts/SKILL.md            # Cache
│   └── developer-experience/SKILL.md # Desk
├── memory/MEMORY.md                  # Long-term memory
├── working/WORKING.md                # Session progress
└── logs/LOGS.md                      # Audit trail
```

## Safety

- Production changes require human approval
- Destructive operations need explicit confirmation
- All actions logged to audit trail
- Least-privilege service accounts recommended

## License

MIT


path: agents/AGENTS.md
content: # Agent: Jarvis (Orchestrator)

## Identity
- **Code Name**: Jarvis
- **Session Key**: `agent:platform:orchestrator`
- **Role**: Task routing, coordination, standups

## Current Task
[To be filled by agent]

## Last Completed Task
[To be filled by agent]

## Status
IDLE | ACTIVE | ERROR

## Capabilities
- Route tasks to appropriate agents
- Coordinate cross-agent operations
- Run daily standups
- Monitor SLA compliance
- Escalate to humans when needed

## Action Log
| Timestamp | Action | Result |
|-----------|--------|--------|
| | | |

---

# Agent: Atlas (Cluster Ops)

## Identity
- **Code Name**: Atlas
- **Session Key**: `agent:platform:cluster-ops`
- **Role**: Cluster lifecycle, nodes, upgrades

## Current Task
[To be filled by agent]

## Last Completed Task
[To be filled by agent]

## Status
IDLE | ACTIVE | ERROR

## Capabilities
- Cluster health monitoring
- Node operations (cordon, drain, uncordon)
- Capacity reporting
- Upgrade pre-checks
- etcd backups

## Action Log
| Timestamp | Action | Result |
|-----------|--------|--------|
| | | |

---

# Agent: Flow (GitOps)

## Identity
- **Code Name**: Flow
- **Session Key**: `agent:platform:gitops`
- **Role**: ArgoCD, Helm, Kustomize, deployments

## Current Task
[To be filled by agent]

## Last Completed Task
[To be filled by agent]

## Status
IDLE | ACTIVE | ERROR

## Capabilities
- ArgoCD application sync
- Drift detection
- Helm diff analysis
- Image promotion
- Rollback execution

## Action Log
| Timestamp | Action | Result |
|-----------|--------|--------|
| | | |

---

# Agent: Shield (Security)

## Identity
- **Code Name**: Shield
- **Session Key**: `agent:platform:security`
- **Role**: RBAC, policies, secrets, scanning

## Current Task
[To be filled by agent]

## Last Completed Task
[To be filled by agent]

## Status
IDLE | ACTIVE | ERROR

## Capabilities
- RBAC auditing
- Network policy validation
- Secret rotation workflows
- Image vulnerability scanning
- CIS benchmark compliance
- Security audit reporting

## Action Log
| Timestamp | Action | Result |
|-----------|--------|--------|
| | | |

---

# Agent: Pulse (Observability)

## Identity
- **Code Name**: Pulse
- **Session Key**: `agent:platform:observability`
- **Role**: Metrics, logs, alerts, incidents

## Current Task
[To be filled by agent]

## Last Completed Task
[To be filled by agent]

## Status
IDLE | ACTIVE | ERROR

## Capabilities
- Alert triage and investigation
- Log search and analysis
- Metric queries
- SLO reporting
- Incident report generation

## Action Log
| Timestamp | Action | Result |
|-----------|--------|--------|
| | | |

---

# Agent: Cache (Artifacts)

## Identity
- **Code Name**: Cache
- **Session Key**: `agent:platform:artifacts`
- **Role**: Registries, SBOM, promotion, CVEs

## Current Task
[To be filled by agent]

## Last Completed Task
[To be filled by agent]

## Status
IDLE | ACTIVE | ERROR

## Capabilities
- Image scanning
- SBOM generation
- Artifact promotion
- CVE tracking
- Registry cleanup

## Action Log
| Timestamp | Action | Result |
|-----------|--------|--------|
| | | |

---

# Agent: Desk (Developer Experience)

## Identity
- **Code Name**: Desk
- **Session Key**: `agent:platform:developer-experience`
- **Role**: Namespaces, onboarding, support

## Current Task
[To be filled by agent]

## Last Completed Task
[To be filled by agent]

## Status
IDLE | ACTIVE | ERROR

## Capabilities
- Namespace provisioning
- Team onboarding
- Pod debugging
- Template generation
- Manifest creation

## Action Log
| Timestamp | Action | Result |
|-----------|--------|--------|
| | | |


path: incidents/INCIDENTS.md
content: # INCIDENTS.md — Production Incident Log

> Log all production-level failures, issues, and near-misses. Severity classification required.

---

## Last Incident: None Recorded

---

## Severity Classification

| Level | Definition | Response Time |
|-------|------------|---------------|
| `CRITICAL` | Production down, data loss risk, security breach | Immediate escalation |
| `HIGH` | Major feature impacted, degraded performance | < 15 minutes |
| `MEDIUM` | Minor impact, workarounds available | < 1 hour |
| `LOW` | Cosmetic, documentation, minor inconvenience | Next business day |

---

## Template: Log New Incident

```
## Incident: <title>

### Severity: LOW | MEDIUM | HIGH | CRITICAL

### Detected: <ISO 8601 timestamp>

### Description:
<what happened>

### Impact:
<affected systems, users, services>

### Root Cause:
<technical root cause>

### Resolution:
<steps taken to resolve>

### Follow-up Actions:
- [ ] <action> - @<assignee> - <due date>
- [ ] <action> - @<assignee> - <due date>

### Lessons Learned:
<what could be improved>

### Related Logs:
<links to LOGS.md entries>
```

---

## Incident Categories

| Category | Examples |
|----------|----------|
| `CLUSTER_FAILURE` | Node down, API server outage, etcd issues |
| `DEPLOYMENT_FAILURE` | Failed GitOps sync, helm failures |
| `SECURITY_INCIDENT` | Unauthorized access, CVE, policy violation |
| `PERFORMANCE_DEGRADATION` | High latency, resource exhaustion |
| `DATA_LOSS` | Backup failure, data corruption |
| `AUTOMATION_FAILURE` | Skill/script errors |
| `CONFIGURATION_DRIFT` | Unintended state changes |

---

## Escalation Triggers

Create incident automatically when:

1. **Cluster availability < 99.9%**
2. **Security policy violation detected**
3. **Failed deployment to production**
4. **Data integrity concern**
5. **Agent unable to resolve within 3 attempts**
6. **Human approval requested and denied**
7. **Any deletion of production resources**

---

## Post-Incident Requirements

1. Document in INCIDENTS.md within 24 hours
2. Create TROUBLESHOOTING.md entry if new problem type
3. Update MEMORY.md with lessons learned
4. Assign follow-up actions with owners
5. Schedule incident review if severity HIGH or CRITICAL


path: index.md
content: # Wiki Index

Catalog of all wiki pages, organized by category.

## Entities

> People, organizations, projects, products

## Concepts

> Ideas, theories, frameworks, methods

## Topics

> Subject areas and themes

## Sources

> Summaries of ingested source documents

## Comparisons & Analyses

> Side-by-sides, syntheses, explorations

---

_Last updated: 2026-04-09_


path: log.md
content: # Wiki Log

Chronological record of all wiki activity.

Format: `## [YYYY-MM-DD] type | Title`

Types: `ingest` | `query` | `lint` | `create` | `update`

---

_Last updated: 2026-04-09_


path: logs/LOGS.md
content: # LOGS.md — Agent Action Audit Trail

> Append EVERY agent action to this file. Format: Most recent first.

---

## 2026-02-24T00:00:00Z — Initial Setup

### Agent: system-initialization
### Action: Created logging infrastructure
### Reason: Enable persistent agent memory and audit trails for swarm operations
### Target: memory/, logs/, incidents/, troubleshooting/ directories
### Result: SUCCESS
### Next Action: Begin normal agent operations with logging

---

## Template: Log New Action

```
## [TIMESTAMP UTC]

### Agent: <agent-name>
### Action: <what was done>
### Reason: <why>
### Target: <file/system/resource>
### Result: SUCCESS | FAILURE | PARTIAL | BLOCKED
### Next Action: <planned next step>
```

---

## Log Categories

| Category | When to Log |
|----------|-------------|
| `CLUSTER_ACTION` | Any kubectl/oc command execution |
| `SKILL_EXECUTION` | Running a skill script |
| `SKILL_IMPROVEMENT` | Identified need to update/improve a skill or script |
| `DECISION` | Agent makes a decision |
| `APPROVAL_NEEDED` | Requires human approval |
| `ESCALATION` | Escalating to human or another agent |
| `ERROR` | Any error or failure |
| `SECURITY` | Security-related action |
| `RELIABILITY` | Reliability/availability impact |

---

## Required Fields Per Entry

- **Timestamp**: ISO 8601 UTC
- **Agent**: Which agent acted
- **Action**: What was done (imperative, e.g., "create", "read", "approve")
- **Reason**: Why this action was taken
- **Target**: What was affected (file, resource, cluster)
- **Result**: SUCCESS | FAILURE | PARTIAL | BLOCKED | PENDING_APPROVAL
- **Next Action**: What happens next
- **Skill Improvement** (optional): If SKILL_IMPROVEMENT category, add:
  - `Skill`: Which skill/script needs improvement
  - `Improvement Type`: SCRIPT_FIX | NEW_CAPABILITY | REFERENCE_DOC | WORKFLOW_CHANGE
  - `Suggested Fix`: Brief description of what should change

---

## SKILL_IMPROVEMENT Log Template

When an agent identifies a skill needs improvement during troubleshooting or cluster activities:

```
## [TIMESTAMP UTC]

### Agent: <agent-name>
### Action: <what was done>
### Reason: <why>
### Target: <file/system/resource>
### Result: SUCCESS | FAILURE | PARTIAL | BLOCKED | PENDING_APPROVAL
### Category: SKILL_IMPROVEMENT
### Skill: <skill-name>/<script-or-file>
### Improvement Type: SCRIPT_FIX | NEW_CAPABILITY | REFERENCE_DOC | WORKFLOW_CHANGE
### Suggested Fix: <description of improvement>
### Next Action: <planned next step>
```

---

## Security Logging Requirements

All actions involving the following MUST be logged with HIGH priority:
- Secret handling (read, write, rotate)
- RBAC changes
- Network policy modifications
- Cluster-wide resources
- Production environment changes
- User credential operations
- Deletion of any resource

---

## Approval Workflow Logging

```
### Approval Requested
### Approver: <human-user>
### Requested By: <agent-name>
### Request Type: DELETE | MODIFY_PROD | RBAC_CHANGE | SECRET_WRITE | CLUSTER_WIDE
### Target: <resource>
### Status: PENDING | APPROVED | REJECTED
### Response: <human response>
```


path: memory/MEMORY.md
content: # MEMORY.md — Persistent Agent Learning

> Append-only learning log. Only store important long-term insights.

---

## Last Updated
<!-- UPDATE_TIMESTAMP -->

---

## Learned: Repository Foundation

### Context
Initial setup of cluster-agent-swarm-skills repository. Contains skills for 7 specialized agents managing Kubernetes/OpenShift operations.

### Decision
Established comprehensive logging infrastructure including MEMORY.md, LOGS.md, INCIDENTS.md, and TROUBLESHOOTING.md to enable persistent agent memory and audit trails.

### Why
Without structured memory, agents lose context between sessions. This repository serves as the single source of truth for cluster operations automation.

### Future Implication
All future agent actions should update relevant log files. Important learnings should be documented here for swarm-wide awareness.

---

## Template: Add New Learning

```
## Learned: <topic>

### Context
<what happened>

### Decision
<what was decided>

### Why
<reasoning>

### Future Implication
<how this affects future actions>
```

---

## Critical Rules (Always Remember)

1. **NEVER delete without human approval** — Any deletion action requires explicit human consent
2. **Human review mandatory** — Important decisions require human-in-the-loop
3. **Log everything** — Every action must be traceable
4. **Reliability first** — System stability > new features
5. **Security default** — Deny by default, approve by exception


path: raw/README.md
content: # raw/ — Source Documents

Drop source files here. Supported formats:
- `.md` — Markdown articles, notes
- `.txt` — Plain text
- `.pdf` — PDFs (agent can extract text)
- `.png`, `.jpg`, `.gif` — Images (go in `assets/`)

## Conventions

- Files are **immutable** — the agent reads but never modifies them
- Use descriptive filenames: `YYYY-MM-DD-title.md`
- Images go in `assets/` subdirectory
- The agent creates wiki summaries in `wiki/` pointing back to these sources


path: troubleshooting/TROUBLESHOOTING.md
content: # TROUBLESHOOTING.md — Debugging Knowledge Base

> Log debugging knowledge, root causes, and solutions. Build institutional memory.

---

## Last Updated: 2026-02-24

---

## Template: Add New Entry

```
## Problem: <title>

### Symptoms
- <observable symptom 1>
- <observable symptom 2>

### Root Cause
<technical cause>

### Fix
<solution steps>

### Prevention
<how to prevent recurrence>

### Related Skills
- skill:cluster-ops:health-check
- skill:observability:alert-triage
```

---

## Common Problem Patterns

### Cluster Issues

| Problem | Quick Check | Skill |
|---------|-------------|-------|
| Node Not Ready | `kubectl get nodes` | cluster-ops:health-check |
| API Server Down | `kubectl cluster-info` | cluster-ops:health-check |
| Pod CrashLoopBackOff | `kubectl describe pod <name>` | dev-experience:debug-pod |
| etcd Issues | `kubectl exec -n kube-system etcd-0 -- etcdctl` | cluster-ops:etcd-backup |

### GitOps Issues

| Problem | Quick Check | Skill |
|---------|-------------|-------|
| Sync Failure | `argocd app get <app>` | gitops:argocd-app-sync |
| Drift Detected | `argocd app diff <app>` | gitops:drift-detect |
| Helm Upgrade Failed | `helm list -A` | gitops:helm-diff |

### Security Issues

| Problem | Quick Check | Skill |
|---------|-------------|-------|
| RBAC Misconfiguration | `kubectl auth can-i` | security:rbac-audit |
| Vulnerable Image | `trivy image <image>` | security:image-scan |
| Secret Exposed | Check pod logs/env | security:secret-rotation |

---

## Diagnostic Commands

### Quick Cluster Health
```bash
kubectl get nodes -o wide
kubectl get pods -A -o wide
kubectl get events -A --sort-by='.lastTimestamp'
```

### OpenShift Specific
```bash
oc get nodes -o wide
oc get co
oc status
```

### Logs & Metrics
```bash
kubectl logs <pod> -n <ns> --tail=100
kubectl top nodes
kubectl top pods -A
```

---

## Escalation Matrix

| Issue Type | First Agent | Escalation |
|------------|-------------|------------|
| Node issues | Atlas (cluster-ops) | @human |
| Deployment | Flow (gitops) | @human |
| Security | Shield (security) | @human IMMEDIATE |
| Performance | Pulse (observability) | @Atlas |
| Developer | Desk (dev-experience) | @Flow |

---

## Investigation Workflow

1. **Observe** — Gather symptoms, check status
2. **Hypothesize** — Form theory of cause
3. **Investigate** — Run diagnostic commands
4. **Verify** — Confirm root cause
5. **Fix** — Apply solution (requires approval if production)
6. **Document** — Log to TROUBLESHOOTING.md
7. **Prevent** — Add automation/guardrails

---

## Never Do Without Human Approval

- Delete any resource
- Modify RBAC
- Change cluster-wide policies
- Rollback production deployment
- Modify secrets
- Scale beyond limits
- Apply unknown YAML
- Execute ad-hoc scripts on production


path: wiki/README.md
content: # wiki/ — Generated Wiki Pages

Maintained by the LLM agent. Browse freely, but let the agent handle writing.

## Page Types

| Type | Directory | Example |
|------|-----------|---------|
| Entity | `wiki/entities/` | People, orgs, projects |
| Concept | `wiki/concepts/` | Ideas, frameworks, methods |
| Topic | `wiki/topics/` | Subject areas |
| Source summary | `wiki/sources/` | Summaries of ingested docs |
| Comparison | `wiki/comparisons/` | Side-by-sides |
| Analysis | `wiki/analyses/` | Deep dives |

## Conventions

- Cross-references use `[[wiki-links]]` for Obsidian
- Every page listed in `index.md`
- Every change logged in `log.md`


path: working/SESSION.md
content: # Cluster Session Context

> This file tracks the current agent's working context including environment, cluster details, and permissions.

---

## Current Session

### Agent
- **Name**: 
- **Session Started**: 
- **Task**: 

### Environment Context
- **Environment**: dev | qa | staging | prod
- **Cluster Name**: 
- **Cluster Type**: openshift | kubernetes | eks | aks | gke | rosa | aro
- **Cluster Version**: 
- **Context Name**: 
- **Namespace**: 

### Cluster Information (Populated on First Run)

#### Cluster Details
| Component | Version |
|-----------|---------|
| Platform | |
| Kubernetes API | |
| etcd | |
| Controller Manager | |
| Scheduler | |
| Kubelet | |
| Kube-proxy | |

#### Key Components
| Component | Version | Namespace |
|-----------|---------|-----------|
| ArgoCD / Flux | | |
| Prometheus | | |
| Grafana | | |
| Ingress/Nginx | | |
| Service Mesh | | |
| cert-manager | | |
| Vault | | |

#### Operator Versions (OpenShift/OLM)
| Operator | Version | Namespace |
|----------|---------|-----------|
| | | |

### Permission Context
- **Can Delete**: NO
- **Can Modify Prod**: NO
- **Can Create RBAC**: NO
- **Requires Approval**: YES (see AGENTS.md)

### Change Constraints by Environment

| Environment | Delete | Modify Prod | RBAC | Scale | Secrets |
|-------------|-------|------------|------|-------|---------|
| **dev** | Approval | Approval | Approval | Auto | Approval |
| **qa** | Approval | Approval | Approval | Approval | Approval |
| **staging** | Approval | Approval | Approval | Approval | Approval |
| **prod** | NEVER | NEVER | NEVER | NEVER | NEVER |

---

## Session Activity Log

| Timestamp | Action | Details |
|-----------|--------|---------|
| | | |

---

*This file is updated at session start and whenever context changes.*


path: working/WORKING.md
content: # WORKING.md — Agent Progress Tracking

> This file is the single source of truth for agent progress. MUST be updated at session start and end.

---

## Session Start Protocol

Before starting ANY work, agents MUST:

1. **Read SESSION.md** - Check environment context (dev/qa/staging/prod)
2. **Read this file** - Check current progress
3. **Check cluster access** - Verify can connect to cluster

```bash
# Required at session start
cat working/SESSION.md    # Environment context
cat working/WORKING.md    # Your progress
cat logs/LOGS.md | head -50  # Recent activity
```

---

## Environment Context (from SESSION.md)

| Key | Value |
|-----|-------|
| Environment | |
| Cluster Type | |
| Cluster Name | |
| Permission Level | |

### Environment Constraints

| Environment | Can Delete | Can Modify Prod | Can RBAC | Can Scale | Can Secrets |
|-------------|------------|-----------------|----------|-----------|--------------|
| **dev** | Approval | Approval | Approval | Auto | Approval |
| **qa** | Approval | Approval | Approval | Approval | Approval |
| **staging** | Approval | Approval | Approval | Approval | Approval |
| **prod** | NEVER | NEVER | NEVER | NEVER | NEVER |

---

## Agent Progress Templates

Copy the appropriate template for your agent at session start. Update before ending session.

---

## orchestrator (Jarvis)

### Current Session
- Started: 
- Task: 
- Environment: 
- Environment: 

### Completed This Session
- 

### Remaining Tasks
- 

### Blockers
- None

### Next Action
- 

---

## cluster-ops (Atlas)

### Current Session
- Started: 
- Task: 
- Environment: 
- Environment: 

### Completed This Session
- 

### Remaining Tasks
- 

### Blockers
- None

### Next Action
- 

---

## gitops (Flow)

### Current Session
- Started: 
- Task: 
- Environment: 

### Completed This Session
- 

### Remaining Tasks
- 

### Blockers
- None

### Next Action
- 

---

## security (Shield)

### Current Session
- Started: 
- Task: 
- Environment: 

### Completed This Session
- 

### Remaining Tasks
- 

### Blockers
- None

### Next Action
- 

---

## observability (Pulse)

### Current Session
- Started: 
- Task: 
- Environment: 

### Completed This Session
- 

### Remaining Tasks
- 

### Blockers
- None

### Next Action
- 

---

## artifacts (Cache)

### Current Session
- Started: 
- Task: 
- Environment: 

### Completed This Session
- 

### Remaining Tasks
- 

### Blockers
- None

### Next Action
- 

---

## developer-experience (Desk)

### Current Session
- Started: 
- Task: 
- Environment: 

### Completed This Session
- 

### Remaining Tasks
- 

### Blockers
- None

### Next Action
- 

---

## Context Management Rules

1. **Read at session start** - Always read this file before starting work
2. **Update before ending** - Document what you did and what remains
3. **Commit with update** - Git commit should include WORKING.md changes
4. **Be specific** - "Fixed node drain issue" not "worked on stuff"
5. **Next action clear** - Next agent should know exactly what to do

---

*Last updated: 2026-02-24*


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)