Condensed onboarding guide

Minions Onboarding: Your First 30 Minutes

Get one repository from installation to a completed first dispatch. For deeper exercises, continue through the full tutorial track below.

Prerequisites

• Node.js 22.5 or newer
• Git
• Azure CLI installed, and Azure Artifacts read access to the internal ProjectFeed-ISS feed. You do not run az login yourself — the installer reuses your Azure CLI session and signs you in once with az login --allow-no-subscriptions only if there is none
• One supported runtime CLI with working authentication
• A local Git repository you are comfortable allowing an agent to change

Minions defaults to GitHub Copilot CLI. Claude Code and Codex are also supported.

1. Install and initialize

Minions is distributed internally as @opg-microsoft/minions on the ISS ProjectFeed-ISS Azure Artifacts feed, not on public npm. There is no repository to clone: download the installer for your platform, then run it. It acquires a short-lived token from your existing az sign-in, uses it only in a throwaway npm config, and deletes that config when it finishes. No PAT is created or stored. It stages the package rather than installing it globally itself, so an earlier public-npm install is backed up and removed by the canonical installer before the internal package is installed.

• Windows

  PowerShell

  Download install-minions.ps1

  Run it from any directory — edit the path if you saved it elsewhere:

  powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\Downloads\install-minions.ps1"

• macOS or Linux

  bash / zsh

  Download install-minions.sh

  Run it from your download folder:

  bash ./install-minions.sh

Both installers run the same steps. The npm view check proves feed read access before anything on the machine changes, so a missing permission fails safely and leaves your host untouched. If it stops there, request Azure Artifacts read permission on ProjectFeed-ISS and re-run. Your existing npm config is inherited rather than replaced, so a custom global prefix keeps applying.

By default the installer takes the newest published version. Pin an exact version when you need a specific known-good build — the flag wins over the environment variable:

powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\Downloads\install-minions.ps1" -Version 1.2.3
bash ./install-minions.sh --version 1.2.3
MINIONS_INSTALL_VERSION=1.2.3 bash ./install-minions.sh

Only an exact published version is accepted; a range or a dist-tag is rejected before the installer requests a token, creates its staging folder, or downloads anything, so a typo leaves the machine untouched. The pinned version is the one staged locally and the one handed to the canonical installer, so the two cannot split. Each run prints its launcher revision as its first line — ==> Minions launcher install-minions.sh sha256:… — so quote that line in a bug report; a stale copy of the installer is otherwise indistinguishable from the current one.

The installer then runs the canonical installer that ships inside the package, so the full migration flow — state backup, public-package cutover, minions init, and a health-verified restart — also needs no clone. It is idempotent; re-run the downloaded installer to upgrade. When it finishes, check the install:

minions doctor

Resolve every doctor FAIL before continuing. To select another runtime:

minions config set-cli claude
# or: minions config set-cli codex

minions init creates ~/.minions/. Primary migrated runtime state lives in engine/state.db (SQLite, WAL mode). Retired JSON mirrors are removed; engine/control.json remains a live JSON control file.

2. Link a project

minions add C:\code\sample-project
minions list

Use the corresponding local path on macOS or Linux. Confirm the detected repository host, remote, main branch, and project description. Write the description as a responsibility, such as "Billing API and webhook ingestion," because agents use it when routing project-agnostic work.

3. Start the engine and dashboard

minions start --open

start is idempotent and starts both services. If the browser does not open:

minions dash

The managed minions start path must bind the configured port (7331 by default) or fail; it never silently splits the stack onto a fallback port. Standalone node dashboard.js may scan upward and records the selected port.

The main pages are Home, Work, PRs, Plans, Inbox, Tools, Schedule, Watches, Pipelines, Meetings, QA, and Engine. Settings are available from the application controls.

4. Dispatch one bounded task

Use a small task with an obvious result:

minions work "Add a Development section to README.md that names the existing test command"
minions dispatch
minions queue

For explicit project selection, create the item from Work or Command Center and choose your project rather than Auto. Watch the assigned agent from Home, then open its Live Output. A mutating dispatch receives an isolated worktree, the matching playbook, project context, and the configured runtime.

5. Inspect completion

minions status
minions queue

Open the item on Work to inspect its output, branch, artifacts, and linked pull request. If the item remains pending, read _pendingReason. If it fails, inspect the failure class before retrying:

minions wi show <work-item-id>
minions wi retry <work-item-id>

Correct authentication, configuration, workspace-manifest, or checkout failures before retrying.

6. Try a plan

In Command Center:

/plan Add a health endpoint, tests, and operator documentation to SampleProject.
Keep the changes as separately testable items with explicit dependencies.

