@yemi33/minions 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.1.9 (2026-03-26)
+
+### Engine
+- engine.js
+- engine/ado.js
+- engine/cli.js
+- engine/github.js
+- engine/lifecycle.js
+- engine/scheduler.js
+- engine/shared.js
+
+### Dashboard
+- dashboard.html
+- dashboard.js
+
+### Playbooks
+- decompose.md
+
+### Documentation
+- README.md
+
+### Other
+- CLAUDE.md
+- TODO.md
+- routing.md
+- test/playwright/dashboard.spec.js
+
 ## 0.1.8 (2026-03-25)
 
 ### Engine

package/README.md

@@ -497,6 +497,60 @@ Engine behavior is controlled via `config.json`. Key settings:
 | `worktreeRoot` | `../worktrees` | Where git worktrees are created |
 | `idleAlertMinutes` | 15 | Alert after no dispatch for this many minutes |
 | `restartGracePeriod` | 1200000 (20min) | Grace period for agent re-attachment after engine restart |
+| `shutdownTimeout` | 300000 (5min) | Max wait for active agents during graceful shutdown (SIGTERM/SIGINT) |
+| `allowTempAgents` | false | Spawn ephemeral agents when all permanent agents are busy |
+| `autoDecompose` | true | Auto-decompose `implement:large` items into sub-tasks before dispatch |
+
+### Scheduled Tasks
+
+Add recurring work via `config.schedules`:
+
+```json
+{
+  "schedules": [
+    {
+      "id": "nightly-tests",
+      "cron": "0 2 *",
+      "type": "test",
+      "title": "Nightly test suite",
+      "project": "MyProject",
+      "agent": "dallas",
+      "enabled": true
+    }
+  ]
+}
+```
+
+Cron format is simplified 3-field: `minute hour dayOfWeek` (0=Sun..6=Sat). Supports `*`, `*/N`, and specific values. Examples:
+- `0 2 *` — 2am daily
+- `0 9 1` — 9am every Monday
+- `*/30 * *` — every 30 minutes
+- `0 9 1,3,5` — 9am Mon/Wed/Fri
+
+### Graceful Shutdown
+
+The engine handles `SIGTERM` and `SIGINT` (Ctrl+C) gracefully:
+1. Stops accepting new work (enters `stopping` state)
+2. Waits for active agents to finish (up to `shutdownTimeout`, default 5 minutes)
+3. Exits cleanly
+
+Active agents continue running as independent processes and will be re-attached on next engine start.
+
+### Task Decomposition
+
+Work items with `complexity: "large"` or `estimated_complexity: "large"` are auto-decomposed before dispatch (controlled by `engine.autoDecompose`, default `true`). The engine dispatches a `decompose` agent that breaks the item into 2-5 smaller sub-tasks, each becoming an independent work item with dependency tracking.
+
+### Temporary Agents
+
+Set `engine.allowTempAgents: true` to let the engine spawn ephemeral agents when all 5 permanent agents are busy. Temp agents:
+- Get a `temp-{id}` identifier
+- Use a minimal system prompt (no charter)
+- Are auto-cleaned up after task completion
+- Count toward `maxConcurrent` slots
+
+### Live Output Streaming
+
+The dashboard streams agent output in real-time via Server-Sent Events (SSE) instead of polling. The `GET /api/agent/:id/live-stream` endpoint pushes output chunks as they're written. Falls back to 3-second polling if SSE is unavailable.
 
 ## Node.js Upgrade Caution
 
@@ -535,6 +589,8 @@ To move to a new machine: `npm install -g @yemi33/minions && minions init --forc
     ado.js               <- ADO token management, PR polling, PR reconciliation
     llm.js               <- callLLM() with session resume, trackEngineUsage()
     spawn-agent.js       <- Agent spawn wrapper (resolves claude cli.js)
+    preflight.js         <- Prerequisite checks (Node, Git, Claude CLI, API key)
+    scheduler.js         <- Cron-style scheduled task discovery
     ado-mcp-wrapper.js   <- ADO MCP authentication wrapper
     check-status.js      <- Quick status check without full engine load
     control.json         <- running/paused/stopped (runtime, generated)
@@ -542,6 +598,7 @@ To move to a new machine: `npm install -g @yemi33/minions && minions init --forc
     log.json             <- Audit trail, capped at 500 (runtime, generated)
     metrics.json         <- Per-agent quality metrics (runtime, generated)
     cooldowns.json       <- Dispatch cooldown tracking (runtime, generated)
+    schedule-runs.json   <- Last-run timestamps for scheduled tasks (runtime, generated)
   dashboard.js           <- Web dashboard server
   dashboard.html         <- Dashboard UI (single-file)
   config.json            <- projects[], agents, engine, claude settings (generated by minions init)
