@copado/agentia-cli 1.0.0 → 1.2.0

package/package.json

@@ -12,6 +12,8 @@
     "@oclif/plugin-plugins": "^5",
     "@xmldom/xmldom": "^0.9.12",
     "exceljs": "^4.4.0",
+    "proxy-agent": "^8.0.2",
+    "proxy-from-env": "^2.1.0",
     "semver": "^7.8.5",
     "tty-table": "^7.0.1",
     "uuid": "^14.0.1",
@@ -59,6 +61,7 @@
     "bin": "agentia",
     "dirname": "agentia-cli",
     "commands": "./dist/commands",
+    "helpClass": "./dist/help.js",
     "hooks": {
       "finally": [
         "./dist/hooks/finally/ide-command-event"
@@ -227,15 +230,45 @@
         "description": "Create and update Agentia Agent Skills"
       },
       "testing": {
-        "description": "Manage Copado Robotic Testing projects, tests, runs, logs, and variables"
+        "description": "Manage Copado Robotic Testing projects, jobs, runs, logs, and variables"
+      },
+      "testing:data-table": {
+        "description": "Manage Copado Robotic Testing data tables"
+      },
+      "testing:job": {
+        "description": "Manage Copado Robotic Testing jobs and their runs"
+      },
+      "testing:job:files": {
+        "description": "Manage files stored in a Copado Robotic Testing job"
+      },
+      "testing:job:runs": {
+        "description": "Inspect and control Copado Robotic Testing job runs"
+      },
+      "testing:job:schedule": {
+        "description": "Manage the schedule for a Copado Robotic Testing job"
       },
       "testing:live": {
         "description": "Manage Copado Robotic Testing live sessions"
+      },
+      "testing:project": {
+        "description": "Manage Copado Robotic Testing projects"
+      },
+      "testing:project:permission": {
+        "description": "Manage Copado Robotic Testing project permissions"
+      },
+      "testing:robot": {
+        "description": "Manage Copado Robotic Testing robots"
+      },
+      "testing:user-parameter": {
+        "description": "Manage account-scoped Copado Robotic Testing user parameters"
+      },
+      "testing:variable": {
+        "description": "Manage Copado Robotic Testing variables and secrets"
       }
     }
   },
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "x-agentia-protected-build": true,
   "x-agentia-protected-files": [
     "dist/lib/runtime.js"

package/templates/rules/cursor/agentia.mdc

@@ -0,0 +1,29 @@
+---
+description: Use Agentia for Copado CICD, Testing, AI, and advanced pipeline workflows
+alwaysApply: false
+---
+
+<!-- Agentia managed rules: agentia setup skills -->
+
+# Agentia CLI
+
+Use Agentia to manage Copado work items. Prefer registered Agentia MCP tools; otherwise use the CLI with `--json`.
+
+Authentication must be configured before operational commands. Never print credentials, tokens, or unmasked environment variables.
+
+## Copado workflow
+
+`list → get → set → (implement & git commit) → test → publish → submit [--done|--deploy]`
+
+Read records before changing them and use IDs returned by Copado. Do not skip `work set` before coding; use one story per feature branch. Keep the working tree clean for lifecycle commands, and confirm promotion/deployment intent before `done`.
+
+## Agent Skills
+
+Load exactly one copy of each applicable installed Agentia skill:
+
+- `agentia-cicd`: Copado stories, commits, publish, submit, done, promotions, jobs, Functions, Job Templates, environments, pipelines, Slack notification configure, and data.
+- `agentia-testing`: Copado Robotic Testing operations.
+- `agentia-ai`: Copado AI operations.
+- `agentia-adv`: advanced pipeline workflows.
+
+Project-specific instructions take precedence over managed Agentia skills. Refresh managed skills with `agentia setup skills update`; do not hand-edit managed files.

package/templates/skills/agentia/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: agentia
+description: Use when working with Agentia or Copado CICD, Robotic Testing, AI, pipelines, user stories, commits, promotions, deployments, jobs, environments, credentials, or data templates.
+---
+
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Agentia CLI
+
+Use Agentia to manage Copado work items. Prefer registered Agentia MCP tools; otherwise use the CLI with `--json`.
+
+Authentication must be configured before operational commands. Never print credentials, tokens, or unmasked environment variables.
+
+## Copado workflow
+
+`list → get → set → (implement & git commit) → test → publish → submit [--done|--deploy]`
+
+Read records before changing them and use IDs returned by Copado. Do not skip `work set` before coding; use one story per feature branch. Keep the working tree clean for lifecycle commands, and confirm promotion/deployment intent before `done`.
+
+## Agent Skills
+
+Use the applicable installed domain skill for detailed instructions:
+
+- `agentia-cicd`: Copado stories, commits, publish, submit, done, promotions, jobs, Functions, Job Templates, environments, pipelines, Slack notification configure, and data.
+- `agentia-testing`: Copado Robotic Testing operations.
+- `agentia-ai`: Copado AI operations.
+- `agentia-adv`: advanced pipeline workflows.
+
+Project-specific instructions take precedence over managed Agentia skills. Refresh managed skills with `agentia setup skills update`; do not hand-edit managed files.

package/templates/skills/agentia-ai/SKILL.md

@@ -14,10 +14,9 @@ Prefer the `agentia_ai_ask` MCP tool when it is available for single-turn prompt
 ## Start Here
 
 1. Confirm AI auth with `agentia auth get --ai --json`. Configure missing credentials with `agentia auth set --ai ...` or the supported `AGENTIA_AI_*` environment variables.
-2. Choose exactly one required `--agent` option for `ask`: `plan`, `build`, `test`, `release`, `operate`, or `knowledge`. `orchestrate` is not valid for `ask`.
-3. Choose exactly one required `--agent` option for `chat`: `plan`, `build`, `test`, `release`, `operate`, `knowledge`, or `orchestrate`.
-4. Add useful context flags when available: `--workspace`, `--dialogue`, `--user-story`, `--sf-org`, and `--component`.
-5. Use `--json` for automation. Use `--no-stream` when the caller needs a buffered response.
+2. Omit `--agent` by default: `ask` and `chat` use `orchestrate`, which routes work to the right specialist. Pass `--agent plan`, `build`, `test`, `release`, `operate`, or `knowledge` only to target a specialist explicitly.
+3. Add useful context flags when available: `--workspace`, `--dialogue`, `--user-story`, `--sf-org`, and `--component`.
+4. Use `--json` for automation. Use `--no-stream` when the caller needs a buffered response.
 
 ## Reference
 

package/templates/skills/agentia-ai/references/ai-agents.md

@@ -25,9 +25,9 @@ Operational options include `--workspace` and `--timeout`; authentication is res
 | `release` | Release, promotion, packaging, and deployment questions. |
 | `operate` | Operational diagnostics, monitoring, and runbook style questions. |
 | `knowledge` | Copado AI Knowledge grounding, product documentation, personas, and troubleshooting. |
-| `orchestrate` | Chat-only orchestration mode for interactive sessions. |
+| `orchestrate` | Default. Routes the request to the right specialist automatically. |
 
-Pass the selected value with the required `--agent` option. `ask` accepts `plan`, `build`, `test`, `release`, `operate`, or `knowledge`; `chat` also accepts `orchestrate`. `ask` requires a prompt with `-p` or `--prompt`; `chat` is TTY-only and prompts interactively.
+`--agent` is optional and defaults to `orchestrate` for `ask`, `chat`, and the `agentia_ai_ask` MCP tool. Pass a specialist only to target it explicitly. `ask` requires a prompt with `-p` or `--prompt`; `chat` is TTY-only and prompts interactively.
 
 ## Single-Turn Ask
 

package/templates/skills/agentia-cicd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentia-cicd
-description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools: user stories (including current/active story context), cloud commit/promote, work publish/submit/done, promotion runs and conflicts, job executions, Copado Functions, Job Templates, environments, credentials, pipelines, stages, Slack pipeline notification subscriptions, and release data templates. Use it whenever the user asks an agent to operate Copado CICD from a terminal, IDE, or headless workflow.
+description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools, including user stories (including current/active story context), cloud commit/promote, work publish/submit/done, promotion runs and conflicts, job executions, Copado Functions, Job Templates, git-hosted CICD extensions, environments, credentials, pipelines, stages, Slack pipeline notification subscriptions, and release data templates. Use it whenever the user asks an agent to operate Copado CICD from a terminal, IDE, or headless workflow.
 ---
 
 <!-- Agentia managed skill file: agentia setup skills -->
@@ -24,22 +24,27 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 - Promotion lookup, run, resume, merge conflicts, and story-centric promotion: [references/promotions.md](references/promotions.md)
 - Copado JobExecution lookup, actions, logs, and monitoring: [references/jobs.md](references/jobs.md)
 - Copado Functions lifecycle, remote run/results, and local Docker run: [references/functions.md](references/functions.md)
+- Git-hosted Copado CICD extensions (`cicd extension`, experimental): [references/extensions.md](references/extensions.md)
 - Copado Job Templates (`cicd template`, not data templates): [references/templates.md](references/templates.md)
 - Copado environments, environment credentials, and browser authentication: [references/environments-and-credentials.md](references/environments-and-credentials.md)
-- Pipelines, environment connections, stages, and stage connections: [references/pipelines.md](references/pipelines.md)
+- Pipelines, automations, quality gates, extension configurations, environment connections, stages, and stage connections: [references/pipelines.md](references/pipelines.md)
 - Slack notification subscriptions on a pipeline (`agentia_notification_configure` / CLI): [references/notifications.md](references/notifications.md)
 - Release data templates, records, matching, sync, dataset files, and data commits: [references/data.md](references/data.md)
 
+For **Org Intelligence** (read Salesforce metadata against a sandbox/developer org credential; prefer local files first, then the org; metadata only—not data, not edits), use the separate skill `agentia-metadata/SKILL.md` (`cicd metadata explore` / MCP `agentia_metadata_explore`).
+
 ## General Rules
 
-- When the user means the **current story**, **current user story**, **active story**, **story context**, or similar without giving an ID, resolve context first with `agentia cicd work get --json` (no positional story ID). Use the returned user story (`result`) for follow-up work—any fields the task needs (for example `id`, `name`, `title`, `status`, specs, pipeline or environment IDs), not only identifiers. If the command fails (for example no active work item from `work set`), report the CLI error to the user and stop; do not guess, list stories, or pick a substitute unless the user asks you to.
+- When the user means the **current story**, **current user story**, **active story**, **story context**, or similar without giving an ID, resolve context first with `agentia cicd work get --json` (no positional story ID). Use the returned user story (`result`) for follow-up work—any fields the task needs (for example `id`, `name`, `title`, `status`, specs, pipeline or environment IDs, subscriber `customFields`), not only identifiers. If the command fails (for example no active work item from `work set`), report the CLI error to the user and stop; do not guess, list stories, or pick a substitute unless the user asks you to.
+- User Story subscriber custom fields: read `result.customFields` from `work get` / MCP `agentia_work_get`. Write with CLI `--custom-field ApiName=value` (repeatable) or MCP `customFields: [{ apiName, value }]` on create/update. See [references/work.md](references/work.md#subscriber-custom-fields).
 - Use Salesforce record IDs or generated names read from Copado. Do not invent story names, promotion IDs, job IDs, credential IDs, or pipeline IDs.
 - Keep human output off stdout in JSON workflows. Prefer `--json`, then parse the result object.
 - For local project work, keep the tracked working tree clean before commands that require it: `work set`, `work publish`, and `work submit`. If `work set` returns `status: "warning"`, show the message and do not assume a feature branch was created; branch keys are cleared and the work item id/name/title are still recorded in config.user.json.
 - Treat `cicd job` as Copado CICD JobExecution. It is different from CRT `testing job`.
 - Treat `cicd function` as Copado Function definitions and runs. It is different from JobExecution (`cicd job`) and Job Templates (`cicd template`).
+- Treat `cicd extension` as experimental git-hosted packaging of Functions/Templates (plus optional `force-app`). It is different from per-asset `cicd function` / `cicd template` upserts.
 - Treat `cicd template` as Copado Job Templates via `/release/jobs/templates`. It is different from Release Data Templates (`cicd data template`).
-- Treat `cicd work test` as local quality gates (`--local` is the default). It is different from CRT `testing test run`.
+- Treat `cicd work test` as local quality gates (`--local` is the default). It is different from CRT `testing job run`.
 - Treat `cicd work test apex` as the Apex test runner that local quality gates (`.agentia_quality_gates.*`) usually call. An empty `--apex-test-classes` list skips Salesforce CLI. It can also be invoked directly. It is different from CRT.
 - Treat `auth` credentials as keychain/API credentials and `cicd credential` records as Copado environment credentials.
 

package/templates/skills/agentia-cicd/references/environments-and-credentials.md

@@ -4,7 +4,7 @@
 
 Use this reference for `agentia cicd environment ...`, `agentia cicd environment auth ...`, and `agentia cicd credential ...`.
 
-`auth set --cicd` stores the API key used by the CLI. `cicd credential` lists, creates, or updates Copado environment credential records. They are different credential types.
+`auth set --cicd` stores the API key used by the CLI. `cicd credential` lists, creates, updates, opens, or authenticates Copado environment credential records. They are different credential types.
 
 ## Environment Commands
 
@@ -14,9 +14,9 @@ Use this reference for `agentia cicd environment ...`, `agentia cicd environment
 | `environment get ID` | Inspect one environment | Read before updates, credential changes, or auth checks. |
 | `environment create NAME` | Create an environment | Set `--type`; platform defaults to SFDX. |
 | `environment update ID` | Sparse environment changes | Use only the fields the user wants changed. |
-| `environment open [ID]` | Open environment or credential | `--credentialid` opens a credential. CLI-only navigation helper. |
-| `environment auth status ID` | Validate org credential auth | Use `--credentialid` when multiple credentials need disambiguation. |
-| `environment auth web login ID` | Complete browser OAuth login | CLI-only, interactive browser flow. Supports bounded port and timeout flags. |
+| `environment open [ID]` | Open an environment | Uses the project default environment when ID is omitted. CLI-only navigation helper. |
+| `environment auth status ID` | Validate auth for an environment credential | Auto-selects when possible; use `--credentialid` to disambiguate. |
+| `environment auth web login ID` | Complete browser OAuth for an environment credential | CLI-only interactive browser flow. Supports bounded port and timeout flags. |
 
 Examples:
 
@@ -26,33 +26,39 @@ agentia cicd environment get <environment-id> --json
 agentia cicd environment auth status <environment-id> --credentialid <credential-id> --json
 ```
 
-## Environment Credential Commands
+## Credential Commands
 
 | Command | Use For | Notes |
 | --- | --- | --- |
-| `credential list` | Find credentials in one environment | Requires `--environmentid`; returns the environment's embedded credentials. OAuth signatures are never returned. |
+| `credential list` | Find credentials across environments | Optional `--name`, `--page-size`, and `--cursor`. OAuth signatures are never returned. |
 | `credential create` | Create a Copado environment credential | Requires `--environmentid` and `--name`; `--default` marks it default. |
-| `credential update ID` | Update a Copado environment credential | Requires `--environmentid`; use `--default` or `--no-default`. |
+| `credential update ID` | Update a Copado credential by ID | No environment flag; resolves environment/orgType from the credential. |
+| `credential open ID` | Open a credential in the browser | CLI-only navigation helper. |
+| `credential auth status ID` | Validate a specific credential | Derives the environment from GET `/corpus/credentials/{id}`. |
+| `credential auth web login ID` | Browser OAuth for a specific credential | CLI-only; derives the environment from the credential. |
 
 Examples:
 
 ```sh
-agentia cicd credential list --environmentid <environment-id> --json
+agentia cicd credential list --name CI --json
 agentia cicd credential create --environmentid <environment-id> --name "CI User" --default --json
-agentia cicd credential update <credential-id> --environmentid <environment-id> --no-default --json
+agentia cicd credential update <credential-id> --no-default --json
+agentia cicd credential open <credential-id>
+agentia cicd credential auth status <credential-id> --json
+agentia cicd credential auth web login <credential-id>
 ```
 
 ## When To Use Which Credential
 
 - Use `agentia auth set --cicd` when the CLI cannot authenticate to the Copado CICD API.
-- Use `agentia cicd credential list` to inspect an environment's credential records before changing authentication or defaults.
+- Use `agentia cicd credential list` to discover credentials without first knowing an environment ID.
 - Use `agentia cicd credential create/update` when a Copado environment needs a Salesforce org credential record.
-- Use `agentia cicd environment auth web login` when a credential exists but needs browser-based OAuth authentication.
+- Use `agentia cicd credential auth web login` when you already know the credential ID; use `agentia cicd environment auth web login` when you want automatic/default selection within an environment.
 - Use `agentia auth get --cicd --json` to inspect local CLI auth status without exposing the raw API key.
 
 ## Gotchas
 
 - Custom Domain environments are not supported by the credential create/update helpers.
-- The credential helper reads the environment first and copies its org type into the credential payload.
+- Create still reads the environment first and copies its org type into the credential payload; update and credential-targeted auth derive environment/orgType from the global credential record.
 - Environment authentication can auto-select only when there is a single obvious credential. Pass `--credentialid` if multiple credentials exist.
-- Browser login is intentionally CLI-only; there is no equivalent MCP flow.
+- Browser login and open are intentionally CLI-only; MCP exposes `agentia_credential_auth_status` for non-interactive validation.

package/templates/skills/agentia-cicd/references/extensions.md

@@ -0,0 +1,52 @@
+
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Copado CICD Extensions
+
+Use this reference for experimental git-hosted extension commands under `agentia cicd extension ...`.
+
+## Scope
+
+`cicd extension` packages Copado Functions and Job Templates (plus optional `force-app`) as a git repository with a semver tag. It is not the same as individual `cicd function` / `cicd template` upserts, Salesforce unlocked packages, or MCP tools (none in v1).
+
+Layout:
+
+- `copado/extension_manifest.json` (includes additive semver `version`)
+- `copado/functions/`
+- `copado/templates/`
+- optional `force-app/`
+
+## Author workflow
+
+```sh
+agentia cicd extension create --name my-extension --version 1.0.0
+agentia cicd extension validate --require-version
+agentia cicd extension package --json
+# commit the manifest version before publish
+agentia cicd extension publish --remote origin
+agentia cicd extension publish --local --force   # offline tag only
+```
+
+`publish --version` fails if the bump is still uncommitted. Prefer committing the version, then publishing without rewriting it.
+
+## Install and uninstall
+
+```sh
+agentia cicd extension install https://gitlab.com/org/my-ext.git --version 1.0.0 --dry-run
+agentia cicd extension install https://gitlab.com/org/my-ext.git --version 1.0.0 --yes --sf-alias destOrg
+agentia cicd extension install ./my-extension --version 1.0.0 --exclude-sf-deploy --yes --json
+agentia cicd extension uninstall ./my-extension --version 1.0.0 --yes --json
+```
+
+Rules:
+
+- Install and uninstall need `--yes` (or a prompt) except `--dry-run`.
+- `force-app` needs `--sf-alias` or `--exclude-sf-deploy`.
+- Symlinks and paths outside the extension root are rejected.
+- Uninstall deletes listed Functions/Templates only (404 = already gone); it does not undeploy `force-app`.
+
+## Related
+
+- Individual Functions: [functions.md](functions.md)
+- Individual Job Templates: [templates.md](templates.md)
+- Customer enablement: `docs/enablement/features/agentia-cli-cicd-extensions.md`

package/templates/skills/agentia-cicd/references/pipelines.md

@@ -2,9 +2,9 @@
 
 # CICD Pipelines Reference
 
-Use this reference for `agentia cicd pipeline ...`, `agentia cicd pipeline connection ...`, `agentia cicd pipeline stage-connection ...`, and `agentia cicd stage ...`.
+Use this reference for `agentia cicd pipeline ...`, `agentia cicd pipeline automation ...`, `agentia cicd pipeline quality-gate ...`, `agentia cicd pipeline connection ...`, `agentia cicd pipeline stage-connection ...`, `agentia cicd stage ...`, and `agentia cicd extension-configuration ...`.
 
-Pipeline connections, stage connections, and stages are related but distinct. Read the target object before mutating it.
+Pipeline connections, stage connections, stages, automation rules, quality gates, and extension configurations are related but distinct. Read the target object before mutating it. These pipeline quality gates are not local `cicd work test` quality gates.
 
 ## Pipeline Commands
 
@@ -23,6 +23,38 @@ agentia cicd pipeline list --platform SFDX --active --json
 agentia cicd pipeline get <pipeline-id> --json
 ```
 
+## Automation Rules
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `pipeline automation list --pipeline-id <id>` | List automation rules | Filters: `--active`, `--name`, `--source-action`, `--execution-time`, `--include-system-generated`. |
+| `pipeline automation get ID --pipeline-id <id>` | Inspect one rule | Accepts Id or name. |
+| `pipeline automation create --pipeline-id <id> ...` | Create an inactive rule | Scopes: `promotion`, `backPromotion`, `environmentSyncBackPromotion`, `advanced`. Requires stage/environment targets; Scheduled needs `--cron-expression`. Optional `--filter-criteria` is a user-story filter: builder `{mode,logic,conditions[]}` or custom `{mode:"custom",whereCondition}`. |
+| `pipeline automation update ID --pipeline-id <id> ...` | Sparse update | Scope is immutable after create. |
+| `pipeline automation activate\|deactivate ID --pipeline-id <id>` | Lifecycle | Salesforce Id only (not name). Requires Copado Deployer ≥ 27.46. |
+| `pipeline automation delete ID --pipeline-id <id> --yes` | Delete | Confirmation required for headless/JSON. |
+| `pipeline automation open ID` | Open in browser | Salesforce Id only. |
+
+## Quality Gates
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `pipeline quality-gate list --pipeline-id <id>` | List quality gates | Filters: `--name`, `--tool`. |
+| `pipeline quality-gate get ID --pipeline-id <id>` | Inspect one gate | Aggregate may include multiple conditions. |
+| `pipeline quality-gate create --pipeline-id <id> ...` | Create inactive gates | Requires an active `--extension-configuration-id` and targeting (`--entire-pipeline` or stage/environment Ids). Optional `--filter-criteria` is a metadata-change filter (`Name`/`Type`/`Directory` conditions + numbered `logic`). Create may return an array. |
+| `pipeline quality-gate update ID --pipeline-id <id> ...` | Sparse update | Gate must be inactive; update uses singular `--stage-id` / `--environment-id`. |
+| `pipeline quality-gate activate\|deactivate ID --pipeline-id <id>` | Lifecycle | Salesforce Id only. |
+| `pipeline quality-gate delete ID --pipeline-id <id> --yes` | Delete inactive gate | Confirmation required for headless/JSON. |
+| `pipeline quality-gate open ID` | Open in browser | Salesforce Id only. |
+
+## Extension Configurations
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `extension-configuration list` | Discover configs | Filters: `--name`, `--tool`, `--test-type`, `--active`. |
+| `extension-configuration get ID` | Inspect one config | Accepts Id or name. |
+| `extension-configuration open ID` | Open in browser | Salesforce Id only. Create/update/activate are not exposed (gateway lifecycle currently unavailable). |
+
 ## Environment Connections
 
 Pipeline connections define source-to-destination environment promotion edges.
@@ -59,5 +91,7 @@ Stages are reusable stage records. Stage connections order those stages inside a
 - `pipeline connection` is an environment promotion edge.
 - `pipeline stage-connection` is the ordered stage chain inside a pipeline.
 - `cicd stage` manages stage records that can be referenced by stage connections.
+- Pipeline `quality-gate` commands manage Copado pipeline quality gates. Local script gates remain under `cicd work test`.
+- Activate/deactivate and open require Salesforce Ids, not names.
 - Delete commands prompt in interactive mode. Use `--yes` only when the user already confirmed the destructive action.
 - Repository setup is a neighboring domain: pipelines can reference `--git-repository-id`, but repository lifecycle commands are under `agentia cicd repository`.

package/templates/skills/agentia-cicd/references/work.md

@@ -1,5 +1,7 @@
 
 
+<!-- Agentia managed skill file: agentia setup skills -->
+
 # CICD Work Reference
 
 Use this reference for `agentia cicd work ...`, `agentia cicd cloud ...`, and matching MCP tools such as `agentia_work_get`, `agentia_cloud_commit`, `agentia_work_publish`, and `agentia_work_submit`.
@@ -19,7 +21,7 @@ agentia cicd work get --json
 
 Omit the positional story ID only; keep `--json` so agents parse the `result` object. With MCP, call `agentia_work_get` without an `id` when available.
 
-**On success:** treat the JSON `result` user story as the story context for the rest of the task. Reuse any returned fields later commands or flags need (identifiers, names, status, acceptance criteria, functional or technical specs, pipeline or environment references, and similar)—not only `id` and `name`.
+**On success:** treat the JSON `result` user story as the story context for the rest of the task. Reuse any returned fields later commands or flags need (identifiers, names, status, acceptance criteria, functional or technical specs, pipeline or environment references, subscriber `customFields`, and similar)—not only `id` and `name`.
 
 **On failure:** the CLI exits when no active work item is recorded (typical message: no active work item; suggestion to run `agentia cicd work set <id>`). Tell the user that no current story is set, include the sanitized error text, and stop. Do not invent an ID, run `work list` to pick one, or continue the original request until the user sets context or provides an explicit story ID.
 
@@ -47,7 +49,7 @@ Use this path when the change exists in the local repository:
 Use this path when Copado should retrieve metadata from a configured source environment instead of using local Git changes:
 
 1. Inspect the Story and pass its Salesforce ID explicitly when possible. An active Story from `work set` is optional, not a prerequisite for the cloud operation.
-2. Start a cloud commit with `agentia cicd cloud commit <story-id> ... --json`. Use the simple metadata flags for one change, or `--file`/`--stdin` for a multi-change request. Salesforce metadata requires `--metadata-category SFDX`.
+2. Start a cloud commit with `agentia cicd cloud commit <story-id> ... --json`. Use the simple metadata flags for one change, or `--file`/`--stdin` for a multi-change request. Always pass `--metadata-category` (use `SFDX` for Salesforce metadata). With `--file`/`--stdin`, each change requires `c` (or `category`).
 3. Let the command wait for its Job Execution by default. After a timeout, use the returned execution ID with `agentia cicd job get` and `agentia cicd job log get`; do not immediately submit a duplicate commit.
 4. When explicitly approved to promote an existing Promotion, use `agentia cicd cloud promote <story-id> --json`; add `--deploy` only for promote-and-deploy. This is independent of local `work submit`.
 
@@ -59,18 +61,18 @@ Cloud commit checks Story readiness and source credentials before submission. Av
 | Command            | Use For                                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `work list`        | Find candidate stories                         | Use `--assigned-to-me`, `--status`, `--project-name`, `--name`, pagination flags.                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `work get [ID]`    | Read story details                             | ID is optional after `work set`. Human output redacts OAuth signatures; JSON preserves structured fields.                                                                                                                                                                                                                                                                                                                                                                                            |
-| `work create`      | Create a story                                 | Use `--title`, project/team/assignee/theme fields, specs, and short acceptance criteria. `--source-credential` sends `sourceEnvironment` as null so Salesforce assigns the environment.                                                                                                                                                                                                                                                                                                              |
-| `work update [ID]` | Mutate story fields or status                  | ID is optional after `work set`. Acceptance criteria must be fewer than 255 chars. `--source-credential` sends `sourceEnvironment` as null.                                                                                                                                                                                                                                                                                                                                                          |
+| `work get [ID]`    | Read story details                             | ID is optional after `work set`. Human output redacts OAuth signatures; JSON preserves structured fields including subscriber `customFields` (`apiName`, `label`, `type`, `value`, `displayValue`, `updateable`, optional `options`). `--committed-metadata` also includes the Story committed metadata list as `committedMetadata` in the result.                                                                                                                                                |
+| `work create`      | Create a story                                 | Use `--title`, project/team/assignee/theme fields, specs, and short acceptance criteria. Write subscriber fields with repeatable `--custom-field ApiName=value` (MCP: `customFields: [{ apiName, value }]`). `--source-credential` sends `sourceEnvironment` as null so Salesforce assigns the environment.                                                                                                                                                                                          |
+| `work update [ID]` | Mutate story fields or status                  | ID is optional after `work set`. Acceptance criteria must be fewer than 255 chars. Same `--custom-field` / MCP `customFields` write shape as create; update-only custom fields is allowed. `--source-credential` sends `sourceEnvironment` as null.                                                                                                                                                                                                                                                  |
 | `work set ID`      | Mark active and prepare branch                 | Fetches the base branch and, when present, the remote feature branch; creates/checks out `feature/<story-name>` from `origin/feature` when that ref exists, otherwise from the base; stores local context. A gateway warning prints the message, skips git, clears branch keys, and records work-item id/name/title. Warns without PATCHing when the Story credential differs from the project default; use `work update --source-credential` to change it. `--none` clears every `last*` key and checks out `lastBaseBranch`, else `main`, else `master`. |
-| `cloud commit`     | Copado cloud metadata commit                   | For local Git work, use `git commit` then `work publish`. `work commit` is a hidden compatibility alias.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `cloud commit`     | Copado cloud metadata commit                   | Prefer `agentia cicd cloud commit`. Requires `--metadata-category` (or `c`/`category` per `--file` change); use `SFDX` for Salesforce metadata. For local Git work, use `git commit` then `work publish`. `cicd work commit` remains a hidden compatibility alias.                                                                                                                                                                                                                                  |
 | `work publish`     | Publish local commits and register with Copado | Requires active story context and clean tree. Accepts `--permissions` and `--full-metadata` when nested detection is not enough. `work push` is a compatibility alias.                                                                                                                                                                                                                                                                                                                               |
 | `work test`        | Run local quality gate scripts                 | `--local` is default. Runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from repo root. If missing, warns and runs the stock setup sample from a temp file. `--cloud` is not implemented yet.                                                                                                                                                                                                                                                                                         |
 | `work test apex`   | Run named Apex test classes                    | Optional `--apex-test-classes`. Omit or pass empty to log a skip and exit 0 without calling Salesforce CLI. `--rerun-failed-apex-tests` reruns classes from `.agentia/apex.tests.<user-story>.json`. Optional `--wait` minutes (default 60). Usually invoked from `.agentia_quality_gates.*`. |
 | `work submit`      | Submit for review/validation or promote        | Runs local gates unless `--skip-local-tests`; can push ahead commits. Waits up to 5 minutes when the last pending related job template contains `Commit`. `--skip-pull-request` skips opening the MR URL. `--done` and `--deploy` match Copado UI Submit when promoting.                                                                                                                                                                                                                             |
 | `work done`        | Compatibility alias                            | Prefer `work submit --done`; both promote and deploy rather than validate-only.                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `work promote`     | Experimental local promotion                   | Skips Quality Gates. Requires `enableLocalPromote: true` in `.agentia/config.json`. Merges `feature/<name>` into `promotion/<promotionName>`. Use `--backpromote --destination-branch` for back promotions; `--continue` after conflict resolution.                                                                                                                                                                                                                                                  |
-| `work environment-sync` | Sync next-env commits onto dest/dev       | Back-promotes every story behind the destination environment. Use `--destination-environment` or `--dev-org-branch`; `--continue --promotion` after pathspec conflicts.                                                                                                                                                                                                                                                                                                                             |
+| `work environment-sync` | Sync next-env commits onto dest/dev       | Back-promotes every story behind the destination environment. Use `--destination-environment` or `--dev-org-branch`. On conflict, stores `lastEnvironmentSyncName` so `--continue` / `--abort` can omit `--promotion` (cleared on success, abort, and `work set`).                                                                                                                                                                                                                                  |
 | `cloud promote`    | Story-centric cloud promotion run              | Use `--deploy` for merge and deploy. Prefer this over local `work promote` unless you explicitly enabled local promote.                                                                                                                                                                                                                                                                                                                                                                              |
 | `work status [ID]` | Check story and related executions             | Useful after submit, promote, or commit jobs.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `work open [ID]`   | Open story in browser                          | CLI-only browser helper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -105,7 +107,7 @@ agentia cicd cloud commit <story-id> --message "Commit AccountService" --metadat
 agentia cicd cloud commit <story-id> --file commit-request.json --json
 ```
 
-For Salesforce metadata, include `--metadata-category SFDX`. Without the SFDX category, Copado deploy logs can report "Salesforce changes not found."
+`--metadata-category` is required on simple flag input. Each `--file`/`--stdin` change requires `c` (or `category`). For Salesforce metadata, use `SFDX`. Without `c:SFDX`, Copado deploy logs can report "Salesforce changes not found."
 
 For a cloud promotion, the Story must already belong to a Promotion:
 
@@ -116,6 +118,21 @@ agentia cicd cloud promote <story-id> --deploy --json
 
 Cloud commit and promotion wait for Job Executions by default and return nonzero on failed or timed-out jobs while preserving diagnostic IDs. If a Promotion reaches Merge Conflict, resolve it and resume the original execution; do not start a replacement run.
 
+## Subscriber Custom Fields
+
+Org-defined User Story fields (API names ending in `__c`, excluding packaged `copado__*`) are exposed as `customFields` on `work get` / create / update responses.
+
+- **Read:** prefer `agentia cicd work get [id] --json` (or MCP `agentia_work_get`) and use `result.customFields`. Prefer `displayValue` when presenting values; use `apiName` when writing. Human output lists them under `Custom Fields:` after `Components:`.
+- **Write (CLI):** repeatable `--custom-field ApiName=value` (string values; first `=` splits key/value). Duplicate `apiName` values are rejected.
+- **Write (MCP):** `customFields: [{ "apiName": "JIRA_Key__c", "value": "CICD-1" }]` on `agentia_work_create` / `agentia_work_update` (values may be string, number, boolean, or null).
+- Omit custom-field flags/args for packaged-only mutations. Unknown or non-updateable names fail with gateway `PLA-US-009`.
+
+```sh
+agentia cicd work create --title "Story" --custom-field JIRA_Key__c=CICD-1 --json
+agentia cicd work update --custom-field Priority_Pick__c=P1 --json
+agentia cicd work get --json
+```
+
 ## Deployment Steps
 
 Deployment steps are attached to a user story and run during promotion.

package/templates/skills/agentia-metadata/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: agentia-metadata
+description: Org Intelligence — read Salesforce metadata in a sandbox or developer org through Agentia `cicd metadata explore` (and MCP `agentia_metadata_explore`). Use when listing or searching metadata names, reading items by API name, finding where a class/field/etc is referenced, describing types, reading type documentation, or running specified Apex tests. Prefer local project files first, then the org. Reads metadata only (not org data); does not edit or deploy metadata.
+---
+
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Org Intelligence (Agentia Metadata Exploration)
+
+**Org Intelligence** lets you inspect Salesforce **metadata** in the user's
+connected sandbox / developer org via `cicd metadata explore` (MCP
+`agentia_metadata_explore`). Prefer MCP when available; otherwise use the CLI
+with `--json` when results will be parsed.
+
+Covers Apex classes, triggers, objects, fields, Flows, and other Metadata API
+types. First release is **read-oriented** only—do not invent validate, deploy,
+create, update, or `check_async_id`.
+
+## Capabilities And Limits
+
+| Can | Cannot |
+| --- | --- |
+| Read / list / search / describe **metadata** | Read or query **org data** (records, SOQL results, reports as data) |
+| Find metadata references (`find_references`) | **Edit**, create, update, validate, or deploy metadata |
+| Run specified Apex test classes (when asked) | Mass-scan or compare entire orgs |
+
+If the user asks to change metadata or fetch record data, say Org Intelligence
+cannot do that and point them at the appropriate Copado/Agentia workflow or
+local editing instead.
+
+## Source Priority
+
+1. **Local project files first** (workspace / git / force-app / retrieved source)
+   when they exist and answer the question.
+2. **Then the connected org** via Org Intelligence (`cicd metadata explore`)
+   for names, bodies, docs, and references that are missing or unclear locally.
+
+Do not call the org when local files already provide a clear answer. Prefer
+local when reconciling differences unless the user asks for the org version.
+
+## What You Can Do
+
+| Goal | Action |
+| --- | --- |
+| List metadata names that match a pattern | `list` |
+| Search source (Apex Page/Class/Trigger/Component only) | `search` |
+| Retrieve one item by API name | `read` |
+| Find where a class/field/etc is used or called | `find_references` |
+| Describe a metadata type shape | `describe_type` |
+| Get type documentation from the tool | `read_documentation` |
+| Run specific Apex test classes | `run_apex_tests` |
+
+Use `list` / `search` to discover exact names before `read` or
+`find_references`. Pass type + name for references. Confirm with the user
+before `run_apex_tests`.
+
+## Org And Scope
+
+- Target is the CICD project default credential when `--credential-id` /
+  `credentialId` is omitted. Pass `--credential-id` only to override. Do not
+  mix credential auth with `--session-id` + `--endpoint`.
+- The user may call this **Org Intelligence**, or the connected org **Org**,
+  **Sandbox**, **Integration**, **Dev Org**, or similar—treat those as the
+  same target unless they ask for a different credential.
+- You can access selected metadata. You **cannot** compare orgs or run mass
+  analysis / full-org scans—that hits limits and takes too long. If a list is
+  truncated or incomplete, say you cannot finish that breadth of scan and ask
+  the user to narrow the request.
+
+## Pattern And Type Rules
+
+- **Always quote CLI wildcards** (`--pattern 'Account*'`). Unquoted `*` is
+  expanded by the shell. MCP `pattern` does not need shell quotes.
+- **`search`** only covers `ApexPage`, `ApexClass`, `ApexTrigger`, and
+  `ApexComponent`. Pattern ≥ 2 characters, at most one `*`.
+- **`list` for CustomField / FieldSet / DuplicateRule / ListView** — pattern
+  must start with the SObject name and a dot (e.g. `Account.Name`,
+  `Account.namespace__Name__c`). You cannot list every item of every object.
+- **`list` for Flow** — `--pattern` matches API name, Flow label, and
+  triggering object API name.
+- **Profiles** — reading Profile details is not supported. Tell the user you
+  cannot answer questions about Profile contents. Listing Profile names may
+  still be attempted if useful, but do not claim you can read their body.
+- **Reports, Dashboards, and Folders** — listing is not supported; say so.
+
+## Apex Tests
+
+- You cannot run all tests or local tests.
+- Ask the user which test class names to run, then pass them via
+  `--apex-unit-tests` / `apexUnitTests` (comma-separated).
+
+## How To Call
+
+```sh
+agentia cicd metadata explore --action describe_type --object-type ApexClass --json
+agentia cicd metadata explore --action list --object-type ApexClass --pattern 'Account*' --json
+agentia cicd metadata explore --action search --pattern 'Cont*' --json
+agentia cicd metadata explore --action read --object-type ApexClass --full-name MyClass --json
+agentia cicd metadata explore --action find_references --object-type ApexClass --full-name MyClass --json
+agentia cicd metadata explore --action run_apex_tests --apex-unit-tests MyClassTest --json
+```
+
+| Surface | Name |
+| --- | --- |
+| CLI | `agentia cicd metadata explore` |
+| MCP | `agentia_metadata_explore` |
+
+Tool/CLI output is YAML inside `output` (human mode prints YAML; `--json` /
+MCP return `{ output, credentialId? }`). **When talking to the user, respond in
+XML—not YAML.** Summarize findings; do not dump full tool YAML unless asked.
+Never echo session Ids, API keys, or other secrets.
+
+## Gathering Context For Generated Code
+
+When helping the user design or draft Salesforce metadata (local edits only):
+
+- Prefer **local files**, then Org Intelligence `list` / `search` / `read` /
+  `describe_type` / `find_references` for accurate names and patterns.
+- When drafting new Apex tests, search local code or ask about existing
+  conventions (data factories, test setup) before querying the org.
+- Present draft code with the client's normal artifact / code-block features.
+  Org Intelligence does not write metadata to the org.
+
+## Safety
+
+- Stay on the supported read actions above—no metadata edits, no org data.
+- Prefer sandbox/dev credentials; treat production as explicit and high-risk.
+- Narrow `--pattern` when lists are large or truncated.
+- Experimental command: expect a warning in human/JSON output.
+
+## Reference
+
+Flags, MCP args, examples, and gotchas:
+[references/metadata-explore.md](references/metadata-explore.md)
+
+## Report Back
+
+Report actions run, object type / fullName / pattern, credential Id (never
+session Id), and outcome (names found, test result summary, or error). Do not
+include secrets. Use XML in the user-facing reply.