@salesforce/afv-skills 1.34.0 → 1.35.0

package/skills/dx-devops-pipeline-manage/examples/common-workflows.md

@@ -0,0 +1,177 @@
+# Common Pipeline Management Workflows
+
+Real-world examples of typical pipeline operations in DevOps Center autonomous release scenarios. All commands use `--json`; add `--target-org <alias>` when not relying on the default org.
+
+---
+
+## Workflow 1: End-to-End Pipeline Setup — Create, Stage, Bind Environments, Activate
+
+**User request:** "Set up a release pipeline on repo myorg/myrepo with Integration → UAT → Production and activate it"
+
+**Steps:**
+
+1. **Create the pipeline** against the existing repo, then resolve its ID from the list:
+   ```bash
+   sf devops pipeline create \
+     --name "Release Pipeline" \
+     --repo https://github.com/myorg/myrepo \
+     --json
+   PIPELINE_ID=$(sf devops pipeline list --json | \
+     jq -r '.result.pipelines[] | select(.Name == "Release Pipeline") | .Id' | head -n1)
+   ```
+
+2. **Inspect the initial stages** (a new pipeline always starts with at least one seeded stage):
+   ```bash
+   sf devops pipeline get --pipeline-id "$PIPELINE_ID" --json | \
+     jq -r '.result.stages[] | "\(.name) (\(.id)) -> next: \(.nextStageId)"'
+   ```
+
+3. **Add stages in promotion order.** `stage add` inserts a stage *before* `--next-stage-id`, so anchor each new stage to the one that should follow it. To build Integration → UAT → Production, add Production first (or anchor to the terminal stage), then insert UAT before Production, then Integration before UAT:
+   ```bash
+   # Assume Production stage id is 0Xc...PROD (from step 2 or a prior add)
+   sf devops pipeline stage add --pipeline-id "$PIPELINE_ID" \
+     --name "UAT" --next-stage-id 0XcPROD --json
+   sf devops pipeline stage add --pipeline-id "$PIPELINE_ID" \
+     --name "Integration" --next-stage-id 0XcUAT --json
+   ```
+
+4. **Bind an environment to each stage** (re-fetch stage IDs with `pipeline get`). In CI, add `--no-browser`:
+   ```bash
+   sf devops stage environment add --pipeline-id "$PIPELINE_ID" \
+     --stage-id 0XcINT --environment-name integration-org --org-type Sandbox --no-browser --json
+   sf devops stage environment add --pipeline-id "$PIPELINE_ID" \
+     --stage-id 0XcUAT --environment-name uat-org --org-type Sandbox --no-browser --json
+   sf devops stage environment add --pipeline-id "$PIPELINE_ID" \
+     --stage-id 0XcPROD --environment-name prod-org --org-type Production --no-browser --json
+   ```
+
+5. **Activate** once every stage has an environment:
+   ```bash
+   sf devops pipeline update --pipeline-id "$PIPELINE_ID" --activate --json
+   ```
+
+6. **Verify** the final shape:
+   ```bash
+   sf devops pipeline get --pipeline-id "$PIPELINE_ID" --json | \
+     jq -r '.result | "\(.name) [\(.isActive)]: \([.stages[].name] | join(", "))"'
+   ```
+
+**Report:** "Release Pipeline created and activated: Integration → UAT → Production, environments bound."
+
+---
+
+## Workflow 2: Insert a Staging Stage Before Production
+
+**User request:** "Add a Staging stage between UAT and Production on the Release Pipeline"
+
+**Steps:**
+
+1. **Find the pipeline and stage IDs**:
+   ```bash
+   PIPELINE_ID=$(sf devops pipeline list --json | \
+     jq -r '.result.pipelines[] | select(.Name == "Release Pipeline") | .Id' | head -n1)
+   sf devops pipeline get --pipeline-id "$PIPELINE_ID" --json | \
+     jq -r '.result.stages[] | "\(.name) (\(.id)) -> next: \(.nextStageId)"'
+   # Integration (0XcINT) -> next: 0XcUAT
+   # UAT (0XcUAT) -> next: 0XcPROD
+   # Production (0XcPROD) -> next: null
+   ```
+
+2. **Insert Staging before Production**:
+   ```bash
+   sf devops pipeline stage add --pipeline-id "$PIPELINE_ID" \
+     --name "Staging" --next-stage-id 0XcPROD --json
+   ```
+
+3. **Bind the staging environment** (get the new stage ID from `pipeline get`):
+   ```bash
+   sf devops stage environment add --pipeline-id "$PIPELINE_ID" \
+     --stage-id 0XcSTG --environment-name staging-org --org-type Sandbox --no-browser --json
+   ```
+
+4. **Verify** Staging now sits between UAT and Production.
+
+> **Constraint:** This works only if the pipeline is not yet locked. Stages can't be modified after the pipeline is activated and changes have been promoted through it.
+
+**Report:** "Staging stage inserted before Production, bound to staging-org."
+
+---
+
+## Workflow 3: Attach a Project to a Pipeline
+
+**User request:** "Connect Project Alpha to the Release Pipeline"
+
+**Steps:**
+
+1. **Resolve IDs**:
+   ```bash
+   PIPELINE_ID=$(sf devops pipeline list --json | \
+     jq -r '.result.pipelines[] | select(.Name == "Release Pipeline") | .Id' | head -n1)
+   PROJECT_ID=$(sf devops project list --json | \
+     jq -r '.result.projects[] | select(.Name == "Project Alpha") | .Id' | head -n1)
+   ```
+
+2. **Attach**:
+   ```bash
+   sf devops pipeline project add --pipeline-id "$PIPELINE_ID" --project-id "$PROJECT_ID" --json
+   ```
+
+3. **Verify** via `pipeline get` that Project Alpha appears in `.result.connectedProjects[]`.
+
+> **Constraint:** A project attaches to only one pipeline. If attach fails with "already attached," detach it from the other pipeline first: `sf devops pipeline project delete --pipeline-id <other> --project-id "$PROJECT_ID" --json`.
+
+**Report:** "Project Alpha attached to Release Pipeline."
+
+---
+
+## Workflow 4: Rename and Deactivate a Pipeline
+
+**User request:** "Deactivate the Release Pipeline and rename it to Legacy Pipeline"
+
+**Steps:**
+
+1. **Combine deactivate + rename** in one command:
+   ```bash
+   sf devops pipeline update --pipeline-id 0XB000000000001 \
+     --deactivate --name "Legacy Pipeline" --json
+   ```
+
+2. **Verify** via `pipeline get` that `.result.isActive` is false and the name updated.
+
+**Report:** "Pipeline deactivated and renamed to 'Legacy Pipeline'."
+
+---
+
+## Workflow 5: Idempotent Pipeline Setup (Safe Re-Run in CI)
+
+**User request:** "Ensure the Release Pipeline exists — runs on every CI job"
+
+**Steps:**
+
+```bash
+PIPELINE_NAME="Release Pipeline"
+
+EXISTING_ID=$(sf devops pipeline list --json | \
+  jq -r ".result.pipelines[] | select(.Name == \"$PIPELINE_NAME\") | .Id" | head -n1)
+
+if [ -n "$EXISTING_ID" ]; then
+  echo "Pipeline already exists: $EXISTING_ID"
+else
+  sf devops pipeline create --name "$PIPELINE_NAME" \
+    --repo https://github.com/myorg/myrepo --json
+fi
+```
+
+**Report:** either the existing pipeline ID or the newly created one — no duplicate created.
+
+---
+
+## Notes for Autonomous Runs
+
+- Confirm org auth with `sf org display --json` before the first command.
+- **Stage IDs come from `sf devops pipeline get`** — always fetch them before `stage add` / `stage update` / `stage delete` / `stage environment add`.
+- `stage add` inserts *before* `--next-stage-id`; plan the anchor stage to get the order you want.
+- `stage environment add` opens a browser OAuth flow — always pass `--no-browser` in CI and complete auth via the printed redirect URL.
+- Finish all stage/environment configuration **before** activating; an active, promoted pipeline locks its stage structure.
+- Deactivate before deleting an environment; the pipeline must be inactive.
+- Treat a same-name create as idempotent — check-before-create and report the existing pipeline.

