Skip to content

Set up Forge Agent Plugins

Install the forge plugin for day-to-day development skills and the Forge and Mosaic MCP servers. Add forge-planning when you want planning and pre-implementation review skills. Install and verify the SAIF CLI first: the Forge MCP registration launches the bare saif executable and cannot bootstrap it for you.

Shipped packages

Package Choose it for
forge Building and delivering Forge applications, with read-only command, documentation, and service discovery through MCP
forge-planning Optional requirements, decisions, implementation plans, technical spikes, and bounded plan review

The package manifest owns the skill inventory. Read an individual skill's SKILL.md in the authoring tree for its instructions; this guide does not maintain a second inventory. The marketplace catalog owns package defaults.

Skills load when the task matches their description. Skills marked user-invocable: true also support direct invocation in hosts with slash commands. Repo-maintenance skills remain local to the Forge repository rather than shipping in either package.

Azure operations are intentionally out of scope

Forge's package boundary excludes Azure operations skills such as role selection, cost optimization, resource health diagnosis, and Entra agent-user management. See ADR 0012; use the Azure-owned distribution for those workflows.

Installing

Install the Forge plugin packages

With saif on your PATH, configure detected VS Code and GitHub Copilot hosts:

saif --version
saif agent init

agent init registers the packages you select. On an interactive terminal it shows a checklist with saved choices preselected: press Space to toggle a package and Enter to accept. On first use, catalog defaults select forge and leave forge-planning clear. The packages are independent, so selecting planning does not enable forge, and clearing both disables both without uninstalling. When it detects GitHub Copilot, it also installs enabled packages that lack an installed plugin.json. It copies files directly to the Copilot plugin cache to avoid a Windows directory-rename failure (Access is denied. (os error 5)) that can affect copilot plugin install. It prints equivalent manual install commands for every enabled package whether or not that direct installation ran, and prints none when you disable every package. Re-running init does not update an already-installed package; use doctor for updates.

Select plugins

Rerun saif agent init to change the selection. For scripts, pass the complete desired set with --plugins, or keep saved choices without prompting:

# Enable both packages
saif agent init --plugins forge forge-planning

# Keep development skills and disable planning
saif agent init --plugins forge

# Enable only planning, or disable both without uninstalling
saif agent init --plugins forge-planning
saif agent init --plugins none

# Retain saved choices, using catalog defaults only for missing entries
saif agent init --no-interactive
Option Behavior
--plugins Complete set of package names to enable, space-separated or supplied through repeated options. The command disables any catalog package you omit. Use none alone to disable all. Unknown names, a missing value, or combining none with package names fail before configuration changes. Explicit --plugins bypasses the checklist in every scope.
--no-interactive Global option. Skips the checklist and retains the resolved saved selection, using catalog defaults only for missing entries. Redirected input behaves the same way, and a terminal without ANSI support also retains the selection and prints guidance to use --plugins.

Saved choices come from the Copilot user settings file, honoring COPILOT_HOME and the configured filename. In project scope, explicit workspace plugin booleans take precedence over user choices; missing entries inherit user choices, then catalog defaults. User scope ignores workspace selections.

Disabling writes false to enabledPlugins without deleting installed files. Repeating the same selection does not rewrite unchanged settings or reinstall cached packages. Disabling forge also turns off its bundled skills and MCP integrations in hosts that honor the selection; it does not disable independently configured MCP servers.

Host activation overrides still apply

Init manages declarative plugin settings, not every host's activation controls. VS Code stores enable/disable state separately from shared workspace configuration; use its Agent Plugins view to change that state. Copilot repository settings and managed policies can override user-level plugin choices. Init does not modify those managed policies or VS Code's private state.

Historical command

saif mcp init remains a hidden compatibility alias through Forge 3.x. It prints a deprecation warning and forwards to saif agent init; the compatibility shim schedules removal for Forge 4.0. Use the new command in scripts and instructions.

For a manual install, or to opt into the planning package:

copilot plugin marketplace add saif-corp/forge
copilot plugin install forge@forge

# Optional planning package
copilot plugin install forge-planning@forge

The catalog is Copilot's distribution entry point; the portable package payloads live under .github/plugins/forge/ and .github/plugins/forge-planning/.

Scope targets

The default scope is user-level and applies across repositories on the machine. Use --local or --scope project for shared workspace plugin settings:

saif agent init --local
saif agent init --workspace-root C:\repos\my-service --scope project

--workspace-root defaults to the git root or current directory. The CLI resolves it even in user scope because optional Copilot permissions use a repository key. --local cannot combine with an explicit --scope user.

