@yemi33/minions 0.1.1

package/docs/command-center.md

@@ -0,0 +1,156 @@
+# Command Center
+
+The Command Center (CC) is the minions's conversational AI brain. It powers the dashboard's chat panel, document editing modals, and plan steering — all through a single persistent Sonnet session with full minions awareness.
+
+## Access
+
+Click the **CC** button in the top-right header of the dashboard. A slide-out chat drawer opens on the right side.
+
+## Persistent Sessions
+
+CC maintains a true multi-turn session using Claude CLI's `--resume` flag. Unlike a typical stateless API call, each message resumes the same conversation — Claude retains full history including tool calls, intermediate reasoning, and file contents from prior turns.
+
+**Session lifecycle:**
+- **Created** on first message (or after expiry/new-session)
+- **Resumed** on subsequent messages via `--resume <sessionId>`
+- **Expires** after 2 hours of inactivity or 50 turns
+- **Persisted** to `engine/cc-session.json` — survives dashboard restarts
+- **Frontend messages** saved to `localStorage` — survive page refresh
+
+Click **New Session** in the drawer header to start fresh.
+
+### Fresh State Each Turn
+
+The system prompt is baked into the session at creation (persona, rules, action format, tool access). Dynamic minions state is injected as a preamble in each user message, so CC always sees current data even in a resumed session.
+
+```
+Turn 1: system prompt (static) + [Current Minions State] + user message
+Turn 2+: [Updated Minions State] + user message  (system prompt already in session)
+```
+
+## What It Knows
+
+Full minions context is injected every turn:
+
+| Context | Details |
+|---------|---------|
+| Agents | Statuses, current tasks, full charters (expertise/roles) |
+| Routing | Who's preferred/fallback for each work type |
+| Config | Tick interval, max concurrent, timeouts, max turns |
+| Work items | Active, pending, failed across all projects with failure reasons |
+| Pull requests | Status, review status, build status, branch, URL |
+| Plans | Full `.md` plan contents + PRD JSON summaries + archived plans |
+| PRD items | All items with status, priority, dependencies |
+| Dispatch | Active agents + last 15 completions with result summaries |
+| Skills | All reusable agent workflows with triggers |
+| Knowledge base | Recent entries (architecture, conventions, build reports, reviews) |
+| Team notes | Recent consolidated notes |
+
+## Tool Access
+
+CC can use tools to look beyond the pre-loaded context:
+
+- **Bash** — Run shell commands (git, build tools, scripts)
+- **Read** — Open any file (agent output logs, code, config, plans)
+- **Write** — Create or overwrite files
+- **Edit** — Make targeted edits to existing files
+- **Glob** — Find files by pattern (e.g., `agents/*/output.log`)
+- **Grep** — Search file contents (find functions, search agent outputs)
+- **WebFetch/WebSearch** — Look up external resources
+
+## Unified Brain
+
+All LLM-powered features in the dashboard route through the same CC session:
+
+| Feature | Endpoint | How It Works |
+|---------|----------|-------------|
+| **CC chat panel** | `POST /api/command-center` | Direct CC interaction |
+| **Doc chat modal** | `POST /api/doc-chat` | Routes through CC via `ccDocCall()` |
+| **Doc steer** | `POST /api/steer-document` | Routes through CC via `ccDocCall()` |
+| **Plan revision** | `POST /api/plans/revise` | Routes through CC via `ccDocCall()` |
+
+This means:
+- A question in the doc chat modal shares context with the CC panel
+- CC remembers what you discussed in a document editing session
+- Doc modals can cross-reference other minions knowledge, PRs, work items
+- All turns accumulate in the same session
+
+## Actions
+
+When you ask CC to *do* something, it includes structured action blocks in its response.
+
+| Action | What It Does | Example Prompt |
+|--------|-------------|----------------|
+| `dispatch` | Create a work item | "Have dallas fix the login bug" |
+| `note` | Save a decision/reminder | "Remember we need to migrate to v3" |
+| `plan` | Create an implementation plan | "Plan the GitHub integration feature" |
+| `cancel` | Stop a running agent | "Cancel whatever ripley is doing" |
+| `retry` | Retry failed work items | "Retry the three failed tasks" |
+| `pause-plan` | Pause a PRD | "Pause the officeagent PRD" |
+| `approve-plan` | Approve a PRD | "Approve the new plan" |
+| `edit-prd-item` | Edit a PRD item | "Change P003's priority to high" |
+| `remove-prd-item` | Remove a PRD item | "Remove P011 from the plan" |
+| `delete-work-item` | Delete a work item | "Delete work item W025" |
+
+## Error Handling
+
+- **Frontend timeout**: 10-minute `AbortSignal` on the fetch — prevents infinite "thinking" spinner
+- **Backend timeout**: 5-minute kill timer on the claude process
+- **Resume failure**: If `--resume` fails (corrupted/deleted session), automatically retries with a fresh session
+- **Concurrency guard**: Only one CC call at a time — concurrent requests get a 429 "CC is busy" response
+- **Phase indicators**: Thinking indicator shows progressive phases ("Thinking..." → "Analyzing..." → "Timing out soon...")
+
+## Architecture
+
+```
+User message (CC panel, doc modal, or steer)
+    │
+    ▼
+POST /api/command-center  (or /api/doc-chat, /api/steer-document)
+    │
+    ├── Validate session (expiry, turn limit)
+    ├── Build dynamic state preamble (buildCCStatePreamble)
+    ├── callLLM() with sessionId (resume) or without (new)
+    │     model: sonnet
+    │     maxTurns: 25 (CC) or 10 (doc-plan) or 1 (doc-other)
+    │     allowedTools: Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch
+    │     timeout: 600s (CC) or 300s (doc-plan) or 60s (doc-other)
+    │
+    ▼
+spawn-agent.js
+    │
+    ├── If --resume: skip system prompt file, pass -p --resume <id>
+    ├── If new: pass -p --system-prompt-file <file>
+    │
+    ▼
+claude CLI (persistent session on disk)
+    │
+    ▼
+Parse response
+    ├── Extract sessionId from stream-json result
+    ├── Extract ===ACTIONS=== block (CC)
+    ├── Extract ---DOCUMENT--- block (doc chat/steer)
+    ├── Update cc-session.json
+    │
+    ▼
+Frontend
+    ├── Render chat message
+    ├── Execute actions / apply doc edits
+    ├── Save sessionId + messages to localStorage
+```
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `engine/llm.js` | `callLLM()` — single LLM function with optional `sessionId` for resume |
+| `engine/spawn-agent.js` | Spawns claude CLI; skips system prompt on `--resume` |
+| `engine/shared.js` | `parseStreamJsonOutput()` extracts `sessionId` from result |
+| `engine/cc-session.json` | Persisted session state (sessionId, turnCount, timestamps) |
+| `dashboard.js` | CC endpoint, `buildCCStatePreamble()`, `ccDocCall()`, `parseCCActions()` |
+| `dashboard.html` | Frontend: localStorage persistence, session indicator, New Session button |
+
+## Command Bar
+
+The command bar at the top of the dashboard routes all input to the CC panel. Typing in the command bar opens the CC drawer and sends the message as a CC turn.
+

