@copado/agentia-cli 0.85.0-alpha.0 → 0.87.0-alpha.0

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

@@ -0,0 +1,65 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Data Reference
+
+Use this reference for Release Data Template commands under `agentia cicd data ...`.
+
+Data commands often accept large JSON bodies. Prefer `--file` or `--stdin` for complex payloads and `--json` for machine-readable responses.
+
+## Template Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `data template list` | Find templates | Filter by name, main object, active flag, and related records. |
+| `data template get ID` | Export selected-column graph | Good for agent inspection and lightweight export. |
+| `data template get-detail ID` | Get raw v2 detail | Use before editing or saving detail JSON. |
+| `data template create` | Create a template | Requires credential, template/API name, and main object fields. |
+| `data template save-detail ID` | Save v2 detail JSON | Use `--file` or `--stdin`. |
+| `data template convert-old ID` | Convert legacy templates | Read current template first. |
+| `data template delete ID` | Delete a template | Destructive; confirm target and intent. |
+| `data template open ID` | Open in browser | CLI-only navigation helper. |
+
+Example:
+
+```sh
+agentia cicd data template list --active --fetch-related --json
+agentia cicd data template create --credential-id <credential-id> --template-name Accounts --api-name Accounts --main-object-api-name Account --main-object-label Account --json
+```
+
+## Records, Matching, Filters, And Formulas
+
+| Command | Use For |
+| --- | --- |
+| `data records search` | Search source records for a template and credential. |
+| `data records match` | Match source records to destination records from JSON input. |
+| `data filter list/add/update/delete` | Manage advanced filters attached to a template. |
+| `data formula list/create/update` | Manage record matching formulas, with up to three fields. |
+| `data sobject fields` | Describe available fields for an sObject and credential. |
+| `data sobject relationships` | Describe relationships for an sObject and credential. |
+| `data sync preview-updates` | Preview data template field sync changes. |
+| `data sync apply` | Apply data template field sync changes. |
+
+Use describe commands before generating payloads that mention fields or relationships.
+
+## Data Commits And Dataset Files
+
+| Command | Use For |
+| --- | --- |
+| `data commit create` | Create a data commit on a User Story from JSON input. |
+| `data commit list <user-story-id>` | List data commits attached to a story. |
+| `data dataset-file list <data-commit-id>` | List generated dataset files. |
+| `data dataset-file content <content-version-id>` | Fetch one dataset file's content. |
+
+Example:
+
+```sh
+agentia cicd data commit list <user-story-id> --json
+agentia cicd data dataset-file list <data-commit-id> --json
+```
+
+## Gotchas
+
+- Template IDs, credential IDs, data commit IDs, and ContentVersion IDs are different values. Read the parent record before using child commands.
+- JSON payload commands should use exactly one input source: inline JSON flags, `--file`, or `--stdin`.
+- `data template get` and `data template get-detail` serve different audiences: selected graph export versus raw v2 detail.
+- `data template open` is CLI-only; MCP covers data operations but not browser navigation.

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

@@ -0,0 +1,55 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Environments And Credentials Reference
+
+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` creates or updates Copado environment credential records. They are different credential types.
+
+## Environment Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `environment list` | Find environments | Filter by `--name`, `--org-id`, `--platform`, `--type`, cursor, and page size. |
+| `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. |
+
+Examples:
+
+```sh
+agentia cicd environment list --type Sandbox --json
+agentia cicd environment get <environment-id> --json
+agentia cicd environment auth status <environment-id> --credentialid <credential-id> --json
+```
+
+## Environment Credential Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `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`. |
+
+Examples:
+
+```sh
+agentia cicd credential create --environmentid <environment-id> --name "CI User" --default --json
+agentia cicd credential update <credential-id> --environmentid <environment-id> --no-default --json
+```
+
+## When To Use Which Credential
+
+- Use `agentia auth set --cicd` when the CLI cannot authenticate to the Copado CICD API.
+- 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 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.
+- 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.

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