@@ -566,6 +623,7 @@ To move to a new machine: `npm install -g @yemi33/minions && minions init --forc
     implement-shared.md  <- Implement on a shared branch
     ask.md               <- Answer a question about the codebase
     verify.md            <- Plan verification: build, test, start webapp, testing guide
+    decompose.md         <- Break large work items into 2-5 sub-tasks
   skills/                <- Agent-created reusable workflows (generated)
   agents/
     {name}/

package/dashboard.html

@@ -917,7 +917,7 @@ function closeDetail() {
   document.getElementById('detail-overlay').classList.remove('open');
   document.getElementById('detail-panel').classList.remove('open');
   currentAgentId = null;
-  stopLivePolling();
+  stopLiveStream();
 }
 
 function renderDetailTabs(detail) {
@@ -978,10 +978,10 @@ function renderDetailContent(detail, tab) {
   } else if (tab === 'live') {
     el.innerHTML = '<div class="section" id="live-output" style="max-height:60vh;overflow-y:auto;font-size:11px;line-height:1.6">Loading live output...</div>' +
       '<div style="margin-top:8px;display:flex;gap:8px;align-items:center">' +
-        '<span class="pulse"></span><span style="font-size:11px;color:var(--green)">Auto-refreshing every 3s</span>' +
+        '<span class="pulse"></span><span id="live-status-label" style="font-size:11px;color:var(--green)">Streaming live</span>' +
         '<button class="pr-pager-btn" onclick="refreshLiveOutput()" style="font-size:10px">Refresh now</button>' +
       '</div>';
-    startLivePolling();
+    startLiveStream(currentAgentId);
   } else if (tab === 'charter') {
     el.innerHTML = '<div class="section">' + escHtml(detail.charter || 'No charter found.') + '</div>';
   } else if (tab === 'history') {
@@ -1011,6 +1011,49 @@ function renderDetailContent(detail, tab) {
 }
 
 let livePollingInterval = null;
+let liveEventSource = null;
+
+function startLiveStream(agentId) {
+  stopLiveStream();
+  if (!agentId) return;
+
+  const outputEl = document.getElementById('live-output');
+  if (outputEl) outputEl.textContent = '';
+
+  liveEventSource = new EventSource('/api/agent/' + agentId + '/live-stream');
+
+  liveEventSource.onmessage = function(e) {
+    try {
+      const chunk = JSON.parse(e.data);
+      const el = document.getElementById('live-output');
+      if (el) {
+        const wasAtBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 100;
+        el.textContent += chunk;
+        if (wasAtBottom) el.scrollTop = el.scrollHeight;
+      }
+    } catch {}
+  };
+
+  liveEventSource.addEventListener('done', function() {
+    stopLiveStream();
+  });
+
+  liveEventSource.onerror = function() {
+    // Fall back to polling on SSE error
+    stopLiveStream();
+    startLivePolling();
+    const label = document.getElementById('live-status-label');
+    if (label) label.textContent = 'Auto-refreshing every 3s';
+  };
+}
+
+function stopLiveStream() {
+  if (liveEventSource) {
+    liveEventSource.close();
+    liveEventSource = null;
+  }
+  stopLivePolling();
+}
 
 function startLivePolling() {
   stopLivePolling();
@@ -2209,6 +2252,7 @@ function renderDispatch(dispatch) {
           '<span class="dispatch-type ' + (d.type || '') + '">' + escHtml(d.type || '') + '</span>' +
           '<span class="dispatch-agent">' + escHtml(d.agentName || d.agent || '') + '</span>' +
           '<span class="dispatch-task" title="' + escHtml(d.task || '') + '">' + escHtml(d.task || '') + '</span>' +
+          (d.skipReason ? '<span style="font-size:9px;color:var(--muted);margin-left:6px" title="' + escHtml(d.skipReason) + '">' + escHtml(d.skipReason.replace(/_/g, ' ')) + '</span>' : '') +
         '</div>'
       ).join('') + '</div>';
   } else {
@@ -2516,6 +2560,7 @@ function wiRow(item) {
     '<td>' + typeBadge(item.type) + '</td>' +
     '<td>' + priBadge(item.priority) + '</td>' +
     '<td>' + statusBadge(item.status || 'pending') +
+      (item._pendingReason ? ' <span style="font-size:9px;color:var(--muted);margin-left:4px" title="Pending reason: ' + escHtml(item._pendingReason) + '">' + escHtml(item._pendingReason.replace(/_/g, ' ')) + '</span>' : '') +
       (item.status === 'failed' ? ' <button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--yellow);border-color:var(--yellow);margin-left:4px" onclick="event.stopPropagation();retryWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')">Retry</button>' : '') +
     '</td>' +
     '<td>' +
@@ -2527,6 +2572,7 @@ function wiRow(item) {
     '<td>' + prLink + '</td>' +
     '<td><span class="pr-date">' + shortTime(item.created) + '</span></td>' +
     '<td style="white-space:nowrap">' +
+      ((item.status === 'pending' || item.status === 'failed') ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--blue);border-color:var(--blue);margin-right:4px" onclick="event.stopPropagation();editWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Edit work item">&#x270E;</button>' : '') +
       ((item.status === 'done' || item.status === 'failed') ? '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--muted);border-color:var(--border);margin-right:4px" onclick="event.stopPropagation();archiveWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Archive work item">&#x1F4E6;</button>' : '') +
       '<button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--red);border-color:var(--red)" onclick="event.stopPropagation();deleteWorkItem(\'' + escHtml(item.id) + '\',\'' + escHtml(item._source || '') + '\')" title="Delete work item and kill agent">&#x2715;</button>' +
     '</td>' +
@@ -2588,6 +2634,63 @@ async function retryWorkItem(id, source) {
   } catch (e) { alert('Retry error: ' + e.message); }
 }
 
+function editWorkItem(id, source) {
+  const item = allWorkItems.find(i => i.id === id);
+  if (!item) return;
+  const types = ['implement', 'fix', 'review', 'plan', 'verify', 'investigate', 'refactor', 'test', 'docs'];
+  const priorities = ['critical', 'high', 'medium', 'low'];
+  const agentOpts = cmdAgents.map(a => '<option value="' + escHtml(a.id) + '"' + (item.agent === a.id ? ' selected' : '') + '>' + escHtml(a.name) + '</option>').join('');
+  const typeOpts = types.map(t => '<option value="' + t + '"' + ((item.type || 'implement') === t ? ' selected' : '') + '>' + t + '</option>').join('');
+  const priOpts = priorities.map(p => '<option value="' + p + '"' + ((item.priority || 'medium') === p ? ' selected' : '') + '>' + p + '</option>').join('');
+
+  document.getElementById('modal-title').textContent = 'Edit Work Item ' + id;
+  document.getElementById('modal-body').style.whiteSpace = 'normal';
+  document.getElementById('modal-body').innerHTML =
+    '<div style="display:flex;flex-direction:column;gap:12px;font-family:inherit">' +
+      '<label style="color:var(--text);font-size:var(--text-md)">Title' +
+        '<input id="wi-edit-title" value="' + escHtml(item.title || '') + '" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md);font-family:inherit">' +
+      '</label>' +
+      '<label style="color:var(--text);font-size:var(--text-md)">Description' +
+        '<textarea id="wi-edit-desc" rows="3" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md);font-family:inherit;resize:vertical">' + escHtml(item.description || '') + '</textarea>' +
+      '</label>' +
+      '<div style="display:flex;gap:12px">' +
+        '<label style="color:var(--text);font-size:var(--text-md);flex:1">Type' +
+          '<select id="wi-edit-type" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md)">' + typeOpts + '</select>' +
+        '</label>' +
+        '<label style="color:var(--text);font-size:var(--text-md);flex:1">Priority' +
+          '<select id="wi-edit-priority" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md)">' + priOpts + '</select>' +
+        '</label>' +
+        '<label style="color:var(--text);font-size:var(--text-md);flex:1">Agent' +
+          '<select id="wi-edit-agent" style="display:block;width:100%;margin-top:4px;padding:6px 8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text);font-size:var(--text-md)"><option value="">Auto</option>' + agentOpts + '</select>' +
+        '</label>' +
+      '</div>' +
+      '<div style="display:flex;justify-content:flex-end;gap:8px;margin-top:8px">' +
+        '<button onclick="closeModal()" class="pr-pager-btn" style="padding:6px 16px;font-size:var(--text-md)">Cancel</button>' +
+        '<button onclick="submitWorkItemEdit(\'' + escHtml(id) + '\',\'' + escHtml(source || '') + '\')" style="padding:6px 16px;font-size:var(--text-md);background:var(--blue);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer">Save</button>' +
+      '</div>' +
+    '</div>';
+  document.getElementById('modal').classList.add('open');
+}
+
+async function submitWorkItemEdit(id, source) {
+  const title = document.getElementById('wi-edit-title').value.trim();
+  const description = document.getElementById('wi-edit-desc').value;
+  const type = document.getElementById('wi-edit-type').value;
+  const priority = document.getElementById('wi-edit-priority').value;
+  const agent = document.getElementById('wi-edit-agent').value;
+  if (!title) { alert('Title is required'); return; }
+  try {
+    const res = await fetch('/api/work-items/update', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id, source: source || undefined, title, description, type, priority, agent })
+    });
+    if (res.ok) { closeModal(); refresh(); showToast('cmd-toast', 'Work item updated', true); } else {
+      const d = await res.json();
+      alert('Update failed: ' + (d.error || 'unknown'));
+    }
+  } catch (e) { alert('Update error: ' + e.message); }
+}
+
 async function deleteWorkItem(id, source) {
   if (!confirm('Delete work item ' + id + '? This will kill any running agent and remove all dispatch history.')) return;
   try {

package/dashboard.js

@@ -852,6 +852,44 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
+  // POST /api/work-items/update — edit a pending/failed work item
+  if (req.method === 'POST' && req.url === '/api/work-items/update') {
+    try {
+      const body = await readBody(req);
+      const { id, source, title, description, type, priority, agent } = body;
+      if (!id) return jsonReply(res, 400, { error: 'id required' });
+
+      let wiPath;
+      if (!source || source === 'central') {
+        wiPath = path.join(MINIONS_DIR, 'work-items.json');
+      } else {
+        const proj = PROJECTS.find(p => p.name === source);
+        if (proj) {
+          wiPath = shared.projectWorkItemsPath(proj);
+        }
+      }
+      if (!wiPath) return jsonReply(res, 404, { error: 'source not found' });
+
+      const items = JSON.parse(safeRead(wiPath) || '[]');
+      const item = items.find(i => i.id === id);
+      if (!item) return jsonReply(res, 404, { error: 'item not found' });
+
+      if (item.status === 'dispatched') {
+        return jsonReply(res, 400, { error: 'Cannot edit dispatched items' });
+      }
+
+      if (title !== undefined) item.title = title;
+      if (description !== undefined) item.description = description;
+      if (type !== undefined) item.type = type;
+      if (priority !== undefined) item.priority = priority;
+      if (agent !== undefined) item.agent = agent || null;
+      item.updatedAt = new Date().toISOString();
+
+      safeWrite(wiPath, items);
+      return jsonReply(res, 200, { ok: true, item });
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
   // POST /api/notes — write to inbox so it flows through normal consolidation
   if (req.method === 'POST' && req.url === '/api/notes') {
     try {
@@ -1076,6 +1114,69 @@ const server = http.createServer(async (req, res) => {
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
+  // GET /api/agent/:id/live-stream — SSE real-time live output streaming
+  const liveStreamMatch = req.url.match(/^\/api\/agent\/([\w-]+)\/live-stream(?:\?.*)?$/);
+  if (liveStreamMatch && req.method === 'GET') {
+    const agentId = liveStreamMatch[1];
+    const liveLogPath = path.join(MINIONS_DIR, 'agents', agentId, 'live-output.log');
+
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+
+    // Send initial content
+    let offset = 0;
+    try {
+      const content = fs.readFileSync(liveLogPath, 'utf8');
+      if (content.length > 0) {
+        res.write(`data: ${JSON.stringify(content)}\n\n`);
+        offset = Buffer.byteLength(content, 'utf8');
+      }
+    } catch {}
+
+    // Watch for changes using fs.watchFile (cross-platform, works on Windows)
+    const watcher = () => {
+      try {
+        const stat = fs.statSync(liveLogPath);
+        if (stat.size > offset) {
+          const fd = fs.openSync(liveLogPath, 'r');
+          const buf = Buffer.alloc(stat.size - offset);
+          fs.readSync(fd, buf, 0, buf.length, offset);
+          fs.closeSync(fd);
+          offset = stat.size;
+          const chunk = buf.toString('utf8');
+          if (chunk) res.write(`data: ${JSON.stringify(chunk)}\n\n`);
+        }
+      } catch {}
+    };
+
+    fs.watchFile(liveLogPath, { interval: 500 }, watcher);
+
+    // Check if agent is still active (poll every 5s)
+    const doneCheck = setInterval(() => {
+      const dispatch = getDispatchQueue();
+      const isActive = (dispatch.active || []).some(d => d.agent === agentId);
+      if (!isActive) {
+        watcher(); // flush final content
+        res.write(`event: done\ndata: complete\n\n`);
+        clearInterval(doneCheck);
+        fs.unwatchFile(liveLogPath, watcher);
+        res.end();
+      }
+    }, 5000);
+
+    // Cleanup on client disconnect
+    req.on('close', () => {
+      clearInterval(doneCheck);
+      fs.unwatchFile(liveLogPath, watcher);
+    });
+
+    return;
+  }
+
   // GET /api/agent/:id/live — tail live output for a working agent
   const liveMatch = req.url.match(/^\/api\/agent\/([\w-]+)\/live(?:\?.*)?$/);
   if (liveMatch && req.method === 'GET') {

package/engine/ado.js

@@ -192,6 +192,7 @@ async function pollPrStatus(config) {
       pr.buildStatus = buildStatus;
       if (buildFailReason) pr.buildFailReason = buildFailReason;
       else delete pr.buildFailReason;
+      if (buildStatus !== 'failing') delete pr._buildFailNotified;
       updated = true;
     }
 

package/engine/cli.js

@@ -305,9 +305,51 @@ const commands = {
     e.tick();
 
     // Start tick loop
-    setInterval(() => e.tick(), interval);
+    const tickTimer = setInterval(() => e.tick(), interval);
     console.log(`Tick interval: ${interval / 1000}s | Max concurrent: ${config.engine?.maxConcurrent || 5}`);
     console.log('Press Ctrl+C to stop');
+
+    // Graceful shutdown — wait for active agents before exiting
+    let shuttingDown = false;
+    function gracefulShutdown(signal) {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      console.log(`\n${signal} received — initiating graceful shutdown...`);
+      clearInterval(tickTimer);
+      safeWrite(CONTROL_PATH, { state: 'stopping', pid: process.pid, stopping_at: e.ts() });
+      e.log('info', `Graceful shutdown initiated (${signal})`);
+
+      if (e.activeProcesses.size === 0) {
+        safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+        e.log('info', 'Graceful shutdown complete (no active agents)');
+        console.log('No active agents — stopped.');
+        process.exit(0);
+      }
+
+      console.log(`Waiting for ${e.activeProcesses.size} active agent(s) to finish...`);
+      const timeout = config.engine?.shutdownTimeout || shared.ENGINE_DEFAULTS.shutdownTimeout;
+      const deadline = Date.now() + timeout;
+
+      const poll = setInterval(() => {
+        if (e.activeProcesses.size === 0) {
+          clearInterval(poll);
+          safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+          e.log('info', 'Graceful shutdown complete (all agents finished)');
+          console.log('All agents finished — stopped.');
+          process.exit(0);
+        }
+        if (Date.now() >= deadline) {
+          clearInterval(poll);
+          safeWrite(CONTROL_PATH, { state: 'stopped', stopped_at: e.ts() });
+          e.log('warn', `Graceful shutdown timed out after ${timeout / 1000}s with ${e.activeProcesses.size} agent(s) still active`);
+          console.log(`Shutdown timeout (${timeout / 1000}s) — force exiting with ${e.activeProcesses.size} agent(s) still running.`);
+          process.exit(1);
+        }
+      }, 2000);
+    }
+
+    process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+    process.on('SIGINT', () => gracefulShutdown('SIGINT'));
   },
 
   stop() {

package/engine/github.js

@@ -159,6 +159,7 @@ async function pollPrStatus(config) {
           pr.buildStatus = buildStatus;
           if (buildFailReason) pr.buildFailReason = buildFailReason;
           else delete pr.buildFailReason;
+          if (buildStatus !== 'failing') delete pr._buildFailNotified;
           updated = true;
         }
       }

package/engine/lifecycle.js

@@ -936,6 +936,82 @@ function parseAgentOutput(stdout) {
   return { resultSummary: parsed.text, taskUsage: parsed.usage };
 }
 
+/**
+ * Handle decomposition result — parse sub-items from agent output and create child work items.
+ * Called from runPostCompletionHooks when type === 'decompose'.
+ */
+function handleDecompositionResult(stdout, meta, config) {
+  const e = engine();
+  const parentId = meta?.item?.id;
+  if (!parentId) return 0;
+
+  // Parse sub-items JSON from agent output
+  const { text } = shared.parseStreamJsonOutput(stdout);
+  const jsonMatch = text.match(/```json\s*\n([\s\S]*?)```/);
+  if (!jsonMatch) {
+    e.log('warn', `Decomposition for ${parentId}: no JSON block found in output`);
+    return 0;
+  }
+
+  let decomposition;
+  try {
+    decomposition = JSON.parse(jsonMatch[1]);
+  } catch (err) {
+    e.log('warn', `Decomposition for ${parentId}: invalid JSON — ${err.message}`);
+    return 0;
+  }
+
+  const subItems = decomposition.sub_items || decomposition.subItems || [];
+  if (subItems.length === 0) {
+    e.log('warn', `Decomposition for ${parentId}: no sub-items produced`);
+    return 0;
+  }
+
+  // Find and update the parent work item
+  const projects = shared.getProjects(config);
+  const allPaths = [path.join(MINIONS_DIR, 'work-items.json')];
+  for (const p of projects) allPaths.push(shared.projectWorkItemsPath(p));
+
+  for (const wiPath of allPaths) {
+    const items = safeJson(wiPath) || [];
+    const parent = items.find(i => i.id === parentId);
+    if (!parent) continue;
+
+    // Mark parent as decomposed
+    parent.status = 'decomposed';
+    parent._decomposed = true;
+    delete parent._decomposing;
+    parent._subItemIds = subItems.map(s => s.id);
+
+    // Create child work items
+    for (const sub of subItems) {
+      if (items.some(i => i.id === sub.id)) continue; // dedupe
+      items.push({
+        id: sub.id,
+        title: sub.name || sub.title || `Sub-task of ${parentId}`,
+        type: (sub.estimated_complexity === 'large') ? 'implement:large' : 'implement',
+        priority: sub.priority || parent.priority || 'medium',
+        description: sub.description || '',
+        status: 'pending',
+        complexity: sub.estimated_complexity || 'medium',
+        depends_on: sub.depends_on || [],
+        parent_id: parentId,
+        sourcePlan: parent.sourcePlan,
+        branchStrategy: parent.branchStrategy,
+        featureBranch: parent.featureBranch,
+        created: new Date().toISOString(),
+        createdBy: 'decomposition',
+      });
+    }
+
+    safeWrite(wiPath, items);
+    e.log('info', `Decomposition: ${parentId} → ${subItems.length} sub-items: ${subItems.map(s => s.id).join(', ')}`);
+    return subItems.length;
+  }
+
+  return 0;
+}
+
 function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
   const e = engine();
   const type = dispatchItem.type;
@@ -944,6 +1020,16 @@ function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config) {
   const result = isSuccess ? 'success' : 'error';
   const { resultSummary, taskUsage } = parseAgentOutput(stdout);
 
+  // Handle decomposition results — create sub-items from decompose agent output
+  if (type === 'decompose' && isSuccess && meta?.item?.id) {
+    const subCount = handleDecompositionResult(stdout, meta, config);
+    if (subCount > 0) {
+      // Parent is marked 'decomposed' by handler — don't overwrite with 'done'
+      return { resultSummary: `Decomposed into ${subCount} sub-items`, taskUsage };
+    }
+    // Fallback: if decomposition produced nothing, mark parent as done to avoid stuck state
+  }
+
   if (isSuccess && meta?.item?.id) updateWorkItemStatus(meta, 'done', '');
   if (!isSuccess && meta?.item?.id) {
     // Auto-retry: read fresh _retryCount from file (not stale dispatch-time snapshot)

package/engine/scheduler.js

@@ -0,0 +1,159 @@
+/**
+ * engine/scheduler.js — Cron-style scheduled task discovery.
+ * Zero dependencies — uses only Node.js built-ins.
+ *
+ * Config schema:
+ *   config.schedules: Array<{
+ *     id: string,          — unique schedule ID
+ *     cron: string,        — simplified cron: "minute hour dayOfWeek" (0=Sun..6=Sat)
+ *     type: string,        — work item type (implement, test, explore, ask, etc.)
+ *     title: string,       — work item title
+ *     description?: string,
+ *     project?: string,    — target project name
+ *     agent?: string,      — preferred agent ID
+ *     enabled?: boolean    — default true
+ *   }>
+ *
+ * Cron field syntax:
+ *   *     — every value
+ *   N     — exact value (e.g., "0" = minute 0, "2" = 2am, "1" = Monday)
+ *   N,M   — multiple values (e.g., "1,3,5" = Mon/Wed/Fri)
+ *   * /N  — every Nth value (e.g., "* /15" = every 15 minutes) [no space — formatting only]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+const { safeJson, safeWrite, mutateJsonFileLocked } = shared;
+
+const SCHEDULE_RUNS_PATH = path.join(__dirname, 'schedule-runs.json');
+
+/**
+ * Parse a single cron field into a matcher function.
+ * @param {string} field — e.g., "*", "5", "1,3,5", "*/15"
+ * @param {number} min — minimum valid value (0 for minute/dow, 0 for hour)
+ * @param {number} max — maximum valid value (59 for minute, 23 for hour, 6 for dow)
+ * @returns {function(number): boolean}
+ */
+function parseCronField(field, min, max) {
+  field = field.trim();
+  if (field === '*') return () => true;
+
+  // Step: */N
+  if (field.startsWith('*/')) {
+    const step = parseInt(field.slice(2), 10);
+    if (isNaN(step) || step <= 0) return () => false;
+    return (val) => val % step === 0;
+  }
+
+  // List: N,M,O
+  if (field.includes(',')) {
+    const values = new Set(field.split(',').map(v => parseInt(v.trim(), 10)).filter(v => !isNaN(v)));
+    return (val) => values.has(val);
+  }
+
+  // Single value: N
+  const exact = parseInt(field, 10);
+  if (!isNaN(exact)) return (val) => val === exact;
+
+  return () => false;
+}
+
+/**
+ * Parse a 3-field cron expression: "minute hour dayOfWeek"
+ * @param {string} expr — e.g., "0 2 *" (2am daily), "0 9 1" (9am Monday), "*/30 * *" (every 30 min)
+ * @returns {{ matches: function(Date): boolean }} or null if invalid
+ */
+function parseCronExpr(expr) {
+  if (!expr || typeof expr !== 'string') return null;
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length < 2 || parts.length > 3) return null;
+
+  const minuteMatcher = parseCronField(parts[0], 0, 59);
+  const hourMatcher = parseCronField(parts[1], 0, 23);
+  const dowMatcher = parts[2] ? parseCronField(parts[2], 0, 6) : () => true;
+
+  return {
+    matches(date) {
+      return minuteMatcher(date.getMinutes()) &&
+             hourMatcher(date.getHours()) &&
+             dowMatcher(date.getDay());
+    }
+  };
+}
+
+/**
+ * Check if a schedule should fire now, given its last run time.
+ * Prevents double-firing within the same minute window.
+ * @param {{ cron: string }} schedule
+ * @param {string|null} lastRunAt — ISO timestamp of last run
+ * @returns {boolean}
+ */
+function shouldRunNow(schedule, lastRunAt) {
+  const cron = parseCronExpr(schedule.cron);
+  if (!cron) return false;
+
+  const now = new Date();
+  if (!cron.matches(now)) return false;
+
+  // Don't fire again if already ran in this minute window
+  if (lastRunAt) {
+    const last = new Date(lastRunAt);
+    if (last.getFullYear() === now.getFullYear() &&
+        last.getMonth() === now.getMonth() &&
+        last.getDate() === now.getDate() &&
+        last.getHours() === now.getHours() &&
+        last.getMinutes() === now.getMinutes()) {
+      return false; // already fired this minute
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Discover work items from configured schedules.
+ * @param {object} config — full config object
+ * @returns {Array<object>} — work items to create
+ */
+function discoverScheduledWork(config) {
+  const schedules = config.schedules;
+  if (!Array.isArray(schedules) || schedules.length === 0) return [];
+
+  const runs = safeJson(SCHEDULE_RUNS_PATH) || {};
+  const work = [];
+
+  for (const sched of schedules) {
+    if (!sched.id || !sched.cron || !sched.title) continue;
+    if (sched.enabled === false) continue;
+
+    const lastRun = runs[sched.id] || null;
+    if (!shouldRunNow(sched, lastRun)) continue;
+
+    work.push({
+      id: `sched-${sched.id}-${Date.now()}`,
+      title: sched.title,
+      type: sched.type || 'implement',
+      priority: sched.priority || 'medium',
+      description: sched.description || sched.title,
+      status: 'pending',
+      created: new Date().toISOString(),
+      createdBy: 'scheduler',
+      agent: sched.agent || null,
+      project: sched.project || null,
+      _scheduleId: sched.id,
+    });
+
+    // Record run time
+    runs[sched.id] = new Date().toISOString();
+  }
+
+  // Persist run times if any schedules fired
+  if (work.length > 0) {
+    safeWrite(SCHEDULE_RUNS_PATH, runs);
+  }
+
+  return work;
+}
+
+module.exports = { parseCronExpr, parseCronField, shouldRunNow, discoverScheduledWork, SCHEDULE_RUNS_PATH };

package/engine/shared.js

@@ -242,6 +242,9 @@ const ENGINE_DEFAULTS = {
   idleAlertMinutes: 15,
   fanOutTimeout: null, // falls back to agentTimeout
   restartGracePeriod: 1200000, // 20min
+  shutdownTimeout: 300000, // 5min — max wait for active agents during graceful shutdown
+  allowTempAgents: false, // opt-in: spawn ephemeral agents when all permanent agents are busy
+  autoDecompose: true, // auto-decompose implement:large items into sub-tasks
 };
 
 const DEFAULT_AGENTS = {

package/engine.js

@@ -207,6 +207,15 @@ function resolveAgent(workType, config, authorAgent = null) {
 
   if (idle[0]) { _claimedAgents.add(idle[0]); return idle[0]; }
 
+  // No idle configured agent — try temp agent if enabled
+  if (config.engine?.allowTempAgents) {
+    const tempId = `temp-${shared.uid()}`;
+    _claimedAgents.add(tempId);
+    tempAgents.set(tempId, { name: `Temp-${tempId.slice(5, 9)}`, role: 'Temporary Agent', createdAt: ts() });
+    log('info', `Spawning temp agent ${tempId} — all permanent agents busy`);
+    return tempId;
+  }
+
   // No idle agent available — return null, item stays pending until next tick
   return null;
 }
@@ -389,7 +398,15 @@ function getPrCreateInstructions(project) {
   const host = getRepoHost(project);
   const repoId = project?.repositoryId || '';
   if (host === 'github') {
-    return `Use \`gh pr create\` or the GitHub MCP tools to create a pull request.`;
+    const org = project?.adoOrg || '';
+    const repo = project?.repoName || '';
+    const mainBranch = project?.mainBranch || 'main';
+    return `Use \`gh pr create\` to create a pull request:\n` +
+      `- \`gh pr create --base ${mainBranch} --head <your-branch> --title "PR title" --body "PR description" --repo ${org}/${repo}\`\n` +
+      `- Always set --base to \`${mainBranch}\` (the main branch)\n` +
+      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
+      `- Use --head to specify your feature branch name\n` +
+      `- Include a meaningful --title and --body describing the changes`;
   }
   // Default: Azure DevOps
   return `Use \`mcp__azure-ado__repo_create_pull_request\`:\n- repositoryId: \`${repoId}\``;
