/dx-devops-project-manage

name: dx-devops-project-manage
description: "Use to list, view, or manage DevOps Center projects in a Salesforce org — show all projects, create a project, or update an existing project's name, description, or active status. Invoke to run sf devops project list on any listing request, or to create a project, set up a new pipeline foundation, initialize DevOps Center for a feature, update project settings, or activate/deactivate (archive) a project. Consolidates sf devops project list/create/update. 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: "(OrgPreferences.ALMDevopsCorePref) && (UserPermissions.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:

   # 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:

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