Minions — Autonomous AI Development Team

A multi-project AI dev team that runs from ~/.minions/. Five autonomous agents share a single engine, dashboard, knowledge base, and MCP toolchain — working across any number of linked repos with self-improving workflows.

Zero dependencies — uses only Node.js built-in modules.

Inspired by and initially scaffolded from Brady Gaster's Minions.

Prerequisites

• Node.js 18+ (LTS recommended)
• Claude Code CLI — install with npm install -g @anthropic-ai/claude-code
• Anthropic API key or Claude Max subscription (agents spawn Claude Code sessions)
• Git — agents create worktrees for all code changes

Installation

# Install globally from npm
npm install -g @yemi33/minions

# Bootstrap ~/.minions/ with default config and agents
minions init

# Link your first project (interactive — auto-detects from git remote)
minions add ~/my-project

Or try without installing:

npx @yemi33/minions init

No dependencies — Minions uses only Node.js built-in modules.

Alternative: clone directly

git clone https://github.com/yemi33/minions.git ~/.minions
node ~/.minions/minions.js init

Upgrading

# Check if an update is available
minions version

# Update the npm package and apply changes
npm update -g @yemi33/minions
minions init --force

What gets updated: Engine code (.js, .html), new playbooks, new agent charters, new docs, CHANGELOG.md.

What's preserved: Your config.json, agent history, notes, knowledge base, routing, skills, and any .md files you've customized (charters, playbooks). If a new playbook or charter is added in an update, it's installed automatically without touching your existing ones.

Upgrades now skip the interactive repo scan automatically. If you want to re-run discovery later, run minions scan. To skip scanning during the very first install, pass --skip-scan and link projects manually when ready.

What's shown: A summary of files updated, added, and preserved, plus a pointer to the changelog.

Migrating from legacy installs

If you previously used an older install layout, run:

minions init --force

minions will auto-detect legacy runtime locations and markers, migrate state into ~/.minions, normalize runtime marker names, and record the action in ~/.minions/migration.log.

Quick Start

# 1. Init + scan — finds all git repos on your machine, multi-select to add
minions init
#    → creates config, agents, engine defaults
#    → scans ~ for git repos (auto-detects host, org, branch)
#    → shows numbered list, pick with "1,3,5-7" or "all"

# 2. Start the engine (runs in foreground, ticks every 60s)
minions start

# 3. Open the dashboard (separate terminal)
minions dash
# → http://localhost:7331

You can also add/scan repos later:

minions scan              # Re-scan and add more repos
minions scan ~/code 4     # Scan specific dir, depth 4
minions add ~/repo        # Add a single repo interactively

Setup via Claude Code

If you use Claude Code as your daily driver, you can set up Minions by prompting Claude directly:

First-time setup:

Install minions with `npm install -g @yemi33/minions`, run `minions init`,
then link my project at ~/my-project with `minions add ~/my-project` —
answer the interactive prompts using what you can auto-detect from the repo.

Give the minions work:

Add a work item to my minions: "Explore the codebase and document the architecture"
— run `minions work "Explore the codebase and document the architecture"`

Check status:

Run `minions status` and tell me what my minions is doing

What happens on first run

1. The engine starts ticking every 60 seconds
2. It scans each linked project for work: PRs needing review, plan items, queued work items
3. If it finds work and an agent is idle, it spawns a Claude Code session with the right playbook
4. You can watch progress on the dashboard or via minions status

To give the minions its first task, open the dashboard Command Center and add a work item, or use the CLI:

minions work "Explore the codebase and document the architecture"

CLI Reference

