SwarmCraft

SwarmCraft brings your project board and packet workflow into VS Code so you can pull work from the board, create linked packet files in your repository, keep updates in sync, and jump into the matching web views when needed.

Deep Discovery inspection uses the provider-neutral @swarmcraft/discovery-package-contract shared with the CLI. The extension is the cockpit for trust, sign-in, review readiness, deterministic package preparation, preview, upload consent, Project Unlock, generation status, and project handoff.

Deep Discovery can start before a SwarmCraft project or unlock exists. Run SwarmCraft: Start Deep Discovery in one trusted Git workspace folder after signing in. The command creates only an account-owned metadata record on the server; local paths and repository contents are not registered. The non-secret binding is stored at .swarmcraft/discovery.binding.json, while account tokens remain in VS Code Secret Storage. After seeding, the extension creates a local SwarmCraft: Start Deep Discovery commit containing only its allowlisted binding, managed state, provider adapter, root guidance, curated templates, and source-folder guidance. Raw sources and unrelated work are never staged. Pre-existing changes on a seed-owned path or a Git failure leave initialization successful but visibly uncommitted.

For multi-root workspaces, select exactly one folder before starting or resuming so SwarmCraft cannot write to an ambiguous repository. A copied repository keeps its binding intentionally: account or API-origin mismatches are blocked, and SwarmCraft: Resume Deep Discovery is the explicit recovery/rebinding path when no local binding exists. If the server workspace was deleted, local files remain untouched and the owner must start a new binding. Direct CLI use reads the same binding and must not bypass its account, origin, or schema checks.

Starting discovery reports registration and seeding progress, opens the local guide, and focuses an expanded Deep Discovery section in the SwarmCraft sidebar. The first row is the context-sensitive next action. Expandable Sources groups show items needing attention, visual-review recommendations, selected ready inputs, and unselected inventory; PDF rows expose both the packageable sidecar and local-only original. Expandable Discovery documents rows show each review lifecycle and open the corresponding Markdown file. Stable tree IDs preserve expansion while debounced file watchers refresh source digests, manifests, documents, and package state as local AI work changes them. The discovery status bar remains a secondary resume shortcut.

Expandable SaaS Spend Evidence supports the optional fifth discovery question. The beta path reads an owner-selected CSV/XLSX export, previews explicit merchant/date/amount/currency mapping, minimizes rows in memory, and does not copy the raw export into the repository. Analysis opens the complete redacted proposal for correction or explicit approval, then atomically updates and locally commits only docs/reports/spend-analysis.md; unrelated staged work is preserved and nothing is pushed. Repeat runs compare stable finding IDs and retain applicable owner corrections. The tree shows only safe source, period, outcome, and next-action metadata. Direct Xero, MYOB, and QuickBooks choices explain their approval gate without requesting credentials; they remain unavailable until provider applications and the confidential exchange boundary are approved. Disconnect deletes local connection material and in-memory evidence but does not delete a reviewed report from Git or falsely claim provider revocation.

Right-click source and document rows for state-aware actions grouped under navigation, review, selection, and utility separators. Inapplicable actions are hidden. Include/exclude updates are deterministic and invalidate the prior aggregate source confirmation; the complete proposed set must be confirmed again before preparation. AI-assisted visual comparison, document review, requested changes, and not-applicable disposition open the relevant local files and copy a focused provider instruction rather than directly manufacturing lifecycle evidence. An owner who already compared an original and sidecar can instead mark that comparison reviewed directly, or use the bulk action on Review recommended. SwarmCraft records timestamped owner evidence in the manifest and creates a local Git commit containing only that manifest; bulk confirmation produces one commit for the batch.

Use Prepare Discovery Package after all nine curated documents are reviewed. The extension runs deterministic CLI checks without opening a terminal or invoking Codex/Copilot, reports review/source/safety/digest/preview milestones, and automatically opens the exact package preview. Durable sidebar state survives reload. Validate Discovery Package confirms that the local files still match the immutable package.

When review or source validation fails, the extension keeps the affected lifecycle rows visible and offers Continue Discovery with AI; it does not copy an instruction merely because the user attempted preparation. Missing, changed, or stale selected inputs block until they match a newly confirmed selection. A sidecar visual-comparison recommendation remains visible but does not block preparation. Transport failures use content-safe diagnostics and Prepare Discovery Package Again; the AI is never asked to repair JSON. The preview shows curated/supporting counts, every included path, review state, bytes, token estimate, digest, server-processing disclosure, and reviewed-document precedence.