package/skills/dx-devops-pipeline-manage/references/cli-commands.md

@@ -0,0 +1,298 @@
+# DevOps Center Pipeline CLI Commands Reference
+
+Command reference for `sf devops pipeline` and `sf devops stage` — flags and JSON output schemas. For jq parsing snippets, error handling, the idempotent check-before-create pattern, and auth setup, see `references/parsing-patterns.md`.
+
+## Command Summary
+
+| Command | Purpose | Required Flags |
+|---------|---------|---------------|
+| `sf devops pipeline list` | List all pipelines in the org | `--target-org` |
+| `sf devops pipeline get` | Get one pipeline's stages, repos, and connected projects | `--target-org`, `--pipeline-id` |
+| `sf devops pipeline create` | Create a pipeline linked to a Git repo | `--target-org`, `--name`, `--repo` |
+| `sf devops pipeline update` | Activate / deactivate / rename a pipeline | `--target-org`, `--pipeline-id` |
+| `sf devops pipeline stage add` | Insert an empty stage before another stage | `--target-org`, `--pipeline-id`, `--name`, `--next-stage-id` |
+| `sf devops pipeline stage update` | Rename a stage | `--target-org`, `--pipeline-id`, `--stage-id`, `--name` |
+| `sf devops pipeline stage delete` | Delete a stage (auto-relinks neighbors) | `--target-org`, `--pipeline-id`, `--stage-id` |
+| `sf devops pipeline project add` | Attach a project to a pipeline | `--target-org`, `--pipeline-id`, `--project-id` |
+| `sf devops pipeline project delete` | Detach a project from a pipeline | `--target-org`, `--pipeline-id`, `--project-id` |
+| `sf devops stage environment add` | Add a Salesforce environment to a stage | `--target-org`, `--pipeline-id`, `--stage-id`, `--environment-name`, `--org-type` |
+| `sf devops stage environment delete` | Remove an environment (inactive pipeline only) | `--target-org`, `--pipeline-id`, `--environment-id` |
+
+All commands support `--json` for structured output and `--api-version <value>` to override the API version. `--target-org` is not required if the `target-org` config variable is already set.
+
+---
+
+## List Pipelines
+
+```bash
+sf devops pipeline list --target-org my-devops-org --json
+```
+
+Returns all pipelines in the org as **SObject records** under `.result.pipelines[]`, with capitalized fields (`Id`, `Name`, `Description`, `IsActive`). This summary view does **not** include stages or connected projects — use `pipeline get` for those.
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "pipelines": [
+      {
+        "attributes": { "type": "DevopsPipeline", "url": "/services/data/v67.0/sobjects/DevopsPipeline/1PJWt0000007NsjOAE" },
+        "Id": "1PJWt0000007NsjOAE",
+        "Name": "Release Pipeline",
+        "Description": null,
+        "IsActive": false
+      }
+    ]
+  }
+}
+```
+
+Use `.Id` with `--pipeline-id` in follow-on commands.
+
+---
+
+## Get Pipeline Details
+
+```bash
+sf devops pipeline get --target-org my-devops-org --pipeline-id 0XB000000000001 --json
+```
+
+Returns a single pipeline's full detail — its stages, the repo/branch per stage, and connected projects. **This is how you discover stage IDs** needed by `stage add` (`--next-stage-id`), `stage update`/`stage delete` (`--stage-id`), and `stage environment add` (`--stage-id`). Unlike `pipeline list`, `get` uses lowercase camelCase fields (`id`, `name`, `stages`, `connectedProjects`).
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "1PJWt000000HLUfOAO",
+    "name": "Release Pipeline",
+    "description": null,
+    "isActive": true,
+    "stages": [
+      {
+        "id": "1QVWt000000G3huOAC",
+        "name": "Staging",
+        "nextStageId": "1QVWt000000G3htOAC",
+        "branchName": "staging",
+        "repositoryName": "my-new-rep",
+        "repositoryOwner": "ad-shreya",
+        "environment": { "id": "1QeWt0000000i13KAA", "name": "cli-stage" }
+      },
+      {
+        "id": "1QVWt000000G3htOAC",
+        "name": "Production",
+        "nextStageId": null,
+        "branchName": "main",
+        "repositoryName": "my-new-rep",
+        "repositoryOwner": "ad-shreya",
+        "environment": { "id": "1QeWt0000000jDFKAY", "name": "Prod 2" }
+      }
+    ],
+    "connectedProjects": [ { "id": "1QgWt0000000rabKAA", "name": "Release Project 1" } ],
+    "warnings": []
+  }
+}
+```
+
+### Stage Ordering — Linked List, Not an Array Index
+
+Stages form a **linked list** via `nextStageId`, not a numeric `order` field:
+- Each stage's `nextStageId` points to the stage that follows it in the promotion chain.
+- The **terminal stage** (last, typically Production) has `nextStageId: null`.
+- To insert before a given stage with `stage add`, pass that stage's `id` as `--next-stage-id`.
+
+See `references/parsing-patterns.md` for jq snippets that list stage names/IDs, find the terminal stage, and resolve a stage ID by name.
+
+---
+
+## Create Pipeline
+
+A pipeline must be linked to a Git repository at creation.
+
+```bash
+# Existing repo — pass the full URL, nothing else
+sf devops pipeline create --target-org my-devops-org --name "Release Pipeline" \
+  --repo https://github.com/myorg/myrepo --json
+
+# New GitHub repo — requires --repo-owner
+sf devops pipeline create --target-org my-devops-org --name "Release Pipeline" \
+  --repo my-new-repo --create-repo --repo-type github --repo-owner myorg --json
+```
+
+For a **new Bitbucket repo**, swap the provider flags: `--repo-type bitbucket --bitbucket-workspace myworkspace` (plus optional `--bitbucket-project-key PROJ`) in place of `--repo-type github --repo-owner`. Add `--description "<text>"` to any scenario for a pipeline description.
+
+### Required Flags by Scenario
+
+The correct flag set depends on whether the repo already exists and, for new repos, on the provider. Always required: `--name` and `--repo`. `--description` is optional in every scenario.
+
+| Scenario | Required flags | Must NOT include |
+|----------|---------------|------------------|
+| **Existing repo** (GitHub or Bitbucket) | `--name`, `--repo <url>` | `--create-repo`, `--repo-type`, `--repo-owner`, `--bitbucket-*` |
+| **New GitHub repo** | `--name`, `--repo <name>`, `--create-repo`, `--repo-type github`, `--repo-owner <org-or-user>` | `--bitbucket-workspace`, `--bitbucket-project-key` |
+| **New Bitbucket repo** | `--name`, `--repo <name>`, `--create-repo`, `--repo-type bitbucket`, `--bitbucket-workspace <workspace>` | `--repo-owner` |
+
+Per-flag detail:
+
+| Flag | Applies to | Notes |
+|------|-----------|-------|
+| `--name` / `-n` | all | Pipeline name (required) |
+| `--repo` / `-r` | all | Existing repo URL, or a repo name when used with `--create-repo` (required) |
+| `--description` / `-d` | all | Pipeline description (optional) |
+| `--create-repo` | new repo only | Create the repo if it doesn't exist |
+| `--repo-type` | new repo only | `github` or `bitbucket` (required when creating a repo) |
+| `--repo-owner` | **GitHub** new repo | Organization or user that owns the repo (required for GitHub create) |
+| `--bitbucket-workspace` | **Bitbucket** new repo | Workspace that owns the repo (required for Bitbucket create) |
+| `--bitbucket-project-key` | Bitbucket new repo | Optional Bitbucket project key |
+| `--stage` / `-s` | all | Name of a pipeline stage, in promotion order. Repeat once per stage. Defaults to Integration, UAT, Staging, Production |
+
+> **Provider mismatch fails:** pairing `--repo-owner` with `--repo-type bitbucket`, or `--bitbucket-workspace` with `--repo-type github`, is rejected. Match the provider flag to `--repo-type`.
+
+### Custom Stage Names at Create Time
+
+By default a new pipeline seeds the stage chain **Integration → UAT → Staging → Production**. To seed a different chain, repeat `--stage` once per stage in promotion order:
+
+```bash
+sf devops pipeline create \
+  --target-org my-devops-org \
+  --name "Release Pipeline" \
+  --repo https://github.com/myorg/myrepo \
+  --stage Dev --stage QA --stage Prod \
+  --json
+```
+
+Seeding stages at create time avoids a separate round of `stage add` / `stage update` calls afterward.
+
+After creating, resolve the new pipeline's ID by name from `sf devops pipeline list --json` (see `references/parsing-patterns.md`) — this avoids depending on the exact shape of the create response. A new pipeline always starts with at least one stage (the default chain, or your `--stage` list) — run `sf devops pipeline get` to see the seeded stages, then add or rename stages if you need to adjust the chain.
+
+---
+
+## Update Pipeline (Activate / Deactivate / Rename)
+
+```bash
+# Activate — requires at least one stage
+sf devops pipeline update --pipeline-id 0XB000000000001 --activate --json
+
+# Deactivate
+sf devops pipeline update --pipeline-id 0XB000000000001 --deactivate --json
+
+# Rename
+sf devops pipeline update --pipeline-id 0XB000000000001 --name "My Pipeline" --json
+
+# Deactivate and rename in one step
+sf devops pipeline update --pipeline-id 0XB000000000001 --deactivate --name "My Pipeline" --json
+```
+
+| Flag | Notes |
+|------|-------|
+| `--pipeline-id` | Required — ID of the pipeline to update |
+| `--activate` | Activate the pipeline. Mutually exclusive with `--deactivate` |
+| `--deactivate` | Deactivate the pipeline. Mutually exclusive with `--activate` |
+| `--name` / `-n` | New name for the pipeline. Can be combined with `--deactivate` |
+
+- A pipeline must have **at least one stage** before it can be activated.
+- `--activate` and `--deactivate` cannot be used together; `--deactivate` and `--name` may be combined in one command.
+- **You can't modify pipeline stages after you activate and promote changes through it.** Finish all stage/environment configuration before activating.
+
+---
+
+## Add a Stage
+
+Inserts an **empty** stage (no branch or environment) immediately before `--next-stage-id`. Configure its environment separately afterward.
+
+```bash
+# Add a Development stage before Integration
+sf devops pipeline stage add \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --name "Development" \
+  --next-stage-id 0Xc000000000001 \
+  --json
+```
+
+Get the `--next-stage-id` from `sf devops pipeline get`. The new stage is always inserted **immediately before** the anchor stage you pass as `--next-stage-id` — there is no append-to-end flag. To place a stage at a given point in the chain, choose the anchor that should follow it (e.g. anchor to the terminal stage to insert the new stage just before it).
+
+---
+
+## Rename / Delete a Stage
+
+```bash
+# Rename a stage
+sf devops pipeline stage update \
+  --pipeline-id 0XB000000000001 \
+  --stage-id 0Xc000000000002 \
+  --name "QA" \
+  --json
+
+# Delete a stage — the predecessor auto-relinks to the successor so the chain stays intact
+sf devops pipeline stage delete \
+  --pipeline-id 0XB000000000001 \
+  --stage-id 0Xc000000000002 \
+  --json
+```
+
+---
+
+## Add an Environment to a Stage
+
+```bash
+sf devops stage environment add \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --stage-id 0Xp000000000001 \
+  --environment-name Production_Org \
+  --org-type Production \
+  --json
+```
+
+| Flag | Required | Notes |
+|------|----------|-------|
+| `--pipeline-id` | Required | Pipeline containing the stage |
+| `--stage-id` | Required | Target stage (from `pipeline get`) |
+| `--environment-name` / `-e` | Required | Environment name |
+| `--org-type` | Required | Exactly `Production` or `Sandbox` |
+| `--no-browser` | Optional | Don't auto-open a browser for OAuth; prints the redirect URL instead |
+
+> **Headless caveat:** This command triggers an OAuth flow and opens a browser by default. In CI or headless runs, pass `--no-browser` and complete authentication via the printed redirect URL.
+
+---
+
+## Delete an Environment from a Stage
+
+The pipeline must be **inactive** before you can delete an environment.
+
+```bash
+sf devops stage environment delete \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --environment-id 0Xe000000000001 \
+  --json
+```
+
+`--pipeline-id` is used to verify the pipeline is inactive before deleting.
+
+---
+
+## Attach / Detach a Project
+
+A project can be attached to **only one pipeline**.
+
+```bash
+# Attach
+sf devops pipeline project add \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --project-id 0Hn000000000001 \
+  --json
+
+# Detach — deletes only the junction record; the project itself is not deleted
+sf devops pipeline project delete \
+  --target-org my-devops-org \
+  --pipeline-id 0XB000000000001 \
+  --project-id 0Hn000000000001 \
+  --json
+```
+
+Resolve a project ID from its name via `sf devops project list --json` — see `references/parsing-patterns.md` for the jq snippet.

