@yemi33/minions 0.1.1874 → 0.1.1875

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1875 (2026-05-11)
+
+### Features
+- real multi-project plan + PRD support
+
 ## 0.1.1874 (2026-05-11)
 
 ### Fixes

package/dashboard/js/render-plans.js

@@ -16,7 +16,7 @@ function openCreatePlanModal() {
   document.getElementById('modal-body').innerHTML =
     '<div style="display:flex;flex-direction:column;gap:10px">' +
       '<label style="color:var(--text);font-size:var(--text-md)">Title <input id="plan-new-title" style="' + inputStyle + '" placeholder="e.g. Add user authentication with JWT"></label>' +
-      '<label style="color:var(--text);font-size:var(--text-md)">Project <select id="plan-new-project" style="' + inputStyle + '"><option value="">Auto</option>' + projOpts + '</select></label>' +
+      '<label style="color:var(--text);font-size:var(--text-md)">Project <select id="plan-new-project" style="' + inputStyle + '"><option value="">Multiple / cross-repo (agent routes per item)</option>' + projOpts + '</select><span style="display:block;font-size:10px;color:var(--muted);margin-top:2px">Pick a project to scope every item to one repo. Leave on cross-repo for plans that span multiple projects.</span></label>' +
       '<label style="color:var(--text);font-size:var(--text-md)">Plan Content <textarea id="plan-new-content" rows="12" style="' + inputStyle + ';resize:vertical;font-family:monospace;font-size:12px" placeholder="Write your plan in markdown...\n\nDescribe what needs to be built, the approach, requirements, and any constraints.\n\nThe squad will convert this into a PRD with structured work items."></textarea></label>' +
       '<div style="font-size:11px;color:var(--muted)">After creating, click Execute on the plan card to have an agent convert it into a PRD with work items.</div>' +
       '<div style="display:flex;justify-content:flex-end;gap:8px;margin-top:4px">' +

package/dashboard.js

@@ -516,22 +516,53 @@ function findWorkItemsTargetById(id, source, projects = PROJECTS) {
 
 function buildPlanWorkItem(body, projects = PROJECTS, options = {}) {
   if (!body?.title || !String(body.title).trim()) return { error: 'title is required' };
-  const target = resolveWorkItemsCreateTarget(body.project, projects);
+
+  // Multi-project: body.project may be an array. Each entry must resolve to a
+  // known project; ≥2 valid entries trigger cross-repo mode (WI lands in central,
+  // _targetProjects records the list, description gains an explicit directive so
+  // the plan agent writes a header-less plan and plan-to-prd routes per item).
+  const rawProject = body.project;
+  let targetProjects = null;
+  let singleProjectInput = rawProject;
+  if (Array.isArray(rawProject)) {
+    const names = [];
+    for (const entry of rawProject) {
+      const t = resolveWorkItemsCreateTarget(entry, projects);
+      if (t.error) return { error: t.error };
+      if (t.project?.name && !names.includes(t.project.name)) names.push(t.project.name);
+    }
+    if (names.length > 1) {
+      targetProjects = names;
+      singleProjectInput = '';
+    } else {
+      singleProjectInput = names[0] || '';
+    }
+  }
+
+  const target = resolveWorkItemsCreateTarget(singleProjectInput, projects);
   if (target.error) return { error: target.error };
   let now = options.now ? new Date(options.now) : new Date();
   if (!Number.isFinite(now.getTime())) now = new Date();
+
+  let description = body.description || '';
+  if (targetProjects) {
+    const prefix = `**Target Projects:** ${targetProjects.join(', ')}\n\nThis is a cross-repo plan. In the plan markdown, omit the \`**Project:**\` header (or leave it blank) so the plan-to-prd step can route each PRD item to the correct project via per-item \`project\` fields.\n\n---\n\n`;
+    description = prefix + description;
+  }
+
   const item = {
     id: options.id || ('W-' + shared.uid()),
     title: body.title,
     type: 'plan',
     priority: body.priority || 'high',
-    description: body.description || '',
+    description,
     status: WI_STATUS.PENDING,
     created: now.toISOString(),
     createdBy: 'dashboard',
     branchStrategy: body.branch_strategy || body.branchStrategy || 'parallel',
   };
   if (target.project) item.project = target.project.name;
+  if (targetProjects) item._targetProjects = targetProjects;
   if (body.agent) item.agent = body.agent;
   return { item, id: item.id };
 }
@@ -7082,7 +7113,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/notes-save', desc: 'Save edited notes.md content', params: 'content, file?', handler: handleNotesSave },
 
     // Plans
-    { method: 'POST', path: '/api/plan', desc: 'Create a plan work item that chains to PRD on completion', params: 'title, description?, priority?, project?, agent?, branch_strategy? or branchStrategy?', handler: handlePlanCreate },
+    { method: 'POST', path: '/api/plan', desc: 'Create a plan work item that chains to PRD on completion', params: 'title, description?, priority?, project? (string OR array for cross-repo plans), agent?, branch_strategy? or branchStrategy?', handler: handlePlanCreate },
     { method: 'GET', path: '/api/plans', desc: 'List plan files (.md drafts + .json PRDs)', handler: handlePlansList },
     { method: 'POST', path: '/api/plans/trigger-verify', desc: 'Manually trigger verification for a completed plan', params: 'file', handler: handlePlansTriggerVerify },
     { method: 'POST', path: '/api/plans/approve', desc: 'Approve a plan for execution', params: 'file, approvedBy?', handler: handlePlansApprove },

package/engine/lifecycle.js

@@ -157,11 +157,28 @@ function checkPlanCompletion(meta, config) {
     return data;
   });
 
-  // Resolve the primary project for writing new work items (PR, verify)
+  // Resolve the primary project for writing new work items (PR, verify).
+  // Multi-project plans (no plan.project) derive primary from the done items —
+  // the project with the most completed items hosts the verify WI; its description
+  // already enumerates worktrees for every project so the agent verifies cross-repo.
   const projectName = plan.project;
-  const primaryProject = projectName
+  let primaryProject = projectName
     ? shared.resolveProjectSource(projectName, projects, { allowCentral: false }).project
     : (projects.length === 1 ? projects[0] : null);
+  if (!primaryProject && doneItems.length > 0) {
+    const counts = new Map();
+    for (const wi of doneItems) {
+      if (!wi.project) continue;
+      counts.set(wi.project, (counts.get(wi.project) || 0) + 1);
+    }
+    if (counts.size > 0) {
+      const [topName] = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+      primaryProject = shared.resolveProjectSource(topName, projects, { allowCentral: false }).project;
+      if (primaryProject) {
+        log('info', `Plan ${planFile}: multi-project — verify WI routed to "${primaryProject.name}" (${counts.get(topName)}/${doneItems.length} done items)`);
+      }
+    }
+  }
   if (!primaryProject) {
     log('warn', `Plan ${planFile}: no primary project found — skipping PR/verify creation`);
     return;
@@ -190,32 +207,19 @@ function checkPlanCompletion(meta, config) {
     }
   }
 
-  // 4. Create verification work item (build, test, start webapp, write testing guide)
-  // Only one verify per PRD — skip if pending/dispatched, re-open if done/failed (PRD was modified)
-  const existingVerify = allWorkItems.find(w => w.sourcePlan === planFile && w.itemType === 'verify');
-  if (isActiveVerify(existingVerify)) {
-    log('info', `Plan ${planFile}: verify WI ${existingVerify.id} already ${existingVerify.status} — skipping`);
-  } else if (isReopenableVerify(existingVerify) && doneItems.length > 0) {
-    const verifyProject = existingVerify.project || projectName;
-    const vProject = shared.resolveProjectSource(verifyProject, projects, { allowCentral: false }).project || primaryProject;
-    const vWiPath = shared.projectWorkItemsPath(vProject);
-    let reopenedVerify = false;
-    mutateWorkItems(vWiPath, items => {
-      const v = items.find(w => w.id === existingVerify.id);
-      if (isReopenableVerify(v)) {
-        shared.reopenWorkItem(v);
-        reopenedVerify = true;
-      }
-    });
-    if (reopenedVerify) log('info', `Re-opened verification work item ${existingVerify.id} for modified plan ${planFile}`);
-  } else if (!existingVerify && doneItems.length > 0) {
-    const verifyId = 'PL-' + shared.uid();
+  // 4. Create verification work items — one per touched project (project with
+  // active PRs linked to this plan's done items). Each project's verify agent
+  // works in its own worktree on its own build/test cycle, in parallel.
+  // Single-project plans behave as before (one verify WI). Cross-repo plans
+  // fan out so each repo gets its own dedicated verification run.
+  if (doneItems.length > 0) {
     const planSlug = planFile.replace('.json', '');
+    const isSharedBranch = plan.branch_strategy === 'shared-branch' && plan.feature_branch;
 
-    // Group PRs by project — one worktree per project with all branches merged in
-    const projectPrs = {}; // projectName -> { project, prs: [], mainBranch }
+    // Group active PRs by project — only projects with PRs from this plan get a verify WI
+    const projectPrs = {};
+    const prLinks = getPrLinks();
     for (const p of projects) {
-      const prLinks = getPrLinks();
       const prs = (safeJson(shared.projectPrPath(p)) || [])
         .filter(pr => {
           const linkedIds = prLinks[pr.id] || [];
@@ -226,118 +230,160 @@ function checkPlanCompletion(meta, config) {
       }
     }
 
-    // Shared-branch plans already have all changes on a single feature branch — no merge needed
-    const isSharedBranch = plan.branch_strategy === 'shared-branch' && plan.feature_branch;
+    // Fallback: no PRs surfaced (e.g., items completed without PR records, or
+    // legacy state). Verify the primary project so the plan still gets verified.
+    const touchedProjects = Object.keys(projectPrs).length > 0
+      ? Object.entries(projectPrs)
+      : [[primaryProject.name, { project: primaryProject, prs: [], mainBranch: shared.resolveMainBranch(primaryProject.localPath, primaryProject.mainBranch) }]];
+
+    const otherProjectNames = (current) => touchedProjects.map(([n]) => n).filter(n => n !== current);
+    let createdAny = false;
+    let reopenedAny = false;
+
+    for (const [projName, { project: p, prs, mainBranch }] of touchedProjects) {
+      // Per-project existing verify lookup. Legacy single-WI plans may have
+      // existingVerify.project unset; match those against the primary project name.
+      const existingVerify = allWorkItems.find(w =>
+        w.sourcePlan === planFile && w.itemType === 'verify' &&
+        (w.project === projName || (!w.project && projName === primaryProject.name)));
+
+      if (isActiveVerify(existingVerify)) {
+        log('info', `Plan ${planFile}: verify WI ${existingVerify.id} for ${projName} already ${existingVerify.status} — skipping`);
+        continue;
+      }
+
+      if (isReopenableVerify(existingVerify)) {
+        const verifyProject = existingVerify.project || projName;
+        const vProject = shared.resolveProjectSource(verifyProject, projects, { allowCentral: false }).project || p;
+        const vWiPath = shared.projectWorkItemsPath(vProject);
+        let reopened = false;
+        mutateWorkItems(vWiPath, items => {
+          const v = items.find(w => w.id === existingVerify.id);
+          if (isReopenableVerify(v)) {
+            shared.reopenWorkItem(v);
+            reopened = true;
+          }
+        });
+        if (reopened) {
+          reopenedAny = true;
+          log('info', `Re-opened verification work item ${existingVerify.id} for ${projName} (modified plan ${planFile})`);
+        }
+        continue;
+      }
 
-    // Build per-project checkout commands: one worktree, merge all PR branches into it
-    const checkoutBlocks = Object.entries(projectPrs).map(([name, { project: p, prs, mainBranch }]) => {
+      // Build per-project setup block
+      let checkoutBlock;
+      let wtPath;
       if (isSharedBranch) {
+        wtPath = `${p.localPath}/../worktrees/verify-${projName}-${planSlug}`;
         const featureBranch = plan.feature_branch;
-        const wtPath = `${p.localPath}/../worktrees/verify-${name}-${planSlug}`;
-        const lines = [
-          `# ${name} — shared-branch: use existing feature branch directly`,
+        checkoutBlock = [
+          `# ${projName} — shared-branch: use existing feature branch directly`,
           `cd "${p.localPath.replace(/\\/g, '/')}"`,
           `git fetch origin "${featureBranch}"`,
           `git worktree add "${wtPath}" "origin/${featureBranch}" 2>/dev/null || (cd "${wtPath}" && git checkout "${featureBranch}" && git pull origin "${featureBranch}")`,
-        ];
-        return lines.join('\n');
+        ].join('\n');
+      } else {
+        wtPath = `${p.localPath}/../worktrees/verify-${projName}-${planSlug}-${shared.uid()}`;
+        const branches = prs.map(pr => pr.branch).filter(Boolean);
+        checkoutBlock = [
+          `# ${projName} — merge ${branches.length} PR branch(es) into one worktree`,
+          `cd "${p.localPath.replace(/\\/g, '/')}"`,
+          branches.length > 0
+            ? `git fetch origin ${branches.map(b => `"${b}"`).join(' ')} "${mainBranch}"`
+            : `git fetch origin "${mainBranch}"`,
+          `git worktree add "${wtPath}" "origin/${mainBranch}" 2>/dev/null || (cd "${wtPath}" && git checkout "${mainBranch}" && git pull origin "${mainBranch}")`,
+          `cd "${wtPath}"`,
+          ...branches.map(b => `git merge "origin/${b}" --no-edit  # ${prs.find(pr => pr.branch === b)?.id || b}`),
+        ].join('\n');
       }
-      const wtPath = `${p.localPath}/../worktrees/verify-${name}-${planSlug}-${shared.uid()}`;
-      const branches = prs.map(pr => pr.branch).filter(Boolean);
-      const lines = [
-        `# ${name} — merge ${branches.length} PR branch(es) into one worktree`,
-        `cd "${p.localPath.replace(/\\/g, '/')}"`,
-        `git fetch origin ${branches.map(b => `"${b}"`).join(' ')} "${mainBranch}"`,
-        `git worktree add "${wtPath}" "origin/${mainBranch}" 2>/dev/null || (cd "${wtPath}" && git checkout "${mainBranch}" && git pull origin "${mainBranch}")`,
-        `cd "${wtPath}"`,
-        ...branches.map(b => `git merge "origin/${b}" --no-edit  # ${prs.find(pr => pr.branch === b)?.id || b}`),
-      ];
-      return lines.join('\n');
-    }).join('\n\n');
-
-    // Build completed items summary with acceptance criteria
-    const itemsWithCriteria = doneItems.map(w => {
-      const planItem = plan.missing_features?.find(f => f.id === w.id);
-      const criteria = (planItem?.acceptance_criteria || []).map(c => `  - ${c}`).join('\n');
-      return `### ${w.id}: ${(w.title || 'Untitled').replace('Implement: ', '')}\n${criteria ? '**Acceptance Criteria:**\n' + criteria : ''}`;
-    }).join('\n\n');
-
-    const prSummary = uniquePrs.map(pr =>
-      `- ${pr.id}: ${pr.title || ''} (branch: \`${pr.branch || '?'}\`) ${pr.url || ''}`
-    ).join('\n');
-
-    // List projects and their worktree paths for the agent
-    const projectWorktrees = Object.entries(projectPrs).map(([name, { project: p }]) =>
-      `- **${name}**: \`${p.localPath}/../worktrees/verify-${planSlug}\``
-    ).join('\n');
 
-    const sharedBranchNote = isSharedBranch
-      ? `\n**Shared-branch plan** — all changes are already on branch \`${plan.feature_branch}\`. Use this branch directly for the E2E PR instead of creating a new \`e2e/\` branch. Check if a PR already exists for this branch before creating one.\n`
-      : '';
-
-    const description = [
-      `Verification task for completed plan \`${planFile}\`.`,
-      sharedBranchNote,
-      `## Projects & Worktrees`,
-      ``,
-      `Each project gets ONE worktree with all PR branches merged in:`,
-      projectWorktrees,
-      ``,
-      `## Setup Commands`,
-      ``,
-      `\`\`\`bash`,
-      checkoutBlocks,
-      `\`\`\``,
-      ``,
-      `If any merge conflicts occur, resolve them (prefer the PR branch changes).`,
-      `After setup, build and test from the worktree paths above.`,
-      ``,
-      `## Completed Items`,
-      ``,
-      itemsWithCriteria,
-      ``,
-      `## Pull Requests`,
-      ``,
-      prSummary,
-    ].join('\n');
-
-    let createdVerify = false;
-    let reopenedVerifyId = null;
-    mutateWorkItems(wiPath, workItems => {
-      const v = workItems.find(w => w.sourcePlan === planFile && w.itemType === 'verify');
-      if (v) {
-        if (isReopenableVerify(v)) {
-          shared.reopenWorkItem(v);
-          reopenedVerifyId = v.id;
+      // Items scoped to this project (fall back to all done items if items lack project field — single-project plans)
+      const projItems = doneItems.filter(w => w.project === projName);
+      const itemsForProject = projItems.length > 0 ? projItems : doneItems;
+      const itemsWithCriteria = itemsForProject.map(w => {
+        const planItem = plan.missing_features?.find(f => f.id === w.id);
+        const criteria = (planItem?.acceptance_criteria || []).map(c => `  - ${c}`).join('\n');
+        return `### ${w.id}: ${(w.title || 'Untitled').replace('Implement: ', '')}\n${criteria ? '**Acceptance Criteria:**\n' + criteria : ''}`;
+      }).join('\n\n');
+
+      const prSummary = prs.map(pr =>
+        `- ${pr.id}: ${pr.title || ''} (branch: \`${pr.branch || '?'}\`) ${pr.url || ''}`
+      ).join('\n') || '_No PRs surfaced for this project — verify the worktree directly._';
+
+      const sharedBranchNote = isSharedBranch
+        ? `\n**Shared-branch plan** — all changes are already on branch \`${plan.feature_branch}\`. Use this branch directly for the E2E PR instead of creating a new \`e2e/\` branch. Check if a PR already exists for this branch before creating one.\n`
+        : '';
+
+      const siblings = otherProjectNames(projName);
+      const crossRepoNote = touchedProjects.length > 1
+        ? `\n**Cross-repo plan** — this verify task covers **${projName}** only. Sibling verify tasks run in parallel for: ${siblings.join(', ')}. Build/test this project's worktree independently.\n`
+        : '';
+
+      const description = [
+        `Verification task for completed plan \`${planFile}\` — project: **${projName}**.`,
+        crossRepoNote,
+        sharedBranchNote,
+        `## Worktree`,
+        ``,
+        `- **${projName}**: \`${wtPath}\``,
+        ``,
+        `## Setup Commands`,
+        ``,
+        `\`\`\`bash`,
+        checkoutBlock,
+        `\`\`\``,
+        ``,
+        `If any merge conflicts occur, resolve them (prefer the PR branch changes).`,
+        `After setup, build and test from the worktree path above.`,
+        ``,
+        `## Completed Items`,
+        ``,
+        itemsWithCriteria,
+        ``,
+        `## Pull Requests`,
+        ``,
+        prSummary,
+      ].join('\n');
+
+      const verifyId = 'PL-' + shared.uid();
+      const vWiPath = shared.projectWorkItemsPath(p);
+      let created = false;
+      mutateWorkItems(vWiPath, workItems => {
+        // Re-check under lock to prevent races
+        if (workItems.some(w => w.sourcePlan === planFile && w.itemType === 'verify' && (w.project === projName || (!w.project && projName === primaryProject.name)))) {
+          return workItems;
         }
-        return workItems;
-      }
-      workItems.push({
-        id: verifyId,
-        title: `Verify plan: ${(plan.plan_summary || planFile).slice(0, 80)}`,
-        type: 'verify',
-        priority: 'high',
-        description,
-        status: WI_STATUS.PENDING,
-        created: ts(),
-        createdBy: 'engine:plan-verification',
-        sourcePlan: planFile,
-        itemType: 'verify',
-        project: projectName,
+        workItems.push({
+          id: verifyId,
+          title: touchedProjects.length > 1
+            ? `Verify plan (${projName}): ${(plan.plan_summary || planFile).slice(0, 70)}`
+            : `Verify plan: ${(plan.plan_summary || planFile).slice(0, 80)}`,
+          type: 'verify',
+          priority: 'high',
+          description,
+          status: WI_STATUS.PENDING,
+          created: ts(),
+          createdBy: 'engine:plan-verification',
+          sourcePlan: planFile,
+          itemType: 'verify',
+          project: projName,
+        });
+        created = true;
       });
-      createdVerify = true;
-    });
-    if (createdVerify) {
-      log('info', `Created verification work item ${verifyId} for plan ${planFile}`);
+      if (created) {
+        createdAny = true;
+        log('info', `Created verification work item ${verifyId} for plan ${planFile} → ${projName}`);
+      }
+    }
 
-      // Teams notification for verify creation — non-blocking
+    if (createdAny) {
       try {
         const teams = require('./teams');
         teams.teamsNotifyPlanEvent({ name: plan.plan_summary || planFile, file: planFile }, 'verify-created').catch(() => {});
       } catch {}
-    } else if (reopenedVerifyId) {
-      log('info', `Re-opened verification work item ${reopenedVerifyId} for modified plan ${planFile}`);
     }
+    if (reopenedAny) log('info', `Plan ${planFile}: re-opened verify WI(s) for modified plan`);
   }
 
   // Archive deferred until verify completes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1874",
+  "version": "0.1.1875",
   "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

@@ -88,6 +88,14 @@ Rules for items:
 - **`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"`). 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.
+  - **Cross-repo plans:** when the plan body does NOT declare `**Project:**` (or declares it empty), `{{project_name}}` is unset. In that case, set each item's `project` to the actual repo where its code changes belong, and omit the top-level `"project"` field (or set it to `""`). Example:
+    ```json
+    "missing_features": [
+      { "id": "P-aaa1", "name": "API endpoint", "project": "backend-service", ... },
+      { "id": "P-bbb2", "name": "UI client",    "project": "web-dashboard",   ... }
+    ]
+    ```
+    The engine routes each item to that project's `work-items.json`. The verify task at plan completion picks the project with the most completed items and runs cross-repo verification from there.
 - `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