SwarmCraft
Discovery and PlanningGuide

Docs

Start and resume Deep Discovery

Prepare one trusted Git workspace, choose Codex or Copilot, and open the Deep Discovery cockpit in VS Code.

Start and resume Deep Discovery

Deep Discovery starts before a SwarmCraft project exists. Use one trusted local Git repository as the owner-controlled workspace for sources, interviews, reviewed documents, and package preparation.

Prerequisites

You need:

  • Visual Studio Code with the SwarmCraft extension installed
  • a signed-in SwarmCraft account with MFA enrolled
  • Codex or GitHub Copilot installed and signed in with your own provider account
  • one trusted folder that is a Git repository

The repository does not need a remote, first commit, protected default branch, or clean working tree. If the folder is not a Git repository, the start command can offer to initialize local Git metadata. It never publishes the folder.

Deep Discovery is currently account-enabled during rollout. If registration is unavailable, preparation cannot bypass the server capability; use the troubleshooting guide or contact support.

Choose the local AI provider

  1. Open the Command Palette.
  2. Run SwarmCraft: Choose AI Provider.
  3. Select Codex or GitHub Copilot.

The provider is used for local discovery conversations. Deterministic package preparation does not call it. SwarmCraft installs only the selected provider's discovery adapter while shared owner guidance remains provider-neutral.

Start the discovery

  1. Open the repository folder in VS Code.
  2. Run SwarmCraft: Start Deep Discovery.
  3. Select the exact workspace folder if VS Code has multiple roots.
  4. Wait for registration and seed progress to finish.

On success, VS Code opens docs/discovery/README.md and expands Deep Discovery in the SwarmCraft sidebar. The seed contains the non-secret binding, managed state, selected provider adapter, root guidance, nine curated templates, and source-folder guidance.

The extension attempts a local commit named SwarmCraft: Start Deep Discovery containing only allowlisted seed files. Raw sources and unrelated work are never staged. A Git failure or pre-existing seed-path changes leave discovery started but clearly report that the seed remains uncommitted.

Resume safely

Close and reopen VS Code whenever needed. Run SwarmCraft: Resume Deep Discovery or use the discovery status-bar item to return to the current stage.

A copied repository intentionally keeps its binding. Account, API-origin, and schema mismatches block rather than silently rebinding. If no local binding exists, Resume is the explicit recovery path. If the server workspace was deleted, local files remain untouched and you must start a new discovery binding.

Continue with Gather and select Deep Discovery sources.