@copado/agentia-cli 0.92.0-alpha.0 → 0.94.0-alpha.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@copado/agentia-cli",
   "description": "Command-line interface for Agentia",
-  "version": "0.92.0-alpha.0",
+  "version": "0.94.0-alpha.0",
   "author": "Copado Solutions",
   "bin": {
     "agentia": "./bin/run.js"

package/templates/AGENTS.md

@@ -0,0 +1,24 @@
+# Agentia CLI for AI Agents
+
+<!-- agentia:managed:start -->
+
+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 → commit → push → submit → done`
+
+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 Agentia skill. Prefer the client-specific root when available (`.cursor/skills` in Cursor or `.claude/skills` in Claude); otherwise use `.agents/skills`.
+
+- `agentia-cicd/SKILL.md`: Copado stories, commits, push, submit, done, promotions, jobs, environments, pipelines, and data.
+- `agentia-testing/SKILL.md`: Copado Robotic Testing operations.
+- `agentia-ai/SKILL.md`: Copado AI operations.
+
+Project rules in this file take precedence over managed skill guidance. Refresh managed skills with `agentia setup skills update`; do not hand-edit managed files.
+<!-- agentia:managed:end -->

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

@@ -31,7 +31,7 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 
 - 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`.
+- For local project work, keep the tracked working tree clean before commands that require it: `work set`, `work push`, and `work submit`.
 - 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.

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

@@ -6,6 +6,75 @@ 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.
 
+## Operating Rules
+
+- Read the target template, credential, User Story, or data commit before mutating it.
+- Use IDs returned by Copado. Do not infer template, credential, commit, or ContentVersion IDs.
+- Use `data sobject fields` and `data sobject relationships` before constructing payloads that reference Salesforce fields or relationships.
+- For JSON payload commands, use exactly one input source: inline JSON flags, `--file`, or `--stdin`.
+- Prefer `--file` when a payload should be reviewed, edited, or reused. Prefer `--stdin` for generated, one-use payloads.
+- After every mutation, read the affected resource back or run its corresponding `list` command.
+
+## Choose A Workflow
+
+| Intent | Workflow |
+| --- | --- |
+| Find or export an existing template | Inspect A Template |
+| Test source records and destination matching | Validate Records And Matching |
+| Update templates after metadata changes | Synchronize Metadata Changes |
+| Attach data to a User Story and inspect generated files | Create A Data Commit |
+| Convert or remove a template | Legacy Conversion And Deletion |
+
+## Inspect A Template
+
+1. Discover candidates with `data template list --json`.
+2. Inspect the selected-column graph with `data template get <template-id> --json`.
+3. Use `data template get-detail <template-id> --json` only when raw v2 configuration is needed for editing or troubleshooting.
+4. Inspect attached filters and formulas with `data filter list` and `data formula list` when relevant.
+
+Finish when the correct template and its current configuration have been identified. Keep `get-detail` output as a baseline before changing template detail.
+
+## Validate Records And Matching
+
+1. Inspect the template and source/destination credentials.
+2. Search representative source records with `data records search`.
+3. Match selected source records against the destination with `data records match`.
+4. Review unmatched or ambiguous results.
+5. Adjust filters or formulas when needed, then repeat the search and match checks.
+
+Treat this as a feedback loop. Finish when representative records produce the intended source selection and destination matches.
+
+## Synchronize Metadata Changes
+
+1. Prepare the metadata-change request in a JSON file.
+2. Run `data sync preview-updates --file <preview-request> --json`.
+3. Review every preview entry, especially `needsAttention` and `autoUpdate`.
+4. Build an apply payload containing only approved sync entries.
+5. Run `data sync apply --file <sync-entries> --json`.
+6. Read each affected template back to verify its fields and relationships.
+
+Never apply preview results without reviewing them first. Stop for user input when an entry needs attention and the intended field change is unclear.
+
+## Create A Data Commit - Full template
+
+1. Resolve and inspect the target User Story; see [work.md](work.md).
+2. Inspect the selected template and credentials.
+3. Prepare the data commit request in a JSON file.
+4. Run `data commit create --file <commit-request> --json`.
+5. If the response contains a JobExecution ID, inspect and monitor it using [jobs.md](jobs.md).
+6. Confirm the commit is attached to the intended story with `data commit list <user-story-id> --json`.
+7. List generated artifacts with `data dataset-file list <data-commit-id> --json`.
+8. Fetch required content with `data dataset-file content <content-version-id>`.
+
+Finish when the data commit belongs to the intended story, any returned job has reached the expected status, and generated dataset files are accounted for.
+
+## Legacy Conversion And Deletion
+
+1. Discover and inspect the exact template.
+2. Save its `get` and `get-detail` output before conversion or deletion.
+3. For legacy conversion, run `data template convert-old <template-id> --json`, then read the converted template back.
+4. For deletion, confirm the target and destructive intent before running `data template delete <template-id> --json`.
+
 ## Template Commands
 
 | Command | Use For | Notes |
@@ -60,6 +129,6 @@ 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.
+- A data commit can hand off to a CICD JobExecution. Continue with `agentia cicd job ...`, not CRT `agentia testing job ...`.

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

@@ -10,7 +10,7 @@ Use this reference for `agentia cicd promotion ...`, `agentia cicd promotion con
 | --- | --- | --- |
 | `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. |
+| `agentia cicd work submit --done` | Active User Story branch | The story is approved and should move to the next stage (Copado UI Submit promote). |
 
 Prefer `work promote` when the user talks about a story. Prefer `promotion run` when the user provides a Promotion ID.
 

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

@@ -2,7 +2,7 @@
 
 # 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`.
+Use this reference for `agentia cicd work ...` and matching MCP tools such as `agentia_work_get`, `agentia_work_commit`, `agentia_work_push`, and `agentia_work_submit`.
 
 ## Workflow
 
@@ -14,9 +14,9 @@ Use this reference for `agentia cicd work ...` and matching MCP tools such as `a
    - 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`
+7. Promote only on explicit approval: `agentia cicd work submit --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`.
+`work set`, `work push`, and `work submit` expect a clean tracked working tree and the active story context recorded by `work set`.
 
 ## Core Commands
 
@@ -30,10 +30,9 @@ Use this reference for `agentia cicd work ...` and matching MCP tools such as `a
 | `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 submit` | Submit for review/validation or promote | Runs local gates unless `--skip-local-tests`; can push ahead commits. `--done` matches Copado UI Submit when promoting. |
 | `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 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. |
 
 ## Local Commit Path
@@ -79,6 +78,6 @@ Prefer explicit flags for standard step types. Use `--config-json`, `--file`, or
 ## 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 submit` may push ahead commits, but `work set` is still required first.
+- `work submit --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.