@@ -0,0 +1,42 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Jobs Reference
+
+Use this reference for Copado CICD JobExecution commands under `agentia cicd job ...`.
+
+`cicd job` is for Copado CICD execution records. It is not the same as CRT `agentia testing job ...` or CRT build runs.
+
+## Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `job list` | Search job executions | Filter by `--status`, `--type`, `--parent`, `--context`, `--mine`, cursor, and page size. |
+| `job get ID` | Inspect a job and ordered steps | Read before action commands or log lookup. |
+| `job log get ID` | Read execution logs | Use `--step <step-id>` when a specific step is needed. |
+| `job run ID` | Run all steps | Use `--restart` only when the user asks to restart from the beginning. |
+| `job resume ID` | Resume outstanding steps | Good after a paused or partially completed job. |
+| `job pause ID` | Pause/cancel resumably | Confirm intent before interrupting active work. |
+| `job kill ID` | Cancel a job | Destructive operational action; confirm target and impact. |
+| `job open ID` | Open in browser | CLI-only navigation helper. |
+
+Examples:
+
+```sh
+agentia cicd job list --status "In Progress" --json
+agentia cicd job get <job-execution-id> --json
+agentia cicd job log get <job-execution-id> --step <step-id> --json
+agentia cicd job resume <job-execution-id> --json
+```
+
+## Monitoring Pattern
+
+1. Use `job list --mine --status "In Progress" --json` or use the job ID returned by another command.
+2. Run `job get <id> --json` to inspect status and step ordering.
+3. Use `job log get <id> --step <step-id>` only when logs are needed for diagnosis.
+4. Use `resume`, `pause`, `kill`, or `run --restart` only after confirming the current status and user intent.
+
+## Gotchas
+
+- Some job tools require user and organization context at the gateway layer. If the CLI reports missing context, inspect auth and user context before retrying.
+- Logs can be large. Prefer a specific step when available.
+- Do not use CICD job commands for Robot Framework builds; use the `agentia-testing` skill for CRT run status and logs.

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

