npm - @yemi33/minions - Versions diffs - 0.1.1 - Mend

@yemi33/minions 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (54) hide show

package/CHANGELOG.md +819 -0
package/LICENSE +21 -0
package/README.md +598 -0
package/agents/dallas/charter.md +56 -0
package/agents/lambert/charter.md +67 -0
package/agents/ralph/charter.md +45 -0
package/agents/rebecca/charter.md +57 -0
package/agents/ripley/charter.md +47 -0
package/bin/minions.js +467 -0
package/config.template.json +28 -0
package/dashboard.html +4822 -0
package/dashboard.js +2623 -0
package/docs/auto-discovery.md +416 -0
package/docs/blog-first-successful-dispatch.md +128 -0
package/docs/command-center.md +156 -0
package/docs/demo/01-dashboard-overview.gif +0 -0
package/docs/demo/02-command-center.gif +0 -0
package/docs/demo/03-work-items.gif +0 -0
package/docs/demo/04-plan-docchat.gif +0 -0
package/docs/demo/05-prd-progress.gif +0 -0
package/docs/demo/06-inbox-metrics.gif +0 -0
package/docs/deprecated.json +83 -0
package/docs/distribution.md +96 -0
package/docs/engine-restart.md +92 -0
package/docs/human-vs-automated.md +108 -0
package/docs/index.html +221 -0
package/docs/plan-lifecycle.md +140 -0
package/docs/self-improvement.md +344 -0
package/engine/ado-mcp-wrapper.js +42 -0
package/engine/ado.js +383 -0
package/engine/check-status.js +23 -0
package/engine/cli.js +754 -0
package/engine/consolidation.js +417 -0
package/engine/github.js +331 -0
package/engine/lifecycle.js +1113 -0
package/engine/llm.js +116 -0
package/engine/queries.js +677 -0
package/engine/shared.js +397 -0
package/engine/spawn-agent.js +151 -0
package/engine.js +3227 -0
package/minions.js +556 -0
package/package.json +48 -0
package/playbooks/ask.md +49 -0
package/playbooks/build-and-test.md +155 -0
package/playbooks/explore.md +64 -0
package/playbooks/fix.md +57 -0
package/playbooks/implement-shared.md +68 -0
package/playbooks/implement.md +95 -0
package/playbooks/plan-to-prd.md +104 -0
package/playbooks/plan.md +99 -0
package/playbooks/review.md +68 -0
package/playbooks/test.md +75 -0
package/playbooks/verify.md +190 -0
package/playbooks/work-item.md +74 -0

package/docs/index.html ADDED Viewed