package/skills/dx-devops-pipeline-manage/references/parsing-patterns.md

@@ -0,0 +1,134 @@
+# DevOps Center Pipeline — Parsing, Errors & Auth
+
+jq snippets for parsing `sf devops` JSON output, error-handling reference, the idempotent check-before-create pattern, and authentication requirements. For command flags and JSON schemas, see `references/cli-commands.md`.
+
+## Parsing Stage Chains
+
+Stages form a linked list via `nextStageId` (see the schema in `references/cli-commands.md`). Use these snippets against `pipeline get`:
+
+```bash
+# List stage names and IDs with their next pointer
+sf devops pipeline get --pipeline-id 1PJWt000000HLUfOAO --json | \
+  jq -r '.result.stages[] | "\(.name) (\(.id)) -> next: \(.nextStageId)"'
+
+# Find the terminal stage ID (nextStageId is null)
+sf devops pipeline get --pipeline-id 1PJWt000000HLUfOAO --json | \
+  jq -r '.result.stages[] | select(.nextStageId == null) | .id'
+
+# Find a stage ID by name (e.g. to anchor an insert before "Production")
+sf devops pipeline get --pipeline-id 1PJWt000000HLUfOAO --json | \
+  jq -r '.result.stages[] | select(.name == "Production") | .id'
+```
+
+---
+
+## Resolve a Pipeline ID by Name
+
+`pipeline list` is the reliable way to turn a pipeline name into an ID (note the `.pipelines[]` wrapper and capitalized `Name`/`Id`):
+
+```bash
+PIPELINE_ID=$(sf devops pipeline list --json | \
+  jq -r '.result.pipelines[] | select(.Name == "Release Pipeline") | .Id' | head -n1)
+echo "Pipeline: $PIPELINE_ID"
+```
+
+### List Pipelines (name, ID, active state)
+
+`pipeline list` does not carry stages — to show the stage chain, feed each ID into `pipeline get`:
+
+```bash
+sf devops pipeline list --json | \
+  jq -r '.result.pipelines[] | "\(.Name) [\(.IsActive)] (\(.Id))"'
+# Release Pipeline [true] (1PJWt000000HLUfOAO)
+```
+
+---
+
+## Resolve a Project ID by Name
+
+`project list` returns SObject records under `.result.projects[]` with capitalized fields (`Id`, `Name`):
+
+```bash
+sf devops project list --json | jq -r '.result.projects[] | "\(.Id): \(.Name)"'
+
+# Extract a specific project ID by name
+sf devops project list --json | \
+  jq -r '.result.projects[] | select(.Name == "Release Project 1") | .Id'
+```
+
+---
+
+## Idempotent Create (Check-Before-Create)
+
+The CLI does not dedupe pipelines. Check for an existing pipeline before creating:
+
+```bash
+PIPELINE_NAME="Release Pipeline"
+
+EXISTING_ID=$(sf devops pipeline list --json | \
+  jq -r ".result.pipelines[] | select(.Name == \"$PIPELINE_NAME\") | .Id" | head -n1)
+
+if [ -n "$EXISTING_ID" ]; then
+  echo "Pipeline already exists: $EXISTING_ID"
+else
+  sf devops pipeline create \
+    --name "$PIPELINE_NAME" \
+    --repo https://github.com/myorg/myrepo \
+    --json
+  NEW_ID=$(sf devops pipeline list --json | \
+    jq -r ".result.pipelines[] | select(.Name == \"$PIPELINE_NAME\") | .Id" | head -n1)
+  echo "Created new pipeline: $NEW_ID"
+fi
+```
+
+---
+
+## Error Handling
+
+**Missing required repo (create):**
+```json
+{ "status": 1, "name": "RequiredFlagsError", "message": "Missing required flag --repo", "exitCode": 1 }
+```
+
+**Pipeline not found:**
+```json
+{ "status": 1, "name": "NOT_FOUND", "message": "Pipeline 0XB000000000999 does not exist or is not accessible", "exitCode": 1 }
+```
+
+**Activation without a stage:**
+```json
+{ "status": 1, "name": "NO_STAGES", "message": "A pipeline must have at least one stage before you can activate it", "exitCode": 1 }
+```
+
+**Environment delete on active pipeline:**
+```json
+{ "status": 1, "name": "PIPELINE_ACTIVE", "message": "The environment must belong to an inactive pipeline", "exitCode": 1 }
+```
+
+**Project already attached:**
+```json
+{ "status": 1, "name": "PROJECT_ALREADY_ATTACHED", "message": "You can attach a project to only one pipeline", "exitCode": 1 }
+```
+
+**Authentication failure:**
+```json
+{ "status": 1, "name": "NoOrgFound", "message": "No org configuration found for target-org. Run 'sf org login web' to authenticate.", "exitCode": 1 }
+```
+
+> **Note:** Error `name`/`message` strings are representative — match on the non-zero `status` and the substring of `message`, not exact strings.
+
+---
+
+## Authentication Requirements
+
+All `sf devops pipeline` / `sf devops stage` commands require:
+
+1. **Authenticated org**: `sf org login web` or JWT auth
+2. **DevOps Center enabled**: org must have DOCe provisioned
+3. **Appropriate permissions**: access to the pipeline, its stages, and connected environments
+
+```bash
+sf org display --target-org <alias> --json
+```
+
+If auth fails: `sf org login web --set-default --alias <alias>`.