@@ -0,0 +1,63 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Pipelines Reference
+
+Use this reference for `agentia cicd pipeline ...`, `agentia cicd pipeline connection ...`, `agentia cicd pipeline stage-connection ...`, and `agentia cicd stage ...`.
+
+Pipeline connections, stage connections, and stages are related but distinct. Read the target object before mutating it.
+
+## Pipeline Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `pipeline list` | Find pipelines | Filter by `--active`, `--name`, `--platform`, cursor, and page size. |
+| `pipeline get ID` | Inspect one pipeline | Returns describe-style details, including embedded connections. |
+| `pipeline create NAME` | Create a pipeline | Common flags: `--platform`, `--main-branch`, `--git-repository-id`. |
+| `pipeline update ID` | Sparse pipeline changes | Set `--name`, branch, repository, or conflict strategy fields. |
+| `pipeline open ID` | Open in browser | CLI-only navigation helper. |
+
+Example:
+
+```sh
+agentia cicd pipeline list --platform SFDX --active --json
+agentia cicd pipeline get <pipeline-id> --json
+```
+
+## Environment Connections
+
+Pipeline connections define source-to-destination environment promotion edges.
+
+| Command | Use For |
+| --- | --- |
+| `pipeline connection list --pipeline-id <id>` | List environment edges in a pipeline. |
+| `pipeline connection create --pipeline-id <id> ...` | Create one edge or pass a JSON file for bulk creation. |
+| `pipeline connection update --pipeline-id <id> ...` | Update one edge or pass a JSON file for bulk update. |
+| `pipeline connection delete --pipeline-id <id> ... --yes` | Delete one or more edges. |
+| `pipeline connection open ID` | Open one connection in the browser. |
+
+Single-create example:
+
+```sh
+agentia cicd pipeline connection create --pipeline-id <pipeline-id> --source-environment-id <dev-id> --destination-environment-id <uat-id> --branch main --json
+```
+
+## Stages And Stage Connections
+
+Stages are reusable stage records. Stage connections order those stages inside a pipeline.
+
+| Command | Use For |
+| --- | --- |
+| `stage list|get|create|update|delete|open` | Manage stage records. |
+| `pipeline stage-connection list --pipeline-id <id>` | Read ordered stages for a pipeline. |
+| `pipeline stage-connection create --pipeline-id <id> --stage-id <id>` | Add a stage to a pipeline chain. |
+| `pipeline stage-connection update ID --pipeline-id <id>` | Rewire the next stage connection. |
+| `pipeline stage-connection delete ID --pipeline-id <id> --yes` | Remove a stage connection. |
+| `pipeline stage-connection open ID` | Open the stage connection in a browser. |
+
+## Gotchas
+
+- `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.
+- 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/promotions.md

@@ -0,0 +1,58 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Promotions Reference
+
+Use this reference for `agentia cicd promotion ...`, `agentia cicd promotion conflict ...`, and `agentia cicd work promote`.
+
+## Entry Points
+
+| Command | Starts From | Use When |
+| --- | --- | --- |
+| `agentia cicd promotion run <promotion-id>` | Promotion ID | You already know the Promotion record and want explicit merge or merge-and-deploy control. |
+| `agentia cicd work promote [story-id] --cloud` | User Story | You want Agentia to resolve the story's Promotion before running it. |
+| `agentia cicd work done` | Active User Story branch | The story is approved and should move to the next stage through the normal work lifecycle. |
+
+Prefer `work promote` when the user talks about a story. Prefer `promotion run` when the user provides a Promotion ID.
+
+## Promotion Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `promotion list` | Find promotions | Filter by `--work-id`, status, project, pipeline, source/destination environment, or back-promotion flags. |
+| `promotion get ID` | Inspect one promotion | Read this before running, resuming, or resolving conflicts. |
+| `promotion run ID` | Preflight and submit a run | Requires `--operation merge` or `--operation merge_and_deploy` unless `--resume` is used. |
+| `promotion open ID` | Open in browser | CLI-only navigation helper. |
+| `work promote [ID] --cloud` | Story-centric run | Use `--deploy` for merge and deploy; use `--promotion-id` if the story has multiple promotions. |
+
+Example:
+
+```sh
+agentia cicd promotion list --work-id <story-id> --json
+agentia cicd promotion run <promotion-id> --operation merge_and_deploy --json
+agentia cicd work promote <story-id> --cloud --deploy --json
+```
+
+## Resume And Wait
+
+`promotion run` and `work promote` can poll job execution status. Use the default wait for normal agent workflows and lower it only when the user wants a fire-and-follow-up flow.
+
+Use `--resume <job-execution-id>` to resume the original execution after conflict resolution instead of starting a new `/run` request.
+
+## Conflict Commands
+
+| Command | Use For |
+| --- | --- |
+| `promotion conflict list -p <promotion-id>` | List merge conflicts for a promotion. |
+| `promotion conflict get <conflict-id> -p <promotion-id>` | Fetch raw conflict content; use `--output` to write a file. |
+| `promotion conflict resolve <conflict-id> -p <promotion-id> --mode auto` | Let Copado apply automatic resolution. |
+| `promotion conflict resolve <conflict-id> -p <promotion-id> --mode manual --file <path>` | Submit reviewed manual content. |
+| `promotion conflict unresolve <conflict-id> -p <promotion-id>` | Undo a prior resolution. |
+
+Read conflict content before manual resolution. Do not invent resolved content; use the user's reviewed file or ask for confirmation.
+
+## Gotchas
+
+- Promotion IDs are not User Story IDs. Use `work promote` if you only have the story.
+- `--deploy` on `work promote` maps to promotion operation `merge_and_deploy`; without it, the default is merge only.
+- `--recreate-promotion-branch` is a sensitive run option and should be paired with explicit user intent and `--yes` when required.
+- If conflicts exist, resolve them first and then resume the same execution.

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

@@ -0,0 +1,84 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CICD Work Reference
+
+Use this reference for `agentia cicd work ...` and matching MCP tools such as `agentia_work_get`, `agentia_work_commit`, `agentia_work_push`, `agentia_work_submit`, and `agentia_work_done`.
+
+## Workflow
+
+1. Discover: `agentia cicd work list --assigned-to-me --json`
+2. Inspect: `agentia cicd work get <id-or-name> --json`
+3. Activate: `agentia cicd work set <id-or-name> --json`
+4. Implement and choose one commit path:
+   - Local Git: `agentia cicd work commit --local --all --json`
+   - Copado cloud metadata: `agentia cicd work commit <story-id> --cloud --metadata-name <name> --metadata-type <type> --metadata-category SFDX --json`
+5. Register local commits: `agentia cicd work push --json`
+6. Validate and submit: `agentia cicd work submit --json`
+7. Promote only on explicit approval: `agentia cicd work done --json`
+
+`work set`, `work push`, `work submit`, and `work done` expect a clean tracked working tree and the active story context recorded by `work set`.
+
+## Core Commands
+
+| 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. |
+| `work update [ID]` | Mutate story fields or status | ID is optional after `work set`. Acceptance criteria must be fewer than 255 chars. |
+| `work set ID` | Mark active and prepare branch | Fetches base branch, creates/checks out `feature/<story-name>`, stores local context. |
+| `work commit` | Local or cloud commit | `--local` is default; `--cloud` calls Copado commit APIs and can poll a job. |
+| `work push` | Push local commits and register with Copado | Requires active story context and clean tree. Sends stored retrieve-only permissions. |
+| `work test --local` | Run local quality gate scripts | Runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from repo root. |
+| `work submit` | Submit for review/validation | Runs local gates unless `--skip-local-tests`; can push ahead commits. |
+| `work done` | Promote after approval | Pushes if needed, then promotes without validate-only behavior. |
+| `work promote` | Story-centric promotion run | Requires `--cloud`; use `--deploy` for merge and deploy. |
+| `work status [ID]` | Check story and related executions | Useful after submit, done, promote, or commit jobs. |
+| `work open [ID]` | Open story in browser | CLI-only browser helper. |
+
+## Local Commit Path
+
+Use local commits for normal source changes:
+
+```sh
+agentia cicd work commit --local --all --permissions CustomField:Account.SLA__c,ApexClass:AccountService --json
+agentia cicd work push --json
+```
+
+`--permissions` records metadata that Copado should treat as Retrieve Only during push. List the metadata the permissions point at, not the permission set or profile files themselves. The value is sticky in local user config until replaced or cleared with `--permissions ""`.
+
+`--apex-test-classes` records story-related test class names for later reference. `work test --local` and `work submit` still take `--apex-test-classes` explicitly when you want the local gate script to receive them.
+
+## Cloud Commit Path
+
+Use cloud commits when Copado should retrieve metadata itself:
+
+```sh
+agentia cicd work commit <story-id> --cloud --message "Commit AccountService" --metadata-name AccountService --metadata-type ApexClass --metadata-category SFDX --json
+agentia cicd work commit <story-id> --cloud --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."
+
+## Deployment Steps
+
+Deployment steps are attached to a user story and run during promotion.
+
+| Command | Use For |
+| --- | --- |
+| `work deployment-step types` | List supported standard/custom step types. |
+| `work deployment-step salesforce-flows` | List directly invocable Salesforce Flows. |
+| `work deployment-step list` | Inspect current story steps. |
+| `work deployment-step create` | Add Manual Task, Salesforce Flow, Function, Apex, Data Set, Data Template, or Robotic Test steps. |
+| `work deployment-step update` | Apply sparse step updates. |
+| `work deployment-step reorder` | Submit a complete before/after ordering snapshot from file or stdin. |
+| `work deployment-step delete` | Delete an owned step by ID. |
+
+Prefer explicit flags for standard step types. Use `--config-json`, `--file`, or `--stdin` only when the step has expert configuration not covered by flags. Read `types` first when unsure.
+
+## Gotchas
+
+- `work test --local` is not CRT. For Robot Framework execution, use the `agentia-testing` skill.
+- `work submit` and `work done` may push ahead commits, but `work set` is still required first.
+- `work done` promotes/deploys. Do not run it unless the user explicitly asked to promote or finish the story.
+- `work delete` is destructive; read the story and confirm intent first.

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