@@ -0,0 +1,221 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Minions — Multi-Agent AI Dev Team</title>
+<meta name="description" content="5 autonomous AI agents, one engine, one dashboard. Minions orchestrates Claude-powered agents to plan, implement, review, and ship code autonomously.">
+<style>
+  :root { --bg: #0d1117; --surface: #161b22; --border: #30363d; --text: #c9d1d9; --muted: #8b949e; --blue: #58a6ff; --green: #3fb950; --yellow: #d29922; --red: #f85149; --purple: #bc8cff; }
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg); color: var(--text); line-height: 1.6; }
+  /* Hero */
+  .hero { text-align: center; padding: 80px 20px 60px; }
+  .hero h1 { font-size: 3.5em; color: var(--blue); margin-bottom: 12px; letter-spacing: -1px; }
+  .hero h1 span { color: var(--text); }
+  .hero .tagline { font-size: 1.3em; color: var(--muted); max-width: 600px; margin: 0 auto 32px; }
+  .hero-badges { display: flex; gap: 12px; justify-content: center; flex-wrap: wrap; margin-bottom: 32px; }
+  .hero-badge { display: inline-flex; align-items: center; gap: 6px; padding: 6px 14px; border-radius: 20px; font-size: 13px; font-weight: 600; border: 1px solid var(--border); background: var(--surface); }
+  .hero-badge.green { color: var(--green); border-color: rgba(63,185,80,0.3); }
+  .hero-badge.blue { color: var(--blue); border-color: rgba(88,166,255,0.3); }
+  .hero-badge.yellow { color: var(--yellow); border-color: rgba(210,153,34,0.3); }
+  .hero-badge.purple { color: var(--purple); border-color: rgba(188,140,255,0.3); }
+  .cta { display: inline-flex; gap: 12px; flex-wrap: wrap; justify-content: center; }
+  .cta a { padding: 12px 28px; border-radius: 8px; font-weight: 600; font-size: 15px; text-decoration: none; transition: all 0.2s; }
+  .cta-primary { background: var(--blue); color: var(--bg); }
+  .cta-primary:hover { background: #79c0ff; }
+  .cta-secondary { background: var(--surface); color: var(--text); border: 1px solid var(--border); }
+  .cta-secondary:hover { border-color: var(--blue); color: var(--blue); }
+  /* Container */
+  .container { max-width: 1100px; margin: 0 auto; padding: 0 20px; }
+  /* Agents strip */
+  .agents-strip { display: flex; justify-content: center; gap: 24px; padding: 40px 20px; flex-wrap: wrap; }
+  .agent-pill { display: flex; align-items: center; gap: 8px; padding: 10px 18px; background: var(--surface); border: 1px solid var(--border); border-radius: 12px; }
+  .agent-pill .emoji { font-size: 1.4em; }
+  .agent-pill .name { font-weight: 700; color: var(--text); font-size: 14px; }
+  .agent-pill .role { color: var(--muted); font-size: 12px; }
+  /* Features grid */
+  .features { display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 16px; padding: 40px 0; }
+  .feature { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 24px; }
+  .feature h3 { color: var(--blue); font-size: 1em; margin-bottom: 6px; }
+  .feature p { color: var(--muted); font-size: 13px; line-height: 1.5; }
+  /* Scenario sections */
+  .scenario { margin: 60px 0; }
+  .scenario-header { display: flex; align-items: center; gap: 14px; margin-bottom: 12px; }
+  .scenario-num { background: var(--blue); color: var(--bg); font-weight: 700; width: 36px; height: 36px; border-radius: 50%; display: flex; align-items: center; justify-content: center; font-size: 15px; flex-shrink: 0; }
+  .scenario h2 { font-size: 1.5em; color: #f0f6fc; }
+  .scenario > p { color: var(--muted); margin-bottom: 16px; max-width: 800px; font-size: 15px; }
+  .demo-frame { border: 1px solid var(--border); border-radius: 10px; overflow: hidden; box-shadow: 0 8px 32px rgba(0,0,0,0.4); }
+  .demo-frame img { width: 100%; display: block; }
+  .demo-caption { background: var(--surface); padding: 10px 18px; font-size: 13px; color: var(--muted); border-top: 1px solid var(--border); }
+  /* Inline badges */
+  .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 11px; font-weight: 600; }
+  .badge-green { background: rgba(63,185,80,0.15); color: var(--green); border: 1px solid rgba(63,185,80,0.3); }
+  .badge-blue { background: rgba(88,166,255,0.15); color: var(--blue); border: 1px solid rgba(88,166,255,0.3); }
+  .badge-yellow { background: rgba(210,153,34,0.15); color: var(--yellow); border: 1px solid rgba(210,153,34,0.3); }
+  .badge-red { background: rgba(248,81,73,0.15); color: var(--red); border: 1px solid rgba(248,81,73,0.3); }
+  .hl { color: var(--green); font-weight: 600; }
+  /* Quick start */
+  .quickstart { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 32px; margin: 60px 0; }
+  .quickstart h2 { color: var(--blue); margin-bottom: 16px; }
+  .quickstart pre { background: var(--bg); border: 1px solid var(--border); border-radius: 8px; padding: 16px 20px; overflow-x: auto; font-size: 14px; line-height: 1.8; color: var(--green); }
+  .quickstart pre .comment { color: var(--muted); }
+  /* Architecture */
+  .arch { text-align: center; padding: 60px 0; }
+  .arch h2 { color: var(--blue); margin-bottom: 20px; }
+  .arch pre { background: var(--surface); border: 1px solid var(--border); border-radius: 10px; padding: 24px; display: inline-block; text-align: left; font-size: 13px; color: var(--muted); line-height: 1.7; }
+  /* Footer */
+  footer { text-align: center; color: #484f58; padding: 40px 0; border-top: 1px solid #21262d; margin-top: 80px; font-size: 13px; }
+  footer a { color: var(--blue); text-decoration: none; }
+</style>
+</head>
+<body>
+<!-- Hero -->
+<div class="hero">
+  <h1>Minions <span>Mission Control</span></h1>
+  <p class="tagline">5 autonomous AI agents, one engine, one dashboard. Plan, implement, review, and ship code — hands-free.</p>
+  <div class="hero-badges">
+    <span class="hero-badge green">Zero Dependencies</span>
+    <span class="hero-badge blue">Claude-Powered</span>
+    <span class="hero-badge yellow">Multi-Project</span>
+    <span class="hero-badge purple">Self-Improving</span>
+  </div>
+  <div class="cta">
+    <a href="https://github.com/yemi33/minions" class="cta-primary">View on GitHub</a>
+    <a href="#quickstart" class="cta-secondary">Quick Start</a>
+  </div>
+</div>
+<!-- Agent strip -->
+<div class="agents-strip">
+  <div class="agent-pill"><span class="emoji">&#x1F3D7;&#xFE0F;</span><div><div class="name">Ripley</div><div class="role">Lead / Explorer</div></div></div>
+  <div class="agent-pill"><span class="emoji">&#x1F527;</span><div><div class="name">Dallas</div><div class="role">Engineer</div></div></div>
+  <div class="agent-pill"><span class="emoji">&#x1F4CA;</span><div><div class="name">Lambert</div><div class="role">Analyst</div></div></div>
+  <div class="agent-pill"><span class="emoji">&#x1F9E0;</span><div><div class="name">Rebecca</div><div class="role">Architect</div></div></div>
+  <div class="agent-pill"><span class="emoji">&#x2699;&#xFE0F;</span><div><div class="name">Ralph</div><div class="role">Engineer</div></div></div>
+</div>
+<!-- Features -->
+<div class="container">
+<div class="features">
+  <div class="feature"><h3>Autonomous Dispatch</h3><p>Engine discovers work from PRDs, PRs, and manual queue — routes to the right agent based on skills and availability.</p></div>
+  <div class="feature"><h3>Plan Lifecycle</h3><p>Plan &rarr; Review &rarr; Approve &rarr; PRD &rarr; Execute &rarr; Verify. Human-in-the-loop at every gate.</p></div>
+  <div class="feature"><h3>Git Worktree Isolation</h3><p>Each agent works in its own worktree. No conflicts, no cross-contamination, safe parallel execution.</p></div>
+  <div class="feature"><h3>Knowledge Consolidation</h3><p>Agent findings auto-consolidate into team notes and a searchable knowledge base. The minions learns as it works.</p></div>
+  <div class="feature"><h3>PR Integration</h3><p>Auto-syncs PRs from Azure DevOps and GitHub. Detects review feedback, build failures, and human comments.</p></div>
+  <div class="feature"><h3>Live Dashboard</h3><p>Real-time mission control on port 7331. Agent status, work items, PRD progress, dispatch queue, and metrics.</p></div>
+</div>
+<!-- Demo scenarios -->
+<div class="scenario">
+  <div class="scenario-header"><div class="scenario-num">1</div><h2>Dashboard Overview</h2></div>
+  <p>All 5 agents visible with live status — <span class="hl">3 working</span>, <span class="hl">2 idle</span>. Work items sorted by priority, PRD progress with dependency tracking.</p>
+  <div class="demo-frame">
+    <img src="demo/01-dashboard-overview.gif" alt="Dashboard overview with agents working">
+    <div class="demo-caption">Scrolling through: Minions Members, Work Items (6 items across statuses), and PRD Progress (40% complete)</div>
+  </div>
+</div>
+<div class="scenario">
+  <div class="scenario-header"><div class="scenario-num">2</div><h2>Command Center</h2></div>
+  <p>Natural language interface — type what you need. Create plans, dispatch work, ask questions about the codebase.</p>
+  <div class="demo-frame">
+    <img src="demo/02-command-center.gif" alt="Command Center typing">
+    <div class="demo-caption"><span class="badge badge-blue">CC</span> Typing a plan request, then switching to a one-off work item — the CC routes each to the right action</div>
+  </div>
+</div>
+<div class="scenario">
+  <div class="scenario-header"><div class="scenario-num">3</div><h2>Work Items</h2></div>
+  <p>Full lifecycle: <span class="badge badge-yellow">PENDING</span> <span class="badge badge-blue">DISPATCHED</span> <span class="badge badge-blue">IN-PR</span> <span class="badge badge-green">DONE</span> <span class="badge badge-red">FAILED</span>. Retry failed items with one click.</p>
+  <div class="demo-frame">
+    <img src="demo/03-work-items.gif" alt="Work items table">
+    <div class="demo-caption">Work items with mixed statuses — hovering over <span class="badge badge-red">Retry</span> on a failed exploration task</div>
+  </div>
+</div>
+<div class="scenario">
+  <div class="scenario-header"><div class="scenario-num">4</div><h2>Plan &amp; Doc Chat</h2></div>
+  <p>Click any plan to open its detail modal. Use the built-in doc chat to ask questions, steer direction, and revise — all before executing.</p>
+  <div class="demo-frame">
+    <img src="demo/04-plan-docchat.gif" alt="Plan detail with doc chat">
+    <div class="demo-caption">Opening a plan, viewing rendered markdown, then asking "What are the security implications?" in the doc chat</div>
+  </div>
+</div>
+<div class="scenario">
+  <div class="scenario-header"><div class="scenario-num">5</div><h2>PRD Progress</h2></div>
+  <p>PRD items track dependencies and block dispatching until prerequisites complete. Progress bar shows done items.</p>
+  <div class="demo-frame">
+    <img src="demo/05-prd-progress.gif" alt="PRD progress with dependencies">
+    <div class="demo-caption">"User Authentication &amp; Authorization" — 5 items with dependency chains, 2 done, 3 to do</div>
+  </div>
+</div>
+<div class="scenario">
+  <div class="scenario-header"><div class="scenario-num">6</div><h2>Inbox &amp; Metrics</h2></div>
+  <p>Agent findings flow to the inbox, get consolidated by Haiku into team notes, and classified into the knowledge base. Quality metrics track per-agent performance.</p>
+  <div class="demo-frame">
+    <img src="demo/06-inbox-metrics.gif" alt="Inbox and metrics">
+    <div class="demo-caption">Inbox with agent findings, dispatch queue with completed tasks, and agent quality metrics</div>
+  </div>
+</div>
+<!-- Quick Start -->
+<div class="quickstart" id="quickstart">
+  <h2>Quick Start</h2>
+  <pre><span class="comment"># Install</span>
+npm install -g @yemi33/minions
+<span class="comment"># Initialize — scans for repos, starts engine + dashboard</span>
+minions init
+<span class="comment"># Open dashboard</span>
+open http://localhost:7331
+<span class="comment"># Use the Command Center to create your first plan</span>
+<span class="comment"># Or add work items directly from the dashboard</span></pre>
+</div>
+<!-- Architecture -->
+<div class="arch">
+  <h2>Architecture</h2>
+  <pre>
+  ┌─────────────────────────────────────────────────────┐
+  │                  ~/.minions/ (central hub)              │
+  │                                                       │
+  │   engine.js ──── 60s tick loop ────┐                 │
+  │       │                            │                  │
+  │   discover work    spawn agents    poll PRs           │
+  │       │                │              │               │
+  │   ┌───┴───┐    ┌──────┴──────┐   ┌──┴───┐           │
+  │   │ PRDs  │    │  Worktrees  │   │ ADO  │           │
+  │   │ Items │    │  (isolated) │   │ GitHub│           │
+  │   └───────┘    └─────────────┘   └──────┘           │
+  │                                                       │
+  │   dashboard.js ── port 7331 ── mission control       │
+  │   notes.md ── consolidated team knowledge            │
+  │   knowledge/ ── searchable KB by category            │
+  └─────────────────────────────────────────────────────┘
+  </pre>
+</div>
+</div>
+<footer>
+  <p>Minions &mdash; <a href="https://github.com/yemi33/minions">GitHub</a> &mdash; MIT License &mdash; Zero dependencies, powered by Claude</p>
+</footer>
+</body>
+</html>

package/docs/plan-lifecycle.md ADDED Viewed

@@ -0,0 +1,140 @@
+# Plan Lifecycle
+How plans go from idea to verified, running code.
+## Pipeline
+```
+/plan "feature description"
+  → agent writes plan JSON (plan-*.json)
+  → engine chains plan → PRD (plan-to-prd)
+  → agent converts plan into structured PRD items with acceptance criteria
+  → engine materializes PRD items as work items (PL-W001, PL-W002, ...)
+  → engine dispatches work items respecting dependency order
+  → agents implement each item, create PRs
+  → engine auto-reviews PRs, handles feedback loops
+  → all items done → engine creates VERIFY task
+  → verify agent builds everything, starts webapp, writes testing guide
+```
+## Dependency Management
+### Dispatch Gating
+PRD items can declare `depends_on: ["P001", "P003"]`. The engine won't dispatch an item until all its dependencies have status `done`. This prevents agents from starting work before prerequisite code exists.
+### Branch Merging at Spawn
+When an agent is spawned for a work item with dependencies, the engine merges the dependency PR branches into the worktree **before the agent starts**. This solves the problem where dependencies have PRs but haven't been merged to `main` yet.
+```
+Agent gets work item PL-W006 (plan item P009)
+  depends_on: ["P006", "P007"]
+spawnAgent():
+  1. Create worktree from main:
+     git worktree add ../worktrees/work/PL-W006 -b work/PL-W006 main
+  2. Resolve dependencies:
+     P006 → work item PL-W001 → PR-4970100 → branch work/PL-W001
+     P007 → work item PL-W002 → PR-4970101 → branch work/PL-W002
+  3. Merge dependency branches:
+     git fetch origin work/PL-W001 work/PL-W002
+     git merge origin/work/PL-W001 --no-edit
+     git merge origin/work/PL-W002 --no-edit
+  4. Agent starts with all dependency changes present
+```
+If a merge conflict occurs, it's logged as a warning. The agent will see conflict markers and can resolve them, or the task will fail and get retried after the dependency PRs are merged to `main`.
+### Resolution Chain
+```
+depends_on: ["P-43e5ac28"]
+  → find work items where id = "P-43e5ac28" (across all projects)
+  → find PRs where prdItems includes "P-43e5ac28"
+  → extract branch names from those PRs
+  → fetch + merge into worktree
+```
+## Plan Completion
+When all PRD items reach `done` or `failed` status, `checkPlanCompletion()` fires:
+1. **Completion summary** written to `notes/inbox/` with results, timing, and PR list
+2. **Verification task** created (type `verify`, priority `high`) — see below
+3. **PR work item** created for shared-branch plans (to merge the feature branch)
+4. **Plan archived** to `plans/archive/`
+## Verification Task
+The verification task (`planItemId: "VERIFY"`) is the final step. It:
+1. **Creates one worktree per affected project** with all PR branches merged in — not separate worktrees per branch. This means the agent builds and tests from a single directory per project with all changes combined.
+2. **Builds and tests** every affected project from its worktree.
+3. **Starts the webapp** on localhost if applicable, and keeps it running so the user can see it.
+4. **Writes a manual testing guide** (`notes/inbox/verify-*.md`) with:
+   - Build/test status table per project
+   - Feature-by-feature testing steps based on acceptance criteria
+   - Integration points to verify across projects
+   - Known issues
+   - Quick smoke test checklist
+   - Exact restart commands with absolute paths
+### Verification Worktree Setup
+```
+# project-a — 3 PRs merged into one worktree
+cd ~/project-a
+git fetch origin "work/PL-W001" "work/PL-W002" "work/PL-W003" "main"
+git worktree add "../worktrees/verify-my-plan-2026-03-15" "origin/main"
+cd "../worktrees/verify-my-plan-2026-03-15"
+git merge "origin/work/PL-W001" --no-edit
+git merge "origin/work/PL-W002" --no-edit
+git merge "origin/work/PL-W003" --no-edit
+# project-b — 2 PRs merged into one worktree
+cd ~/project-b
+git fetch origin "feat/PL-W004" "feat/PL-W005" "master"
+git worktree add "../worktrees/verify-my-plan-2026-03-15" "origin/master"
+cd "../worktrees/verify-my-plan-2026-03-15"
+git merge "origin/feat/PL-W004" --no-edit
+git merge "origin/feat/PL-W005" --no-edit
+```
+The verify agent and the user can then build and run from these paths.
+## Human Feedback on PRs
+After PRs are created, humans can leave comments containing `@minions` to trigger fix tasks. If you're the only human commenting, any comment triggers a fix — no keyword needed. See `pollPrHumanComments()` in `engine/ado.js`.
+## Routing
+| Type | Preferred | Fallback |
+|------|-----------|----------|
+| plan | ripley | rebecca |
+| plan-to-prd | lambert | rebecca |
+| implement | dallas | ralph |
+| implement:large | rebecca | dallas |
+| review | ripley | lambert |
+| fix | _author_ | dallas |
+| verify | dallas | ralph |
+| test | dallas | ralph |
+## Key Files
+| File | Purpose |
+|------|---------|
+| `plans/*.json` | Active plan files with PRD items |
+| `plans/archive/` | Completed/archived plans |
+| `playbooks/verify.md` | Verification task playbook |
+| `playbooks/implement.md` | Implementation playbook |
+| `playbooks/plan-to-prd.md` | Plan → PRD conversion playbook |
+| `engine/lifecycle.js` | `checkPlanCompletion`, `chainPlanToPrd` |
+| `engine.js` | `spawnAgent` (dependency merging), `resolveDependencyBranches` |