Salesforce Orchestrator

Salesforce Orchestrator runs supervised GitHub Copilot agents for Salesforce development directly inside VS Code.

Use @sforchestrator to build features, fix bugs, create tests, document metadata, or review an existing change. Planner, Salesforce Architect, Salesforce Developer, Test Engineer, and Salesforce Reviewer are specialized roles inside one Supervisor-owned workflow. The model can propose work and use tools, but it does not control routing, permissions, final verification, or run state.

Agents can inspect and, when their role permits it, change the assigned workspace. They cannot commit, push, deploy directly, access arbitrary network services, or override the Supervisor's hard safety policy.

Why use it?

• Native Copilot Chat — start work through @sforchestrator and follow the same run in Chat, the Activity Bar, or the Workflow panel.
• Salesforce-specific roles — each role has a bounded responsibility, permission profile, rules, skills, and resumable Copilot session.
• Deterministic supervision — Python code, rather than model prose, owns valid handoffs, state transitions, approvals, retries, and completion gates.
• Workspace isolation — implementation runs use a fresh Git worktree by default; the original checkout changes only after an explicit apply action.
• Structured review — a Developer cannot bypass recorded-change checks or the final Salesforce Reviewer.
• Auditable evidence — the UI exposes role activity, tool decisions, changed metadata, feature-document usage, skills, validation, model usage, and provider-reported GitHub AI Credits.
• Packaged runtime — release VSIX files include the Python backend and a tested GitHub Copilot CLI baseline; users do not install Python or Node dependencies.

Quick start

1. Install the VSIX matching the operating system and architecture of the VS Code extension host.

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

3. Open GitHub Copilot Chat and run:

   @sforchestrator /settings
   

4. Confirm the repository, workspace mode, roles, permissions, and optional context sources, 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 GitHub authentication provider. Installed builds do not require a token file, a separate Copilot CLI installation, or a user-managed Python environment.

Architecture and communication layers

User and Copilot Chat
        │
        ▼
VS Code extension (TypeScript)
  commands · settings · webviews · sidebar projections
        │ newline-delimited JSON-RPC 2.0 over local stdin/stdout
        ▼
Bundled orchestrator (Python)
  Supervisor · state · worktrees · permissions · verification
        │
        ▼
Microsoft Agent Framework
  GitHubCopilotAgent · streamed turns · resumable sessions
        │
        ▼
GitHub Copilot SDK / packaged Copilot CLI
  model inference · native tools · native skills · usage events
        │
        ▼
Assigned Salesforce workspace

Layer	Owns	Does not own
TypeScript extension	Chat participant, commands, Settings and Workflow webviews, sidebar views, authentication handoff, JSON-RPC client, and UI projections	Agent routing, permission decisions, or authoritative run state
Local JSON-RPC transport	Typed requests, responses, errors, and live run notifications over the backend process's private standard streams	A public, remote, or network API
Python orchestrator	Run state, role routing, worktrees, permission enforcement, persistence, recovery, changed-file evidence, and optional Salesforce validation	Model inference or GitHub authentication ownership
Microsoft Agent Framework	GitHubCopilotAgent lifecycle, streamed normalized content, custom function tools, and resumable service sessions	The application's workflow graph or final completion decision
GitHub Copilot SDK and CLI	Model execution, native repository tools, native skill loading, context and usage telemetry	Permission bypasses, valid handoffs, or Salesforce deployment policy

The extension starts backend/<platform>-<architecture>/salesforce-orchestrator from the installed package. In an Extension Development Host, it can fall back to the adjacent Python virtual environment. Communication is newline-delimited JSON-RPC 2.0: TypeScript sends methods such as system.ping, system.authenticate, run.start, and run.get; Python returns results and publishes ordered event notifications.

Startup follows this sequence:

1. TypeScript starts the bundled or explicitly overridden backend.
2. system.ping verifies protocol compatibility.
3. VS Code obtains the selected GitHub session.
4. The token is sent once through the private local pipe with system.authenticate.
5. Python retains the token only in memory and passes it to individual Copilot sessions.
6. Saved runs, events, models, and usage are projected into the VS Code UI.

