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

package/oclif.manifest.json

@@ -6294,6 +6294,164 @@
         "update.js"
       ]
     },
+    "setup:skills:create": {
+      "aliases": [],
+      "args": {},
+      "description": "Create portable Markdown-only Agentia CLI skills in this project without overwriting managed files",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --cicd --target agents --no-prompt",
+        "<%= config.bin %> <%= command.id %> --testing --ai --target cursor --no-prompt",
+        "<%= config.bin %> <%= command.id %> --json"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "ai": {
+          "description": "Create the Copado AI agent skill pack",
+          "name": "ai",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "cicd": {
+          "description": "Create the Copado CICD skill pack",
+          "name": "cicd",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "force": {
+          "description": "Replace conflicting unmanaged Agentia skill files",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-prompt": {
+          "char": "n",
+          "description": "Skip interactive prompts; defaults the target to .agents/skills when --target is omitted",
+          "name": "no-prompt",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "target": {
+          "description": "Project skill root to write",
+          "name": "target",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "agents",
+            "cursor",
+            "claude"
+          ],
+          "type": "option"
+        },
+        "testing": {
+          "description": "Create the Copado Robotic Testing skill pack",
+          "name": "testing",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "setup:skills:create",
+      "pluginAlias": "@copado/agentia-cli",
+      "pluginName": "@copado/agentia-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "setup",
+        "skills",
+        "create.js"
+      ]
+    },
+    "setup:skills:update": {
+      "aliases": [],
+      "args": {},
+      "description": "Update Agentia-managed Markdown skill files and restore missing files in this project",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> --ai --target cursor --no-prompt",
+        "<%= config.bin %> <%= command.id %> --cicd --testing --target agents --no-prompt",
+        "<%= config.bin %> <%= command.id %> --force --json"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "ai": {
+          "description": "Update the Copado AI agent skill pack",
+          "name": "ai",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "cicd": {
+          "description": "Update the Copado CICD skill pack",
+          "name": "cicd",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "force": {
+          "description": "Replace conflicting unmanaged Agentia skill files",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-prompt": {
+          "char": "n",
+          "description": "Skip interactive prompts; defaults the target to .agents/skills when --target is omitted",
+          "name": "no-prompt",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "target": {
+          "description": "Project skill root to write",
+          "name": "target",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "agents",
+            "cursor",
+            "claude"
+          ],
+          "type": "option"
+        },
+        "testing": {
+          "description": "Update the Copado Robotic Testing skill pack",
+          "name": "testing",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "setup:skills:update",
+      "pluginAlias": "@copado/agentia-cli",
+      "pluginName": "@copado/agentia-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "setup",
+        "skills",
+        "update.js"
+      ]
+    },
     "testing:build:abort": {
       "aliases": [],
       "args": {
@@ -13470,5 +13628,5 @@
       ]
     }
   },
-  "version": "0.85.0-alpha.0"
+  "version": "0.86.0-alpha.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@copado/agentia-cli",
   "description": "Command-line interface for Agentia",
-  "version": "0.85.0-alpha.0",
+  "version": "0.86.0-alpha.0",
   "author": "Copado Solutions",
   "bin": {
     "agentia": "./bin/run.js"
@@ -44,6 +44,7 @@
     "./bin",
     "./dist",
     "./oclif.manifest.json",
+    "./templates",
     "./vendor/java"
   ],
   "homepage": "https://github.com/Copado/agentia-cli",
@@ -183,6 +184,12 @@
       "mcp": {
         "description": "Start a local Model Context Protocol server for MCP-compatible clients"
       },
+      "setup": {
+        "description": "Prepare Agentia local project assets"
+      },
+      "setup:skills": {
+        "description": "Create and update Agentia Agent Skills"
+      },
       "testing": {
         "description": "Manage Copado Robotic Testing projects, tests, runs, logs, and variables"
       }

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

@@ -0,0 +1,34 @@
+---
+name: agentia-ai
+description: Use this skill when prompting Copado AI agents through the Agentia CLI or MCP, including `agentia ai agent ask`, `agentia ai agent chat`, Plan, Build, Test, Release, Operate, Knowledge, workspace, dialogue, user story, Salesforce org, and component context.
+---
+
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Agentia AI
+
+Use this skill to ask Copado AI agents through Agentia with the right agent selector, workspace context, and output mode.
+
+Prefer the `agentia_ai_ask` MCP tool when it is available for single-turn prompts. Use CLI examples as the fallback. Use `agentia ai agent chat` only for interactive terminal sessions.
+
+## Start Here
+
+1. Confirm AI auth with `agentia auth get --ai --json`, or provide `--pat`, `--domain`, `--org`, and optional `--gateway-url`.
+2. Choose exactly one agent selector for `ask`: `--plan`, `--build`, `--test`, `--release`, `--operate`, or `--knowledge`.
+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
+
+- Copado AI agent prompts, chat sessions, workspace context, MCP parity, and gotchas: [references/ai-agents.md](references/ai-agents.md)
+
+## General Rules
+
+- Keep prompts specific and include IDs or names read from Copado or the local project.
+- Use the Knowledge agent for Copado AI Knowledge grounding and product questions.
+- Use the Plan, Build, Test, Release, and Operate agents according to the lifecycle intent.
+- Do not paste PATs or secrets into prompts.
+
+## Report Back
+
+Report the selected AI agent, workspace/dialogue identifiers when returned, whether the response was streamed or buffered, and any follow-up action. Do not include secrets.

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

@@ -0,0 +1,70 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# AI Agents Reference
+
+Use this reference for `agentia ai agent ask`, `agentia ai agent chat`, and the matching `agentia_ai_ask` MCP tool.
+
+## Authentication And Context
+
+Configure AI once:
+
+```sh
+agentia auth set --ai --ai-domain <domain> --ai-org <organization-id> --ai-workspace <workspace-id>
+agentia auth get --ai --json
+```
+
+Per-command overrides include `--pat`, `--domain`, `--org`, `--workspace`, `--gateway-url`, and `--timeout`. Do not print PAT values.
+
+## Agent Selectors
+
+| Selector | Use For |
+| --- | --- |
+| `--plan` | Break requirements into delivery plans and acceptance criteria. |
+| `--build` | Implementation guidance, code-level questions, and construction tasks. |
+| `--test` | Test strategy, regression selection, and test troubleshooting. |
+| `--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. |
+
+Choose one selector that matches the user's intent. `ask` requires a prompt with `-p` or `--prompt`; `chat` is TTY-only and prompts interactively.
+
+## Single-Turn Ask
+
+Use `ask` for automation and agent-to-agent workflows:
+
+```sh
+agentia ai agent ask --plan -p "Break this user story into implementation steps" --json
+agentia ai agent ask --knowledge -p "Summarize Copado guidance for data template sync" --no-stream --json
+agentia ai agent ask --build --user-story US-1042 --component AccountService -p "Review the implementation approach" --json
+```
+
+MCP `agentia_ai_ask` mirrors the buffered JSON-safe ask flow. It does not provide interactive chat.
+
+## Interactive Chat
+
+Use `chat` only when a human is present in a terminal:
+
+```sh
+agentia ai agent chat --build --user-story US-1042
+agentia ai agent chat --orchestrate --workspace <workspace-id>
+```
+
+Chat creates or reuses one dialogue for the session and supports session slash commands. It is not suitable for headless JSON workflows.
+
+## Workspace And Quota Helpers
+
+Use these adjacent commands when the prompt workflow needs context setup:
+
+| Command | Use For |
+| --- | --- |
+| `ai workspace list|get|create|update` | Inspect or manage Copado AI workspaces. |
+| `ai workspace member list|invite` | Inspect or invite workspace members. |
+| `ai quota get` | Check organization quota before large AI activity. |
+
+## Gotchas
+
+- `--workspace` selects the workspace; `--dialogue` reuses a conversation inside that workspace.
+- `--user-story`, `--sf-org`, and `--component` enrich prompt context but do not replace a clear prompt.
+- Streaming is human-friendly. For tools, CI, or follow-up parsing, use `--json` and consider `--no-stream`.
+- `chat` has no MCP equivalent and should not be used in non-interactive shells.

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

@@ -0,0 +1,41 @@
+---
+name: agentia-cicd
+description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools: user stories, work commit/push/submit/done, promotion runs and conflicts, job executions, environments, credentials, pipelines, stages, 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 -->
+
+# Agentia CICD
+
+Use this skill to operate Copado CICD through Agentia without guessing command order, IDs, or JSON fields.
+
+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 `agentia auth get --cicd --json` is configured, or that the current process supplies `AGENTIA_CICD_API_KEY` and `AGENTIA_CICD_BASE_URL`.
+2. Identify the domain below and read only the matching reference file.
+3. Before mutating data, read the target record first with the matching `get`, `list`, or `status` command.
+4. Never print credentials, PATs, OAuth signatures, or unmasked environment variables.
+
+## References
+
+- User stories, local commits, cloud commits, push, submit, done, quality gates, and deployment steps: [references/work.md](references/work.md)
+- 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 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)
+- Release data templates, records, matching, sync, dataset files, and data commits: [references/data.md](references/data.md)
+
+## General Rules
+
+- 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 push`, `work submit`, and `work done`.
+- Treat `cicd job` as Copado CICD JobExecution. It is different from CRT `testing job`.
+- Treat `cicd work test --local` as local quality gates. It is different from CRT `testing test run`.
+- Treat `auth` credentials as keychain/API credentials and `cicd credential` records as Copado environment credentials.
+
+## Report Back
+
+When you finish a CICD operation, report the command path used, target IDs or names, final status, whether JSON was used, and any remaining manual action. Do not include secrets.

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.