Review the generated PRD on Plans. Use Discuss & Revise until its acceptance criteria and dependencies are concrete, then approve it. Approval materializes work items. When all items complete, Minions creates a verification item. Archiving remains a manual action after you review the final result.

Full tutorial track

Complete the first two tutorials before jumping to an advanced topic. Each tutorial ends with an observable result rather than only describing configuration.

Continue with Tutorial 1: Install and Connect a Project →

Tutorial 1

Tutorial 1: Install and Connect a Project

Install Minions, verify the default Copilot runtime, link one Git repository, start the engine and dashboard, and enable its read-only bridge to Constellation.

Prerequisites

• Node.js 22.5 or newer
• Git
• Azure CLI installed, and Azure Artifacts read access to ProjectFeed-ISS. The installer handles the sign-in itself — running az login first is not a prerequisite
• GitHub Copilot CLI, Claude Code, or Codex CLI with working authentication
• A local Git repository with an origin remote

Minions defaults to GitHub Copilot CLI. Install it if you have not selected a different runtime:

npm install -g @github/copilot

1. Install and initialize

Minions itself comes from the internal @opg-microsoft/minions package on the ISS ProjectFeed-ISS Azure Artifacts feed. Nothing is cloned. Download the installer for your platform from Install and initialize in the onboarding guide above and run it — that single command is the whole install. It reuses your Azure CLI session, or signs you in once with az login --allow-no-subscriptions if you have none, takes a short-lived token, uses it only in a throwaway npm config, deletes that config afterwards, and finishes by handing the install to the canonical installer that ships inside the staged package. Then initialize the operator home:

minions init

Initialization creates the operator home at ~/.minions/, including agent charters, playbooks, routing, prompts, and the SQLite state database.

2. Verify the host

minions doctor

Resolve every FAIL before dispatching. Warnings are non-blocking but should be read: a permission-flag warning can mean that the selected CLI will stop for an interactive prompt during a headless dispatch.

To choose another runtime:

minions config set-cli claude
# or
minions config set-cli codex

Run minions doctor again after switching.

3. Link a repository

minions add C:\code\sample-project

On macOS or Linux, use the corresponding path such as ~/code/sample-project. Confirm the detected host, repository, main branch, and description. The description helps agents route project-agnostic work, so describe the repository's responsibility rather than its implementation language.

Confirm the result:

minions list

4. Start Minions

minions start --open

start is idempotent and starts both the engine and dashboard. If browser launch is blocked, run minions dash.

minions bridge enable
minions bridge status

Next: Ship Your First Task →

Tutorial 2

Tutorial 2: Ship Your First Task

Queue a small documentation change, observe routing and live output, and inspect the resulting work item and pull request.

1. Choose a bounded task

Start with a task that has one clear result and a cheap validation step:

minions work "Add a short Development section to README.md that names the existing test command"

For precise project selection, use the dashboard's Work page or Command Center and select the linked project instead of Auto. A project-scoped task is better than auto-routing while learning the lifecycle.

2. Wake and inspect the queue

The engine checks for work on its normal tick. You can wake it immediately:

minions dispatch
minions queue

The item normally moves from pending to dispatched. If it remains pending, open its detail view and read _pendingReason; common reasons are an unmet dependency, no available agent, cooldown, or concurrency limits.

3. Follow the agent

In the dashboard:

1. Open Home and select the working agent.
2. Watch Live Output for repository exploration, edits, and checks.
3. Open Work and select the item to inspect its branch, output, and artifacts.

The engine chooses an agent from routing.md, creates an isolated worktree for mutating work, renders the work-type playbook, and invokes the configured runtime adapter.

4. Inspect the outcome

minions status
minions queue

A successful code-changing task should finish with a branch and pull request. If the runtime reports success without the required artifact, the work item can still be flagged for lifecycle follow-up.

If the item fails, read its failure class and output before retrying:

minions wi show <work-item-id>
minions wi retry <work-item-id>

Do not retry authentication, invalid configuration, or workspace-permission failures without correcting the cause first.

Next: Build a Feature from a Plan →

Tutorial 3

Tutorial 3: Build a Feature from a Plan

Use a plan when the outcome spans several independently verifiable changes. Create a plan, review its PRD, approve it, and follow dependency-aware implementation through verification.

1. Draft the request

Open Command Center and enter:

/plan Add a health endpoint to SampleProject, document it, and add automated
tests. Keep implementation, tests, and documentation as separate items with
explicit dependencies.

The plan agent writes Markdown under plans/. The plan-to-PRD agent writes a one-shot result sidecar; the engine validates it and imports structured items with acceptance criteria and depends_on relationships into SQLite.

You can also provide plan text from the CLI:

minions plan "Add a health endpoint, tests, and operator documentation" SampleProject