The backend is authoritative. Closing a panel does not stop a run, and reopening a panel does not replay or advance it. UI state is reconstructed from the persisted run snapshot plus its ordered event stream.

How an agent is assembled

The roles are configurations, not independent background processes. Only one role owns the active workflow step. Every role receives a bounded combination of the following layers:

Context layer	Purpose	Scope
Hard safety and control contract	Non-overridable tool, routing, output, and completion rules	Every role and run
Built-in role and task-mode instructions	Planner, Architect, Developer, Test Engineer, or Reviewer behavior for feature, fix, review, tests, or documentation work	Active role
.sforchestrator/agents/shared.md	Durable repository conventions that every role must follow	Every role
Role Markdown file	Role-specific repository conventions	Matching role only
Saved and per-run guidance	Workspace defaults and task-specific instructions	Configured run or role
Steering	One-use user guidance for the active role; running turns are interrupted and restarted, while paused agent turns queue it for Resume	Current role only; same session and worktree
Explicit skills	Reusable procedural instructions loaded and verified through native Copilot skill support	Shared or assigned role
Feature catalogue and selected feature documents	Optional business-process evidence chosen semantically for the task	Catalogue for active roles; full documents only after selection

Hard policy always wins. Repository Markdown, skills, feature documents, and model output cannot expand permissions, authorize an invalid handoff, or bypass a Supervisor gate.

Repository layout

.sforchestrator/
├── agents/
│   ├── shared.md
│   ├── planner.md
│   ├── architect.md
│   ├── developer.md
│   ├── test-engineer.md
│   └── reviewer.md
├── features/
│   ├── index.md
│   └── one-or-more-business-processes.md
├── skills/
│   └── custom-skill/SKILL.md
└── salesforce-skills/
    └── managed-skill/SKILL.md

All of these files belong to the repository. The extension package does not embed or upload project-specific rules, skills, or feature documents.

Agent Markdown rules

The Markdown agent rules editor reads and writes .sforchestrator/agents/.

• shared.md applies to every role. Use it for repository-wide conventions such as Apex sharing policy, naming, packaging, test standards, and common definition-of-done requirements.
• planner.md, architect.md, developer.md, test-engineer.md, and reviewer.md apply only to their matching roles.
• Missing files are represented by small templates in Settings but are not created until Save Markdown rules is selected.
• Rules are snapshotted into the run at start. Editing them later affects new runs, not an already-running workflow.
• Rule contents are persisted in the local run record for auditability. Do not put secrets, tokens, credentials, or private keys in them.

shared.md should not contain a pointer to the feature catalogue. Feature documentation is injected independently when enabled; adding the pointer to shared rules would duplicate context and incorrectly mix mandatory instructions with optional business evidence.

Skills

Skills are reusable instruction packages centered on SKILL.md. They are different from agent rules and feature documentation:

• Shared skills are configured once and supplied to every role.
• Per-agent skills are supplied only to the selected role.
• Explicitly configured skills are mandatory. The backend checks native skill discovery and invocation evidence; a missing required skill does not fail open.
• Standard repository roots such as .github/skills, .copilot/skills, .agents/skills, .sforchestrator/skills, and .orchestrator/skills remain discoverable even when they are not explicitly selected.
• Paths are stored repository-relative and must stay inside the repository.

Install and assign copies the version-pinned Salesforce skills and the bundled review skill into .sforchestrator/salesforce-skills/ without overwriting existing folders. It then fills the standard role cards:

Role	Managed assignment
Salesforce Architect	Apex generation
Salesforce Developer	Apex generation and Apex test generation
Test Engineer	Apex test execution and log debugging
Salesforce Reviewer	Read-only Apex review

Select Save defaults after installing or changing assignments. In isolated-worktree mode, explicitly selected skill folders are snapshotted into the new worktree, allowing a newly installed but uncommitted skill to be used. Other ordinary uncommitted project files are not copied into that worktree.

Project feature documentation

