@agentspec/codegen 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,151 @@
1
+ # AgentSpec → Helm Chart Generation Skill
2
+
3
+ You are generating a production-ready **Helm chart** from an AgentSpec manifest JSON.
4
+ The universal output format, reference syntax, and quality rules are in the guidelines prepended above.
5
+
6
+ ## What You Are Generating
7
+
8
+ A Helm chart that deploys the agent alongside the `agentspec-sidecar` as a sidecar container.
9
+ The chart is framework-agnostic — it wraps whatever container image the agent runs in.
10
+
11
+ ## File Generation Rules
12
+
13
+ | File | When to generate |
14
+ |---|---|
15
+ | `Chart.yaml` | Always — chart metadata (name, version, description from manifest) |
16
+ | `values.yaml` | Always — defaults for all configurable values |
17
+ | `templates/deployment.yaml` | Always — agent + agentspec-sidecar containers |
18
+ | `templates/service.yaml` | Always — ClusterIP exposing agent and sidecar ports |
19
+ | `templates/configmap.yaml` | Always — non-secret env vars (MODEL_PROVIDER, MODEL_ID, AGENT_NAME) |
20
+ | `templates/secret.yaml` | Always — Opaque secret; all `$env:` refs from manifest listed as required keys |
21
+ | `templates/serviceaccount.yaml` | Always — dedicated service account with optional IRSA annotations |
22
+ | `templates/ingress.yaml` | When `spec.api` is set — optional ingress controlled by `values.ingress.enabled` |
23
+ | `templates/_helpers.tpl` | Always — reusable template helpers (name, labels, selectorLabels, fullname) |
24
+ | `.helmignore` | Always — standard Helm ignore file |
25
+ | `README.md` | Always — installation instructions, required env vars, upgrade guidance |
26
+
27
+ ## AgentSpec → Helm Mapping
28
+
29
+ | Manifest field | Helm target |
30
+ |---|---|
31
+ | `metadata.name` | Chart name, resource names, app labels |
32
+ | `metadata.version` | `Chart.yaml appVersion` |
33
+ | `metadata.description` | `Chart.yaml description` |
34
+ | `spec.api.port` | Container port, Service port, `values.service.port` |
35
+ | `spec.model.provider` | `values.config.modelProvider` in ConfigMap |
36
+ | `spec.model.id` | `values.config.modelId` in ConfigMap |
37
+ | `spec.requires.envVars[]` | Keys in Secret template + listed in README as required |
38
+ | `spec.requires.services[]` | Listed in README as external dependencies |
39
+ | `spec.requires.minimumMemoryMB` | `values.resources.requests.memory` |
40
+
41
+ ## Invariants
42
+
43
+ - **`agentspec-sidecar` is always included** as a sidecar container in the Deployment, never optional.
44
+ - Image: `ghcr.io/agentspec/sidecar:latest` (controlled by `values.sidecar.image`)
45
+ - Proxy port: 4000, Control plane port: 4001
46
+ - Env: `UPSTREAM_URL: http://localhost:<agent-port>`, `MANIFEST_PATH: /manifest/agent.yaml`
47
+ - **No `$env:` or `$secret:` values** must appear in rendered ConfigMap data — only in the Secret.
48
+ - **Secret template** must list every `$env:VAR` ref found in the manifest as a key with a base64 placeholder comment.
49
+ - **`_helpers.tpl`** must define at minimum: `chart.name`, `chart.fullname`, `chart.labels`, `chart.selectorLabels`.
50
+ - **Resource names** must use the `{{ include "chart.fullname" . }}` helper to respect `nameOverride` / `fullnameOverride`.
51
+ - **`values.yaml`** must have sensible defaults (replica count 1, ClusterIP service, resources requests/limits).
52
+
53
+ ## Helm Best Practices to Follow
54
+
55
+ - Use `{{ .Values.xxx | quote }}` for string values in env vars.
56
+ - Use `{{- toYaml .Values.resources | nindent 12 }}` for resource blocks.
57
+ - Add `NOTES.txt` under `templates/` with post-install instructions (how to reach the agent, sidecar endpoints).
58
+ - All resources must carry standard labels from `_helpers.tpl` (app.kubernetes.io/name, app.kubernetes.io/instance, app.kubernetes.io/version, app.kubernetes.io/managed-by).
59
+ - Include `helm.sh/chart` annotation.
60
+ - ServiceAccount must be conditionally created (`values.serviceAccount.create: true`).
61
+
62
+ ## Output Format
63
+
64
+ Return a JSON object matching the GeneratedAgent schema:
65
+
66
+ ```json
67
+ {
68
+ "files": {
69
+ "Chart.yaml": "...",
70
+ "values.yaml": "...",
71
+ "templates/_helpers.tpl": "...",
72
+ "templates/deployment.yaml": "...",
73
+ "templates/service.yaml": "...",
74
+ "templates/configmap.yaml": "...",
75
+ "templates/secret.yaml": "...",
76
+ "templates/serviceaccount.yaml": "...",
77
+ "templates/NOTES.txt": "...",
78
+ ".helmignore": "...",
79
+ "README.md": "..."
80
+ },
81
+ "installCommands": [
82
+ "helm install <agent-name> . -f values.yaml --set image.tag=latest"
83
+ ],
84
+ "envVars": ["VAR1", "VAR2"]
85
+ }
86
+ ```
87
+
88
+ `envVars` must list every `$env:VAR` name found in the manifest (for the README and CI checks).
89
+ `installCommands` must include the `helm install` and `helm upgrade` commands.
90
+
91
+ ## Example Chart.yaml
92
+
93
+ ```yaml
94
+ apiVersion: v2
95
+ name: <metadata.name>
96
+ description: <metadata.description>
97
+ type: application
98
+ version: 0.1.0
99
+ appVersion: "<metadata.version>"
100
+ ```
101
+
102
+ ## Example values.yaml (minimal)
103
+
104
+ ```yaml
105
+ replicaCount: 1
106
+
107
+ image:
108
+ repository: <metadata.name>
109
+ tag: latest
110
+ pullPolicy: IfNotPresent
111
+
112
+ service:
113
+ type: ClusterIP
114
+ port: <spec.api.port or 8000>
115
+
116
+ sidecar:
117
+ image: ghcr.io/agentspec/sidecar:latest
118
+ proxyPort: 4000
119
+ controlPort: 4001
120
+
121
+ config:
122
+ agentName: "<metadata.name>"
123
+ modelProvider: "<spec.model.provider>"
124
+ modelId: "<spec.model.id>"
125
+
126
+ ingress:
127
+ enabled: false
128
+ className: ""
129
+ annotations: {}
130
+ hosts: []
131
+ tls: []
132
+
133
+ resources:
134
+ requests:
135
+ cpu: 100m
136
+ memory: <spec.requires.minimumMemoryMB or 256>Mi
137
+ limits:
138
+ cpu: 500m
139
+ memory: 512Mi
140
+
141
+ serviceAccount:
142
+ create: true
143
+ annotations: {}
144
+ name: ""
145
+
146
+ nameOverride: ""
147
+ fullnameOverride: ""
148
+ ```
149
+
150
+ Map **every** manifest field. Do not skip sections.
151
+ Ensure the Helm chart is installable with `helm install` against a standard Kubernetes cluster.