| Command | Description | |---------|-------------| | minions init | Bootstrap ~/.minions/ with default agents and config (--skip-scan to skip repo scan) | | minions init --force | Upgrade engine code + add new files (preserves customizations) | | minions version | Show installed vs package version | | minions scan [dir] [depth] | Scan for git repos and multi-select to add (default: ~, depth 3) | | minions add <dir> | Link a single project (auto-detects settings from git, prompts to confirm) | | minions remove <dir> | Unlink a project | | minions list | List all linked projects with descriptions | | minions start | Start engine daemon (ticks every 60s, auto-syncs MCP servers) | | minions stop | Stop the engine | | minions status | Show agents, projects, dispatch queue, quality metrics | | minions pause / resume | Pause/resume dispatching | | minions dispatch | Force a dispatch cycle | | minions discover | Dry-run work discovery | | minions work <title> [opts] | Add to central work queue | | minions spawn <agent> <prompt> | Manually spawn an agent | | minions plan <file\|text> [proj] | Run a plan | | minions cleanup | Run cleanup manually (temp files, worktrees, zombies) | | minions dash | Start web dashboard (default port 7331) |

You can also run scripts directly: node ~/.minions/engine.js start, node ~/.minions/dashboard.js, etc.

Architecture

                    ┌───────────────────────────────┐
                    │      ~/.minions/ (central)       │
                    │                               │
                    │  engine.js        ← tick 60s  │
                    │  dashboard.js     ← :7331     │
                    │  config.json      ← projects  │
                    │  agents/          ← 5 agents  │
                    │  playbooks/       ← templates │
                    │  plans/           ← approved plans│
                    │  knowledge/       ← KB store  │
                    │  skills/          ← workflows │
                    │  notes/       ← knowledge  │
                    └──────┬────────────────────────┘
                           │ discovers work + dispatches agents
              ┌────────────┼────────────────┐
              ▼            ▼                ▼
     ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
     │  Project A   │ │  Project B   │ │  Project C   │
     │ projects/A   │ │ projects/B   │ │ projects/C   │
     │  work-items  │ │  work-items  │ │  work-items  │
     │  pull-reqs   │ │  pull-reqs   │ │  pull-reqs   │
     │  .claude/    │ │  .claude/    │ │  .claude/    │
     │   skills/    │ │   skills/    │ │   skills/    │
     └──────────────┘ └──────────────┘ └──────────────┘

What It Does