Feature documentation connects business-process Markdown to a run without turning it into always-on instructions or a skill.

The source is fixed:

.sforchestrator/features/
└── index.md

Settings provides Create feature catalogue for first-time setup. It creates .sforchestrator/features/index.md plus a linked example-feature.md starter inside the folder currently selected in Git repository; it does not use the extension workspace as a fallback. The action does not enable the source or overwrite an existing catalogue. Replace or remove the clearly marked example before enabling feature documentation for real work.

index.md uses normal Markdown links whose targets are relative to the catalogue. Every link should include a short semantic scope description:

Link text	Relative target	Semantic scope description
Contract renewals	renewals.md	Expiry, renewal opportunities, cancellations, pricing, and owner handoff
Customer onboarding	onboarding.md	Account activation, compliance, provisioning, and welcome tasks

The selection flow is:

1. At run preparation, Python validates the fixed folder and catalogue in the actual assigned workspace.
2. Only the catalogue and canonical linked paths enter the initial agent context; the complete feature files do not.
3. The model compares the user request semantically with the descriptions in index.md and calls resolve_feature_documentation.
4. selected loads only the chosen allowlisted Markdown through a bounded custom tool.
5. no_match means business documentation could be relevant but the catalogue has no matching entry. It is valid and does not fail the run.
6. not_applicable means the task does not require business-process documentation. It is also non-failing.
7. Later participating roles call consult_feature_documentation when documents were selected, or independently confirm a negative decision. A selected document is delivered once per unchanged role/provider session; later turns reuse that evidence, while a replaced session or changed selection must consult again.

There is no keyword matcher, embedding database, RAG service, or hidden copy of project documents. The model decides using the catalogue text; the Supervisor enforces the structured decision and the linked-file allowlist.

The Workflow panel shows the global selection, reason, and per-role status:

• Consulted — the listed documents entered that role's context.
• Confirmed — that role recorded no_match or not_applicable.
• Pending — the role has participated but has not yet supplied the required evidence.
• Not involved — the role has not participated in the run.

An empty but readable index.md is valid and can resolve to no_match. A missing folder or index, an invalid UTF-8 catalogue, a broken or escaping link, or a symbolic link is a configuration error. Linked-document size and UTF-8 validity are enforced before that document can enter agent context. Unlisted Markdown is reported in Settings and the Workflow panel but cannot be selected. Limits are 500 documents, 100 KiB for the catalogue, 250 KiB per document, and 400 KiB total selected content for one role.

In isolated-worktree mode, feature documentation comes from committed HEAD. Commit newly added feature documents before starting a run, or intentionally use current-checkout mode. If the catalogue changes during a run, the backend refreshes the allowlist and invalidates the previous semantic resolution before the next role turn.

Roles and workflow

Role responsibilities

Role	Default permission	Responsibility
Planner	Read-only; repository tools initially disabled	Clarify blocking requirements, create a bounded plan, and request targeted repository evidence only when necessary
Salesforce Architect	Read-only	Review and, when needed, revise the native Markdown plan in every Full-team run
Salesforce Developer	Edit assigned workspace	Implement, verify existing behavior when no change is required, and submit structured completion evidence
Test Engineer	Edit assigned workspace	Investigate concrete failures, create or adjust tests, and return evidence to Developer
Salesforce Reviewer	Read-only	Review the current bounded change evidence and submit an authoritative structured approval or blocking findings

Task modes

Chat command	Initial route
/feature	Planner → implementation → verification → Reviewer
/fix	Planner → focused implementation → verification → Reviewer
/tests	Developer starts directly; Test Engineer may participate in a Full team
/docs	Developer starts directly and changes documentation based on repository evidence
/review	Read-only Reviewer only, against the current checkout including pending and untracked files
/status	Opens or reports the active run without creating a new one
/settings	Opens defaults for future runs

The default Focused team uses Planner, Developer, and Reviewer. The Full team requires Architect between Planner and Developer and also makes Test Engineer available for valid implementation handoffs. The Supervisor rejects routes that do not belong to the active team and mode.

