@salesforce/afv-skills 1.65.1 → 1.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.65.1",
+  "version": "1.66.0",
   "description": "Salesforce's curated collection of agent skills for building applications. Optimized for Agentforce Vibes, compatible with all AI tools.",
   "license": "Apache-2.0",
   "files": [

package/skills/agentforce-offline-experimentation-run/SKILL.md

@@ -58,13 +58,13 @@ Operations grouped by purpose. Use these as the building blocks for the workflow
 | `find-sessions` | read | implemented | `queryCdpAnsiSqlV2` | `verify-stdm-availability`, `discover-agents` |
 | `get-conversation-details` | read | proposed | `queryCdpAnsiSqlV2` | `find-sessions` |
 | `get-llm-step-details` | read | proposed | `queryCdpAnsiSqlV2` | `get-conversation-details` |
-| `obtain-sfap-token` | validate | proposed | `obtainSfapJwt` | — |
-| `replay-turn-prompts` | read | proposed | `sfapChatGenerations` | `get-llm-step-details`, `obtain-sfap-token` |
-| `score-exact-matches` | read | proposed | `computeExactMatchScores` | `replay-turn-prompts` |
-| `judge-function-args` | read | proposed | `sfapChatGenerations` | `score-exact-matches`, `obtain-sfap-token` |
-| `judge-text-responses` | read | proposed | `sfapChatGenerations` | `replay-turn-prompts`, `obtain-sfap-token` |
-| `generate-csv-report` | write | proposed | `generateCsvReport` | `score-exact-matches`, `judge-function-args`, `judge-text-responses` |
-| `generate-html-report` | write | proposed | `generateHtmlReport` | `generate-csv-report` |
+| `obtain-sfap-token` | validate | proposed | — | — |
+| `replay-turn-prompts` | read | proposed | — | `get-llm-step-details`, `obtain-sfap-token` |
+| `score-exact-matches` | read | proposed | — | `replay-turn-prompts` |
+| `judge-function-args` | read | proposed | — | `score-exact-matches`, `obtain-sfap-token` |
+| `judge-text-responses` | read | proposed | — | `replay-turn-prompts`, `obtain-sfap-token` |
+| `generate-csv-report` | write | proposed | — | `score-exact-matches`, `judge-function-args`, `judge-text-responses` |
+| `generate-html-report` | write | proposed | — | `generate-csv-report` |
 
 ### Dependency graph
 
@@ -172,9 +172,10 @@ Fetch interaction steps including LLM inputs and outputs for each interaction
 
 #### `replay-turn-prompts`
 
-Replay each turn's LLM prompt through the target model via SFAP REST API with structured tool calling
+Extract structured messages (system/assistant/user) from STDM LLM step inputs, convert to OpenAI-format messages array preserving role positions, extract tool definitions dynamically from gen_ai.request.tools, classify each step as router (topic) or action based on tool signatures, and replay via SFAP REST API POST /ai/gpt/v1/chat/generations with tool_choice=required
 
-**Call:** `sfapChatGenerations`   — status: `proposed`
+
+**Status:** `proposed`
 
 **Inputs:**
 
@@ -186,7 +187,7 @@ Replay each turn's LLM prompt through the target model via SFAP REST API with st
 
 Compute exact-match scores for topic agreement and function name accuracy
 
-**Call:** `computeExactMatchScores`   — status: `proposed`
+**Status:** `proposed`
 
 **Depends on:** `replay-turn-prompts`
 
@@ -194,7 +195,7 @@ Compute exact-match scores for topic agreement and function name accuracy
 
 LLM-as-judge scoring of function arguments when function names match (exact or lenient)
 
-**Call:** `sfapChatGenerations`   — status: `proposed`
+**Status:** `proposed`
 
 **Depends on:** `score-exact-matches`, `obtain-sfap-token`
 
@@ -202,7 +203,7 @@ LLM-as-judge scoring of function arguments when function names match (exact or l
 
 LLM-as-judge scoring of text responses for turns that end with text output
 
-**Call:** `sfapChatGenerations`   — status: `proposed`
+**Status:** `proposed`
 
 **Depends on:** `replay-turn-prompts`, `obtain-sfap-token`
 
@@ -212,7 +213,7 @@ LLM-as-judge scoring of text responses for turns that end with text output
 
 Generate CSV report with per-turn replay results and aggregate summary scores
 
-**Call:** `generateCsvReport`   — status: `proposed`
+**Status:** `proposed`
 
 **Inputs:**
 
@@ -224,7 +225,7 @@ Generate CSV report with per-turn replay results and aggregate summary scores
 
 Build a self-contained HTML analysis report with verdict badges, scorecards, and failure breakdown
 
-**Call:** `generateHtmlReport`   — status: `proposed`
+**Status:** `proposed`
 
 **Inputs:**
 
@@ -246,7 +247,7 @@ Verify STDM (Session Trace Data Model) is queryable in Data Cloud
 
 Obtain an SFAP JWT token via org session authentication and the /ide/auth endpoint
 
-**Call:** `obtainSfapJwt`   — status: `proposed`
+**Status:** `proposed`
 
 **Inputs:**
 

package/skills/agentforce-offline-experimentation-run/scripts/sfap_replay.py

@@ -22,206 +22,10 @@ STDM_DATA_FILE = os.environ.get("STDM_DATA_FILE", "/tmp/details_result.json")
 LLM_STEPS_FILES = os.environ.get("LLM_STEPS_FILES", "/tmp/llm_steps_1.json,/tmp/llm_steps_2.json").split(",")
 
 # ---------------------------------------------------------------------------
-# Dynamic tool extraction from STDM data
-# ---------------------------------------------------------------------------
-# Instead of hardcoded tools, we extract actual tool definitions from the
-# original LLM responses in the STDM data. This handles both routing tools
-# (go_to_*) and domain action tools (SearchProducts, AddToCart, etc.)
+# Tool extraction is dynamic-only: definitions come from STDM step inputs
+# (gen_ai.request.tools) at runtime. No hardcoded tool schemas.
 # ---------------------------------------------------------------------------
 
-# Well-known tool schemas observed from agent responses. Keyed by tool name.
-# These are built from observed argument patterns in STDM LLM responses.
-KNOWN_TOOL_SCHEMAS = {
-    # --- Routing tools (topic router layer) ---
-    "go_to_product_discovery": {
-        "type": "function",
-        "function": {
-            "name": "go_to_product_discovery",
-            "description": "Route to product discovery topic for searching, browsing, product questions, recommendations.",
-            "parameters": {"type": "object", "properties": {}}
-        }
-    },
-    "go_to_cart_and_checkout": {
-        "type": "function",
-        "function": {
-            "name": "go_to_cart_and_checkout",
-            "description": "Route to cart and checkout topic for adding items, viewing cart, checkout, payments.",
-            "parameters": {"type": "object", "properties": {}}
-        }
-    },
-    "go_to_store_help": {
-        "type": "function",
-        "function": {
-            "name": "go_to_store_help",
-            "description": "Route to store help topic for shipping, returns, store policies, greetings.",
-            "parameters": {"type": "object", "properties": {}}
-        }
-    },
-    "go_to_off_topic": {
-        "type": "function",
-        "function": {
-            "name": "go_to_off_topic",
-            "description": "Route to off-topic handler for queries unrelated to shopping.",
-            "parameters": {"type": "object", "properties": {}}
-        }
-    },
-    # --- Domain action tools (sub-topic agents) ---
-    "SearchProducts": {
-        "type": "function",
-        "function": {
-            "name": "SearchProducts",
-            "description": "Search the product catalog with optional filters.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "searchQuery": {"type": "string", "description": "Search terms or keywords"},
-                    "category": {"type": "string", "description": "Product category filter"},
-                    "color": {"type": "string", "description": "Color filter"},
-                    "department": {"type": "string", "description": "Department filter (e.g. Men, Women, Unisex)"},
-                    "maxPrice": {"type": "string", "description": "Maximum price filter"},
-                    "minPrice": {"type": "string", "description": "Minimum price filter"},
-                    "sortBy": {"type": "string", "description": "Sort order (e.g. relevance, price_asc, price_desc, rating)"}
-                },
-                "required": []
-            }
-        }
-    },
-    "GetProductDetails": {
-        "type": "function",
-        "function": {
-            "name": "GetProductDetails",
-            "description": "Get detailed information about a specific product.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "productCode": {"type": "string", "description": "The product code (e.g. SHOE-M-088)"}
-                },
-                "required": ["productCode"]
-            }
-        }
-    },
-    "GetRecommendations": {
-        "type": "function",
-        "function": {
-            "name": "GetRecommendations",
-            "description": "Get product recommendations based on a product.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "productCode": {"type": "string", "description": "Product code to base recommendations on"}
-                },
-                "required": ["productCode"]
-            }
-        }
-    },
-    "AddToCart": {
-        "type": "function",
-        "function": {
-            "name": "AddToCart",
-            "description": "Add a product to the shopping cart.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "productCode": {"type": "string", "description": "Product code to add"},
-                    "quantity": {"type": "string", "description": "Quantity to add"},
-                    "size": {"type": "string", "description": "Size selection"},
-                    "color": {"type": "string", "description": "Color selection"}
-                },
-                "required": ["productCode", "quantity"]
-            }
-        }
-    },
-    "ViewCart": {
-        "type": "function",
-        "function": {
-            "name": "ViewCart",
-            "description": "View the current shopping cart contents.",
-            "parameters": {"type": "object", "properties": {}}
-        }
-    },
-    "UpdateCart": {
-        "type": "function",
-        "function": {
-            "name": "UpdateCart",
-            "description": "Update cart item quantity, size, or color. Set quantity to 0 to remove.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "productCode": {"type": "string", "description": "Product code to update (or 'all' to clear cart)"},
-                    "quantity": {"type": "string", "description": "New quantity (0 to remove)"},
-                    "size": {"type": "string", "description": "New size"},
-                    "color": {"type": "string", "description": "New color"}
-                },
-                "required": ["productCode", "quantity"]
-            }
-        }
-    },
-    "Checkout": {
-        "type": "function",
-        "function": {
-            "name": "Checkout",
-            "description": "Place an order with the current cart.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "shippingMethod": {"type": "string", "description": "Shipping method (Standard or Express)"},
-                    "shopperName": {"type": "string", "description": "Name for the order"}
-                },
-                "required": ["shippingMethod"]
-            }
-        }
-    },
-    # --- Generic CRM tools (fallback for non-shopper agents) ---
-    "QueryRecords": {
-        "type": "function",
-        "function": {
-            "name": "QueryRecords",
-            "description": "Query records using natural language.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Natural language query"}
-                },
-                "required": ["query"]
-            }
-        }
-    },
-    "IdentifyRecordByName": {
-        "type": "function",
-        "function": {
-            "name": "IdentifyRecordByName",
-            "description": "Identify a record by its name to get the record ID.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "name": {"type": "string", "description": "The name of the record"},
-                    "objectType": {"type": "string", "description": "The Salesforce object type"}
-                },
-                "required": ["name"]
-            }
-        }
-    },
-    "GetRecordDetails": {
-        "type": "function",
-        "function": {
-            "name": "GetRecordDetails",
-            "description": "Get detailed information about a specific record by its ID.",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "recordId": {"type": "string", "description": "The Salesforce record ID"}
-                },
-                "required": ["recordId"]
-            }
-        }
-    },
-}
-
-ROUTING_TOOLS = ['go_to_product_discovery', 'go_to_cart_and_checkout', 'go_to_store_help', 'go_to_off_topic']
-ACTION_TOOLS_SHOPPER = ['SearchProducts', 'GetProductDetails', 'GetRecommendations',
-                        'AddToCart', 'ViewCart', 'UpdateCart', 'Checkout']
-GENERIC_CRM_TOOLS = ['QueryRecords', 'IdentifyRecordByName', 'GetRecordDetails']
-
 
 def _is_routing_tools(tools):
     """True when ALL tools in the list are routing functions (go_to_* / __end_session_action__).
@@ -270,27 +74,6 @@ def sanitize_tools_for_sfap(tools):
     return sanitized
 
 
-def build_tools_for_step(original_tool_name, prompt_text):
-    """Select the right tool set based on the original tool call and prompt content."""
-    # If original called a routing tool, offer routing tools
-    if original_tool_name and original_tool_name.startswith('go_to_'):
-        return [KNOWN_TOOL_SCHEMAS[t] for t in ROUTING_TOOLS if t in KNOWN_TOOL_SCHEMAS]
-
-    # If original called a shopper action tool, offer shopper tools
-    if original_tool_name and original_tool_name in ACTION_TOOLS_SHOPPER:
-        return [KNOWN_TOOL_SCHEMAS[t] for t in ACTION_TOOLS_SHOPPER if t in KNOWN_TOOL_SCHEMAS]
-
-    # Detect from prompt content
-    if prompt_text:
-        if 'go_to_product_discovery' in prompt_text or 'go_to_cart' in prompt_text:
-            return [KNOWN_TOOL_SCHEMAS[t] for t in ROUTING_TOOLS if t in KNOWN_TOOL_SCHEMAS]
-        if 'SearchProducts' in prompt_text or 'AddToCart' in prompt_text:
-            return [KNOWN_TOOL_SCHEMAS[t] for t in ACTION_TOOLS_SHOPPER if t in KNOWN_TOOL_SCHEMAS]
-
-    # Fallback to generic CRM tools
-    return [KNOWN_TOOL_SCHEMAS[t] for t in GENERIC_CRM_TOOLS if t in KNOWN_TOOL_SCHEMAS]
-
-
 def extract_tools_from_llm_responses(llm_step_map):
     """Scan all LLM responses to discover the actual tool names used by the agent."""
     seen = set()
@@ -309,10 +92,6 @@ def extract_tools_from_llm_responses(llm_step_map):
     return seen
 
 
-# Legacy alias for backward compatibility
-AGENT_TOOLS = [KNOWN_TOOL_SCHEMAS[t] for t in GENERIC_CRM_TOOLS if t in KNOWN_TOOL_SCHEMAS]
-
-
 def read_token():
     if SFAP_TOKEN_FILE and os.path.exists(SFAP_TOKEN_FILE):
         with open(SFAP_TOKEN_FILE) as f:
@@ -415,24 +194,6 @@ def convert_stdm_messages_for_sfap(stdm_messages):
     return out
 
 
-def prompt_has_tools(prompt_text):
-    """Check if this prompt includes tool/function calling instructions."""
-    indicators = [
-        'data retrieval functions',
-        'QueryRecords',
-        'IdentifyRecordByName',
-        'GetRecordDetails',
-        'TOOL USAGE PROTOCOL',
-        'go_to_product_discovery',
-        'go_to_cart_and_checkout',
-        'go_to_store_help',
-        'SearchProducts',
-        'AddToCart',
-        'Checkout',
-    ]
-    return any(ind in prompt_text for ind in indicators)
-
-
 def call_sfap(messages, model, tools=None, max_tokens=2048):
     """Call SFAP chat generations endpoint."""
     token = read_token()
@@ -880,13 +641,10 @@ def main():
             print(f"    SKIP: Could not parse prompt into messages")
             continue
 
-        # Use tool definitions from STDM step input if available, else fall back
+        # Use tool definitions from STDM step input (dynamic-only, no hardcoded fallback)
         tools = target.get('step_tools')
         if tools:
             tools = sanitize_tools_for_sfap(tools)
-        else:
-            has_tools = prompt_has_tools(target['prompt'])
-            tools = build_tools_for_step(target.get('original_tool_name'), target['prompt']) if has_tools else None
 
         print(f"    Messages: {len(messages)}, Tools: {'yes' if tools else 'no'}")
 

package/skills/dx-devops-work-item-manage/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: dx-devops-work-item-manage
-description: "Use this skill to manage the full lifecycle of DevOps Center work items — list, create, update, commit changes, perform status transitions, and create pull requests. Update fields like subject, description, and status. Commit and push code changes to work item branches. Create pull requests for work item branches via DevOps Center API. Invoke when the user wants to track, find, create, or update a work item, commit changes to a work item branch, advance a work item's status through the pipeline, or create a pull request for code review. Consolidates sf devops work-item and review operations. DO NOT TRIGGER for promotion or deployment operations, or conflict detection."
+description: "Use this skill to manage the full lifecycle of DevOps Center work items — list, create, update, commit changes, perform status transitions, and create pull requests. Update fields like subject, description, and status. Commit changes to work item branches, through the DevOps Center commit API or git. Create pull requests for work item branches via DevOps Center API. Invoke when the user wants to track, find, create, or update a work item, commit changes to a work item branch, advance a work item's status through the pipeline, or create a pull request for code review. Consolidates sf devops work-item and review operations. DO NOT TRIGGER for promotion or deployment operations, or conflict detection."
 metadata:
   relatedSkills:
     - "dx-devops-promote"
-  version: "1.0"
+  version: "1.1"
   domains: ["Developer Experience"]
   minApiVersion: "58.0"
   cliTools:
@@ -34,7 +34,7 @@ Gather or infer before proceeding:
 - **Operation type**: list, create, update, commit, or create-review
 - **For list**: project ID (required) — obtain via `sf devops project list --json` if not provided
 - **For create**: project ID (required), subject (required), description (optional)
-- **For commit**: work item name or ID (required) to retrieve branch name, files to commit, commit message
+- **For commit**: work item name or ID (required), commit message, and either the files to commit (git path) or the components to commit (API path). Optional: **dev org alias** — the org that holds the changes. When provided, try the DevOps Center commit API first (see step 5); otherwise use git
 - **For update**: work item name (e.g., WI-000001) or work item ID (required), fields to update (subject, description, status)
 - **For create-review**: work item name (e.g., WI-000001) or work item ID (required)
 
@@ -48,7 +48,7 @@ If the user provides a clear request ("list work items for Project Alpha", "crea
 
 ## Workflow
 
-All operations use `sf devops work-item` CLI commands with `--json` output for structured consumption.
+Operations use `sf devops work-item` CLI commands with `--json` output; the API commit path also uses `sf api request rest` and `sf data query`.
 
 ### Phase 1 — Identify Operation
 
@@ -71,6 +71,7 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
      ```
    - Verify the authenticated org has DevOps Center enabled by attempting to list projects
    - If the user wants to target a specific org, use `--target-org <alias>` on all subsequent commands
+   - For the API commit path, run `sf org display --target-org <alias> --json` for **both** the dev org and the hub org
 
 3. **List work items** — when the user wants to see existing work items:
    ```bash
@@ -102,9 +103,21 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
    - Capture the returned work item name (e.g., WI-000001), branch name, and environment from JSON output for future operations
    - Idempotent: if the user attempts to create a duplicate (same subject + project), check via list first and return the existing work item
 
-5. **Execute commit operation** — when operation type is commit:
-   - DevOps Center creates a dedicated feature branch for each work item (returned in the create operation)
-   - The user must commit and push changes to this branch before transitioning status or creating a PR
+5. **Execute commit operation** — when operation type is commit. Choose the path first:
+   - **API path** — only when the user gave a dev org alias AND the changes are already deployed in that dev org (if unsure, ask: deploy with `sf project deploy start`, or use git). Dev org alias: `commitChanges`, `DevopsRequestInfo`. Hub alias: `sf devops` and `WorkItemComponentList`. DevOps Center retrieves the named components from the dev org and commits them as `DevOps Center <noreply@salesforce.com>`.
+   - **Git path** — everything else. If the changes exist only in the dev org, run `sf project retrieve start --target-org <dev-org>` first.
+
+   **API path** (commands, body, error codes and polling in `references/commit-api.md`):
+   1. Preflight `GET /connect/devops/doceConnectionType` on the dev org; a failed call (non-zero exit or error body) or `isCore` not `true` means use the git path.
+   2. `sf devops project list` → project id, then `sf devops work-item list --project-id <id> --target-org <hub>` → work item id and name. Status must be New, In Progress, In Review or Ready to Promote.
+   3. `POST /connect/devops/commitChanges` on the **dev org**; the body is the inner object (no `commitChanges` wrapper).
+   4. A failed call, or `status: "ERROR"` with `reqId` = `CODE:message`: surface it and stop.
+   5. If the POST `status` is `SUCCESS` (accepted only), poll `DevopsRequestInfo WHERE RequestToken = '<reqId>'` on the dev org every 10 seconds until `Status` is `SUCCESS` or `ERROR` (report `Message`/`ErrorDetails`), 12-minute deadline. Past it the request is stuck; report it and do not retry automatically.
+   6. Confirm a new `WorkItemComponentList` exists on the hub before creating a review.
+
+   **Git path:**
+   - If the work item is New, first set it to In Progress (step 6); the hub ignores pushes made while it is New
+   - Use the work item's `branch` field as the branch
    - Standard git workflow:
      ```bash
      git checkout <branch-name>
@@ -112,8 +125,7 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
      git commit -m "<commit-message>"
      git push origin <branch-name>
      ```
-   - The branch name is available from the work item's `branch` field (retrieve via list or create operation)
-   - Changes must be committed before the work item can be marked "Ready to Promote" or before creating a PR
+   - The hub registers the push asynchronously; re-check it before creating a PR
 
 6. **Update work item** — when the user wants to change subject, description, or status:
    ```bash
@@ -162,7 +174,8 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
 8. **Verify operation success**:
    - **For list**: confirm the CLI returned status 0, parse the JSON `.result[]` array, and verify it contains work items (or is empty if no matches). If the user specified a project by name, confirm the resolved project ID matches.
    - **For create**: verify the CLI returned status 0 and the JSON output contains `.result.name` (work item ID like WI-000001), `.result.branch` (branch name), and `.result.environment` fields.
-   - **For commit**: verify each git command returned exit code 0. If `git push` succeeds, the commit is saved to the work item branch.
+   - **For commit (git path)**: verify each git command returned exit code 0. If `git push` succeeds, the commit is saved to the work item branch; the hub registers it asynchronously.
+   - **For commit (API path)**: verify the POST `status`, then `DevopsRequestInfo.Status`, are `SUCCESS`, and that a new `WorkItemComponentList` with a `CommitReference` exists on the hub. A new list with an empty `CommitReference` means nothing new was committed; report that, not a clean success.
    - **For update (general fields)**: verify the CLI returned status 0 and compare the returned JSON fields against the user's requested changes. If updating subject, confirm `.result.subject` matches the new value.
    - **For update (status transition)**: verify the CLI returned status 0, then **explicitly confirm the status transition** by checking `.result.status` in the JSON response matches the target status (e.g., "Ready to Promote"). If the response doesn't include the status field, re-run `sf devops work-item list` filtered to this work item and verify the status persisted.
    - **For create-review**: verify the CLI returned status 0 and the JSON output contains `.result.pullRequestUrl` (the PR URL) and `.result.status` (should be "open" or equivalent). If VCS credentials are missing, the CLI returns an error — surface this to the user.
@@ -170,7 +183,7 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
 9. **Report results**:
    - **List**: present work items in a readable format showing work item name, subject, status, branch, and environment. If filtering by status was requested, show only matching work items.
    - **Create**: return the work item name (e.g., WI-000001), branch name, environment, and confirm "Work item created successfully."
-   - **Commit**: confirm which files were staged, the commit SHA (from git output), and "Changes committed and pushed to branch <branch-name>."
+   - **Commit**: git path — confirm which files were staged, the commit SHA (from git output), and "Changes committed and pushed to branch <branch-name>." API path — confirm the `reqId`, components committed and hub `CommitReference` (author is DevOps Center)
    - **Update (general)**: confirm which fields changed with before/after values (e.g., "Subject updated from 'X' to 'Y'").
    - **Status transition**: explicitly state the transition with old → new status (e.g., "Status updated: In Progress → Ready to Promote").
    - **Create-review**: return the PR URL and confirm "Pull request created successfully. Status: open. URL: <url>"
@@ -187,7 +200,9 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
 | At least one update field required | Update command fails if no `--subject`, `--description`, or `--status` flag is provided |
 | Status values must be exact strings | "In Progress" and "Ready to Promote" (with spaces, proper capitalization); other values fail |
 | Idempotent create operations | Check for existing work item with same subject + project before creating duplicates |
-| Changes must be committed before status transition to Ready to Promote | DevOps Center validates that the work item branch has commits before allowing promotion readiness |
+| Commit before creating a PR | Commit first and confirm a component list exists on the hub before `review create` |
+| API commit only sends components already in the dev org | The API retrieves from the dev org, not from local disk; deploy local-only edits first (`sf project deploy start`) or use the git path |
+| Check `status` in the commit API response | Errors are returned as HTTP 200 with `status: "ERROR"` |
 | PR creation requires VCS credentials in org | DevOps Center API uses stored VCS credentials; no local git auth needed |
 | Never use interactive prompts | Skills run in headless environments; all inputs must be via CLI flags |
 
@@ -205,6 +220,8 @@ All operations use `sf devops work-item` CLI commands with `--json` output for s
 | **Invalid status value** | Only "In Progress" and "Ready to Promote" are valid (exact strings with spaces); check spelling and capitalization |
 | **Project not found** | User provided invalid project ID; run `sf devops project list --json` to show available projects |
 | **Duplicate work item subject** | Idempotent create check should catch this; return existing work item name instead of creating duplicate |
+| **Commit pushed while work item is New** | The hub ignores external pushes for New work items; set In Progress first and, if already pushed, re-check after the status change |
+| **API commit still in progress past the deadline** | Report it as stuck; do not retry automatically (a new request could race it) |
 | **Git push fails - no commits or branch not found** | Verify files are staged with `git status` and branch name retrieved from work item via list command |
 | **PR creation fails - VCS credentials** | VCS credentials not configured in DevOps Center UI; instruct user to configure in Setup → DevOps Center → VCS Credentials |
 
@@ -216,7 +233,7 @@ Deliverables vary by operation:
 
 - **List**: JSON array of work items with work item name (WI-######), subject, branch, environment, repository details
 - **Create**: Work item name (e.g., WI-000001), ID, branch name, and environment of the newly created work item
-- **Commit**: Confirmation of git commit and push success, with commit SHA
+- **Commit**: Confirmation of git commit and push success with commit SHA, or for the API path the `reqId`, final request status and `CommitReference`
 - **Update**: Confirmation of updated fields (old value → new value for subject/description, or status change)
 - **Create-review**: Pull request URL, PR number, and status
 
@@ -247,10 +264,9 @@ Before reporting results to the user:
 - [ ] Was `--project-id` provided (or obtained via project list)?
 
 ### Commit Operation Checks
-- [ ] Was the work item branch name retrieved successfully?
-- [ ] Were files staged with `git add`?
-- [ ] Did `git commit` succeed with exit code 0?
-- [ ] Did `git push` succeed with exit code 0?
+- [ ] API path: preflight passed, POST `status` checked, `DevopsRequestInfo` polled to `SUCCESS`, new `WorkItemComponentList` with `CommitReference` seen on the hub?
+- [ ] Git path: was the work item In Progress, and the branch name retrieved?
+- [ ] Git path: did `git add`, `git commit` and `git push` all exit 0?
 
 ### Update Operation Checks
 - [ ] Was work item identifier provided (name or ID)?
@@ -269,5 +285,6 @@ Before reporting results to the user:
 
 | File | When to read |
 |------|-------------|
+| `references/commit-api.md` | When committing through the DevOps Center API: request body, response and error codes, polling, preflight |
 | `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 (bulk updates, reassignment, idempotent creation, sequential transitions) |

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

@@ -477,3 +477,52 @@ Real-world examples of typical work item operations in DevOps Center autonomous
    ```
 
 > **Note:** The CLI will return a non-zero status with error name `PR_ALREADY_EXISTS` if a PR already exists for that work item.
+
+---
+
+## Workflow 16: Commit Through the DevOps Center API (with git fallback)
+
+**User request:** "Commit the HelloWorld class to WI-000001. My changes are in the dev org <dev-org>."
+
+**Steps:**
+
+1. **Preflight on the dev org** (both orgs must be authenticated):
+   ```bash
+   sf api request rest "/services/data/v67.0/connect/devops/doceConnectionType" --target-org <dev-org>
+   ```
+   `{"isCore": true}` → continue. A failed call or `isCore` not `true` → use the git path (Workflow 3).
+
+2. **Look up the work item on the hub** (status must be New, In Progress, In Review or Ready to Promote):
+   ```bash
+   sf devops project list --target-org <hub-org> --json
+   sf devops work-item list --project-id <project-id> --target-org <hub-org> --json \
+     | jq '.result.workItems[] | select(.name == "WI-000001")'
+   ```
+
+3. **Commit** (body is the inner object, no wrapper; take `workItemId`/`projectId` from step 2):
+   ```bash
+   BODY=$(mktemp)
+   cat > "$BODY" <<'JSON'
+   {"isCommitCore":"true","workItemId":"<work-item-id>","projectId":"<project-id>",
+    "workItemName":"WI-000001","workItemLink":"<work item url>","commitMessage":"Update HelloWorld",
+    "changes":[{"fullName":"HelloWorld","type":"ApexClass","operation":"modify"}]}
+   JSON
+   sf api request rest "/services/data/v67.0/connect/devops/commitChanges" --method POST --body @"$BODY" --target-org <dev-org>
+   rm "$BODY"
+   ```
+   Expect `{"reqId":"<uuid>","status":"SUCCESS"}` (accepted). If the call fails or `status` is `ERROR`, report the error (`CODE:message` in `reqId`) and stop.
+
+4. **Poll until `SUCCESS` or `ERROR`** (every 10 s, up to 12 min):
+   ```bash
+   sf data query --target-org <dev-org> --json \
+     -q "SELECT Status, Message, ErrorDetails FROM DevopsRequestInfo WHERE RequestToken = '<reqId>'"
+   ```
+
+5. **Confirm on the hub**, then offer to create the review:
+   ```bash
+   sf data query --target-org <hub-org> --json \
+     -q "SELECT Name, CommitReference FROM WorkItemComponentList WHERE WorkItemId = '<work-item-id>' ORDER BY CreatedDate"
+   ```
+   A new row with a `CommitReference` means the commit was recorded.
+
+**Fallback:** if the preflight fails, retrieve the changes with `sf project retrieve start --target-org <dev-org>` if they exist only in the dev org, set the work item to In Progress if it is New, then follow Workflow 3 and re-check the hub before creating the PR.