@@ -0,0 +1,34 @@
+---
+name: agentia-testing
+description: Use this skill when creating, updating, running, inspecting, or troubleshooting Copado Robotic Testing tests with the Agentia CLI, especially commands under `agentia testing test`, CRT projects, robots, jobs, builds, logs, variables, PAT authentication, Git-backed test storage, and Robot Framework execution.
+---
+
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Agentia Testing
+
+Use this skill to operate Copado Robotic Testing through Agentia without confusing CRT projects, robots, jobs, tests, and builds.
+
+Prefer Agentia MCP tools when they are available and match the task. Use CLI examples as the fallback, and add `--json` whenever the result will be parsed or reused.
+
+## Start Here
+
+1. Confirm CRT auth with `agentia auth get --crt --json`, or provide `--pat`, `--domain`, and `--org` on the command.
+2. Identify or create the CRT Project and Robot before creating or running tests.
+3. Use `testing test ...` as the canonical namespace for test workflows. The shorter `testing run|logs|status|create|update` forms exist for compatibility.
+4. Never expose PATs, organization secrets, or generated log content that contains secrets.
+
+## Reference
+
+- CRT test creation, updates, execution, status, logs, and related project/robot/job/build prerequisites: [references/tests.md](references/tests.md)
+
+## General Rules
+
+- `agentia testing test run` starts CRT Robot Framework execution. It is different from `agentia cicd work test --local`.
+- `agentia testing job` manages CRT job/test definitions. It is different from `agentia cicd job`, which manages Copado CICD JobExecution records.
+- Use `--wait-for-result` on `testing test run` when the agent must return the final build result in one turn.
+- Use Git-backed job flags only when the user or project clearly uses repository-backed CRT test storage.
+
+## Report Back
+
+Report the CRT project, robot, job/test ID, build ID when present, final status, and where logs were written or fetched. Do not include PATs or other secrets.