Prepare repository
      ↓
Planner and mandatory Architect in Full
      ↓
Developer and optional Test Engineer
      ↓
Supervisor change verification
      ↓
Optional Salesforce org validation
      ↓
Fresh Reviewer
      ├── approved → succeeded
      └── blocking findings → fresh Developer correction → verify → review again

Planner and Architect manage flexible Markdown with Copilot's native plan mode and finish through submit_planner_result or submit_architect_result; printed JSON is never their protocol. The Planner may use at most two focused clarification rounds, with up to three questions in each, only when missing requirements block safe progress. When behavior depends on business context, the plan and handoff retain a concise source, assumption, and expected-outcome note. The Planner starts with no repository tools and may request one targeted read-only inspection. Automatic handoffs continue immediately. Manual handoffs store the proposed transition and wait for Continue to … in Chat, the sidebar, or the Workflow panel.

User steering

Steer corrects the role currently executing the run. In running, it interrupts the active turn and starts a new turn for the same role, reusing its resumable Copilot session and assigned worktree. When an agent turn is paused, it stores one pending instruction and waits for Resume. A later instruction replaces the pending one, and the instruction is not repeated on later turns.

Steering preserves workspace writes completed before interruption and does not recover tokens already spent. It is available only while an agent turn is running or paused; it does not redirect to Planner, Architect, Developer, or another role and does not replan the workflow.

Developer completion requires successful repository-write evidence unless the Developer explicitly verifies that the requested behavior already exists and submits no_changes_required. The Reviewer still runs. When review requests changes, the next Developer round must provide fresh write evidence; old changes cannot satisfy the correction. Repeated no-progress responses and unchanged handoff loops are bounded and eventually stop with recoverable evidence instead of running indefinitely.

Permissions and safety boundaries

Permission profiles define preapproval, not authority beyond hard policy.

Profile	Preapproved	Still asks or denies
Read-only	Workspace read/search and classified read-only shell commands	Sensitive reads ask; writes, deletion, unsafe shell, and network are denied
Edit files in assigned workspace	Read/search, structured edits, single-file deletion, and safe read-only shell	Sensitive edits, mass deletion, mutating or unclassified shell, network, commit, and push are denied
Ask for every permitted action	Nothing ordinary is preapproved	Every otherwise eligible action asks once; hard denials remain impossible to approve

Every native tool call passes through Supervisor-owned pre-tool and permission checks. Paths are normalized and must stay inside the assigned workspace. Tool classification, the active role, its saved profile, sensitive-path policy, and workspace ownership all participate in the decision.

Hard restrictions include:

• no commit or push;
• no arbitrary network access by agents;
• no destructive or unclassified shell command and no shell-based repository mutation;
• no mass deletion;
• no edit of sensitive credentials;
• approval required for permitted sensitive reads;
• no access outside the assigned workspace;
• no direct agent deployment or org test execution.

Structured control tools such as Planner results, Developer completion, review submission, feature-document resolution, and consultation are preapproved because they update bounded Supervisor state; they do not grant repository or network access.

Workspace modes

Isolated worktree — default

A run starts from committed HEAD in a managed Git worktree. The original checkout remains untouched while agents work. When the run is terminal, Bring changes to original repo copies only Supervisor-recorded paths after checking for overlapping local edits, path escapes, symbolic links, file-count limits, and size limits. It does not commit the result.

Use Open in new window to inspect or recover a run worktree. Delete worktree removes it after a terminal run. Permanently deleting a run also removes any remaining isolated worktree after confirmation.

Current checkout

Agents work directly in the selected repository, including its uncommitted state. The UI displays a warning, and the backend prevents concurrent active runs from owning the same checkout. Review-only mode always uses the current checkout so Reviewer can inspect pending and untracked changes.

Settings reference

Saved defaults are scoped to the current VS Code workspace and affect only new runs.

Run defaults