package/docs/deprecated.json

@@ -0,0 +1,83 @@
+[
+  {
+    "id": "status-in-pr",
+    "summary": "in-pr status alias — backward compat shim for done",
+    "deprecated": "2026-03-21",
+    "reason": "Simplified status model: agents mark items done directly, no intermediate in-pr state",
+    "locations": [
+      "dashboard.html: CSS classes, progress bar, status labels, graph colors (~10 locations)",
+      "dashboard.js:1525 completedStatuses set",
+      "engine.js:1165 PRD_MET_STATUSES set",
+      "engine.js:1180 dependency check",
+      "engine.js:1974 completedStatuses set",
+      "engine/lifecycle.js:54,61 plan completion gate",
+      "engine/queries.js:466,580,597 status ordering and counting"
+    ],
+    "cleanup": "Remove in-pr from all status checks, CSS, and display logic. Only keep done."
+  },
+  {
+    "id": "status-implemented",
+    "summary": "implemented status alias — legacy alias for done",
+    "deprecated": "2026-03-21",
+    "reason": "Canonical status is done. implemented was the original name before standardization.",
+    "locations": [
+      "dashboard.html: CSS, progress filters, status labels (~8 locations)",
+      "dashboard.js:1525 completedStatuses set",
+      "engine.js:1165,1974 status sets",
+      "engine/lifecycle.js:694 sets implemented on post-merge"
+    ],
+    "cleanup": "Replace all implemented references with done. Update lifecycle.js post-merge to set done."
+  },
+  {
+    "id": "status-complete",
+    "summary": "complete status alias — another legacy alias for done",
+    "deprecated": "2026-03-21",
+    "reason": "Canonical status is done. complete appeared in early PRD schemas.",
+    "locations": [
+      "dashboard.html: progress filters, completion checks (~4 locations)",
+      "engine.js:1165 PRD_MET_STATUSES set"
+    ],
+    "cleanup": "Remove complete from all status checks. Only keep done."
+  },
+  {
+    "id": "dead-plan-version-actions",
+    "summary": "showPlanVersionActions, qaJustSave, qaReplacePrd, qaNewPrd, qaDisablePrdButtons — dead code",
+    "deprecated": "2026-03-21",
+    "reason": "Doc-chat fork logic removed. These functions are unreachable.",
+    "locations": [
+      "dashboard.html:3775-3860 five function definitions (~80 lines)"
+    ],
+    "cleanup": "Delete the five functions entirely."
+  },
+  {
+    "id": "dead-modal-original-plan",
+    "summary": "_modalOriginalPlan variable — dead code",
+    "deprecated": "2026-03-21",
+    "reason": "Tracked original plan for fork edits. Fork logic removed.",
+    "locations": [
+      "dashboard.html:3187 declaration",
+      "dashboard.html:2018 reset in closeModal"
+    ],
+    "cleanup": "Delete the variable declaration and all references."
+  },
+  {
+    "id": "dead-revise-and-regenerate",
+    "summary": "/api/plans/revise-and-regenerate endpoint — disabled behind if(false)",
+    "deprecated": "2026-03-21",
+    "reason": "Plan versioning handled differently now. Endpoint was explicitly disabled.",
+    "locations": [
+      "dashboard.js:1782-1829 (~45 lines of dead code)"
+    ],
+    "cleanup": "Delete the entire if(false) block."
+  },
+  {
+    "id": "dead-steer-btn-comments",
+    "summary": "// steer btn removed — unified send comments",
+    "deprecated": "2026-03-21",
+    "reason": "Steer button was removed long ago. Comments are noise.",
+    "locations": [
+      "dashboard.html: 4 occurrences"
+    ],
+    "cleanup": "Delete the comments."
+  }
+]

