plural Gitops skills

go/deployment-operator/dockerfiles/agent-harness/base.Dockerfile

@@ -105,11 +105,20 @@ RUN groupadd -g 65532 nonroot && \
 WORKDIR /plural
 
 COPY deployment-operator/dockerfiles/agent-harness/system /plural/system
-
-RUN mkdir -p /plural/.opencode && \
-    mkdir -p /plural/.claude && \
-    mkdir -p /plural/.gemini && \
-    mkdir -p /plural/.codex
+COPY deployment-operator/dockerfiles/agent-harness/skills /plural/skills
+
+# Copy bundled skills into each runtime's discovery path under /plural.
+# Shell vars use single `$` here (not `$$`) — `$$` expands to the shell PID in RUN.
+RUN for provider in .claude .codex .gemini .opencode; do \
+      mkdir -p "/plural/${provider}/skills"; \
+    done && \
+    for skill in /plural/skills/*/; do \
+      name="$(basename "$skill")"; \
+      [ -f "$skill/SKILL.md" ] || continue; \
+      for provider in .claude .codex .gemini .opencode; do \
+        cp -a "$skill" "/plural/${provider}/skills/${name}"; \
+      done; \
+    done
 
 RUN chown -R 65532:65532 /plural && \
     mkdir -p /run/user/65532 && \

go/deployment-operator/dockerfiles/agent-harness/skills/plural-cd-extensions/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: plural-cd-extensions
+description: Advanced Plural CD patterns including service-of-services, multi-source services, Liquid/Lua templating, observers, and pipelines. Use when implementing advanced continuous deployment features in Plural GitOps.
+---
+# Official Continuous Deployment Extensions
+
+This file maps common "advanced" Plural CD workflows to official docs so agents can quickly
+jump from CRD basics to the right extension pattern.
+
+Primary docs entrypoint:
+- https://docs.plural.sh/plural-features/continuous-deployment
+
+CRD field reference (all management kinds):
+- https://docs.plural.sh/api-reference/kubernetes/management-api-reference
+
+---
+
+## Service-of-services (recursive GitOps)
+
+Use this when one `ServiceDeployment` should apply a folder containing other
+`deployments.plural.sh` objects (`ServiceDeployment`, `GlobalService`, `InfrastructureStack`, etc.).
+
+Official docs:
+- https://docs.plural.sh/plural-features/continuous-deployment/git-service
+
+Agent guidance:
+- Treat this as a composition/orchestration layer, not an app workload.
+- Keep child objects in deterministic folder paths; avoid mixing unrelated environments.
+- Expect reconciliation to overwrite manual edits to generated/child resources.
+
+---
+
+## GlobalService fleet templating
+
+Use `GlobalService` when you need one service template replicated across many clusters,
+with small per-cluster overrides.
+
+Official docs:
+- https://docs.plural.sh/plural-features/continuous-deployment/global-service
+- https://docs.plural.sh/plural-features/continuous-deployment/service-templating
+
+Agent guidance:
+- Prefer `spec.template` + `spec.context.raw` for cluster-specific values.
+- Use cluster metadata/tags for routing and Liquid variables for substitutions.
+- If per-cluster behavior diverges heavily, split into multiple `ServiceDeployment`s.
+
+---
+
+## Multi-source services
+
+Use this when one deployment needs manifests from multiple sources (for example,
+operator chart from Helm + CRs from Git).
+
+Official docs:
+- https://docs.plural.sh/plural-features/continuous-deployment/multi-source-services
+
+Agent guidance:
+- Model each source explicitly via `spec.sources`.
+- Control render behavior with `spec.renderers` by path.
+- Keep source path boundaries clear to avoid accidental file shadowing.
+
+---
+
+## Dynamic Helm values via Lua
+
+Use this for runtime generation of Helm values or value files from context.
+
+Official docs:
+- https://docs.plural.sh/plural-features/continuous-deployment/helm-service
+- https://docs.plural.sh/plural-features/continuous-deployment/lua
+
+Agent guidance:
+- Keep Lua logic deterministic and side-effect free.
+- Reserve Lua for cases where static values files or Liquid cannot express required logic.
+- Document expected input context near the script.
+
+---
+
+## Resource application and sync behavior
+
+Official docs:
+https://docs.plural.sh/plural-features/continuous-deployment/resource-application-logic
+
+Supported annotations on **any managed manifest**:
+
+| Annotation | Effect |
+|------------|--------|
+| `deployment.plural.sh/sync-options: Replace=True` | Replace semantics (PUT) instead of server-side apply — drops fields absent from desired manifest |
+| `deployment.plural.sh/sync-options: Force=True` | On apply failure (e.g. immutable field), delete and recreate |
+| `deployment.plural.sh/sync-wave: "<n>"` | Apply ordering — lower numbers first |
+| `argocd.argoproj.io/sync-options` | Argo CD-compatible alias (same semantics) |
+| `argocd.argoproj.io/sync-wave` | Argo CD-compatible wave alias |
+
+Hook delete policies and lifecycle hooks are also supported — see the full doc for
+pre/post-sync hook resources.
+
+Agent guidance:
+- Use sync waves for strict ordering (CRDs → namespace → operator → app).
+- Prefer minimal overrides; document non-obvious ordering in commit messages.
+
+---
+
+## Event-driven updates and promotion workflows
+
+Use observers/pipelines when deployments should respond to upstream changes or environment
+promotion rules.
+
+Official docs:
+- https://docs.plural.sh/plural-features/continuous-deployment/observer
+- https://docs.plural.sh/plural-features/continuous-deployment/pipelines
+
+Agent guidance:
+- Use `Observer` for trigger detection (registry/git/other sources) and action execution.
+- Use `Pipeline` for deterministic or AI-assisted promotion across environments.
+- Keep promotion stages explicit and test-gated.
+
+---
+
+## Operator behavior and ownership boundaries
+
+The deployment operator is an **API-driven frontend** — it automates Console provisioning and
+applies manifests on clusters; it does not replace Terraform for cluster creation.
+
+Official docs:
+- https://docs.plural.sh/plural-features/continuous-deployment/deployment-operator
+- https://docs.plural.sh/plural-features/continuous-deployment/management-controllers-reconciliation-logic
+
+Agent guidance:
+- **Creation mode** CRs: edit the GitOps YAML as the source of truth.
+- **Read-only mode** (`.status.readonly: true`): resource owned elsewhere — update Terraform /
+  Console directly, not the observing CR.
+- Avoid conflicting writes: Terraform owns infra, Plural CD owns k8s app manifests unless
+  explicitly composed via service-of-services.
+

go/deployment-operator/dockerfiles/agent-harness/skills/plural-git-repository/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: plural-git-repository
+description: Explains GitRepository CRs and how GitOps repos relate to source repos. Use when editing Plural GitOps repos, ServiceDeployment repositoryRef, spec.git.folder, or deployments.plural.sh GitRepository CRs.
+---
+# GitRepository
+
+Plural CD separates **where CRs are defined** from **where application or IaC code lives**:
+
+| Repo role | Contents | Typical path |
+|---|---|---|
+| **GitOps repo** | Plural management CRs (`ServiceDeployment`, `GitRepository`, `Cluster`, …) | `manifests/*.yaml` |
+| **Source repo** | Helm charts, Kustomize, raw YAML, Terraform, etc. | paths referenced by `spec.git.folder` |
+
+A `GitRepository` CR registers a **source repo** in Console so `ServiceDeployment` and
+`InfrastructureStack` can clone it without repeating the URL.
+
+---
+
+## GitRepository CR
+
+Cluster-scoped (`deployments.plural.sh/v1alpha1`, no namespace):
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: GitRepository
+metadata:
+  name: my-app-repo
+spec:
+  url: https://github.com/my-org/my-app.git
+  connectionRef:          # optional — reuse an ScmConnection for auth
+    name: github
+  credentialsRef:         # optional — Secret with privateKey, username, password, …
+    name: my-app-repo-credentials
+    namespace: infra
+```
+
+| Field | Purpose |
+|---|---|
+| `spec.url` | HTTPS or SSH git URL — **immutable** after creation |
+| `spec.connectionRef` | Existing SCM connection for credentials |
+| `spec.credentialsRef` | Direct Secret reference for repo auth |
+| `status.health` | `PULLABLE` or `FAILED` — Console can reach the repo |
+
+Find existing registrations in the GitOps repo:
+
+```bash
+grep -rl 'kind: GitRepository' manifests/
+```
+
+---
+
+## How consumers use it
+
+`ServiceDeployment` and `InfrastructureStack` point at a `GitRepository` via `repositoryRef`,
+then specify **where inside that repo** to read with `spec.git`:
+
+```yaml
+apiVersion: deployments.plural.sh/v1alpha1
+kind: ServiceDeployment
+metadata:
+  name: my-app-prod
+  namespace: infra
+spec:
+  cluster: prod-eu-1
+  repositoryRef:
+    name: my-app-repo
+  git:
+    ref: main
+    folder: deploy/k8s
+  namespace: my-app
+```
+
+| Field | Purpose |
+|---|---|
+| `repositoryRef.name` | Name of the `GitRepository` CR |
+| `spec.git.ref` | Branch, tag, or commit |
+| `spec.git.folder` | Subdirectory with manifests, chart, or Terraform |
+
+**Inline URL** (no `GitRepository` CR) is also supported — set `spec.git.url` directly on the
+consumer CR instead of `repositoryRef`.
+
+---
+
+## Working in an unfamiliar repo
+
+**If you are in the GitOps repo** — read `manifests/` for `GitRepository`, `ServiceDeployment`,
+and `Cluster` CRs. Use `Cluster` resources with `apiVersion: deployments.plural.sh/v1alpha1`
+(not CAPI `cluster.x-k8s.io`) to find valid `spec.handle` values for `spec.cluster`.
+
+**If you are in a source repo** — find the matching `GitRepository.spec.url` and follow
+`repositoryRef` + `spec.git.folder` on the consuming CRs in the GitOps repo's `manifests/`.
+
+---
+
+## Official docs
+
+- [Management API Reference — GitRepository](https://docs.plural.sh/api-reference/kubernetes/management-api-reference)
+- [Git-sourced services](https://docs.plural.sh/plural-features/continuous-deployment/git-service)
+- [Deployment operator](https://docs.plural.sh/plural-features/continuous-deployment/deployment-operator)
+
+Plural CD is **Flux-interoperable** for source types.