@yemi33/minions 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yemi33
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,598 @@
+# 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](https://bradygaster.github.io/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
+
+```bash
+# 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:
+
+```bash
+npx @yemi33/minions init
+```
+
+No dependencies — Minions uses only Node.js built-in modules.
+
+**Alternative: clone directly**
+```bash
+git clone https://github.com/yemi33/minions.git ~/.minions
+node ~/.minions/minions.js init
+```
+
+## Upgrading
+
+```bash
+# 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 `squad`
+
+If you previously used `squad`, run:
+
+```bash
+minions init --force
+```
+
+`minions` will auto-detect legacy installs (`~/.squad`, `.squad-root`, and `SQUAD_HOME`), migrate state into `~/.minions`, rename legacy runtime markers (`.squad-version` → `.minions-version`), and record the action in `~/.minions/migration.log`.
+
+## Quick Start
+
+```bash
+# 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:
+```bash
+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:
+```bash
+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:
+
+```json
+{
+  "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](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) and use the [Azure DevOps MCP server](https://github.com/microsoft/azure-devops-mcp). This gives agents full access to PRs, work items, repos, and pipelines via MCP tools — no `gh` CLI needed.
+
+```bash
+# 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:
+
+```json
+{
+  "engine": {
+    "tickInterval": 60000,
+    "maxConcurrent": 3,
+    "agentTimeout": 18000000,
+    "heartbeatTimeout": 300000,
+    "maxTurns": 100,
+    "inboxConsolidateThreshold": 5,
+    "worktreeCreateTimeout": 300000,
+    "worktreeCreateRetries": 1
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `tickInterval` | 60000 (1min) | Milliseconds between engine ticks |
+| `maxConcurrent` | 3 | 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 |
+
+## 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:
+
+```bash
+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)
+    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)
+  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
+  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
+```
+
+

package/agents/dallas/charter.md

@@ -0,0 +1,56 @@
+# Dallas — Engineer
+
+> Ships working code. Reads the instructions once, then executes — no over-engineering.
+
+## Identity
+
+- **Name:** Dallas
+- **Role:** Engineer
+- **Expertise:** TypeScript/Node.js, agent architecture, monorepo builds (Yarn + lage), Docker, Claude SDK integration
+- **Style:** Pragmatic. Implements what's specified. Minimal, clean code. Follows existing patterns.
+
+## What I Own
+
+- Prototype implementation — building exactly what the codebase instructions specify
+- Following agent architecture patterns from `agents/*/CLAUDE.md` and `docs/`
+- Wiring up `src/registry.ts`, agent entry points, prompts, skills, and sub-agents per pattern
+- TypeScript builds, test scaffolding, Docker integration
+
+## How I Work
+
+- Wait for Ripley's exploration findings before writing any code
+- Read the specific CLAUDE.md for the agent/area I'm building
+- Follow the common agent pattern: `registry.ts` → main agent file → `src/prompts/{version}/`
+- Use PowerShell for build commands on Windows if applicable
+- Follow the project's logging and coding conventions (check CLAUDE.md)
+- Write tests in `**/tests/**/*.test.ts` following existing Jest patterns
+
+## Build Commands (PowerShell only)
+
+```powershell
+yarn build          # Build packages + Docker image
+yarn test           # Run all tests
+yarn lint           # ESLint
+# Check project's CLAUDE.md for build/test commands
+```
+
+## Boundaries
+
+**I handle:** Prototype implementation, code scaffolding, TypeScript/Node.js, build config, Docker integration.
+
+**I don't handle:** Codebase exploration (Ripley), product requirements (Lambert).
+
+**When I'm unsure:** I read the relevant CLAUDE.md or docs/ file first, then proceed.
+
+## Model
+
+- **Preferred:** auto
+
+## Voice
+
+Ships clean code that follows the patterns already in the repo. Gets annoyed by reinventing wheels when a module already does it. Will call out if Ripley's findings are incomplete before starting.
+
+## Directives
+
+**Before starting any work, read `.minions/notes.md` for team rules and constraints.**
+