agent-skill-kit 3.9.135

package/.agent/skills/gitops/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: gitops
+description: >-
+  GitOps workflows with ArgoCD and Flux for declarative Kubernetes deployments.
+  Use when setting up GitOps, ArgoCD sync, or Kubernetes declarative infrastructure.
+  NOT for simple deploys (use vercel-deploy) or general CI/CD (use cicd-pipeline).
+category: devops-architect
+triggers: ["GitOps", "ArgoCD", "Flux", "Kubernetes", "declarative deployment"]
+coordinates_with: ["cicd-pipeline", "server-ops", "yaml-linter"]
+success_metrics: ["100% manual sync for production", "0 secrets in git repo"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# GitOps Workflow — Declarative Kubernetes Delivery
+
+> Git is the single source of truth. Continuous reconciliation. No auto-sync to production.
+
+---
+
+## Prerequisites
+
+**Required:** Kubernetes cluster, `kubectl`, ArgoCD or Flux installed.
+
+---
+
+## When to Use
+
+| Situation | Action |
+|-----------|--------|
+| K8s deployment needed | Choose ArgoCD or Flux via decision tree |
+| CD pipeline setup | Configure sync policies per environment |
+| Secret management | Use Sealed Secrets or External Secrets (no plaintext) |
+| Multi-environment | Set up staging → production promotion |
+| Architecture review | Read `rules/engineering-spec.md` |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| ArgoCD vs Flux decision (4 criteria) | CI pipeline (→ cicd-pipeline) |
+| Sync policy selection (4 policies) | Server management (→ server-ops) |
+| Repository structure template | Git operations (→ git-workflow) |
+| OpenGitOps compliance (4 principles) | Cluster provisioning |
+| Secret management strategy | Helm chart development |
+
+**Expert decision skill:** Produces architecture decisions. No cluster modifications.
+
+---
+
+## OpenGitOps Principles (4 — All Required)
+
+| # | Principle | Requirement |
+|---|-----------|-------------|
+| 1 | Declarative | Entire system described declaratively |
+| 2 | Versioned | Desired state stored in Git |
+| 3 | Pulled | Agents pull desired state (not pushed) |
+| 4 | Reconciled | Agents continuously reconcile actual vs desired |
+
+---
+
+## ArgoCD vs Flux Decision Tree
+
+| Criterion | ArgoCD | Flux |
+|-----------|--------|------|
+| Web UI | ✅ Rich dashboard | ❌ CLI only |
+| Multi-cluster | ✅ Native support | ⚠️ Requires setup |
+| Helm support | ✅ Native | ✅ Native |
+| Learning curve | Medium | Lower |
+
+**Rule:** needs_ui=true OR cluster_count>1 → **ArgoCD**. Otherwise → **Flux**.
+
+---
+
+## Sync Policies (4)
+
+| Policy | Environment | Behavior |
+|--------|-------------|----------|
+| **Manual** | Production | Requires explicit approval |
+| **Auto** | Dev, Staging | Deploys on Git push |
+| **Prune** | All | Removes resources not in Git |
+| **Self-Heal** | All | Reverts manual cluster changes |
+
+**Safety:** Production is ALWAYS manual sync. No exceptions.
+
+---
+
+## Repository Structure
+
+```
+gitops-repo/
+├── apps/
+│   ├── production/
+│   └── staging/
+├── infrastructure/
+│   ├── ingress-nginx/
+│   └── cert-manager/
+└── argocd/
+    └── applications/
+```
+
+---
+
+## Safety Rules (Non-Negotiable)
+
+| Rule | Enforcement |
+|------|-------------|
+| No auto-sync to production | Sync policy = manual |
+| No secrets in Git | Sealed Secrets / External Secrets |
+| Rollback tested | Rollback procedure in promotion workflow |
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_MISSING_CLUSTER_COUNT` | Yes | Cluster count not provided |
+| `ERR_MISSING_ENVIRONMENTS` | Yes | Environment list not provided |
+| `ERR_INVALID_ENVIRONMENT` | Yes | Environment name not recognized |
+| `ERR_REFERENCE_NOT_FOUND` | No | Reference file missing |
+
+**Zero internal retries.** Deterministic; same context = same recommendation.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Auto-sync to production | Manual sync with approval |
+| Store secrets in Git | Sealed Secrets / External Secrets |
+| Push-based deployment | Pull-based reconciliation |
+| Skip rollback testing | Test rollback on every release |
+| Use imperative `kubectl apply` | Declarative manifests in Git |
+
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [argocd-setup.md](rules/argocd-setup.md) | ArgoCD installation and config | ArgoCD selected |
+| [sync-policies.md](rules/sync-policies.md) | Sync policy deep dive | Policy configuration |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec | Architecture review |
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `cicd-pipeline` | Skill | CI/CD pipeline |
+| `server-ops` | Skill | Server management |
+| `git-workflow` | Skill | Git operations |
+| `/launch` | Workflow | Deployment |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/gitops/rules/_sections.md

@@ -0,0 +1,25 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Argocd (argocd)
+
+**Impact:** LOW  
+**Description:** Argocd patterns and best practices.
+
+## 2. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+## 3. Sync (sync)
+
+**Impact:** LOW  
+**Description:** Sync patterns and best practices.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/gitops/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/gitops/rules/argocd-setup.md

@@ -0,0 +1,148 @@
+---
+title: ArgoCD Setup and Configuration
+impact: MEDIUM
+tags: gitops
+---
+
+# ArgoCD Setup and Configuration
+
+> Installation, access, SSO, and RBAC configuration for ArgoCD.
+
+---
+
+## Installation Methods
+
+### 1. Standard Installation
+```bash
+kubectl create namespace argocd
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
+```
+
+### 2. High Availability Installation
+```bash
+kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml
+```
+
+### 3. Helm Installation
+```bash
+helm repo add argo https://argoproj.github.io/argo-helm
+helm install argocd argo/argo-cd -n argocd --create-namespace
+```
+
+## Initial Configuration
+
+### Access ArgoCD UI
+```bash
+# Port forward
+kubectl port-forward svc/argocd-server -n argocd 8080:443
+
+# Get initial admin password
+argocd admin initial-password -n argocd
+```
+
+### Configure Ingress
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: argocd-server-ingress
+  namespace: argocd
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt-prod
+    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
+    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: argocd.example.com
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: argocd-server
+            port:
+              number: 443
+  tls:
+  - hosts:
+    - argocd.example.com
+    secretName: argocd-secret
+```
+
+## CLI Configuration
+
+### Login
+```bash
+argocd login argocd.example.com --username admin
+```
+
+### Add Repository
+```bash
+argocd repo add https://github.com/org/repo --username user --password token
+```
+
+### Create Application
+```bash
+argocd app create my-app \
+  --repo https://github.com/org/repo \
+  --path apps/my-app \
+  --dest-server https://kubernetes.default.svc \
+  --dest-namespace production
+```
+
+## SSO Configuration
+
+### GitHub OAuth
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-cm
+  namespace: argocd
+data:
+  url: https://argocd.example.com
+  dex.config: |
+    connectors:
+      - type: github
+        id: github
+        name: GitHub
+        config:
+          clientID: $GITHUB_CLIENT_ID
+          clientSecret: $GITHUB_CLIENT_SECRET
+          orgs:
+          - name: my-org
+```
+
+## RBAC Configuration
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: argocd-rbac-cm
+  namespace: argocd
+data:
+  policy.default: role:readonly
+  policy.csv: |
+    p, role:developers, applications, *, */dev, allow
+    p, role:operators, applications, *, */*, allow
+    g, my-org:devs, role:developers
+    g, my-org:ops, role:operators
+```
+
+## Best Practices
+
+1. Enable SSO for production
+2. Implement RBAC policies
+3. Use separate projects for teams
+4. Enable audit logging
+5. Configure notifications
+6. Use ApplicationSets for multi-cluster
+7. Implement resource hooks
+8. Configure health checks
+9. Use sync windows for maintenance
+10. Monitor with Prometheus metrics
+
+---
+
+⚡ PikaKit v3.9.134