package/skills/dx-devops-pipeline-manage/scripts/check-activation-ready.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Check the deterministic activation prerequisite: a pipeline must have >=1 stage
+# before `sf devops pipeline update --activate` will succeed.
+# Usage: scripts/check-activation-ready.sh <pipeline-id> [target-org-alias]
+# Exits 0 if the pipeline has at least one stage; otherwise prints an actionable
+# error and exits 1. Exits 2 if the pipeline can't be read.
+
+set -euo pipefail
+
+PIPELINE_ID="${1:?Usage: check-activation-ready.sh <pipeline-id> [target-org-alias]}"
+TARGET_ORG="${2:-}"
+
+ORG_FLAG=()
+[ -n "$TARGET_ORG" ] && ORG_FLAG=(--target-org "$TARGET_ORG")
+
+GET_JSON=$(sf devops pipeline get --pipeline-id "$PIPELINE_ID" "${ORG_FLAG[@]+"${ORG_FLAG[@]}"}" --json 2>/dev/null) || {
+  echo "ERROR: could not read pipeline '$PIPELINE_ID'. Verify the ID with 'sf devops pipeline list --json' and that the org has DevOps Center enabled." >&2
+  exit 2
+}
+
+STATUS=$(echo "$GET_JSON" | jq -r '.status // 1')
+if [ "$STATUS" != "0" ]; then
+  echo "ERROR: 'pipeline get' returned status $STATUS for '$PIPELINE_ID'." >&2
+  exit 2
+fi
+
+STAGE_COUNT=$(echo "$GET_JSON" | jq -r '(.result.stages // []) | length')
+if [ "$STAGE_COUNT" -ge 1 ]; then
+  echo "OK: pipeline '$PIPELINE_ID' has $STAGE_COUNT stage(s) — ready to activate"
+  exit 0
+fi
+
+echo "ERROR: pipeline '$PIPELINE_ID' has no stages. Add at least one stage (sf devops pipeline stage add ...) before --activate." >&2
+exit 1

package/skills/dx-devops-pipeline-manage/scripts/validate-org-type.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Validate a stage-environment --org-type value against the fixed CLI enum.
+# Usage: scripts/validate-org-type.sh <org-type>
+# Exits 0 if the value is exactly "Production" or "Sandbox"; otherwise prints
+# an actionable error and exits 1.
+
+set -euo pipefail
+
+ORG_TYPE="${1:-}"
+
+if [ "$ORG_TYPE" = "Production" ] || [ "$ORG_TYPE" = "Sandbox" ]; then
+  echo "OK: --org-type '$ORG_TYPE' is valid"
+  exit 0
+fi
+
+echo "ERROR: --org-type must be exactly 'Production' or 'Sandbox' (case-sensitive). Got: '${ORG_TYPE}'" >&2
+exit 1