@copado/agentia-cli 0.115.0-alpha.0 → 0.117.0-alpha.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@copado/agentia-cli",
   "description": "Command-line interface for Agentia",
-  "version": "0.115.0-alpha.0",
+  "version": "0.117.0-alpha.0",
   "author": "Copado Solutions",
   "bin": {
     "agentia": "./bin/run.js"
@@ -191,6 +191,9 @@
       "cicd:work:deployment-step": {
         "description": "Manage user story deployment steps"
       },
+      "cicd:work:test": {
+        "description": "Run quality gates and Apex tests for a work item"
+      },
       "cicd:promotion": {
         "description": "Manage Copado promotions"
       },

package/templates/AGENTS.md

@@ -8,7 +8,7 @@ Authentication must be configured before operational commands. Never print crede
 
 ## Copado workflow
 
-`list → get → set → commit → push → submit → done`
+`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`.
 
@@ -16,7 +16,7 @@ Read records before changing them and use IDs returned by Copado. Do not skip `w
 
 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-cicd/SKILL.md`: Copado stories, commits, publish, submit, done, promotions, jobs, environments, pipelines, and data.
 - `agentia-testing/SKILL.md`: Copado Robotic Testing operations.
 - `agentia-ai/SKILL.md`: Copado AI operations.
 

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, 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.
+description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools: user stories, work commit/publish/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 -->
@@ -20,7 +20,7 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 
 ## References
 
-- User stories, local commits, cloud commits, push, submit, done, quality gates, and deployment steps: [references/work.md](references/work.md)
+- User stories, git commits, cloud commits, publish, 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)
@@ -31,9 +31,10 @@ 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`, and `work submit`.
+- 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 or local work context was created.
 - Treat `cicd job` as Copado CICD JobExecution. It is different from CRT `testing job`.
 - Treat `cicd work test` as local quality gates (`--local` is the default). It is different from CRT `testing test run`.
+- Treat `cicd work test apex` as the Apex test runner that local quality gates (`.agentia_quality_gates.*`) usually call when those scripts are configured. 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.
 
 ## Report Back

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

@@ -2,26 +2,26 @@
 
 # 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`, and `agentia_work_submit`.
+Use this reference for `agentia cicd work ...` and matching MCP tools such as `agentia_work_get`, `agentia_work_commit`, `agentia_work_publish`, and `agentia_work_submit`.
 
 ## Choose One Workflow
 
-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.
+Local and cloud work are separate delivery paths. Do not continue a cloud commit with local `work publish` or `work submit`: those commands inspect and push the local Git feature branch.
 
 ### 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. If the Story source credential differs from the project default, work set warns with the current credential and environment and does not PATCH; use `agentia cicd work update <id> --source-credential <credential-id>` to change it.
-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 --json`. This runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from the repository root when present. `--local` is the default; `--cloud` is reserved and not implemented yet.
-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.
+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. If the JSON result has `status: "warning"` (missing pipeline or credential), show that `message`, do not assume a feature branch was created, and stop until the Story setup is fixed — publish and submit will not work. If the Story source credential differs from the project default, work set warns with the current credential and environment and does not PATCH; use `agentia cicd work update <id> --source-credential <credential-id>` to change it.
+3. Implement with Salesforce CLI, VS Code, or an IDE. Stage and commit with `git add` / `git commit`. Do not use `agentia cicd work commit` for local Git work.
+4. Run project-owned gates: `agentia cicd work test --json`. This runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from the repository root when present. If those files are missing, it warns and runs `agentia cicd work test apex` via the stock sample from a temporary file. Local tests can be slow; pass `--apex-test-classes=MyTest,OtherTest` for faster, earlier Apex checks.
+5. Register and synchronize: `agentia cicd work publish --json`. A plain `git push` does not register a Copado Commit or merge the feature branch into the recorded dev org branch. Pass `--permissions` and `--full-metadata` when nested detection is not enough.
+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. `--skip-pull-request` skips opening the compare URL.
+7. Only with explicit approval to promote and deploy, run `agentia cicd work submit --deploy --json` (or `--done`). `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.
+`work set`, `work publish`, and `work submit` require a clean tracked working tree. `work publish` also requires the exact `feature/<story-name>` branch, recorded `lastBaseBranch` and `lastDevOrgBranch`, and at least one commit in `origin/<lastBaseBranch>..HEAD`. `work submit` fetches `origin/<lastBaseBranch>` and permits an empty commit range only for a Story with a Salesforce Data Set or Data Template deployment step.
 
 ### Copado Cloud Flow
 
@@ -42,11 +42,12 @@ Cloud commit checks Story readiness and source credentials before submission. Av
 | `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 set ID` | Mark active and prepare branch | Fetches base branch, creates/checks out `feature/<story-name>`, stores local context. 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`. |
-| `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` | Run local quality gate scripts | `--local` is default. Runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from repo root. `--cloud` is not implemented yet. |
-| `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 set ID` | Mark active and prepare branch | Fetches base branch, creates/checks out `feature/<story-name>`, stores local context. A gateway warning prints the message and skips git. 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`. |
+| `work commit` | Copado cloud metadata commit | Requires `--cloud`. For local Git work, use `git commit` then `work publish`. |
+| `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 | Required `--apex-test-classes`. Optional `--wait` minutes (default 60). Usually invoked from `.agentia_quality_gates.*` when local quality gates are configured. |
+| `work submit` | Submit for review/validation or promote | Runs local gates unless `--skip-local-tests`; can push ahead commits. `--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` | 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. |
@@ -54,21 +55,21 @@ Cloud commit checks Story readiness and source credentials before submission. Av
 
 ## Local Repository Details
 
-Use local commits for normal source changes. Stage new files explicitly because `--all` behaves like `git commit -a`:
+Use Git for normal source changes:
 
 ```sh
 git add -A
-agentia cicd work commit --local --all --permissions CustomField:Account.SLA__c,ApexClass:AccountService --json
+git commit -m "US-0001 add account service"
 agentia cicd work test --json
-agentia cicd work push --json
+agentia cicd work publish --permissions CustomField:Account.SLA__c,ApexClass:AccountService --json
 agentia cicd work submit --json
 ```
 
-`--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.
+`--permissions` on publish names metadata that Copado should treat as Retrieve Only. 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 flags apply to that publish only.
 
-`--apex-test-classes` records story-related test class names for later reference. `work test` and `work submit` still take `--apex-test-classes` explicitly when you want the local gate script to receive them.
+`work test` and `work submit` take `--apex-test-classes` when you want the local gate script to receive them as `AGENTIA_APEX_TEST_CLASSES`. Sample quality-gate scripts pass that value to `work test apex`.
 
-`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.
+`work publish` 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
 
@@ -109,8 +110,9 @@ Prefer explicit flags for standard step types. Use `--config-json`, `--file`, or
 ## Gotchas
 
 - `work test` is not CRT. For Robot Framework execution, use the `agentia-testing` skill.
-- Local `work commit` rejects Story IDs and cloud-only flags; cloud `work commit --cloud` rejects local-only flags.
+- `work test apex` runs named Apex classes. Local quality gates (`.agentia_quality_gates.*`) usually call it when `AGENTIA_APEX_TEST_CLASSES` is set. Direct use is for a targeted rerun without the rest of the gates.
+- Local Git work uses `git commit` then `work publish`. Cloud `work commit --cloud` is a separate path.
 - `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 submit --done` (or `--deploy`) 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 git commit; local delivery uses `work publish` and `work submit`.
 - `work delete` is destructive; read the story and confirm intent first.