2. Review before approval

Open Plans and inspect:

• every item has a concrete deliverable;
• acceptance criteria can be tested;
• dependencies use item IDs and are acyclic;
• each item names the correct project;
• rejected or out-of-scope ideas are explicit.

Use Discuss & Revise for corrections. Approval is the human gate that materializes work items, so do not approve a vague PRD and expect routing to repair it.

3. Approve and observe dependency gating

Approve the plan, then inspect Work. Independent items can dispatch in parallel. Dependent items stay pending until their prerequisites are done.

At spawn time, Minions resolves completed dependencies to their pull-request branches and merges those branches into the dependent item's worktree. This lets later items build on code that has not reached the main branch yet.

4. Follow verification

When all implementation items finish, Minions creates a verify work item. Verification builds and tests the combined result and must attach a pull request when its contract requires one. A completed plan remains visible until you archive it manually.

Archive only after reviewing the verify result:

minions plans list
minions plans archive <plan-or-prd-id>

Archived PRDs remain retained in place; the source plan Markdown moves to plans/archive/.

Next: Choose Runtimes and Use Native Project Tools →

Tutorial 4

Tutorial 4: Choose Runtimes and Use Native Project Tools

Switch the fleet runtime, separate Command Center from agent settings, and check the selected runtime's native skill, command, and MCP discovery surface.

1. Inspect the current fleet

minions status
minions doctor --harness

The harness report is read-only. It lists runtime asset directories, skill roots, slash-command roots, and MCP configuration paths.

2. Select a fleet runtime

minions config set-cli copilot --model gpt-5.4
minions restart

Use a model ID supported by your installed CLI. Omit --model to let the CLI choose its default. To clear a persisted model while switching:

minions restart --cli claude --model ""

Fleet resolution is:

agent.cli -> engine.defaultCli -> copilot
agent.model -> engine.defaultModel -> runtime default

Command Center has independent engine.ccCli and engine.ccModel overrides. Changing CC does not silently switch dispatched agents.

3. Add a project-local skill

Use the selected runtime's native project skill root:

Claude:  .claude/skills/<skill-name>/SKILL.md
Copilot: .github/skills/<skill-name>/SKILL.md
Codex:   .agents/skills/<skill-name>/SKILL.md

Describe when the skill applies and provide the exact existing project command to run. Commit the skill so worktree-mode dispatches receive it. Copilot also reads .claude/skills and .agents/skills, but Claude does not natively discover .agents/skills. Uncommitted assets are visible only when the dispatch actually runs in that checkout, such as live checkout mode.

4. Verify native discovery

minions doctor --harness

The report inventories adapter-declared roots and whether they exist. It does not inject assets or attest that the runtime loaded or used them. Dispatch a small task that clearly matches the skill and inspect the runtime output for the observable behavior you requested.

Next: Automate Recurring Work and Follow-Ups →

Tutorial 5

Tutorial 5: Automate Recurring Work and Follow-Ups

Schedules create work at a time; watches react to state changes. Create one of each and verify them without waiting for the clock.

1. Explore the live schemas

minions schedule --help
minions watch --help
minions watch target-types
minions watch action-types

Use the dashboard forms for your first records. They validate against the same server-side schemas as the CLI JSON commands.

2. Create a schedule

Open Schedule, create a disabled schedule named weekly-doc-check, select your sample project, and use a task such as:

Review README.md for commands that no longer match the CLI. Correct only
verified stale claims and report the source lines used.

Use the natural-language parser or cron builder to choose a weekly time. Save the schedule disabled, then use Run now to test it.

From the CLI:

minions schedule list
minions schedule run-now <schedule-id>

Confirm that a work item appears before enabling the recurring schedule.

3. Create a watch

Open Watches and create a watch for the test work item:

• target type: work-item
• target: the work-item ID
• condition: completed
• owner: human
• stop after: 0

For an absolute condition such as completed, stopAfter: 0 means fire once and expire. For change conditions, zero means continue indefinitely.

Choose the default inbox notification first. Follow-up actions can dispatch work, call a webhook, trigger a pipeline, run a skill, or invoke CC triage, but they should be added only after the condition itself is proven.

4. Observe the trigger

minions watch list
minions watch show <watch-id>

Watches are evaluated on their polling cadence, not every engine tick. After the work item completes, confirm the watch records a trigger and an inbox note.

Next: Keep a Development Service Running →

Tutorial 6

Tutorial 6: Keep a Development Service Running

Use managed spawn when later agents need a dev server, emulator, or daemon to survive the creating agent's exit. The engine owns the process, checks health, and exposes it to later dispatches.

1. Prove the service manually

In the worktree that will host the service:

