# Minions Onboarding — Your First 30 Minutes

A fast, hands-on walkthrough for new contributors. Follow the eight steps below in order. Each step is independent enough that you can stop, take a break, and resume without losing state.

> **Prerequisites:** Node.js 22.5+ (required by `package.json#engines` for the `node:sqlite` runtime backing the state DB), Git, and a working Claude Code CLI (`npm install -g @anthropic-ai/claude-code`) authenticated against your Anthropic API key or Claude Max subscription. See the top-level [README.md](../README.md#prerequisites) for the full list.

> **Screenshots:** This walkthrough is intentionally text-only on the first pass. If you want annotated dashboard screenshots, run the [`capture-demos`](../README.md#dashboard) skill after Step 5; it drives Playwright over the running dashboard and writes images you can drop alongside each section.

---

## Step 1 — Clone the repo

You only need to clone if you intend to modify Minions itself. End users normally `npm install -g @yemi33/minions` instead, but a checkout is the right starting point for contributors.

```bash
git clone https://github.com/yemi33/minions.git ~/minions-dev
cd ~/minions-dev
npm install     # installs dev tooling (Playwright) + the lone runtime dep (@azure-devops/mcp); engine is otherwise built on Node built-ins
```

You should now have:

- `engine.js` — the orchestrator entry point
- `dashboard.js` — the HTTP/UI server (binds `:7331`)
- `minions.js` — the CLI shim that maps `minions <cmd>` to the right script
- `playbooks/`, `agents/`, `prompts/`, `docs/` — content the engine renders into agent prompts
- `test/` — `unit.test.js`, the integration suite, and Playwright specs

If you cloned to somewhere other than `~/.minions`, the CLI will still work — `minions init` writes runtime state under `~/.minions/` regardless of where the source lives. The `node` scripts under your checkout will use the checkout as the runtime root when invoked directly (e.g. `node ./engine.js start`).

---

## Step 2 — Run `minions doctor`

`minions doctor` runs the same preflight checks the engine runs at startup. It is safe to run any time and never mutates state.

```bash
minions doctor
```

A healthy Mac/Linux run looks roughly like:

```
  Runtime:

    ✓ node: v20.11.1 (>= 18 required)
    ✓ git: git version 2.45.0
    ✓ claude CLI: 1.0.x found on PATH

  Authentication:

    ✓ ANTHROPIC_API_KEY: set
    ✓ gh auth: logged in as <you>

  Filesystem:

    ✓ ~/.minions writable
    ✓ engine/ writable

  All checks passed.
```

What to look for:

- `✓` (green) means OK. `!` is a warning the engine can usually work around. `✗` (critical) will block dispatch — fix it before continuing.
- The most common failure is `claude CLI: not found` — re-install with `npm install -g @anthropic-ai/claude-code` and re-run.
- On Windows, runtime resolution prefers native `claude.exe` over the POSIX bash shim; if you see runtime-resolution warnings, `gh auth status` and `where.exe claude` are good first stops.

If `doctor` reports any `✗`, stop and resolve it. The remaining steps assume a clean preflight.

---

## Step 3 — Bootstrap state with `minions init`

`minions init` scaffolds `~/.minions/` with a default config, five agent charters, default playbooks, an empty knowledge base, and the engine state files.

```bash
minions init
```

After init you will have (under `~/.minions/`):

- `config.json` — projects, agents, schedules
- `agents/<name>/charter.md` — the personality + boundaries for each of the five default agents (`ripley`, `dallas`, `lambert`, `rebecca`, `ralph`)
- `engine/dispatch.json`, `engine/control.json`, `engine/metrics.json` — empty queues, ready for first dispatch
- `pinned.md`, `notes.md` — empty team-memory surfaces
- `playbooks/`, `prompts/`, `routing.md` — agent prompt scaffolding

`init` is safe to re-run; existing customizations to `config.json`, charters, notes, knowledge, and routing are preserved. To force overwrites after a major version bump, use `minions init --force`.

---

## Step 4 — Link your first project with `minions add`

A "project" tells Minions which repo to discover work for and where to spawn worktrees. The CLI auto-detects host (GitHub/ADO), org, repo name, and main branch from the directory's git remote.

```bash
minions add ~/code/your-repo
```

You will be prompted to confirm or override the auto-detected fields, plus a one-line description. The description is **important** — agents read it during routing to decide whether a work item belongs to your repo. Keep it specific (e.g. "Internal billing API and webhook ingestion service") rather than generic ("Backend code").

After `minions add` returns, `~/.minions/config.json` has a new `projects[]` entry, and `~/.minions/projects/<name>/` holds the per-project `work-items.json` + `pull-requests.json` trackers.

To link several at once interactively, run `minions scan` (default: scans `~` to depth 3 for git repos and lets you multi-select).

---

## Step 5 — Start engine + dashboard with `minions restart`

`minions restart` starts (or restarts) both the engine daemon and the dashboard server. Use `restart` rather than `start` whenever you have edited engine code or playbooks — it ensures the daemon picks up your changes.

```bash
minions restart
```

You should see logs like `Engine started (pid=…)` and `Dashboard listening on http://localhost:7331`. Open the dashboard:

```bash
minions dash    # opens http://localhost:7331 in your default browser
```

A quick tour of the panels you will use most often during onboarding:

| Panel | What it shows | When to use it |
|---|---|---|
| **Projects bar** (top) | All linked projects with descriptions | Confirm Step 4 worked |
| **Minions Members** | Five agent cards with status, current task, last result | Watch dispatches happen in real time |
| **Live Output** (per agent) | Streaming `live-output.log` | Tail an agent while it runs — refreshes every 3 s |
| **Command Center** (CC button, top-right) | Conversational chat with Claude over your full Minions state | Ask questions, queue work, draft plans |
| **Work Items** | Paginated table of all work, filterable by project/status | Inspect / retry / archive |
| **Plans & PRD** | Plan markdown drafts and approved PRDs | Approve, discuss-and-revise, or reject plans |
| **Pull Requests** | Cached PR status (build, review, merge) | Track the PRs your agents create |
| **Engine** | Dispatch queue, engine log, LLM call performance | Diagnose timing / token issues |

The engine ticks every 10 seconds. If the dashboard says "Engine: stopped", run `minions restart` again — the dashboard auto-restarts a dead engine on its next health check, but a manual restart is faster.

---

## Step 6 — Your first dispatch via the Command Center

The fastest way to give Minions a task is the Command Center (CC).

1. Click the **CC** button in the top-right of the dashboard.
2. In the slide-out chat, type a one-line description, e.g.:
   ```
   Add a brief comment to README.md explaining what minions doctor does
   ```
3. CC will propose an action (usually `POST /api/work-items` or `POST /api/plan`). Confirm.

Within one tick (≤10 s), the engine will:

1. Pick an idle agent that matches the work type (per `routing.md`).
2. Create a git worktree for that agent under `<your-repo>/.worktrees/<work-item-id>/`.
3. Render the appropriate playbook (`playbooks/implement.md` for an implement task) with your project context, charter, pinned notes, and recent team notes.
4. Spawn `engine/spawn-agent.js`, which invokes the Claude CLI with the rendered prompt.

Watch the **Minions Members** card for that agent flip to "working", and click into the **Live Output** tab to tail the streaming agent log.

You can do the same thing from the CLI: `minions work "Add a brief comment to README.md…"`.

---

## Step 7 — Your first plan via `/plan`

For multi-step work, use a plan instead of a one-shot work item. In the Command Center, type:

```
/plan Audit our README and propose three concrete improvements with examples
```

CC will queue a `plan` work item. The plan agent writes a markdown draft to `~/.minions/plans/<project>-<date>.md`, then chains automatically to a `plan-to-prd` agent that produces a structured PRD JSON in `~/.minions/prd/`. The PRD lands with `status: "awaiting-approval"`.

Open **Plans & PRD** in the dashboard. You will see the new plan with three buttons:

- **Approve** — materializes one work item per PRD entry, with `depends_on` honored.
- **Discuss & Revise** — opens a doc-chat modal where you can iterate on the plan with Claude.
- **Reject** — closes the plan with a reason.

After approving, agents start picking up the materialized work items on the next tick. When all PRD items complete, the engine auto-dispatches a `verify` task that builds + tests the changes and writes a manual testing guide. Archiving (after verify) is a manual dashboard action — see [docs/plan-lifecycle.md](plan-lifecycle.md) for the full pipeline.

---

## Step 8 — Your first PR review

When an `implement` agent finishes a work item, it pushes a branch and opens a PR. The engine polls PR status every `prPollStatusEvery` ticks (≈12 minutes by default) and dispatches a `review` agent automatically.

To watch the cycle end-to-end on your first task:

1. Open **Pull Requests** in the dashboard. Find the PR your agent just opened.
2. Wait for the next status poll (or run `minions dispatch` to wake the daemon immediately). The PR's `reviewStatus` will flip from `pending` to `waiting`, then a review agent will spawn.
3. Click the agent card to watch the live review. The reviewer reads the diff, runs targeted checks, then posts a comment that starts with `VERDICT: APPROVE` or `VERDICT: REQUEST_CHANGES`.
4. If the verdict is `REQUEST_CHANGES`, the engine queues a `fix` task for the original author with a feedback note. The cycle repeats until approved or capped by the eval-loop config.

You can also trigger reviews manually by commenting on the PR — see [docs/pr-review-fix-loop.md](pr-review-fix-loop.md).

> **Note on self-approval:** Minions agents share a single GitHub identity, so `gh pr review --approve` is blocked by GitHub's self-approval rule. Reviewers post a `VERDICT:` **comment** instead, and the engine treats that comment as authoritative.

---

## Debugging — Where to look when something goes wrong

When an agent gets stuck, hangs, or produces unexpected output, these files are your first stops. They live under `~/.minions/` (or wherever your runtime root is).

| File | What it tells you |
|---|---|
| `agents/<id>/live-output.log` | Real-time streaming output from the agent's Claude CLI session — same content the dashboard's Live Output tab shows. Tail this with `tail -f ~/.minions/agents/<id>/live-output.log`. |
| `agents/<id>/last-prompt.txt` | The most recent rendered prompt the agent received (playbook + system prompt + injected context). Inspect this to see exactly what the agent was asked to do, including pinned notes, team notes, charter, and dispatch context. If your install does not surface this file yet, the live equivalents are `engine/tmp/prompt-<dispatch-id>.md` (while the agent is running) and `engine/contexts/<dispatch-id>.md` (when the prompt was sidecarred because it exceeded `maxDispatchPromptBytes`). |
| `agents/<id>/output.log` | The agent's final output after completion (post-mortem read; `live-output.log` is the during-run read). |
| `agents/<id>/history.md` | Last 20 tasks for that agent with timestamps, results, projects, and branches. Useful when a single agent is misbehaving over multiple tasks. |
| `engine/log.json` | Audit trail of engine actions (last 2500 entries, rotated to 2000). Filter with `jq` for a specific agent or work item. |
| `engine/dispatch.json` | Pending / active / completed dispatch queue. If an agent appears idle on the dashboard but the queue says `active`, the engine likely lost process tracking — try `minions restart`. |
| `engine/metrics.json` | Per-agent token usage, runtime, error counts. Useful for spotting agents that are silently retrying. |
| `notes/inbox/` | Raw findings agents drop after each task. Look here for the latest learnings before the consolidator merges them into `notes.md`. |
| `pinned.md` and `notes.md` | Team memory that gets injected into every agent prompt. If an agent keeps making the same mistake, pin a correction here. |

Other quick debugging knobs:

- `minions status` — text snapshot of agents, projects, dispatch queue, and quality metrics.
- `minions queue` — focused view of the dispatch queue (pending, active, completed).
- `minions kill` — kills all active agents and resets their dispatches to `pending`. Use when an agent is wedged.
- `minions cleanup` — manually run the temp-file / worktree / zombie sweep that normally runs every 10 ticks.

For deeper dives: [docs/engine-restart.md](engine-restart.md), [docs/auto-discovery.md](auto-discovery.md), and [docs/self-improvement.md](self-improvement.md).

---

## What's next

You have:

- Linked a project, started the engine, opened the dashboard.
- Dispatched a one-shot task via Command Center.
- Authored a plan, approved it, and watched the PRD materialize into work items.
- Watched an agent open and review a PR.
- Located the files you need to debug a stuck agent.

From here, sensible next reads are:

- [README.md](../README.md) — the full feature catalog and CLI reference.
- [CLAUDE.md](../CLAUDE.md) — engineering conventions, tick cycle, locking rules. Read this before editing engine code.
- [docs/plan-lifecycle.md](plan-lifecycle.md) — plan → PRD → implement → verify → archive in detail.
- [docs/command-center.md](command-center.md) — full CC capabilities, including doc-chat and plan steering.
- [docs/pr-review-fix-loop.md](pr-review-fix-loop.md) — how the review/fix cycle is bounded and steered.

Welcome to the team.