Setting User scope (default) Project scope
VS Code marketplace discovery Detected Stable/Insiders user profile settings.json, under chat.plugins.marketplaces Not written
Shared workspace plugin selection Not written .github/copilot/settings.json, with extraKnownMarketplaces and enabledPlugins
Copilot CLI and app plugin selection ~/.copilot/settings.json, with extraKnownMarketplaces and enabledPlugins Same user-level file
VS Code approval rules, only with --grant-permissions User profile settings.json .vscode/settings.json
Copilot CLI approval rules, only with --grant-permissions ~/.copilot/permissions-config.json, keyed by repository Same user-level file and repository key

COPILOT_HOME relocates the Copilot configuration root. VS Code user profiles live under %APPDATA%\Code\User\ on Windows, ~/Library/Application Support/Code/User/ on macOS, and $XDG_CONFIG_HOME/Code/User/ (or ~/.config/Code/User/) on Linux. Insiders uses Code - Insiders.

Migrating an earlier MCP setup

Forge's current agent initialization no longer reads or writes the former ~/.copilot/mcp-config.json registration. Its Copilot scanner registers plugins in settings.json instead. Verify the new plugin setup before cleaning up an old Forge entry, and preserve any unrelated MCP server definitions. This change to Forge's registration does not establish whether a host still uses that file for other servers.

Project scope does not isolate every setting

Committing .github/copilot/settings.json shares that plugin selection with collaborators; init writes it only when VS Code is detected. Copilot CLI and app settings and CLI permission grants still use user-level files regardless of --scope, so changing a project-scope selection can also affect other repositories.

Permissions are a separate opt-in

Prefer Forge MCP tools such as list_commands, get_command, search_docs, and search_services for read-only lookups. Plugin setup registers those tools without granting direct shell execution.

Only if you want the agent to execute saif through the shell, opt in:

saif agent init --grant-permissions

Copilot CLI approval trusts the whole SAIF CLI

VS Code generates per-command chat.tools.terminal.autoApprove rules, allowing read-only commands and explicitly denying mutating commands. Copilot CLI's saif grant approves every subcommand, including mutations such as pipeline approval and token generation. An individual saif subcommand deny rule cannot narrow that bare-command grant. agent init prints the mutating commands covered by this approval so you can review its breadth.

To review or revert permissions, inspect chat.tools.terminal.autoApprove in the VS Code file for your chosen scope. For Copilot CLI, remove the {"kind": "commands", "commandIdentifiers": ["saif"]} entry under locations.<repo-key>.tool_approvals in permissions-config.json. Do not remove unrelated approvals.

Verify installation

  1. Confirm saif --version works in the host's environment, not only in an unrelated terminal.
  2. Check that the detected host's settings contain the Forge marketplace and intended plugin selection.
  3. Check the installed packages under ~/.copilot/installed-plugins/forge/ (or the relocated Copilot root). Each installed package should have plugin.json.
  4. In the agent host, check for Forge skills and the Forge MCP tools, then ask it to look up a SAIF command through get_command.

VS Code discovers plugins in the Copilot installed-plugin directory. Its marketplace setting supports browsing additional packages; it is not a separate copy of the installed plugin. If init did not detect a supported host or reported a scanner/install failure, address that message and use the printed install command after the host becomes available.

Review the active plan

After installing forge-planning, invoke:

/review-plan

The skill uses the active issue, design, or plan from the conversation; no file path is required. Optional trailing text narrows the scope, for example /review-plan Focus on migration and rollback. Use it in the host's plan mode. It challenges scope by constructing the smallest coherent version of the plan that still meets the goal, and treats public API surface with no named consumer, or contracts that leak implementation detail, as the hardest scope to reverse. It preserves required security, integrity, recovery, and accessibility behavior when cutting scope. It returns evidence-backed blockers, optional suggestions, and unknowns, or No findings; material unjustified scope counts as a blocker. It applies only unambiguous, safety-preserving corrections to an editable plan document, never to an issue or work-item body, code, configuration, or other documentation, then asks the plan owner how to proceed on the remaining findings. It saves no report.

Keeping packages up to date

saif doctor checks plugin installation, version drift, and host registration. saif doctor fix includes that group with no filter flags; target only plugins with:

saif doctor fix --agent

Version drift compares installed plugin.json versions with the marketplace. A package update must bump that version for version-based detection; missing installations and stale registrations do not depend on a version bump.

Refresh and recovery

agent init only installs missing plugins. doctor fix refreshes installed ones through the same installer, overwriting files in place rather than deleting the whole plugin directory. Stale-entry pruning is best-effort: a locked obsolete file can remain. A locked file that the new package must overwrite fails the refresh, and earlier copies may already contain new content because the directory update is not transactional.

The installer writes plugin.json last, so a failed refresh remains detectable as drift. Release the lock and rerun saif doctor fix --agent. A file/directory/link kind change requires removing the old entry before recreating it, so that entry can remain absent if recreation fails. A first install can also leave an incomplete directory if copying fails before plugin.json; doctor treats the missing manifest as not installed and retries.

Do not treat a settings entry or an existing directory alone as proof of a healthy install. Verify the manifest and host tools after repair.