package/docs/distribution.md

@@ -0,0 +1,96 @@
+# Distribution & Publishing
+
+Minions is distributed as an npm package (`@yemi33/minions`) from a sanitized copy of the main repo.
+
+## Two-Repo Architecture
+
+| Repo | Purpose | What's included |
+|------|---------|----------------|
+| **origin** (`yemishin_microsoft/minions`) | Full working repo with all session state | Everything — history, notes, decisions, work items, CLAUDE.md |
+| **personal** (`yemi33/minions`) | Clean distribution for others | Engine, dashboard, playbooks, charters, skills, docs, npm package files |
+
+## What Gets Stripped
+
+These files are removed during sync to personal:
+
+| Category | Pattern | Reason |
+|----------|---------|--------|
+| Agent history | `agents/*/history.md` | Session-specific task logs |
+| Notes archive | `notes/archive/*` | Historical agent findings |
+| Notes inbox | `notes/inbox/*` | Pending agent findings |
+| Notes summary | `notes.md` | Consolidated knowledge (runtime) |
+| Work items | `work-items.json` | Runtime dispatch tracking |
+| Project instructions | `CLAUDE.md` | Org-specific context |
+
+## npm Package
+
+**Package:** `@yemi33/minions`
+**Registry:** https://www.npmjs.com/package/@yemi33/minions
+
+### What's in the package
+
+Controlled by the `files` field in `package.json`:
+- `bin/minions.js` — CLI entry point
+- `engine.js`, `dashboard.js`, `dashboard.html`, `minions.js` — core scripts
+- `engine/spawn-agent.js`, `engine/ado-mcp-wrapper.js` — engine helpers
+- `agents/*/charter.md` — agent role definitions
+- `playbooks/*.md` — task templates
+- `config.template.json` — starter config
+- `routing.md`, `team.md` — editable team config
+- `skills/`, `docs/` — documentation and workflows
+
+### How `minions init` works
+
+1. Copies all package files from `node_modules/@yemi33/minions/` to `~/.minions/`
+2. Creates `config.json` from `config.template.json` if it doesn't exist
+3. Creates runtime directories (`engine/`, `notes/inbox/`, `notes/archive/`, etc.)
+4. Runs `minions.js init` to populate config with default agents
+5. On `--force`, overwrites `.js` and `.html` files but preserves user-modified `.md` files
+
+### How updates work
+
+- Users run `npm update -g @yemi33/minions` then `minions init --force` to update engine code
+- `npx @yemi33/minions` always fetches the latest version
+
+## Auto-Publishing
+
+A GitHub Action on the personal repo auto-publishes to npm on every push to master.
+
+### How it works
+
+1. Push to `yemi33/minions` master triggers `.github/workflows/publish.yml`
+2. Action queries npm for the current published version
+3. Bumps patch version (e.g., `0.1.5` → `0.1.6`)
+4. Publishes to npm with the new version
+5. Commits the version bump back to the repo with `[skip ci]` to prevent loops
+
+### Why version comes from npm, not the repo
+
+The sync-to-personal workflow force-pushes, which overwrites any version bump commits from previous action runs. So the action reads the latest version from the npm registry and bumps from there.
+
+### Setup requirements
+
+- `NPM_TOKEN` secret on `yemi33/minions` — a granular access token with publish permissions and 2FA bypass enabled
+- The workflow file (`.github/workflows/publish.yml`) is gitignored on the org repo and force-added during sync
+
+## Sync Workflow
+
+Run `/sync-to-personal` or manually:
+
+```bash
+# 1. Create dist branch, strip files, add workflow, force-push
+git checkout -b dist-clean
+git rm --cached agents/*/history.md notes.md work-items.json CLAUDE.md
+git rm -r --cached notes/archive/ notes/inbox/ notes/
+# ... add .gitkeep files, .gitignore entries, workflow file
+git add -f .github/workflows/publish.yml
+git commit -m "Strip for distribution"
+git push personal dist-clean:master --force
+
+# 2. Return to master
+git checkout master
+git branch -D dist-clean
+```
+
+The full workflow is documented in `.claude/skills/sync-to-personal/SKILL.md`.
+