@@ -399,7 +416,13 @@ function getPrCommentInstructions(project) {
   const host = getRepoHost(project);
   const repoId = project?.repositoryId || '';
   if (host === 'github') {
-    return `Use \`gh pr comment\` or the GitHub MCP tools to post a comment on the PR.`;
+    const org = project?.adoOrg || '';
+    const repo = project?.repoName || '';
+    return `Use \`gh pr comment\` to post a comment on the PR:\n` +
+      `- \`gh pr comment <number> --body "Your comment text" --repo ${org}/${repo}\`\n` +
+      `- Replace <number> with the PR number\n` +
+      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
+      `- Use --body to provide the comment text (supports Markdown)`;
   }
   return `Use \`mcp__azure-ado__repo_create_pull_request_thread\`:\n- repositoryId: \`${repoId}\``;
 }
@@ -407,7 +430,17 @@ function getPrCommentInstructions(project) {
 function getPrFetchInstructions(project) {
   const host = getRepoHost(project);
   if (host === 'github') {
-    return `Use \`gh pr view\` or the GitHub MCP tools to fetch PR status.`;
+    const org = project?.adoOrg || '';
+    const repo = project?.repoName || '';
+    const mainBranch = project?.mainBranch || 'main';
+    return `Use \`gh pr view\` to fetch PR status:\n` +
+      `- \`gh pr view <number> --json number,title,state,mergeable,reviewDecision,headRefName,baseRefName,statusCheckRollup --repo ${org}/${repo}\`\n` +
+      `- This returns JSON with PR state, mergeability, review decision, and check statuses\n` +
+      `- To fetch the PR branch locally:\n` +
+      `  1. \`git fetch origin <branch-name>\`\n` +
+      `  2. \`git checkout <branch-name>\`\n` +
+      `- Or use \`gh pr checkout <number> --repo ${org}/${repo}\` to fetch and checkout in one step\n` +
+      `- The base branch is \`${mainBranch}\``;
   }
   return `Use \`mcp__azure-ado__repo_get_pull_request_by_id\` to fetch PR status.`;
 }
@@ -416,7 +449,15 @@ function getPrVoteInstructions(project) {
   const host = getRepoHost(project);
   const repoId = project?.repositoryId || '';
   if (host === 'github') {
-    return `Use \`gh pr review\` to approve or request changes:\n- \`gh pr review <number> --approve\`\n- \`gh pr review <number> --request-changes\``;
+    const org = project?.adoOrg || '';
+    const repo = project?.repoName || '';
+    return `Use \`gh pr review\` to submit a review on the PR:\n` +
+      `- Approve: \`gh pr review <number> --approve --body "Approval comment" --repo ${org}/${repo}\`\n` +
+      `- Request changes: \`gh pr review <number> --request-changes --body "What needs to change" --repo ${org}/${repo}\`\n` +
+      `- Comment only: \`gh pr review <number> --comment --body "Review comment" --repo ${org}/${repo}\`\n` +
+      `- Replace <number> with the PR number\n` +
+      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
+      `- Use --body to provide a review summary (supports Markdown)`;
   }
   return `Use \`mcp__azure-ado__repo_update_pull_request_reviewers\`:\n- repositoryId: \`${repoId}\`\n- Set your reviewer vote on the PR (10=approve, 5=approve-with-suggestions, -10=reject)`;
 }
@@ -437,8 +478,8 @@ function getRepoHostToolRule(project) {
 
 // Lean system prompt: agent identity + rules only (~2-4KB, never grows)
 function buildSystemPrompt(agentId, config, project) {
-  const agent = config.agents[agentId];
-  const charter = getAgentCharter(agentId);
+  const agent = config.agents[agentId] || tempAgents.get(agentId) || { name: agentId, role: 'Temporary Agent', skills: [] };
+  const charter = getAgentCharter(agentId); // returns '' for temp agents (no charter file)
   project = project || getProjects(config)[0] || {};
 
   let prompt = '';
@@ -567,6 +608,7 @@ const { runPostCompletionHooks, updateWorkItemStatus, syncPrdItemStatus, handleP
 // ─── Agent Spawner ──────────────────────────────────────────────────────────
 
 const activeProcesses = new Map(); // dispatchId → { proc, agentId, startedAt }
+const tempAgents = new Map(); // tempAgentId → { name, role, createdAt }
 let engineRestartGraceUntil = 0; // timestamp — suppress orphan detection until this time
 
 // Resolve dependency plan item IDs to their PR branches
@@ -965,6 +1007,17 @@ function spawnAgent(dispatchItem, config) {
     try { fs.unlinkSync(promptPath.replace(/prompt-/, 'pid-').replace(/\.md$/, '.pid')); } catch {}
 
     log('info', `Agent ${agentId} completed. Output saved to ${archivePath}`);
+
+    // Clean up temp agent directory
+    if (tempAgents.has(agentId)) {
+      tempAgents.delete(agentId);
+      try {
+        const agentDir = path.join(AGENTS_DIR, agentId);
+        // Keep output archive but remove temp agent directory (live-output.log etc.)
+        fs.rmSync(agentDir, { recursive: true, force: true });
+        log('info', `Temp agent ${agentId} cleaned up`);
+      } catch {}
+    }
   });
 
   proc.on('error', (err) => {
@@ -1014,6 +1067,7 @@ function spawnAgent(dispatchItem, config) {
     if (idx < 0) return;
     const item = dispatch.pending.splice(idx, 1)[0];
     item.started_at = startedAt;
+    delete item.skipReason;
     if (!dispatch.active.some(d => d.id === id)) {
       dispatch.active.push(item);
     }
@@ -2280,7 +2334,7 @@ function selectPlaybook(workType, item) {
   if (workType === 'review' && !item?._pr && !item?.pr_id) {
     return 'work-item';
   }
-  const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask', 'verify'];
+  const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask', 'verify', 'decompose'];
   return typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
 }
 
@@ -2399,6 +2453,26 @@ function discoverFromPrs(config, project) {
         review_note: `Build is failing: ${pr.buildFailReason || 'Check CI pipeline for details'}. Fix the build errors and push.`,
       }, `Fix build failure on PR ${pr.id}`, { dispatchKey: key, source: 'pr', pr, branch: pr.branch, project: projMeta });
       if (item) { newWork.push(item); setCooldown(key); }
+
+      // Notify the author agent about the build failure
+      if (pr.agent && !pr._buildFailNotified) {
+        writeInboxAlert(`build-fail-${pr.agent}-${pr.id}`,
+          `# Build Failure Notification\n\n` +
+          `**Your PR ${pr.id}** on branch \`${pr.branch || 'unknown'}\` has a failing build.\n` +
+          `**Reason:** ${pr.buildFailReason || 'Check CI pipeline for details'}\n\n` +
+          `A fix agent has been dispatched to address this. Review the fix when complete.\n`
+        );
+        // Mark notified to prevent duplicate alerts
+        try {
+          const prPath = projectPrPath(project);
+          const prs = safeJson(prPath) || [];
+          const target = prs.find(p => p.id === pr.id);
+          if (target) {
+            target._buildFailNotified = true;
+            safeWrite(prPath, prs);
+          }
+        } catch {}
+      }
     }
 
   }
@@ -2442,10 +2516,15 @@ function discoverFromWorkItems(config, project) {
       if (depStatus === 'failed') {
         item.status = 'failed';
         item.failReason = 'Dependency failed — cannot proceed';
+        delete item._pendingReason;
         log('warn', `Marking ${item.id} as failed: dependency failed (plan: ${item.sourcePlan})`);
+        needsWrite = true;
+        continue;
+      }
+      if (!depStatus) {
+        if (item._pendingReason !== 'dependency_unmet') { item._pendingReason = 'dependency_unmet'; needsWrite = true; }
         continue;
       }
-      if (!depStatus) continue;
     }
 
     const key = `work-${project?.name || 'default'}-${item.id}`;
@@ -2465,14 +2544,30 @@ function discoverFromWorkItems(config, project) {
       delete item._resumedAt;
       safeWrite(projectWorkItemsPath(project), items);
     }
-    if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) { skipped.gated++; continue; }
+    if (isAlreadyDispatched(key)) {
+      if (item._pendingReason !== 'already_dispatched') { item._pendingReason = 'already_dispatched'; needsWrite = true; }
+      skipped.gated++; continue;
+    }
+    if (isOnCooldown(key, cooldownMs)) {
+      if (item._pendingReason !== 'cooldown') { item._pendingReason = 'cooldown'; needsWrite = true; }
+      skipped.gated++; continue;
+    }
 
     let workType = item.type || 'implement';
     if (workType === 'implement' && (item.complexity === 'large' || item.estimated_complexity === 'large')) {
       workType = 'implement:large';
     }
+    // Auto-decompose large items before implementation
+    if (workType === 'implement:large' && !item._decomposed && !item._decomposing && config.engine?.autoDecompose !== false) {
+      workType = 'decompose';
+      item._decomposing = true;
+      needsWrite = true;
+    }
     const agentId = item.agent || resolveAgent(workType, config);
-    if (!agentId) { skipped.noAgent++; continue; }
+    if (!agentId) {
+      if (item._pendingReason !== 'no_agent') { item._pendingReason = 'no_agent'; needsWrite = true; }
+      skipped.noAgent++; continue;
+    }
 
     const isShared = item.branchStrategy === 'shared-branch' && item.featureBranch;
     const branchName = isShared ? item.featureBranch : (item.branch || `work/${item.id}`);
@@ -2525,6 +2620,7 @@ function discoverFromWorkItems(config, project) {
     item.status = 'dispatched';
     item.dispatched_at = ts();
     item.dispatched_to = agentId;
+    delete item._pendingReason;
     prdSyncQueue.push({ id: item.id, sourcePlan: item.sourcePlan });
 
     newWork.push({
@@ -2964,6 +3060,23 @@ function discoverWork(config) {
   // Central work items (project-agnostic — agent decides where to work)
   const centralWork = discoverCentralWorkItems(config);
 
+  // Scheduled tasks (cron-style recurring work)
+  try {
+    const { discoverScheduledWork } = require('./engine/scheduler');
+    const scheduledWork = discoverScheduledWork(config);
+    for (const item of scheduledWork) {
+      // Write scheduled items to central work-items.json so they persist across ticks
+      const centralPath = path.join(MINIONS_DIR, 'work-items.json');
+      const items = safeJson(centralPath) || [];
+      // Dedupe: don't re-create if same schedule already has a pending/dispatched item
+      if (!items.some(i => i._scheduleId === item._scheduleId && i.status !== 'done' && i.status !== 'failed')) {
+        items.push(item);
+        safeWrite(centralPath, items);
+        log('info', `Scheduled task fired: ${item._scheduleId} → ${item.title}`);
+      }
+    }
+  } catch {}
+
   // Gate reviews and fixes: do not dispatch until all implement items are complete
   const hasIncompleteImplements = projects.some(project => {
     const items = safeJson(projectWorkItemsPath(project)) || [];
@@ -3016,7 +3129,7 @@ async function tick() {
 
 async function tickInner() {
   const control = getControl();
-  if (control.state !== 'running') {
+  if (control.state !== 'running' && control.state !== 'stopping') {
     log('info', `Engine state is "${control.state}" — exiting process`);
     process.exit(0);
   }
@@ -3031,6 +3144,12 @@ async function tickInner() {
   checkTimeouts(config);
   checkIdleThreshold(config);
 
+  // In stopping state, only track agent completions — skip discovery and dispatch
+  if (control.state === 'stopping') {
+    log('info', `Engine stopping — ${activeProcesses.size} agent(s) still active, skipping discovery/dispatch`);
+    return;
+  }
+
   // 2. Consolidate inbox
   consolidateInbox(config);
 
@@ -3212,6 +3331,28 @@ async function tickInner() {
       dispatched.add(item.id);
     }
   }
+
+  // Annotate remaining pending items with skipReason so dashboard can show why they're waiting.
+  // Re-read dispatch after spawns (spawnAgent moves items from pending→active).
+  const postDispatch = getDispatch();
+  const postBusyAgents = new Set((postDispatch.active || []).map(d => d.agent));
+  const postActiveCount = (postDispatch.active || []).length;
+  let skipReasonChanged = false;
+  for (const item of (postDispatch.pending || [])) {
+    let reason = null;
+    if (postActiveCount >= maxConcurrent) {
+      reason = 'max_concurrency';
+    } else if (postBusyAgents.has(item.agent)) {
+      reason = 'agent_busy';
+    }
+    if (item.skipReason !== reason) {
+      item.skipReason = reason;
+      skipReasonChanged = true;
+    }
+  }
+  if (skipReasonChanged) {
+    mutateDispatch((dp) => { dp.pending = postDispatch.pending; });
+  }
 }
 
 // ─── Exports (for engine/cli.js and other modules) ──────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/decompose.md

@@ -0,0 +1,60 @@
+# Playbook: Task Decomposition
+
+You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
+TEAM ROOT: {{team_root}}
+
+## Your Task
+
+A work item has been flagged as too large for a single agent dispatch. Analyze the item and break it into 2-5 smaller, independently implementable sub-tasks.
+
+## Work Item
+
+- **ID:** {{item_id}}
+- **Title:** {{item_title}}
+- **Description:** {{item_description}}
+- **Complexity:** {{item_complexity}}
+- **Project:** {{project_name}} (`{{project_path}}`)
+
+{{#acceptance_criteria}}
+## Acceptance Criteria
+
+{{acceptance_criteria}}
+{{/acceptance_criteria}}
+
+## Instructions
+
+1. **Explore the codebase** at `{{project_path}}` — understand the existing structure, patterns, and dependencies
+2. **Analyze the work item** — identify distinct units of work that can be implemented as separate PRs
+3. **Break into 2-5 sub-tasks** — each should be:
+   - Small or medium complexity (not large)
+   - A single PR's worth of work
+   - Independently testable
+   - Clear enough for another agent to implement without ambiguity
+4. **Order by dependency** — if sub-task B needs sub-task A's code, declare `depends_on`
+5. **Generate unique IDs** — use format `{{item_id}}-a`, `{{item_id}}-b`, etc.
+
+## Output
+
+Write the decomposition result as a JSON code block in your response:
+
+```json
+{
+  "parent_id": "{{item_id}}",
+  "sub_items": [
+    {
+      "id": "{{item_id}}-a",
+      "name": "Short descriptive name",
+      "description": "What to build, where, and how. Be specific enough that an engineer can implement without further exploration.",
+      "estimated_complexity": "small|medium",
+      "depends_on": [],
+      "acceptance_criteria": ["Criterion 1", "Criterion 2"]
+    }
+  ]
+}
+```
+
+Keep the total number of sub-items between 2 and 5. If the task genuinely cannot be broken down further, output a single sub-item that matches the original.
+
+{{pr_create_instructions}}
+
+{{pr_comment_instructions}}

package/routing.md

@@ -17,6 +17,7 @@ How the engine decides who handles what. Parsed by engine.js — keep the table
 | test | dallas | ralph |
 | ask | ripley | rebecca |
 | verify | dallas | ralph |
+| decompose | ripley | rebecca |
 
 Notes:
 - `_author_` means route to the PR author