/dx-devops-work-item-manage

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."
metadata:
  relatedSkills:
    - "dx-devops-promote"
  version: "1.0"
  domains: ["Developer Experience"]
  minApiVersion: "58.0"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
    - tool: ["git"]
      semver: ">=2.0.0"
    - tool: ["jq"]
      semver: ">=1.6"

DevOps Center Work Item Management

Manages the complete work item lifecycle in DevOps Center — from creation through status transitions to promotion readiness. Provides headless CLI-driven operations for autonomous release workflows.

Scope

• **In scope**: List work items, create new work items, commit changes to work item branches, update work item fields (subject, description, status), transition work item status (New → In Progress → Ready to Promote), create pull requests for work item branches
• **Out of scope**: Promotion/deployment, conflict detection, pipeline or project management (separate skills)

---

Required Inputs

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 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)

Defaults unless specified:

• Output format: `--json` for headless consumption
• Work item identifier: prefer `--work-item-name` (WI-000001) over `--work-item-id` when both are available (names are human-readable)

If the user provides a clear request ("list work items for Project Alpha", "create work item to fix login bug", "move WI-12345 to In Progress", "create PR for WI-12345"), proceed immediately without unnecessary questions.

---

Workflow

All operations use `sf devops work-item` 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" → list operation
• Keywords like "create", "new", "add" → create operation
• Keywords like "commit", "push", "save changes", "git commit" → commit operation
• Keywords like "update", "change", "modify", "edit", "move", "transition", "advance", "mark as" → update operation
• Keywords like "create PR", "pull request", "code review", "review", "open PR" → create-review operation

Phase 2 — Execute Operation

2. **Verify org authentication** before any operation:

   sf org display --json

• If no default org is set or authentication has expired, instruct the user to run:

     sf org login web --set-default --alias <alias>

• 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

3. **List work items** — when the user wants to see existing work items:

   sf devops work-item list --project-id <project-id> --json

• `--project-id` is required — if the user provides a project name instead of ID, first run `sf devops project list --json` to resolve the name to an ID
• Verify the command returns status 0 (success)
• Parse the JSON output: the work items are in the `.result[]` array
• Each work item has: `name` (e.g., WI-000001), `subject`, `branch`, `environment`, `status`, `description`
• Present in a readable format showing work item name, subject, status, branch, and environment
• If `.result[]` is an empty array, confirm "No work items found in project <project-name>."
• If the user requested filtering by status (e.g., "show work items in Ready to Promote status"), run:

     sf devops work-item list --project-id <id> --json | jq '.result[] | select(.status == "<requested-status>")'

Then present the matching work items

4. **Create a work item** — when the user wants to create a new work item:

   sf devops work-item create \
     --project-id <project-id> \
     --subject "<subject>" \
     --description "<description>" \
     --json

• `--project-id` is required (obtain from user or via `sf devops project list --json`)
• `--subject` is required (user-facing title)
• `--description` is optional (defaults to blank if omitted)
• 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
• Standard git workflow:

     git checkout <branch-name>
     git add <files>
     git commit -m "<commit-message>"
     git push origin <branch-name>