forcedotcom/sf-skills / plugins/builder/dx-devops/skills/dx-devops-work-item-manage
dx-devops-work-item-manage
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.2 KB |
| examples/common-workflows.md | markdown | 16.6 KB |
| references/cli-commands.md | markdown | 10.5 KB |
| references/commit-api.md | markdown | 6.2 KB |
| references/review-api.md | markdown | 5.0 KB |
references/cli-commands.md
View on GitHub# 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |