# setup-agents ⚡ — Agentic Development Framework for Salesforce

> Configure once. Let agents drive.

[![Plugin version](https://img.shields.io/npm/v/@jterrats/setup-agents.svg?logo=npm&label=plugin)](https://npmjs.org/package/@jterrats/setup-agents)
[![Extension version](https://img.shields.io/github/v/tag/jterrats/setup-agents?filter=ext-*&logo=visualstudiocode&label=extension)](https://github.com/jterrats/setup-agents/releases?q=ext-)
[![Downloads](https://img.shields.io/npm/dw/@jterrats/setup-agents.svg?logo=npm)](https://npmjs.org/package/@jterrats/setup-agents)
[![CI](https://img.shields.io/github/actions/workflow/status/jterrats/setup-agents/test.yml?branch=main&logo=github&label=CI)](https://github.com/jterrats/setup-agents/actions)
[![License](https://img.shields.io/npm/l/@jterrats/setup-agents.svg)](https://github.com/jterrats/setup-agents/blob/main/LICENSE.txt)
[![Node.js](https://img.shields.io/node/v/@jterrats/setup-agents.svg?logo=node.js)](https://nodejs.org)

> **Disclaimer:** This is a **personal open-source project** by [Jaime Terrats](https://github.com/jterrats). It is **not** an official Salesforce product, nor is it endorsed, supported, or affiliated with Salesforce, Inc. Use at your own discretion.

---

## About

`setup-agents` is an agentic development framework for Salesforce teams. It gives AI agents everything they need to operate as a senior team member in a Salesforce project: role identity, project standards, a workflow engine, and an accountability loop.

```
sf setup-agents init          # configure profiles, tools, and workspace once
        │
        ▼
  CLAUDE.md / AGENTS.md       # agents read this on every session
  .cursor/rules/*.mdc         # role-specific standards loaded per task type
        │
        ▼
sf setup-agents workflow run --story SA-42
        │
        ├── BA phase          # refine acceptance criteria
        ├── Architect phase   # design decisions + ADR
        ├── Developer phase   # implement + unit tests
        ├── QA phase          # verify + evidence
        └── Release phase     # validate + PR
        │
        ▼
  evidence.jsonl + decisions.jsonl   # auditable delivery trail
```

Phases are dynamic — only the roles configured for your project run. A project with just `developer` runs Developer → QA → Release. Add `architect` and the Architect phase is inserted automatically.

### What agents get

- **41 role profiles** — Developer, Technical Architect, Solution Architect, BA, PM, MuleSoft, UX, CGCloud, DevOps, QA, CRMA, Commerce, Data Cloud, Admin, SFMC, Security, Service, CPQ, OmniStudio, FSL, FSC, AI/Agentforce, Slack, Tableau, Experience Cloud, Release Manager, Sales Cloud, Health Cloud, Manufacturing Cloud, Communications Cloud, Automotive Cloud, Education Cloud, Net Zero Cloud, Nonprofit Cloud, Public Sector Solutions, Media Cloud, Energy & Utilities Cloud, Revenue Cloud, Salesforce Maps, Loyalty Management, Salesforce Industries Cloud (Platform)
- **Workflow engine** — autonomous multi-phase pipeline with gates, QA loop, and resume
- **Sub-agent protocol** — generated routing manifest mapping task types to roles with handover checklists
- **Evidence and accountability** — agents record commands, files, and decisions before each gate
- **Action Risk Scale** — agents know what to run autonomously, what to ask, and what to never touch
- **Agentforce Workflows** — `.a4drules/workflows/*.md` for automated dev tasks in Vibes chat
- **MCP integration** — `sf setup-agents mcp` wires `@salesforce/mcp` into Cursor for any org

### What teams get

- **VS Code Extension** — visual sidebar for guided setup, MCP config, integrations, and rule management
- **Auto-detection** — detects `cgcloud__`, `WaveDashboard`, `DataStream`, Playwright config, and more
- **Combinable profiles** — `--profile developer,architect,crma` stacks rules from multiple roles
- **Rule overrides** — customize Cursor scope and globs per profile in `config.json`
- **Safe by default** — never overwrites existing rule files without `--force`

---

## Quick Start

```sh
# Install the plugin
sf plugins install @jterrats/setup-agents

# Run in your Salesforce project
cd my-salesforce-project
sf setup-agents local
```

The command auto-detects your tools and prompts for role selection:

```
? Select your role profile(s):
❯◉ Developer
 ◯ Architect
 ◯ Business Analyst
 ◯ Project Manager
 ◯ MuleSoft
 ◯ UX / UI
 ◉ CGCloud  ← pre-selected (cgcloud__ detected)
 ◯ DevOps / Release Manager
 ◯ QA (Playwright)
 ◯ CRM Analytics Engineer (CRMA)
 ◯ Data Cloud Architect / Engineer (Data 360)
 ◯ Salesforce Admin / Configurator
 ◯ Salesforce Marketing Cloud (SFMC)
 ◯ Security / Compliance
 ◯ Service Cloud
 ◯ CPQ Specialist
 ◯ OmniStudio / Vlocity
 ◯ Field Service (FSL)
 ◯ AI / Agentforce Specialist
 ◯ Slack Developer
 ◯ Tableau / Analytics Cloud
```

> **Unsigned Plugin Notice:**
> You will be prompted the first time you install an unsigned plugin. To trust this plugin:
>
> ```sh
> sf plugins install @jterrats/setup-agents --no-verify
> # or add to allowlist in ~/.config/sf/unsignedPluginAllowList.json
> ```

> **Full agent workflow guide:** see [docs/user-guide/agent-workflow.md](docs/user-guide/agent-workflow.md) for the complete loop — from init to shipped PR — with phase matrix, gates, evidence, and a real example.

> **Versioning:** the plugin (`v2.x`) and the VS Code extension (`ext-v1.x`) are released independently on separate tracks. Both badges above always reflect the latest of each.

### VS Code Extension (Preview)

A visual sidebar UI that wraps the CLI plugin for teams that prefer point-and-click over terminal commands.

<p align="center">
  <img src="docs/assets/extension-guided-setup.gif" alt="Extension demo: guided setup and MCP configuration" width="420" />
</p>

**Features:**

- **Guided Setup** — auto-detects tools, displays 41 profile cards, scope selector, live console output
- **MCP Configuration** — lists authenticated orgs, pre-selects already-connected ones, one-click connect
- **Third-Party Integrations** — profile-filtered cards for Figma, Jira, draw.io, GitHub with credential input
- **Update Agent Rules** — detects stale files and updates in one click
- **Rule Management** — import from URL/file, browse, edit, and save rule files inline
- **Health Checks** — verifies SF CLI and plugin installation with actionable error banners

<details>
<summary>SF CLI not installed?</summary>
<p align="center">
  <img src="docs/assets/extension-sf-cli-missing.gif" alt="Extension: SF CLI missing banner" width="420" />
</p>
</details>

```sh
cd extensions/vscode-setup-agents-ui
npm install && npm run build
# Then press F5 or open the Setup Agents sidebar in VS Code
```

> **Full documentation:** see the [Extension page](https://jterrats.github.io/setup-agents/extension/) on the docs site.

---

## Architecture

```mermaid
graph TD
    subgraph cmds [Commands]
        local["sf setup-agents local"]
        mcp["sf setup-agents mcp"]
        update["sf setup-agents update"]
    end

    subgraph setup [Setup Layer]
        cursorSetup["cursor-setup.ts"]
        vscodeSetup["vscode-setup.ts"]
        codexSetup["codex-setup.ts"]
        claudeSetup["claude-setup.ts"]
        a4dSetup["agentforce-setup.ts"]
    end

    subgraph gen [Generators]
        mdcGen["mdc-generator"]
        workflowGen["workflow-generator"]
        copilotGen["copilot-generator"]
        extGen["extensions-generator"]
        codexGen["codex-generator"]
        claudeGen["claude-generator"]
        a4dGen["agentforce-generator"]
        diagramGen["diagram-renderer"]
        reportGen["report-renderer"]
        dashGen["dashboard-generator"]
        sharedGen["shared"]
    end

    local --> detectTools["detectTools()"]
    local --> resolveProfiles["resolveProfiles()"]
    local --> cursorSetup
    local --> vscodeSetup
    local --> codexSetup
    local --> claudeSetup
    local --> a4dSetup

    cursorSetup --> mdcGen
    cursorSetup --> workflowGen
    vscodeSetup --> copilotGen
    vscodeSetup --> extGen
    codexSetup --> codexGen
    claudeSetup --> claudeGen
    a4dSetup --> a4dGen
    a4dSetup --> workflowGen
    a4dGen --> sharedGen
    claudeGen --> sharedGen

    mcp --> orgList["sf org list"]
    mcp --> mcpJson[".cursor/mcp.json"]

    update --> findStale["findStaleFiles()"]
    update --> local
```

### Files generated per tool

| Tool           | Files                                                                                                                         |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Cursor**     | `.cursor/rules/agent-guidelines.mdc`, `salesforce-standards.mdc`, `<profile>-standards.mdc`, `sub-agent-protocol.mdc`         |
| **VS Code**    | `.github/copilot-instructions.md`, `.vscode/extensions.json`                                                                  |
| **Codex**      | `AGENTS.md`                                                                                                                   |
| **Claude**     | `CLAUDE.md`                                                                                                                   |
| **Agentforce** | `.a4drules/00-base-guidelines.md`, `01-salesforce-standards.md`, `<profile>.md`, `99-sub-agent-protocol.md`, `workflows/*.md` |

---

## Profiles

Each profile generates a dedicated `.mdc` rule file in `.cursor/rules/` and contributes extensions to `.vscode/extensions.json`.

| Profile                                    | Flag               | Rule File                        | Auto-detect Signal                                |
| ------------------------------------------ | ------------------ | -------------------------------- | ------------------------------------------------- |
| **Developer**                              | `developer`        | `developer-standards.mdc`        | —                                                 |
| **Technical Architect**                    | `ta`               | `ta-standards.mdc`               | —                                                 |
| **Architect** _(alias → ta)_               | `architect`        | `architect-standards.mdc`        | —                                                 |
| **Solution Architect**                     | `sa`               | `sa-standards.mdc`               | —                                                 |
| **Business Analyst**                       | `ba`               | `ba-standards.mdc`               | —                                                 |
| **Project Manager**                        | `pm`               | `pm-standards.mdc`               | —                                                 |
| **MuleSoft**                               | `mulesoft`         | `mulesoft-standards.mdc`         | `mule-artifact.json` / `pom.xml`                  |
| **UX / UI**                                | `ux`               | `ux-standards.mdc`               | —                                                 |
| **CGCloud**                                | `cgcloud`          | `cgcloud-standards.mdc`          | `cgcloud__` in `package.xml`                      |
| **DevOps**                                 | `devops`           | `devops-standards.mdc`           | `azure-pipelines.yml`                             |
| **QA**                                     | `qa`               | `qa-standards.mdc`               | `playwright.config.ts/js`                         |
| **CRM Analytics**                          | `crma`             | `analytics-standards.mdc`        | `WaveDashboard` / `WaveDataflow` in `package.xml` |
| **Commerce Cloud**                         | `commerce`         | `commerce-standards.mdc`         | `dw.json` / `cartridges/` / B2B metadata          |
| **Data Cloud**                             | `data360`          | `data360-standards.mdc`          | `DataStream` / `DataModelObject` in `package.xml` |
| **Admin**                                  | `admin`            | `admin-standards.mdc`            | `force-app/`                                      |
| **SFMC**                                   | `sfmc`             | `sfmc-standards.mdc`             | `.ampscript` / `mc-project.json`                  |
| **Security**                               | `security`         | `security-standards.mdc`         | `force-app/`                                      |
| **Service Cloud**                          | `service`          | `service-standards.mdc`          | `objects/Case/` / entitlements / bots             |
| **CPQ**                                    | `cpq`              | `cpq-standards.mdc`              | `SBQQ__` metadata                                 |
| **OmniStudio**                             | `omnistudio`       | `omnistudio-standards.mdc`       | `omniScripts/` / `flexCards/`                     |
| **Field Service**                          | `fsl`              | `fsl-standards.mdc`              | `ServiceAppointment` / `WorkOrder` metadata       |
| **AI / Agentforce**                        | `ai`               | `ai-standards.mdc`               | `bots/` / `aiApplications/`                       |
| **Slack**                                  | `slack`            | `slack-standards.mdc`            | `slack.json` / `manifest.json`                    |
| **Tableau**                                | `tableau`          | `tableau-standards.mdc`          | `datasources/` / `workbooks/`                     |
| **Experience Cloud**                       | `experience-cloud` | `experience-cloud-standards.mdc` | `experiences/` / `sites/`                         |
| **Release Manager**                        | `release-manager`  | `release-manager-standards.mdc`  | `sfdx-project.json` / `force-app/`                |
| **Financial Services Cloud**               | `fsc`              | `fsc-standards.mdc`              | `FinServ__FinancialAccount__c` / rollup CMDT      |
| **Health Cloud**                           | `health`           | `health-standards.mdc`           | `HealthCloudGA__` / `CarePlan` / `CareProgram`    |
| **Manufacturing Cloud**                    | `manufacturing`    | `manufacturing-standards.mdc`    | `ManufacturingCloud__` metadata                   |
| **Communications Cloud**                   | `communications`   | `communications-standards.mdc`   | `vlocity_cmt__` / `Vlocity CMT` metadata          |
| **Automotive Cloud**                       | `automotive`       | `automotive-standards.mdc`       | `Automotive__` metadata                           |
| **Education Cloud**                        | `education`        | `education-standards.mdc`        | `Education__` metadata                            |
| **Net Zero Cloud**                         | `netzero`          | `netzero-standards.mdc`          | `StnryAssetEnvrSrc` / carbon footprint metadata   |
| **Nonprofit Cloud**                        | `nonprofit`        | `nonprofit-standards.mdc`        | `npsp__` / `Nonprofit` metadata                   |
| **Public Sector Solutions**                | `public-sector`    | `public-sector-standards.mdc`    | `PublicSector__` metadata                         |
| **Media Cloud**                            | `media`            | `media-standards.mdc`            | `MediaCloud__` metadata                           |
| **Energy & Utilities Cloud**               | `energy`           | `energy-standards.mdc`           | `EnergyUtility__` metadata                        |
| **Revenue Cloud**                          | `revenue`          | `revenue-standards.mdc`          | `Revenue__` / billing metadata                    |
| **Salesforce Maps**                        | `maps`             | `maps-standards.mdc`             | `Maps__` / geolocation metadata                   |
| **Loyalty Management**                     | `loyalty`          | `loyalty-standards.mdc`          | `Loyalty__` / `LoyaltyProgram` metadata           |
| **Salesforce Industries Cloud (Platform)** | `industries`       | `industries-standards.mdc`       | `omnistudio` / `industries` metadata              |
| **Sales Cloud**                            | `salescloud`       | `salescloud-standards.mdc`       | Lead, Opportunity, Forecast, Territory, Quote     |

Profiles are **combinable**. All rules use `alwaysApply: true` so every AI agent in the project has full context.

---

## Sub-agent Protocol

When multiple profiles are active, `sf setup-agents local` generates `.cursor/rules/sub-agent-protocol.mdc` — a routing manifest that tells AI agents which role handles which task type:

```
## Active Profiles
| Role                          | Rule File                  |
|-------------------------------|----------------------------|
| Developer                     | developer-standards.mdc    |
| Analytics Engineer (CRMA)     | analytics-standards.mdc    |
| Data Cloud Engineer           | data360-standards.mdc      |

## Task-to-Profile Routing
| Task Type                              | Assigned Role       |
|----------------------------------------|---------------------|
| Apex / LWC / Triggers                  | Developer           |
| Recipes / Dataflows / SAQL             | Analytics Engineer  |
| Data Streams / Identity Resolution     | Data Cloud Engineer |
```

---

## Agentforce Workflows

When `--rules agentforce` is used on a Salesforce project, the plugin generates workflow files in `.a4drules/workflows/` that can be invoked in the Agentforce Vibes extension chat with `/[workflow-name.md]`.

| Workflow                  | Trigger   | Description                                   |
| ------------------------- | --------- | --------------------------------------------- |
| `deploy.md`               | Always    | Guided Salesforce component deploy            |
| `run-tests.md`            | Always    | Run Apex test classes with coverage           |
| `validate.md`             | Always    | Validate-only deploy (CI-safe)                |
| `create-apex-class.md`    | Developer | Create Apex class following project standards |
| `create-lwc.md`           | Developer | Scaffold LWC with SLDS best practices         |
| `create-trigger.md`       | Developer | Create trigger using Kevin O'Hara pattern     |
| `adr.md`                  | Architect | Architecture Decision Record template         |
| `release.md`              | DevOps    | Release checklist and deployment plan         |
| `create-scratch-org.md`   | DevOps    | Scratch org setup with permission sets        |
| `run-playwright.md`       | QA        | Run Playwright tests and capture report       |
| `generate-test-report.md` | QA        | Generate test coverage report                 |
| `sprint-plan.md`          | PM        | Create sprint plan with Gantt timeline        |
| `status-report.md`        | PM        | Generate weekly status report                 |
| `risk-register.md`        | PM        | Maintain project risk register                |
| `deploy-analytics.md`     | CRMA      | Deploy CRM Analytics dashboards and dataflows |

---

## AI Skills

The plugin generates reusable AI skills (`.cursor/skills/` for Cursor, portable markdown for other tools) for profiles that need them.

| Skill                 | Generated For                | Description                                                                                      |
| --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------ |
| **Story Mapping**     | BA, PM, Architect            | Jeff Patton–style story maps rendered as Mermaid diagrams (PDF)                                  |
| **Deploy & Validate** | Developer, Architect, DevOps | Guided deploy/validate using `@jterrats/profiler` and `@jterrats/smart-deployment` plugins       |
| **Diagram Export**    | BA, PM, Architect, Developer | Export Mermaid diagrams to Lucidchart (API), draw.io (XML), or local SVG/PDF with auto-detection |

---

## Install

```sh
sf plugins install @jterrats/setup-agents
```

### Requirements

- Salesforce CLI (`sf`) v2+
- Node.js >= 18

### Troubleshooting: `ETARGET` date restriction

If you see an error like:

```
npm error notarget No matching version found for @jterrats/setup-agents@X.Y.Z with a date before ...
```

Your npm configuration restricts package installation to versions published before a certain date. This is controlled by the `before` and `min-release-age` options in `~/.npmrc`.

**Fix:**

```bash
npm config delete before
npm config set min-release-age 0
sf plugins install @jterrats/setup-agents@latest
```

**To verify your current settings:**

```bash
npm config get before
npm config get min-release-age
```

> **Note:** `min-release-age` is a security feature that prevents installing packages published less than N days ago (supply chain protection). Setting it to `0` disables the restriction. If you prefer to keep it enabled, wait the configured number of days after a release before installing, or use `sf plugins link .` from a local clone.

---

## Commands

<!-- commands -->

- [`sf setup-agents canvas clean`](#sf-setup-agents-canvas-clean)
- [`sf setup-agents canvas status`](#sf-setup-agents-canvas-status)
- [`sf setup-agents canvas sync`](#sf-setup-agents-canvas-sync)
- [`sf setup-agents dashboard`](#sf-setup-agents-dashboard)
- [`sf setup-agents decision add`](#sf-setup-agents-decision-add)
- [`sf setup-agents decision list`](#sf-setup-agents-decision-list)
- [`sf setup-agents evidence add`](#sf-setup-agents-evidence-add)
- [`sf setup-agents evidence list`](#sf-setup-agents-evidence-list)
- [`sf setup-agents export`](#sf-setup-agents-export)
- [`sf setup-agents handoff create`](#sf-setup-agents-handoff-create)
- [`sf setup-agents handoff list`](#sf-setup-agents-handoff-list)
- [`sf setup-agents import`](#sf-setup-agents-import)
- [`sf setup-agents init`](#sf-setup-agents-init)
- [`sf setup-agents local`](#sf-setup-agents-local)
- [`sf setup-agents mcp`](#sf-setup-agents-mcp)
- [`sf setup-agents review complete`](#sf-setup-agents-review-complete)
- [`sf setup-agents review list`](#sf-setup-agents-review-list)
- [`sf setup-agents review request`](#sf-setup-agents-review-request)
- [`sf setup-agents status`](#sf-setup-agents-status)
- [`sf setup-agents sync`](#sf-setup-agents-sync)
- [`sf setup-agents task archive`](#sf-setup-agents-task-archive)
- [`sf setup-agents task claim`](#sf-setup-agents-task-claim)
- [`sf setup-agents task create`](#sf-setup-agents-task-create)
- [`sf setup-agents task delete`](#sf-setup-agents-task-delete)
- [`sf setup-agents task done`](#sf-setup-agents-task-done)
- [`sf setup-agents task list`](#sf-setup-agents-task-list)
- [`sf setup-agents task update`](#sf-setup-agents-task-update)
- [`sf setup-agents task view`](#sf-setup-agents-task-view)
- [`sf setup-agents update`](#sf-setup-agents-update)
- [`sf setup-agents verify`](#sf-setup-agents-verify)
- [`sf setup-agents workflow benchmark`](#sf-setup-agents-workflow-benchmark)
- [`sf setup-agents workflow clarify`](#sf-setup-agents-workflow-clarify)
- [`sf setup-agents workflow clarify-list`](#sf-setup-agents-workflow-clarify-list)
- [`sf setup-agents workflow clarify-respond`](#sf-setup-agents-workflow-clarify-respond)
- [`sf setup-agents workflow estimate`](#sf-setup-agents-workflow-estimate)
- [`sf setup-agents workflow execute`](#sf-setup-agents-workflow-execute)
- [`sf setup-agents workflow gate`](#sf-setup-agents-workflow-gate)
- [`sf setup-agents workflow pending`](#sf-setup-agents-workflow-pending)
- [`sf setup-agents workflow playbooks`](#sf-setup-agents-workflow-playbooks)
- [`sf setup-agents workflow release-check`](#sf-setup-agents-workflow-release-check)
- [`sf setup-agents workflow rollback`](#sf-setup-agents-workflow-rollback)
- [`sf setup-agents workflow run`](#sf-setup-agents-workflow-run)
- [`sf setup-agents workflow sprint close`](#sf-setup-agents-workflow-sprint-close)
- [`sf setup-agents workflow sprint start`](#sf-setup-agents-workflow-sprint-start)
- [`sf setup-agents workflow sprint velocity`](#sf-setup-agents-workflow-sprint-velocity)
- [`sf setup-agents workflow telemetry`](#sf-setup-agents-workflow-telemetry)

## `sf setup-agents canvas clean`

Remove orphan files from the Cursor canvas cache.

```
USAGE
  $ sf setup-agents canvas clean [--json] [--flags-dir <value>] [--path <value>] [--yes]

FLAGS
  --path=<value>  Target repository path (default: git root of current directory).
  --yes           Skip confirmation prompt and remove orphans immediately.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Remove orphan files from the Cursor canvas cache.

  Finds files in `~/.cursor/projects/<slug>/canvases/` that have no matching source canvas in the repo and removes them.
  Prompts for confirmation unless `--yes` is supplied or stdout is non-TTY.

EXAMPLES
  Remove orphans interactively:

    $ sf setup-agents canvas clean

  Remove orphans without prompting:

    $ sf setup-agents canvas clean --yes
```

_See code: [src/commands/setup-agents/canvas/clean.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/canvas/clean.ts)_

## `sf setup-agents canvas status`

Show the state of Cursor canvas cache entries.

```
USAGE
  $ sf setup-agents canvas status [--json] [--flags-dir <value>] [--path <value>]

FLAGS
  --path=<value>  Target repository path (default: git root of current directory).

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Show the state of Cursor canvas cache entries.

  Lists each source canvas and its state in the Cursor cache: symlink pointing to the correct source (`symlink-ok`),
  symlink with a wrong target (`symlink-wrong`), a regular (possibly stale) file (`regular`), or absent from the cache
  (`missing`). Also reports orphan cache files with no repo counterpart.

EXAMPLES
  Check canvas status for the current repo:

    $ sf setup-agents canvas status
```

_See code: [src/commands/setup-agents/canvas/status.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/canvas/status.ts)_

## `sf setup-agents canvas sync`

Sync Cursor canvas cache with repo source files.

```
USAGE
  $ sf setup-agents canvas sync [--json] [--flags-dir <value>] [--dry-run] [--init] [--clean] [--path <value>]

FLAGS
  --clean         Remove orphan files in cache after syncing.
  --dry-run       Preview changes without writing anything.
  --init          Create the cache directory if it does not exist.
  --path=<value>  Target repository path (default: git root of current directory).

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Sync Cursor canvas cache with repo source files.

  Replaces each cached `.canvas.tsx` file under `~/.cursor/projects/<slug>/canvases/` with a symlink to the repo source
  so edits made outside Cursor are reflected immediately on reopen.

  Supported canvas locations (first match wins): `docs/canvases`, `canvases`, `src/canvases`.

EXAMPLES
  Sync canvases for the current repo:

    $ sf setup-agents canvas sync

  Preview without making changes:

    $ sf setup-agents canvas sync --dry-run

  Initialize cache dir and sync:

    $ sf setup-agents canvas sync --init

  Sync and remove orphans:

    $ sf setup-agents canvas sync --clean
```

_See code: [src/commands/setup-agents/canvas/sync.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/canvas/sync.ts)_

## `sf setup-agents dashboard`

Generate a delivery dashboard from local workflow state.

```
USAGE
  $ sf setup-agents dashboard [--json] [--flags-dir <value>] [-p <value>] [--open] [-f html|json]

FLAGS
  -f, --format=<option>  [default: html] Output format: html (default) or json.
                         <options: html|json>
  -p, --output=<value>   [default: docs/dashboard.html] Output file path for the HTML dashboard.
      --open             Open the dashboard in the default browser after generation.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Generate a delivery dashboard from local workflow state.

  Reads `.setup-agents/state/tasks.jsonl` and `workflow-runs.jsonl` and produces a standalone HTML dashboard (Chart.js,
  SLDS colors) or a JSON metrics payload. No org connection required.

  Default output path: `docs/dashboard.html`.

EXAMPLES
  Generate dashboard at default path:

    $ sf setup-agents dashboard

  Custom output path:

    $ sf setup-agents dashboard --output reports/delivery.html

  Open in browser after generation:

    $ sf setup-agents dashboard --open

  Print raw JSON metrics:

    $ sf setup-agents dashboard --format json

FLAG DESCRIPTIONS
  -f, --format=html|json  Output format: html (default) or json.

    `html` writes a standalone Chart.js file. `json` prints the metrics payload to stdout and does not write a file.

  -p, --output=<value>  Output file path for the HTML dashboard.

    Path where the HTML file will be written. Defaults to `docs/dashboard.html`.
```

_See code: [src/commands/setup-agents/dashboard.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/dashboard.ts)_

## `sf setup-agents decision add`

Add a setup-agents decision record.

```
USAGE
  $ sf setup-agents decision add -s <value> [--json] [--flags-dir <value>] [-t <value>] [-r <value>] [-p
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--rationale <value>] [--status
    proposed|accepted|superseded] [--outcome <value>] [--alternative <value>] [--evidence <value>]

FLAGS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|servic
  e|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Owning setup-agents profile.

  -r, --role=<value>
      [default: developer] Owning role for this decision.

  -s, --summary=<value>
      (required) Short decision summary.

  -t, --task=<value>
      Task or issue id for this decision.

  --alternative=<value>
      Alternatives considered.

  --evidence=<value>
      Related evidence ids.

  --outcome=<value>
      Decision outcome.

  --rationale=<value>
      Decision rationale.

  --status=<option>
      [default: accepted] Decision status.
      <options: proposed|accepted|superseded>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Add a setup-agents decision record.

  Appends a JSON Lines decision entry to `.setup-agents/state/decisions.jsonl`.

  Decision records capture selected approaches, rationale, ownership, timestamps, and optional task ids.

EXAMPLES
  Add an accepted decision for a task:

    $ sf setup-agents decision add --task SA-96 --profile architect --summary "Use native JSONL records" --rationale \
      "Keeps setup-agents independent of external engines"

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Owning setup-agents profile.

    Record the setup-agents profile responsible for the decision.

  -r, --role=<value>  Owning role for this decision.

    Record the current role or agent owner responsible for the decision.

  -s, --summary=<value>  Short decision summary.

    Describe the decision in one concise sentence.

  -t, --task=<value>  Task or issue id for this decision.

    Associate the decision with a task id such as `SA-96` or `#96`.

  --alternative=<value>  Alternatives considered.

    Comma-separated alternatives considered before this decision.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence record ids that support this decision.

  --outcome=<value>  Decision outcome.

    Record the outcome text for the decision. When omitted, the status is used.

  --rationale=<value>  Decision rationale.

    Add the reason this decision was made.

  --status=proposed|accepted|superseded  Decision status.

    Set whether the decision is proposed, accepted, or superseded.
```

_See code: [src/commands/setup-agents/decision/add.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/decision/add.ts)_

## `sf setup-agents decision list`

List setup-agents decision records.

```
USAGE
  $ sf setup-agents decision list [--json] [--flags-dir <value>] [-t <value>] [-r <value>] [-p <value>] [--status <value>] [-l
    <value>]

FLAGS
  -l, --limit=<value>    [default: 20] Maximum records to show.
  -p, --profile=<value>  Filter by owning setup-agents profile.
  -r, --role=<value>     Filter by owning role.
  -t, --task=<value>     Filter by task or issue id.
      --status=<value>   Filter by decision status.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List setup-agents decision records.

  Reads JSON Lines decision entries from `.setup-agents/state/decisions.jsonl`.

EXAMPLES
  List recent decisions:

    $ sf setup-agents decision list

  List accepted decisions for a task:

    $ sf setup-agents decision list --task SA-96 --status accepted

FLAG DESCRIPTIONS
  -l, --limit=<value>  Maximum records to show.

    Limit the number of matching records returned from the end of the decision log.

  -p, --profile=<value>  Filter by owning setup-agents profile.

    Show only decision records owned by the given setup-agents profile.

  -r, --role=<value>  Filter by owning role.

    Show only decision records owned by the given role.

  -t, --task=<value>  Filter by task or issue id.

    Show only decision records associated with the given task id.

  --status=<value>  Filter by decision status.

    Show only decisions matching the given status.
```

_See code: [src/commands/setup-agents/decision/list.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/decision/list.ts)_

## `sf setup-agents evidence add`

Add a setup-agents evidence record.

```
USAGE
  $ sf setup-agents evidence add -s <value> [--json] [--flags-dir <value>] [-t <value>] [-r <value>] [-p
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--type
    command|file|screenshot|trace|report|validation|other] [--kind
    command|file|screenshot|trace|report|validation|other] [--source <value>] [--command <value>] [--path <value>]
    [--exit-code <value>] [--details <value>]

FLAGS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|servic
  e|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Owning setup-agents profile.

  -r, --role=<value>
      [default: developer] Owning role for this evidence.

  -s, --summary=<value>
      (required) Short evidence summary.

  -t, --task=<value>
      Task or issue id for this evidence.

  --command=<value>
      Command that produced this evidence.

  --details=<value>
      Additional evidence details.

  --exit-code=<value>
      Command exit code.

  --kind=<option>
      Evidence kind.
      <options: command|file|screenshot|trace|report|validation|other>

  --path=<value>
      Evidence path.

  --source=<value>
      Evidence source reference.

  --type=<option>
      [default: other] Evidence type.
      <options: command|file|screenshot|trace|report|validation|other>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Add a setup-agents evidence record.

  Appends a JSON Lines evidence entry to `.setup-agents/state/evidence.jsonl`.

  Evidence records capture validation artifacts such as commands, files, screenshots, traces, reports, or notes.

EXAMPLES
  Add command evidence for a task:

    $ sf setup-agents evidence add --task SA-96 --profile developer --type command --source "npm run build" \
      --summary "Build passed"

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Owning setup-agents profile.

    Record the setup-agents profile responsible for the evidence.

  -r, --role=<value>  Owning role for this evidence.

    Record the current role or agent owner responsible for the evidence.

  -s, --summary=<value>  Short evidence summary.

    Describe the evidence in one concise sentence.

  -t, --task=<value>  Task or issue id for this evidence.

    Associate the evidence with a task id such as `SA-96` or `#96`.

  --command=<value>  Command that produced this evidence.

    Record the command string used to produce command evidence.

  --details=<value>  Additional evidence details.

    Add optional supporting details that should be stored with the evidence record.

  --exit-code=<value>  Command exit code.

    Record the exit code for command evidence.

  --kind=command|file|screenshot|trace|report|validation|other  Evidence kind.

    Alias for `--type`.

  --path=<value>  Evidence path.

    Record a file, report, screenshot, or trace path.

  --source=<value>  Evidence source reference.

    Reference a command, file path, URL, report path, trace id, or other source for the evidence.

  --type=command|file|screenshot|trace|report|validation|other  Evidence type.

    Classify the evidence as command, file, screenshot, trace, report, validation, or other.
```

_See code: [src/commands/setup-agents/evidence/add.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/evidence/add.ts)_

## `sf setup-agents evidence list`

List setup-agents evidence records.

```
USAGE
  $ sf setup-agents evidence list [--json] [--flags-dir <value>] [-t <value>] [-r <value>] [-p <value>] [-l <value>]

FLAGS
  -l, --limit=<value>    [default: 20] Maximum records to show.
  -p, --profile=<value>  Filter by owning setup-agents profile.
  -r, --role=<value>     Filter by owning role.
  -t, --task=<value>     Filter by task or issue id.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List setup-agents evidence records.

  Reads JSON Lines evidence entries from `.setup-agents/state/evidence.jsonl`.

EXAMPLES
  List recent evidence:

    $ sf setup-agents evidence list

  List evidence for a task:

    $ sf setup-agents evidence list --task SA-96

FLAG DESCRIPTIONS
  -l, --limit=<value>  Maximum records to show.

    Limit the number of matching records returned from the end of the evidence log.

  -p, --profile=<value>  Filter by owning setup-agents profile.

    Show only evidence records owned by the given setup-agents profile.

  -r, --role=<value>  Filter by owning role.

    Show only evidence records owned by the given role.

  -t, --task=<value>  Filter by task or issue id.

    Show only evidence records associated with the given task id.
```

_See code: [src/commands/setup-agents/evidence/list.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/evidence/list.ts)_

## `sf setup-agents export`

Export setup-agents workspace state to a portable bundle file.

```
USAGE
  $ sf setup-agents export [--json] [--flags-dir <value>] [--output <value>]

FLAGS
  --output=<value>  Output file path for the export bundle.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Export setup-agents workspace state to a portable bundle file.

  Reads all orchestration state from `.setup-agents/state/` (tasks, decisions, evidence, handoffs, reviews) plus
  `config.json` and writes them to a `.setup-agents-export.json` file.

  The exported bundle preserves setup-agents profile ownership on all records and can be imported into another workspace
  using `setup-agents import`.

EXAMPLES
  Export workspace state to the default output path:

    $ sf setup-agents export

  Export to a specific file:

    $ sf setup-agents export --output /tmp/my-workspace.setup-agents-export.json

FLAG DESCRIPTIONS
  --output=<value>  Output file path for the export bundle.

    Path where the export bundle will be written. Defaults to `<cwd>/setup-agents-export-<timestamp>.json`.
```

_See code: [src/commands/setup-agents/export.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/export.ts)_

## `sf setup-agents handoff create`

Create a setup-agents handoff record.

```
USAGE
  $ sf setup-agents handoff create -s <value> --from <value> --to <value> [--json] [--flags-dir <value>] [-t <value>] [-r
    <value>] [-p developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|servi
    ce|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--files <value>] [--changed-file
    <value>] [--risks <value>] [--risk <value>] [--next-actions <value>] [--next-action <value>] [--evidence <value>]

FLAGS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|servic
  e|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Owning setup-agents profile.

  -r, --role=<value>
      [default: developer] Owning role for this handoff.

  -s, --summary=<value>
      (required) Short handoff summary.

  -t, --task=<value>
      Task or issue id for this handoff.

  --changed-file=<value>
      Changed file paths.

  --evidence=<value>
      Related evidence ids.

  --files=<value>
      Changed files.

  --from=<value>
      (required) Source role or profile.

  --next-action=<value>
      Next actions.

  --next-actions=<value>
      Next actions.

  --risk=<value>
      Known risks.

  --risks=<value>
      Known risks.

  --to=<value>
      (required) Target role or profile.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Create a setup-agents handoff record.

  Appends a JSON Lines handoff entry to `.setup-agents/state/handoffs.jsonl`.

  Handoff records capture role-to-role transfer summaries, ownership, task ids, changed files, risks, and next actions.

EXAMPLES
  Create a handoff from developer to QA:

    $ sf setup-agents handoff create --task SA-96 --from developer --to qa --files "src/foo.ts,test/foo.test.ts" \
      --summary "Commands implemented and ready for verification"

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Owning setup-agents profile.

    Record the setup-agents profile responsible for this handoff record.

  -r, --role=<value>  Owning role for this handoff.

    Record the current role or agent owner responsible for this handoff record.

  -s, --summary=<value>  Short handoff summary.

    Describe the handoff in one concise sentence.

  -t, --task=<value>  Task or issue id for this handoff.

    Associate the handoff with a task id such as `SA-96` or `#96`.

  --changed-file=<value>  Changed file paths.

    Alias for `--files`.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence record ids that support this handoff.

  --files=<value>  Changed files.

    Comma-separated list of files relevant to the handoff.

  --from=<value>  Source role or profile.

    Record who is handing off the work.

  --next-action=<value>  Next actions.

    Alias for `--next-actions`.

  --next-actions=<value>  Next actions.

    Record concise next actions for the receiving role.

  --risk=<value>  Known risks.

    Alias for `--risks`.

  --risks=<value>  Known risks.

    Record known risks, gaps, or review concerns.

  --to=<value>  Target role or profile.

    Record who should receive the handoff.
```

_See code: [src/commands/setup-agents/handoff/create.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/handoff/create.ts)_

## `sf setup-agents handoff list`

List setup-agents handoff records.

```
USAGE
  $ sf setup-agents handoff list [--json] [--flags-dir <value>] [-t <value>] [-r <value>] [-p <value>] [--from <value>] [--to
    <value>] [-l <value>]

FLAGS
  -l, --limit=<value>    [default: 20] Maximum records to show.
  -p, --profile=<value>  Filter by owning setup-agents profile.
  -r, --role=<value>     Filter by owning role.
  -t, --task=<value>     Filter by task or issue id.
      --from=<value>     Filter by source role or profile.
      --to=<value>       Filter by target role or profile.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List setup-agents handoff records.

  Reads JSON Lines handoff entries from `.setup-agents/state/handoffs.jsonl`.

EXAMPLES
  List recent handoffs:

    $ sf setup-agents handoff list

  List handoffs for a task:

    $ sf setup-agents handoff list --task SA-96

FLAG DESCRIPTIONS
  -l, --limit=<value>  Maximum records to show.

    Limit the number of matching records returned from the end of the handoff log.

  -p, --profile=<value>  Filter by owning setup-agents profile.

    Show only handoff records owned by the given setup-agents profile.

  -r, --role=<value>  Filter by owning role.

    Show only handoff records owned by the given role.

  -t, --task=<value>  Filter by task or issue id.

    Show only handoff records associated with the given task id.

  --from=<value>  Filter by source role or profile.

    Show only handoffs from the given role or profile.

  --to=<value>  Filter by target role or profile.

    Show only handoffs to the given role or profile.
```

_See code: [src/commands/setup-agents/handoff/list.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/handoff/list.ts)_

## `sf setup-agents import`

Import setup-agents workspace state from an export bundle file.

```
USAGE
  $ sf setup-agents import --file <value> [--json] [--flags-dir <value>] [--on-conflict skip|overwrite] [--dry-run]

FLAGS
  --dry-run               Preview what would be imported without writing any files.
  --file=<value>          (required) Path to the export bundle file.
  --on-conflict=<option>  [default: skip] How to handle records whose id already exists in the workspace.
                          <options: skip|overwrite>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Import setup-agents workspace state from an export bundle file.

  Reads a `.setup-agents-export.json` bundle and appends its records into the current workspace's `.setup-agents/state/`
  JSONL files.

  Validates the bundle format before importing. Existing records with the same id are either skipped or overwritten
  depending on `--on-conflict`. Use `--dry-run` to preview changes without writing anything.

EXAMPLES
  Import from a bundle file (default: skip conflicts):

    $ sf setup-agents import --file ./setup-agents-export-1234567890.json

  Import and overwrite conflicting records:

    $ sf setup-agents import --file ./bundle.setup-agents-export.json --on-conflict overwrite

  Preview import without writing:

    $ sf setup-agents import --file ./bundle.setup-agents-export.json --dry-run

FLAG DESCRIPTIONS
  --dry-run  Preview what would be imported without writing any files.

    Runs validation and conflict resolution but does not write any JSONL records. Useful for auditing a bundle before
    committing to the import.

  --file=<value>  Path to the export bundle file.

    Path to a `.setup-agents-export.json` bundle produced by `setup-agents export`.

  --on-conflict=skip|overwrite  How to handle records whose id already exists in the workspace.

    Set to `skip` (default) to leave existing records untouched, or `overwrite` to append the incoming record on top of
    the existing one.
```

_See code: [src/commands/setup-agents/import.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/import.ts)_

## `sf setup-agents init`

Initialize setup-agents workspace configuration.

```
USAGE
  $ sf setup-agents init [--json] [--flags-dir <value>] [--mode project|advisory] [--advisory] [--profile
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--tools
    cursor|vscode|codex|claude|agentforce|windsurf|jetbrains] [-f] [--commit] [--dry-run]

FLAGS
  -f, --force
      Overwrite existing workspace config.

  --advisory
      Persist advisory mode.

  --commit
      Add team setup note to README.md.

  --dry-run
      Preview changes without writing.

  --mode=<option>
      [default: project] Workspace mode to persist.
      <options: project|advisory>

  --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cp
  q|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Role profiles to persist (comma-separated).

  --tools=cursor|vscode|codex|claude|agentforce|windsurf|jetbrains
      AI tools to persist (comma-separated).

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Initialize setup-agents workspace configuration.

  Creates `.setup-agents/config.json` in the current project directory with default setup-agents workspace settings.

  The config stores the plugin version, workspace mode, selected profiles, selected tools, and native orchestration
  settings.

  Use project mode for a normal repository workspace. Use advisory mode for consultative setup defaults outside a
  project workspace.

EXAMPLES
  Initialize project workspace config with detected defaults:

    $ sf setup-agents init

  Initialize advisory workspace config:

    $ sf setup-agents init --mode advisory

  Initialize with explicit profiles and tools:

    $ sf setup-agents init --profile developer,architect --tools codex,claude

  Recreate an existing config:

    $ sf setup-agents init --force

  Initialize and add team setup instructions to README.md:

    $ sf setup-agents init --commit

FLAG DESCRIPTIONS
  -f, --force  Overwrite existing workspace config.

    Force overwrite of `.setup-agents/config.json` if it already exists.

  --advisory  Persist advisory mode.

    Shortcut for `--mode advisory`.

  --commit  Add team setup note to README.md.

    After writing `.setup-agents/config.json`, appends a short "Team Setup" section to `README.md` (creates it if
    missing) instructing teammates to run `sf setup-agents local` after cloning to generate their AI rule files from the
    committed config.

  --dry-run  Preview changes without writing.

    Show what would be written without modifying any files.

  --mode=project|advisory  Workspace mode to persist.

    Set the workspace mode stored in `.setup-agents/config.json`. Valid options are `project` and `advisory`.

  --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Role profiles to persist (comma-separated).

    Specify one or more role profiles as a comma-separated list.

    When omitted, the command runs a short guided onboarding: first a role question, then a clouds/products question,
    then an optional advanced full-list picker. If no profile is selected, `developer` is used as the default.

  --tools=cursor|vscode|codex|claude|agentforce|windsurf|jetbrains  AI tools to persist (comma-separated).

    Specify one or more AI coding tools as a comma-separated list. Valid options are `cursor`, `vscode`, `codex`,
    `claude`, or `agentforce`.

    When omitted, the command auto-detects tools present in the project; if none are found, all supported tools are
    stored.
```

_See code: [src/commands/setup-agents/init.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/init.ts)_

## `sf setup-agents local`

Configure AI agent rules for the local development environment.

```
USAGE
  $ sf setup-agents local [--json] [--flags-dir <value>] [--rules
    cursor|vscode|codex|claude|agentforce|windsurf|jetbrains] [--profile
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [-f] [--open-orchestra] [--advisory] [--scope
    project|user]

FLAGS
  -f, --force
      Overwrite existing rule files.

  --advisory
      Generate advisory role guidance without project-scoped rule files.

  --open-orchestra
      Generate optional Open Orchestra integration artifacts.

  --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cp
  q|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Role profiles to configure (comma-separated).

  --rules=cursor|vscode|codex|claude|agentforce|windsurf|jetbrains
      Target AI tool to configure (cursor, vscode, codex, claude, agentforce).

  --scope=<option>
      Cursor rule scope: project (default) or user (~/.cursor/rules).
      <options: project|user>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Configure AI agent rules for the local development environment.

  Sets up agent rule files for AI coding assistants in the current project directory.

  Supported tools:

  - **cursor** — Creates `.cursor/rules/agent-guidelines.mdc` and per-profile rule files for Cursor AI.
  - **vscode** — Creates `.github/copilot-instructions.md` and `.vscode/extensions.json` for GitHub Copilot.
  - **codex** — Creates `AGENTS.md` for OpenAI Codex CLI.
  - **claude** — Creates `CLAUDE.md` for Anthropic Claude Code.
  - **agentforce** — Creates `.a4drules/` numbered markdown files for Agentforce Vibes Extension.

  If `--rules` is omitted, the command auto-detects installed tools based on existing directories
  (`.cursor`, `.vscode`, `AGENTS.md`, `CLAUDE.md`, `.a4drules`). If none are detected, all tools are configured.

  If `--profile` is omitted, the command auto-detects profiles from the project structure and
  presents a selection prompt. If nothing is selected, the `developer` profile is used by default.

  Use `--force` to overwrite existing files (useful when running `sf setup-agents update` under the hood).

EXAMPLES
  Configure all detected AI tools with interactive profile selection:

    $ sf setup-agents local

  Configure only Cursor rules:

    $ sf setup-agents local --rules cursor

  Configure only GitHub Copilot instructions for VS Code:

    $ sf setup-agents local --rules vscode

  Configure only Codex (AGENTS.md):

    $ sf setup-agents local --rules codex

  Configure Claude Code (CLAUDE.md):

    $ sf setup-agents local --rules claude

  Configure Agentforce Vibes rules:

    $ sf setup-agents local --rules agentforce

  Configure with a specific profile:

    $ sf setup-agents local --profile developer

  Configure with multiple combined profiles:

    $ sf setup-agents local --profile developer,architect,cgcloud

  Configure QA automation profile:

    $ sf setup-agents local --profile qa

  Force overwrite all existing rule files:

    $ sf setup-agents local --force

  Generate optional Open Orchestra integration artifacts:

    $ sf setup-agents local --open-orchestra

  Generate advisory guidance outside a project workspace:

    $ sf setup-agents local --advisory --profile architect,ba

FLAG DESCRIPTIONS
  -f, --force  Overwrite existing rule files.

    Force overwrite of all generated files, even if they already exist.
    Use this flag after updating your profiles or when the plugin version has changed.

  --advisory  Generate advisory role guidance without project-scoped rule files.

    Create `.setup-agents/advisory/` with consultative role guidance for sessions outside a project workspace.
    Advisory mode does not create `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.codex/`, or `.a4drules/`.

  --open-orchestra  Generate optional Open Orchestra integration artifacts.

    Create `.setup-agents/open-orchestra/` with profile-to-role mapping and boundary documentation.
    This does not install Open Orchestra or enable runtime orchestration by default.

  --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Role profiles to configure (comma-separated).

    Specify one or more role profiles as a comma-separated list. Each profile generates a dedicated
    rule file with role-specific agent guidance and adds the relevant VS Code extensions.

    Valid profiles: developer, architect, ba, pm, mulesoft, ux, cgcloud, devops, qa, crma, commerce, data360, admin,
    sfmc, security, service, cpq, omnistudio, fsl, ai, slack, tableau

    When omitted, the command auto-detects profiles from the project structure and presents an
    interactive multi-select prompt. If no profile is selected, `developer` is used as the default.

  --rules=cursor|vscode|codex|claude|agentforce|windsurf|jetbrains

    Target AI tool to configure (cursor, vscode, codex, claude, agentforce).

    Specify which AI coding assistant to configure. Valid options are `cursor`, `vscode`, `codex`, `claude`, or
    `agentforce`.
    When omitted, the command auto-detects tools present in the project; if none are found, all tools are configured.

  --scope=project|user  Cursor rule scope: project (default) or user (~/.cursor/rules).

    Controls where Cursor rule files are written. Use `user` to install rules globally in `~/.cursor/rules` so they
    apply to every project. Defaults to `project` (writes to `.cursor/rules/` in the current workspace).
```

_See code: [src/commands/setup-agents/local.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/local.ts)_

## `sf setup-agents mcp`

Configure Cursor MCP servers for Salesforce orgs.

```
USAGE
  $ sf setup-agents mcp [--json] [--flags-dir <value>] [--target-org myOrgAlias] [--profile
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--all-toolsets] [-g]

FLAGS
  -g, --global
      Write to the global ~/.cursor/mcp.json instead of the project-level .cursor/mcp.json.

  --all-toolsets
      Enable all MCP toolsets regardless of profile.

  --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cp
  q|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Role profile(s) used to determine MCP toolsets.

  --target-org=myOrgAlias
      Salesforce org alias or username to configure.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Configure Cursor MCP servers for Salesforce orgs.

  Sets up Cursor's Micro-Agent Collaboration Protocol (MCP) configuration for one or more
  Salesforce orgs using `@salesforce/mcp`. This allows Cursor AI to interact directly with
  your Salesforce org metadata, data, users, and testing tools via tool calls.

  The command writes (or merges into) a `.cursor/mcp.json` file with an MCP server entry per
  selected org. Use `--global` to write to the user-level `~/.cursor/mcp.json` instead.

  Toolsets included by default (based on profile):

  - **metadata** — SFDX metadata read/deploy tools.
  - **data** — SOQL and org data inspection tools.
  - **testing** — Apex and project testing tools.
  - **users** — permission set and user management tools.

  If `--target-org` is omitted, all authenticated orgs are listed for interactive selection.

EXAMPLES
  Configure MCP for all authenticated orgs (interactive):

    $ sf setup-agents mcp

  Configure MCP for a specific org:

    $ sf setup-agents mcp --target-org myOrgAlias

  Configure MCP globally (all projects):

    $ sf setup-agents mcp --global --target-org myOrgAlias

  Configure MCP with toolsets for the developer profile:

    $ sf setup-agents mcp --profile developer --target-org myOrgAlias

  Configure MCP with all toolsets:

    $ sf setup-agents mcp --all-toolsets --target-org myOrgAlias

FLAG DESCRIPTIONS
  -g, --global  Write to the global ~/.cursor/mcp.json instead of the project-level .cursor/mcp.json.

    When set, the MCP server entries are added to `~/.cursor/mcp.json`, making them available
    across all Cursor projects on this machine.

  --all-toolsets  Enable all MCP toolsets regardless of profile.

    Force-enable all available MCP toolsets for every org configured.

  --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Role profile(s) used to determine MCP toolsets.

    Comma-separated list of role profiles. Each profile maps to a subset of MCP toolsets.
    If omitted, all available MCP toolsets are enabled.

  --target-org=myOrgAlias  Salesforce org alias or username to configure.

    Specify a single org alias or username. An MCP server entry will be added for this org.
    Omit to select from all authenticated orgs interactively.
```

_See code: [src/commands/setup-agents/mcp.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/mcp.ts)_

## `sf setup-agents review complete`

Complete a setup-agents review.

```
USAGE
  $ sf setup-agents review complete --id <value> --result approved|blocked|changes [--json] [--flags-dir <value>] [--reviewer
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--findings <value>] [--recommendation <value>]

FLAGS
  --findings=<value>
      Review findings.

  --id=<value>
      (required) Review record id.

  --recommendation=<value>
      Review recommendation.

  --result=<option>
      (required) Review outcome.
      <options: approved|blocked|changes>

  --reviewer=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|c
  pq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Profile completing the review.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Complete a setup-agents review.

  Appends an updated JSON Lines review entry to `.setup-agents/state/reviews.jsonl` with the final result.

  The result must be `approved`, `blocked`, or `changes`.

EXAMPLES
  Approve a review:

    $ sf setup-agents review complete --id setup-agents-review-1234567-abc123 --result approved --reviewer qa \
      --findings "All acceptance criteria met"

  Block a review with changes needed:

    $ sf setup-agents review complete --id setup-agents-review-1234567-abc123 --result changes --reviewer security \
      --findings "Missing input validation" --recommendation "Add gate check before status update"

FLAG DESCRIPTIONS
  --findings=<value>  Review findings.

    Summarize what was found during the review.

  --id=<value>  Review record id.

    The id of the review record to complete.

  --recommendation=<value>  Review recommendation.

    Describe the recommended next action after this review.

  --result=approved|blocked|changes  Review outcome.

    Final result of the review: `approved`, `blocked`, or `changes`.

  --reviewer=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Profile completing the review.

    The setup-agents profile acting as reviewer, stored as `setup-agents:<profile>`.
```

_See code: [src/commands/setup-agents/review/complete.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/review/complete.ts)_

## `sf setup-agents review list`

List setup-agents review records.

```
USAGE
  $ sf setup-agents review list [--json] [--flags-dir <value>] [--status pending|approved|blocked|changes] [-t <value>] [-l
    <value>]

FLAGS
  -l, --limit=<value>    [default: 20] Maximum records to show.
  -t, --task=<value>     Filter by task or issue id.
      --status=<option>  Filter by review status.
                         <options: pending|approved|blocked|changes>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List setup-agents review records.

  Reads JSON Lines review entries from `.setup-agents/state/reviews.jsonl`.

EXAMPLES
  List pending reviews:

    $ sf setup-agents review list --status pending

  List reviews for a task:

    $ sf setup-agents review list --task SA-98

FLAG DESCRIPTIONS
  -l, --limit=<value>  Maximum records to show.

    Limit the number of matching records returned from the end of the review log.

  -t, --task=<value>  Filter by task or issue id.

    Show only review records associated with the given task id.

  --status=pending|approved|blocked|changes  Filter by review status.

    Show only reviews with the given status: `pending`, `approved`, `blocked`, or `changes`.
```

_See code: [src/commands/setup-agents/review/list.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/review/list.ts)_

## `sf setup-agents review request`

Request a setup-agents review.

```
USAGE
  $ sf setup-agents review request -s <value> [--json] [--flags-dir <value>] [-t <value>] [--requester
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--reviewer
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--gate <value>] [--evidence <value>]

FLAGS
  -s, --summary=<value>
      (required) Short review summary.

  -t, --task=<value>
      Task or issue id for this review.

  --evidence=<value>
      Related evidence ids.

  --gate=<value>
      Gate or quality check names.

  --requester=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|
  cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      [default: developer] Profile requesting the review.

  --reviewer=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|c
  pq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Profile assigned to review.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Request a setup-agents review.

  Appends a JSON Lines review entry to `.setup-agents/state/reviews.jsonl` with status `pending`.

  Review records capture the requester, optional reviewer, gates, task ids, and related evidence ids.

EXAMPLES
  Request a security review for a task:

    $ sf setup-agents review request --task SA-98 --requester developer --reviewer security --gate readiness \
      --summary "Review gate: native review commands implementation"

FLAG DESCRIPTIONS
  -s, --summary=<value>  Short review summary.

    Describe what is being reviewed in one concise sentence.

  -t, --task=<value>  Task or issue id for this review.

    Associate the review with a task id such as `SA-98` or `#98`.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence record ids that support this review.

  --gate=<value>  Gate or quality check names.

    Comma-separated gate names required for this review, such as `readiness,security`.

  --requester=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Profile requesting the review.

    The setup-agents profile that is requesting the review, stored as `setup-agents:<profile>`.

  --reviewer=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Profile assigned to review.

    Optionally assign a specific setup-agents profile as reviewer.
```

_See code: [src/commands/setup-agents/review/request.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/review/request.ts)_

## `sf setup-agents status`

Summarize native setup-agents workspace state.

```
USAGE
  $ sf setup-agents status [--json] [--flags-dir <value>] [--fix]

FLAGS
  --fix  Auto-run update when stale rule files are detected.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Summarize native setup-agents workspace state.

  Reads `.setup-agents/config.json`, `.setup-agents/state/tasks.jsonl`, reviews, handoffs, and evidence to print a
  workspace health summary.

  Useful for agents and humans to check open tasks, pending reviews, blocked handoffs, and missing evidence before
  starting work.

EXAMPLES
  Show workspace status:

    $ sf setup-agents status

  Show status and auto-fix stale rule files:

    $ sf setup-agents status --fix
```

_See code: [src/commands/setup-agents/status.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/status.ts)_

## `sf setup-agents sync`

Sync workspace state to or from a shared remote target for team visibility.

```
USAGE
  $ sf setup-agents sync --remote <value> [--json] [--flags-dir <value>] [--pull] [--dry-run]

FLAGS
  --dry-run         Print what would be pushed or pulled without modifying state.
  --pull            Pull and merge remote state into local instead of pushing.
  --remote=<value>  (required) Remote target. Use 'gist' to create a new private GitHub Gist, or 'gist:<id>' to use
                    existing.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Sync workspace state to or from a shared remote target for team visibility.

  Pushes or pulls .setup-agents/state/ JSONL files to a GitHub Gist.
  Run without --pull to push. Run with --pull to merge remote state into local.

EXAMPLES
  Push state to a new private Gist:

    $ sf setup-agents sync --remote gist

  Push to existing Gist:

    $ sf setup-agents sync --remote gist:abc123

  Pull from Gist:

    $ sf setup-agents sync --remote gist:abc123 --pull
```

_See code: [src/commands/setup-agents/sync.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/sync.ts)_

## `sf setup-agents task archive`

Archive a setup-agents task.

```
USAGE
  $ sf setup-agents task archive -t <value> [--json] [--flags-dir <value>]

FLAGS
  -t, --task=<value>  (required) Task id.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Archive a setup-agents task.

  Marks a task as archived in `.setup-agents/state/tasks.jsonl`. Archived tasks are hidden from `task list` output
  unless `--status archived` is specified. Unlike delete, archive preserves the task record for audit purposes.

EXAMPLES
  Archive a task:

    $ sf setup-agents task archive --task SA-97

FLAG DESCRIPTIONS
  -t, --task=<value>  Task id.

    Id of the task to archive.
```

_See code: [src/commands/setup-agents/task/archive.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/task/archive.ts)_

## `sf setup-agents task claim`

Claim a setup-agents task.

```
USAGE
  $ sf setup-agents task claim -t <value> [--json] [--flags-dir <value>] [-r <value>] [-p
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--evidence <value>]

FLAGS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|servic
  e|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Claiming setup-agents profile.

  -r, --role=<value>
      [default: developer] Claiming role.

  -t, --task=<value>
      (required) Task id.

  --evidence=<value>
      Related evidence ids.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Claim a setup-agents task.

  Appends a claimed task state entry to `.setup-agents/state/tasks.jsonl`.

EXAMPLES
  Claim a task as the developer profile:

    $ sf setup-agents task claim --task SA-97 --profile developer

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Claiming setup-agents profile.

    Record the setup-agents profile claiming this task.

  -r, --role=<value>  Claiming role.

    Alias for a setup-agents profile owner such as `developer`, stored as `setup-agents:developer`.

  -t, --task=<value>  Task id.

    Task id to claim.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence record ids to attach while claiming.
```

_See code: [src/commands/setup-agents/task/claim.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/task/claim.ts)_

## `sf setup-agents task create`

Create a setup-agents task.

```
USAGE
  $ sf setup-agents task create -s <value> [--json] [--flags-dir <value>] [--id <value>] [-r <value>] [-p
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--mode project|advisory] [--evidence <value>]

FLAGS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|servic
  e|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Owning setup-agents profile.

  -r, --role=<value>
      Owning role for this task.

  -s, --summary=<value>
      (required) Short task summary.

  --evidence=<value>
      Related evidence ids.

  --id=<value>
      Task id.

  --mode=<option>
      Workspace mode for the task.
      <options: project|advisory>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Create a setup-agents task.

  Appends a JSON Lines task entry to `.setup-agents/state/tasks.jsonl`.

  Task records capture id, summary, status, setup-agents profile owner, timestamps, and related evidence ids.

EXAMPLES
  Create an unclaimed task:

    $ sf setup-agents task create --summary "Implement task CLI"

  Create a task owned by a profile:

    $ sf setup-agents task create --id SA-97 --profile developer --summary "Implement task CLI"

  Create an advisory task:

    $ sf setup-agents task create --mode advisory --summary "Compare implementation options"

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Owning setup-agents profile.

    Record the setup-agents profile responsible for this task.

  -r, --role=<value>  Owning role for this task.

    Alias for a setup-agents profile owner such as `developer`, stored as `setup-agents:developer`.

  -s, --summary=<value>  Short task summary.

    Describe the task in one concise sentence.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence record ids that support this task.

  --id=<value>  Task id.

    Use a specific task id instead of generating one.

  --mode=project|advisory  Workspace mode for the task.

    Record whether this task belongs to project or advisory orchestration mode.
```

_See code: [src/commands/setup-agents/task/create.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/task/create.ts)_

## `sf setup-agents task delete`

Delete a setup-agents task.

```
USAGE
  $ sf setup-agents task delete -t <value> [--json] [--flags-dir <value>] [-y]

FLAGS
  -t, --task=<value>  (required) Task id.
  -y, --yes           Skip confirmation prompt.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Delete a setup-agents task.

  Marks a task as deleted in `.setup-agents/state/tasks.jsonl`. Deleted tasks are hidden from `task list` output unless
  `--status deleted` is specified.

EXAMPLES
  Delete a task interactively:

    $ sf setup-agents task delete --task SA-97

  Delete without confirmation:

    $ sf setup-agents task delete --task SA-97 --yes

FLAG DESCRIPTIONS
  -t, --task=<value>  Task id.

    Id of the task to delete.

  -y, --yes  Skip confirmation prompt.

    Delete without prompting for confirmation (useful in scripts and non-interactive environments).
```

_See code: [src/commands/setup-agents/task/delete.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/task/delete.ts)_

## `sf setup-agents task done`

Mark a setup-agents task done.

```
USAGE
  $ sf setup-agents task done -t <value> [--json] [--flags-dir <value>] [-r <value>] [-p
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--evidence <value>] [--push-to github|jira]
    [--dry-run] [--ticket <value>]

FLAGS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|servic
  e|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      Completing setup-agents profile.

  -r, --role=<value>
      Completing role.

  -t, --task=<value>
      (required) Task id.

  --dry-run
      Print the write-back payload without sending.

  --evidence=<value>
      Related evidence ids.

  --push-to=<option>
      Push task completion to GitHub Issue or Jira ticket.
      <options: github|jira>

  --ticket=<value>
      GitHub issue number or Jira ticket ID to comment on.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Mark a setup-agents task done.

  Appends a completed task state entry to `.setup-agents/state/tasks.jsonl`.

EXAMPLES
  Mark a task done with evidence:

    $ sf setup-agents task done --task SA-97 --evidence setup-agents-evidence-1

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    Completing setup-agents profile.

    Record the setup-agents profile completing this task.

  -r, --role=<value>  Completing role.

    Alias for a setup-agents profile owner such as `developer`, stored as `setup-agents:developer`.

  -t, --task=<value>  Task id.

    Task id to mark done.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence record ids to attach while completing the task.
```

_See code: [src/commands/setup-agents/task/done.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/task/done.ts)_

## `sf setup-agents task list`

List setup-agents tasks.

```
USAGE
  $ sf setup-agents task list [--json] [--flags-dir <value>] [--status open|claimed|done] [-r <value>] [-p <value>] [--mode
    project|advisory] [-l <value>]

FLAGS
  -l, --limit=<value>    [default: 20] Maximum tasks to show.
  -p, --profile=<value>  Filter by owning setup-agents profile.
  -r, --role=<value>     Filter by owning role.
      --mode=<option>    Filter by workspace mode.
                         <options: project|advisory>
      --status=<option>  Filter by task status.
                         <options: open|claimed|done>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List setup-agents tasks.

  Reads latest task state from `.setup-agents/state/tasks.jsonl`.

EXAMPLES
  List recent tasks:

    $ sf setup-agents task list

  List claimed tasks for a profile:

    $ sf setup-agents task list --status claimed --profile developer

  List advisory tasks:

    $ sf setup-agents task list --mode advisory

FLAG DESCRIPTIONS
  -l, --limit=<value>  Maximum tasks to show.

    Limit the number of matching tasks returned from the end of the task list.

  -p, --profile=<value>  Filter by owning setup-agents profile.

    Show only tasks owned by the given setup-agents profile.

  -r, --role=<value>  Filter by owning role.

    Show only tasks owned by the given role, stored as a setup-agents profile owner.

  --mode=project|advisory  Filter by workspace mode.

    Show only tasks recorded for project or advisory orchestration mode.

  --status=open|claimed|done  Filter by task status.

    Show only tasks with status `open`, `claimed`, or `done`.
```

_See code: [src/commands/setup-agents/task/list.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/task/list.ts)_

## `sf setup-agents task update`

Update a setup-agents task.

```
USAGE
  $ sf setup-agents task update -t <value> [--json] [--flags-dir <value>] [-s <value>] [-r <value>] [-p
    developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnist
    udio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc] [--evidence <value>]

FLAGS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|servic
  e|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc
      New owner profile.

  -r, --role=<value>
      New owner role.

  -s, --summary=<value>
      New summary text.

  -t, --task=<value>
      (required) Task id.

  --evidence=<value>
      Related evidence ids.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Update a setup-agents task.

  Patches an existing task record in `.setup-agents/state/tasks.jsonl` without changing its status.

EXAMPLES
  Update a task summary:

    $ sf setup-agents task update --task SA-97 --summary "Revised scope"

  Reassign a task:

    $ sf setup-agents task update --task SA-97 --profile developer

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|ba|pm|mulesoft|ux|cgcloud|devops|qa|crma|commerce|data360|admin|sfmc|security|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc

    New owner profile.

    Replace the task owner with this setup-agents profile.

  -r, --role=<value>  New owner role.

    Alias for a setup-agents profile owner.

  -s, --summary=<value>  New summary text.

    Replace the task summary with this text.

  -t, --task=<value>  Task id.

    Id of the task to update.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence ids to attach to the task.
```

_See code: [src/commands/setup-agents/task/update.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/task/update.ts)_

## `sf setup-agents task view`

View a setup-agents task.

```
USAGE
  $ sf setup-agents task view -t <value> [--json] [--flags-dir <value>]

FLAGS
  -t, --task=<value>  (required) Task id.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  View a setup-agents task.

  Reads the latest state for a task from `.setup-agents/state/tasks.jsonl`.

EXAMPLES
  View a task:

    $ sf setup-agents task view --task SA-97

FLAG DESCRIPTIONS
  -t, --task=<value>  Task id.

    Task id to view.
```

_See code: [src/commands/setup-agents/task/view.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/task/view.ts)_

## `sf setup-agents update`

Update stale AI agent rule files to the current plugin version.

```
USAGE
  $ sf setup-agents update [--json] [--flags-dir <value>] [-y] [--doc-reference] [--fetch-refs] [-f | --dry-run |
  --check]

FLAGS
  -f, --force          Regenerate all rule files and skills from saved workspace config, regardless of version.
  -y, --yes            Skip confirmation prompt.
      --check          Check for stale files without writing changes.
      --doc-reference  Regenerate reference doc rule files (salesforce-pdf-registry.mdc) from existing config without
                       re-running setup.
      --dry-run        Preview changes without writing any files.
      --fetch-refs     Download Salesforce reference PDFs and HTML docs to .setup-agents/references/ for local agent
                       access.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Update stale AI agent rule files to the current plugin version.

  Scans the current project for rule files generated by `sf setup-agents local` and re-generates any
  files whose embedded `pluginVersion` (or `<!-- setup-agents: -->` comment) does not match the
  current plugin version.

  Detection logic:

  - `.cursor/rules/*.mdc` — checks `pluginVersion:` in frontmatter.
  - `.github/copilot-instructions.md` — checks `<!-- setup-agents: x.y.z -->` comment.
  - `AGENTS.md` — checks `<!-- setup-agents: x.y.z -->` comment.
  - `CLAUDE.md` — checks `<!-- setup-agents: x.y.z -->` comment.
  - `.a4drules/*.md` — checks `<!-- setup-agents: x.y.z -->` comment.

  Active profiles are inferred from the filenames in `.cursor/rules/` (e.g. `developer-standards.mdc`
  maps to the `developer` profile). Use `--dry-run` to preview changes without writing files.
  Files with setup-agents managed blocks update only the generated block content; user content outside
  those blocks is preserved.

EXAMPLES
  Preview which rule files are stale:

    $ sf setup-agents update --dry-run

  Update all stale files with confirmation:

    $ sf setup-agents update

  Update all stale files without prompting (CI mode):

    $ sf setup-agents update --yes

  Regenerate all rule files from saved config without re-selecting profiles:

    $ sf setup-agents update --force

FLAG DESCRIPTIONS
  -y, --yes  Skip confirmation prompt.

    Automatically confirm the update without interactive prompting.
    Useful in CI/CD pipelines or scripted environments.

  --check  Check for stale files without writing changes.

    Report stale files and whether each file can be updated through setup-agents managed blocks.
    This is intended for CI or pre-PR validation.

  --dry-run  Preview changes without writing any files.

    List all stale files that would be updated without actually modifying them.
    Useful to audit what would change before committing to an update.
```

_See code: [src/commands/setup-agents/update.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/update.ts)_

## `sf setup-agents verify`

Verify that your AI agent is reading the generated rule files.

```
USAGE
  $ sf setup-agents verify [--json] [--flags-dir <value>] [--rules
    cursor|vscode|codex|claude|agentforce|windsurf|jetbrains] [--profile <value>]

FLAGS
  --profile=<value>                                                 Profiles to include in the probe (comma-separated).
  --rules=cursor|vscode|codex|claude|agentforce|windsurf|jetbrains  AI tool to verify.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Verify that your AI agent is reading the generated rule files.

  Generates a probe prompt tailored to the active tool and profiles in this workspace.
  Paste it into your AI agent — if the agent responds correctly, the rules are being applied.

  Does not invoke the agent automatically. Prints the probe prompt and instructions.

EXAMPLES
  Print a probe prompt for the active workspace:

    $ sf setup-agents verify

  JSON output for scripting:

    $ sf setup-agents verify --json
```

_See code: [src/commands/setup-agents/verify.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/verify.ts)_

## `sf setup-agents workflow benchmark`

Compute actual delivery time vs. declared estimates for completed workflow runs.

```
USAGE
  $ sf setup-agents workflow benchmark [--json] [--flags-dir <value>] [-s <value>] [--summary]

FLAGS
  -s, --story=<value>  Story id to benchmark.
      --summary        Print summary table for all stories with estimates.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Compute actual delivery time vs. declared estimates for completed workflow runs.

  Joins declared estimates (from `sf setup-agents workflow estimate`) with
  completed workflow run records to compute actual cycle time, savings percentage
  vs. solo delivery, and savings percentage vs. unguided AI delivery.

  Actual cycle time is derived automatically from the run's phase timestamps —
  no manual input required after the estimate is declared.

EXAMPLES
  Benchmark a single completed story:

    $ sf setup-agents workflow benchmark --story US-42

  Summary table of all stories:

    $ sf setup-agents workflow benchmark --summary

FLAG DESCRIPTIONS
  -s, --story=<value>  Story id to benchmark.

    Single story report. Prints sizing, estimates, actual days, savings percentages,
    QA iterations, and evidence count.

  --summary  Print summary table for all stories with estimates.

    Prints a sorted table of every story that has a declared estimate, with aggregate
    averages at the bottom. Stories without a completed run show status `pending`.
```

_See code: [src/commands/setup-agents/workflow/benchmark.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/benchmark.ts)_

## `sf setup-agents workflow clarify`

Open a clarification question from a developer or qa phase.

```
USAGE
  $ sf setup-agents workflow clarify --run <value> --from developer|qa --to po|architect --question <value> [--json] [--flags-dir
    <value>]

FLAGS
  --from=<option>     (required) Role opening the clarification.
                      <options: developer|qa>
  --question=<value>  (required) Clarification question text.
  --run=<value>       (required) Workflow run id.
  --to=<option>       (required) Role receiving the clarification.
                      <options: po|architect>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Open a clarification question from a developer or qa phase.

  Suspends the active developer or qa phase with status `awaiting_clarification` and records a clarification question
  directed to a PO or architect.

  Appends a JSON Lines clarification entry to `.setup-agents/state/clarifications.jsonl` and updates the workflow run
  record in `.setup-agents/state/workflow-runs.jsonl`.

  Use `setup-agents workflow clarify-respond` to record the answer and resume the phase.

EXAMPLES
  Open a clarification from developer to architect:

    $ sf setup-agents workflow clarify --run wf-123 --from developer --to architect --question "Should we use batch \
      or queueable for this async job?"

  Open a clarification from qa to po:

    $ sf setup-agents workflow clarify --run wf-123 --from qa --to po --question "Is field X required in the \
      acceptance criteria?"

FLAG DESCRIPTIONS
  --from=developer|qa  Role opening the clarification.

    The phase role requesting clarification. Must be `developer` or `qa`.

  --question=<value>  Clarification question text.

    The question to be answered before the phase can continue.

  --run=<value>  Workflow run id.

    The id of the active workflow run containing the phase to suspend.

  --to=po|architect  Role receiving the clarification.

    The role that should answer the clarification. Use `po` for Product Owner or `architect` for Architect.
```

_See code: [src/commands/setup-agents/workflow/clarify.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/clarify.ts)_

## `sf setup-agents workflow clarify-list`

List clarifications for a workflow run.

```
USAGE
  $ sf setup-agents workflow clarify-list --run <value> [--json] [--flags-dir <value>]

FLAGS
  --run=<value>  (required) Workflow run id.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List clarifications for a workflow run.

  Reads `.setup-agents/state/clarifications.jsonl` and lists all clarification records for the given run id, showing
  both open and answered entries.

EXAMPLES
  List all clarifications for a run:

    $ sf setup-agents workflow clarify-list --run wf-123

  List clarifications as JSON:

    $ sf setup-agents workflow clarify-list --run wf-123 --json

FLAG DESCRIPTIONS
  --run=<value>  Workflow run id.

    The id of the workflow run whose clarifications should be listed.
```

_See code: [src/commands/setup-agents/workflow/clarify-list.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/clarify-list.ts)_

## `sf setup-agents workflow clarify-respond`

Record an answer to an open clarification and resume the suspended phase.

```
USAGE
  $ sf setup-agents workflow clarify-respond --run <value> --clarification <value> --answer <value> [--json]
  [--flags-dir <value>]

FLAGS
  --answer=<value>         (required) Answer text.
  --clarification=<value>  (required) Clarification id.
  --run=<value>            (required) Workflow run id.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Record an answer to an open clarification and resume the suspended phase.

  Appends an answered clarification entry to `.setup-agents/state/clarifications.jsonl` and transitions the phase status
  from `awaiting_clarification` back to `running` in `.setup-agents/state/workflow-runs.jsonl`.

  After responding, use `setup-agents workflow run --resume <runId>` to continue execution from the suspended phase.

EXAMPLES
  Respond to an open clarification:

    $ sf setup-agents workflow clarify-respond --run wf-123 --clarification sa-clarification-456 --answer "Use \
      Queueable — it supports chaining and avoids heap limits."

FLAG DESCRIPTIONS
  --answer=<value>  Answer text.

    The response to the clarification question.

  --clarification=<value>  Clarification id.

    The id of the clarification record to answer.

  --run=<value>  Workflow run id.

    The id of the workflow run that contains the suspended phase.
```

_See code: [src/commands/setup-agents/workflow/clarify-respond.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/clarify-respond.ts)_

## `sf setup-agents workflow estimate`

Record a delivery baseline estimate for a story before the workflow starts.

```
USAGE
  $ sf setup-agents workflow estimate -s <value> --sizing xs|s|m|l|xl --solo-days <value> --ai-unguided-days <value> [--json]
    [--flags-dir <value>] [--ai-guided-days <value>] [--confidence low|medium|high] [--declared-by <value>]
    [--ignore-history]

FLAGS
  -s, --story=<value>             (required) Story or backlog item id.
      --ai-guided-days=<value>    Estimated days with setup-agents guided workflow.
      --ai-unguided-days=<value>  (required) Estimated days with unguided AI (no orchestration).
      --confidence=<option>       [default: medium] Confidence level in these estimates.
                                  <options: low|medium|high>
      --declared-by=<value>       [default: pm] Profile declaring the estimate.
      --ignore-history            Skip historical benchmark data when producing the estimate.
      --sizing=<option>           (required) Story size label.
                                  <options: xs|s|m|l|xl>
      --solo-days=<value>         (required) Estimated days a developer would take working alone.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Record a delivery baseline estimate for a story before the workflow starts.

  Appends an estimate record to `.setup-agents/state/estimates.jsonl` with the
  declared solo, AI-unguided, and sizing baselines. Once the workflow run
  completes, `sf setup-agents workflow benchmark` uses these values to compute
  actual vs. baseline delta automatically.

EXAMPLES
  Record a medium-sized story baseline before starting the workflow:

    $ sf setup-agents workflow estimate --story US-42 --sizing m --solo-days 3 --ai-unguided-days 2

  Record with explicit confidence and declarer:

    $ sf setup-agents workflow estimate --story US-42 --sizing l --solo-days 5 --ai-unguided-days 3 --confidence \
      high --declared-by architect

FLAG DESCRIPTIONS
  -s, --story=<value>  Story or backlog item id.

    The story id used in `sf setup-agents workflow run --story <id>` (e.g. `US-42`).

  --ai-guided-days=<value>  Estimated days with setup-agents guided workflow.

    Optional. Predicted delivery time when using setup-agents with profiles and
    orchestration. Used as the denominator for `vsAiGuidedPct` — the ROI signal
    that shows how actual performance compares to the guided estimate. Can be
    provided at initial declaration or as a backfill on existing estimates by
    re-running this command with only this flag (other flags are re-read from the
    last record).

  --ai-unguided-days=<value>  Estimated days with unguided AI (no orchestration).

    Baseline with a plain AI assistant but without setup-agents orchestration. Used
    as the denominator for `vsAiUnguidedPct` — the signal that measures the specific
    value added by the workflow engine.

  --confidence=low|medium|high  Confidence level in these estimates.

    How confident you are in the declared baselines. Options: `low` `medium` `high`.
    Defaults to `medium`.

  --declared-by=<value>  Profile declaring the estimate.

    The setup-agents profile making the declaration (e.g. `pm`, `architect`).
    Defaults to `pm`.

  --sizing=xs|s|m|l|xl  Story size label.

    T-shirt size for this story. Options: `xs` `s` `m` `l` `xl`.

  --solo-days=<value>  Estimated days a developer would take working alone.

    Baseline without any AI assistance. Used as the denominator for `vsSoloPct` in
    the benchmark report.
```

_See code: [src/commands/setup-agents/workflow/estimate.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/estimate.ts)_

## `sf setup-agents workflow execute`

Execute workflow phases by spawning an AI runtime for each phase.

```
USAGE
  $ sf setup-agents workflow execute -s <value> [--json] [--flags-dir <value>] [--runtime auto|claude|cursor|codex] [--from-phase
    pm|ba|architect|ux|developer|security-review|qa|release] [--dry-run] [--gates none|phase|all] [--max-iterations
    <value>] [--max-phase-minutes <value>] [--max-agents <value>]

FLAGS
  -s, --story=<value>              (required) Story or backlog item id.
      --dry-run                    Print what would be executed per phase without running.
      --from-phase=<option>        Resume execution from this phase.
                                   <options: pm|ba|architect|ux|developer|security-review|qa|release>
      --gates=<option>             [default: phase] Gate approval mode.
                                   <options: none|phase|all>
      --max-agents=<value>         [default: 5] Maximum number of sub-agents the runtime may spawn per phase.
      --max-iterations=<value>     [default: 5] Maximum QA→Developer loop iterations.
      --max-phase-minutes=<value>  [default: 60] Maximum minutes a single phase may run before it is killed.
      --runtime=<option>           [default: auto] AI runtime to use for phase execution.
                                   <options: auto|claude|cursor|codex>

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Execute workflow phases by spawning an AI runtime for each phase.

  Delegates each phase of the story workflow to an AI runtime (claude, cursor, or codex).
  Unlike `workflow run`, this command does not manage state records — it simply spawns the
  runtime process and streams its output to the terminal. State tracking is the runtime's
  responsibility via the sub-agent protocol.

  Phase sequence: PM → BA → Architect → Developer → QA → Release

  The `--runtime` flag selects which AI CLI to invoke:

  - `auto` — detects the first available runtime in order: claude, cursor, codex (default).
  - `claude` — uses the `claude` CLI with `--system-prompt` and `--print`.
  - `cursor` — uses the `cursor agent --print` CLI (requires `CURSOR_API_KEY`).
  - `codex` — uses the `codex` CLI with `--instructions`.

  The `--from-phase` flag resumes execution from a specific phase, skipping earlier ones.

  The `--gates` flag controls when to pause between phases:

  - `none` — run all phases sequentially without pausing.
  - `phase` — pause at BA→Architect and QA→Release boundaries (default).
  - `all` — pause at every phase boundary.

  Use `--dry-run` to preview the command that would be run for each phase without executing.

EXAMPLES
  Execute all phases with auto-detected runtime:

    $ sf setup-agents workflow execute --story SA-102

  Execute with Claude and no gate pauses:

    $ sf setup-agents workflow execute --story SA-102 --runtime claude --gates none

  Resume from the developer phase after a gate pause:

    $ sf setup-agents workflow execute --story SA-102 --from-phase developer

  Preview the execution plan without running anything:

    $ sf setup-agents workflow execute --story SA-102 --dry-run

FLAG DESCRIPTIONS
  -s, --story=<value>  Story or backlog item id.

    The story id passed to the runtime prompt for each phase, e.g. `SA-102` or `#102`.

  --dry-run  Print what would be executed per phase without running.

    Shows the resolved runtime, rule file path, and full command for each phase
    without spawning any processes.

  --from-phase=pm|ba|architect|ux|developer|security-review|qa|release  Resume execution from this phase.

    Skip all phases before this one and begin execution here.
    Useful when resuming after a gate pause or a failed phase.

  --gates=none|phase|all  Gate approval mode.

    Controls where execution pauses for human review: `none` (no pauses),
    `phase` (pause at BA→Architect and QA→Release, default), or `all` (every transition).

  --max-agents=<value>  Maximum number of sub-agents the runtime may spawn per phase.

    Passed to the runtime CLI as --max-turns (claude/cursor) or --max-agents (codex).
    Prevents sub-agent fan-out that can exhaust memory in CI environments. Default: 5. Min: 1.

  --max-iterations=<value>  Maximum QA→Developer loop iterations.

    Maximum number of times the QA→Developer loop can repeat before the run is blocked.
    Defaults to 5. Must be at least 1.

  --max-phase-minutes=<value>  Maximum minutes a single phase may run before it is killed.

    If a spawned runtime process does not exit within this many minutes, it is sent SIGTERM
    and the phase is marked failed with exit code 124 (timeout). Default: 60. Min: 1.

  --runtime=auto|claude|cursor|codex  AI runtime to use for phase execution.

    Select which AI CLI to invoke: `auto` (detect), `claude`, `cursor`, or `codex`.
    `auto` checks PATH in order: claude → cursor → codex and uses the first found.
```

_See code: [src/commands/setup-agents/workflow/execute.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/execute.ts)_

## `sf setup-agents workflow gate`

Open a mid-phase gate to request input from another role.

```
USAGE
  $ sf setup-agents workflow gate --run <value> --phase <value> --from <value> --to <value> -s <value> [--json] [--flags-dir
    <value>] [--gate <value>]

FLAGS
  -s, --summary=<value>  (required) Short description of what is needed.
      --from=<value>     (required) Profile requesting the consultation.
      --gate=<value>     Gate label.
      --phase=<value>    (required) Phase that is opening the gate.
      --run=<value>      (required) Workflow run id.
      --to=<value>       (required) Profile that must respond.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Open a mid-phase gate to request input from another role.

  Registers a review request mid-phase (e.g. developer requesting sizing validation from architect,
  or QA requesting criteria clarification from the product owner) without requiring a phase
  transition. The gate is attached to the active phase's `reviewIds` list and persisted in
  `.setup-agents/state/reviews.jsonl`.

  Use `sf setup-agents review complete` to resolve the gate, then resume the run with
  `sf setup-agents workflow run --resume`.

EXAMPLES
  Developer requests sizing validation from architect:

    $ sf setup-agents workflow gate --run wf-123 --phase developer --from developer --to architect --gate \
      "developer:sizing→architect" --summary "Story points ambiguous — is this a 5 or 8?"

  QA requests criteria clarification from product owner:

    $ sf setup-agents workflow gate --run wf-123 --phase qa --from qa --to ba --gate "qa:criteria→ba" --summary \
      "Acceptance criterion 3 is ambiguous for edge case X"

FLAG DESCRIPTIONS
  -s, --summary=<value>  Short description of what is needed.

    Describe the question or decision that requires input from the other role.

  --from=<value>  Profile requesting the consultation.

    The setup-agents profile that needs the input, e.g. `developer`.

  --gate=<value>  Gate label.

    Semantic label for this gate, e.g. `developer:sizing→architect` or `qa:criteria→ba`.
    Defaults to `<from>→<to>`.

  --phase=<value>  Phase that is opening the gate.

    The currently active phase requesting consultation, e.g. `developer`.

  --run=<value>  Workflow run id.

    The run id returned by `sf setup-agents workflow run`. Use `sf setup-agents workflow pending`
    to find active run ids.

  --to=<value>  Profile that must respond.

    The setup-agents profile that will provide input, e.g. `architect`.
```

_See code: [src/commands/setup-agents/workflow/gate.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/gate.ts)_

## `sf setup-agents workflow pending`

List workflow runs waiting for gate approval.

```
USAGE
  $ sf setup-agents workflow pending [--json] [--flags-dir <value>]

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List workflow runs waiting for gate approval.

  Reads `.setup-agents/state/workflow-runs.jsonl` and shows all runs with
  status `paused`, the gate that blocked them, and the exact commands to
  approve the review and resume execution.

EXAMPLES
  Check what needs your attention:

    $ sf setup-agents workflow pending
```

_See code: [src/commands/setup-agents/workflow/pending.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/pending.ts)_

## `sf setup-agents workflow playbooks`

List phase-to-playbook mappings for the current workspace.

```
USAGE
  $ sf setup-agents workflow playbooks [--json] [--flags-dir <value>] [--instructions-dir <value>] [--scaffold] [--phase <value>]
    [--dry-run]

FLAGS
  --dry-run                   Preview scaffold output without writing files.
  --instructions-dir=<value>  [default: .setup-agents/playbooks] Directory to resolve playbooks from.
  --phase=<value>             Scaffold only the specified phase.
  --scaffold                  Generate stub files for missing playbooks.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  List phase-to-playbook mappings for the current workspace.

  Shows which generator playbooks are mapped to each workflow phase and
  whether each file exists on disk. Missing playbooks are non-blocking —
  the workflow engine will emit a warning and continue without them.

  Run `sf setup-agents local` to generate missing playbooks for the
  profiles active in this workspace.

EXAMPLES
  Show playbook mapping for the current workspace:

    $ sf setup-agents workflow playbooks

  Show mapping for a custom instructions directory:

    $ sf setup-agents workflow playbooks --instructions-dir .cursor/rules/workflows

FLAG DESCRIPTIONS
  --instructions-dir=<value>  Directory to resolve playbooks from.

    Path relative to the workspace root where generator playbooks are stored.
    Defaults to `.a4drules/workflows`. Override for non-cursor/agentforce
    targets if playbooks are stored elsewhere.

  --phase=<value>  Scaffold only the specified phase.

    Limits --scaffold to a single phase (e.g. developer, qa, release).

  --scaffold  Generate stub files for missing playbooks.

    Writes default playbook stubs into the instructions directory for every missing playbook. Existing files are never
    overwritten.
```

_See code: [src/commands/setup-agents/workflow/playbooks.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/playbooks.ts)_

## `sf setup-agents workflow release-check`

Run static-analysis release checks and record evidence artifacts.

```
USAGE
  $ sf setup-agents workflow release-check --task <value> [--json] [--flags-dir <value>] [--dry-run] [--checks <value>]

FLAGS
  --checks=<value>  Comma-separated list of checks to run.
  --dry-run         Skip all checks and exit zero.
  --task=<value>    (required) Task or story id to associate evidence with.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Run static-analysis release checks and record evidence artifacts.

  Executes a suite of static-analysis checks before closing a release:

  - **npm-audit** — dependency vulnerability scan (blocking on high/critical CVEs)
  - **knip** — dead-code detection (advisory only)
  - **coverage** — test coverage report (advisory only)
  - **secret-scan** — secret / credential leak detection (blocking)

  Each check result is recorded as an evidence artifact in
  `.setup-agents/state/evidence.jsonl`. The command exits non-zero when any
  blocking check fails.

  Use `--dry-run` to skip all checks (useful for previewing the workflow phase graph).

EXAMPLES
  Run all release checks for story SA-110:

    $ sf setup-agents workflow release-check --task SA-110

  Run only the security-related checks:

    $ sf setup-agents workflow release-check --task SA-110 --checks npm-audit,secret-scan

  Dry run (skip all checks):

    $ sf setup-agents workflow release-check --task SA-110 --dry-run

  Emit JSON report:

    $ sf setup-agents workflow release-check --task SA-110 --json

FLAG DESCRIPTIONS
  --checks=<value>  Comma-separated list of checks to run.

    Override the default set of checks. Valid values: npm-audit, knip, coverage, secret-scan.
    Defaults to all checks.

  --dry-run  Skip all checks and exit zero.

    When set, no tools are invoked and all checks are reported as skipped.
    Useful when previewing the release phase in a dry-run workflow run.

  --task=<value>  Task or story id to associate evidence with.

    Evidence artifacts created by each check will reference this task id,
    e.g. `SA-110` or the workflow phase task id.
```

_See code: [src/commands/setup-agents/workflow/release-check.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/release-check.ts)_

## `sf setup-agents workflow rollback`

Roll back a workflow run to a prior phase.

```
USAGE
  $ sf setup-agents workflow rollback --run <value> --phase pm|ba|architect|ux|developer|security-review|qa|release [--json]
    [--flags-dir <value>] [--reason <value>]

FLAGS
  --phase=<option>  (required) Phase to roll back to (inclusive).
                    <options: pm|ba|architect|ux|developer|security-review|qa|release>
  --reason=<value>  Short reason for the rollback.
  --run=<value>     (required) Workflow run id to roll back.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Roll back a workflow run to a prior phase.

  Resets a workflow run to a prior phase so it can be re-executed from that point.
  All phase records after the target phase are removed and the run status is set back
  to `running`. The rollback is persisted as an append to `workflow-runs.jsonl`.

  Use when a phase produced incorrect output and needs to be redone, or when a gate
  review determined that an earlier phase must be revisited.

EXAMPLES
  Roll back to the developer phase because QA found a regression:

    $ sf setup-agents workflow rollback --run wf-123 --phase developer --reason "QA found a regression in the SOQL \
      bulkification fix"

  Roll back to architect after BA identified a missing acceptance criterion:

    $ sf setup-agents workflow rollback --run wf-123 --phase architect --reason "Missing AC for error state — needs \
      architect re-design"

FLAG DESCRIPTIONS
  --phase=pm|ba|architect|ux|developer|security-review|qa|release  Phase to roll back to (inclusive).

    All phases from this phase onward are reset. The run will re-execute from this phase
    when `sf setup-agents workflow run --resume` is invoked.

  --reason=<value>  Short reason for the rollback.

    Free-text explanation recorded on the run record. Used for audit and sprint retrospectives.

  --run=<value>  Workflow run id to roll back.

    The run id returned by `sf setup-agents workflow run`. Use `sf setup-agents workflow pending`
    to list active or paused runs.
```

_See code: [src/commands/setup-agents/workflow/rollback.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/rollback.ts)_

## `sf setup-agents workflow run`

Scaffold and orchestrate a multi-phase story workflow (state records only — no AI invoked).

```
USAGE
  $ sf setup-agents workflow run -s <value> [--json] [--flags-dir <value>] [--gates none|phase|all] [--max-iterations <value>]
    [--profiles <value>] [--resume <value>] [--from-phase pm|ba|architect|ux|developer|security-review|qa|release]
    [--qa-result pass|fail] [--dry-run] [--instructions-dir <value>] [--push-to github|jira] [--ticket <value>]

FLAGS
  -s, --story=<value>             (required) Story or backlog item id.
      --dry-run                   Print the planned phase graph without executing.
      --from-phase=<option>       Start the pipeline from a specific phase, skipping all prior phases.
                                  <options: pm|ba|architect|ux|developer|security-review|qa|release>
      --gates=<option>            [default: phase] Gate approval mode.
                                  <options: none|phase|all>
      --instructions-dir=<value>  [default: .setup-agents/playbooks] Directory to resolve playbooks from.
      --max-iterations=<value>    [default: 5] Maximum Dev↔QA loop iterations.
      --profiles=<value>          Override active profiles for this run.
      --push-to=<option>          Push phase completion comments to GitHub Issue or Jira ticket.
                                  <options: github|jira>
      --qa-result=<option>        QA result for this resume.
                                  <options: pass|fail>
      --resume=<value>            Resume a paused workflow run.
      --ticket=<value>            GitHub issue number or Jira ticket ID to comment on.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Scaffold and orchestrate a multi-phase story workflow (state records only — no AI invoked).

  Creates orchestration state for a story lifecycle across phases:

  PM → BA/PO → Architect → UX? → Developer ↔ QA (loop) → Release

  **This command is an orchestration scaffold.** It creates task records, records handoffs,
  and pauses at gate transitions. No AI runtime is invoked. Total elapsed time is typically
  under 5 seconds because no work is executed.

  To dispatch work to an AI runtime (Claude, Codex, etc.), use:

  sf setup-agents workflow execute --runtime claude --story <id>

  Each phase creates a native task, claims it, records evidence, and creates a handoff
  to the next role. Gate transitions create a review request and pause until completed
  via `sf setup-agents review complete`.

  The `--gates` flag controls gate behavior:

  - `none` — all gates auto-approved.
  - `phase` — human approval at BA→Architect and QA→Release boundaries (default).
  - `all` — human approval at every phase transition.

  Run state is persisted to `.setup-agents/state/workflow-runs.jsonl`.
  Resume a paused run after approving the gate review with `--resume <run-id>`.

EXAMPLES
  Run with default phase gates:

    $ sf setup-agents workflow run --story SA-102

  Fully autonomous run (no human gates):

    $ sf setup-agents workflow run --story SA-102 --gates none

  Supervised run (gate at every transition):

    $ sf setup-agents workflow run --story SA-102 --gates all --max-iterations 3

  Preview without executing:

    $ sf setup-agents workflow run --story SA-102 --dry-run

  Resume after approving a gate review:

    $ sf setup-agents workflow run --story SA-102 --resume wf-1234567-abc1

  Start at developer phase (work already in progress):

    $ sf setup-agents workflow run --story PHP-313 --from-phase developer

  Start at QA phase with immediate pass result:

    $ sf setup-agents workflow run --story PHP-313 --from-phase qa --qa-result pass

  Resume a run but force restart from QA (overrides auto-detected phase):

    $ sf setup-agents workflow run --story PHP-313 --resume wf-1234567-abc1 --from-phase qa

FLAG DESCRIPTIONS
  -s, --story=<value>  Story or backlog item id.

    The story id to track throughout the workflow, e.g. `SA-102` or `#102`.

  --dry-run  Print the planned phase graph without executing.

    Show which phases will run, which gates will fire, and the handoff chain — without creating any records.

  --from-phase=pm|ba|architect|ux|developer|security-review|qa|release

    Start the pipeline from a specific phase, skipping all prior phases.

    Creates a new run with upstream phases marked as skipped and begins execution at the specified phase. Use this when
    work is already in progress (e.g. implementation started) to avoid duplicating upstream tasks.

  --gates=none|phase|all  Gate approval mode.

    Controls where human approval is required: `none` (fully autonomous),
    `phase` (gate at BA→Architect and QA→Release, default), or `all` (every transition).

  --instructions-dir=<value>  Directory to resolve playbooks from.

    Path relative to the workspace root where playbook files are stored.
    Defaults to `.setup-agents/playbooks` (generated automatically by `sf setup-agents local`).
    Override to point at a custom directory.

  --max-iterations=<value>  Maximum Dev↔QA loop iterations.

    Stop the Dev↔QA bug-fix loop after this many QA failures. Default: 5.

  --profiles=<value>  Override active profiles for this run.

    Comma-separated profile ids to activate for this workflow run.
    Defaults to profiles in `.setup-agents/config.json`.

  --qa-result=pass|fail  QA result for this resume.

    Report the QA outcome when resuming after a QA phase: `pass` to proceed to
    release, `fail` to return to developer for bug fixes. Required when resuming
    a run that is in the QA phase. Omitting it defaults to `pass`.

  --resume=<value>  Resume a paused workflow run.

    Resume execution of a paused workflow run after a gate review was approved.
    Provide the run id returned by the original invocation.
```

_See code: [src/commands/setup-agents/workflow/run.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/run.ts)_

## `sf setup-agents workflow sprint close`

Close a sprint and compute velocity metrics.

```
USAGE
  $ sf setup-agents workflow sprint close --sprint <value> --committed-points <value> [--json] [--flags-dir <value>]

FLAGS
  --committed-points=<value>  (required) Story points committed at sprint planning.
  --sprint=<value>            (required) Sprint identifier to close.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Close a sprint and compute velocity metrics.

  Appends a sprint close record to `.setup-agents/state/sprints.jsonl`.
  Reads all estimates declared within the sprint window to compute actual points
  delivered, velocity percentage vs committed, and average savings vs solo / vs
  unguided AI baselines. Also runs bias detection and writes auto-lessons to
  `.setup-agents/state/lessons.jsonl` when a role shows >30% bias in the same
  direction for 3+ stories.

EXAMPLES
  Close sprint SP-12 with 8 committed points:

    $ sf setup-agents workflow sprint close --sprint SP-12 --committed-points 8

FLAG DESCRIPTIONS
  --committed-points=<value>  Story points committed at sprint planning.

    The number of story points the team committed to deliver in this sprint.
    Used as the baseline denominator for velocity percentage.

  --sprint=<value>  Sprint identifier to close.

    Must match the id used in `sf setup-agents workflow sprint start`.
```

_See code: [src/commands/setup-agents/workflow/sprint/close.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/sprint/close.ts)_

## `sf setup-agents workflow sprint start`

Start a new sprint and record its capacity window.

```
USAGE
  $ sf setup-agents workflow sprint start --sprint <value> --start-date <value> --end-date <value> --capacity <value> [--json]
    [--flags-dir <value>]

FLAGS
  --capacity=<value>    (required) Team capacity in days.
  --end-date=<value>    (required) Sprint end date (YYYY-MM-DD).
  --sprint=<value>      (required) Sprint identifier.
  --start-date=<value>  (required) Sprint start date (YYYY-MM-DD).

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Start a new sprint and record its capacity window.

  Appends a sprint start record to `.setup-agents/state/sprints.jsonl` with the
  declared sprint id, date range, and capacity in days. Run this before stories
  are delivered to anchor the sprint window for velocity calculation.

EXAMPLES
  Start sprint SP-12 with a two-week window and 10 capacity days:

    $ sf setup-agents workflow sprint start --sprint SP-12 --start-date 2026-05-05 --end-date 2026-05-16 --capacity \
      10

FLAG DESCRIPTIONS
  --capacity=<value>  Team capacity in days.

    Total available developer-days for this sprint. Used as denominator when
    computing velocity percentage.

  --end-date=<value>  Sprint end date (YYYY-MM-DD).

    ISO date when the sprint is expected to close.

  --sprint=<value>  Sprint identifier.

    Unique id for this sprint (e.g. `SP-12`, `2026-Q2-S1`).

  --start-date=<value>  Sprint start date (YYYY-MM-DD).

    ISO date when the sprint begins. Stories estimated after this date are
    associated with the sprint in `workflow sprint close`.
```

_See code: [src/commands/setup-agents/workflow/sprint/start.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/sprint/start.ts)_

## `sf setup-agents workflow sprint velocity`

Print sprint velocity trend table.

```
USAGE
  $ sf setup-agents workflow sprint velocity [--json] [--flags-dir <value>] [--limit <value>]

FLAGS
  --limit=<value>  [default: 5] Number of recent sprints to show.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Print sprint velocity trend table.

  Reads closed sprint records from `.setup-agents/state/sprints.jsonl` and
  prints a table showing Sprint, Committed points, Actual points, Velocity%,
  AvgVsSolo, and AvgVsAI for the last N sprints. Use `--json` to get
  machine-readable output.

EXAMPLES
  Show velocity for the last 5 sprints:

    $ sf setup-agents workflow sprint velocity

  Show last 10 sprints:

    $ sf setup-agents workflow sprint velocity --limit 10

  Machine-readable output:

    $ sf setup-agents workflow sprint velocity --json

FLAG DESCRIPTIONS
  --limit=<value>  Number of recent sprints to show.

    Limits the output to the N most recent closed sprints. Defaults to 5.
```

_See code: [src/commands/setup-agents/workflow/sprint/velocity.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/sprint/velocity.ts)_

## `sf setup-agents workflow telemetry`

Show AI effort classification breakdown for delivered workflow phases.

```
USAGE
  $ sf setup-agents workflow telemetry [--json] [--flags-dir <value>] [-s <value>]

FLAGS
  -s, --story=<value>  Story id to scope the report to.

GLOBAL FLAGS
  --flags-dir=<value>  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Show AI effort classification breakdown for delivered workflow phases.

  Reads recorded effort-estimate records (written automatically when phases close
  via `sf setup-agents workflow run`) and reports minutes by autonomy mode:

  - `ai_autonomous` — agent completed phase with no gate
  - `ai_supervised` — agent completed phase, gate review was required
  - `ai_calibration_baseline` — estimate declared without active rules (baseline)
  - `human_manual` — human wrote deliverable directly
  - `human_review` — human approved a gate, no AI authorship

  Use `--story <id>` to scope the report to a single story, or omit to aggregate
  across all recorded phases.

EXAMPLES
  Show effort breakdown for a single story:

    $ sf setup-agents workflow telemetry --story US-42

  Show aggregated effort across all stories:

    $ sf setup-agents workflow telemetry

FLAG DESCRIPTIONS
  -s, --story=<value>  Story id to scope the report to.

    Filter effort records by story id. Omit to aggregate all stories.
```

_See code: [src/commands/setup-agents/workflow/telemetry.ts](https://github.com/jterrats/setup-agents/blob/v2.8.0/src/commands/setup-agents/workflow/telemetry.ts)_

<!-- commandsstop -->

---

## Build

### Local Development

```sh
# Clone and install
git clone https://github.com/jterrats/setup-agents.git
cd setup-agents
npm install

# Compile
npx tsc -p .

# Link for local testing
sf plugins link .
sf setup-agents local
```

### Running Tests

```sh
# Unit tests (225 specs)
node --loader ts-node/esm --no-warnings=ExperimentalWarning \
  ./node_modules/mocha/bin/mocha.js "test/**/*.test.ts"

# End-to-end tests (requires sf CLI in PATH)
npm run test:e2e

# Full suite (lint + compile + tests)
npm test
```

### Extension Development

```sh
cd extensions/vscode-setup-agents-ui
npm install && npm run build

# E2E tests (27 Playwright specs)
npm run test:e2e

# Generate demo GIFs (requires ffmpeg)
npm run demo
```

### Package Validation Before Publish

```sh
# Build from a clean state
yarn clean-all
yarn build

# Validate npm tarball includes compiled commands/profiles
npm pack --dry-run
```

Confirm the dry-run output includes at least:

- `lib/commands/setup-agents/local.js`
- `lib/commands/setup-agents/mcp.js`
- `lib/commands/setup-agents/update.js`
- `lib/profiles/index.js`

---

## Contributing

1. Fork the repository
2. Create a branch: `git checkout -b feature/my-feature`
3. Make your changes and add tests
4. Run `npm test` to ensure everything passes
5. Open a pull request on [GitHub](https://github.com/jterrats/setup-agents)

Please open an [issue](https://github.com/jterrats/setup-agents/issues) before starting work on large features.

---

## License

Apache-2.0 — see [LICENSE.txt](LICENSE.txt).

---

<div align="center">
  Built by <strong>Jaime Terrats</strong> · <a href="https://github.com/jterrats/setup-agents">GitHub</a>
  <br>
  <sub>This is a personal open-source project, not an official Salesforce product.</sub>
</div>
