@yemi33/minions 0.1.1885 → 0.1.1887

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 (9) hide show
  1. package/docs/distribution.md +79 -0
  2. package/docs/index.html +33 -45
  3. package/engine/lifecycle.js +16 -2
  4. package/package.json +1 -1
  5. package/playbooks/explore.md +1 -1
  6. package/playbooks/meeting-conclude.md +13 -3
  7. package/playbooks/meeting-investigate.md +4 -0
  8. package/playbooks/plan.md +16 -10
  9. package/playbooks/review.md +7 -4
package/docs/distribution.md ADDED
@@ -0,0 +1,79 @@
1
+ # Distribution & Publishing
2
+
3
+ Minions is distributed as an npm package (`@yemi33/minions`) from a sanitized package boundary.
4
+
5
+ ## Distribution Boundary
6
+
7
+ | Surface | Purpose | What's included |
8
+ |------|---------|----------------|
9
+ | **source repository** | Private development and automation | Working code, project history, and release workflows |
10
+ | **npm package** (`@yemi33/minions`) | Public installation for users | Engine, dashboard, playbooks, charters, skills, docs, and package files |
11
+
12
+ ## What Gets Stripped
13
+
14
+ These files are excluded from published packages:
15
+
16
+ | Category | Pattern | Reason |
17
+ |----------|---------|--------|
18
+ | Agent history | `agents/*/history.md` | Session-specific task logs |
19
+ | Notes archive | `notes/archive/*` | Historical agent findings |
20
+ | Notes inbox | `notes/inbox/*` | Pending agent findings |
21
+ | Notes summary | `notes.md` | Consolidated knowledge (runtime) |
22
+ | Work items | `work-items.json` | Runtime dispatch tracking |
23
+ | Project instructions | `CLAUDE.md` | Org-specific context |
24
+
25
+ ## npm Package
26
+
27
+ **Package:** `@yemi33/minions`
28
+ **Registry:** https://www.npmjs.com/package/@yemi33/minions
29
+
30
+ ### What's in the package
31
+
32
+ Controlled by the `files` field in `package.json`:
33
+ - `bin/minions.js` — CLI entry point
34
+ - `engine.js`, `dashboard.js`, `dashboard/` (fragments), `minions.js` — core scripts
35
+ - `engine/spawn-agent.js`, `engine/ado-mcp-wrapper.js` — engine helpers
36
+ - `agents/*/charter.md` — agent role definitions
37
+ - `playbooks/*.md` — task templates
38
+ - `config.template.json` — starter config
39
+ - `routing.md`, `team.md` — editable team config
40
+ - `skills/`, `docs/` — documentation and workflows
41
+
42
+ ### How `minions init` works
43
+
44
+ 1. Copies all package files from `node_modules/@yemi33/minions/` to `~/.minions/`
45
+ 2. Creates `config.json` from `config.template.json` if it doesn't exist
46
+ 3. Creates runtime directories (`engine/`, `notes/inbox/`, `notes/archive/`, etc.)
47
+ 4. Runs `minions.js init` to populate config with default agents
48
+ 5. On `--force`, overwrites `.js` and `.html` files but preserves user-modified `.md` files
49
+
50
+ ### How updates work
51
+
52
+ - Users run `npm update -g @yemi33/minions` then `minions init --force` to update engine code
53
+ - `npx @yemi33/minions` always fetches the latest version
54
+
55
+ ## Auto-Publishing
56
+
57
+ A GitHub Action on the personal repo auto-publishes to npm on every push to master.
58
+
59
+ ### How it works
60
+
61
+ 1. Push to `yemi33/minions` master triggers `.github/workflows/publish.yml`
62
+ 2. Action queries npm for the current published version
63
+ 3. Bumps patch version (e.g., `0.1.5` → `0.1.6`)
64
+ 4. Publishes to npm with the new version
65
+ 5. Commits the version bump back to the repo with `[skip ci]` to prevent loops
66
+
67
+ ### Why version comes from npm, not the repo
68
+
69
+ 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.
70
+
71
+ ### Setup requirements
72
+
73
+ - `NPM_TOKEN` secret on `yemi33/minions` — a granular access token with publish permissions and 2FA bypass enabled
74
+ - The workflow file (`.github/workflows/publish.yml`) is not included in the npm package
75
+
76
+ ## Sync Workflow
77
+
78
+ Repository and package publishing automation should keep private repository names, tokens, runtime state, and internal-only metadata out of public docs and public package contents.
79
+
package/docs/index.html CHANGED
@@ -3,8 +3,8 @@
3
3
  <head>
