@salesforce/afv-skills 1.30.0 → 1.32.0

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

@@ -0,0 +1,476 @@
+# DevOps Center Work Item CLI Commands Reference
+
+Complete reference for `sf devops work-item` CLI commands with JSON output schemas and common patterns.
+
+## Command Summary
+
+| Command | Purpose | Required Flags | Optional Flags |
+|---------|---------|---------------|----------------|
+| `sf devops work-item list` | List all work items in a project | `--project-id` | `--api-version` |
+| `sf devops work-item create` | Create new work item | `--project-id`, `--subject` | `--description`, `--api-version` |
+| `sf devops work-item update` | Update work item fields or status | `--work-item-name` OR `--work-item-id`, plus at least one of: `--subject`, `--description`, `--status` | `--api-version` |
+| `sf devops review create` | Create pull request for work item | `--work-item-name` OR `--work-item-id` | `--api-version` |
+
+All commands support `--json` for structured output and `--target-org <alias>` for multi-org scenarios.
+
+**Org Authentication:**
+Before running any DevOps Center commands, verify org authentication:
+```bash
+sf org display --json
+```
+
+If no default org is set or the user wants to target a specific org, add `--target-org <alias>` to all commands.
+
+---
+
+## List Work Items
+
+### Basic Usage
+
+```bash
+sf devops work-item list --project-id <project-id> --json
+```
+
+### Example
+
+```bash
+# List all work items for project 1Qg000000000001
+sf devops work-item list --target-org my-devops-org --project-id 1Qg000000000001 --json
+```
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": [
+    {
+      "id": "0Wx000000000001AAA",
+      "name": "WI-000001",
+      "subject": "Fix login bug",
+      "description": "Users can't log in on mobile devices",
+      "branch": "feature/fix-login",
+      "environment": "dev-scratch-1",
+      "repositoryUrl": "https://github.com/org/repo",
+      "status": "In Progress",
+      "lastModifiedDate": "2026-07-22T10:30:00.000Z",
+      "createdDate": "2026-07-20T08:15:00.000Z"
+    },
+    {
+      "id": "0Wx000000000002AAA",
+      "name": "WI-000002",
+      "subject": "Add dark mode",
+      "description": "",
+      "branch": "feature/dark-mode",
+      "environment": "dev-scratch-2",
+      "repositoryUrl": "https://github.com/org/repo",
+      "status": "Ready to Promote",
+      "lastModifiedDate": "2026-07-21T15:45:00.000Z",
+      "createdDate": "2026-07-19T09:00:00.000Z"
+    }
+  ]
+}
+```
+
+### Key Fields
+
+- `id`: Salesforce record ID (use with `--work-item-id`)
+- `name`: Human-readable work item name like WI-000001 (use with `--work-item-name`)
+- `subject`: Title of the work item
+- `description`: Detailed description (may be empty string)
+- `branch`: Git branch associated with this work item
+- `environment`: Development environment name
+- `status`: Current work item status
+
+---
+
+## Create Work Item
+
+### Required Fields
+
+```bash
+sf devops work-item create \
+  --project-id <project-id> \
+  --subject "<subject>" \
+  --json
+```
+
+### With Optional Description
+
+```bash
+sf devops work-item create \
+  --project-id 1Qg000000000001 \
+  --subject "Fix login bug" \
+  --description "Users can't log in on mobile devices" \
+  --json
+```
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "0Wx000000000003AAA",
+    "name": "WI-000003",
+    "subject": "Fix login bug",
+    "description": "Users can't log in on mobile devices",
+    "branch": "feature/fix-login-bug",
+    "environment": "dev-scratch-3",
+    "repositoryUrl": "https://github.com/org/repo",
+    "status": "New",
+    "createdDate": "2026-07-22T11:00:00.000Z"
+  }
+}
+```
+
+---
+
+## Update Work Item
+
+### Update Subject
+
+```bash
+sf devops work-item update \
+  --work-item-name WI-000001 \
+  --subject "Fix critical login bug" \
+  --json
+```
+
+### Update Description
+
+```bash
+sf devops work-item update \
+  --work-item-name WI-000001 \
+  --description "Updated description with repro steps: 1. Open app on iOS 2. Tap login..." \
+  --json
+```
+
+### Update Status
+
+```bash
+sf devops work-item update \
+  --work-item-name WI-000001 \
+  --status "In Progress" \
+  --json
+```
+
+Valid status values (exact strings):
+- `"In Progress"` (with space and proper capitalization)
+- `"Ready to Promote"` (with space and proper capitalization)
+
+### Update Multiple Fields
+
+```bash
+sf devops work-item update \
+  --work-item-name WI-000001 \
+  --subject "Fix critical login bug [P0]" \
+  --description "Updated with repro steps" \
+  --status "In Progress" \
+  --json
+```
+
+### Using Work Item ID Instead of Name
+
+```bash
+sf devops work-item update \
+  --work-item-id 0Wx000000000001AAA \
+  --status "Ready to Promote" \
+  --json
+```
+
+> **Note:** Prefer `--work-item-name` (WI-000001) over `--work-item-id` when available — names are human-readable and easier to reference.
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "0Wx000000000001AAA",
+    "name": "WI-000001",
+    "subject": "Fix critical login bug [P0]",
+    "description": "Updated with repro steps",
+    "status": "In Progress",
+    "lastModifiedDate": "2026-07-22T11:15:00.000Z"
+  }
+}
+```
+
+---
+
+## Error Handling
+
+### Common Error Scenarios
+
+**Work item not found:**
+```json
+{
+  "status": 1,
+  "name": "NOT_FOUND",
+  "message": "The requested resource does not exist",
+  "exitCode": 1
+}
+```
+
+**Invalid status value:**
+```json
+{
+  "status": 1,
+  "name": "INVALID_STATUS",
+  "message": "Invalid status value. Allowed values: 'In Progress', 'Ready to Promote'",
+  "exitCode": 1
+}
+```
+
+**Missing required field (create):**
+```json
+{
+  "status": 1,
+  "name": "RequiredFlagsError",
+  "message": "Missing required flag --subject",
+  "exitCode": 1
+}
+```
+
+**Missing update field:**
+```json
+{
+  "status": 1,
+  "name": "RequiredFlagsError",
+  "message": "At least one of --subject, --description, or --status must be provided",
+  "exitCode": 1
+}
+```
+
+**Project not found:**
+```json
+{
+  "status": 1,
+  "name": "NOT_FOUND",
+  "message": "Project with ID 1Qg000000000999 does not exist or is not accessible",
+  "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
+}
+```
+
+---
+
+## Parsing JSON Output
+
+### Extract Work Item Name (create operation)
+
+```bash
+# Store work item name in a variable
+WORK_ITEM_NAME=$(sf devops work-item create \
+  --project-id 1Qg000000000001 \
+  --subject "Test WI" \
+  --json | jq -r '.result.name')
+
+echo "Created work item: $WORK_ITEM_NAME"
+# Output: Created work item: WI-000004
+```
+
+### Check for Empty List
+
+```bash
+# Count returned work items
+COUNT=$(sf devops work-item list --project-id 1Qg000000000001 --json | jq '.result | length')
+
+if [ "$COUNT" -eq 0 ]; then
+  echo "No work items found for this project"
+else
+  echo "Found $COUNT work items"
+fi
+```
+
+### Extract Specific Fields
+
+```bash
+# List work item names and subjects
+sf devops work-item list --project-id 1Qg000000000001 --json | \
+  jq -r '.result[] | "\(.name): \(.subject)"'
+
+# Output:
+# WI-000001: Fix login bug
+# WI-000002: Add dark mode
+```
+
+### Filter by Status
+
+```bash
+# Find all work items with "Ready to Promote" status
+sf devops work-item list --project-id 1Qg000000000001 --json | \
+  jq -r '.result[] | select(.status == "Ready to Promote") | "\(.name): \(.subject)"'
+```
+
+---
+
+## Idempotent Create Pattern
+
+To avoid duplicate work items, check for existing work items with the same subject before creating:
+
+```bash
+PROJECT_ID="1Qg000000000001"
+SUBJECT="Fix login bug"
+
+# Check if work item with subject exists
+EXISTING_NAME=$(sf devops work-item list \
+  --project-id "$PROJECT_ID" \
+  --json | \
+  jq -r ".result[] | select(.subject == \"$SUBJECT\") | .name" | head -n1)
+
+if [ -n "$EXISTING_NAME" ]; then
+  echo "Work item already exists: $EXISTING_NAME"
+else
+  # Create new work item
+  NEW_NAME=$(sf devops work-item create \
+    --project-id "$PROJECT_ID" \
+    --subject "$SUBJECT" \
+    --json | jq -r '.result.name')
+  echo "Created new work item: $NEW_NAME"
+fi
+```
+
+---
+
+## Authentication Requirements
+
+All `sf devops work-item` commands require:
+
+1. **Authenticated org**: `sf org login web` or JWT auth
+2. **DevOps Center enabled**: Org must have DOCe provisioned
+3. **Appropriate permissions**: User must have access to the project
+
+Verify authentication before running commands:
+
+```bash
+sf org display --target-org <alias> --json
+```
+
+If authentication fails, the user must run:
+
+```bash
+sf org login web --set-default --alias <alias>
+```
+
+---
+
+## Create Pull Request
+
+### Basic Usage
+
+```bash
+sf devops review create \
+  --work-item-name <WI-name> \
+  --json
+```
+
+### Example with Work Item Name
+
+```bash
+sf devops review create \
+  --work-item-name WI-000001 \
+  --json
+```
+
+### Example with Work Item ID
+
+```bash
+sf devops review create \
+  --work-item-id 0Wx000000000001AAA \
+  --json
+```
+
+> **Note:** Prefer `--work-item-name` (WI-000001) over `--work-item-id` when available — names are human-readable and easier to reference.
+
+### JSON Output Schema
+
+```json
+{
+  "status": 0,
+  "result": {
+    "id": "0PR000000000001AAA",
+    "workItemId": "0Wx000000000001AAA",
+    "workItemName": "WI-000001",
+    "pullRequestUrl": "https://github.com/org/repo/pull/42",
+    "pullRequestNumber": 42,
+    "pullRequestStatus": "open",
+    "createdDate": "2026-07-23T10:00:00.000Z"
+  }
+}
+```
+
+### Key Fields
+
+- `pullRequestUrl`: Direct link to the PR in VCS (GitHub or Bitbucket)
+- `pullRequestNumber`: PR number in the VCS system
+- `pullRequestStatus`: Current status (typically "open" at creation)
+- `workItemName`: Work item the PR was created for
+- `id`: Salesforce record ID for the review record
+
+### How It Works
+
+- Uses VCS credentials stored in DevOps Center org (not local git auth)
+- Creates PR from work item's branch to the pipeline's base branch
+- Works with GitHub and Bitbucket
+- Requires VCS connection configured in DevOps Center UI first
+
+### Error Scenarios
+
+**VCS credentials not configured:**
+```json
+{
+  "status": 1,
+  "name": "VCS_NOT_CONFIGURED",
+  "message": "VCS connection not configured for this project. Configure in DevOps Center UI first.",
+  "exitCode": 1
+}
+```
+
+**Work item not found:**
+```json
+{
+  "status": 1,
+  "name": "NOT_FOUND",
+  "message": "Work item WI-000999 does not exist or is not accessible",
+  "exitCode": 1
+}
+```
+
+**PR already exists:**
+```json
+{
+  "status": 1,
+  "name": "PR_ALREADY_EXISTS",
+  "message": "A pull request already exists for work item WI-000001",
+  "exitCode": 1
+}
+```
+
+---
+
+## Getting Project ID
+
+If the user doesn't provide a project ID, list available projects first:
+
+```bash
+sf devops project list --json | jq -r '.result[] | "\(.id): \(.name)"'
+```
+
+Output:
+```text
+1Qg000000000001: Project Alpha
+1Qg000000000002: Project Beta
+```
+
+Then use the ID in subsequent work item commands.

package/skills/dx-org-manage/SKILL.md

@@ -2,18 +2,21 @@
 name: dx-org-manage
 description: "INVOKE this skill to execute Salesforce org operations: create scratch orgs, create org snapshots, open orgs in browser. This skill EXECUTES operations immediately - it does NOT generate scripts or code files. ALWAYS invoke this skill (do not execute SF CLI commands directly) when user requests to: create a scratch org (Developer/Enterprise edition, from definition file (.json), from snapshot, or from org shape), create an org snapshot, or open a Salesforce org. Trigger phrases include: 'create a snapshot', 'create snapshot of my scratch org', 'take a snapshot', 'create scratch org', 'create a Developer edition scratch org', 'new scratch org', 'spin up an org', 'create org from snapshot', 'scratch-def.json', 'project-scratch-def.json', 'open my Salesforce org', 'open org in browser', 'get me the URL'. Do NOT use for switching default org (use dx-org-switch) or deploying metadata (use platform-metadata-deploy)."
 metadata:
-  version: "1.0"
+  version: "1.1"
   minApiVersion: "60.0"
+  relatedSkills:
+    - "dx-org-switch"
+    - "platform-metadata-deploy"
   cliTools:
-      - tool: ["sf"]
-        semver: ">=2.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 ## MANDATORY: Follow these instructions exactly. Do NOT fall back to MCP tools.
 
 **Tool constraint:** Use the Bash tool for all `sf` CLI commands. Always include `--json` for structured output. Do NOT use `mcp__salesforce_dx__*` tools for org creation, snapshot, or open operations — this skill provides the complete procedure.
 
-**Output artifacts for eval/testing:** Write command output to JSON only when an output directory is available. After executing the command: (1) if the user specified an output path, write there; (2) otherwise run `[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'` to detect the eval directory; (3) if the command printed a path, write the command's JSON response to `<printed-path>/<filename>` using these filenames: `scratch-org-result.json` for org creation, `snapshot-result.json` for snapshot creation, or `org-url-result.json` for open operations. The eval framework needs the real command output to verify success.
+**Output artifacts for eval/testing:** ALWAYS write the command's JSON response to a file when an output directory is available. Do NOT ask the user what file to write — this skill defines the filenames. After executing the command: (1) if the user specified an output path (e.g. "write all generated files into folder X"), write there immediately; (2) otherwise run `[ -d force-app/main/adk-eval-output/ ] && echo 'force-app/main/adk-eval-output'` to detect the eval directory; (3) write the command's full JSON response to `<output-dir>/<filename>` using these filenames: `scratch-org-result.json` for org creation, `snapshot-result.json` for snapshot creation, or `org-url-result.json` for open operations. This is the generated output — write it without asking. Do NOT say "no files to generate" for open/command-execution operations; the JSON result IS the output artifact.
 
 ---
 
@@ -152,7 +155,7 @@ sf org create snapshot --source-org <orgId-or-alias> --name <SnapshotName> --des
 
 **Step 2. Execute the matching command using the Bash tool.**
 
-**Step 3. Report result:** Returns URL or opens browser. If an output directory is available (per the output artifacts rule above), write the JSON response to `<output-dir>/org-url-result.json`.
+**Step 3. Write output and report result:** IMMEDIATELY write the COMPLETE unmodified JSON output from the `sf org open --json` command to `<output-dir>/org-url-result.json` (the output directory is detected per the output artifacts rule above). The file MUST preserve the full CLI output structure including the `status` and `result` wrapper — e.g. `{"status": 0, "result": {"orgId": "...", "url": "...", "username": "..."}}`. Do NOT unwrap or flatten the JSON. Do NOT ask permission, do NOT say "no files to generate." Then report the URL and org details to the user.
 
 **Error handling:**
 - "no target org" → advise `sf config set target-org <alias>`