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

### Workspace authorization

Successful OTP authorization is local to the OS user and stored as a versioned SHA-256 hash of the resolved workspace path. Only an activation timestamp is persisted—never an OTP, authorization code, email address, or bearer token. Path identity is intentional: replacing a checkout or worktree at the same path remains authorized. To reset that authorization, run `sf setup-agents auth revoke` from that workspace (or provide `--target-dir <workspace>`). Authorization updates and legacy migration are serialized across processes; a busy state fails closed.

### What agents get

- **37 profiles** — 7 core roles (Developer, Architect, SA, PM, UX, QA, Release Manager) plus 30 Salesforce product/industry specializations (MuleSoft, CGCloud, CRMA, Commerce, Data Cloud, SFMC, Service, CPQ, OmniStudio, FSL, FSC, AI/Agentforce, Slack, Tableau, Experience Cloud, 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). Product profiles fuse into whichever role profile is selected alongside them when a role-specific fragment exists (see CGCloud), or generate standalone when selected alone — run `sf setup-agents local --help` for the exact current list
- **Workflow engine** — deterministic multi-phase pipeline with gates, QA loop, and resume
- **Opt-in autonomous verification** — `workflow run --autonomous` uses registered verifier contracts, run/iteration/source-digest evidence, selected/excluded/blocked test lanes, a five-attempt cap, and a two-no-progress stop; manual mode remains the default and human architecture/release gates remain mandatory
- **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`

Autonomous workflow `GO` is a release-readiness recommendation, not approval or authority to
merge, push, publish, deploy, or release. The deterministic autonomous execution seam is for tests
only; production uses the configured delegated provider, and unavailable required providers or
test environments are reported as blocked rather than passed. Rollback preserves the versioned
run and its evidence so operators can disable new autonomous starts without erasing audit history.

---

## 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 the [Workflow Commands](https://setup-agents.pages.dev/workflow) page on the docs site 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=".github/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=".github/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["agent-rules-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`, `salesforce-pdf-registry.mdc` |
| **VS Code**    | `.github/copilot-instructions.md`, `.vscode/extensions.json`                                                                                         |
| **Codex**      | `AGENTS.md`, `.codex/<profile>.md`, `.codex/sub-agent-protocol.md`, `.codex/salesforce-pdf-registry.md`                                              |
| **Claude**     | `CLAUDE.md`, `.claude/rules/<profile>.md`, `.claude/rules/sub-agent-protocol.md`, `.claude/rules/salesforce-pdf-registry.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 a sub-agent routing manifest for every configured runtime — `.cursor/rules/sub-agent-protocol.mdc` (Cursor), `.claude/rules/sub-agent-protocol.md` (Claude), and `.codex/sub-agent-protocol.md` (Codex) — 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`](#sf-setup-agents)
- [`sf setup-agents agentforce-deploy`](#sf-setup-agents-agentforce-deploy)
- [`sf setup-agents auth revoke`](#sf-setup-agents-auth-revoke)
- [`sf setup-agents background run`](#sf-setup-agents-background-run)
- [`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 decision render`](#sf-setup-agents-decision-render)
- [`sf setup-agents diagram import`](#sf-setup-agents-diagram-import)
- [`sf setup-agents diagram migrate`](#sf-setup-agents-diagram-migrate)
- [`sf setup-agents diagram render`](#sf-setup-agents-diagram-render)
- [`sf setup-agents docs`](#sf-setup-agents-docs)
- [`sf setup-agents docs sync`](#sf-setup-agents-docs-sync)
- [`sf setup-agents evidence add`](#sf-setup-agents-evidence-add)
- [`sf setup-agents evidence compact`](#sf-setup-agents-evidence-compact)
- [`sf setup-agents evidence generate`](#sf-setup-agents-evidence-generate)
- [`sf setup-agents evidence list`](#sf-setup-agents-evidence-list)
- [`sf setup-agents evidence validate`](#sf-setup-agents-evidence-validate)
- [`sf setup-agents export`](#sf-setup-agents-export)
- [`sf setup-agents extract html-to-markdown`](#sf-setup-agents-extract-html-to-markdown)
- [`sf setup-agents extract pdf-to-markdown`](#sf-setup-agents-extract-pdf-to-markdown)
- [`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 knowledge refresh`](#sf-setup-agents-knowledge-refresh)
- [`sf setup-agents local`](#sf-setup-agents-local)
- [`sf setup-agents mcp`](#sf-setup-agents-mcp)
- [`sf setup-agents offline guide`](#sf-setup-agents-offline-guide)
- [`sf setup-agents offline status`](#sf-setup-agents-offline-status)
- [`sf setup-agents profile audit-api-names`](#sf-setup-agents-profile-audit-api-names)
- [`sf setup-agents release-notes collect`](#sf-setup-agents-release-notes-collect)
- [`sf setup-agents report generate`](#sf-setup-agents-report-generate)
- [`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 rules inject`](#sf-setup-agents-rules-inject)
- [`sf setup-agents serve`](#sf-setup-agents-serve)
- [`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 decompose`](#sf-setup-agents-workflow-decompose)
- [`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 lessons`](#sf-setup-agents-workflow-lessons)
- [`sf setup-agents workflow pending`](#sf-setup-agents-workflow-pending)
- [`sf setup-agents workflow phase-plan`](#sf-setup-agents-workflow-phase-plan)
- [`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`

Generate a dependency-aware metadata catalog from a Salesforce source directory.

```
USAGE
  $ sf setup-agents [--json] [--flags-dir <value>] [--full] [--format json|md] [--include <value>] [--exclude
    <value>] [--source-dir <value>]

FLAGS
  --exclude=<value>     Comma-separated list of metadata types to exclude.
  --format=<option>     [default: json] Output format: json (default) or md.
                        <options: json|md>
  --full                Force a full scan instead of incremental git-diff mode.
  --include=<value>     Comma-separated list of metadata types to include (others are excluded).
  --source-dir=<value>  [default: force-app] Source directory to scan (default: force-app).

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

DESCRIPTION
  Generate a dependency-aware metadata catalog from a Salesforce source directory.

  Scans the specified source directory (default: force-app), parses all recognized Salesforce metadata types (Apex
  classes, triggers, LWC, objects, fields, flows, permission sets, labels), builds a dependency graph, and outputs the
  index to .setup-agents/sf-metadata-index.json (or .md with --format md).

  Supports incremental indexing via git-diff mode (default) which only re-indexes changed files, or --full for a
  complete rescan.

EXAMPLES
  Generate a full metadata index:

    $ sf setup-agents --full

  Generate index in markdown format:

    $ sf setup-agents --format md

  Index only Apex classes and triggers:

    $ sf setup-agents --include ApexClass,ApexTrigger

  Index from a custom source directory:

    $ sf setup-agents --source-dir src/main

FLAG DESCRIPTIONS
  --exclude=<value>  Comma-separated list of metadata types to exclude.

    Exclude the specified types from indexing. Valid types: ApexClass, ApexTrigger, LightningComponentBundle,
    CustomObject, CustomField, Flow, PermissionSet, CustomLabel.

  --full  Force a full scan instead of incremental git-diff mode.

    By default, the index command uses git-diff mode to only re-index files changed since the last commit. Use --full to
    scan all files regardless of changes.

  --include=<value>  Comma-separated list of metadata types to include (others are excluded).

    Only index the specified types. Valid types: ApexClass, ApexTrigger, LightningComponentBundle, CustomObject,
    CustomField, Flow, PermissionSet, CustomLabel.
```

_See code: [src/commands/setup-agents/index.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/index.ts)_

## `sf setup-agents agentforce-deploy`

Generate and deploy an Agentforce agent to a Salesforce org.

```
USAGE
  $ sf setup-agents agentforce-deploy [--json] [--flags-dir <value>] [--target-org myOrgAlias] [--profile
    developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--dry-run] [-f]

FLAGS
  -f, --force
      Overwrite existing agent metadata files.

  --dry-run
      Generate metadata locally without deploying.

  --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudi
  o|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|n
  etzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      [default: developer] Role profile to use for agent behavior (default: developer).

  --target-org=myOrgAlias
      Salesforce org alias or username to deploy the agent to.

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

DESCRIPTION
  Generate and deploy an Agentforce agent to a Salesforce org.

  Generates Salesforce metadata (BotDefinition, GenAiPlanner, Topics, PromptTemplates) for
  a deployable Agentforce agent tailored to the selected profile, then deploys it to the target org.

  Use `--dry-run` to generate metadata locally without deploying.

EXAMPLES
  Deploy an Agentforce agent with developer profile:

    $ sf setup-agents agentforce-deploy --target-org myOrg --profile developer

  Generate metadata without deploying (dry run):

    $ sf setup-agents agentforce-deploy --dry-run --profile architect

  Deploy with force overwrite:

    $ sf setup-agents agentforce-deploy --target-org myOrg --force

FLAG DESCRIPTIONS
  -f, --force  Overwrite existing agent metadata files.

    Force overwrite of all generated metadata files, even if they already exist.

  --dry-run  Generate metadata locally without deploying.

    When set, the command generates all Agentforce metadata files under `force-app/main/default/`
    but does not execute `sf project deploy start`. Useful for reviewing generated metadata before deploying.

  --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    Role profile to use for agent behavior (default: developer).

    Determines which topics, prompt templates, and system instructions the agent will use.
    See the --profile flag's help value above for the full current list of valid profile ids.

  --target-org=myOrgAlias  Salesforce org alias or username to deploy the agent to.

    The target org where the Agentforce agent metadata will be deployed.
    Required unless `--dry-run` is used.
```

_See code: [src/commands/setup-agents/agentforce-deploy.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/agentforce-deploy.ts)_

## `sf setup-agents auth revoke`

Revoke setup-agents authorization for a workspace.

```
USAGE
  $ sf setup-agents auth revoke [--json] [--flags-dir <value>] [--target-dir <value>]

FLAGS
  --target-dir=<value>  Workspace whose activation should be revoked.

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

DESCRIPTION
  Revoke setup-agents authorization for a workspace.

  Removes the local durable authorization for the current workspace. Use --target-dir to revoke another workspace.

EXAMPLES
  $ sf setup-agents auth revoke

  $ sf setup-agents auth revoke --target-dir ../project
```

_See code: [src/commands/setup-agents/auth/revoke.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/auth/revoke.ts)_

## `sf setup-agents background run`

Launch an allow-listed long-running command in a durable background lane.

```
USAGE
  $ sf setup-agents background run [--json] [--flags-dir <value>] [--label <value>] [--port <value>] [--chat-session
  <value>]

FLAGS
  --chat-session=<value>  Originating chat session id, used to correlate the background task to the chat panel.
  --label=<value>         Human-friendly label shown in the chat UI for this background task.
  --port=<value>          Bridge server port. Defaults to SETUP_AGENTS_BRIDGE_PORT, then 4195.

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

DESCRIPTION
  Launch an allow-listed long-running command in a durable background lane.

  Delegates a long-running, side-effecting command (Salesforce metadata retrieve/deploy, package operations, or a
  project build) to the running setup-agents bridge server, which executes it as a detached process that OUTLIVES the
  current chat turn.

  This exists so work the agent starts inside a chat turn — `sf project retrieve start`, `sf project deploy start`, `npm
  run build` — is not killed when the turn ends, when the user hits Stop, when the idle session is reaped, or when the
  session respawns on the next message.

  The command after `--` must match the background allow-list: `sf project ...`, `sf package ...`, `npm run build`, or
  `yarn build`. Anything else is rejected. Lifecycle (started/completed/failed) is reported to the web console via the
  bridge's spawn event stream.

  Requires a running bridge (`sf setup-agents serve`). The bridge port is discovered from the `SETUP_AGENTS_BRIDGE_PORT`
  environment variable, or supplied with `--port`.

EXAMPLES
  Run a metadata retrieve in the background:

    $ sf setup-agents background run --label "Retrieve Apex" -- sf project retrieve start -m ApexClass

  Run a project build in the background:

    $ sf setup-agents background run -- npm run build
```

_See code: [src/commands/setup-agents/background/run.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/background/run.ts)_

## `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/v3.22.3/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/v3.22.3/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/v3.22.3/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/v3.22.3/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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--rationale <value>] [--status
    proposed|accepted|superseded] [--outcome <value>] [--alternative <value>] [--evidence <value>]

FLAGS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnis
  tudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educati
  on|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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/v3.22.3/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/v3.22.3/src/commands/setup-agents/decision/list.ts)_

## `sf setup-agents decision render`

Render decision records as Markdown ADRs.

```
USAGE
  $ sf setup-agents decision render [--json] [--flags-dir <value>] [--id <value> | --all]

FLAGS
  --all         Render every decision record.
  --id=<value>  Decision record id to render.

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

DESCRIPTION
  Render decision records as Markdown ADRs.

  Reads decision records from `.setup-agents/state/decisions.jsonl` and writes human-reviewable Markdown ADRs to
  `docs/adr/`.

  The JSONL log stays the canonical source; `docs/adr/` is a derived render. Each record is written to
  `docs/adr/ADR-<id>.md` so the record id is recoverable from the filename. This command never mutates
  `decisions.jsonl`.

EXAMPLES
  Render every decision record as an ADR:

    $ sf setup-agents decision render --all

  Render a single decision record:

    $ sf setup-agents decision render --id setup-agents-decision-1700000000000-abc123

FLAG DESCRIPTIONS
  --all  Render every decision record.

    Render all decision records found in the decision log.

  --id=<value>  Decision record id to render.

    Render only the decision record with this id.
```

_See code: [src/commands/setup-agents/decision/render.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/decision/render.ts)_

## `sf setup-agents diagram import`

Import an existing diagram or org metadata into AgentDiagramData JSON.

```
USAGE
  $ sf setup-agents diagram import -i <value> [--json] [--flags-dir <value>] [-f force-app|drawio|mermaid|md|auto] [--out
    <value>] [-t <value>]

FLAGS
  -f, --from=force-app|drawio|mermaid|md|auto  [default: auto] Source adapter: force-app, drawio, mermaid, md, or auto
                                               (infer from the path — directory → force-app, by extension otherwise).
  -i, --input=<value>                          (required) Path to the source: a force-app directory, a .drawio file, a
                                               .mmd Mermaid file, or a .md Markdown file.
  -t, --title=<value>                          Diagram title. Defaults to the input file/directory name.
      --out=<value>                            Path to write the AgentDiagramData JSON. When omitted, the model is
                                               printed to stdout.

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

DESCRIPTION
  Import an existing diagram or org metadata into AgentDiagramData JSON.

  Builds the canonical AgentDiagramData model from a real source — force-app metadata, an existing draw.io file, a
  Mermaid `.mmd`, or a Markdown file with an embedded `mermaid` block — so `sf setup-agents diagram render` can
  re-lay-it-out optimally instead of you hand-authoring the JSON. Each source normalizes to the same model: nodes are
  entities/objects (never fields — an ERD models objects, a field's relationship becomes an edge), edges are
  relationships, and `group` is inferred per source (namespace for force-app, subgraph/swimlane for drawio/mermaid).
  Output goes to a file with `--out`, or to stdout when `--out` is omitted; pipe it into `diagram render`.

EXAMPLES
  `sf setup-agents diagram import --input force-app --from force-app --out model.json`

  `sf setup-agents diagram import --input docs/erd.drawio --out model.json`

  `sf setup-agents diagram import -i diagram.mmd --out model.json && sf setup-agents diagram render -i model.json -f drawio -o /tmp/erd.drawio`

  `sf setup-agents diagram import -i design.md` (extracts the embedded mermaid block, prints the model)
```

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

## `sf setup-agents diagram migrate`

Migrate a drawio ERD to use orthogonal routing, row-level connections, and dagre layout.

```
USAGE
  $ sf setup-agents diagram migrate -f <value> [--json] [--flags-dir <value>] [--relayout] [--node-sep <value>] [--rank-sep
    <value>]

FLAGS
  -f, --file=<value>      (required) Path to the drawio file to migrate.
      --node-sep=<value>  [default: 100] Horizontal separation between nodes (dagre nodesep).
      --rank-sep=<value>  [default: 180] Vertical separation between ranks (dagre ranksep).
      --relayout          Reposition tables using dagre layout engine.

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

DESCRIPTION
  Migrate a drawio ERD to use orthogonal routing, row-level connections, and dagre layout.

  Applies best-practice ERD rendering to an existing drawio file: orthogonal edge style, PK/FK row-level connections,
  label backgrounds, and optional dagre relayout.

EXAMPLES
  `sf setup-agents diagram migrate --file docs/architecture/erd.drawio`

  `sf setup-agents diagram migrate --file erd.drawio --relayout`
```

_See code: [src/commands/setup-agents/diagram/migrate.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/diagram/migrate.ts)_

## `sf setup-agents diagram render`

Render structured AgentDiagramData JSON to Mermaid, draw.io XML, maxGraph JSON, SVG, or PDF.

```
USAGE
  $ sf setup-agents diagram render -i <value> [--json] [--flags-dir <value>] [-f mermaid|drawio|maxgraph-json|svg|pdf] [-o
    <value>]

FLAGS
  -f, --format=mermaid|drawio|maxgraph-json|svg|pdf  [default: mermaid] Output format: mermaid, drawio, maxgraph-json,
                                                     svg, or pdf.
  -i, --input=<value>                                (required) Path to an AgentDiagramData JSON file.
  -o, --out=<value>                                  Path to write the rendered output. When omitted, the result is
                                                     printed to stdout.

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

DESCRIPTION
  Render structured AgentDiagramData JSON to Mermaid, draw.io XML, maxGraph JSON, SVG, or PDF.

  Reads an AgentDiagramData JSON document and renders it with the plugin's deterministic diagram renderer. Use this
  instead of hand-rolling a one-off conversion script. The AgentDiagramData shape is: `{ type, title?, direction?,
  nodes: [{ id, label, shape?, group?, style? }], edges: [{ from, to, label?, style?, arrowhead? }], participants?,
  messages? }`. Output goes to a file with `--out`, or to stdout when `--out` is omitted. The `svg` and `pdf` formats
  emit the same painted diagram the web-console shows (orthogonal edge routing, ER row-level connections, group bands) —
  not raw mxGraph XML. `pdf` requires `--out` and a local puppeteer install.

EXAMPLES
  `sf setup-agents diagram render --input data.json --format mermaid`

  `sf setup-agents diagram render --input data.json --format drawio --out docs/architecture/diagram.drawio`

  `sf setup-agents diagram render -i data.json -f maxgraph-json -o diagram.json`

  `sf setup-agents diagram render -i data.json -f svg -o diagram.svg`

  `sf setup-agents diagram render -i data.json -f pdf -o diagram.pdf`
```

_See code: [src/commands/setup-agents/diagram/render.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/diagram/render.ts)_

## `sf setup-agents docs`

Render workspace markdown as a PDF document or interactive HTML deck.

```
USAGE
  $ sf setup-agents docs -i <value> --review <value> [--json] [--flags-dir <value>] [--output <value>] [--deck | --pdf]

FLAGS
  -i, --input=<value>   (required) Directory of markdown files, or a comma-separated list of markdown files.
      --deck            Render an interactive Salesforce-branded HTML deck.
      --output=<value>  Path to write the generated PDF or HTML deck.
      --pdf             Render a linear PDF document.
      --review=<value>  (required) Path to the approved document quality review JSON.

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

DESCRIPTION
  Render workspace markdown as a PDF document or interactive HTML deck.

  Choose exactly one output format: `--pdf` renders a linear PDF document, while `--deck` renders a self-contained
  interactive HTML presentation. Both formats render embedded Mermaid diagrams and inline local images.

EXAMPLES
  Create an interactive deck from a markdown file:

    $ sf setup-agents docs --deck --input presentation.md --output presentation.html --review \
      presentation-review.json

  Create a PDF document from every markdown file under a directory:

    $ sf setup-agents docs --pdf --input docs --output documentation.pdf --review documentation-review.json

FLAG DESCRIPTIONS
  -i, --input=<value>  Directory of markdown files, or a comma-separated list of markdown files.

    A directory is walked recursively for `*.md` and `*.markdown` files and sorted. A comma-separated list preserves the
    given order.

  --deck  Render an interactive Salesforce-branded HTML deck.

    Splits markdown at each top-level heading (`#`) and adds previous/next controls, keyboard navigation, URL slide
    hashes, and fullscreen mode. Deck output is always self-contained HTML.

  --output=<value>  Path to write the generated PDF or HTML deck.

    When omitted, writes `document-<timestamp>.pdf` or `deck-<timestamp>.html` in the current directory.

  --pdf  Render a linear PDF document.

    Consolidates the markdown into a Salesforce-branded PDF. Use `--deck` instead for an interactive HTML presentation.

  --review=<value>  Path to the approved document quality review JSON.

    Required for every render. The review must approve the exact ordered input files and SHA-256 source digest, use an
    independent reviewer, and contain no open blocking findings.
```

_See code: [src/commands/setup-agents/docs.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/docs.ts)_

## `sf setup-agents docs sync`

Sync Salesforce documentation for profiles to local cache.

```
USAGE
  $ sf setup-agents docs sync [--json] [--flags-dir <value>] [-p <value>] [--force] [--max-pages <value>]

FLAGS
  -p, --profile=<value>    Profile to sync documentation for.
      --force              Re-download even if documentation is already cached.
      --max-pages=<value>  [default: 5] Maximum pages to download per doc source.

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

DESCRIPTION
  Sync Salesforce documentation for profiles to local cache.

  Downloads documentation from developer.salesforce.com and caches it locally in `.setup-agents/docs/<profile>/` so
  sub-agents can read it on demand during workflow execution.

EXAMPLES
  Sync all registered profiles:

    $ sf setup-agents docs sync

  Sync a specific profile:

    $ sf setup-agents docs sync --profile loyalty

  Force re-download even if cached:

    $ sf setup-agents docs sync --profile fsc --force

FLAG DESCRIPTIONS
  -p, --profile=<value>  Profile to sync documentation for.

    When omitted, syncs documentation for all profiles that have registered doc sources. Use this to sync a single
    profile.

  --force  Re-download even if documentation is already cached.

    By default, previously synced documentation is skipped. Use --force to re-download and overwrite.

  --max-pages=<value>  Maximum pages to download per doc source.

    Controls how many sub-pages are fetched from each documentation source. Higher values provide more detail but take
    longer. Default is 5.
```

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

## `sf setup-agents evidence add`

Add a setup-agents evidence record.

```
USAGE
  $ sf setup-agents evidence add -s <value> [--json] [--flags-dir <value>] [--target-dir <value>] [-t <value>] [-r <value>] [-p
    developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--type
    command|file|screenshot|trace|report|validation|lesson|other] [--kind
    command|file|screenshot|trace|report|validation|lesson|other] [--source <value>] [--command <value>] [--path
    <value>] [--exit-code <value>] [--details <value>] [--minutes <value>]

FLAGS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnis
  tudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educati
  on|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      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|lesson|other>

  --minutes=<value>
      Measured human-effort minutes (for `manual` / `review` evidence).

  --path=<value>
      Evidence path.

  --source=<value>
      Evidence source reference.

  --target-dir=<value>
      Workspace root to target (defaults to cwd).

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

  ID format: `setup-agents-evidence-<unix_ms>-<6_random_alnum>` (auto-generated).

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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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|lesson|other  Evidence kind.

    Alias for `--type`.

  --minutes=<value>  Measured human-effort minutes (for `manual` / `review` evidence).

    Minutes a human spent on this work. Use with `--type manual` (hands-on platform execution: Setup config not possible
    via metadata/tooling API, MIAW, data fixes) or `--type review` (gate approvals, architecture corrections,
    direction). The effort insights sum these as real human effort (GH-445).

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

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.

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

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

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

## `sf setup-agents evidence compact`

Compact and archive old evidence records.

```
USAGE
  $ sf setup-agents evidence compact [--json] [--flags-dir <value>] [-d <value>] [--dry-run] [-t <value>]

FLAGS
  -d, --older-than-days=<value>  [default: 30] Age threshold in days.
  -t, --task=<value>             Only compact records for a specific task.
      --dry-run                  Preview what would be compacted without writing.

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

DESCRIPTION
  Compact and archive old evidence records.

  Moves evidence records older than the specified threshold into an archive file,
  reducing the size of the active evidence log.

EXAMPLES
  Compact evidence older than 30 days:

    $ sf setup-agents evidence compact

  Preview compaction of 60-day-old records:

    $ sf setup-agents evidence compact --older-than-days 60 --dry-run

  Compact evidence for a specific task:

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

FLAG DESCRIPTIONS
  -d, --older-than-days=<value>  Age threshold in days.

    Archive evidence records older than this many days (default: 30).

  -t, --task=<value>  Only compact records for a specific task.

    Restrict compaction to evidence records associated with the given task id.
```

_See code: [src/commands/setup-agents/evidence/compact.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/evidence/compact.ts)_

## `sf setup-agents evidence generate`

Generate QA evidence (test, coverage, lint) and record it.

```
USAGE
  $ sf setup-agents evidence generate -t <value> [--json] [--flags-dir <value>] [--target-dir <value>] [-k
  all|test|coverage|lint]

FLAGS
  -k, --kind=<option>       [default: all] Which evidence to generate.
                            <options: all|test|coverage|lint>
  -t, --task=<value>        (required) Task or issue id for the generated evidence.
      --target-dir=<value>  Workspace root to target (defaults to cwd).

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

DESCRIPTION
  Generate QA evidence (test, coverage, lint) and record it.

  Runs the built-in QA evidence generators and appends the results to `.setup-agents/state/evidence.jsonl` as `report`
  evidence for the given task.

  - `test` runs `npx mocha --reporter json` and records pass/fail/skip counts.
  - `coverage` parses `coverage/lcov.info` and records line/function/branch percentages.
  - `lint` runs ESLint and records error/warning counts.
  - `all` (default) runs the three concurrently and reports an overall status.

  Use this instead of hand-rolling a script to collect QA evidence — the generated records feed the workflow QA gate and
  effort insights.

EXAMPLES
  Generate test, coverage, and lint evidence for a task:

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

  Generate only coverage evidence:

    $ sf setup-agents evidence generate --task SA-96 --kind coverage

FLAG DESCRIPTIONS
  -k, --kind=all|test|coverage|lint  Which evidence to generate.

    One of `all` (default), `test`, `coverage`, or `lint`.

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

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

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

_See code: [src/commands/setup-agents/evidence/generate.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/evidence/generate.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/v3.22.3/src/commands/setup-agents/evidence/list.ts)_

## `sf setup-agents evidence validate`

Validate evidence record IDs in the state file.

```
USAGE
  $ sf setup-agents evidence validate [--json] [--flags-dir <value>] [--target-dir <value>]

FLAGS
  --target-dir=<value>  Workspace root to target (defaults to cwd).

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

DESCRIPTION
  Validate evidence record IDs in the state file.

  Scans `.setup-agents/state/evidence.jsonl` and reports entries with IDs that do not match the canonical format:
  `setup-agents-evidence-<unix_ms>-<6_random_alnum>`.

EXAMPLES
  Validate all evidence records:

    $ sf setup-agents evidence validate

FLAG DESCRIPTIONS
  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

_See code: [src/commands/setup-agents/evidence/validate.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/evidence/validate.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/v3.22.3/src/commands/setup-agents/export.ts)_

## `sf setup-agents extract html-to-markdown`

Extract the content of an HTML file to Markdown.

```
USAGE
  $ sf setup-agents extract html-to-markdown -i <value> [--json] [--flags-dir <value>] [-o <value>]

FLAGS
  -i, --input=<value>  (required) Path to an HTML file to extract.
  -o, --out=<value>    Path to write the Markdown output. When omitted, the result is printed to stdout.

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

DESCRIPTION
  Extract the content of an HTML file to Markdown.

  Reads an HTML file and converts it to Markdown, mapping headings, lists, tables, and inline emphasis. Use this to turn
  a large HTML reference into a greppable `.md` file instead of trying to `Read` the markup whole (which blows the
  context window). Output goes to a file with `--out`, or to stdout when `--out` is omitted.

EXAMPLES
  `sf setup-agents extract html-to-markdown --input page.html --out page.md`

  `sf setup-agents extract html-to-markdown -i page.html`
```

_See code: [src/commands/setup-agents/extract/html-to-markdown.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/extract/html-to-markdown.ts)_

## `sf setup-agents extract pdf-to-markdown`

Extract the text of a PDF file to Markdown.

```
USAGE
  $ sf setup-agents extract pdf-to-markdown -i <value> [--json] [--flags-dir <value>] [-o <value>]

FLAGS
  -i, --input=<value>  (required) Path to a PDF file to extract.
  -o, --out=<value>    Path to write the Markdown output. When omitted, the result is printed to stdout.

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

DESCRIPTION
  Extract the text of a PDF file to Markdown.

  Reads a PDF file and converts its text content to Markdown, preserving paragraph breaks. Use this to turn a large PDF
  reference into a greppable `.md` file instead of trying to `Read` the binary whole (which fails and blows the context
  window). Output goes to a file with `--out`, or to stdout when `--out` is omitted.

EXAMPLES
  `sf setup-agents extract pdf-to-markdown --input spec.pdf --out spec.md`

  `sf setup-agents extract pdf-to-markdown -i spec.pdf`
```

_See code: [src/commands/setup-agents/extract/pdf-to-markdown.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/extract/pdf-to-markdown.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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omni
    studio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educ
    ation|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--files <value>]
    [--changed-file <value>] [--risks <value>] [--risk <value>] [--next-actions <value>] [--next-action <value>]
    [--evidence <value>] [--acceptance <value>] [--capability-signals qa evidence,release evidence]

FLAGS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnis
  tudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educati
  on|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      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.

  --acceptance=<value>
      Acceptance criteria for the receiving role.

  --capability-signals=qa evidence,release evidence
      Runtime capability signals for the receiving role.

  --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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

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

  --acceptance=<value>  Acceptance criteria for the receiving role.

    Quoted, comma-separated acceptance criteria. Text containing commas should be wrapped in quotes, e.g. `"Given X,
    when Y" , "Then Z"`.

  --capability-signals=qa evidence,release evidence  Runtime capability signals for the receiving role.

    Comma-separated signals the next sub-agent should use to activate runtime capabilities,
    for example `qa evidence,acceptance criteria coverage,release evidence`.

  --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/v3.22.3/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/v3.22.3/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/v3.22.3/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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--white-label mx|co|br] [--tools
    cursor|vscode|codex|claude|agentforce|windsurf|jetbrains|opencode] [-f] [--commit] [--dry-run] [--quick]

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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudi
  o|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|n
  etzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      Role profiles to persist (comma-separated).

  --quick
      Auto-detect everything and generate rules immediately.

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

  --white-label=mx|co|br
      FSC white-label country pack to load (`mx`, `co`, or `br`).

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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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.

  --quick  Auto-detect everything and generate rules immediately.

    Skip all interactive prompts. Auto-detects tools from the project directory and profiles from project signals (e.g.
    sfdx-project.json, force-app/, package.json). Writes config and generates rule files in one step. Equivalent to
    running init + local with auto-detected defaults.

  --tools=cursor|vscode|codex|claude|agentforce|windsurf|jetbrains|opencode  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.

  --white-label=mx|co|br  FSC white-label country pack to load (`mx`, `co`, or `br`).

    When the `fsc` profile is active, selects a single country white-label so only that country's FSC rule and workflows
    are generated (`mx` = México, `co` = Colombia, `br` = Brasil). When omitted, the `fsc` profile emits its
    country-neutral output. Inert if the `fsc` profile is not selected.
```

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

## `sf setup-agents knowledge refresh`

Refresh repository knowledge artifacts.

```
USAGE
  $ sf setup-agents knowledge refresh [--json] [--flags-dir <value>] [--check] [--full] [--source-dir <value>...]
    [--refresh-timestamp <value>]

FLAGS
  --check                      Check freshness and readiness without writing files.
  --full                       Force a complete deterministic repository scan.
  --refresh-timestamp=<value>  Explicit ISO timestamp to include in generated provenance.
  --source-dir=<value>...      Source root to scan; repeat for multiple roots. Defaults to all sfdx packageDirectories.

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

DESCRIPTION
  Refresh repository knowledge artifacts.

  Builds the metadata index, class catalog, documentation index, managed project-knowledge evidence, and knowledge
  manifest from every configured Salesforce package directory.

EXAMPLES
  Refresh all configured source roots:

    $ sf setup-agents knowledge refresh --full

  Check freshness without writing files:

    $ sf setup-agents knowledge refresh --check --json

  Refresh explicitly scoped roots with reproducible provenance:

    $ sf setup-agents knowledge refresh --source-dir force-app --source-dir packages/core --refresh-timestamp \
      2026-08-07T00:00:00.000Z
```

_See code: [src/commands/setup-agents/knowledge/refresh.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/knowledge/refresh.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,opencode] [--profile
    developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [-f] [--open-orchestra] [--quick]
    [--advisory] [--scope project|user] [--sf-skills]

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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudi
  o|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|n
  etzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      Role profiles to configure (comma-separated).

  --quick
      Generate rules only — skip orchestration state, playbooks, and docs sync.

  --rules=cursor,vscode,codex,claude,agentforce,windsurf,jetbrains,opencode
      Target AI tools to configure (comma-separated).

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

  --[no-]sf-skills
      Install the official Salesforce Agent Skills for Salesforce projects (default: enabled; use --no-sf-skills to skip).

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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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.

    See the --profile flag's help value above for the full current list of valid profile ids.

    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.

  --quick  Generate rules only — skip orchestration state, playbooks, and docs sync.

    Quick mode generates AI rule files for the selected tools and profiles but does not create `.setup-agents/state/`,
    playbooks, offline runbook, or documentation sync. Use this for a minimal onboarding experience.

  --rules=cursor,vscode,codex,claude,agentforce,windsurf,jetbrains,opencode

    Target AI tools to configure (comma-separated).

    Specify one or more AI coding assistants as a comma-separated list. Valid values are `cursor`, `vscode`, `codex`,
    `claude`, `agentforce`, `windsurf`, `jetbrains`, and `opencode`.
    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).

  --[no-]sf-skills

    Install the official Salesforce Agent Skills for Salesforce projects (default: enabled; use --no-sf-skills to skip).

    For Salesforce projects (detected via `sfdx-project.json`), install the official `forcedotcom/sf-skills` Agent
    Skills into the on-demand `.setup-agents/sf-skills/` directory — a location NOT auto-scanned by Claude Code, so the
    skills add zero base-context footprint and are referenced by path only when relevant. Best-effort and idempotent: a
    missing `npx`/`git` or network never breaks setup. Pass `--no-sf-skills` to skip installation entirely.
```

_See code: [src/commands/setup-agents/local.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudi
  o|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|n
  etzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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/v3.22.3/src/commands/setup-agents/mcp.ts)_

## `sf setup-agents offline guide`

Show deterministic offline guide for a specific task.

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

FLAGS
  -t, --task=<value>  (required) Task ID to generate guide for.

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

DESCRIPTION
  Show deterministic offline guide for a specific task.

  Provides step-by-step recovery guidance, relevant references, and suggested commands for the specified task. Works
  without any LLM or network access.

EXAMPLES
  Show guide for task TASK-1:

    $ sf setup-agents offline guide --task TASK-1

  Show guide as JSON:

    $ sf setup-agents offline guide --task TASK-1 --json
```

_See code: [src/commands/setup-agents/offline/guide.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/offline/guide.ts)_

## `sf setup-agents offline status`

Show offline recovery status for the current workspace.

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

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

DESCRIPTION
  Show offline recovery status for the current workspace.

  Summarizes active task, workflow phase, evidence gaps, local references, configured profiles, runtime executability,
  and suggested next commands. Local LLM checks use a bounded HTTP models probe; all other diagnostics work without
  optional runtimes or network access.

EXAMPLES
  Show offline status:

    $ sf setup-agents offline status

  Show offline status as JSON:

    $ sf setup-agents offline status --json
```

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

## `sf setup-agents profile audit-api-names`

Audit governed Salesforce API examples in guidance files.

```
USAGE
  $ sf setup-agents profile audit-api-names [--json] [--flags-dir <value>] [--target-dir <value>]

FLAGS
  --target-dir=<value>  Directory to audit. Defaults to the current working directory.

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

DESCRIPTION
  Audit governed Salesforce API examples in guidance files.

  Scans generated and hand-authored guidance files (.md, .mdc, .txt) for Automotive, Commerce,
  Nonprofit, and Education Cloud API-context object/field examples that are invalid aliases of a
  governed standard object or that reference an unrecognized name in a governed context. Also
  reports, per governed product, whether the current-model, legacy-package, or parallel data model
  was detected from the project's metadata.

EXAMPLES
  Audit the current directory for invalid or unclassified governed API name examples:

    $ sf setup-agents profile audit-api-names

  Audit a specific directory and emit machine-readable JSON:

    $ sf setup-agents profile audit-api-names --target-dir docs --json
```

_See code: [src/commands/setup-agents/profile/audit-api-names.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/profile/audit-api-names.ts)_

## `sf setup-agents release-notes collect`

Collect a Salesforce release-note inventory.

```
USAGE
  $ sf setup-agents release-notes collect -r <value> [--json] [--flags-dir <value>] [--content] [--article <value>...] [--concurrency
    <value>] [--timeout <value>] [--output <value>] [--baseline <value>]

FLAGS
  -r, --release=<value>      (required) Three-digit Salesforce release number.
      --article=<value>...   Article ID to retrieve; repeat to select multiple articles. Defaults to all articles with
                             --content.
      --baseline=<value>     Compare inventory IDs and count, content hashes, and lifecycle classifications against this
                             prior collector JSON. Failed retrievals retain prior high-confidence evidence and enter the
                             review queue.
      --concurrency=<value>  [default: 3] Maximum simultaneous article browser sessions (1-8).
      --content              Retrieve authoritative content metadata and hashes through observed Aura responses.
      --output=<value>       Write the JSON result to this path.
      --timeout=<value>      [default: 45000] Per-page timeout in milliseconds (1000-120000).

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

DESCRIPTION
  Collect a Salesforce release-note inventory.

  Uses a bounded Playwright browser session to inspect the rendered Salesforce Help table of contents. Optionally
  observes page-generated Aura responses for authoritative article metadata without replaying or hard-coding dynamic
  Aura context.

EXAMPLES
  Collect the Release 264 inventory:

    $ sf setup-agents release-notes collect --release 264 --json

  Retrieve authoritative metadata for selected articles:

    $ sf setup-agents release-notes collect --release 264 --content --article rn_apex_symbol_api --output \
      release-264.json

  Compare a refresh with a prior baseline and emit explicit deltas and a review queue:

    $ sf setup-agents release-notes collect --release 264 --content --baseline release-264-baseline.json --output \
      release-264-refresh.json
```

_See code: [src/commands/setup-agents/release-notes/collect.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/release-notes/collect.ts)_

## `sf setup-agents report generate`

Render structured AgentReportData JSON to an HTML or Markdown report.

```
USAGE
  $ sf setup-agents report generate -i <value> [--json] [--flags-dir <value>] [-f html|markdown] [-o <value>]

FLAGS
  -f, --format=html|markdown  [default: markdown] Output format: html or markdown.
  -i, --input=<value>         (required) Path to an AgentReportData JSON file.
  -o, --out=<value>           Path to write the rendered output. When omitted, the result is printed to stdout.

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

DESCRIPTION
  Render structured AgentReportData JSON to an HTML or Markdown report.

  Reads an AgentReportData JSON document and renders it with the plugin's deterministic report renderer. Use this
  instead of hand-rolling a one-off report script. The AgentReportData shape is: `{ title, generatedAt, taskId?,
  author?, sections: [{ title, findings?, metrics?, recommendations?, prose? }] }`. Output goes to a file with `--out`,
  or to stdout when `--out` is omitted.

EXAMPLES
  `sf setup-agents report generate --input data.json --format markdown`

  `sf setup-agents report generate --input data.json --format html --out report.html`

  `sf setup-agents report generate -i data.json -f html -o docs/report.html`
```

_See code: [src/commands/setup-agents/report/generate.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/report/generate.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>] [--target-dir
    <value>] [--reviewer developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|
    cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automot
    ive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--findings <value>]
    [--recommendation <value>] [--return-to pm|ba|architect|ux|developer|security-review|qa|document-review|release]

FLAGS
  --findings=<value>
      Review findings.

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

  --recommendation=<value>
      Review recommendation.

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

  --return-to=<option>
      Target phase for correction routing.
      <options: pm|ba|architect|ux|developer|security-review|qa|document-review|release>

  --reviewer=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistud
  io|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|
  netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      Profile completing the review.

  --target-dir=<value>
      Workspace root to target (defaults to cwd).

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

  --return-to=pm|ba|architect|ux|developer|security-review|qa|document-review|release

    Target phase for correction routing.

    When the result is `blocked` or `changes`, specify which phase the correction should be routed to. On next `workflow
    run --resume`, the workflow will return to this phase automatically.

  --reviewer=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    Profile completing the review.

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

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

_See code: [src/commands/setup-agents/review/complete.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/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/v3.22.3/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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--reviewer
    developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistu
  dio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education
  |netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      [default: developer] Profile requesting the review.

  --reviewer=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistud
  io|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|
  netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    Profile requesting the review.

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

  --reviewer=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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/v3.22.3/src/commands/setup-agents/review/request.ts)_

## `sf setup-agents rules inject`

Inject neutral rules into runtime-specific locations.

```
USAGE
  $ sf setup-agents rules inject -t claude|cursor|codex|vscode|windsurf|opencode [--json] [--flags-dir <value>] [-p <value>]
    [-r <value>] [--dry-run]

FLAGS
  -p, --profile=<value>  Filter rules by profile ID.
  -r, --rule=<value>     Inject a specific rule by ID.
  -t, --target=<option>  (required) Target runtime to inject rules for.
                         <options: claude|cursor|codex|vscode|windsurf|opencode>
      --dry-run          Preview changes without writing files.

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

DESCRIPTION
  Inject neutral rules into runtime-specific locations.

  Reads rules from the neutral registry (`.setup-agents/rules/`), renders them for the specified target runtime, and
  writes to the correct location. Use `--dry-run` to preview without writing.

EXAMPLES
  Inject all rules for Claude:

    $ sf setup-agents rules inject --target claude

  Inject rules for a specific profile:

    $ sf setup-agents rules inject --target cursor --profile developer

  Preview injection of a single rule:

    $ sf setup-agents rules inject --target codex --rule my-rule --dry-run

FLAG DESCRIPTIONS
  -p, --profile=<value>  Filter rules by profile ID.

    Only inject rules that apply to the specified profile. Omit to inject all rules.

  -r, --rule=<value>  Inject a specific rule by ID.

    Only inject the rule with the given ID. Omit to inject all matching rules.

  -t, --target=claude|cursor|codex|vscode|windsurf|opencode  Target runtime to inject rules for.

    The target AI coding assistant runtime. Determines output format and destination path.

  --dry-run  Preview changes without writing files.

    Show which files would be written and their content, but do not actually write anything.
```

_See code: [src/commands/setup-agents/rules/inject.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/rules/inject.ts)_

## `sf setup-agents serve`

Start a local bridge server exposing the setup-agents API for the web UI.

```
USAGE
  $ sf setup-agents serve [--json] [--flags-dir <value>] [-p <value>] [-H <value>] [--open] [--auto-reload]

FLAGS
  -H, --hostname=<value>  [default: 127.0.0.1] Hostname to bind the server to.
  -p, --port=<value>      [default: 4195] Port number for the bridge server.
      --auto-reload       Automatically restart the bridge if a newer plugin version is installed while it's running
                          (GH-753). Off by default.
      --open              Open the browser after starting the server.

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

DESCRIPTION
  Start a local bridge server exposing the setup-agents API for the web UI.

  Starts a lightweight HTTP server that exposes the setup-agents service layer as a REST API. The web app (onboarding
  wizard and dashboard) connects to this server to read project state and apply configurations.

  The server runs on localhost and provides CORS headers for browser access.

EXAMPLES
  Start the bridge server on the default port (4195):

    $ sf setup-agents serve

  Start on a custom port:

    $ sf setup-agents serve --port 8080

  Start and open the browser:

    $ sf setup-agents serve --open

  Start and auto-restart when a newer version is installed:

    $ sf setup-agents serve --auto-reload
```

_See code: [src/commands/setup-agents/serve.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/serve.ts)_

## `sf setup-agents status`

Summarize native setup-agents workspace state.

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

FLAGS
  --doctor              Print the read-only task/workflow reconciliation report.
  --fix                 Auto-run update when stale rule files are detected.
  --reconcile           Append safe deterministic reconciliation repairs. Never creates or changes approvals.
  --target-dir=<value>  Workspace root to inspect. Defaults to the current directory.

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/v3.22.3/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/v3.22.3/src/commands/setup-agents/sync.ts)_

## `sf setup-agents task archive`

Archive a setup-agents task.

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

FLAGS
  -t, --task=<value>        Task id.
      --id=<value>          Task id.
      --target-dir=<value>  Workspace root to target (defaults to cwd).

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. Alias: --id.

  --id=<value>  Task id.

    Id of the task. Alias: --task.

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

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

## `sf setup-agents task claim`

Claim a setup-agents task.

```
USAGE
  $ sf setup-agents task claim [--json] [--flags-dir <value>] [--target-dir <value>] [-t <value>] [--id <value>] [-r <value>]
    [-p developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fs
    l|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|net
    zero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--evidence <value>]

FLAGS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnis
  tudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educati
  on|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      Claiming setup-agents profile.

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

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

  --evidence=<value>
      Related evidence ids.

  --id=<value>
      Task id.

  --target-dir=<value>
      Workspace root to target (defaults to cwd).

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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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.

    Id of the task. Alias: --id.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence record ids to attach while claiming.

  --id=<value>  Task id.

    Id of the task. Alias: --task.

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

_See code: [src/commands/setup-agents/task/claim.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/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>] [--target-dir <value>] [-t <value>] [--id <value>]
    [-r <value>] [-p developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|
    omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|
    education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--mode project|advisory]
    [--evidence <value>] [--required-roles developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|s
    alescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|comm
    unications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries]
    [--optional-roles developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq
    |omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive
    |education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--declared-phases
    pm|ba|architect|ux|developer|security-review|qa|document-review|release] [--routing-override-rationale <value>]

FLAGS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnis
  tudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educati
  on|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      Owning setup-agents profile.

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

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

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

  --declared-phases=pm|ba|architect|ux|developer|security-review|qa|document-review|release
      Phases to include in this task's workflow.

  --evidence=<value>
      Related evidence ids.

  --id=<value>
      Task id.

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

  --optional-roles=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|om
  nistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educ
  ation|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      Optional roles for this task.

  --required-roles=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|om
  nistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educ
  ation|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      Required roles for this task.

  --routing-override-rationale=<value>
      Reason for overriding deterministic profile inference.

  --target-dir=<value>
      Workspace root to target (defaults to cwd).

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"

  Create a task with required and optional roles:

    $ sf setup-agents task create --summary "Build login page" --required-roles "ux,developer" --optional-roles \
      "security"

  Create a task with declared phases:

    $ sf setup-agents task create --summary "Quick fix" --declared-phases "developer,qa"

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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.

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

    Id of the task. Alias: --id.

  --declared-phases=pm|ba|architect|ux|developer|security-review|qa|document-review|release

    Phases to include in this task's workflow.

    Comma-separated phase ids to include in the workflow for this task. Phases listed here are added to the plan
    alongside always-included phases. Use this instead of roles when you want to control the exact phase sequence.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence record ids that support this task.

  --id=<value>  Task id.

    Id of the task. Alias: --task.

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

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

  --optional-roles=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    Optional roles for this task.

    Comma-separated profile/phase ids that may participate in the workflow. These phases are included but not strictly
    required for task completion.

  --required-roles=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    Required roles for this task.

    Comma-separated profile/phase ids that must participate in the workflow for this task. Determines which phases are
    included in the phase sequence.

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

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

## `sf setup-agents task delete`

Delete a setup-agents task.

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

FLAGS
  -t, --task=<value>        Task id.
  -y, --yes                 Skip confirmation prompt.
      --id=<value>          Task id.
      --target-dir=<value>  Workspace root to target (defaults to cwd).

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. Alias: --id.

  -y, --yes  Skip confirmation prompt.

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

  --id=<value>  Task id.

    Id of the task. Alias: --task.

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

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

## `sf setup-agents task done`

Mark a setup-agents task done.

```
USAGE
  $ sf setup-agents task done [--json] [--flags-dir <value>] [--target-dir <value>] [-t <value>] [--id <value>] [-r <value>]
    [-p developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fs
    l|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|net
    zero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--evidence <value>] [--push-to
    github|jira] [--dry-run] [--ticket <value>] [--risk-accept <value>]

FLAGS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnis
  tudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educati
  on|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      Completing setup-agents profile.

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

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

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

  --evidence=<value>
      Related evidence ids.

  --id=<value>
      Task id.

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

  --risk-accept=<value>
      Accept lifecycle risk and complete the task.

  --target-dir=<value>
      Workspace root to target (defaults to cwd).

  --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|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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.

    Id of the task. Alias: --id.

  --evidence=<value>  Related evidence ids.

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

  --id=<value>  Task id.

    Id of the task. Alias: --task.

  --risk-accept=<value>  Accept lifecycle risk and complete the task.

    Explicit rationale for overriding reconciliation blockers. The rationale and finding codes are appended to task
    history for audit. This does not create gate approvals.

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

_See code: [src/commands/setup-agents/task/done.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/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>] [--target-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>
      --target-dir=<value>  Workspace root to target (defaults to cwd).

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

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

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

## `sf setup-agents task update`

Update a setup-agents task (metadata or status).

```
USAGE
  $ sf setup-agents task update [--json] [--flags-dir <value>] [--target-dir <value>] [-t <value>] [--id <value>] [--status
    open|claimed|done|cancelled|blocked|archived] [--reason <value>] [-s <value>] [-r <value>] [-p
    developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai
    |slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero
    |nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries] [--evidence <value>]

FLAGS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnis
  tudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|educati
  on|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries
      New owner profile.

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

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

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

  --evidence=<value>
      Related evidence ids.

  --id=<value>
      Task id.

  --reason=<value>
      Reason for the status transition.

  --status=<option>
      Transition the task to this status.
      <options: open|claimed|done|cancelled|blocked|archived>

  --target-dir=<value>
      Workspace root to target (defaults to cwd).

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

DESCRIPTION
  Update a setup-agents task (metadata or status).

  Patches an existing task record in `.setup-agents/state/tasks.jsonl`. Use `--status` to transition the task to any
  valid state (open, claimed, done, cancelled, blocked, archived). Without `--status`, only metadata fields are patched.

EXAMPLES
  Update a task summary:

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

  Cancel a task that failed:

    $ sf setup-agents task update --task SA-97 --status cancelled --reason "Agent crashed with resource_exhausted"

  Block a task pending external input:

    $ sf setup-agents task update --task SA-97 --status blocked --reason "Waiting on PO acceptance criteria"

  Reassign a task:

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

  Transition using --id alias:

    $ sf setup-agents task update --id SA-97 --status done

FLAG DESCRIPTIONS
  -p, --profile=developer|architect|sa|pm|mulesoft|ux|cgcloud|qa|crma|commerce|data360|sfmc|salescloud|service|cpq|omnistudio|fsl|ai|slack|tableau|experience-cloud|release-manager|fsc|health|manufacturing|communications|automotive|education|netzero|nonprofit|public-sector|media|energy|revenue|maps|loyalty|industries

    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. Alias: --id.

  --evidence=<value>  Related evidence ids.

    Comma-separated evidence ids to attach to the task.

  --id=<value>  Task id.

    Id of the task. Alias: --task.

  --reason=<value>  Reason for the status transition.

    Free-text explanation for why the task was cancelled or blocked. Recorded in the JSONL event.

  --status=open|claimed|done|cancelled|blocked|archived  Transition the task to this status.

    Set the task status to open, claimed, done, cancelled, blocked, or archived. Use --reason to provide context for
    cancelled or blocked transitions.

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

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

## `sf setup-agents task view`

View a setup-agents task.

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

FLAGS
  -t, --task=<value>        Task id.
      --id=<value>          Task id.
      --target-dir=<value>  Workspace root to target (defaults to cwd).

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.

    Id of the task. Alias: --id.

  --id=<value>  Task id.

    Id of the task. Alias: --task.

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

_See code: [src/commands/setup-agents/task/view.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/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) for every configured runtime —
                       Cursor (.mdc), Claude and Codex (.md) — 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/v3.22.3/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|opencode] [--profile <value>]

FLAGS
  --profile=<value>                                                          Profiles to include in the probe
                                                                             (comma-separated).
  --rules=cursor|vscode|codex|claude|agentforce|windsurf|jetbrains|opencode  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/v3.22.3/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/v3.22.3/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|ta --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|ta>

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|ta  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/v3.22.3/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/v3.22.3/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/v3.22.3/src/commands/setup-agents/workflow/clarify-respond.ts)_

## `sf setup-agents workflow decompose`

Record a decomposition vote for a task.

```
USAGE
  $ sf setup-agents workflow decompose -t <value> --voter ba|ta --verdict proceed|decompose --reason <value> [--json] [--flags-dir
    <value>] [--splits <value>...]

FLAGS
  -t, --story=<value>      (required) Task or story id to vote on.
      --reason=<value>     (required) Reason for the verdict.
      --splits=<value>...  Suggested sub-story titles.
      --verdict=<option>   (required) Decomposition verdict.
                           <options: proceed|decompose>
      --voter=<option>     (required) Role casting the vote.
                           <options: ba|ta>

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

DESCRIPTION
  Record a decomposition vote for a task.

  BA and Architect independently assess whether a task is too large for a single sprint.
  Both must vote before consensus is reached. If either votes `decompose`, the task is
  escalated to an epic and the workflow pauses for sub-story creation.

  Consensus rules:

  - Both vote `proceed` → task continues as a story
  - Either votes `decompose` → task becomes an epic, workflow pauses

  Use `sf setup-agents task create --parent-id <epic-id>` to create subtasks after decomposition.

EXAMPLES
  BA votes to decompose a task:

    $ sf setup-agents workflow decompose --story sa-241 --voter ba --verdict decompose --reason "12 acceptance \
      criteria spanning 3 user journeys" --splits "User registration flow" --splits "Admin approval flow" --splits \
      "Notification integration"

  Architect votes to proceed:

    $ sf setup-agents workflow decompose --story sa-241 --voter architect --verdict proceed --reason "Single bounded \
      context, well-isolated from existing modules"

  Architect votes to decompose (escalates to epic):

    $ sf setup-agents workflow decompose --story sa-241 --voter architect --verdict decompose --reason "Requires 3 \
      new integrations and a schema migration" --splits "Schema migration" --splits "External API integration" \
      --splits "UI updates"

FLAG DESCRIPTIONS
  -t, --story=<value>  Task or story id to vote on.

    The task id that BA and Architect are evaluating for decomposition, e.g. `sa-241`.

  --reason=<value>  Reason for the verdict.

    Explain why the task should proceed or be decomposed. BA focuses on functional scope (acceptance criteria count,
    journey complexity). Architect focuses on technical scope (coupling, unknowns, integration surface).

  --splits=<value>...  Suggested sub-story titles.

    When voting `decompose`, provide suggested sub-story summaries. Repeat the flag for multiple splits.

  --verdict=proceed|decompose  Decomposition verdict.

    `proceed` if the task fits in a single sprint, or `decompose` if it should be split into sub-stories.

  --voter=ba|ta  Role casting the vote.

    Must be `ba` (functional complexity) or `architect` (technical complexity). Each role votes once.
```

_See code: [src/commands/setup-agents/workflow/decompose.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/workflow/decompose.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 xxs|xs|s|m|l|xl|xxl --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: xxs|xs|s|m|l|xl|xxl>
      --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=xxs|xs|s|m|l|xl|xxl  Story size label.

    T-shirt size in human-effort days: `xxs` (<4h) `xs` (4-8h) `s` (1-2d) `m` (3-5d) `l` (6-8d) `xl` (9-11d) `xxl`
    (12+d). `xxl` is a split gate — it cannot be estimated; break the story down first.

  --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/v3.22.3/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|opencode]
    [--from-phase pm|ba|architect|ux|developer|security-review|qa|document-review|release] [--dry-run] [--foreground]
    [--gates none|phase|all] [--max-iterations <value>] [--max-phase-minutes <value>] [--max-agents <value>]
    [--capability-signals qa evidence,release evidence] [--runtime-preference codex,claude,cursor,opencode]

FLAGS
  -s, --story=<value>                                    (required) Story or backlog item id.
      --capability-signals=qa evidence,release evidence  Additional runtime capability signals.
      --dry-run                                          Print what would be executed per phase without running.
      --foreground                                       Run the next phase inline and wait for it, even inside a chat
                                                         session that could dispatch it to the background instead.
      --from-phase=<option>                              Resume execution from this phase.
                                                         <options: pm|ba|architect|ux|developer|security-review|qa|docum
                                                         ent-review|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|opencode>
      --runtime-preference=codex,claude,cursor,opencode  Preferred runtime order for auto detection.

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 → Document Review → Release

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

  - `auto` — detects the first available runtime using `--runtime-preference`, then workspace
  `orchestration.runtimePreference`, then workspace `tools`, then claude, cursor, codex.
  - `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 Document Review→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

  Prefer Codex when auto-detecting:

    $ sf setup-agents workflow execute --story SA-102 --runtime auto --runtime-preference codex,claude,cursor

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

  --capability-signals=qa evidence,release evidence  Additional runtime capability signals.

    Additional task signals used to activate runtime capabilities for each phase prompt.
    Sub-agent handoff records are read automatically; this flag is only an explicit override/addition.
    For example: `qa evidence,acceptance criteria coverage,release evidence`.

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

  --foreground

    Run the next phase inline and wait for it, even inside a chat session that could dispatch it to the background
    instead.

    By default, when SETUP_AGENTS_BRIDGE_PORT, SETUP_AGENTS_BRIDGE_TOKEN, and
    SETUP_AGENTS_CHAT_SESSION_ID are present in the environment (all three are
    already set when this command runs from the web console chat's own Bash tool), the
    next phase is dispatched via the bridge's existing async spawn pipeline (the
    same one behind the console's own "Detached subagent" delegation) and this
    command returns immediately instead of waiting for it — only the NEXT phase
    is delegated, not the full remaining sequence; re-run with --from-phase
    <next> once notified the delegated phase completed. --foreground skips that
    and always runs inline, matching the pre-GH-746 behavior. Outside a chat
    session (CI, manual terminal use) those environment variables are simply
    absent, so this command already runs inline with or without --foreground.

  --from-phase=pm|ba|architect|ux|developer|security-review|qa|document-review|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 Document Review→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|opencode  AI runtime to use for phase execution.

    Select which AI CLI to invoke: `auto` (detect), `claude`, `cursor`, or `codex`.
    `auto` checks PATH using `--runtime-preference`, workspace `orchestration.runtimePreference`,
    workspace `tools`, then the fallback order claude → cursor → codex.

  --runtime-preference=codex,claude,cursor,opencode  Preferred runtime order for auto detection.

    Comma-separated runtime order used only when `--runtime auto` is selected.
    For Codex-preferred execution, pass `codex,claude,cursor` or set
    `orchestration.runtimePreference` in `.setup-agents/config.json`.
```

_See code: [src/commands/setup-agents/workflow/execute.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/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/v3.22.3/src/commands/setup-agents/workflow/gate.ts)_

## `sf setup-agents workflow lessons`

List canonical delivery, estimation, and operational lessons.

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

FLAGS
  --migrate         Migrate legacy lesson records into the canonical append-only store.
  --search=<value>  Filter lessons by keyword.

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

DESCRIPTION
  List canonical delivery, estimation, and operational lessons.

  Reads the canonical lesson projection and reconciles legacy operational lessons, estimation lessons, and lesson
  evidence without duplicates.

EXAMPLES
  List all lessons:

    $ sf setup-agents workflow lessons

  Search lessons by keyword:

    $ sf setup-agents workflow lessons --search "developer"

  Output as JSON:

    $ sf setup-agents workflow lessons --json

FLAG DESCRIPTIONS
  --search=<value>  Filter lessons by keyword.

    When provided, searches every canonical lesson field and source task id.
```

_See code: [src/commands/setup-agents/workflow/lessons.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/workflow/lessons.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/v3.22.3/src/commands/setup-agents/workflow/pending.ts)_

## `sf setup-agents workflow phase-plan`

Resolve and display the phase sequence for a story based on roles, profiles, and overrides.

```
USAGE
  $ sf setup-agents workflow phase-plan -s <value> [--json] [--flags-dir <value>] [--skip-phase
    pm|ba|architect|ux|developer|security-review|qa|document-review|release...] [--add-phase
    pm|ba|architect|ux|developer|security-review|qa|document-review|release...] [--require-gate
    pm|ba|architect|ux|developer|security-review|qa|document-review|release...] [--remove-gate
    pm|ba|architect|ux|developer|security-review|qa|document-review|release...] [--save]

FLAGS
  -s, --story=<value>             (required) Story/task ID to resolve the plan for.
      --add-phase=<option>...     Add a phase to the resolved sequence.
                                  <options: pm|ba|architect|ux|developer|security-review|qa|document-review|release>
      --remove-gate=<option>...   Remove the gate after the specified phase.
                                  <options: pm|ba|architect|ux|developer|security-review|qa|document-review|release>
      --require-gate=<option>...  Add a gate after the specified phase.
                                  <options: pm|ba|architect|ux|developer|security-review|qa|document-review|release>
      --save                      Persist the overrides to the task record.
      --skip-phase=<option>...    Skip a phase from the resolved sequence.
                                  <options: pm|ba|architect|ux|developer|security-review|qa|document-review|release>

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

DESCRIPTION
  Resolve and display the phase sequence for a story based on roles, profiles, and overrides.

  Merges the baseline phase registry with workspace profiles, task-declared roles, and phase overrides to produce a
  concrete execution plan. Useful for previewing which phases will run before starting a workflow.

  Sources of phase inclusion (in priority order):

  1. **Always-included** — developer, qa, release are always present.
  2. **Required roles** — task.roles.required maps to phases.
  3. **Optional roles** — task.roles.optional maps to phases.
  4. **Profile triggers** — workspace config profiles trigger matching phases.
  5. **Override add** — explicit `--add-phase` flags inject additional phases.

  Phase overrides (`--skip-phase`, `--add-phase`, `--require-gate`, `--remove-gate`) take final precedence.

EXAMPLES
  $ sf setup-agents workflow phase-plan --story SA-200

  $ sf setup-agents workflow phase-plan --story SA-200 --skip-phase ux --skip-phase pm

  $ sf setup-agents workflow phase-plan --story SA-200 --add-phase security-review --require-gate developer

FLAG DESCRIPTIONS
  -s, --story=<value>  Story/task ID to resolve the plan for.

    The task ID whose declared roles and phase overrides will be used for resolution.

  --add-phase=pm|ba|architect|ux|developer|security-review|qa|document-review|release...

    Add a phase to the resolved sequence.

    Force-include a phase regardless of role/profile signals. Can be specified multiple times.

  --remove-gate=pm|ba|architect|ux|developer|security-review|qa|document-review|release...

    Remove the gate after the specified phase.

    Removes a gate that would otherwise be present, allowing the workflow to continue without pausing.

  --require-gate=pm|ba|architect|ux|developer|security-review|qa|document-review|release...

    Add a gate after the specified phase.

    Forces a human-approval gate after this phase, even if the default gate configuration would not include one.

  --save  Persist the overrides to the task record.

    When set, writes the resolved phase overrides back to the task record so future `workflow run` invocations use them
    automatically.

  --skip-phase=pm|ba|architect|ux|developer|security-review|qa|document-review|release...

    Skip a phase from the resolved sequence.

    Remove a phase that would otherwise be included. Can be specified multiple times.
```

_See code: [src/commands/setup-agents/workflow/phase-plan.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/src/commands/setup-agents/workflow/phase-plan.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/v3.22.3/src/commands/setup-agents/workflow/playbooks.ts)_

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

Evaluate substantive project release readiness and record required check evidence.

```
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
  Evaluate substantive project release readiness and record required check evidence.

  Evaluates the latest workflow run for current substantive evidence, AC mapping,
  resolved phases and reviews, generated setup health, and knowledge freshness. The
  configured static-analysis checks are then run as additional required checks:

  - **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.

  Older project configs that omit evidence and substance modes migrate to fail-closed
  project defaults. Advisory mode is explicitly non-release-ready. Explicit `warn` or
  `off` values remain compatible for non-release transitions, but cannot make the
  production release predicate pass. Use `--dry-run` only to preview command output;
  it does not create release-ready workflow state.

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/v3.22.3/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|document-review|release
    [--json] [--flags-dir <value>] [--reason <value>] [--target-dir <value>]

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

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.

  For an `autonomous-v1` run, rollback preserves the run mode and retained evidence history. To
  disable autonomous execution, stop new autonomous starts and leave the run paused for manual
  review; do not reinterpret the persisted run as manual or delete its evidence, corrections, or
  approvals. Rollback does not approve, merge, push, publish, deploy, or release anything.

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|document-review|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/v3.22.3/src/commands/setup-agents/workflow/rollback.ts)_

## `sf setup-agents workflow run`

Run a multi-phase story workflow, with optional autonomous delegated execution and verification.

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

FLAGS
  -s, --story=<value>             (required) Story/task id — the same id you passed to `task create --id`.
      --autonomous                Run real verification checks and automatically correct failures.
      --dry-run                   Print the planned phase graph without executing.
      --findings=<value>          Rejection findings to pass as context to the target phase.
      --from-phase=<option>       Start the pipeline from a specific phase, skipping all prior phases.
                                  <options: pm|ba|architect|ux|developer|security-review|qa|document-review|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>
      --reject-to=<option>        Reject current phase and return work to a target phase.
                                  <options: pm|ba|architect|ux|developer|security-review|qa|document-review|release>
      --resume=<value>            Resume a paused workflow run.
      --target-dir=<value>        Workspace root to target (defaults to cwd).
      --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
  Run a multi-phase story workflow, with optional autonomous delegated execution and verification.

  Creates orchestration state for a story lifecycle across phases:

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

  Manual mode creates task records, handoffs, and gate pauses. With `--autonomous`, the same
  workflow controller invokes delegated phases, executes registered verification lanes, returns
  failures to Developer, and persists criterion-specific assertion evidence. Mandatory human
  architecture and final release gates remain enforced. Manual mode is the default.

  Autonomous verification records every governed lane as selected, excluded, or blocked with a
  reason. A substantive criterion is verified only by a registered verifier contract and evidence
  from the same run, iteration, and source digest. Required unavailable lanes block readiness.
  The loop stops after at most five attempts or two consecutive no-progress iterations.

  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 transition gates auto-approved in manual mode; invalid with `--autonomous`.
  - `phase` — human approval at BA→Architect and Document Review→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

  Opt in to autonomous verification with mandatory human gates:

    $ sf setup-agents workflow run --story SA-102 --autonomous --gates phase

  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/task id — the same id you passed to `task create --id`.

    The id to track throughout the workflow. This is the SAME id you registered with `task create --id <id>` — `workflow
    run` resolves that task's roles and phase overrides from it. e.g. `SA-102`, `#102`, or a `setup-agents-task-…` id.
    (Note: this is `--story`, not `--task`; the Orchestra CLI uses `--task` for the equivalent, but `sf setup-agents
    workflow` uses `--story`.)

  --autonomous  Run real verification checks and automatically correct failures.

    Opt in to the bounded autonomous-v1 delivery loop. QA derives pass/fail from a run-baseline
    changed-surface plan and criterion-specific verifier contracts in
    `.setup-agents/autonomous-verifiers.json`; generic lane success cannot verify a criterion.
    The validated scope/architecture and final release gates remain mandatory. The Web bridge
    exposes equivalent `POST /api/v1/workflows/autonomous/start` and `/resume` requests. Each lane
    is reported as selected, excluded, or blocked, and qualifying evidence is bound to run ID,
    iteration, and source digest. Execution stops after no more than five attempts or two consecutive
    no-progress iterations. The deterministic environment seam is test-only; production uses the
    configured delegated provider, and an unavailable required provider is a blocking deferral.

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

  --findings=<value>  Rejection findings to pass as context to the target phase.

    Free-text description of why the current phase is rejecting. This text is attached to the re-initialized target
    phase task so the responsible role has context about what needs to be fixed.

  --from-phase=pm|ba|architect|ux|developer|security-review|qa|document-review|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` (no transition gates in manual mode),
    `phase` (gate at BA→Architect and Document Review→Release, default), or `all` (every transition).
    `none` applies only to manual orchestration; autonomous-v1 rejects it because its two mandatory
    human gates cannot be disabled.

  --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 manual run that is in the QA phase. Autonomous mode derives the result from
    registered verification and does not accept caller-supplied QA as evidence.

  --reject-to=pm|ba|architect|ux|developer|security-review|qa|document-review|release

    Reject current phase and return work to a target phase.

    When resuming a paused run, reject the active phase and re-route work to the specified target phase with findings as
    context. The target phase will be re-initialized with rejection context so the role knows what to fix.

    Example: QA rejects back to developer:
    sf setup-agents workflow run --story SA-102 --resume wf-123 --reject-to developer --findings "Missing null check in
    handler"

    Example: Architect rejects back to BA:
    sf setup-agents workflow run --story SA-102 --resume wf-123 --reject-to ba --findings "Acceptance criteria
    incomplete"

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

  --target-dir=<value>  Workspace root to target (defaults to cwd).

    Explicit workspace directory for state writes. When omitted, uses the current working directory.
```

_See code: [src/commands/setup-agents/workflow/run.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/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/v3.22.3/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/v3.22.3/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/v3.22.3/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>] [--recalculate]

FLAGS
  -s, --story=<value>  Story id to scope the report to.
      --recalculate    Recompute effort summary from all recorded data.

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.

  --recalculate  Recompute effort summary from all recorded data.

    Re-reads all effort estimate records and recomputes the summary, including rules_multiplier.
```

_See code: [src/commands/setup-agents/workflow/telemetry.ts](https://github.com/jterrats/setup-agents/blob/v3.22.3/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>