4
4
  <meta charset="UTF-8">
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Minions &mdash; Multi-Agent AI Dev Team</title>
7
- <meta name="description" content="Five autonomous coding agents, one engine, and one dashboard. Minions orchestrates Claude or GitHub Copilot agents to plan, implement, review, verify, and ship code.">
6
+ <title>Minions — Multi-Agent AI Dev Team</title>
7
+ <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.">
8
8
  <style>
9
9
  :root { --bg: #0d1117; --surface: #161b22; --border: #30363d; --text: #c9d1d9; --muted: #8b949e; --blue: #58a6ff; --green: #3fb950; --yellow: #d29922; --red: #f85149; --purple: #bc8cff; }
10
10
  * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -83,15 +83,15 @@
83
83
  <!-- Hero -->
84
84
  <div class="hero">
85
85
  <h1>Minions <span>Mission Control</span></h1>
86
- <p class="tagline">Five autonomous coding agents, one engine, one dashboard. Plan, implement, review, verify, and ship code with human control at every gate.</p>
86
+ <p class="tagline">5 autonomous AI agents, one engine, one dashboard. Plan, implement, review, and ship code &mdash; hands-free.</p>
87
87
  <div class="hero-badges">
88
- <span class="hero-badge green">Node.js 18+</span>
89
- <span class="hero-badge blue">Claude or Copilot</span>
88
+ <span class="hero-badge green">Zero Dependencies</span>
89
+ <span class="hero-badge blue">Claude-Powered</span>
90
90
  <span class="hero-badge yellow">Multi-Project</span>
91
- <span class="hero-badge purple">Dashboard + CLI</span>
91
+ <span class="hero-badge purple">Self-Improving</span>
92
92
  </div>
93
93
  <div class="cta">
94
- <a href="https://www.npmjs.com/package/@yemi33/minions" class="cta-primary">Install from npm</a>
94
+ <a href="https://github.com/yemi33/minions" class="cta-primary">View on GitHub</a>
95
95
  <a href="#quickstart" class="cta-secondary">Quick Start</a>
96
96
  </div>
97
97
  </div>
@@ -108,25 +108,24 @@
108
108
  <!-- Features -->
109
109
  <div class="container">
110
110
  <div class="features">
111
- <div class="feature"><h3>Autonomous Dispatch</h3><p>Engine discovers work from plans, PRs, schedules, pipelines, and queues &mdash; then routes to the right agent by role, skill, and availability.</p></div>
112
- <div class="feature"><h3>Plan Lifecycle</h3><p>Plan &rarr; Approve &rarr; PRD &rarr; Execute &rarr; Review &rarr; Verify. Completed plans stay available until you manually archive them.</p></div>
111
+ <div class="feature"><h3>Autonomous Dispatch</h3><p>Engine discovers work from plans, PRs, pipelines, and queues &mdash; routes to the right agent based on skills and availability.</p></div>
112
+ <div class="feature"><h3>Plan Lifecycle</h3><p>Plan &rarr; Approve &rarr; PRD &rarr; Execute &rarr; Review &rarr; Verify. Human-in-the-loop at every gate.</p></div>
113
113
  <div class="feature"><h3>Team Meetings</h3><p>Multi-agent meetings with investigate, debate, and conclude rounds. Agents research, discuss, and produce actionable conclusions.</p></div>
114
114
  <div class="feature"><h3>Multi-Stage Pipelines</h3><p>Chain tasks, meetings, plans, and more into automated workflows. Cron triggers or manual. Artifacts flow between stages.</p></div>
115
- <div class="feature"><h3>Review / Fix Loop</h3><p>After implementation, Minions can dispatch reviews, react to human PR comments, and send fixes back to the original author agent.</p></div>
115
+ <div class="feature"><h3>Eval Loop</h3><p>After implementation, auto-dispatches review &rarr; fix cycles. Configurable iterations and cost ceiling per work item.</p></div>
116
116
  <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>
117
- <div class="feature"><h3>Knowledge Consolidation</h3><p>Agent findings, quick notes, pinned notes, and feedback consolidate into team notes and a categorized knowledge base.</p></div>
118
- <div class="feature"><h3>PR Integration</h3><p>Tracks Azure DevOps and GitHub PRs, including review votes, build status, merge status, human comments, and context-only links.</p></div>
119
- <div class="feature"><h3>Scheduled Tasks &amp; Watches</h3><p>Cron-style recurring work plus watches for PRs, work items, dispatches, meetings, pipelines, agents, and status changes.</p></div>
120
- <div class="feature"><h3>Command Center &amp; Doc Chat</h3><p>Natural language orchestration, persistent CC tabs, document Q&amp;A/editing, issue filing, routing updates, and local API actions.</p></div>
121
- <div class="feature"><h3>Pluggable Runtimes</h3><p>Run agents through Claude Code or GitHub Copilot CLI, with runtime-specific models, effort, session resume, and permission handling.</p></div>
122
- <div class="feature"><h3>Live Dashboard</h3><p>Real-time mission control on port 7331 with paginated views, optimistic updates, live streams, metrics, and settings.</p></div>
123
- <div class="feature"><h3>One-Command Updates</h3><p><code>minions update</code> pulls the latest npm package, reapplies files, and restarts while preserving config and customizations.</p></div>
117
+ <div class="feature"><h3>Knowledge Consolidation</h3><p>Agent findings auto-consolidate into team notes and a searchable knowledge base. The team learns as it works.</p></div>
118
+ <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>
119
+ <div class="feature"><h3>Scheduled Tasks</h3><p>Cron-style recurring work: nightly tests, weekly audits, daily standups. Visual cron builder in the dashboard.</p></div>
120
+ <div class="feature"><h3>Command Center</h3><p>Natural language interface for delegating work to agents. CC orchestrates &mdash; agents implement.</p></div>
121
+ <div class="feature"><h3>Live Dashboard</h3><p>Real-time mission control on port 7331. Paginated views, optimistic updates, and visibility-aware polling.</p></div>
122
+ <div class="feature"><h3>One-Command Updates</h3><p><code>minions update</code> pulls latest from npm and applies. Config and charters preserved automatically.</p></div>
124
123
  </div>
125
124
 
126
125
  <!-- Demo scenarios -->
127
126
  <div class="scenario">
128
127
  <div class="scenario-header"><div class="scenario-num">1</div><h2>Dashboard Overview</h2></div>
129
- <p>Home page with agent status cards, project bar, setup guidance, and engine state. All agents visible at a glance.</p>
128
+ <p>Home page with agent status cards, project bar, and setup guidance. All agents visible at a glance.</p>
130
129
  <div class="demo-frame">
131
130
  <img src="demo/01-dashboard-overview.png" alt="Dashboard overview with agent cards">
132
131
  <div class="demo-caption">Home page showing Minions Members, project bar, and engine status badge</div>
@@ -135,7 +134,7 @@
135
134
 
136
135
  <div class="scenario">
137
136
  <div class="scenario-header"><div class="scenario-num">2</div><h2>Work Items</h2></div>
138
- <p>Paginated table with status, type, priority, agent, dependencies, artifacts, and linked PRs. <span class="badge badge-yellow">PENDING</span> <span class="badge badge-blue">DISPATCHED</span> <span class="badge badge-green">DONE</span> <span class="badge badge-red">FAILED</span>. Retry, delete, archive, and add feedback with optimistic updates.</p>
137
+ <p>Paginated table with status, type, priority, agent, and linked PRs. <span class="badge badge-yellow">PENDING</span> <span class="badge badge-blue">DISPATCHED</span> <span class="badge badge-green">DONE</span> <span class="badge badge-red">FAILED</span>. Retry, delete, and archive with optimistic updates.</p>
139
138
  <div class="demo-frame">
140
139
  <img src="demo/02-work-items.png" alt="Work items table">
141
140
  <div class="demo-caption">Work items page &mdash; 20 per page with create, edit, retry, and delete actions</div>
@@ -144,7 +143,7 @@
144
143
 
145
144
  <div class="scenario">
146
145
  <div class="scenario-header"><div class="scenario-num">3</div><h2>Plans &amp; PRD</h2></div>
147
- <p>Plan cards with Approve / Discuss &amp; Revise / Reject. PRD dependency graph with per-item retry, reopening, verification, and manual archive.</p>
146
+ <p>Plan cards with Approve / Discuss &amp; Revise / Reject. PRD dependency graph with per-item retry. Archive completed plans.</p>
148
147
  <div class="demo-frame">
149
148
  <img src="demo/03-plans-prd.png" alt="Plans and PRD progress">
150
149
  <div class="demo-caption">Plans page with status-colored cards, PRD dependency graph, and action buttons</div>
@@ -153,7 +152,7 @@
153
152
 
154
153
  <div class="scenario">
155
154
  <div class="scenario-header"><div class="scenario-num">4</div><h2>Pull Requests</h2></div>
156
- <p>PR tracker sorted by date, with review, build, merge, conflict, and human-comment status. Linked to work items and PRD items. Manual PR linking and context-only observation supported.</p>
155
+ <p>PR tracker sorted by date, with review, build, and merge status. Linked to work items and PRD items. Manual PR linking supported.</p>
157
156
  <div class="demo-frame">
158
157
  <img src="demo/04-pull-requests.png" alt="Pull requests tracker">
159
158
  <div class="demo-caption">PRs sorted newest-first with build status, review status, and agent attribution</div>
@@ -171,7 +170,7 @@
171
170
 
172
171
  <div class="scenario">
173
172
  <div class="scenario-header"><div class="scenario-num">6</div><h2>Pipelines</h2></div>
174
- <p>Multi-stage workflows chaining tasks, meetings, plans, tests, docs, and more. Cron triggers or manual runs. Artifact tracking between stages.</p>
173
+ <p>Multi-stage workflows chaining tasks, meetings, plans, and more. Cron triggers or manual. Artifact tracking between stages.</p>
175
174
  <div class="demo-frame">
176
175
  <img src="demo/06-pipelines.png" alt="Pipelines page">
177
176
  <div class="demo-caption">Pipeline cards with stage flow visualization, run history, and progress bars</div>
@@ -180,7 +179,7 @@
180
179
 
181
180
  <div class="scenario">
182
181
  <div class="scenario-header"><div class="scenario-num">7</div><h2>Notes &amp; Knowledge Base</h2></div>
183
- <p>Inbox for agent findings, quick notes, pinned notes, consolidated team notes, and categorized knowledge base. Inline Q&amp;A/editing on documents.</p>
182
+ <p>Inbox for agent findings, consolidated team notes, and categorized knowledge base. Inline Q&amp;A on any document.</p>
184
183
  <div class="demo-frame">
185
184
  <img src="demo/07-notes-kb.png" alt="Notes and knowledge base">
186
185
  <div class="demo-caption">Notes inbox, team notes, and knowledge base with category tabs and pagination</div>
@@ -189,7 +188,7 @@
189
188
 
190
189
  <div class="scenario">
191
190
  <div class="scenario-header"><div class="scenario-num">8</div><h2>Scheduled Tasks</h2></div>
192
- <p>Cron-style recurring work with a visual builder. Schedule work items, tests, docs, plans, asks, meetings, and recurring maintenance.</p>
191
+ <p>Cron-style recurring work with visual builder. Natural language parsing &mdash; type "every weekday at 9am" and it generates the cron.</p>
193
192
  <div class="demo-frame">
194
193
  <img src="demo/08-schedules.png" alt="Schedules page">
195
194
  <div class="demo-caption">Schedule list with cron expressions, last-run times, and enable/disable toggles</div>
@@ -198,7 +197,7 @@
198
197
 
199
198
  <div class="scenario">
200
199
  <div class="scenario-header"><div class="scenario-num">9</div><h2>Engine &amp; Metrics</h2></div>
201
- <p>Dispatch queue, engine log, agent metrics, token usage, runtime/model data, quality signals, and context pressure. All paginated.</p>
200
+ <p>Dispatch queue, engine log, agent metrics, token usage, and context pressure. All paginated.</p>
202
201
  <div class="demo-frame">
203
202
  <img src="demo/09-engine.png" alt="Engine page">
204
203
  <div class="demo-caption">Active/pending dispatches, completed history, engine log, and per-agent quality metrics</div>
@@ -207,7 +206,7 @@
207
206
 
208
207
  <div class="scenario">
209
208
  <div class="scenario-header"><div class="scenario-num">10</div><h2>Command Center</h2></div>
210
- <p>Natural language delegation. CC orchestrates &mdash; agents implement. Sessions persist across refreshes and tabs; actions can create work, notes, plans, watches, PR links, and issues.</p>
209
+ <p>Natural language delegation. CC orchestrates &mdash; agents implement. Session persists across refreshes. Actions auto-execute.</p>
211
210
  <div class="demo-frame">
212
211
  <img src="demo/10-command-center.png" alt="Command Center panel">
213
212
  <div class="demo-caption">Command Center side panel with conversation history, action execution, and session indicator</div>
@@ -217,27 +216,17 @@
217
216
  <!-- Quick Start -->
218
217
  <div class="quickstart" id="quickstart">
219
218
  <h2>Quick Start</h2>
220
- <pre><span class="comment"># Prerequisites: Node.js 18+, Git, and at least one agent runtime</span>
221
- <span class="comment"># Install Claude Code or GitHub Copilot CLI separately, then install Minions</span>
219
+ <pre><span class="comment"># Install</span>
222
220
  npm install -g @yemi33/minions
223
221
 
224
- <span class="comment"># Bootstrap ~/.minions/ and scan/link repositories</span>
222
+ <span class="comment"># Initialize &mdash; prompts for project locations, starts engine + dashboard</span>
225
223
  minions init
226
224
 
227
- <span class="comment"># Or add a specific project later</span>
228
- minions add ~/my-project
229
-
230
- <span class="comment"># Start engine + dashboard, then open http://localhost:7331</span>
231
- minions restart --open
232
- minions dash
233
-
234
225
  <span class="comment"># Give your first task</span>
235
226
  minions work "Explore the codebase and document the architecture"
236
227
 
237
- <span class="comment"># Useful operations</span>
238
- minions status
239
- minions doctor
240
- minions config set-cli copilot --model gpt-5.4
228
+ <span class="comment"># Open dashboard at http://localhost:7331</span>
229
+ minions dash
241
230
 
242
231
  <span class="comment"># Update to latest</span>
243
232
  minions update</pre>
@@ -252,7 +241,7 @@ minions update</pre>
252
241
  │ │
253
242
  │ engine.js ──── 60s tick loop ────┐ │
254
243
  │ │ │ │
255
- │ discover work spawn agents poll PRs/comments │
244
+ │ discover work spawn agents poll PRs │
256
245
  │ │ │ │ │
257
246
  │ ┌───┴───┐ ┌──────┴──────┐ ┌──┴───┐ │
258
247
  │ │ Plans │ │ Worktrees │ │ ADO │ │
@@ -261,11 +250,10 @@ minions update</pre>
261
250
  │ └───────┘ └─────────────┘ └──────┘ │
262
251
  │ │
263
252
  │ dashboard.js ── port 7331 ── mission control │
264
- │ runtimes/ ── Claude Code or GitHub Copilot CLI │
265
253
  │ meetings/ ── multi-agent discussions │
266
254
  │ pipelines/ ── multi-stage workflows │
267
- │ schedules + watches ── recurring/conditional work │
268
- │ notes.md + knowledge/ ── team memory and KB │
255
+ │ notes.md ── consolidated team knowledge │
256
+ │ knowledge/ ── searchable KB by category │
269
257
  └─────────────────────────────────────────────────────┘
270
258
  </pre>
271
259
  </div>
@@ -273,7 +261,7 @@ minions update</pre>
273
261
  </div>
274
262
 
275
263
  <footer>
276
- <p>Minions &mdash; <a href="https://www.npmjs.com/package/@yemi33/minions">npm</a> &mdash; <a href="https://yemi33.github.io/minions/">Public site</a> &mdash; MIT License &mdash; Claude Code or GitHub Copilot CLI runtime</p>
264
+ <p>Minions &mdash; built by <a href="https://github.com/yemi33">yemi33</a> &mdash; <a href="https://github.com/yemi33/minions">GitHub</a> &mdash; <a href="https://www.npmjs.com/package/@yemi33/minions">npm</a> &mdash; MIT License</p>
277
265
  </footer>
278
266
 
279
267
  </body>
package/engine/lifecycle.js CHANGED
@@ -1624,8 +1624,22 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
1624
1624
  if (!postReviewStatus) {
1625
1625
  const verdict = reviewVerdictFromCompletion(structuredCompletion) || parseReviewVerdict(resultSummary);
1626
1626
  if (verdict) {
1627
- postReviewStatus = verdict;
1628
- log('info', `Read review verdict from agent completion for ${reviewPr.id}: ${verdict}`);
1627
+ // P-e1c8a9d2 — Refuse self-review APPROVE: an agent approving their own PR
1628
+ // is meaningless self-promotion (PR #1867/#1868/#2253 all shipped this way).
1629
+ // Treat it like a bailout — don't apply the verdict (so reviewStatus stays
1630
+ // 'waiting' and the engine routes the next review to a different agent on
1631
+ // the next dispatch tick). The verdict-gate at runPostCompletionHooks sees
1632
+ // the verdict and skips the no-verdict retry path, so _retryCount stays
1633
+ // unchanged. REQUEST_CHANGES from a self-author is still accepted — a
1634
+ // self-author flagging issues on their own PR is harmless and useful.
1635
+ const reviewerLower = String(agentId || '').toLowerCase();
1636
+ const authorLower = String(reviewPr.agent || '').toLowerCase();
1637
+ if (verdict === 'approved' && reviewerLower && authorLower && reviewerLower === authorLower) {
1638
+ log('warn', `review verdict rejected: self-review (reviewer=${reviewerName}, author=${reviewPr.agent})`);
1639
+ } else {
1640
+ postReviewStatus = verdict;
1641
+ log('info', `Read review verdict from agent completion for ${reviewPr.id}: ${verdict}`);
1642
+ }
1629
1643
  }
1630
1644
  }
1631
1645
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yemi33/minions",
3
- "version": "0.1.1885",
3
+ "version": "0.1.1887",
4
4
  "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
5
5
  "bin": {
6
6
  "minions": "bin/minions.js"
package/playbooks/explore.md CHANGED
@@ -37,7 +37,7 @@ After the requested exploration succeeds, write your findings to `{{team_root}}/
37
37
  - **Patterns**: conventions and patterns found
38
38
  - **Dependencies**: what depends on what
39
39
  - **Gaps**: anything missing, broken, or unclear
40
- - **Recommendations**: suggestions for the team
40
+ - **Recommended next dispatches**: one bullet per follow-up using the format `<work-type> <agent> — <one-line scope>` (e.g., `implement ralph — wire X helper into Y caller`, `fix lambert — guard Z against null project`). If you have nothing concrete to recommend, the section must read exactly `Recommended next dispatches: none — no follow-up needed`.
41
41
  - **Source References**: for EVERY finding, include the source — file paths, line numbers, PR URLs, API endpoints, config keys. Format: `(source: path/to/file.ts:42)` or `(source: PR-12345)`. This is critical — other agents and humans need to verify your findings.
42
42
 
43
43
  If exploration is blocked or fails before you can produce sourced findings, do **not** write an inbox note. Report the blocker in your final response instead.
package/playbooks/meeting-conclude.md CHANGED
@@ -31,11 +31,21 @@ Write a clear, **self-contained** meeting conclusion. Someone reading ONLY this
31
31
  - What the fix should be (concrete: "change X to Y", "add guard in Z")
32
32
  - Estimated complexity (small/medium/large)
33
33
 
34
- 2. **Deferred items** — what was discussed but explicitly deprioritized, and why
34
+ 2. **Overrules** — required section. Document every priority where you (the synthesizer) chose differently than a participant argued in debate. Each bullet must take this exact form:
35
35
 
36
- 3. **Unresolved disagreements** — where positions still differ (if any)
36
+ - `Overruled <participant>'s claim that <X>; chose <Y> because <reason cited from debate or source file>`
37
37
 
38
- 4. **Open questions for human** — what needs human input before proceeding (if any)
38
+ The cited reason must be a concrete pointer (debate quote, finding ID, or `path/to/file.ext:line`), not a paraphrase. If the synthesizer truly overruled nothing — every priority above converged in debate — the section must read exactly:
39
+
40
+ - `Overrules: none — every priority converged in debate`
41
+
42
+ Do NOT omit this section. An empty `Overrules:` (without the escape-hatch sentence) is not acceptable.
43
+
44
+ 3. **Deferred items** — what was discussed but explicitly deprioritized, and why
45
+
46
+ 4. **Unresolved disagreements** — where positions still differ (if any)
47
+
48
+ 5. **Open questions for human** — what needs human input before proceeding (if any)
39
49
 
40
50
  **Be concrete, not vague.** Do NOT write "fix 3 bugs" — write which 3 bugs, in which files, with what fix. The conclusion is used as input to create an implementation plan, so it must contain enough detail to act on without re-reading the entire meeting.
41
51
 
package/playbooks/meeting-investigate.md CHANGED
@@ -25,6 +25,10 @@ Investigate this topic from your unique perspective as {{agent_role}}.
25
25
 
26
26
  Focus on what YOU uniquely bring to this discussion. Be thorough but concise.
27
27
 
28
+ ### Evidence rule for code claims
29
+
30
+ Every claim about repository code — a bug, a regression, a missing guard, a test gap, a behavior assertion — must include a concrete citation: a `path/to/file.ext:line` reference (or range like `path:120-145`) for current code, or a `git show <sha>:<path>` hunk reference when the claim is about a specific commit or historical state. Claims you cannot back with such a reference must be tagged `[unverified]` inline (e.g., "the dispatch loop ignores `paused` items `[unverified]`") so debaters in the next round can call them out and either verify or discard them. Do not paraphrase code from memory and present it as fact; if you have not opened the file in this session, it is `[unverified]`.
31
+
28
32
  ## Output Format
29
33
 
30
34
  Write your findings as a clear markdown document. Start with your key conclusion, then supporting evidence.
package/playbooks/plan.md CHANGED
@@ -42,6 +42,7 @@ A user has described a feature they want built. Your job is to create a detailed
42
42
  - Order by dependency (foundations first)
43
43
  - Estimate complexity: `small` (1 file), `medium` (2-5 files), `large` (6+ files)
44
44
  - Each item should be independently testable
45
+ - Also list ideas you considered and chose **not** to include — these go in the required `## Rejected items` section so scope is declared explicitly
45
46
 
46
47
  ### 5. Write the Plan
47
48
 
@@ -65,19 +66,24 @@ What exists today, what needs to change, key files involved.
65
66
  ## Approach
66
67
  High-level design decisions and rationale.
67
68
 
68
- ## Work Breakdown
69
+ ## Work items
69
70
 
70
- ### Phase 1: Foundation
71
- 1. **Item name** (complexity: small/medium/large)
72
- - What to build
73
- - Files to create/modify
74
- - Acceptance criteria
71
+ Flat numbered list, ordered by dependency in prose (not by phase). Use phases only when items genuinely block each other across PR boundaries; otherwise the plan is a flat numbered list.
75
72
 
76
- ### Phase 2: Core Implementation
77
- 2. **Item name** ...
73
+ ### 1. <item name> (complexity: small/medium/large)
74
+ - What to build
75
+ - Files to create/modify
76
+ - Acceptance criteria
78
77
 
79
- ### Phase 3: Polish & Integration
80
- 3. **Item name** ...
78
+ ### 2. <item name> (complexity: small/medium/large)
79
+ - ...
80
+
81
+ ## Rejected items
82
+
83
+ Required section. Declare scope by listing ideas you considered and chose not to include, one line per rejected item with the reason.
84
+
85
+ - <rejected idea> — <one-line reason>
86
+ - <rejected idea> — <one-line reason>
81
87
 
82
88
  ## Risks & Open Questions
83
89
  - Risk or question that needs user input
package/playbooks/review.md CHANGED
@@ -54,7 +54,6 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
54
54
 
55
55
  8. If the code is genuinely ready:
56
56
  - Verdict: **APPROVE**
57
- - Note any minor non-blocking suggestions
58
57
  - Do not request changes for nits, speculative edge cases, or unrelated improvements
59
58
 
60
59
  ## Post Review — Submit your verdict
@@ -79,10 +78,14 @@ Automated checks:
79
78
  - `<command>`: pass/fail/skipped — short result or reason
80
79
 
81
80
  Blocking issues:
82
- - None, or `path:line` — issue and required fix
81
+ - `path:line — failure mode — required fix`
82
+ - (one bullet per blocking finding; the literal string `None` is the only allowed empty form)
83
83
 
84
- Non-blocking suggestions:
85
- - None, or `path:line` — suggestion
84
+ Minimum diff to ship: <one-line description of the smallest change that would flip this verdict to APPROVE>
85
+ (REQUEST_CHANGES only — omit this line on APPROVE verdicts)
86
+
87
+ Non-blocking observations: None
88
+ - (default to `None`; if you list any, each must be tied to an existing diff line in the form `path:line — observation`)
86
89
  ```
87
90
 
88
91
  After running the command, confirm it succeeded (check the command output for errors). If it fails, retry once.