@copado/agentia-cli 0.93.0-alpha.0 → 0.95.0-alpha.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@copado/agentia-cli",
   "description": "Command-line interface for Agentia",
-  "version": "0.93.0-alpha.0",
+  "version": "0.95.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/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/work.md

@@ -4,19 +4,35 @@
 
 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
+## Choose One 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 submit --done --json`
+Local and cloud work are separate delivery paths. Do not continue a cloud commit with local `work push` or `work submit`: those commands inspect and push the local Git feature branch.
 
-`work set`, `work push`, and `work submit` expect a clean tracked working tree and the active story context recorded by `work set`.
+### Local Repository Flow
+
+Use this path when the change exists in the local repository:
+
+1. Discover and inspect: `agentia cicd work list --assigned-to-me --json`, then `agentia cicd work get <id-or-name> --json`.
+2. Activate: `agentia cicd work set <id-or-name> --json`. This fetches the configured base branch, checks out `feature/<story-name>`, and records the story, base branch, dev org branch, and pull-request context in `.agentia/config.user.json`. Use `--base-branch <branch>` only when intentionally overriding the Pipeline default.
+3. Implement and stage new files with `git add`. Commit with Git, or use `agentia cicd work commit --local --all --json` when Agentia should also remember permission, full-metadata, or Apex-test selections. `--local` is the default, and `--all` includes tracked changes only.
+4. Run project-owned gates: `agentia cicd work test --local --json`. This runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from the repository root when present.
+5. Register and synchronize: `agentia cicd work push --json`. A plain `git push` does not register a Copado Commit or merge the feature branch into the recorded dev org branch.
+6. Validate and open the merge-request flow: `agentia cicd work submit --json`. Submit runs the local gates unless `--skip-local-tests` is explicit, pushes ahead commits, and submits with validate-only behavior.
+7. Only with explicit approval to promote and deploy, run `agentia cicd work submit --done --json`. `work done` is a compatibility alias.
+8. Check asynchronous results with `agentia cicd work status [id-or-name] --json`.
+
+`work set`, `work push`, and `work submit` require a clean tracked working tree. `work push` also requires the exact `feature/<story-name>` branch, recorded `lastBaseBranch` and `lastDevOrgBranch`, and at least one commit in `lastBaseBranch..HEAD`. `work submit` permits an empty commit range only for a Story with a Salesforce Data Set or Data Template deployment step.
+
+### Copado Cloud Flow
+
+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 work commit <story-id> --cloud ... --json`. Use the simple metadata flags for one change, or `--file`/`--stdin` for a multi-change request. Salesforce metadata requires `--metadata-category SFDX`.
+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 work promote <story-id> --cloud --json`; add `--deploy` only for promote-and-deploy. This is independent of local `work submit`.
+
+Cloud commit checks Story readiness and source credentials before submission. Avoid concurrent cloud commits to one Story. Treat `--recreate-feature-branch` as destructive because it can overwrite Story-branch work.
 
 ## Core Commands
 
@@ -27,28 +43,34 @@ Use this reference for `agentia cicd work ...` and matching MCP tools such as `a
 | `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 commit` | Local or cloud commit | The flag sets are disjoint. `--local` is default and performs no gateway call; `--cloud` calls Copado commit APIs and polls by default. |
 | `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 or promote | Runs local gates unless `--skip-local-tests`; can push ahead commits. `--done` matches Copado UI Submit when promoting. |
+| `work done` | Compatibility alias | Prefer `work submit --done`; both promote and deploy rather than validate-only. |
 | `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, promote, or commit jobs. |
 | `work open [ID]` | Open story in browser | CLI-only browser helper. |
 
-## Local Commit Path
+## Local Repository Details
 
-Use local commits for normal source changes:
+Use local commits for normal source changes. Stage new files explicitly because `--all` behaves like `git commit -a`:
 
 ```sh
+git add -A
 agentia cicd work commit --local --all --permissions CustomField:Account.SLA__c,ApexClass:AccountService --json
+agentia cicd work test --local --json
 agentia cicd work push --json
+agentia cicd work submit --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 ""`.
+`--permissions` records metadata that Copado should treat as Retrieve Only during push. List the components whose access changed, not the permission set or profile files. Use `--full-metadata` only when a profile or permission set should travel as a complete file, because it can overwrite permissions the Story did not touch. Both selections are sticky in local user config until replaced or cleared with an empty value. Push-time selections apply only to that push.
 
 `--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
+`work push` detects nested metadata across the full branch diff from the merge base to `HEAD`, applies Copado environment-variable and YAML replacements, registers every commit in the range, and merges into the recorded dev org branch. Review unexpected Retrieve Only, Full Metadata, or nested-deletion output before continuing.
+
+## Cloud Operation Details
 
 Use cloud commits when Copado should retrieve metadata itself:
 
@@ -59,6 +81,15 @@ 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."
 
+For a cloud promotion, the Story must already belong to a Promotion:
+
+```sh
+agentia cicd work promote <story-id> --cloud --json
+agentia cicd work promote <story-id> --cloud --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.
+
 ## Deployment Steps
 
 Deployment steps are attached to a user story and run during promotion.
@@ -78,6 +109,8 @@ 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` may push ahead commits, but `work set` is still required first.
+- Local `work commit` rejects Story IDs and cloud-only flags; cloud `work commit --cloud` rejects local-only flags.
+- `work submit` may push ahead commits, but the local flow still needs story and branch context from `work set`.
 - `work submit --done` promotes/deploys. Do not run it unless the user explicitly asked to promote or finish the story.
+- `work promote --cloud` is not the next step after a local commit; local delivery uses `work push` and `work submit`.
 - `work delete` is destructive; read the story and confirm intent first.