Setting	Behavior
Default agent team	Focused or Full; review commands force review-only routing
Workspace mode	Isolated worktree or current checkout
Agent handoffs	Automatic or manual confirmation before each transition
Review Planner plan before handoff	Optional Markdown edit/approve/reject gate after Planner, or after Architect in Full; approval also confirms the Developer handoff
Git repository	Selected Salesforce DX Git repository; isolated mode requires at least one commit

Models and guidance

Setting	Behavior
Per-agent model	Copilot default, explicit Copilot Auto, or one model returned by the authenticated Copilot service
Per-agent reasoning effort	Uses the selected model's default unless a supported level is selected; Copilot default and Auto remain provider-managed
Default shared guidance	Free-form guidance included in every new run for this workspace
Markdown agent rules	Loads and saves .sforchestrator/agents/*.md independently from ordinary defaults

There is no shared model fallback. Every role defaults to Copilot default, which omits the SDK model option and preserves the provider/account default. Copilot Auto is different: it explicitly sends auto to activate Copilot's automatic model router. Choosing a concrete model enables a reasoning selector populated only with that model's supported levels; leaving it at Model default sends no reasoning override.

The configured selection, provider-resolved model, effective reasoning level, and source are visible per agent in the Workflow panel and downloaded run log. Model discovery requires an authenticated GitHub account with access to the Copilot SDK/CLI agent capability.

Skills and feature documentation

Setting	Behavior
Shared skill files	Mandatory skills for every role
Per-agent skill cards	Mandatory skills for one role
Install and assign	Installs pinned Salesforce skill copies and fills standard role assignments
Enable project feature documentation	Activates .sforchestrator/features/index.md for new runs; path fields are fixed and read-only
Create feature catalogue	Non-destructively creates a starter index.md and linked example-feature.md; it does not enable the source

Settings previews discovered and unlisted feature documents. Save defaults rejects an enabled source whose fixed folder or catalogue is invalid.

Optional Salesforce verification

Setting	Default	Behavior
Target org	None	Authenticated Salesforce alias used only by enabled Supervisor validation
Allow Salesforce Code Analyzer	Off	Lets an agent run it only when explicitly requested; it is not an automatic gate
Apex test level	Don't run tests	Applied only inside enabled deployment validation
Validate deployment against target org	Off	Runs Supervisor-owned sf project deploy validate before review

Test levels are NoTestRun, RunSpecifiedTests, RunLocalTests, and RunAllTestsInOrg. Run changed Apex tests automatically maps to RunSpecifiedTests; the Supervisor selects recorded changed Apex test classes and falls back to RunLocalTests when none are found.

Enabling org validation does not grant network access to agents. Python invokes Salesforce CLI directly, outside the model tool channel. It verifies the target connection at run start, retains only bounded alias/username status, validates the detected package directory inside the workspace, and returns failed validation evidence to Developer. A missing Salesforce CLI is reported as skipped rather than represented as a successful validation.

Diagnostics and managed runtime

Setting or action	Behavior
Diagnostic logs	error, info, or bounded debug events in the Output channel
Refresh models/orgs	Requeries the authenticated local provider or Salesforce CLI discovery
Check for Copilot CLI update	Validates a newer runtime in temporary staging before activating it
Use included version	Removes the managed update and returns to the packaged baseline
Restart backend	Restarts the local process and recovers durable runs safely

Managed CLI maintenance is blocked while a workflow is active. Updates use private VS Code storage and never overwrite files inside the installed extension.

Advanced VS Code settings normally remain empty:

Key	Purpose
copilotOrchestrator.backendExecutablePath	Development/recovery override for the bundled backend
copilotOrchestrator.copilotCliPath	Application-scoped override for the managed Copilot CLI
copilotOrchestrator.logLevel	Structured Output-channel detail; default info

Verification and completion gates

The extension does not discover arbitrary validation commands from package.json or YAML, and it does not silently execute local build, lint, analyzer, or test scripts. Repository changes are evidenced by successful bounded tool events.

The normal completion gates are:

1. The active role satisfies mandatory skill and feature-document requirements.
2. Developer submits a structured result.
3. The Supervisor verifies fresh workspace-change evidence or a verified no-change result.
4. Optional Supervisor-owned Salesforce deployment validation runs when enabled.
5. Reviewer receives bounded current changed-file evidence and submits a structured decision.
6. Approval marks the run succeeded; blocking findings create a fresh correction round.

Missing or invalid Planner, Architect, Developer, or Reviewer structured output follows a bounded protocol-recovery path: one corrective retry uses a fresh session, and a repeated failure pauses the run while preserving workspace changes, captured plan revisions, and audit evidence. Missing feature-document resolution or consultation receives its own corrective retry. Missing mandatory skill evidence fails closed with diagnostics instead of silently continuing. Salesforce validation failures and review findings return bounded actionable evidence to Developer.

Workflow panel and Activity Bar

The Salesforce Orchestrator Activity Bar contains:

• GitHub Account — selected identity, authentication state, and Copilot agent-access readiness.
• Runs — recent durable workflows and actions.
• AI Token Usage — terminal-run token totals and provider-reported AI Credits.
• Live Activity — current structured milestones, tools, approvals, handoffs, and failures.

The run-specific Workflow panel shows:

• status, task mode, current stage, role pipeline, and counters;
• pause, resume, steer, retry, cancel, log download, and manual handoff controls;
• Planner questions, native Markdown plan review/edit/approve/reject, permission approvals, and user steering state;
• feature-document selection and consultation per agent;
• configured and loaded skills per agent;
• configured model selection, model used, reasoning level/source, Copilot session, permission profile, and effective tool access per agent;
• token usage and current context-window telemetry per agent;
• changed Salesforce metadata, validation status, and structured review findings;
• isolated-worktree open, apply, and cleanup actions.

Orchestration Settings is a separate panel. Saving it cannot silently mutate a run already in progress because every run snapshots its effective configuration and repository rules at start.

Persistence, logging, and privacy

Python stores authoritative run snapshots and immutable plan revisions in SQLite and ordered per-run events in JSONL under VS Code global storage. Steering instructions are persisted in the run snapshot and event history. Restart recovery pauses unsafe in-flight operations, clears stale approvals, preserves manual handoffs and plan-review waits, and resumes model work only after GitHub authentication is restored.

The GitHub token is memory-only. Durable diagnostics exclude raw streamed model text, feature-document contents, repository file contents, and arbitrary tool results. Logs retain bounded operational metadata such as task text, repository paths, rule snapshots, selected filenames, steering messages, redacted command evidence, handoffs, status, usage, and errors. Do not put secrets, tokens, credentials, or private keys in steering messages; review downloaded JSON logs before sharing them.

Permanently deleting a terminal run removes its state, event journal, diagnostics, and remaining worktree after confirmation. A compact aggregate of timestamps, token totals, and provider-reported AI Credits remains for the usage view.

Requirements

• VS Code 1.96 or newer.
• A trusted Salesforce DX project in a Git repository.
• GitHub Copilot access, including any organization policy required for Copilot SDK/CLI agents.
• At least one Git commit when using isolated-worktree mode.
• A native VSIX matching the local or remote extension host platform.
• Salesforce CLI only for org discovery and optional Supervisor-owned org validation.

Troubleshooting checklist

• If sign-in or model discovery fails, select the GitHub account again and confirm that organization policy permits Copilot SDK/CLI agents.
• If a repository is rejected, verify Git, sfdx-project.json, and committed HEAD for isolated mode.
• If feature documentation is not available in isolated mode, commit .sforchestrator/features/ or use current-checkout mode intentionally.
• If a mandatory skill fails, verify the selected directory contains SKILL.md, remains inside the repository, and contains no unsafe symbolic links.
• If org validation fails, verify sf, the target alias, package directory, and authentication outside the agent workflow.
• If a run is interrupted by reload or backend restart, inspect its recovered state and use Resume or Retry as appropriate.
• Use Salesforce Orchestrator: Show Logs and Download log for bounded diagnostic evidence.

Source documentation

The source repository's docs/ directory contains the detailed architecture, protocol, configuration, security, validation, operations, troubleshooting, and release references used to maintain this extension.