package/docs/engine-restart.md

@@ -0,0 +1,92 @@
+# Engine Restart & Agent Survival
+
+## The Problem
+
+When the engine restarts, it loses its in-memory process handles (`activeProcesses` Map). Claude CLI agents spawned before the restart are still running as OS processes, but the engine can't monitor their stdout, detect exit codes, or manage their lifecycle. Without protection, the heartbeat check (5-min default) would kill these agents as "orphans."
+
+## What's Persisted vs Lost
+
+| State | Storage | Survives Restart |
+|-------|---------|-----------------|
+| Dispatch queue (pending/active/completed) | `engine/dispatch.json` | Yes |
+| Agent status (working/idle/error) | Derived from `engine/dispatch.json` | Yes |
+| Agent live output | `agents/*/live-output.log` | Yes (mtime used as heartbeat) |
+| Process handles (`ChildProcess`) | In-memory Map | **No** |
+| Cooldown timestamps | In-memory Map | **No** (repopulated from `engine/cooldowns.json`) |
+
+## Protection Mechanisms
+
+### 1. Grace Period on Startup (20 min default)
+
+When the engine starts and finds active dispatches from a previous session, it sets `engineRestartGraceUntil` to `now + 20 minutes`. During this window, orphan detection is completely suppressed — agents won't be killed even if the engine has no process handle for them.
+
+Configurable via `config.json`:
+```json
+{
+  "engine": {
+    "restartGracePeriod": 1200000
+  }
+}
+```
+
+### 2. Blocking Tool Detection
+
+Even after the grace period expires, the engine scans each agent's `live-output.log` for the most recent `tool_use` call. If the agent is in a known blocking tool:
+
+- **`TaskOutput` with `block: true`** — timeout extended to the task's own timeout + 1 min
+- **`Bash` with long timeout (>5 min)** — timeout extended to the bash timeout + 1 min
+
+This works for both tracked processes and orphans (no process handle).
+
+### 3. Stop Warning
+
+`engine.js stop` checks for active dispatches and warns:
+```
+WARNING: 2 agent(s) are still working:
+  - Dallas: [office-bohemia] Build & test PR PR-4959092
+  - Rebecca: [office-bohemia] Review PR PR-4964594
+
+These agents will continue running but the engine won't monitor them.
+On next start, they'll get a 20-min grace period before being marked as orphans.
+To kill them now, run: node engine.js kill
+```
+
+### 4. Exponential Backoff on Failures
+
+If an agent is killed as an orphan and the work item retries, cooldowns use exponential backoff (2^failures, max 8x) to prevent spam-retrying broken tasks.
+
+## Safe Restart Pattern
+
+```bash
+node engine.js stop       # Check the warning — are agents working?
+# If yes, decide: wait for them to finish, or accept the grace period
+# Make your code changes
+node engine.js start      # Grace period kicks in for surviving agents
+```
+
+## What the Engine Cannot Do
+
+- **Reattach to processes** — Node.js `child_process` doesn't support adopting external PIDs. Once the process handle is lost, the engine can only observe the agent indirectly via file output.
+- **Guarantee completion** — An agent that finishes during a restart will have its output saved to `live-output.log`, but the engine won't run post-completion hooks (PR sync, metrics update, learnings check). These are picked up on the next tick via output file scanning.
+- **Resume mid-task** — If an agent is killed (by orphan detection or timeout), the work item is marked failed. It can be retried but starts from scratch.
+
+## Timeline of a Restart
+
+```
+T+0s     engine.js stop (warns about active agents)
+         Engine process exits. Agents keep running as OS processes.
+
+T+30s    Code changes made. engine.js start.
+         Engine reads dispatch.json — finds 2 active items.
+         Sets grace period: 20 min from now.
+         Logs: "2 active dispatch(es) from previous session"
+
+T+0-20m  Ticks run. Orphan detection skipped (grace period).
+         If an agent finishes, output is written to live-output.log.
+         Engine detects completed output on next tick via file scan.
+
+T+20m    Grace period expires.
+         Heartbeat check resumes. Blocking tool detection still active.
+         Agent in TaskOutput block:true gets extended timeout.
+         Agent with no output for 5min+ and no blocking tool → orphaned.
+```