Upload Discovery Package verifies the latest ready manifest, opens the exact preview, and sends only metadata for server-policy preflight. The package uploads only after explicit digest-bound consent. SwarmCraft revalidates and encrypts the exact text; the sidebar then offers Continue Project Unlock and the web Discoveries workspace remains a durable recovery surface. When VS Code regains focus, the extension refreshes remote status and reveals a newly created project automatically.

After admission, Open Deep Discovery Project Unlock opens the authenticated browser for the same one-off unlock used by Fast Start. Card entry and terms stay in the web app. Check Deep Discovery Generation Status polls only API-owned entitlement state and opens the normal project board when generation succeeds; private prompts and reasoning never return to the extension.

Install

1. Download VS Code from https://code.visualstudio.com/download.
2. Install SwarmCraft from the Marketplace: https://marketplace.visualstudio.com/items?itemName=SwarmCraft.swarmcraft-vscode-extension.
3. Or install it directly from the command line:

code --install-extension SwarmCraft.swarmcraft-vscode-extension

4. Open the local repository you want to connect to SwarmCraft.

Sign In

SwarmCraft uses the same authenticated account model as the web app.

1. Finish account setup and MFA enrollment in the SwarmCraft web app if you have not done that already.
2. Open the SwarmCraft activity-bar view in VS Code.
3. Run SwarmCraft: Sign In.
4. Complete the MFA challenge if prompted.
5. Run SwarmCraft: Choose Repo and select the local repository folder you want the extension to use.

After sign-in, the extension stores the session in VS Code Secret Storage and refreshes it on startup or before board and packet commands when the access token is near expiry. If SwarmCraft is temporarily unreachable, the saved session stays on the machine so the next refresh can retry.

If you need the full walkthrough, use these guides:

• Install guide: https://swarmcraft.ai/docs/install-and-connect/download-vscode-and-install-swarmcraft
• Sign in and MFA: https://swarmcraft.ai/docs/install-and-connect/sign-in-and-set-up-mfa
• Connect SwarmCraft to your project: https://swarmcraft.ai/docs/install-and-connect/connect-swarmcraft-to-your-project

What You Can Do

• Sign in with your SwarmCraft account using VS Code Secret Storage for session tokens.
• View unlocked project boards in the SwarmCraft activity-bar view.
• Open project boards and tasks in the SwarmCraft web app.
• Choose which local repository folder the extension should use.
• Seed shared SwarmCraft repo guidance plus only the selected Copilot or Codex adapter files when one unlocked project maps unambiguously to the selected trusted repository.
• Seed owner-controlled docs/discovery/ guidance and the selected provider's discover skill before a project exists.
• Create linked packet files under .swarmcraft/projects/ for supported tasks.
• Copy provider-aware SwarmCraft action commands for planning, implementation, checking, review, and testing.
• Open, reveal, and sync linked packet files from the board.
• Drag tasks within a lane to reorder them and move them one adjacent lane at a time.
• Keep packet notes, checklists, and supported lane changes in sync with SwarmCraft.
• Launch the installed SwarmCraft CLI for one-shot project-board runs from VS Code, with project-board counts refreshed as the launched run advances.

AI Action Commands

SwarmCraft exposes five primary AI actions. These are the visible user workflow; diagnostic and seed-audit helpers are maintainer/support tools, not default customer actions.

Use SwarmCraft: Copy Plan Command or SwarmCraft: Copy Test Command from a project when one unlocked project maps to the selected trusted workspace. When a task has a linked packet, use SwarmCraft: Copy SwarmCraft Command from the tree context menu to copy the right do, check, or review command for the current lane. SwarmCraft: Copy Test Command is also available from linked packet tasks.

The copied format follows the user-level swarmcraft.aiProvider preference. New repositories inherit the same provider:

• copilot copies /plan, /do, /check, /review, and /test commands for .github/prompts.
• codex copies $swarmcraft-plan, $swarmcraft-do, $swarmcraft-check, $swarmcraft-review, and $swarmcraft-test skill invocations for .agents/skills.

Use SwarmCraft: Choose AI Provider to change the user preference and reconcile the current workspace between Copilot and Codex. Unchanged old-provider files are removed, modified ones are preserved and reported, and shared or owner-authored files remain untouched. When Codex skills are newly seeded, SwarmCraft offers to reload the workspace if Codex has not detected them. The packet file remains the execution contract.

