@salesforce/afv-skills 1.46.0 → 1.48.0

package/skills/consumer-goods-promotion-bo-api-deploy/references/smoke-and-verify.md

@@ -0,0 +1,211 @@
+# Phase 6 — Smoke test through the REST endpoints
+
+Prove the interview's chosen workflows all reach the org and that the generated
+step actually applied the interview's writes. `SKILL.md` Phase 6 links here.
+
+The **shape** of the payload varies by interview:
+- `entity` decides which nested entity the writes go on (`Tactic`, `Promotion`, etc.).
+- `inputPaths` decide what keys the payload must carry.
+- `outputWrites` decide what the verification SOQL should assert.
+
+The **flow** is fixed: `initialize → ingest(create) → verify → ingest(update) →
+verify → ingest(copy) → verify`, but the update and copy legs only run if the
+interview included them in `workflows`.
+
+## 6.-1 — Derive the payload contract from the workflow (schema-first)
+
+Do this BEFORE composing any request body. The workflow itself declares the
+accepted paths — read them, don't guess. See
+`references/conventions-and-payload-rules.md` ("Payload contract derivation")
+for the canonical SOQL; run it once per invoked workflow (`create`, `update`,
+`copy`), producing three contracts.
+
+**Additionally**, apply the eight cross-workflow rules (R1..R8) in
+`references/conventions-and-payload-rules.md` ("Promotion payload — cross-workflow
+rules"). These are the constraints the schema alone cannot express and every one
+has caused a smoke-test failure historically. Summary of what the skill MUST do
+on top of the derived contract:
+
+- **R1** — force `DateFrom`, `DateThru`, `Slogan` into the create payload. If the user gave duration-in-weeks intent, compute `DateThru = DateFrom + weeks*7 - 1` client-side.
+- **R2** — poll for `Status__c = 'Calculated'` (NOT `Processed`, which does not exist in the picklist).
+- **R3** — send level NAMES verbatim as `ProductFilter.Criteria` keys (`Category`, `Brand`, ...), NOT Product2 field API names.
+- **R4** — pre-flight the anchor account has a `Plan` `Account_Extension__c` row valid for `DateFrom..DateThru` in this sales org.
+- **R5** — restrict `ManualInputs[].KPI` values to `editable` / `editable_calculated` `KPI_Definition__c.Name` on the template's `KPI_Set__c`.
+- **R6** — for `copy`, derive requireds the same way, then layer the Apex-only preconditions (`Is_Copyable__c`, template type, anchor).
+- **R7** — reject any `Tactics[*].TacticTemplate` not linked to the chosen `PromotionTemplate` in this sales org.
+- **R8** — reject any `PromotionTemplate` whose `Promotion_Type__c != 'Promotion'` (fail-fast before ingest — otherwise it surfaces as a misleading `/productfilter` error).
+
+For each derived contract, compute:
+- `requiredPaths` = union of `Path__c` where `Required__c = true`.
+- `optionalPaths` = every other declared path.
+- `arrayPaths` = any `Path__c` starting with or containing `[*]` (bind to `Tactics[]` / `ManualInputs[]` in the request).
+
+Emit `./out/contracts/<workflow>.json`:
+```json
+{
+  "workflow": "create",
+  "salesOrg": "<salesOrg>",
+  "required": [{"path": ".PromotionTemplate", "step": "loadPromotionDefaults2"}, ...],
+  "optional": [...],
+  "arrayPaths": ["Tactics[*].TacticTemplate", ...]
+}
+```
+
+Then reconcile against user input (three possible sources; skill picks the first non-empty):
+
+1. `--intent-file <path>` — a JSON object whose keys mirror the payload shape. Validate every top-level key against the derived contract; any key not in `required ∪ optional` → stop, print `"Property '<key>' is not declared in the <workflow> contract"`.
+2. `--mass-upload <path>` — a JSONL or CSV file, one promotion per row. Column headers MUST match the contract's `required` and `optional` path list verbatim; missing any required column → stop with the list of missing columns.
+3. Interactive prompt — print the required list, ask for each in turn, then offer the optional list. Interview text is `./out/prompts/<workflow>.txt` (generated, not hard-coded).
+
+Reference-data resolution (still schema-first, but the schema alone cannot
+express these — do it AFTER contract validation and BEFORE any REST call):
+
+- `PromotionTemplate` value → resolve name against `${PREFIX_UNDER}Promotion_Template__c` with `${PREFIX_UNDER}Sales_Org__c = <salesOrg>`. Miss → stop with "Promotion Template <name> not found in sales org <salesOrg>".
+- Each `Tactics[*].TacticTemplate` value → resolve against `${PREFIX_UNDER}Tactic_Template__c` scoped to sales org, AND confirm linkage to the chosen `PromotionTemplate` via `${PREFIX_UNDER}Promotion_Template_Tactic_Template__c`. Miss → stop with the concrete failure.
+- `AnchorAccount` value → resolve against `Account` where `${PREFIX_UNDER}ExternalId__c = <value> AND ${PREFIX_UNDER}Sales_Org__c = <salesOrg>`. Never pass a Salesforce Id — the packaged Apex looks up by external id.
+- `ProductFilter.Criteria.{Brand,Category,Subcategory,Flavor,Package}[*]` → resolve each name against the packaged product-attribute lookups, scoped to the sales org.
+- `ProductFilter.{Included,Excluded}Products[*]` → resolve each SKU against `Product2` scoped to the sales org.
+
+Template-conditional requireds (the two the schema cannot express):
+- `setPromotionAnchor2` declares `.AnchorAccount` as OPTIONAL, but the packaged Apex enforces it for certain `PromotionTemplate` values (verified for `Customer Promotion`). Do NOT hard-code the list — if a pre-flight `POST /ingest` with a probe promotion returns `"AnchorAccount is required"`, re-prompt for `AnchorAccount` and retry.
+
+## 6.0 — Materialize per-run payloads
+
+Only reached once the derived contract, user input, and reference-data
+resolution all pass. Emit three payload files under `./out/smoke/`:
+`create.json`, `update.json`, `copy.json`. Each is composed from the contract:
+
+1. Top-level: `{importId, workflow, salesOrg, promotions: [...]}`. All four keys are lower-camel in the wire format (see the "Wire-format quirks" note in `references/conventions-and-payload-rules.md`).
+2. Each promotion carries every `requiredPaths` value the user supplied (or an interview-collected value), plus any `optionalPaths` opted into. No unrecognized keys.
+3. Nested arrays (`Tactics[]`, `ManualInputs[]`) mirror the `arrayPaths` groups from the contract.
+4. Any user-supplied lookup value has been REPLACED by its resolved-in-sales-org form before writing the file: template names remain as names (packaged Apex resolves per sales org), account external ids remain as external ids.
+5. Probe values for interview-driven `outputWrites` assertions are written to `./out/smoke/expected.json`.
+
+The reference example ships a working set for `SetCommentValue`
+(`assets/set-comment-value/payloads/`); `--preset set-comment-value` copies
+those directly instead of running the generator.
+
+Setup — every REST call below goes through `sf api request rest`, which
+authenticates with the CLI's stored session for `--target-org` and
+mints/refreshes the token internally. **Never** extract the access token
+(`sf org display` / `sf org auth show-access-token`) and hand-build a `curl`
+request: a bearer token in shell output, traces, or agent context is a
+credential exposure (S1). Do **not** add `--json` to `sf api request rest` — the
+raw stdout body is already JSON. `${URL_NS}` is the namespace segment from
+Phase 1 (`/cgcloud` / `/cgcloud_dev` / empty); the endpoint is instance-relative.
+
+```bash
+BASE="/services/apexrest${URL_NS}/promotions"
+```
+
+## 6a — Create
+
+```bash
+# 1. Initialize a transaction
+INIT=$(sf api request rest "${BASE}/initialize" --method POST \
+  --body '{"nrOfItems": 1, "salesOrg": "<salesOrg>", "timeout": 600}' \
+  --target-org <alias>)
+IMPORT_ID=$(echo "$INIT" | jq -r .importId)
+```
+
+Bounds (from `BeginPromotionImportService`): `nrOfItems >= 1` and
+`nrOfItems <= BoApiPromotionsPerTransaction` application limit; `timeout in
+[300, 3600]`. Smoke test uses 1 item and 600s.
+
+```bash
+# 2. Ingest the generated create payload
+CREATE_JSON=$(jq --arg id "$IMPORT_ID" '.importId = $id' ./out/smoke/create.json)
+CREATE_RESP=$(sf api request rest "${BASE}/ingest" --method POST \
+  --body "$CREATE_JSON" \
+  --target-org <alias>)
+```
+
+Non-2xx → stop, print the response body.
+
+```bash
+# 3. Poll status until every record is Calculated (terminal success) or Error.
+#    Wire shape (verified against the running org): the endpoint returns an
+#    object, not an array — {"txid":"...","details":[{"status":"Calculated",
+#    "nrOfItems":1}]}. Note lowercase `status` and the `details[]` nesting.
+for i in $(seq 1 60); do
+  STATUS=$(sf api request rest "${BASE}/status?importId=${IMPORT_ID}" \
+    --target-org <alias>)
+  echo "$STATUS" | jq .
+  DONE=$(echo "$STATUS" | jq '[.details[] | select(.status | test("^(Calculated|Error)$"))] | length')
+  TOTAL=$(echo "$STATUS" | jq '.details | length')
+  [ "$DONE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ] && break
+  sleep 5
+done
+```
+
+## 6a-verify — transaction-log query + interview-driven write assertion
+
+The status endpoint returns *counts*. To guarantee we never claim success while
+a record failed, also query `BO_API_Transaction_Log__c` directly:
+
+```bash
+sf data query --target-org <alias> --json --query "
+  SELECT Id, ${PREFIX_UNDER}Status__c, ${PREFIX_UNDER}Error_Type__c,
+         ${PREFIX_UNDER}Error_Information__c,
+         ${PREFIX_UNDER}Promotion__c, ${PREFIX_UNDER}Transaction_Id__c
+    FROM ${PREFIX_UNDER}BO_API_Transaction_Log__c
+   WHERE ${PREFIX_UNDER}Transaction_Id__c = '${IMPORT_ID}'
+     AND ${PREFIX_UNDER}Status__c != 'Calculated'
+"
+```
+
+Any rows returned → stop, print them, refuse to declare success.
+`Error_Information__c` carries the actual transform/validation message (e.g.
+`Properties other than those defined were not expected at #.<path>` or `Required
+property missing at #.<path>`) — read it verbatim to fix the payload; it is the
+ONLY error-detail field on this object (there is no `Error_Message__c`).
+
+Once green, pull the created promotion and assert every field named in the
+interview's `outputWrites` matches its expected probe value from
+`./out/smoke/expected.json`:
+
+```bash
+PROMO_ID=$(sf data query --target-org <alias> --json --query "
+  SELECT ${PREFIX_UNDER}Promotion__c
+    FROM ${PREFIX_UNDER}BO_API_Transaction_Log__c
+   WHERE ${PREFIX_UNDER}Transaction_Id__c = '${IMPORT_ID}'
+     AND ${PREFIX_UNDER}Status__c = 'Calculated'
+   LIMIT 1
+" | jq -r ".result.records[0].${PREFIX_UNDER}Promotion__c")
+
+# For each outputWrite {field}: SELECT ${PREFIX_UNDER}<field> FROM
+# ${PREFIX_UNDER}<entity>__c WHERE (entity's parent linkage to PROMO_ID)
+```
+
+Every field's actual value must equal the expected probe value in
+`expected.json`. Any mismatch → stop, print `(field, expected, actual)`, refuse
+to declare success — the generated step didn't do what the interview said.
+
+## 6b — Update (skip if `update` not in interview `workflows`)
+
+Repeat 6a with `update.json`. The payload references the newly-created promotion
+id + entity ids from 6a's create response and carries different probe values.
+Verify every `outputWrites` field now equals the *update* probe values.
+
+## 6c — Copy (skip if `copy` not in interview `workflows`)
+
+Repeat 6a with `copy.json` (references the created promotion id as the copy
+source). Verify:
+- A new promotion id came back.
+- Every `outputWrites` field on the *copied* record equals the source record's value at copy-time (proves the step fired inside the copy workflow too).
+
+**Copy payload schema is *stricter* than create/update, and child inputs come
+from the source record.** The BO API rejects `PromotionTemplate`, `DateFrom`,
+`DateThru`, `AnchorAccount`, `Tactics[].Id`, `Tactics[].TacticTemplate` for the
+`copy` workflow — those come from the source record. Copying `create.json`
+verbatim and swapping `workflow` fails with `Properties other than those defined
+were not expected at #.<field>` and the ATL row lands in `Error`.
+
+Also — verified in-org — on `copy`, **per-child input paths come from the source
+record, not the payload**. The payload's `Tactics[]` block is accepted by the
+schema but has no effect on the cloned children; each cloned child runs its
+`outputWrites` against the *source* child's value. That is why the 6c verify says
+"copied == source-at-copy value": it checks the step fired, not that payload
+child probes made it through. `copy.json` should therefore carry only the source
+promotion `Id` plus top-level probe fields (e.g. `Slogan`); `Tactics[]` in the
+copy payload is decorative.

package/skills/dx-devops-project-manage/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: dx-devops-project-manage
+description: "Use this skill to list, view, or manage DevOps Center projects in a Salesforce org — show all projects, create a new project, or update an existing project's name, description, or active status. Invoke it to run sf devops project list whenever the user wants to show, see, view, display, or list available projects, check which or how many DevOps Center projects exist, or look up a project ID — even a plain listing request should use this skill rather than a raw tool or a direct answer. Also invoke to create a project, set up a new deployment pipeline foundation, initialize DevOps Center for a new feature, update project settings like name and description, or activate/deactivate (archive) a project. Consolidates sf devops project list/create/update operations. DO NOT TRIGGER for work item, pipeline, promotion, or conflict operations — those are separate skills."
+metadata:
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "58.0"
+  relatedSkills:
+    - "dx-devops-pipeline-manage"
+    - "dx-devops-promote"
+    - "dx-devops-work-item-manage"
+  accessCheck:
+    - type: "orgPref"
+      value: "ALMDevopsCorePref"
+    - type: "userPerm"
+      value: "UserHasDevOpsCore"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# DevOps Center Project Management
+
+Manages the complete DevOps Center project lifecycle — from listing existing projects through creation to updating project settings. Provides headless CLI-driven operations for autonomous release workflows.
+
+## Scope
+
+- **In scope**: List DevOps Center projects, create a new project, update project fields (name, description), resolve a project name to its ID for downstream skills
+- **Out of scope**: Work item lifecycle, pipeline creation/configuration, promotion/deployment, conflict detection (separate skills)
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Operation type**: list, create, or update
+- **Target org**: `--target-org <alias>` is required on every command unless the `target-org` config var is already set (`sf config get target-org`)
+- **For list**: no other required input (lists all projects in the org); optional name filter
+- **For create**: project name (required), description (optional)
+- **For update**: project ID (required), fields to update — at least one of name, description, or active status
+
+Defaults unless specified:
+- Output format: `--json` for headless consumption
+- Project identifier: when the user gives a project name for update, resolve it to a project ID first via `sf devops project list --target-org <alias> --json`
+
+If the user provides a clear request ("list all projects", "create a project called Release Alpha", "rename project X to Y"), proceed immediately without unnecessary questions.
+
+---
+
+## Workflow
+
+All operations use `sf devops project` CLI commands with `--json` output for structured consumption.
+
+### Phase 1 — Identify Operation
+
+1. **Determine the operation type** from user intent:
+   - Keywords like "list", "show", "find", "what projects", "get project ID" → list operation
+   - Keywords like "create", "new", "set up", "initialize" → create operation
+   - Keywords like "update", "change", "rename", "modify", "edit" → update operation
+
+### Phase 2 — Execute Operation
+
+2. **Verify org authentication** before any operation, checking the same org the operation will target:
+   ```bash
+   # When a specific org is requested, check that alias (do NOT rely on the default org):
+   sf org display --target-org <alias> --json
+   # Only when no alias is supplied and a default org is expected:
+   sf org display --json
+   ```
+   - If the requested org is not authenticated or authentication has expired, instruct the user to run:
+     ```bash
+     sf org login web --alias <alias>
+     ```
+   - Verify the authenticated org has DevOps Center enabled by attempting to list projects
+   - `--target-org <alias>` is **required** on every `sf devops project` command unless the `target-org` config var is set (check with `sf config get target-org`). Add `--target-org <alias>` to all commands when targeting a specific org — a targeted operation must never require or reset the default org
+
+   > Deterministic project-list parsing, empty-list handling, name→ID resolution, idempotent create, and update are handled by the scripts in `scripts/` — each script exits non-zero with an actionable message on failure. Pass the org alias as the trailing/`--target-org` argument when the `target-org` config var is not set; omit it to use the default org. The scripts read the authoritative `.result.projects[]` list envelope.
+
+3. **List projects** — when the user wants to see existing projects or resolve a project name to an ID:
+   - **Use the `sf devops project list` CLI (via `scripts/list-projects.sh`) — do NOT substitute an MCP/metadata tool** (e.g. a `list_devops_center_projects` tool). The `sf devops project` CLI is the only supported, verifiable path; other tools bypass this skill and will not satisfy the operation.
+   - To list all projects: run `scripts/list-projects.sh [target-org]` and report any errors it returns. Output is tab-separated `Id  Name  Description`, one project per line; a single line `NO_PROJECTS` means none exist.
+   - To resolve a single project name to its ID: run `scripts/list-projects.sh --resolve "<project-name>" [target-org]` and report any errors it returns (exit 3 = no such project).
+
+4. **Create a project** — when the user wants to create a new project:
+   - Run `scripts/create-project.sh "<name>" "<description>" [target-org]` and report any errors it returns. The description argument is optional.
+   - The script is idempotent: it prints `EXISTING <id>` if a project with that name already exists, or `CREATED <id>` after creating and verifying a new one. Capture the returned ID for downstream operations (work items, pipelines).
+
+5. **Update a project** — when the user wants to change name, description, or active status:
+   - Run `scripts/update-project.sh --project (<id>|name:<name>) [--name "<new-name>"] [--description "<new-desc>"] [--is-active|--no-is-active] [--target-org <alias>]` and report any errors it returns.
+   - Pass `--project name:<name>` to update by name (the script resolves it to an ID) or `--project <id>` for a known ID.
+   - At least one of `--name`, `--description`, or `--is-active`/`--no-is-active` must be provided (the script enforces this). Use `--is-active` to activate or `--no-is-active` to deactivate.
+   - The script prints `UPDATED <id>` on success.
+
+### Phase 3 — Report
+
+6. **Report results** (the scripts already verified success deterministically; report their output to the user):
+   - **List**: present projects in a readable format showing project ID, name, and description. If `NO_PROJECTS` was returned, state that no DevOps Center projects were found. If resolving a name to an ID, return the ID.
+   - **Create**: return the project ID and confirm — "Project created successfully. Use this project ID for work items and pipelines: <id>." If the script returned `EXISTING <id>`, tell the user the project already existed and return that ID.
+   - **Update**: confirm which fields were changed (e.g., "Project name updated to 'Platform Core'", or "Project deactivated").
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Always use the `sf devops project` CLI | List/create/update MUST go through `sf devops project` (via the `scripts/`), never a `salesforce_dx` MCP tool or metadata query — those bypass this skill and fail the operation |
+| All sf devops commands must use `--json` flag | Structured output is required for headless consumption; human-readable output is unreliable for parsing |
+| `--target-org` required unless config var set | Every `sf devops project` command requires `--target-org <alias>` unless the `target-org` config var is already set |
+| Project ID required for update | Use `--project-id` (`-i`); resolve from a name via `sf devops project list --target-org <alias> --json` when the user gives a name |
+| `--name` required for create | A project cannot be created without a name |
+| At least one update field required | Update command fails if none of `--name`, `--description`, or `--is-active` is provided |
+| Use `--is-active` / `--no-is-active` for activation | Activate with `--is-active`, deactivate with `--no-is-active`; do not pass a value |
+| Idempotent create operations | Check for an existing project with the same name before creating a duplicate |
+| Never use interactive prompts | Skills run in headless environments; all inputs must be via CLI flags |
+| A project is a prerequisite for work items and pipelines | Downstream skills (work-item-manage, pipeline-manage) need the project ID this skill returns |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| **No default org set** | Run `sf org display --json` first; if it fails, instruct the user to run `sf org login web --set-default` |
+| **User provides project by name, not ID (update)** | Resolve via `scripts/list-projects.sh --resolve "<name>" [target-org]`, or pass `--project name:<name>` to `scripts/update-project.sh` (it resolves internally) |
+| **Tempted to use an MCP listing tool** | A `salesforce_dx` MCP tool (e.g. `list_devops_center_projects`) may be available, but using it bypasses this skill and the `sf devops project list` CLI — always list via `scripts/list-projects.sh` |
+| **DevOps Center not enabled** | If `sf devops project list` errors, the org lacks DevOps Center; instruct the user to provision it in Setup → DevOps Center |
+| **Project not found (update)** | User provided an invalid project ID; run `scripts/list-projects.sh [target-org]` to show available projects |
+| **Wrong list envelope** | `project list` returns records under `.result.projects[]` (capitalized `Id`/`Name`/`Description`), NOT `.result[]`; the scripts already use the correct path |
+| **Duplicate project name** | Idempotent create check should catch this; return the existing project ID instead of creating a duplicate |
+| **Empty project list** | No projects exist yet; guide the user to create one before setting up work items or pipelines |
+| **Missing update field** | Update fails if none of `--name`, `--description`, or `--is-active` is provided; ensure at least one is passed |
+| **No default org and no `--target-org`** | Commands fail with a NoOrgFound / missing target-org error; set `--target-org <alias>` or `sf config set target-org <alias>` |
+| **Activate/deactivate passes a value** | `--is-active` is a boolean flag — use `--is-active` or `--no-is-active`, never `--is-active true` |
+
+---
+
+## Output Expectations
+
+Deliverables vary by operation:
+
+- **List**: tab-separated `Id  Name  Description` lines (or `NO_PROJECTS`) from `scripts/list-projects.sh`
+- **Create**: `EXISTING <id>` or `CREATED <id>` from `scripts/create-project.sh`
+- **Update**: `UPDATED <id>` from `scripts/update-project.sh`
+
+Outputs are derived from the `sf devops project` CLI via the `scripts/` helpers, which read the authoritative `.result.projects[]` list envelope.
+
+---
+
+## Verification Checklist
+
+Before reporting results to the user:
+
+### Universal Checks
+- [ ] Was org authentication verified with `sf org display --json`?
+- [ ] Was `--target-org <alias>` supplied to the script (or the `target-org` config var confirmed set)?
+- [ ] Did the invoked script exit 0? (Non-zero exit means the operation failed — report the script's error message.)
+
+### List Operation Checks
+- [ ] Are projects displayed with project ID, name, and description?
+- [ ] If the script returned `NO_PROJECTS`, was this communicated to the user?
+- [ ] If resolving a name to an ID, was the ID returned (or "not found" surfaced on exit 3)?
+
+### Create Operation Checks
+- [ ] Did the script return `CREATED <id>` or `EXISTING <id>`, and was the ID reported?
+
+### Update Operation Checks
+- [ ] Was the project identified by `--project <id>` or `--project name:<name>`?
+- [ ] Was at least one update field provided (name, description, or `--is-active`/`--no-is-active`)?
+- [ ] Did the script return `UPDATED <id>`?
+
+---
+
+## Cross-Skill Integration
+
+| When | Delegate to |
+|------|-------------|
+| User wants to create, list, or update work items in a project | `dx-devops-work-item-manage` (pass the project ID from this skill) |
+| User wants to create or configure a pipeline for a project | `dx-devops-pipeline-manage` |
+| User wants to promote or deploy changes | `dx-devops-promote` |
+
+This skill typically runs **first** in a DevOps Center workflow — the project ID it returns is the entry point for work item and pipeline skills.
+
+---
+
+## Reference File Index
+
+| File | When to read / run |
+|------|-------------|
+| `scripts/list-projects.sh` | Workflow step 3 — list all projects or resolve a project name to an ID (`--resolve`); handles the empty-list case |
+| `scripts/create-project.sh` | Workflow step 4 — idempotently create a project and verify it via re-read |
+| `scripts/update-project.sh` | Workflow step 5 — update name/description/active status by ID or name |
+| `references/cli-commands.md` | When you need detailed CLI flag documentation, JSON output schemas, or error handling patterns |
+| `examples/common-workflows.md` | When the user's request matches a common pattern (name resolution, idempotent creation, project setup as a workflow entry point) |

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

@@ -0,0 +1,197 @@
+# Common Project Management Workflows
+
+Real-world examples of typical project operations in DevOps Center autonomous release scenarios.
+
+---
+
+## Workflow 1: List All Projects
+
+**User request:** "Show me all DevOps Center projects in this org"
+
+**Steps:**
+
+1. **Verify authentication**:
+   ```bash
+   sf org display --json
+   ```
+
+2. **List projects**:
+   ```bash
+   sf devops project list --target-org my-devops-org --json
+   ```
+
+3. **Present in a readable format**:
+   ```bash
+   sf devops project list --target-org my-devops-org --json | \
+     jq -r '.result.projects[] | "\(.Id): \(.Name) — \(.Description // "(no description)")"'
+   ```
+   Output:
+   ```text
+   1Qg000000000001: Project Alpha — Core platform release pipeline
+   1Qg000000000002: Project Beta — (no description)
+   ```
+
+---
+
+## Workflow 2: Create a New Project (Entry Point for a Release)
+
+**User request:** "Set up a new DevOps Center project called 'Release Q3' for our Q3 features"
+
+**Steps:**
+
+1. **Idempotent check** — confirm it doesn't already exist:
+   ```bash
+   NAME="Release Q3"
+   EXISTING_ID=$(sf devops project list --target-org my-devops-org --json | \
+     jq -r ".result.projects[] | select(.Name == \"$NAME\") | .Id" | head -n1)
+   ```
+
+2. **Create only if not found**:
+   ```bash
+   if [ -n "$EXISTING_ID" ]; then
+     echo "Project already exists: $EXISTING_ID"
+   else
+     # Create, then read the ID back from the authoritative list envelope
+     sf devops project create \
+       --target-org my-devops-org \
+       --name "$NAME" \
+       --description "Q3 feature release pipeline" \
+       --json >/dev/null
+     NEW_ID=$(sf devops project list --target-org my-devops-org --json | \
+       jq -r ".result.projects[] | select(.Name == \"$NAME\") | .Id" | head -n1)
+     echo "Created project: $NEW_ID"
+   fi
+   ```
+
+   > In practice, use `scripts/create-project.sh "$NAME" "Q3 feature release pipeline"` — it performs this idempotent create-then-verify and prints `EXISTING <id>` or `CREATED <id>`.
+
+3. **Hand off the project ID** to `dx-devops-work-item-manage` or `dx-devops-pipeline-manage` for the next steps.
+
+---
+
+## Workflow 3: Resolve a Project Name to Its ID
+
+**User request:** "What's the project ID for Project Alpha?"
+
+**Steps:**
+
+1. **Filter the list by name**:
+   ```bash
+   sf devops project list --target-org my-devops-org --json | \
+     jq -r '.result.projects[] | select(.Name == "Project Alpha") | .Id'
+   ```
+   Output: `1Qg000000000001`
+
+2. **Return the ID** so downstream skills (work items, pipelines) can use it.
+
+---
+
+## Workflow 4: Rename a Project
+
+**User request:** "Rename 'Project Alpha' to 'Platform Core'"
+
+Resolve the name to an ID, update it, then verify:
+
+```bash
+PROJECT_ID=$(sf devops project list --target-org my-devops-org --json | \
+  jq -r '.result.projects[] | select(.Name == "Project Alpha") | .Id')
+
+sf devops project update \
+  --target-org my-devops-org \
+  --project-id "$PROJECT_ID" \
+  --name "Platform Core" \
+  --json
+
+sf devops project list --target-org my-devops-org --json | \
+  jq -r ".result.projects[] | select(.Id == \"$PROJECT_ID\") | .Name"   # -> Platform Core
+```
+
+---
+
+## Workflow 5: Update Project Description
+
+**User request:** "Update the description for project 1Qg000000000001 to note it now covers services too"
+
+```bash
+sf devops project update \
+  --target-org my-devops-org \
+  --project-id 1Qg000000000001 \
+  --description "Core platform + services release pipeline" \
+  --json
+
+# Confirm from the authoritative list envelope
+sf devops project list --target-org my-devops-org --json | \
+  jq -r '.result.projects[] | select(.Id == "1Qg000000000001") | .Description'
+```
+
+---
+
+## Workflow 6: Update Multiple Fields at Once
+
+**User request:** "Rename project 1Qg000000000002 to 'Beta Program' and update its description"
+
+Pass every field in a single `update` call, then verify from the list envelope:
+
+```bash
+sf devops project update \
+  --target-org my-devops-org \
+  --project-id 1Qg000000000002 \
+  --name "Beta Program" \
+  --description "Early-access beta feature pipeline" \
+  --json
+
+sf devops project list --target-org my-devops-org --json | \
+  jq -r '.result.projects[] | select(.Id == "1Qg000000000002") | "\(.Name) — \(.Description)"'
+```
+
+---
+
+## Workflow 6b: Deactivate (Archive) a Project
+
+**User request:** "Archive project 1Qg000000000002 — we're done with the beta"
+
+**Steps:**
+
+1. **Deactivate the project**:
+   ```bash
+   sf devops project update \
+     --target-org my-devops-org \
+     --project-id 1Qg000000000002 \
+     --no-is-active \
+     --json
+   ```
+
+2. **Confirm** the project is inactive by re-reading the authoritative list envelope:
+   ```bash
+   sf devops project list --target-org my-devops-org --json | \
+     jq -r '.result.projects[] | select(.Id == "1Qg000000000002") | .IsActive'
+   ```
+   Output: `false`
+
+> To reactivate later, run the same command with `--is-active` instead of `--no-is-active`.
+
+---
+
+## Workflow 7: Bootstrap — First Project in a Fresh Org
+
+**User request:** "I just enabled DevOps Center. Get me started with a project."
+
+**Steps:**
+
+1. **Confirm the org has DevOps Center and list existing projects**:
+   ```bash
+   sf devops project list --target-org my-devops-org --json | jq '.result.projects | length'
+   ```
+   Output: `0` (empty — no projects yet)
+
+2. **Create the first project**:
+   ```bash
+   sf devops project create \
+     --target-org my-devops-org \
+     --name "Main Release Pipeline" \
+     --description "Primary continuous delivery project" \
+     --json
+   ```
+
+3. **Report the project ID** and guide the user to the next step:
+   > Project created (ID: `1Qg000000000010`). Next, create a pipeline with `dx-devops-pipeline-manage` and work items with `dx-devops-work-item-manage`.