@inference-gateway/adl-cli 0.64.1 → 0.64.3

package/README.md

@@ -231,7 +231,7 @@ adl init my-agent --defaults
 
 # Non-interactive with specific configuration
 adl init my-agent \
-  --name "Weather Agent" \
+  --name weather-agent \
   --description "Provides weather information" \
   --provider deepseek \
   --model deepseek-v4-flash \
@@ -433,10 +433,24 @@ The `--deployment` flag generates platform-specific deployment configurations:
   - Configurable resources (CPU, memory), scaling (min/max instances), and service options
   - Uses direct gcloud commands for truly serverless deployment (no Kubernetes required)
   - Automatic container building with Docker or Cloud Build integration
-- **Kubernetes Deployment**: Creates `k8s/deployment.yaml` with standard Kubernetes manifests
-  - Enterprise-ready configurations with resource limits and health checks
-  - ConfigMap and Secret integration for environment variables
-  - Service and Ingress configurations for load balancing
+- **Kubernetes Deployment**: Creates `k8s/deployment.yaml` containing a `Namespace` named `<name>-ns` and an
+  `Agent` custom resource (`apiVersion: core.inference-gateway.com/v1alpha1`)
+  - The target cluster must have the Inference Gateway Operator and its `Agent` CRD installed - the operator
+    reconciles the `Agent` resource into the underlying workload
+  - No Deployment, Service, Ingress, ConfigMap, Secret, health checks or resource limits are generated; those
+    are the operator's responsibility
+  - The container image defaults to `<name>:<version>` and can be overridden with `spec.deployment.kubernetes.image`:
+
+    ```yaml
+    spec:
+      deployment:
+        type: kubernetes
+        kubernetes:
+          image:
+            registry: ghcr.io/your-org # optional, prefixed to the repository
+            repository: weather-agent # defaults to metadata.name
+            tag: 1.2.3 # defaults to metadata.version
+    ```
 
 ## Agent Definition Language (ADL)
 
@@ -465,8 +479,11 @@ spec:
     maxTokens: 4096
     temperature: 0.7
   tools:
-    - name: get_weather
+    - id: get_weather
+      name: get_weather
       description: "Get current weather for a city"
+      tags:
+        - weather
       schema:
         type: object
         properties:
@@ -501,7 +518,7 @@ The complete ADL schema includes:
 - **services**: Service services with interfaces, factories, and type definitions
 - **agent**: AI provider configuration (OpenAI, Anthropic, Google, Groq, Mistral, DeepSeek, Cohere, Cloudflare, Moonshot, Ollama, Ollama Cloud, Nvidia)
 - **tools**: Function-call definitions with JSON schemas, validation, and service injection support
-- **skills**: Markdown playbooks (id + optional `bare`, version, source) pulled from the skills registry, fetched as a full directory from a GitHub repo (shorthand or URL), or scaffolded locally; advertised on the agent card and prepended to the system prompt at runtime
+- **skills**: Markdown playbooks (id + optional `bare`, version, source) pulled from the skills registry, fetched as a full directory from a GitHub repo (shorthand or URL), or scaffolded locally into `.agents/skills/<id>/`; advertised on the agent card, and summarised at runtime in an `AVAILABLE SKILLS:` block appended to the system prompt (frontmatter only - the model reads each `SKILL.md` body on demand)
 - **server**: HTTP server configuration with authentication support
 - **language**: Programming language-specific settings (Go, Rust, TypeScript) and configurable acronyms
 - **scm**: Source control management configuration (GitHub, GitLab)
@@ -552,8 +569,11 @@ spec:
       factory: NewNotificationService
       description: Multi-channel notification service
   tools:
-    - name: query_database
+    - id: query_database
+      name: query_database
       description: "Execute database queries with validation"
+      tags:
+        - database
       inject:
         - logger
         - database
@@ -573,8 +593,11 @@ spec:
         required:
           - query
           - table
-    - name: send_notification
+    - id: send_notification
+      name: send_notification
       description: "Send multi-channel notifications"
+      tags:
+        - notifications
       inject:
         - logger
         - notifications
@@ -812,7 +835,9 @@ spec:
 The ADL spec distinguishes two complementary concepts:
 
 - **Tools** (`spec.tools`) are function-call entrypoints with explicit JSON schemas. They are generated as code in the target language and registered with the agent's toolbox. The model invokes them by name with structured arguments.