• Auto-discovers work from plans (plans/*.json), pull requests, and work queues across all linked projects
• Plan pipeline — /plan spawns a plan agent, chains to plan-to-prd, produces plans/{project}-{date}.json with status: "awaiting-approval". Supports shared-branch and parallel strategies.
• Human approval gate — plans require approval before materializing as work items. Dashboard provides Approve / Discuss & Revise / Reject. Discussion launches an interactive Claude Code session.
• Dispatches AI agents (Claude CLI) with full project context, git worktrees, and MCP server access
• Routes intelligently — fixes first, then reviews, then implementation, matched to agent strengths
• LLM-powered consolidation — Haiku summarizes notes (threshold: 5 files). Regex fallback. Source references required.
• Knowledge base — knowledge/ with categories: architecture, conventions, project-notes, build-reports, reviews. Full notes preserved. Dashboard browsable with inline Q&A.
• Token tracking — per-agent and per-day usage. Dashboard Token Usage panel.
• Engine watchdog — dashboard auto-restarts dead engine.
• Agent re-attachment — on restart, finds surviving agent processes via PID files.
• Learns from itself — agents write findings, engine consolidates into institutional knowledge
• Tracks quality — approval rates, error rates, and task metrics per agent
• Shares workflows — agents create reusable skills (Claude Code-compatible) that all other agents can follow
• Supports cross-repo tasks — a single work item can span multiple repositories
• Fan-out dispatch — broad tasks can be split across all idle agents in parallel, each assigned a project
• Auto-syncs PRs — engine scans agent output for PR URLs and updates project trackers automatically. PR reconciliation sweep catches any missed PRs from ADO.
• Human feedback on PRs — comment on any ADO PR to trigger agent fix tasks. @minions keyword required when multiple humans are commenting; optional when you're the only reviewer.
• Dependency-aware spawning — when a work item depends on others, the engine merges dependency PR branches into the worktree before the agent starts
• Plan verification — when all PRD items complete, engine auto-dispatches a verify task that builds all repos, starts the webapp, and writes a manual testing guide
• PRD modification — edit plans via doc-chat in the modal, then "Generate PRD" to regenerate. Dashboard supports regenerating, retrying failed items, and syncing edits to pending work items.
• Auto-extracts skills — agents write ```skill blocks in output; engine auto-extracts them
• Heartbeat monitoring — detects dead/hung agents via output file activity, not just timeouts
• Auto-cleanup — stale temp files, orphaned worktrees, zombie processes cleaned every 10 minutes

Dashboard

The web dashboard at http://localhost:7331 provides:

• Projects bar — all linked projects with descriptions (hover for full text)
• Command Center — add work items, notes, plans (multi-project via #project tags). "make a plan for..." auto-detection, "remember" keyword, --parallel/--shared flags, arrow key history, Past Commands modal.
• Minions Members — agent cards with status and result summary, click for charter/history/output detail panel
  • Live Output tab — real-time streaming output for working agents (auto-refreshes every 3s)
• Work Items — paginated table with status, source, type, priority, assigned agent, linked PRs, fan-out badges, and retry button for failed items
• Plans — plan approval UI with Approve / Discuss & Revise / Reject. Click to open in doc-chat modal for natural language editing; "Generate PRD" button appears after edits.
• Knowledge Base — browsable by category with inline Q&A (Haiku-powered)
• PRD Progress — dependency graph view, per-item retry button, "Edit PRD" and "Regenerate" actions. Failed items show green retry button.
• Token Usage — per-agent and per-day token tracking, plus engine LLM usage (command-center, doc-chat, consolidation)
• Pull Requests — paginated PR tracker sorted by date, with review/build/merge status
• Skills — agent-created reusable workflows (minions-wide + project-specific), click to view full content
• Notes Inbox + Team Notes — learnings and team rules, editable from dashboard modal
• Dispatch Queue + Engine Log — active/pending work and audit trail
• Agent Metrics — tasks completed, errors, PRs created/approved/rejected, approval rates
• Document modals — inline Q&A with Haiku on any document modal

Project Config

When you run minions add <dir>, it prompts for project details and saves them to config.json. Each project entry looks like:

{
  "name": "MyProject",
  "description": "What this repo is for — agents read this to decide where to work",
  "localPath": "C:/Users/you/MyProject",
  "repoHost": "github",
  "repositoryId": "",
  "adoOrg": "your-github-org",
  "adoProject": "",
  "repoName": "MyProject",
  "mainBranch": "main",
  "workSources": {
    "pullRequests": { "enabled": true, "path": ".minions/pull-requests.json" },
    "workItems":    { "enabled": true, "path": ".minions/work-items.json" }
  }
}

Key fields:

• description — critical for auto-routing. Agents read this to decide which repo to work in.
• repoHost — "ado" (Azure DevOps) or "github". Controls which MCP tools agents use for PR creation, review comments, and status checks. Defaults to "ado".
• repositoryId — required for ADO (the repo GUID), optional for GitHub.
• adoOrg — ADO organization or GitHub org/user.
• adoProject — ADO project name (leave blank for GitHub).
• workSources — toggle which work sources the engine scans for each project.

Per-project runtime state is stored centrally at ~/.minions/projects/<project-name>/work-items.json and ~/.minions/projects/<project-name>/pull-requests.json.

Auto-Discovery

When you run minions add, the tool automatically detects what it can from the repo:

| What | How | |------|-----| | Main branch | git symbolic-ref | | Repo host | Git remote URL (github.com → github, visualstudio.com/dev.azure.com → ado) | | Org / project / repo | Parsed from git remote URL | | Description | First non-heading line from CLAUDE.md or README.md | | Project name | name field from package.json |

All detected values are shown as defaults in the interactive prompts — just press Enter to accept or type to override.

Project Conventions (CLAUDE.md)

When dispatching agents, the engine reads each project's CLAUDE.md and injects it into the agent's system prompt as "Project Conventions". This means agents automatically follow repo-specific rules (logging, build commands, coding style, etc.) without needing to discover them each time. Each project can have different conventions.

MCP Server Integration

Agents need MCP tools to interact with your repo host (create PRs, post review comments, etc.). Agents inherit MCP servers directly from ~/.claude.json as Claude Code processes — add servers there and they're immediately available to all agents on next spawn.

Example: If you use Azure DevOps, configure the azure-ado MCP server in your Claude Code settings. If you use GitHub, configure the github MCP server. Agents will discover and use whichever tools are available.

Manually refresh with minions mcp-sync.

Azure DevOps Users

For the best experience with ADO repos, install the Azure CLI and use the Azure DevOps MCP server. This gives agents full access to PRs, work items, repos, and pipelines via MCP tools — no gh CLI needed.

# Install Azure CLI
winget install Microsoft.AzureCLI   # Windows
brew install azure-cli               # macOS
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash  # Linux

# Login and set defaults
az login
az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT

Then add the ADO MCP server to your Claude Code settings (~/.claude.json). The engine will auto-sync it to all agents on next start.

Work Items

All work items use the shared playbooks/work-item.md template, which provides consistent branch naming, worktree workflow, PR creation steps, and status tracking.

Per-project — scoped to one repo. Select a project in the Command Center dropdown.

Central (auto-route) — agent gets all project descriptions and decides where to work. Use "Auto (agent decides)" in the dropdown, or minions work "title". Can span multiple repos.

Fan-Out (Parallel Multi-Agent)

Set Scope to "Fan-out (all agents)" in the Command Center, or add "scope": "fan-out" to the work item JSON.

The engine dispatches the task to all idle agents simultaneously, assigning each a project (round-robin). Each agent focuses on their assigned project and writes findings to the inbox.

"Explore all codebases and write architecture doc"  scope: fan-out
       │
       ├─→ Ripley   → Project A
       ├─→ Lambert  → Project B
       ├─→ Rebecca  → Project C
       └─→ Ralph    → Project A (round-robin wraps)

Failed Work Items

When an agent fails (timeout, crash, error), the engine marks the work item as failed with a reason. The dashboard shows a Retry button that resets it to pending for re-dispatch.

Auto-Discovery Pipeline

The engine discovers work from 5 sources, in priority order:

| Priority | Source | Dispatch Type | |----------|--------|---------------| | 1 | PRs with changes-requested | fix | | 2 | PRs with human @minions feedback | fix | | 3 | PRs with build failures | fix | | 4 | PRs pending review | review | | 5 | PRs needing build/test verification | test | | 6 | Plan items (plans/*.json, approved) | implement | | 7 | Per-project work items | item's type | | 8 | Central work items | item's type |

Each item passes through: dedup (checks pending, active, AND recently completed), cooldown, and agent availability gates. See docs/auto-discovery.md for the full pipeline.

Agent Execution

Spawn Chain

engine.js
  → spawn node spawn-agent.js <prompt.md> <sysprompt.md> <args...>
    → spawn-agent.js resolves claude-code cli.js path
      → spawn node cli.js -p --system-prompt <content> <args...>
        → prompt piped via stdin (avoids shell metacharacter issues)

No bash or shell involved — Node spawns Node directly. Prompts with special characters (parentheses, backticks, etc.) are safe.

What Each Agent Gets

• System prompt — lean (~2-4KB) identity + rules only
• Task prompt — rendered playbook with {{variables}} filled from config, plus bulk context (charter, history, project context, active PR/dispatch context, team notes). Skills/KB are referenced by path and loaded on-demand.
• Working directory — project root (agent creates worktrees as needed)
• MCP servers — inherited from ~/.claude.json (no extra config needed)
• Full tool access — all built-in tools plus all MCP tools
• Permission mode — bypassPermissions (no interactive prompts)
• Output format — stream-json (real-time streaming for live dashboard + heartbeat)

Post-Completion

When an agent finishes:

1. Output saved to agents/<name>/output.log
2. Agent status derived from engine/dispatch.json (done/error/working)
3. Work item status updated (done/failed, with auto-retry up to 3x)
4. PRs auto-synced from output → correct project's pull-requests.json (per-URL matching)
5. "No PR" detection — implement/fix tasks that complete without creating a PR get flagged (noPr: true)
6. Plan completion check — if all PRD items done, creates verification task + archives plan
7. Agent history updated (last 20 tasks)
8. Quality metrics updated (tokens, cost, approval rates)
9. Review feedback created for PR authors (if review task)
10. Learnings checked in notes/inbox/
11. Skills auto-extracted from ```skill blocks in output
12. Temp files cleaned up

Team

| Agent | Role | Best for | |-------|------|----------| | Ripley | Lead / Explorer | Code review, architecture, exploration | | Dallas | Engineer | Features, tests, UI | | Lambert | Analyst | PRD generation, docs | | Rebecca | Architect | Complex systems, CI/infra | | Ralph | Engineer | Features, bug fixes |

Routing rules in routing.md. Charters in agents/{name}/charter.md. Both are editable — customize agents and routing to fit your team's needs.

Playbooks

| Playbook | Purpose | |----------|---------| | work-item.md | Shared template for all work items (central + per-project) | | implement.md | Build a PRD item in a git worktree, create PR | | review.md | Review a PR, post findings to repo host | | fix.md | Fix review feedback on existing PR branch | | explore.md | Read-only codebase exploration | | test.md | Run tests and report results | | build-and-test.md | Build project and run test suite | | plan-to-prd.md | Convert a plan into PRD gap items | | plan.md | Generate a plan from user request | | implement-shared.md | Implement on a shared branch (multiple agents) | | ask.md | Answer a question about the codebase | | verify.md | Plan completion: build all repos, start webapp, write testing guide |

All playbooks use {{template_variables}} filled from project config. The work-item.md playbook uses {{scope_section}} to inject project-specific or multi-project context. Playbooks are fully customizable — edit them to match your workflow.

Health Monitoring

Heartbeat Check (every tick)

Uses live-output.log file modification time as a heartbeat:

• Process alive + recent output → healthy, keep running
• Process alive + in blocking tool call → extended timeout (matches tool's timeout + grace period)
• Process alive + silent >5min → hung, kill and mark failed
• No process + silent >5min → orphaned (engine restarted), mark failed

Agents can run for hours as long as they're producing output. The heartbeatTimeout (default 5min) only triggers on silence. When an agent is in a blocking tool call (e.g., TaskOutput with block:true, Bash with long timeout), the engine detects this from the live output and extends the timeout automatically.

Automated Cleanup (every 10 ticks)

| What | Condition | |------|-----------| | Temp prompt/sysprompt files | >1 hour old | | live-output.log for idle agents | >1 hour old | | Git worktrees for merged/abandoned PRs | PR status is merged/abandoned/completed | | Orphaned worktrees | >24 hours old, no active dispatch references them | | Zombie processes | In memory but no matching dispatch |

Manual cleanup: minions cleanup

Self-Improvement Loop

Six mechanisms that make the minions get better over time:

1. Learnings Inbox → notes.md

Agents write findings to notes/inbox/. Engine consolidates at 5+ files using Haiku LLM summarization (regex fallback) into notes.md — categorized with source references. Auto-prunes at 50KB. Injected into every future playbook.

6. Knowledge Base

knowledge/ stores full notes by category: architecture, conventions, project-notes, build-reports, reviews. Browsable in dashboard with inline Q&A (Haiku-powered).

2. Per-Agent History

agents/{name}/history.md tracks last 20 tasks with timestamps, results, projects, and branches. Injected into the agent's system prompt so it remembers past work.

3. Review Feedback Loop

When a reviewer flags issues, the engine creates feedback-<author>-from-<reviewer>.md in the inbox. The PR author sees the feedback in their next task.

4. Quality Metrics

engine/metrics.json tracks per agent: tasks completed, errors, PRs created/approved/rejected, reviews done. Visible in CLI (status) and dashboard with color-coded approval rates.

5. Skills

Agents save repeatable workflows to skills/<name>.md with Claude Code-compatible frontmatter. Engine builds an index injected into all prompts. Skills can also be stored per-project at <project>/.claude/skills/<name>/SKILL.md (requires a PR). Visible in the dashboard Skills section.

See docs/self-improvement.md for the full breakdown.

Configuration Reference

Engine behavior is controlled via config.json. Key settings:

{
  "engine": {
    "tickInterval": 60000,
    "maxConcurrent": 5,
    "agentTimeout": 18000000,
    "heartbeatTimeout": 300000,
    "maxTurns": 100,
    "inboxConsolidateThreshold": 5,
    "worktreeCreateTimeout": 300000,
    "worktreeCreateRetries": 1
  }
}

| Setting | Default | Description | |---------|---------|-------------| | tickInterval | 60000 (1min) | Milliseconds between engine ticks | | maxConcurrent | 5 | Max agents running simultaneously | | agentTimeout | 18000000 (5h) | Max total agent runtime | | heartbeatTimeout | 300000 (5min) | Kill agents silent longer than this | | maxTurns | 100 | Max Claude CLI turns per agent session | | inboxConsolidateThreshold | 5 | Inbox files needed before consolidation | | worktreeCreateTimeout | 300000 (5min) | Timeout for each git worktree add attempt | | worktreeCreateRetries | 1 | Retry count for transient git worktree add failures (0-3) | | worktreeRoot | ../worktrees | Where git worktrees are created | | idleAlertMinutes | 15 | Alert after no dispatch for this many minutes | | restartGracePeriod | 1200000 (20min) | Grace period for agent re-attachment after engine restart | | shutdownTimeout | 300000 (5min) | Max wait for active agents during graceful shutdown (SIGTERM/SIGINT) | | allowTempAgents | false | Spawn ephemeral agents when all permanent agents are busy | | autoDecompose | true | Auto-decompose implement:large items into sub-tasks before dispatch |

Scheduled Tasks

Add recurring work via config.schedules:

{
  "schedules": [
    {
      "id": "nightly-tests",
      "cron": "0 2 *",
      "type": "test",
      "title": "Nightly test suite",
      "project": "MyProject",
      "agent": "dallas",
      "enabled": true
    }
  ]
}

Cron format is simplified 3-field: minute hour dayOfWeek (0=Sun..6=Sat). Supports *, */N, and specific values. Examples:

• 0 2 * — 2am daily
• 0 9 1 — 9am every Monday
• */30 * * — every 30 minutes
• 0 9 1,3,5 — 9am Mon/Wed/Fri

Graceful Shutdown

The engine handles SIGTERM and SIGINT (Ctrl+C) gracefully:

1. Stops accepting new work (enters stopping state)
2. Waits for active agents to finish (up to shutdownTimeout, default 5 minutes)
3. Exits cleanly

Active agents continue running as independent processes and will be re-attached on next engine start.

Task Decomposition

Work items with complexity: "large" or estimated_complexity: "large" are auto-decomposed before dispatch (controlled by engine.autoDecompose, default true). The engine dispatches a decompose agent that breaks the item into 2-5 smaller sub-tasks, each becoming an independent work item with dependency tracking.

Temporary Agents

Set engine.allowTempAgents: true to let the engine spawn ephemeral agents when all 5 permanent agents are busy. Temp agents:

• Get a temp-{id} identifier
• Use a minimal system prompt (no charter)
• Are auto-cleaned up after task completion
• Count toward maxConcurrent slots

Live Output Streaming

The dashboard streams agent output in real-time via Server-Sent Events (SSE) instead of polling. The GET /api/agent/:id/live-stream endpoint pushes output chunks as they're written. Falls back to 3-second polling if SSE is unavailable.

Node.js Upgrade Caution

The engine and all spawned agents use the Node binary that started the engine (process.execPath). After upgrading Node, restart the engine:

minions stop
minions start

Portability

Portable (works on any machine): Engine code, dashboard, playbooks, charters, docs, config.template.json.

Machine-specific (reconfigure per machine):

• config.json — contains absolute paths to project directories. Re-link via minions add <dir>.

Generated at runtime: routing, notes, knowledge, skills, plans, PRDs, work items, dispatch queue, metrics — all created by the engine as agents work.

To move to a new machine: npm install -g @yemi33/minions && minions init --force, then re-run minions add for each project.

File Layout

~/.minions/
  bin/
    minions.js             <- Unified CLI entry point (npm package)
  minions.js               <- Project management: init, add, remove, list
  engine.js              <- Engine daemon + orchestrator
  engine/
    shared.js            <- Shared utilities: IO, process spawning, config helpers
    queries.js           <- Read-only state queries (used by engine + dashboard)
    cli.js               <- CLI command handlers (start, stop, status, plan, etc.)
    lifecycle.js          <- Post-completion hooks, plan chaining, PR sync, metrics
    consolidation.js     <- Haiku-powered inbox consolidation, knowledge base
    ado.js               <- ADO token management, PR polling, PR reconciliation
    llm.js               <- callLLM() with session resume, trackEngineUsage()
    spawn-agent.js       <- Agent spawn wrapper (resolves claude cli.js)
    preflight.js         <- Prerequisite checks (Node, Git, Claude CLI, API key)
    scheduler.js         <- Cron-style scheduled task discovery
    ado-mcp-wrapper.js   <- ADO MCP authentication wrapper
    check-status.js      <- Quick status check without full engine load
    control.json         <- running/paused/stopped (runtime, generated)
    dispatch.json        <- pending/active/completed queue (runtime, generated)
    log.json             <- Audit trail, capped at 500 (runtime, generated)
    metrics.json         <- Per-agent quality metrics (runtime, generated)
    cooldowns.json       <- Dispatch cooldown tracking (runtime, generated)
    schedule-runs.json   <- Last-run timestamps for scheduled tasks (runtime, generated)
  dashboard.js           <- Web dashboard server
  dashboard.html         <- Dashboard UI (single-file)
  config.json            <- projects[], agents, engine, claude settings (generated by minions init)
  config.template.json   <- Template for new installs
  package.json           <- npm package definition
  plans/                 <- Approved plans: plans/{project}-{date}.json (generated)
  prd/                   <- PRD archives and verification guides (generated)
  knowledge/             <- KB: architecture, conventions, project-notes, build-reports, reviews (generated)
  routing.md             <- Dispatch rules table (generated, editable)
  notes.md               <- Team rules + consolidated learnings (generated)
  work-items.json        <- Central work queue (generated)
  playbooks/
    work-item.md         <- Shared work item template
    implement.md         <- Build a PRD item
    review.md            <- Review a PR
    fix.md               <- Fix review feedback
    explore.md           <- Codebase exploration
    test.md              <- Run tests
    build-and-test.md    <- Build project and run test suite
    plan-to-prd.md       <- Convert plan to PRD gap items
    plan.md              <- Generate a plan from user request
    implement-shared.md  <- Implement on a shared branch
    ask.md               <- Answer a question about the codebase
    verify.md            <- Plan verification: build, test, start webapp, testing guide
    decompose.md         <- Break large work items into 2-5 sub-tasks
  skills/                <- Agent-created reusable workflows (generated)
  agents/
    {name}/
      charter.md         <- Agent identity and boundaries (editable)
      history.md         <- Task history, last 20 (runtime, generated)
      live-output.log    <- Streaming output while working (runtime, generated)
      output.log         <- Final output after completion (runtime, generated)
  identity/
    now.md               <- Engine-generated state snapshot (runtime, generated)
  notes/
    inbox/               <- Agent findings drop-box (generated)
    archive/             <- Processed inbox files (generated)
  docs/
    auto-discovery.md    <- Auto-discovery pipeline docs
    self-improvement.md  <- Self-improvement loop docs
    plan-lifecycle.md    <- Full plan pipeline: plan → PRD → implement → verify
    command-center.md    <- Command Center usage and features
    engine-restart.md    <- Engine restart and recovery procedures

Each linked project keeps locally:
  <project>/.claude/
    skills/              <- Project-specific skills (requires PR)

Per-project engine state remains centralized:
  ~/.minions/projects/<project-name>/
    work-items.json      <- Per-project work queue
    pull-requests.json   <- PR tracker