@yemi33/minions 0.1.1807 → 0.1.1809

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.1809 (2026-05-08)
+
+### Features
+- add CC action intent fallback (#2234)
+
+### Fixes
+-  Plan-to-PRD conversion can override explicit plan project with contextual project (#2235)
+
 ## 0.1.1807 (2026-05-08)
 
 ### Other

package/dashboard/js/command-center.js

@@ -567,7 +567,8 @@ function ccAddMessage(role, html, skipSave, targetTabId, meta) {
   }
 }
 
-async function ccSend() {
+async function ccSend(options) {
+  var intentMetadata = options && options.intentMetadata ? options.intentMetadata : null;
   var input = document.getElementById('cc-input');
   var message = input.value.trim();
   if (!message) return;
@@ -580,11 +581,11 @@ async function ccSend() {
 
   // If this tab is already processing, queue the message
   if (tab._sending) {
-    tab._queue.push(message);
+    tab._queue.push({ message: message, intentMetadata: intentMetadata });
     _renderQueueIndicator();
     return;
   }
-  var wasAborted = await _ccDoSend(message, false, originTabId);
+  var wasAborted = await _ccDoSend(message, false, originTabId, intentMetadata);
 
   // Flush queued messages to the ORIGINAL tab, even if user switched tabs
   while (tab._queue && tab._queue.length > 0) {
@@ -592,8 +593,10 @@ async function ccSend() {
       await new Promise(function(r) { setTimeout(r, 1500); });
     }
     var next = tab._queue.shift();
+    var nextMessage = typeof next === 'string' ? next : next.message;
+    var nextIntentMetadata = typeof next === 'string' ? null : (next.intentMetadata || null);
     _renderQueueIndicator();
-    wasAborted = await _ccDoSend(next, false, originTabId);
+    wasAborted = await _ccDoSend(nextMessage, false, originTabId, nextIntentMetadata);
   }
 }
 
@@ -608,13 +611,13 @@ function _renderQueueIndicator() {
     var el = document.createElement('div');
     el.className = 'cc-queue-item';
     el.style.cssText = 'padding:8px 12px;border-radius:8px;font-size:12px;line-height:1.6;max-width:95%;align-self:flex-end;background:var(--blue);color:#fff;opacity:0.5;order:9999';
-    el.innerHTML = escHtml(m) + '<div style="font-size:9px;opacity:0.7;font-style:italic;margin-top:2px">queued</div>';
+    el.innerHTML = escHtml(typeof m === 'string' ? m : m.message) + '<div style="font-size:9px;opacity:0.7;font-style:italic;margin-top:2px">queued</div>';
     msgs.appendChild(el);
   });
   if (msgs.scrollHeight - msgs.scrollTop - msgs.clientHeight < 150) msgs.scrollTop = msgs.scrollHeight;
 }
 
-async function _ccDoSend(message, skipUserMsg, forceTabId) {
+async function _ccDoSend(message, skipUserMsg, forceTabId, intentMetadata) {
   // Client-side /pin and /unpin — no LLM round-trip needed
   var pinMatch = message.match(/^\/(pin|unpin)\s+(.+)/i);
   if (pinMatch) {
@@ -762,7 +765,7 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
       if (!isReconnect && res.status === 429 && (!activeTab._429retries || activeTab._429retries < 3)) {
         activeTab._429retries = (activeTab._429retries || 0) + 1;
         await new Promise(function(r) { setTimeout(r, 1500); });
-        return await _ccConsumeStream({ message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, transcript: _ccBuildTranscript(activeTab) }, false);
+        return await _ccConsumeStream({ message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, transcript: _ccBuildTranscript(activeTab), intentMetadata: intentMetadata || null }, false);
       }
       activeTab._429retries = 0;
       var errText = await res.text();
@@ -871,7 +874,7 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
     while (true) {
       var consume = await _ccConsumeStream(
         reconnectAttempts === 0
-          ? { message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, transcript: _ccBuildTranscript(activeTab) }
+          ? { message: message, tabId: activeTabId, sessionId: activeTab.sessionId || null, transcript: _ccBuildTranscript(activeTab), intentMetadata: intentMetadata || null }
           : { tabId: activeTabId, sessionId: activeTab.sessionId || null, reconnect: true },
         reconnectAttempts > 0
       );

package/dashboard/js/command-input.js

@@ -134,12 +134,13 @@ async function cmdSubmit() {
   const input = document.getElementById('cmd-input');
   const raw = input.value.trim();
   if (!raw) return showToast('cmd-toast', 'Type something first', false);
+  const parsed = cmdParseInput(raw);
 
   // Route to Command Center panel
   input.value = '';
   if (!_ccOpen) toggleCommandCenter();
   document.getElementById('cc-input').value = raw;
-  ccSend();
+  ccSend({ intentMetadata: parsed });
   cmdSaveHistory(raw, 'cc');
   return;
 }

package/dashboard/js/modal-qa.js

@@ -344,7 +344,7 @@ function _qaBuildAssistantHtml(text, opts) {
     '</div>';
 }
 
-const QA_WORK_ITEM_ACTION_TYPES = new Set(['dispatch', 'fix', 'implement', 'explore', 'review', 'test']);
+const QA_WORK_ITEM_ACTION_TYPES = new Set(['dispatch', 'fix', 'explore', 'review', 'test']);
 
 function _qaActionFeedbackHandled(action, actionResult) {
   const type = String(actionResult?.type || action?.type || '');

package/dashboard.js

@@ -1815,6 +1815,7 @@ function _extractActionsJson(segment) {
 }
 
 const CC_DISPATCH_ACTION_ALIASES = new Set(['fix', 'explore', 'review', 'test']);
+const CC_ACTION_INTENT_WORK_TYPES = new Set(['fix', 'implement', 'explore', 'review', 'test']);
 
 function normalizeCCAction(action) {
   if (!action || typeof action !== 'object') return action;
@@ -1827,6 +1828,161 @@ function normalizeCCAction(action) {
   return { ...action, type: 'dispatch', workType: action.workType || type };
 }
 
+function _ccCleanIntentString(value, max = 500) {
+  if (typeof value !== 'string') return '';
+  return value.replace(/[\0\r\n]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+function _ccNormalizeIntentMetadata(meta) {
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) return {};
+  const out = {};
+  for (const key of ['intent', 'type', 'title', 'description', 'priority', 'project', 'branchStrategy', 'branch_strategy']) {
+    const value = _ccCleanIntentString(meta[key], key === 'description' ? 2000 : 300);
+    if (value) out[key] = value;
+  }
+  if (Array.isArray(meta.agents)) {
+    out.agents = meta.agents.map(a => _ccCleanIntentString(a, 80)).filter(Boolean);
+  }
+  if (Array.isArray(meta.projects)) {
+    out.projects = meta.projects.map(p => _ccCleanIntentString(p, 120)).filter(Boolean);
+  }
+  if (meta.fanout === true) out.fanout = true;
+  return out;
+}
+
+function _messageExplicitlyRequestsMinionsOrchestration(message) {
+  const text = String(message || '').toLowerCase();
+  if (!text.trim()) return false;
+  return [
+    /\b(?:dispatch|delegate|assign|queue)\b/,
+    /\b(?:create|open|file)\s+(?:a\s+)?(?:work\s*item|task)\b/,
+    /\b(?:have|ask|tell)\s+(?:minions|an?\s+agent|[a-z][\w-]*)\s+(?:to\s+)?(?:fix|implement|review|test|explore|investigate)\b/,
+    /\bminions\b[^.?!\n]*\b(?:fix|implement|review|test|explore|investigate|plan)\b/,
+    /\b(?:create|make|draft|write)\s+(?:a\s+)?minions?\s+plan\b/,
+  ].some(pattern => pattern.test(text));
+}
+
+function _ccInferMessageActionIntent(message, source = 'command-center') {
+  const text = String(message || '').trim();
+  const lower = text.toLowerCase();
+  if (!lower) return null;
+  if (source === 'doc-chat' && !_messageExplicitlyRequestsMinionsOrchestration(text)) return null;
+  if (/^\/plan\b/.test(lower) || /\b(?:make|create|draft|write|design|come up with)\s+(?:a\s+)?plan\b/.test(lower) || /\bplan\s+(?:this|that|it|for|how|out)\b/.test(lower)) {
+    return { kind: 'plan' };
+  }
+  const workPatterns = [
+    ['fix', /\b(?:fix|repair|resolve|patch|debug)\b|\b(?:bug|broken|crash|error|regression|failing|failure)\b/],
+    ['implement', /\b(?:implement|build|add|create|ship)\b/],
+    ['review', /\b(?:review|code review|inspect|audit)\b/],
+    ['test', /\b(?:test|verify|validate|run tests?|write tests?|add tests?|coverage|build)\b/],
+    ['explore', /\b(?:explore|investigate|research|analyze|understand|look into|map out|survey)\b/],
+  ];
+  for (const [workType, pattern] of workPatterns) {
+    if (pattern.test(lower)) return { kind: 'work-item', workType };
+  }
+  return null;
+}
+
+function _ccInferMetadataActionIntent(meta) {
+  if (meta.intent === 'plan') return { kind: 'plan' };
+  if (meta.intent === 'work-item' && CC_ACTION_INTENT_WORK_TYPES.has(String(meta.type || '').toLowerCase())) {
+    return { kind: 'work-item', workType: String(meta.type).toLowerCase() };
+  }
+  return null;
+}
+
+function _ccActionIntentTargetText(message, intent) {
+  let text = _ccCleanIntentString(message, 500);
+  text = text
+    .replace(/^\/(?:plan|fix|implement|review|test|explore)\s+/i, '')
+    .replace(/^(?:please\s+)?(?:dispatch|delegate|assign|queue)\s+(?:a\s+|an\s+)?(?:work\s*item|task|agent)?\s*(?:to\s+)?/i, '')
+    .replace(/^(?:please\s+)?(?:create|open|file)\s+(?:a\s+)?(?:work\s*item|task)\s+(?:to\s+|for\s+)?/i, '')
+    .replace(/^(?:please\s+)?(?:have|ask|tell)\s+(?:minions|an?\s+agent|[a-z][\w-]*)\s+(?:to\s+)?/i, '')
+    .replace(/^(?:please\s+)?/, '')
+    .trim();
+  if (intent?.kind === 'plan') {
+    text = text.replace(/^(?:make|create|draft|write|design|come up with)\s+(?:a\s+)?plan\s+(?:for\s+|to\s+|about\s+)?/i, '')
+      .replace(/^plan\s+(?:out\s+)?(?:for\s+|how\s+to\s+|this\s+|that\s+|it\s+)?/i, '');
+  } else if (intent?.workType) {
+    const workType = intent.workType;
+    const verbPattern = {
+      fix: /^(?:fix|repair|resolve|patch|debug)\s+(?:the\s+|a\s+|an\s+)?/i,
+      implement: /^(?:implement|build|add|create|ship)\s+(?:the\s+|a\s+|an\s+)?/i,
+      review: /^(?:review|code review|inspect|audit)\s+(?:the\s+|a\s+|an\s+)?/i,
+      test: /^(?:test|verify|validate|run tests?\s+(?:for\s+|on\s+)?|write tests?\s+(?:for\s+)?|add tests?\s+(?:for\s+)?)\s*(?:the\s+|a\s+|an\s+)?/i,
+      explore: /^(?:explore|investigate|research|analyze|understand|look into|map out|survey)\s+(?:the\s+|a\s+|an\s+)?/i,
+    }[workType];
+    if (verbPattern) text = text.replace(verbPattern, '');
+    text = text.replace(/^(?:a\s+)?(?:fix|review|test|implementation|exploration|investigation)\s+(?:for\s+|to\s+|of\s+)?/i, '');
+  }
+  return text.replace(/^(?:for|to|of|on|about)\s+/i, '').trim();
+}
+
+function _ccIntentHasConcreteTarget(message, metadataTitle, intent) {
+  const raw = String(message || '');
+  if (/\b(?:PR|pull request|issue)\s*#?\d+\b/i.test(raw) || /\bW-[a-z0-9][a-z0-9-]*\b/i.test(raw) || /https?:\/\//i.test(raw)) return true;
+  const target = _ccActionIntentTargetText(metadataTitle || raw, intent)
+    .replace(/[.!?]+$/g, '')
+    .trim()
+    .toLowerCase();
+  if (!target) return false;
+  if (/^(?:this|that|it|these|those|same|above|the above|here|there)(?:\s+(?:one|thing|issue|bug|task|request|change|pr|pull request|code|test|plan|doc|document|file))?$/.test(target)) {
+    return false;
+  }
+  return target.length >= 3;
+}
+
+function _ccIntentTitle(message, metadataTitle, intent) {
+  const metaTitle = _ccCleanIntentString(metadataTitle, 300);
+  if (metaTitle && _ccIntentHasConcreteTarget(message, metaTitle, intent)) return metaTitle;
+  const cleaned = _ccCleanIntentString(message, 300).replace(/^\/plan\s+/i, 'plan ');
+  if (!cleaned) return '';
+  return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+
+function _ccFallbackMissingTargetError(intent) {
+  const label = intent?.kind === 'plan' ? 'plan' : (intent?.workType || 'dispatch');
+  return `Missing target for ${label} request. Specify a concrete title, PR/work item, file, or feature to ${label}.`;
+}
+
+function _actionsWithIntentFallback(actions, { message = '', intentMetadata = null, source = 'command-center' } = {}) {
+  const existing = Array.isArray(actions) ? actions : [];
+  if (existing.length > 0) return existing;
+  const meta = _ccNormalizeIntentMetadata(intentMetadata);
+  const messageIntent = _ccInferMessageActionIntent(message, source);
+  const metadataIntent = source === 'doc-chat' ? null : _ccInferMetadataActionIntent(meta);
+  const intent = messageIntent || metadataIntent;
+  if (!intent) return existing;
+
+  const title = _ccIntentTitle(message, meta.title, intent);
+  const hasTarget = _ccIntentHasConcreteTarget(message, meta.title || title, intent);
+  const description = meta.description || _ccCleanIntentString(message, 2000);
+  const common = {
+    ...(title ? { title } : {}),
+    ...(description ? { description } : {}),
+    ...(meta.priority ? { priority: meta.priority } : {}),
+    ...(meta.project ? { project: meta.project } : {}),
+    ...(Array.isArray(meta.agents) && meta.agents.length ? { agents: meta.agents } : {}),
+    ...(meta.fanout ? { scope: 'fan-out' } : {}),
+  };
+  if (intent.kind === 'plan') {
+    const action = {
+      type: 'plan',
+      ...common,
+      branchStrategy: meta.branchStrategy || meta.branch_strategy || 'parallel',
+    };
+    if (!hasTarget) action._intentFallbackError = _ccFallbackMissingTargetError(intent);
+    return [action];
+  }
+  const action = {
+    type: 'dispatch',
+    workType: intent.workType,
+    ...common,
+  };
+  if (!hasTarget) action._intentFallbackError = _ccFallbackMissingTargetError(intent);
+  return [action];
+}
+
 function parseCCActions(text) {
   let actions = [];
   let displayText = stripCCActionsForDisplay(text);
@@ -2262,6 +2418,8 @@ function _ccValidateAction(action) {
     case 'dispatch': case 'fix': case 'explore': case 'review': case 'test':
       if (!action.title || typeof action.title !== 'string' || !action.title.trim()) return `${action.type} action missing required field: title`;
       return null;
+    case 'implement':
+      return 'Unsupported action type "implement"; use type="dispatch" with workType="implement".';
     case 'build-and-test':
       if (!action.pr) return 'build-and-test action missing required field: pr';
       return null;
@@ -2586,6 +2744,15 @@ async function executeCCActions(actions, { source = 'command-center', inferredPr
   const results = [];
   for (const rawAction of actions) {
     const action = normalizeCCAction(rawAction);
+    if (action?._intentFallbackError) {
+      results.push({
+        type: action.type || 'dispatch',
+        ...(action.workType ? { workType: action.workType } : {}),
+        error: action._intentFallbackError,
+        missingTarget: true,
+      });
+      continue;
+    }
     const validationError = _ccValidateAction(action);
     if (validationError) {
       results.push({ type: action?.type || 'unknown', error: validationError });
@@ -2887,7 +3054,7 @@ async function executeDocChatActions(actions, { filePath = null } = {}) {
   return executeCCActions(actions, { source: 'doc-chat', inferredProject: _inferDocChatProject(filePath) });
 }
 
-const DOC_CHAT_WORK_ITEM_ACTION_TYPES = new Set(['dispatch', 'fix', 'implement', 'explore', 'review', 'test']);
+const DOC_CHAT_WORK_ITEM_ACTION_TYPES = new Set(['dispatch', 'fix', 'explore', 'review', 'test']);
 
 function _buildDocChatActionFeedback(actions, actionResults) {
   if (!Array.isArray(actions) || !Array.isArray(actionResults)) return [];
@@ -5506,12 +5673,14 @@ const server = http.createServer(async (req, res) => {
       shared.sanitizePath(body.file, PLANS_DIR);
       const planPath = path.join(MINIONS_DIR, 'plans', body.file);
       if (!fs.existsSync(planPath)) return jsonReply(res, 404, { error: 'plan file not found' });
+      const planContent = fs.readFileSync(planPath, 'utf8');
+      const declaredProject = shared.extractPlanDeclaredProject(planContent);
 
       const queued = shared.queuePlanToPrd({
         planFile: body.file,
         title: 'Convert plan to PRD: ' + body.file.replace('.md', ''),
         description: 'Plan file: plans/' + body.file,
-        project: body.project || '', createdBy: 'dashboard:execute',
+        project: declaredProject || body.project || '', createdBy: 'dashboard:execute',
       });
       if (!queued) return jsonReply(res, 200, { ok: true, alreadyQueued: true });
       invalidateStatusCache();
@@ -5911,7 +6080,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         }
       }
 
-      const { answer, content, actions, actionParseError, partial, warning, toolUses, error: ccError } = await ccDocCall({
+      let { answer, content, actions, actionParseError, partial, warning, toolUses, error: ccError } = await ccDocCall({
         message: body.message, document: currentContent, title: body.title,
         filePath: body.filePath, selection: body.selection, canEdit, isJson,
         model: body.model || undefined,
@@ -5919,6 +6088,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         transcript: body.transcript,
         onAbortReady: (abort) => { _docAbort = abort; },
       });
+      actions = _actionsWithIntentFallback(actions, { message: body.message, source: 'doc-chat' });
       const actionResults = await executeDocChatActions(actions, { filePath: body.filePath });
       const actionFeedback = _buildDocChatActionFeedback(actions, actionResults);
       const finalize = _finalizeDocChatEdit({
@@ -6003,7 +6173,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
       try {
 
-        const { answer, content, actions, actionParseError, partial, warning, toolUses, error: ccError } = await ccDocCallStreaming({
+        let { answer, content, actions, actionParseError, partial, warning, toolUses, error: ccError } = await ccDocCallStreaming({
           message: body.message, document: currentContent, title: body.title,
           filePath: body.filePath, selection: body.selection, canEdit, isJson,
           model: body.model || undefined,
@@ -6014,6 +6184,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           onToolUse: (name, input) => { writeDocEvent({ type: 'tool', name, input: _lightToolInput(input) }); },
           onRetry: (attempt) => { writeDocEvent({ type: 'progress', attempt }); },
         });
+        actions = _actionsWithIntentFallback(actions, { message: body.message, source: 'doc-chat' });
         const actionResults = await executeDocChatActions(actions, { filePath: body.filePath });
         const actionFeedback = _buildDocChatActionFeedback(actions, actionResults);
         const finalize = _finalizeDocChatEdit({
@@ -6543,6 +6714,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         }
 
         const parsed = parseCCActions(result.text);
+        parsed.actions = _actionsWithIntentFallback(parsed.actions, {
+          message: body.message,
+          intentMetadata: body.intentMetadata,
+          source: 'command-center',
+        });
         const toolUses = Array.isArray(result.toolUses) ? result.toolUses : _extractToolUsesFromRaw(result.raw);
         // Safety net: detect /loop invocation and convert to create-watch
         const _loopWatch = _detectLoopInvocation(parsed.text, parsed.actions, toolUses, body.message);
@@ -6872,6 +7048,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
         // Send final result with actions — execute server-side first
         let { text: displayText, actions, _actionParseError } = parseCCActions(result.text);
+        actions = _actionsWithIntentFallback(actions, {
+          message: body.message,
+          intentMetadata: body.intentMetadata,
+          source: 'command-center',
+        });
         // Safety net: detect /loop invocation and convert to create-watch
         const _loopWatch = _detectLoopInvocation(displayText, actions, toolUses, body.message);
         if (_loopWatch) {
@@ -8509,6 +8690,7 @@ module.exports = {
   _resolveSkillReadPath,
   DOC_CHAT_DOCUMENT_DELIMITER,
   _ccValidateAction,
+  _actionsWithIntentFallback,
   _messageExplicitlyRequestsMonitoring,
   _filterImplicitPostDispatchActions,
   _findDuplicateWorkItemCreate: findDuplicateWorkItemCreate,

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-08T19:31:14.792Z"
+  "cachedAt": "2026-05-08T20:58:39.806Z"
 }

package/engine/playbook.js

@@ -332,14 +332,29 @@ function validatePlaybookVars(playbookName, vars) {
  * @param {string} playbookType — playbook type name (e.g. 'implement', 'review')
  * @returns {string} absolute path to the playbook file
  */
+function isSafeProjectPlaybookName(projectName) {
+  const name = String(projectName || '').trim();
+  return !!name &&
+    !name.includes('\0') &&
+    !name.includes('..') &&
+    !/[\\/]/.test(name) &&
+    !path.isAbsolute(name) &&
+    !/^[a-zA-Z]:/.test(name);
+}
+
 function resolvePlaybookPath(projectName, playbookType) {
   if (projectName) {
-    const localPath = path.join(MINIONS_DIR, 'projects', projectName, 'playbooks', `${playbookType}.md`);
-    try {
-      fs.accessSync(localPath, fs.constants.R_OK);
-      log('info', `Using project-local playbook: projects/${projectName}/playbooks/${playbookType}.md`);
-      return localPath;
-    } catch { /* no local override — fall through to global */ }
+    const projectDirName = String(projectName).trim();
+    if (isSafeProjectPlaybookName(projectDirName)) {
+      const localPath = path.join(MINIONS_DIR, 'projects', projectDirName, 'playbooks', `${playbookType}.md`);
+      try {
+        fs.accessSync(localPath, fs.constants.R_OK);
+        log('info', `Using project-local playbook: projects/${projectDirName}/playbooks/${playbookType}.md`);
+        return localPath;
+      } catch { /* no local override — fall through to global */ }
+    } else {
+      log('warn', `Skipping project-local playbook lookup for unsafe project name: ${projectDirName}`);
+    }
   }
   return path.join(PLAYBOOKS_DIR, `${playbookType}.md`);
 }

package/engine/shared.js

@@ -1579,6 +1579,24 @@ function queuePlanToPrd({ planFile, prdFile, title, description, project, create
   }, { defaultValue: [] });
   return queued;
 }
+
+function extractPlanDeclaredProject(planContent) {
+  if (typeof planContent !== 'string' || !planContent.trim()) return '';
+  const lines = planContent.split(/\r?\n/).slice(0, 80);
+  for (const rawLine of lines) {
+    const line = rawLine
+      .replace(/^\s*[-*]\s+/, '')
+      .replace(/\*\*/g, '')
+      .trim();
+    const match = line.match(/^Project\s*:\s*(.+)$/i);
+    if (!match) continue;
+    let value = match[1].trim();
+    value = value.replace(/\s+#.*$/, '').trim();
+    value = value.replace(/^["'`]+|["'`]+$/g, '').trim();
+    return value;
+  }
+  return '';
+}
 const DISPATCH_RESULT = { SUCCESS: 'success', ERROR: 'error', TIMEOUT: 'timeout' };
 const PIPELINE_STATUS = {
   PENDING: 'pending', RUNNING: 'running', COMPLETED: 'completed',
@@ -3257,7 +3275,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
   FAILURE_CLASS, ESCALATION_POLICY, COMPLETION_FIELDS,
@@ -3302,6 +3320,7 @@ module.exports = {
   getAdoOrgBase,
   sanitizePath,
   sanitizeBranch,
+  safeSlugComponent,
   buildWorktreeDirName, // exported for testing
   isPathInside,
   isPathInsideOrEqual,

package/engine.js

@@ -1978,6 +1978,20 @@ function buildWiDescription(item, planFile) {
   return `${item.description || ''}\n\n**Plan:** ${planFile}\n**Plan Item:** ${item.id}\n**Complexity:** ${complexity}${criteria ? '\n\n**Acceptance Criteria:**\n' + criteria : ''}`;
 }
 
+function safePrdProjectSlug(projectName) {
+  const slug = shared.safeSlugComponent(projectName || 'project', 80)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'project';
+}
+
+function safePrdFilenameForProject(projectName, suffix) {
+  const fileName = `${safePrdProjectSlug(projectName)}-${suffix}.json`;
+  shared.sanitizePath(fileName, PRD_DIR);
+  return fileName;
+}
+
 function materializePlansAsWorkItems(config) {
   if (!fs.existsSync(PRD_DIR)) { try { fs.mkdirSync(PRD_DIR, { recursive: true }); } catch (e) { log('warn', 'create PRD directory: ' + e.message); } }
   const writePrdLocked = (fileName, data) => {
@@ -1990,6 +2004,100 @@ function materializePlansAsWorkItems(config) {
       return mutator(current) || current;
     }, { defaultValue: fallback || {}, ...options });
   };
+  const declaredProjectPrdFilename = (fileName, projectName) => {
+    const match = String(fileName || '').match(/-(\d{4}-\d{2}-\d{2}(?:-\d+)?)\.json$/);
+    if (!match) return null;
+    return safePrdFilenameForProject(projectName, match[1]);
+  };
+  const migratePrdFilenameReferences = (oldFileName, newFileName) => {
+    if (!oldFileName || !newFileName || oldFileName === newFileName) return 0;
+    let migrated = 0;
+    const wiPaths = new Set([path.join(MINIONS_DIR, 'work-items.json')]);
+    for (const project of getProjects(config)) wiPaths.add(projectWorkItemsPath(project));
+    for (const wiPath of wiPaths) {
+      if (!fs.existsSync(wiPath)) continue;
+      mutateWorkItems(wiPath, (items) => {
+        for (const wi of items) {
+          if (!wi || typeof wi !== 'object') continue;
+          if (wi.sourcePlan === oldFileName) {
+            wi.sourcePlan = newFileName;
+            migrated++;
+          }
+          if (wi._artifacts?.sourcePlan === oldFileName) {
+            wi._artifacts.sourcePlan = newFileName;
+            migrated++;
+          }
+        }
+        return items;
+      });
+    }
+    if (fs.existsSync(DISPATCH_PATH)) {
+      mutateDispatch((dispatch) => {
+        for (const queue of ['pending', 'active', 'completed']) {
+          for (const entry of dispatch[queue] || []) {
+            const metaItem = entry?.meta?.item;
+            if (!metaItem || typeof metaItem !== 'object') continue;
+            if (metaItem.sourcePlan === oldFileName) {
+              metaItem.sourcePlan = newFileName;
+              migrated++;
+            }
+            if (metaItem._prdFilename === oldFileName) {
+              metaItem._prdFilename = newFileName;
+              migrated++;
+            }
+          }
+        }
+        return dispatch;
+      });
+    }
+    return migrated;
+  };
+  const enforceDeclaredPlanProject = (fileName, currentPlan) => {
+    if (!currentPlan?.source_plan) return { fileName, plan: currentPlan };
+    let declaredProject = '';
+    try {
+      declaredProject = shared.extractPlanDeclaredProject(safeRead(path.join(PLANS_DIR, currentPlan.source_plan)) || '');
+    } catch (e) {
+      log('warn', `Plan project enforcement: could not read source plan ${currentPlan.source_plan}: ${e.message}`);
+    }
+    if (!declaredProject) return { fileName, plan: currentPlan };
+
+    let changed = false;
+    const normalizedPlan = mutatePrdLocked(fileName, currentPlan, (planData) => {
+      if (planData.project !== declaredProject) {
+        planData.project = declaredProject;
+        changed = true;
+      }
+      if (Array.isArray(planData.missing_features)) {
+        for (const feature of planData.missing_features) {
+          if (feature && feature.project !== declaredProject) {
+            feature.project = declaredProject;
+            changed = true;
+          }
+        }
+      }
+      return planData;
+    }, { skipWriteIfUnchanged: true });
+
+    let nextFileName = fileName;
+    const desiredFileName = declaredProjectPrdFilename(fileName, declaredProject);
+    if (desiredFileName && desiredFileName.toLowerCase() !== String(fileName).toLowerCase()) {
+      const fromPath = path.join(PRD_DIR, fileName);
+      const desiredPath = shared.sanitizePath(desiredFileName, PRD_DIR);
+      const toPath = shared.uniquePath(desiredPath);
+      try {
+        fs.renameSync(fromPath, toPath);
+        nextFileName = path.basename(toPath);
+        const migrated = migratePrdFilenameReferences(fileName, nextFileName);
+        if (migrated > 0) log('info', `Plan project enforcement: migrated ${migrated} PRD reference(s) from ${fileName} to ${nextFileName}`);
+        changed = true;
+      } catch (e) {
+        log('warn', `Plan project enforcement: could not rename ${fileName} to ${path.basename(toPath)}: ${e.message}`);
+      }
+    }
+    if (changed) log('info', `Plan project enforcement: preserved declared project "${declaredProject}" for ${nextFileName}`);
+    return { fileName: nextFileName, plan: normalizedPlan };
+  };
 
   // Enforce: PRDs must be .json — auto-rename .md files that contain valid PRD JSON
   // Check both prd/ and plans/ (agents may still write JSON to plans/)
@@ -2036,12 +2144,13 @@ function materializePlansAsWorkItems(config) {
   // Regex for detecting sequential PRD item IDs (P-001, P-002) — hoisted outside loop
   const SEQUENTIAL_ID_RE = /^P-?\d+$/;
 
-  for (const file of planFiles) {
+  for (let file of planFiles) {
     // safeJsonNoRestore — if a PRD was archived between readdir and this
     // read, do not auto-resurrect it from a stale .backup sidecar
     // (W-mouptdh1000h9f39).
     let plan = safeJsonNoRestore(path.join(PRD_DIR, file));
     if (!plan?.missing_features) continue;
+    ({ fileName: file, plan } = enforceDeclaredPlanProject(file, plan));
 
     // ID collision prevention: remap sequential IDs (P-001, P-002) to globally unique P-<uid> IDs.
     // Agents are instructed to use P-<uuid> format but sometimes generate sequential IDs,
@@ -3576,7 +3685,7 @@ function discoverCentralWorkItems(config) {
   const items = safeJson(centralPath) || [];
   const projects = getProjects(config);
   const dispatchProjects = getCentralDispatchProjects(projects);
-  const projectsByName = new Map(dispatchProjects.map(p => [p.name, p]));
+  const projectsByName = new Map(dispatchProjects.map(p => [String(p.name || '').toLowerCase(), p]));
   const newWork = [];
   // Collect mutations to apply atomically inside lock callback (avoids TOCTOU)
   const mutations = new Map(); // item.id → { field: value, ... }
@@ -3706,9 +3815,32 @@ function discoverCentralWorkItems(config) {
 
       const agentName = config.agents[agentId]?.name || agentId;
       const agentRole = config.agents[agentId]?.role || 'Agent';
+      let planFileContent = null;
+      let planReadError = null;
+      let declaredPlanProject = '';
+      if (workType === WORK_TYPE.PLAN_TO_PRD && item.planFile) {
+        const planPath = path.join(PLANS_DIR, item.planFile);
+        try {
+          planFileContent = fs.readFileSync(planPath, 'utf8');
+          declaredPlanProject = shared.extractPlanDeclaredProject(planFileContent);
+        } catch (e) {
+          planReadError = e;
+        }
+      }
       const firstProject = dispatchProjects[0];
-      const requestedProjectName = typeof item.project === 'string' ? item.project : item.project?.name;
-      const targetProject = (requestedProjectName && projectsByName.get(requestedProjectName)) || firstProject;
+      const requestedProjectName = declaredPlanProject || (typeof item.project === 'string' ? item.project : item.project?.name);
+      const requestedProject = requestedProjectName ? projectsByName.get(String(requestedProjectName).toLowerCase()) : null;
+      const targetProject = requestedProject || (declaredPlanProject
+        ? { name: declaredPlanProject, localPath: '', repoName: declaredPlanProject, mainBranch: firstProject?.mainBranch || 'main' }
+        : firstProject);
+      if (declaredPlanProject) {
+        const projectMutation = { project: targetProject.name, _declaredPlanProject: declaredPlanProject };
+        if (!requestedProject) projectMutation._declaredPlanProjectMissing = true;
+        mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, projectMutation));
+        if (!requestedProject) {
+          log('warn', `plan-to-prd: plan ${item.planFile} declares project "${declaredPlanProject}" but no configured project matches; preserving the declared project name with no project_path`);
+        }
+      }
 
       // Branch mutex: skip if target branch is locked by an active dispatch
       const centralBranch = item.branch || item.featureBranch || `work/${item.id}`;
@@ -3776,16 +3908,16 @@ function discoverCentralWorkItems(config) {
       if (workType === WORK_TYPE.PLAN_TO_PRD && item.planFile) {
         if (!fs.existsSync(PLANS_DIR)) fs.mkdirSync(PLANS_DIR, { recursive: true });
         if (!fs.existsSync(PRD_DIR)) fs.mkdirSync(PRD_DIR, { recursive: true });
-        const planPath = path.join(PLANS_DIR, item.planFile);
-        try {
-          vars.plan_content = fs.readFileSync(planPath, 'utf8');
-        } catch (e) {
-          log('warn', `plan-to-prd: could not read plan file ${item.planFile} for ${item.id}: ${e.message}`);
+        if (planFileContent !== null) {
+          vars.plan_content = planFileContent;
+        } else {
+          if (planReadError) log('warn', `plan-to-prd: could not read plan file ${item.planFile} for ${item.id}: ${planReadError.message}`);
           vars.plan_content = item.description || '';
         }
         vars.plan_summary = (item.title || item.planFile).substring(0, 80);
         vars.plan_file = item.planFile || '';
         vars.project_name_lower = (targetProject?.name || 'project').toLowerCase();
+        vars.project_filename_slug = safePrdProjectSlug(targetProject?.name || 'project');
         // Default empty string so the {{existing_prd_json}} token always resolves —
         // playbook treats empty as "no existing PRD, fresh run". Without this default
         // the renderPlaybook pass logs an "unresolved template variables" warning
@@ -3805,8 +3937,9 @@ function discoverCentralWorkItems(config) {
         }
         if (!prdFilename) {
           // Generate unique PRD filename — check prd/ and prd/archive/ for collisions
-          const prdBase = vars.project_name_lower + '-' + dateStamp();
+          const prdBase = vars.project_filename_slug + '-' + dateStamp();
           prdFilename = prdBase + '.json';
+          shared.sanitizePath(prdFilename, PRD_DIR);
           const prdExisting = new Set([
             ...prdFiles,
             ...safeReadDir(path.join(PRD_DIR, 'archive')).filter(f => f.endsWith('.json')),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1807",
+  "version": "0.1.1809",
   "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/plan-to-prd.md

@@ -14,6 +14,7 @@ A user has provided a plan. Analyze it against the codebase and produce a struct
 ## Instructions
 
 1. **Read the plan carefully** — understand the goals, scope, and requirements
+   - If the plan declares `Project: <name>` (including `**Project:** <name>`), the engine has resolved `{{project_name}}` from that declaration. Preserve `{{project_name}}` for the top-level `project`, default item `project`, filename, and implementation framing; do not let contextual mentions of another product or repository override it.
 2. **Check for an existing PRD** — if the engine provides `existing_prd_json` below, a PRD already exists for this plan. See "Reusing an Existing PRD" section for how to preserve item IDs and done statuses. If no existing PRD is provided, this is a fresh run — all items start as `"missing"`.
 3. **Explore the codebase** at `{{project_path}}` — understand the existing structure to write accurate descriptions and acceptance criteria. Do NOT use observations about existing PRs or partial work to set item statuses — status is determined only by existing PRD items (step 2), not codebase state
 4. **Break the plan into discrete, implementable items** — each should be a single PR's worth of work, with enough detail for another agent to implement it directly
@@ -47,7 +48,7 @@ This file is NOT checked into the repo. The engine reads it on every tick and di
       "id": "P-<uuid>",
       "name": "Short feature name",
       "description": "What needs to be built and why",
-      "project": "ProjectName",
+      "project": "{{project_name}}",
       "status": "missing",
       "estimated_complexity": "small|medium|large",
       "priority": "high|medium|low",
@@ -86,7 +87,7 @@ Rules for items:
 - IDs must be `P-<uuid>` format (e.g. `P-a3f9b2c1`) — globally unique, never sequential
 - **`status` is `"missing"` for new items** — do not set `done`, `complete`, `implemented`, or any other value based on codebase observations. The only exception is when reusing an existing PRD (see below) — items already `"done"` in the existing PRD carry forward as `"done"`. Pre-setting any other status on new items causes them to be silently skipped by the engine.
 - **Do NOT include a "verify" or "test" or "integration test" item** — the engine automatically creates a verify task when all PRD items are done. Adding one manually creates a duplicate that blocks plan completion.
-- **`project` field is REQUIRED** — set it to the project name where the code changes go (e.g., `"OfficeAgent"`, `"office-bohemia"`). Cross-repo plans must route each item to the correct project. The engine materializes items into that project's work queue.
+- **`project` field is REQUIRED** — set it to the project name where the code changes go (e.g., `"OfficeAgent"`, `"office-bohemia"`). If the plan declares a single project, every item must use `{{project_name}}`; contextual mentions of another repo/product must not override it. Cross-repo plans must route each item to the correct project. The engine materializes items into that project's work queue.
 - `depends_on` lists IDs of items that must be done first
 - Keep descriptions actionable — name the files, functions, patterns, or integration points the implementing agent should touch whenever the plan makes them clear
 - Include `acceptance_criteria` so reviewers know when it's done