The extension also reconciles generated skills from its bundled template set when a trusted repository is selected. Use SwarmCraft: Update Repo Guidance to retry explicitly. Missing and unchanged generated files are updated, owner edits are preserved and reported, older clients never downgrade newer repository guidance, and SwarmCraft never commits these changes automatically. Review the Git diff and commit it normally; reload the workspace when prompted after Codex skill changes.

Seeded Guidance Files

SwarmCraft separates the shared packet contract from provider-specific adapters:

• .swarmcraft/AGENTS.md, .swarmcraft/project.instructions.md, .swarmcraft/project.context.md, and .swarmcraft/agents/*.instructions.md are shared guidance for every AI surface.
• .swarmcraft/projects/<project>/<task>.md packet files are the source of truth for task scope, checklist progress, notes, agent updates, and supported lane movement.
• .github/prompts/plan.prompt.md, do.prompt.md, check.prompt.md, review.prompt.md, and test.prompt.md are Copilot command wrappers.
• .github/skills/swarmcraft-* are Copilot skills for the same five primary actions.
• .github/agents/swarmcraft-implementor.agent.md, swarmcraft-checker.agent.md, and swarmcraft-reviewer.agent.md are optional Copilot role agents for the lane work.
• .agents/skills/swarmcraft-* are Codex skills for the same five primary actions.
• .codex/agents contains optional Codex role-agent examples for the lane work.
• .codex/config.example.toml documents optional local Codex setup. Do not commit .codex/config.toml if it contains local paths, credentials, or machine-specific values.

If a provider cannot find its adapter files, use the shared .swarmcraft files and packet path as the contract, then reseed or repair the missing provider-specific files.

The task contract is a clean cutover from the earlier project-ticket format. Upgrade the API, CLI, and extension together; old ticketId packet files and ticket-named commands are not accepted. Preserve owner-authored notes, remove the retired generated packets, then choose the repository again and create or sync the task packets from the current board.

Key Commands

• SwarmCraft: Sign In
• SwarmCraft: Sign Out
• SwarmCraft: Refresh
• SwarmCraft: Choose Repo
• SwarmCraft: Choose AI Provider
• SwarmCraft: Update Repo Guidance
• SwarmCraft: Start Deep Discovery
• SwarmCraft: Resume Deep Discovery
• SwarmCraft: Open Deep Discovery Guidance
• SwarmCraft: Copy Deep Discovery Command
• SwarmCraft: Connect Accounting Source
• SwarmCraft: Analyse SaaS Spend
• SwarmCraft: Disconnect Accounting Source
• SwarmCraft: Continue Discovery with AI
• SwarmCraft: Prepare Discovery Package
• SwarmCraft: Prepare Discovery Package Again
• SwarmCraft: Validate Discovery Package
• SwarmCraft: Copy Instructions for AI
• SwarmCraft: Open Discovery Package Preview
• SwarmCraft: Open Discovery Package Document
• SwarmCraft: Upload Discovery Package
• SwarmCraft: Open Deep Discovery Project Unlock
• SwarmCraft: Check Deep Discovery Generation Status
• SwarmCraft: Move to Doing
• SwarmCraft: Open File
• SwarmCraft: Copy SwarmCraft Command
• SwarmCraft: Copy Plan Command
• SwarmCraft: Copy Test Command
• SwarmCraft: Sync Packet
• SwarmCraft: Open Board
• SwarmCraft: Run One-Shot with CLI
• SwarmCraft: Open in Web

When one-shot preflight needs CLI authentication, Run CLI Login opens a separate interactive terminal. Complete sign-in there, then run SwarmCraft: Run One-Shot with CLI again. Login does not start or resume one-shot automatically.

One-shot launches use a 100-agent-request ceiling. Before launch, the extension checks unfinished board work against the selected checking policy and asks for explicit approval of a sufficient higher limit when required, preventing a known-too-small limit from stopping the run partway through.

Configuration

The extension reads two workspace or user settings and one user-level preference:

• swarmcraft.apiBaseUrl: API base URL used for extension requests. Default: https://swarmcraft.ai/api
• swarmcraft.webBaseUrl: optional advanced browser-origin override. Without an override, production API settings open https://swarmcraft.ai and localhost API settings open local Vite at http://localhost:5173.
• swarmcraft.aiProvider: user-level provider preference used for repository seeding and copied SwarmCraft packet commands. New repositories inherit it. Default: copilot

Most users should leave these defaults unchanged.

Support

• Support workspace: https://swarmcraft.ai/login?next=%2fapp%2fsupport
• Product site: https://swarmcraft.ai