-- **Skills** (`spec.skills`) are markdown playbooks (with YAML frontmatter) that describe _when and how_ to use the tools. Each is written to its own directory at `skills/<id>/SKILL.md` in the generated project, advertised on the agent card so orchestrators can discover them, and prepended to the system prompt at runtime. The directory layout matches Anthropic's [agent skills convention](https://github.com/anthropics/skills) - bare skills can ship arbitrary scripts, templates, or reference material alongside `SKILL.md`.
+- **Skills** (`spec.skills`) are markdown playbooks (with YAML frontmatter) that describe _when and how_ to use the tools. Each is written to its own directory at `.agents/skills/<id>/SKILL.md` in the generated project, advertised on the agent card so orchestrators can discover them, and summarised at runtime in an `AVAILABLE SKILLS:` block appended to the system prompt - only the frontmatter is inlined; the model reads each `SKILL.md` body on demand (see [Runtime: AVAILABLE SKILLS manifest + on-demand Read](#runtime-available-skills-manifest--on-demand-read)). The directory layout matches Anthropic's [agent skills convention](https://github.com/anthropics/skills) - bare skills can ship arbitrary scripts, templates, or reference material alongside `SKILL.md`.
+
+When `spec.skills` is non-empty, `adl generate` also creates a `.claude/skills` → `../.agents/skills` relative symlink in the generated project, so Claude Code discovers the same skill tree at its conventional path without duplicating any files.
 
 A skill entry is small:
 
@@ -836,9 +861,9 @@ spec:
 
 ### Resolution rules
 
-- **`bare: true`** → the CLI scaffolds `skills/<id>/SKILL.md` with frontmatter from the manifest and a TODO body that you author by hand. The whole `skills/<id>/` directory is listed in `.adl-ignore`, so any bundled scripts, templates, or resources you drop alongside `SKILL.md` are preserved on regeneration.
-- **`source:` set** → the source must resolve to a public GitHub directory (a `/tree/<ref>/<path>` URL, or one of the shorthand forms below). The CLI pulls the _entire_ directory - `SKILL.md`, reference docs, bundled scripts, anything else - and writes it to `skills/<id>/`. Non-`github.com` URLs are rejected so the same code path always produces a complete skill bundle, not a stray markdown file.
-- **Otherwise** → fetch `https://registry.inference-gateway.com/skills/<id>[/<version>].md` (becomes `skills/<id>/SKILL.md`). Override the registry with `ADL_SKILLS_REGISTRY`. Registry-by-id currently ships `SKILL.md` only; if you need bundled assets, use `source:` to point at a GitHub directory.
+- **`bare: true`** → the CLI scaffolds `.agents/skills/<id>/SKILL.md` with frontmatter from the manifest and a TODO body that you author by hand. The whole `.agents/skills/<id>/` directory is listed in `.adl-ignore`, so any bundled scripts, templates, or resources you drop alongside `SKILL.md` are preserved on regeneration.
+- **`source:` set** → the source must resolve to a public GitHub directory (a `/tree/<ref>/<path>` URL, or one of the shorthand forms below). The CLI pulls the _entire_ directory - `SKILL.md`, reference docs, bundled scripts, anything else - and writes it to `.agents/skills/<id>/`. Non-`github.com` URLs are rejected so the same code path always produces a complete skill bundle, not a stray markdown file.
+- **Otherwise** → fetch `https://registry.inference-gateway.com/skills/<id>[/<version>].md` (becomes `.agents/skills/<id>/SKILL.md`). Override the registry with `ADL_SKILLS_REGISTRY`. Registry-by-id currently ships `SKILL.md` only; if you need bundled assets, use `source:` to point at a GitHub directory.
 
 ### Licensing
 
@@ -894,7 +919,7 @@ The 3-segment form assumes a `skills/<id>/` subdirectory inside the repo (the co
 
 ### Runtime: AVAILABLE SKILLS manifest + on-demand Read
 
-The generated agent advertises skills to the LLM via a frontmatter-only manifest, **not** by inlining SKILL.md bodies. At startup it walks first-level subdirectories under `skills/` (overridable with `A2A_SKILLS_DIR`), parses each `<id>/SKILL.md`'s YAML frontmatter, and appends an `AVAILABLE SKILLS:` block to the system prompt:
+The generated agent advertises skills to the LLM via a frontmatter-only manifest, **not** by inlining SKILL.md bodies. At startup it walks first-level subdirectories under `.agents/skills` (overridable with `A2A_SKILLS_DIR`), parses each `<id>/SKILL.md`'s YAML frontmatter, and appends an `AVAILABLE SKILLS:` block to the system prompt:
 
 ```text
 AVAILABLE SKILLS:
@@ -903,12 +928,14 @@ skill's description, read the SKILL.md file at the listed path using the Read
 tool, then follow its instructions.
 
 - incident-response: Use this when the user reports a production incident...
-  Path: skills/incident-response/SKILL.md
+  Path: .agents/skills/incident-response/SKILL.md
 - pdf: Fill in PDF forms and extract structured data from PDFs.
-  Path: skills/pdf/SKILL.md
+  Path: .agents/skills/pdf/SKILL.md
 ```
 
-The model loads each SKILL.md body on demand via the `Read` built-in tool, and executes any bundled scripts via `Bash` / `Write` / `Edit`. **A skills-using agent must therefore list `- id: read` in `spec.tools` and set `spec.config.tools.read.enabled: true`** - the validator enforces this; see [Reserved built-in tools](#reserved-built-in-tools).
+The model loads each SKILL.md body on demand via the `Read` built-in tool, and executes any bundled scripts via `Bash` / `Write` / `Edit`. **A skills-using agent must therefore list `- id: read` in `spec.tools` and set `spec.config.tools.read.enabled: true`** - see [Reserved built-in tools](#reserved-built-in-tools). `adl validate` does not enforce this: when `spec.skills` and `spec.agent` are both set, `validateSkills` (`internal/schema/validator.go`) emits a non-fatal **warning** if `- id: read` is missing from `spec.tools` or `spec.config.tools.read.enabled` is not `true`. The manifest still validates; the agent just cannot load any SKILL.md body at runtime.
+
+The `Read` built-in always allows the skills directory regardless of `allowed_roots`, so skills work even with a narrow read allowlist.
 
 ### Reserved built-in tools
 
@@ -932,6 +959,8 @@ spec:
     - id: query_database # user tool: full entry still required
       name: query_database
       description: "..."
+      tags:
+        - database
       schema: { type: object, ... }
 ```
 
@@ -944,26 +973,36 @@ spec:
       read:
         enabled: true
         max_lines: 2000 # offset/limit default window
-        allowed_roots: [] # empty = project-wide
+        allowed_roots: # REQUIRED: empty denies every path (fail-closed)
+          - ./docs
+          - ./data
       bash:
         enabled: true
         whitelist: [ls, cat, grep, jq]
         timeout_seconds: 30
+        working_dir: ./workspace # optional cwd for the command (default: process cwd)
       write:
         enabled: false # listed but explicitly disabled
+        allowed_roots: # REQUIRED when enabled: empty denies every path
+          - ./output
       edit:
         enabled: true
+        allowed_roots: # REQUIRED: empty denies every path
+          - ./output
       fetch:
         enabled: true
-        allowed_domains: # whitelist of hosts (empty = unrestricted, discouraged)
+        allowed_domains: # whitelist of hosts (empty = any public host)
           - example.com
           - .api.dev # entries starting with "." match any subdomain
+        allow_internal: false # true to permit loopback/private/link-local hosts
         max_bytes: 10485760 # 10 MiB cap on response body (default)
         timeout_seconds: 30 # total request timeout (default)
         download_dir: /tmp # root for save_path writes (default /tmp)
         allow_downloads: false # set true to allow writing response bodies to disk
 ```
 
+**`allowed_roots` fails closed.** In the Go and Rust built-in templates an empty (or omitted) `allowed_roots` denies **every** path for `read`, `write` and `edit` - it is not "project-wide". You must list the roots you want to permit. Two directories are exempt: `read` always allows the skills directory (`A2A_SKILLS_DIR`, default `.agents/skills`) and the artifacts directory (`A2A_ARTIFACTS_STORAGE_BASE_PATH`, default `/tmp/artifacts`); `write` and `edit` always allow the artifacts directory.
+
 Values are baked into the generated constructor as compile-time literals - there's no `ToolsConfig` struct in `config/config.go` because reserved-namespace sections are intentionally skipped. The validator decodes each `spec.config.tools.<id>` block into the built-in's typed shape and rejects unknown keys (typos like `tymeout_seconds` fail with `spec.config.tools.bash.tymeout_seconds`).
 
 Runtime overrides for Bash (read inside `tools/bash.go`):
@@ -973,8 +1012,10 @@ Runtime overrides for Bash (read inside `tools/bash.go`):
 
 Runtime overrides for Fetch (resolution precedence: env > compile-time literal > default-disabled):
 
-- Go: `TOOLS_FETCH_ENABLED`, `TOOLS_FETCH_ALLOWED_DOMAINS`, `TOOLS_FETCH_MAX_BYTES`, `TOOLS_FETCH_TIMEOUT_SECONDS`, `TOOLS_FETCH_DOWNLOAD_DIR`, `TOOLS_FETCH_ALLOW_DOWNLOADS` (envconfig-style; comma-separated for lists).
-- Rust: `A2A_FETCH_DISABLED=1` (kill switch), `A2A_FETCH_ALLOWED_DOMAINS`, `A2A_FETCH_MAX_BYTES`, `A2A_FETCH_TIMEOUT_SECONDS`, `A2A_FETCH_DOWNLOAD_DIR`, `A2A_FETCH_ALLOW_DOWNLOADS`.
+- Go: `TOOLS_FETCH_ENABLED`, `TOOLS_FETCH_ALLOWED_DOMAINS`, `TOOLS_FETCH_ALLOW_INTERNAL`, `TOOLS_FETCH_MAX_BYTES`, `TOOLS_FETCH_TIMEOUT_SECONDS`, `TOOLS_FETCH_DOWNLOAD_DIR`, `TOOLS_FETCH_ALLOW_DOWNLOADS` (envconfig-style; comma-separated for lists).
+- Rust: `A2A_FETCH_DISABLED=1` (kill switch), `A2A_FETCH_ALLOWED_DOMAINS`, `A2A_FETCH_ALLOW_INTERNAL`, `A2A_FETCH_MAX_BYTES`, `A2A_FETCH_TIMEOUT_SECONDS`, `A2A_FETCH_DOWNLOAD_DIR`, `A2A_FETCH_ALLOW_DOWNLOADS`.
+
+**An empty `allowed_domains` is not unrestricted.** With no allowlist, `fetch` still refuses any host that resolves to a loopback, private (RFC 1918 / IPv6 ULA), link-local or unspecified address - an SSRF guard applied to the initial request and to every redirect hop. Set `allow_internal: true` (or `TOOLS_FETCH_ALLOW_INTERNAL` / `A2A_FETCH_ALLOW_INTERNAL` at runtime) to reach internal hosts, e.g. when calling a sidecar or a service on the cluster network. When `allowed_domains` _is_ non-empty the allowlist decides on its own and `allow_internal` is not consulted.
 
 The Fetch tool supports `GET` and `HEAD` only. Optional `save_path` writes the response body to a path resolved under `download_dir` - absolute paths and parent-directory traversal (`..`) are rejected, and the request fails unless `allow_downloads: true`. Bodies (and on-disk files) are capped at `max_bytes`; oversized responses are truncated and the result payload sets `"truncated": true`. The Go template uses only the standard library (`net/http`); the Rust template adds `reqwest` (rustls-tls + json features) to `Cargo.toml` automatically when `- id: fetch` is present in `spec.tools`.
 
@@ -1011,8 +1052,11 @@ spec:
       factory: NewCacheRepository
       description: High-performance caching layer for API responses
   tools:
-    - name: create_event
+    - id: create_event
+      name: create_event
       description: "Create a new calendar event"
+      tags:
+        - calendar
       inject:
         - logger # Built-in, always available
         - googleCalendar # Custom service
@@ -1089,8 +1133,11 @@ spec:
       factory: NewDatabaseService
       description: PostgreSQL database service
   tools:
-    - name: export_report
+    - id: export_report
+      name: export_report
       description: "Export data and email report"
+      tags:
+        - reporting
       inject:
         - logger
         - database
@@ -1105,7 +1152,7 @@ spec:
 
 **Generated Tool Code:**
 
-> Illustrative example - see `internal/templates/languages/go/tool.go.tmpl` for the actual template. Generated tools live under `tools/`, not `skills/`.
+> Illustrative example - see `internal/templates/languages/go/tool.go.tmpl` for the actual template. Generated tools live under `tools/`, not `.agents/skills/`.
 
 ```go
 type ExportReportTool struct {
@@ -1199,8 +1246,8 @@ my-agent/
 ├── tools/
 │   ├── create_event.go             # Function-call tools with injected services
 │   └── list_events.go
-├── skills/
-│   ├── calendar-workflow/          # Markdown playbooks loaded into the system prompt
+├── .agents/skills/
+│   ├── calendar-workflow/          # Markdown playbooks read on demand by the model
 │   │   └── SKILL.md
 │   └── meeting-summary/
 │       └── SKILL.md
@@ -1239,7 +1286,7 @@ Skills automatically receive injected services as constructor parameters:
 
 **Example `tools/create_event.go`:**
 
-> Illustrative example - see `internal/templates/languages/go/tool.go.tmpl` for the actual template. Generated tools live under `tools/`, not `skills/`.
+> Illustrative example - see `internal/templates/languages/go/tool.go.tmpl` for the actual template. Generated tools live under `tools/`, not `.agents/skills/`.
 
 ```go
 type CreateEventTool struct {
@@ -1301,11 +1348,13 @@ my-go-agent/
 ├── tools/                     # Function-call tool implementations
 │   ├── query_database.go      # Individual tool files (TODO placeholders)
 │   └── send_notification.go
-├── skills/                    # Skill directories (SKILL.md + optional bundled assets)
-│   ├── incident-response/     # Loaded into the system prompt at startup
+├── .agents/skills/            # Skill directories (SKILL.md + optional bundled assets)
+│   ├── incident-response/     # Frontmatter listed in the AVAILABLE SKILLS block at startup
 │   │   └── SKILL.md
 │   └── support-handoff/
 │       └── SKILL.md
+├── .claude/
+│   └── skills -> ../.agents/skills  # Symlink so Claude Code finds the same tree
 ├── Taskfile.yml               # Development tasks (build, test, lint)
 ├── Dockerfile                 # Container configuration
 ├── .adl-ignore                # Files to protect from regeneration
@@ -1345,11 +1394,13 @@ my-rust-agent/
 │       ├── mod.rs             # Module declarations
 │       ├── query_database.rs  # Individual tool implementations
 │       └── send_notification.rs
-├── skills/                    # Skill directories (SKILL.md + optional bundled assets)
+├── .agents/skills/            # Skill directories (SKILL.md + optional bundled assets)
 │   ├── incident-response/
 │   │   └── SKILL.md
 │   └── support-handoff/
 │       └── SKILL.md
+├── .claude/
+│   └── skills -> ../.agents/skills  # Symlink so Claude Code finds the same tree
 ├── Cargo.toml                 # Rust package configuration
 ├── Taskfile.yml               # Development tasks
 ├── Dockerfile                 # Rust-optimized container
@@ -1380,11 +1431,13 @@ my-typescript-agent/
 │       ├── index.ts           # Toolbox wiring
 │       ├── query_database.ts  # Individual tool implementations (TODO placeholders)
 │       └── send_notification.ts
-├── skills/                    # Skill directories (SKILL.md + optional bundled assets)
+├── .agents/skills/            # Skill directories (SKILL.md + optional bundled assets)
 │   ├── incident-response/
 │   │   └── SKILL.md
 │   └── support-handoff/
 │       └── SKILL.md
+├── .claude/
+│   └── skills -> ../.agents/skills  # Symlink so Claude Code finds the same tree
 ├── package.json               # Node package definition + scripts
 ├── tsconfig.json              # TypeScript compiler configuration
 ├── Taskfile.yml               # Development tasks
@@ -1440,7 +1493,7 @@ This creates a GitHub Actions workflow (`.github/workflows/ci.yml`) that include
 
 - **Automated Testing**: Runs all tests on every push and pull request
 - **Code Quality**: Format checking and linting
-- **Multi-Environment**: Supports main and develop branches
+- **Branch Scope**: Triggers on push and pull requests targeting `main`
 - **Caching**: Go module caching for faster builds
 - **Task Integration**: Uses the generated Taskfile for consistent build steps
 
@@ -1489,11 +1542,13 @@ gh workflow run cd.yml
 **Container Registry**: Published images are available at:
 
 ```text
+ghcr.io/your-org/your-agent:1.0.0
 ghcr.io/your-org/your-agent:latest
-ghcr.io/your-org/your-agent:v1.0.0
-ghcr.io/your-org/your-agent:1.0
 ```
 
+The version tag carries no `v` prefix (the git tag does), and `:latest` is only pushed from `main` - releases
+from `rc/*` branches publish the version tag alone.
+
 ## CloudRun Deployment
 
 The ADL CLI provides native support for deploying A2A agents to Google Cloud Run, offering a truly serverless deployment experience without Kubernetes complexity.
@@ -1589,10 +1644,15 @@ This creates:
 
 **Required GitHub Secrets:**
 
-- `GCP_SA_KEY`: Service account key JSON
+- `GCP_CREDENTIALS`: Service account credentials JSON (used by the CloudRun deploy job)
 - `GCP_PROJECT_ID`: Google Cloud project ID
 - `GCP_REGION`: Deployment region (e.g., us-central1)
 
+The same `.github/workflows/cd.yml` also contains deploy jobs for the other platforms, which require:
+
+- `KUBECONFIG`: Kubeconfig for the target cluster (Kubernetes deploy job)
+- `VERCEL_TOKEN`: Vercel API token (Vercel deploy job)
+
 ### CloudRun Benefits
 
 - **Truly Serverless**: No Kubernetes clusters or infrastructure management
@@ -1847,14 +1907,28 @@ Enable OpenTelemetry instrumentation for the generated agent:
 spec:
   telemetry:
     enabled: true
+    traces:
+      exporter:
+        otlp:
+          endpoint: http://localhost:4318
+          protocol: http/protobuf # grpc or http/protobuf
+    metrics:
+      exporter:
+        prometheus: # pull endpoint - Go only
+          host: 0.0.0.0
+          port: 9464
 ```
 
-The manifest field is a single on/off switch - exporter endpoints, ports, and sampling stay runtime concerns configured via environment variables in the generated `.env.example`:
+`enabled` is the master switch; the optional `traces.exporter` and `metrics.exporter` blocks pick how each signal leaves the agent. Traces accept `otlp` (`endpoint`, `protocol`); metrics accept either `otlp` (same fields) or `prometheus` (`host`, `port`). Omitting a signal's exporter disables it (`none`). Every field is a default only - each one renders into the generated `.env.example` and is overridden by the environment at runtime. Auth headers, credentials, and sampling stay runtime-only concerns.
 
-- **Go**: the ADK spans every tool call (`tool.<name>`, carrying the propagated `session.id`/`gen_ai.tool.call.id`) and the generator surfaces `A2A_TELEMETRY_ENABLED`, `A2A_TELEMETRY_METRICS_PORT`/`_HOST`, `A2A_TELEMETRY_TRACE_ENABLED`/`_ENDPOINT`/`_HEADERS` in `.env.example`.
-- **TypeScript**: wires the ADK's `createTelemetryProvider` into `src/index.ts` (no extra npm dependencies) and surfaces `TELEMETRY_ENABLED` plus the standard `OTEL_EXPORTER_OTLP_*` / `OTEL_SERVICE_*` variables in `.env.example`.
+> **Note:** Prometheus pull is Go-only - the TypeScript ADK does not support it yet, and the validator warns when a TypeScript manifest configures it.
+
+- **Go**: the ADK spans every tool call (`tool.<name>`, carrying the propagated `session.id`/`gen_ai.tool.call.id`) and the generator surfaces `A2A_TELEMETRY_ENABLED` plus `A2A_OTEL_TRACES_EXPORTER`, `A2A_OTEL_METRICS_EXPORTER`, `A2A_OTEL_EXPORTER_OTLP_ENDPOINT`/`_PROTOCOL` and `A2A_OTEL_EXPORTER_PROMETHEUS_HOST`/`_PORT` in `.env.example`. The Go ADK nests its whole config under the `A2A_` prefix, so each standard `OTEL_*` name is read as `A2A_OTEL_*`; it has no per-signal OTLP variants.
+- **TypeScript**: wires the ADK's `createTelemetryProvider` into `src/index.ts` (no extra npm dependencies) and surfaces the same `A2A_TELEMETRY_ENABLED` / `A2A_OTEL_*` names, using the per-signal `A2A_OTEL_EXPORTER_OTLP_TRACES_*` / `_METRICS_*` forms when traces and metrics push to different collectors. `A2A_OTEL_SERVICE_NAME` / `_VERSION` are emitted commented out. The generated `src/index.ts` mirrors each `A2A_OTEL_*` variable onto its bare `OTEL_*` name at startup, since the OpenTelemetry Node SDK reads the unprefixed names.
 
 > **Note:** Telemetry generation currently supports Go and TypeScript only; Rust agents ignore `spec.telemetry`.
+>
+> `.env.example` is only generated when `spec.development.sandbox.dockerCompose.enabled: true`.
 
 **Examples:**
 
@@ -1881,6 +1955,8 @@ spec:
 `enabled` is the master switch. When true (and omitted the block is off), the generator wires an `MCPClientManager` into `main.go` that connects to the servers in the background, discovers their tools, and registers two selector tools - `mcp_list_tools` and `mcp_call_tool` - into the agent's toolbox. Everything else is a runtime concern: each `mcp` field maps 1:1 to an `A2A_MCP_*` variable in the generated `.env.example` (the manifest value is the default, overridden by the environment). `A2A_MCP_SERVERS` is derived from the `http` servers' base URLs. Defaults: `endpoint=/mcp`, `refreshInterval=5m`, `dialTimeout=30s`, `callTimeout=30s`, `maxRetries=0`, `retryInterval=2s`, `retryMaxInterval=30s`.
 
 > **Note:** The ADK MCP client is generated for Go agents only and is streamable-HTTP-only; `stdio`/`sse` servers are dropped from `A2A_MCP_SERVERS` (the validator warns), and the block is ignored for TypeScript/Rust agents.
+>
+> `.env.example` is only generated when `spec.development.sandbox.dockerCompose.enabled: true`.
 
 **Example:**
 
@@ -2004,7 +2080,7 @@ Each language has its own file mapping that determines what gets generated:
 - `internal/{service}/{service}.go` → Service implementation per ADL service
 - `tools/{toolname}.go` → Individual function-call tool implementations
 - `tools/{builtin}.go` + `tools/{builtin}_test.go` → Reserved built-in tool implementations (read, bash, write, edit, fetch)
-- `skills/{skillid}/SKILL.md` → Markdown skill playbooks (loaded into system prompt at runtime)
+- `.agents/skills/{skillid}/SKILL.md` → Markdown skill playbooks (frontmatter listed in the runtime `AVAILABLE SKILLS:` block; body read on demand)
 - `go.mod` → Go module configuration
 - `Dockerfile` → Container image
 - `.dockerignore` → Docker build exclusions
@@ -2020,9 +2096,9 @@ Each language has its own file mapping that determines what gets generated:
 - `CLAUDE.md`, `GEMINI.md`, `AGENTS.md` → AI assistant documentation (conditional on AI toggles)
 - `.github/ISSUE_TEMPLATE/*.md` → GitHub issue templates (conditional on SCM config)
 - `.github/dependabot.yml` → Dependabot configuration (conditional on SCM config)
-- CI workflow (`.github/workflows/ci.go.yaml`) → Conditional on SCM CI toggle
-- CD workflow (`.github/workflows/cd.yaml`) → Conditional on SCM CD toggle
-- AI agent workflows (`.github/workflows/ai-*.yaml`) → Conditional on AI orchestrator toggles
+- CI workflow (`.github/workflows/ci.yml`) → Conditional on SCM CI toggle
+- CD workflow (`.github/workflows/cd.yml`) → Conditional on SCM CD toggle
+- AI agent workflows (`.github/workflows/claude.yml`, `codex.yml`, `gemini.yml`, `infer.yml`) → Conditional on AI orchestrator toggles
 
 **Rust Projects:**
 
@@ -2030,7 +2106,7 @@ Each language has its own file mapping that determines what gets generated:
 - `src/tools/{toolname}.rs` → Tool descriptor + handler
 - `src/tools/{builtin}.rs` → Reserved built-in tool implementations (read, bash, write, edit, fetch)
 - `src/tools/mod.rs` → Module declarations
-- `skills/{skillid}/SKILL.md` → Markdown skill playbooks
+- `.agents/skills/{skillid}/SKILL.md` → Markdown skill playbooks
 - `Cargo.toml` → Rust package configuration
 - `Dockerfile` → Container image
 - `.dockerignore` → Docker build exclusions
@@ -2046,9 +2122,9 @@ Each language has its own file mapping that determines what gets generated:
 - `CLAUDE.md`, `GEMINI.md`, `AGENTS.md` → AI assistant documentation (conditional on AI toggles)
 - `.github/ISSUE_TEMPLATE/*.md` → GitHub issue templates (conditional on SCM config)
 - `.github/dependabot.yml` → Dependabot configuration (conditional on SCM config)
-- CI workflow (`.github/workflows/ci.rust.yaml`) → Conditional on SCM CI toggle
-- CD workflow (`.github/workflows/cd.yaml`) → Conditional on SCM CD toggle
-- AI agent workflows (`.github/workflows/ai-*.yaml`) → Conditional on AI orchestrator toggles
+- CI workflow (`.github/workflows/ci.yml`) → Conditional on SCM CI toggle
+- CD workflow (`.github/workflows/cd.yml`) → Conditional on SCM CD toggle
+- AI agent workflows (`.github/workflows/claude.yml`, `codex.yml`, `gemini.yml`, `infer.yml`) → Conditional on AI orchestrator toggles
 
 **TypeScript Projects:**
 
@@ -2059,7 +2135,7 @@ Each language has its own file mapping that determines what gets generated:
 - `src/tools/{toolname}.ts` → Individual function-call tool implementations
 - `src/tools/index.ts` → Tool module barrel export
 - `src/worker.ts` → Cloudflare Worker entrypoint (only when `spec.deployment.type: cloudflare`)
-- `skills/{skillid}/SKILL.md` → Markdown skill playbooks
+- `.agents/skills/{skillid}/SKILL.md` → Markdown skill playbooks
 - `package.json` → Node.js package configuration
 - `pnpm-workspace.yaml` → pnpm workspace configuration
 - `tsconfig.json` → TypeScript compiler configuration
@@ -2078,9 +2154,9 @@ Each language has its own file mapping that determines what gets generated:
 - `CLAUDE.md`, `GEMINI.md`, `AGENTS.md` → AI assistant documentation (conditional on AI toggles)
 - `.github/ISSUE_TEMPLATE/*.md` → GitHub issue templates (conditional on SCM config)
 - `.github/dependabot.yml` → Dependabot configuration (conditional on SCM config)
-- CI workflow (`.github/workflows/ci.typescript.yaml`) → Conditional on SCM CI toggle
-- CD workflow (`.github/workflows/cd.yaml`) → Conditional on SCM CD toggle
-- AI agent workflows (`.github/workflows/ai-*.yaml`) → Conditional on AI orchestrator toggles
+- CI workflow (`.github/workflows/ci.yml`) → Conditional on SCM CI toggle
+- CD workflow (`.github/workflows/cd.yml`) → Conditional on SCM CD toggle
+- AI agent workflows (`.github/workflows/claude.yml`, `codex.yml`, `gemini.yml`, `infer.yml`) → Conditional on AI orchestrator toggles
 
 ### Template Context
 
@@ -2252,13 +2328,14 @@ Each language has sensible defaults:
 
 **Go Projects:**
 
-- `go fmt ./...` - Format all Go source files
 - `go mod tidy` - Download dependencies and clean up go.mod
+- `go fmt ./...` - Format all Go source files
 
 **Rust Projects:**
 
 - `cargo fmt` - Format all Rust source files
-- `cargo check` - Check the project for errors
+
+**TypeScript Projects:** no default hooks run.
 
 ### Custom Hooks
 
@@ -2288,7 +2365,7 @@ spec:
 - **Command Execution**: Commands run in the generated project directory
 - **Error Handling**: Failed commands show warnings but don't stop generation
 - **Sequential Execution**: Commands run in the order specified
-- **Shell Support**: Commands are executed through the system shell
+- **No Shell**: Each command is split on whitespace and executed directly - pipes, redirects, `&&`, quoting, and variable expansion do not work. Put anything that needs a shell into a script and invoke it (`./scripts/setup.sh`).
 
 ### Example Configurations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inference-gateway/adl-cli",
-  "version": "0.64.1",
+  "version": "0.64.3",
   "description": "Scaffold complete A2A (Agent-to-Agent) projects from YAML Agent Definition Language (ADL) manifests. Thin npm wrapper around the native adl binary.",
   "bin": {
     "adl": "bin/run.js"