plural Gitops skills

[zreigz]

Test Plan

Test environment: https://console.your-env.onplural.sh/

Checklist

• I have added a meaningful title and summary to convey the impact of this PR to a user.
• If required, I have updated the Plural documentation accordingly.
• I have added tests to cover my changes.
• I have deployed the agent to a test environment and verified that it works as expected (required only when changing agent code).

Plural Flow: console

[linear]

PROD-4935

[greptile-apps]

Greptile Summary

This PR adds a skills/ directory of domain-knowledge reference files for Plural GitOps and wires them into all three agent system prompt templates (analyze, babysit, write). The Dockerfile is updated with a single COPY to bundle the skills into the agent image at /plural/skills.

• Four new skill files (repo-structure.md, infrastructure-stack.md, services.md, official-cd-extensions.md) and an index README.md provide field-level guidance on Plural CRDs, reconciliation modes, Liquid templating, IaC stack configuration, and advanced CD patterns.
• All three system templates receive an identical "Plural GitOps skills" section instructing agents to read the skill files when working on a Plural-managed GitOps repo; the README.md index is instructed to be read first but is listed last in all three blocks, which could confuse sequential readers.
• The cascade deletion example in services.md shows delete: true and detach: false together in one YAML block with an "(alternatively)" comment, which may mislead an agent into treating them as co-settable rather than mutually exclusive options.

Confidence Score: 4/5

The change is entirely additive — new documentation files and instruction text in system templates — with no modifications to Go code, APIs, or data-handling logic. The risk of breakage is low.

All changes are markdown documentation and Dockerfile copy instructions. The two findings are clarity issues in the content: one in the cascade YAML example and one in the read README first instruction ordering. Neither would cause runtime failures, but both could produce incorrect agent behavior when the skill files are consumed.

go/deployment-operator/dockerfiles/agent-harness/skills/services.md (cascade example) and the README.md ordering in all three system templates.

Important Files Changed

Filename	Overview
go/deployment-operator/dockerfiles/agent-harness/base.Dockerfile	Adds a single COPY instruction to bundle the new skills/ directory into the Docker image at /plural/skills, consistent with the existing system/ copy pattern.
go/deployment-operator/dockerfiles/agent-harness/skills/README.md	New skills index file with architecture overview and quick-start checklist. The "Read README.md first" instruction appears at the end after the other skill files are listed, which is confusing for agents that read sequentially.
go/deployment-operator/dockerfiles/agent-harness/skills/services.md	Comprehensive ServiceDeployment vs GlobalService reference. The cascade deletion example YAML conflates two mutually exclusive options in one block with an ambiguous "(alternatively)" comment, which could mislead agents.
go/deployment-operator/dockerfiles/agent-harness/skills/infrastructure-stack.md	New reference file for InfrastructureStack CRs; covers type mapping, configuration fields, lifecycle, state management, and common mistakes. Content looks accurate and complete.
go/deployment-operator/dockerfiles/agent-harness/skills/official-cd-extensions.md	New reference file cataloguing advanced CD patterns (service-of-services, GlobalService fleet templating, multi-source, Lua Helm, sync options, observers, pipelines) with official doc links. Well-structured and concise.
go/deployment-operator/dockerfiles/agent-harness/skills/repo-structure.md	New reference file describing GitOps repo layout, Cluster/GitRepository CRs, reconciliation modes, Liquid templating variables, and namespace conventions. Content is accurate and well-documented.
go/deployment-operator/dockerfiles/agent-harness/system/analyze.md.tmpl	Injects the new "Plural GitOps skills" section before the hard rules. README.md is listed last but instructed to be read first (same issue in all three template files).
go/deployment-operator/dockerfiles/agent-harness/system/babysit.md.tmpl	Injects the identical "Plural GitOps skills" block before the MCP tool hints. Same README.md ordering issue as analyze.md.tmpl and write.md.tmpl.
go/deployment-operator/dockerfiles/agent-harness/system/write.md.tmpl	Injects the identical "Plural GitOps skills" block before the MCP tool hints. Same README.md ordering issue as the other two template files.

Comments Outside Diff (2)

1. go/deployment-operator/dockerfiles/agent-harness/skills/services.md, line 868-876 (link)

   Misleading cascade example YAML

   The deletion cascade block shows delete: true and detach: false set simultaneously with an "(alternatively)" comment on detach. This is confusing: an agent reading the YAML literally would see both fields set in the same object (which is syntactically valid but semantically odd), while the comment implies they are mutually exclusive options. The risk is that an agent generates a cascade block with both delete: true and detach: true set, or is uncertain which field to use. Consider splitting these into two separate annotated examples (Option A / Option B) to make the mutual-exclusivity explicit.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

2. go/deployment-operator/dockerfiles/agent-harness/system/analyze.md.tmpl, line 967-987 (link)

   README.md listed last but instructed to be read first

   The section bullet-lists the four specific skill files first, then ends with "Read the /plural/skills/README.md index first for architecture context and a quick-start checklist." An agent following the list top-to-bottom will read the four skill files before seeing the "read first" instruction. The same pattern is repeated identically in babysit.md.tmpl and write.md.tmpl. Moving README.md to the top of the list (or rewording to "also read") would make the intended reading order unambiguous.

_{Reviews (1): Last reviewed commit: "update" | Re-trigger Greptile}

[michaeljguarino]

I don't know if this is formatted in the standard way for skill loading, make sure it's in line with claude code's spec (which is followed elsewhere)