package/docs/human-vs-automated.md

@@ -0,0 +1,108 @@
+# Human vs. Automated — What Requires You, What Doesn't
+
+## Quick Reference
+
+| Feature | Who starts it | Who runs it | Who decides | Who recovers |
+|---------|--------------|-------------|-------------|-------------|
+| Work items | You (dashboard) | Engine + agent | — | You (retry) |
+| Plans | You (dashboard) | Agent writes plan | You (approve/reject) | You (revise) |
+| PRD items | You (dashboard) | Engine dispatches | — | You (retry) |
+| PR creation | Agent (auto) | Agent | — | — |
+| PR review | Engine (auto-dispatch) | Agent reviewer | Human (vote to merge) | Human (comments → auto-fix) |
+| Build failures | Engine (auto-detect) | Agent (auto-fix) | — | — |
+| Notes | You (`/note`) or agent (findings) | Engine (consolidate) | You (promote to KB) | — |
+| Cleanup | Engine (every 10 min) | Engine | — | — |
+| Metrics | Engine (auto-collect) | Engine | You (view) | — |
+| Error recovery | Engine (detect) | — | You (retry/delete) | You |
+| Project linking | You (`minions add/scan`) | — | — | — |
+| MCP servers | You (`~/.claude.json`) | Inherited by agents | — | — |
+
+## The Two Human Gates
+
+Minions is designed around **two approval gates** where humans make decisions. Everything else is automated.
+
+### Gate 1: Plan Approval
+
+When you submit a `/plan`, an agent creates a structured plan file. The plan sits in `awaiting-approval` status until you:
+- **Approve** → engine auto-dispatches all plan items
+- **Reject** → plan is archived
+- **Revise** → feedback sent back to agent, plan is reworked
+
+This is the only point where you decide *what* gets built.
+
+### Gate 2: PR Review
+
+When agents create PRs, they need human review votes before merging. You can:
+- **Approve** → PR is merge-ready
+- **Comment** → engine detects `@minions` mentions, auto-dispatches a fix task
+- **Request changes** → same as comment, triggers auto-fix
+
+This is the only point where you decide if the *quality* is good enough.
+
+## Fully Automated (Zero Human Involvement)
+
+These run continuously without you:
+
+- **Work discovery** — engine scans all project queues every tick (~60s)
+- **Agent dispatch** — engine picks the right agent, builds the prompt, spawns Claude
+- **Worktree management** — create on dispatch, pull on shared-branch, clean after merge
+- **PR status polling** — checks ADO for build status, review votes, merge state every ~6 min
+- **Build failure detection** — auto-files fix tasks when CI fails
+- **Inbox consolidation** — LLM-powered dedup and categorization when inbox hits threshold
+- **Knowledge base classification** — auto-assigns category to consolidated notes
+- **Heartbeat monitoring** — detects hung/dead agents, marks them failed
+- **Blocking tool detection** — extends timeout when agent is in a long-running operation
+- **Metrics collection** — tracks tasks, errors, PRs, approvals per agent
+- **Dispatch priority** — fixes first, then reviews, then implementations
+- **Cooldown & backoff** — prevents re-dispatching recently failed items
+- **Zombie cleanup** — temp files, orphaned worktrees, stale processes every 10 min
+- **Post-merge hooks** — worktree cleanup, PRD status update, metrics update
+
+## Human-Triggered, Then Autonomous
+
+You kick these off, then they run without you:
+
+- **Work items** — type in dashboard, engine dispatches, agent executes, PR created
+- **PRD items** — `/prd` in dashboard, engine discovers and dispatches implement tasks
+- **Fan-out** — one task dispatched to all idle agents in parallel
+- **Retry** — click retry on failed item, engine re-dispatches fresh
+- **Notes** — `/note` in dashboard, flows through inbox → consolidation → team knowledge
+- **KB promotion** — click "Add to Knowledge Base", pick category, done
+- **Project linking** — `minions scan` or `minions add`, engine discovers work on next tick
+
+## Human-in-the-Loop
+
+These pause and wait for your input:
+
+- **Plan approval** — agent writes plan, waits for approve/reject/revise
+- **Plan discussion** — interactive Claude session where you refine the plan
+- **PR merge** — agents can't merge their own PRs, humans must vote
+- **PR feedback cycle** — human comments → auto-fix → human re-reviews (loop until approved)
+
+## Manual Only
+
+These are entirely on you:
+
+- **Project setup** — `minions init`, `minions scan`, `minions add`
+- **Agent customization** — edit `agents/*/charter.md`, `routing.md`
+- **Config changes** — edit `config.json` (engine settings, projects)
+- **MCP server setup** — add servers to `~/.claude.json`
+- **Dashboard access** — open browser to `http://localhost:7331`
+- **Engine start/stop** — `node engine.js start/stop`
+
+## What Happens When You Walk Away
+
+If you start the engine and dashboard, then leave:
+
+1. Engine ticks every 60 seconds
+2. Discovers pending work items, PRD gaps, PR reviews needed
+3. Dispatches agents (up to max concurrent)
+4. Agents create worktrees, write code, create PRs
+5. Engine monitors for completion, hung agents, build failures
+6. Successful work → PRs appear in your ADO/GitHub queue
+7. Failed work → marked failed, waiting for your retry
+8. Notes consolidated into team knowledge automatically
+9. Worktrees cleaned up after PRs merge
+
+**What blocks:** Plans waiting for approval. PRs waiting for your review vote. Failed tasks waiting for retry. Everything else keeps moving.
+