package/templates/skills/agentia-testing/references/tests.md

@@ -0,0 +1,65 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CRT Testing Reference
+
+Use this reference for `agentia testing test ...` and related Copado Robotic Testing commands.
+
+## Authentication And Context
+
+Configure CRT once:
+
+```sh
+agentia auth set --crt --crt-domain <domain> --crt-org <organization-id>
+agentia auth get --crt --json
+```
+
+Most CRT commands also accept per-command `--pat`, `--domain`, and `--org` overrides. Do not print PAT values.
+
+## Canonical Test Workflow
+
+1. List or create a project: `agentia testing project list --json`
+2. List or create a robot: `agentia testing robot list --json`
+3. Create or update a test: `agentia testing test create ... --json`
+4. Run the test: `agentia testing test run <job-id> --project <project-id> --wait-for-result --json`
+5. Inspect status and logs: `agentia testing test status ... --json` and `agentia testing test logs ... --json`
+
+## Test Commands
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `testing test create` | Create a CRT test and upload Robot files | Requires project, robot, name, and `--file` or `--dir`. |
+| `testing test update ID` | Update files for a test | Use `--add`, `--remove`, `--replace`, or Git branch options. |
+| `testing test run ID` | Run a CRT test | Use `--project`; use `--wait-for-result` when the final status is required. |
+| `testing test status` | List build/run status | Filter by project, job, and status. |
+| `testing test logs ID` | Fetch build logs | Use `--project`, `--job`, and optional `--output`. |
+
+Examples:
+
+```sh
+agentia testing test create --project <project-id> --robot <robot-id> --name "Smoke" --file tests/smoke.robot --json
+agentia testing test run <job-id> --project <project-id> --wait-for-result --json
+agentia testing test logs <build-id> --project <project-id> --job <job-id> --output ./crt.log --json
+```
+
+## Related CRT Commands
+
+| Area | Commands | Use For |
+| --- | --- | --- |
+| Projects | `testing project list/create/get/delete` | Top-level CRT project lifecycle. |
+| Robots | `testing robot list/create/get/delete` | Robot worker definitions. |
+| Jobs | `testing job list/create/get/update/delete/files/upload/download` | CRT job/test definitions and file storage. |
+| Builds | `testing build run/list/logs/abort` | Lower-level run/build management. |
+| Variables | `testing variable list/create/update/delete` | CRT variables, with value redaction in output. |
+
+Use related commands to discover IDs needed by `testing test`.
+
+## Git-Backed Tests
+
+Some CRT tests store Robot files in Git. Use Git-backed flags only when the project already expects Git storage or the user asks for it. Preserve branch, path, and credential values from existing job details when updating.
+
+## Gotchas
+
+- The `testing test` namespace and the shorter `testing` namespace overlap. Prefer `testing test` in generated guidance because it makes the CRT domain explicit.
+- There is no `testing test get` or `testing test delete`; use `testing job get` or `testing job delete` for CRT job/test definitions.
+- `testing test run --wait-for-result` can poll until a terminal build status. Without it, the command may return only the started build.
+- Log commands may write files. In JSON mode, keep stdout structured and report the output path instead of mixing log text with JSON.