1. Install its existing dependencies.
2. Run the real start command for at least five seconds.
3. Probe the intended health endpoint and verify the expected status.
4. Stop the test process.

Do not derive a managed-spawn spec from package names or guessed monorepo filters. A command that exits immediately will not become reliable because the engine starts it.

2. Dispatch a managed-spawn work item

Create a project-scoped work item through the API so the opt-in metadata is explicit. Save a temporary managed-work-item.json:

{
  "title": "Start the sample development service",
  "description": "Start the existing development service and leave it available for downstream validation.",
  "project": "SampleProject",
  "type": "implement",
  "meta": {
    "managed_spawn": true,
    "managed_spawn_ttl_minutes": 120
  }
}

Submit it, then delete the temporary file:

minions api POST /api/work-items --body-file managed-work-item.json

The rendered playbook tells the agent where to write agents/<id>/managed-spawn.json and includes the current executable allowlist and schema. The declared cwd must be an absolute path that exists when the agent exits; the agent should derive it from its current worktree.

3. Require a healthcheck

For a web service, use an HTTP healthcheck:

{
  "type": "http",
  "url": "http://localhost:3000/health",
  "expect_status": 200,
  "interval_s": 1,
  "timeout_s": 60
}

For an emulator or non-HTTP daemon, use a command healthcheck that exits zero and matches a stable readiness signal.

4. Inspect and use the service

Open Engine and find Managed Processes, or query:

minions api GET /api/managed-processes

Confirm the process is healthy, its log path is populated, and its expiration time is correct. Dispatch a second work item in the same project and verify that the live managed-process context is included in its prompt.

Use meta.keep_processes instead when the agent itself must retain an ad-hoc child with no health endpoint. Prefer managed spawn for named services.

Next: Coordinate a Cross-Repository Change →

Tutorial 7

Tutorial 7: Coordinate a Cross-Repository Change

Cross-repository plans keep one product outcome together while materializing each item into the project that owns its code.

1. Link and name both projects

minions add C:\code\sample-api
minions add C:\code\sample-web
minions list

Give each project a distinct responsibility in its description. Cross-repo routing is much easier to review when sample-api and sample-web do not both say only "application code."

2. Request a cross-repo plan

In Command Center:

/plan Add an API capability in sample-api and consume it from sample-web.
Create separately testable items, assign every item to one project, and make
the web integration depend on the API contract item.

The plan must declare both target projects, and every PRD item must have a valid project value matching a configured project name.

3. Review the dependency boundary

Before approval, confirm:

• shared contracts are explicit acceptance criteria;
• each item edits only one repository;
• cross-repo depends_on records sequencing intent;
• each repository has its own verification responsibility.

Cross-repo dependencies are advisory for merge coordination. They do not make separate repositories share a Git history or automatically merge one repo's branch into another.

4. Approve and observe fan-out

Approval materializes items into each project's work-item store. Minions creates one verify work item per touched project after implementation completes. Inspect both project filters in Work and Plans rather than assuming the central plan card shows every repository-specific detail.

Next: Operate and Recover Minions →

Tutorial 8

Tutorial 8: Operate and Recover Minions

Build a repeatable triage order for engine, dispatch, runtime, and worktree failures.

1. Start with supported summaries

minions status
minions queue
minions sources

Use the dashboard Engine page for dispatch logs, metrics, managed processes, and worktree state. Runtime state is canonical in engine/state.db; remaining JSON files have explicit configuration, definition, cache, artifact, or coordination contracts and are not state mirrors.

2. Classify before acting

For a pending item, inspect _pendingReason. For a failed item, inspect its failure class and final output. Correct non-retryable causes such as authentication, invalid manifests, bad managed-spawn schemas, or dirty live checkouts before retrying.

minions wi show <work-item-id>
minions wi retry <work-item-id>

3. Restart safely

minions start is idempotent. Use minions restart after changing engine configuration or playbooks:

minions restart
minions status

Agents are independent child processes. A restart loses in-memory process handles, so Minions uses persisted dispatch state, PID data, live-output activity, and a restart grace period to recover or classify orphans. Do not delete worktrees or dispatch rows to force recovery.

4. Use targeted recovery commands

minions dispatch    # wake the daemon; does not run a second tick loop
minions cleanup     # run the supported cleanup path
minions kill        # kill active agents and reset dispatches to pending

Use kill only when agents are genuinely wedged. Quiet output is not enough: tracked agents are allowed to be silent during long builds and tests.

5. Protect against process-level outages

For unattended installations, inspect and optionally install the external watchdog:

minions watchdog status
minions watchdog install --interval=5

The watchdog complements the in-process supervisor by probing and recovering the engine through the operating system scheduler.

↑ Return to the condensed onboarding guide