Salesforce Orchestrator

Supervised GitHub Copilot agents for Salesforce development—directly inside VS Code.

Build features, fix bugs, improve tests, document metadata, and review Salesforce projects through @sforchestrator. A local Supervisor keeps work focused, controls permissions and handoffs, verifies recorded changes, and requires a final Salesforce review.

Agents can inspect and change the selected workspace. They cannot commit, push, deploy, or access arbitrary network services.

Why use it?

• Native Copilot Chat experience — start and follow work without switching to another agent application.
• Salesforce-focused roles — Planner, Architect, Developer, Test Engineer, and Reviewer have explicit responsibilities.
• Supervised execution — agents propose decisions; the local Supervisor owns routing, permissions, verification, and recovery.
• Safe workspace isolation — every run uses a fresh Git worktree by default.
• Review before completion — implementation cannot bypass Supervisor checks or final structured review.
• Visible and auditable — follow tool activity, handoffs, changed metadata, validation, token usage, and provider-reported GitHub AI Credits.
• No separate runtime setup for users — native packages include the Python backend and a verified GitHub Copilot CLI.

Quick start

1. Install the package matching your VS Code extension host.

2. Open and trust a Salesforce DX project inside a Git repository.

3. In GitHub Copilot Chat, run:

   @sforchestrator /settings
   

4. Confirm the repository and defaults, then select Save defaults.

5. Start a task:

   @sforchestrator /feature Add bulk-safe Opportunity renewal logic and Apex tests.
   

The extension uses VS Code's normal GitHub sign-in. Installed releases do not require Python, Node.js, uv, backend packages, a separate Copilot CLI, or a manual token file.

A supervised Salesforce workflow

The default Focused workflow is:

Request → Planner → Developer → Supervisor verification → Reviewer → Complete or correct

The Planner asks questions only when a missing decision blocks safe work. Implementation tasks normally require successful workspace-write evidence; when the requested behavior already exists, the Developer must verify and explicitly report that no change is required. The Reviewer still runs.

Reviewer findings become structured Developer corrections with fresh evidence and a new review. The Full team adds optional architecture guidance and a dedicated Test Engineer. Manual handoffs require Continue to … before each next role.

How it works

VS Code surfaces
      ↓ local JSON-RPC 2.0
Bundled Python Supervisor
      ↓ Microsoft Agent Framework (`GitHubCopilotAgent`)
GitHub Copilot SDK and service

The extension presents runs; the Python Supervisor owns routing, permissions, worktrees, state, verification, and recovery. Microsoft Agent Framework provides resumable agent execution and streaming over the GitHub Copilot SDK. Native tool calls still pass through the Supervisor's workspace and permission policy.

Detailed architecture and local protocol references are maintained under docs/ in the source repository.

Chat commands

Work safely

The recommended Isolated worktree mode starts from committed HEAD. Your original checkout remains untouched until you explicitly select Bring changes to original repo after the run finishes. That action copies only Supervisor-recorded files and stops if the original checkout has overlapping edits. You review and commit the result yourself.

Current checkout mode is available when you intentionally want agents to edit the open repository, including its uncommitted state. The UI highlights this mode, and the backend prevents two active runs from owning the same checkout.

Permission profiles control preapproval but cannot override hard policy:

• paths must remain inside the assigned workspace;
• sensitive credential files cannot be edited and sensitive reads require approval;
• commits, pushes, destructive shell activity, and mass deletion are denied;
• general agent network access is denied;
• Salesforce org validation is a separate, explicit Supervisor action.

The complete security and data-handling model is maintained in docs/security-and-data.md in the source repository.

Everything stays visible

The Salesforce Orchestrator Activity Bar contains GitHub Account, Runs, AI Token Usage, and Live Activity views. The run-specific Workflow panel shows:

• status, current stage, agent pipeline, and review result;
• approvals, Planner questions, and manual handoffs;
• pause, resume, retry, cancel, and JSON log export;
• changed Salesforce metadata and optional validation results;
• models, permissions, sessions, context usage, and loaded skills;
• worktree inspection, apply, and failed-worktree cleanup actions.

Orchestration Settings remains separate, so changing defaults cannot silently modify a run already in progress.

Configuration and runtime

Save defaults for the team, workspace mode, handoffs, models, guidance, repository Markdown rules, shared/per-role skills, tool permissions, optional Salesforce validation, and safe diagnostic detail. Org validation is disabled by default and, when enabled, is executed by the Supervisor before review—not by an agent.

Every native package includes a known-good Copilot CLI baseline. Explicit updates use private VS Code storage with one rollback slot and never overwrite the installed extension. Runtime maintenance is blocked while a workflow is active.

The source repository contains detailed configuration, agent rules and skills, Salesforce validation, operations, and troubleshooting references under docs/.

Requirements and privacy

Requires VS Code 1.96 or newer, GitHub Copilot access, and a trusted Salesforce DX Git repository. Isolated mode requires at least one commit. Install the native package matching the local or remote VS Code extension host. The Salesforce CLI is needed only for org discovery and optional validation.

The GitHub access token remains only in backend memory. Durable diagnostics exclude raw streamed model text, file contents, and arbitrary tool results, but downloaded run logs can contain task text, paths, rule snapshots, redacted commands, changed filenames, and other operational metadata. Inspect exports before sharing.

Learn more

Complete user, configuration, operations, security, architecture, protocol, and release documentation is maintained in the source repository's docs/ directory.