@yemi33/minions 0.1.1678 → 0.1.1680

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1680 (2026-05-02)
+
+### Other
+- Improve agent playbook accuracy
+
+## 0.1.1679 (2026-05-02)
+
+### Fixes
+-  preserve PR context for linked fix work items
+
 ## 0.1.1678 (2026-05-02)
 
 ### Fixes

package/dashboard.js

@@ -110,6 +110,22 @@ function normalizePrMetadata(metadata) {
   };
 }
 
+function getWorkItemPrRef(input) {
+  if (!input || typeof input !== 'object') return null;
+  return input.targetPr || input.pr || input.prId || input.prNumber || input.pullRequest || input.sourcePr || input.prUrl || null;
+}
+
+function copyWorkItemPrFields(item, input, pr = null) {
+  const prRef = getWorkItemPrRef(input);
+  if (!prRef && !pr) return;
+  const prNumber = pr ? shared.getPrNumber(pr) : shared.getPrNumber(prRef);
+  item.targetPr = pr?.id || prRef;
+  item.pr_id = pr?.id || (typeof prRef === 'string' ? prRef : '');
+  if (prNumber != null) item.prNumber = prNumber;
+  if (pr?.branch || input.prBranch) item.prBranch = pr?.branch || input.prBranch;
+  if (pr?.title || input.prTitle) item.prTitle = pr?.title || input.prTitle;
+  if (pr?.url || input.prUrl) item.prUrl = pr?.url || input.prUrl;
+}
 function linkPullRequestForTracking({ url, title, project: projectName, autoObserve, context, workItemId }, config = CONFIG, options = {}) {
   if (!url) {
     const err = new Error('url required');
@@ -1395,6 +1411,8 @@ async function executeCCActions(actions) {
           const workType = routing.normalizeWorkType(action.workType || (action.type !== 'dispatch' ? action.type : WORK_TYPE.IMPLEMENT), WORK_TYPE.IMPLEMENT);
           const id = 'W-' + shared.uid();
           const project = action.project || '';
+          const prRef = getWorkItemPrRef(action);
+          let linkedPr = null;
 
           // Strict project resolution. Silent fallback to PROJECTS[0] when the model named an unknown
           // project caused work items to land in the wrong repo. Now: unknown name → error; ambiguous
@@ -1408,6 +1426,18 @@ async function executeCCActions(actions) {
               results.push({ type: action.type, error: `Project "${project}" not found. Known projects: ${known}` });
               break;
             }
+          } else if (prRef) {
+            const allPrs = getPullRequests().filter(p => !p._ghost);
+            linkedPr = shared.findPrRecord(allPrs, prRef) || null;
+            if (linkedPr?._project && linkedPr._project !== 'central') {
+              targetProject = PROJECTS.find(p => p.name?.toLowerCase() === String(linkedPr._project).toLowerCase()) || null;
+            }
+            if (!targetProject && PROJECTS.length > 1) {
+              results.push({ type: action.type, error: `project field is required when ${PROJECTS.length} projects are configured: ${PROJECTS.map(p => p.name).join(', ')}` });
+              break;
+            } else if (!targetProject && PROJECTS.length === 1) {
+              targetProject = PROJECTS[0];
+            }
           } else if (PROJECTS.length > 1) {
             results.push({ type: action.type, error: `project field is required when ${PROJECTS.length} projects are configured: ${PROJECTS.map(p => p.name).join(', ')}` });
             break;
@@ -1416,6 +1446,16 @@ async function executeCCActions(actions) {
           }
           // PROJECTS.length === 0 → targetProject stays null, falls back to root work-items.json (existing behavior).
 
+          if (prRef && !linkedPr && targetProject) {
+            const projectPrs = shared.safeJson(shared.projectPrPath(targetProject)) || [];
+            shared.normalizePrRecords(projectPrs, targetProject);
+            linkedPr = shared.findPrRecord(projectPrs, prRef, targetProject) || null;
+          }
+          if (prRef && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST) && !linkedPr) {
+            results.push({ type: action.type, error: `PR not found: ${prRef}` });
+            break;
+          }
+
           const wiPath = targetProject ? shared.projectWorkItemsPath(targetProject) : path.join(MINIONS_DIR, 'work-items.json');
 
           // Promote `agent` (singular) → `agents` (array). Models emit either shape and the prior code
@@ -1438,14 +1478,16 @@ async function executeCCActions(actions) {
           const isOneShot = action.oneShot === true || (action.oneShot !== false && ccOneShotTypes.has(workType));
           shared.mutateJsonFileLocked(wiPath, items => {
             if (!Array.isArray(items)) items = [];
-            items.push({
+            const item = {
               id, title: action.title, type: workType,
               priority: action.priority || 'medium', description: action.description || '',
               status: WI_STATUS.PENDING, created: new Date().toISOString(),
-              createdBy: 'command-center', project,
+              createdBy: 'command-center', project: targetProject?.name || project,
               ...(agentHints.length ? { preferred_agent: agentHints[0], agents: agentHints } : {}),
               ...(isOneShot ? { oneShot: true } : {}),
-            });
+            };
+            copyWorkItemPrFields(item, action, linkedPr);
+            items.push(item);
             return items;
           }, { defaultValue: [] });
           results.push({ type: action.type, id, ok: true });
@@ -2740,6 +2782,7 @@ const server = http.createServer(async (req, res) => {
       if (body.acceptanceCriteria) item.acceptanceCriteria = body.acceptanceCriteria;
       if (body.skipPr) item.skipPr = true;
       if (body.oneShot) item.oneShot = true;
+      copyWorkItemPrFields(item, body);
       let dupId = null;
       mutateJsonFileLocked(wiPath, (items) => {
         if (!Array.isArray(items)) items = [];

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-02T05:22:33.108Z"
+  "cachedAt": "2026-05-02T13:32:18.770Z"
 }

package/engine/playbook.js

@@ -628,9 +628,13 @@ function selectPlaybook(workType, item) {
   if (workType === WORK_TYPE.IMPLEMENT || workType === WORK_TYPE.IMPLEMENT_LARGE) {
     return 'implement';
   }
-  if (workType === WORK_TYPE.REVIEW && !item?._pr && !item?.pr_id) {
+  const hasPrContext = !!(item?._pr || item?.pr_id || item?.targetPr || item?.sourcePr || item?.pr);
+  if (workType === WORK_TYPE.REVIEW && !hasPrContext) {
     return 'work-item';
   }
+  if (workType === WORK_TYPE.FIX && hasPrContext) {
+    return 'fix';
+  }
   const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask', 'verify', 'decompose', 'docs', 'meeting-investigate', 'meeting-debate', 'meeting-conclude'];
   return typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
 }

package/engine.js

@@ -2592,6 +2592,14 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     worktree_path: path.resolve(root, config.engine?.worktreeRoot || '../worktrees', `${branchName}`),
     commit_message: item.commitMessage || `feat: ${item.title || item.id}`,
     notes_content: '',
+    pr_id: item.pr_id || item._pr || item.targetPr || item.sourcePr || item.pr || '',
+    pr_number: item.prNumber || item.pr_number || '',
+    pr_title: item.pr_title || item.prTitle || '',
+    pr_branch: item.pr_branch || item.prBranch || '',
+    pr_author: item.pr_author || item.prAuthor || '',
+    pr_url: item.pr_url || item.prUrl || '',
+    reviewer: item.reviewer || 'Reviewer',
+    review_note: item.review_note || item.reviewNote || item.description || item.title || 'See PR thread comments',
   };
   const cpResult = buildWorkItemDispatchVars(item, vars, config, {
     worktreePath: vars.worktree_path || root,
@@ -2612,6 +2620,38 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
   };
 }
 
+function getWorkItemPrRef(item) {
+  if (!item || typeof item !== 'object') return null;
+  return item.targetPr || item.pr || item.pr_id || item.sourcePr || item.pullRequest || item.prUrl || item.prNumber || null;
+}
+
+function resolveWorkItemPrRecord(item, project) {
+  if (!project) return null;
+  const prRef = getWorkItemPrRef(item);
+  if (!prRef) return null;
+  const prs = safeJson(projectPrPath(project)) || [];
+  shared.normalizePrRecords(prs, project);
+  return shared.findPrRecord(prs, prRef, project);
+}
+
+function withWorkItemPrContext(item, pr) {
+  if (!pr) return item;
+  const prNumber = shared.getPrNumber(pr);
+  return {
+    ...item,
+    _pr: pr.id,
+    pr_id: pr.id,
+    targetPr: item.targetPr || pr.id,
+    prNumber: prNumber ?? item.prNumber,
+    pr_number: prNumber ?? item.pr_number,
+    pr_title: pr.title || item.pr_title || item.prTitle || '',
+    pr_branch: pr.branch || item.pr_branch || item.prBranch || '',
+    pr_author: pr.agent || item.pr_author || item.prAuthor || '',
+    pr_url: pr.url || item.pr_url || item.prUrl || '',
+    reviewer: item.reviewer || 'Reviewer',
+    review_note: item.review_note || item.reviewNote || item.description || item.title || 'See PR thread comments',
+  };
+}
 function projectFromDispatchMeta(metaProject, config) {
   if (!metaProject) return null;
   const projects = getProjects(config);
@@ -2775,8 +2815,17 @@ function discoverFromWorkItems(config, project) {
       skipped.noAgent++; continue;
     }
 
+    const linkedPr = resolveWorkItemPrRecord(item, project);
+    const promptItem = linkedPr ? withWorkItemPrContext(item, linkedPr) : item;
+    const prBranch = linkedPr?.branch || '';
+    const isPrTargeted = !!(linkedPr && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST));
+    if (!linkedPr && getWorkItemPrRef(item) && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST)) {
+      if (item._pendingReason !== 'pr_not_found') { item._pendingReason = 'pr_not_found'; needsWrite = true; }
+      log('warn', `Work item ${item.id} references PR ${getWorkItemPrRef(item)} but no tracked PR record was found`);
+      continue;
+    }
     const isShared = item.branchStrategy === 'shared-branch' && item.featureBranch;
-    const branchName = isShared ? item.featureBranch : (item.branch || `work/${item.id}`);
+    const branchName = isPrTargeted && prBranch ? prBranch : (isShared ? item.featureBranch : (item.branch || `work/${item.id}`));
     const deferredAgentResolution = agentId === routing.ANY_AGENT;
 
     // Branch mutex: skip if target branch is locked by an active dispatch
@@ -2789,7 +2838,7 @@ function discoverFromWorkItems(config, project) {
     }
 
     const promptAgentId = deferredAgentResolution ? reservedAgentId : agentId;
-    const promptResult = renderProjectWorkItemPromptForAgent(item, workType, promptAgentId, config, project, root, branchName);
+    const promptResult = renderProjectWorkItemPromptForAgent(promptItem, workType, promptAgentId, config, project, root, branchName);
     if (promptResult.needsReview) {
       log('warn', `Work item ${item.id} exceeded 3 checkpoint-resumes — marking as failed for manual intervention`);
       item.status = WI_STATUS.FAILED;
@@ -2827,7 +2876,7 @@ function discoverFromWorkItems(config, project) {
       agentRole: config.agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent',
       task: `[${project?.name || 'project'}] ${item.title || item.description?.slice(0, 80) || item.id}`,
       prompt,
-      meta: { dispatchKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(item.branchStrategy === 'shared-branch' && item.featureBranch), item, project: { name: project?.name, localPath: project?.localPath }, deferAgentResolution: deferredAgentResolution }
+      meta: { dispatchKey: key, source: 'work-item', branch: branchName, branchStrategy: item.branchStrategy || 'parallel', useExistingBranch: !!(isPrTargeted || (item.branchStrategy === 'shared-branch' && item.featureBranch)), item: promptItem, project: { name: project?.name, localPath: project?.localPath }, deferAgentResolution: deferredAgentResolution, ...(linkedPr ? { pr: linkedPr } : {}) }
     });
 
     setCooldown(key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1678",
+  "version": "0.1.1680",
   "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/fix.md

@@ -17,6 +17,14 @@ Branch: `{{pr_branch}}`
 
 {{review_note}}
 
+## Finding Triage
+
+Before editing, split the feedback into:
+
+- **Blocking findings to fix:** correctness, safety, build/test failure, missing requested behavior, broken compatibility, or review comments explicitly required for approval.
+- **Findings to answer with rationale:** comments where the current approach is intentionally correct, the reviewer misunderstood the code, or the requested change would broaden the PR beyond its purpose.
+- **Non-blocking suggestions:** style, optional refactors, extra docs, or enhancements that are not required for approval. Do not implement these unless they are necessary to resolve a blocking issue.
+
 ## Health Check
 
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{pr_branch}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
@@ -42,6 +50,7 @@ Before pushing, prove the review fix did not break the branch:
 
 - Use the project's source of truth for commands: `CLAUDE.md`, README, package scripts, Makefile, or equivalent build config.
 - Run checks that are relevant to the addressed findings. Prefer the full suite when practical.
+- Capture the exact commands run and meaningful results in the PR comment and completion report.
 - Fix regressions you introduced. If failures are pre-existing or unrelated, capture the evidence and include it in the PR comment.
 - Do not push code that breaks existing tests or the build because of your changes.
 

package/playbooks/implement.md

@@ -34,11 +34,21 @@ Before starting work, run `git status` and verify the worktree is clean and on t
 
 Use subagents only for genuinely parallel, independent tasks (e.g., editing files in unrelated modules simultaneously). For sequential work, single-file edits, searches, and file reads, work directly — do not spawn subagents.
 
+## Context Discovery
+
+Before editing, assemble a small, dependency-aware context pack:
+
+- Read project instructions first (`CLAUDE.md`, README, package scripts, Makefile, or equivalent).
+- Identify candidate files from the task text, existing symbols, comparable implementations, direct imports/callers, and corresponding tests.
+- Read the smallest useful set of files first (usually 5-8). Expand only when a concrete question, failing validation, or missing pattern requires it.
+- For large files, read imports, exported/public entry points, and task-relevant sections before reading the whole file.
+
 ## Delivery Contract
 
 Deliver this as if the user asked you directly in a CLI:
 
 - Understand the requested behavior and relevant acceptance criteria before editing.
+- State the likely files to touch, patterns to follow, and main risks to yourself before making the first code change.
 - Read the smallest useful set of source, tests, docs, and comparable implementations needed to make the change correctly.
 - Follow existing project conventions, including logging, typing, error handling, and test structure.
 - Make the complete change required by the task; do not add unrelated cleanups or speculative improvements.
@@ -55,6 +65,7 @@ Before publishing, prove the change with the repo's own documented checks:
 
 - Use the project's source of truth for commands: `CLAUDE.md`, README, package scripts, Makefile, or equivalent build config.
 - Run the checks that are relevant to this task, including tests that cover the changed behavior. Prefer the full suite when practical.
+- Capture the exact commands run and the meaningful result in the PR description or completion report. Do not summarize validation as "tests passed" without naming what ran.
 - Fix regressions you introduced. If failures are pre-existing or outside the task, capture the evidence and make that explicit in the PR.
 - Do not publish changes with a broken build or failing tests that you introduced.
 

package/playbooks/plan.md

@@ -28,12 +28,14 @@ A user has described a feature they want built. Your job is to create a detailed
 - Map the areas of code that this feature will touch
 - Identify existing patterns, conventions, and extension points
 - Note dependencies and potential conflicts with in-progress work
+- Build a concise context pack before planning: start with 5-15 candidate files from paths, symbols, comparable implementations, imports/callers, and tests; read the smallest useful set (usually 5-8 files) and expand only for specific unknowns
 
 ### 3. Design the Approach
 - Outline the high-level architecture for the feature
 - Identify what needs to be created vs modified
 - Consider edge cases, error handling, and backwards compatibility
 - Note any prerequisites or migrations needed
+- Record non-obvious design decisions with the alternatives considered and why the chosen option best fits existing architecture
 
 ### 4. Break Down into Work Items
 - Decompose into discrete, PR-sized chunks of work

package/playbooks/review.md

@@ -23,7 +23,14 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
    git diff {{main_branch}}...origin/{{pr_branch}}
    ```
 
-2. For each changed file, verify:
+2. Think about deploy risk before commenting:
+   - What user-visible behavior changed?
+   - What dependencies, callers, or tests could be affected?
+   - What security, data-loss, concurrency, or compatibility risks are plausible for this diff?
+
+3. Run or inspect the repo's documented checks when practical. Use `CLAUDE.md`, README, package scripts, Makefile, or equivalent as the command source of truth, and record the exact commands/results in the review body.
+
+4. For each changed file, verify:
    - Does it follow existing patterns?
    - Are file paths and imports correct?
    - Follows the project's logging conventions (check CLAUDE.md)?
@@ -31,14 +38,19 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
    - Tests cover the important logic?
    - No security issues (injection, unsanitized input)?
 
-3. Do NOT blindly approve. If you find real issues:
+5. Classify findings by ship risk:
+   - **Blocking:** failing checks, security/data-loss risk, broken existing behavior, missing requested behavior, invalid API/schema/data migration, or tests that do not cover changed critical logic.
+   - **Non-blocking:** style preferences, minor refactors, optional documentation, low-risk performance ideas, or additional tests that are useful but not required for safety.
+
+6. Do NOT blindly approve. If you find real blocking issues:
    - Verdict: **REQUEST_CHANGES**
    - List specific issues with file paths and line numbers
    - Describe what needs to change
 
-4. If the code is genuinely ready:
+7. If the code is genuinely ready:
    - Verdict: **APPROVE**
    - Note any minor non-blocking suggestions
+   - Do not request changes for nits, speculative edge cases, or unrelated improvements
 
 ## Post Review — Submit your verdict
 
@@ -55,6 +67,19 @@ Your review body **MUST** start with one of these verdict lines (exactly as show
 Follow the verdict line with your detailed review findings, then sign off:
 - Sign: `Review by Minions ({{agent_name}} — {{agent_role}})`
 
+Use this structure after the verdict:
+
+```markdown
+Automated checks:
+- `<command>`: pass/fail/skipped — short result or reason
+
+Blocking issues:
+- None, or `path:line` — issue and required fix
+
+Non-blocking suggestions:
+- None, or `path:line` — suggestion
+```
+
 After running the command, confirm it succeeded (check the command output for errors). If it fails, retry once.
 
 ## Handling Merge Conflicts

package/playbooks/shared-rules.md

@@ -13,6 +13,8 @@ Treat a Minions assignment like the user typed the same task directly into a cap
 - Optimize for the requested outcome, not for mechanically completing checklist steps.
 - Use judgment to choose the smallest reliable workflow that fully satisfies the task.
 - Read only the context needed to make correct decisions; do not perform broad archaeology unless the task requires it.
+- Build an initial context pack before editing: start from repo docs and team memory, identify 5-15 candidate files by path names, symbols, imports, tests, and comparable implementations, then read the smallest useful pack (usually 5-8 files). Expand beyond that only when a specific gap or failure proves more context is needed.
+- Prefer dependency-aware context over keyword-only searching: when touching a file, also check its direct imports, direct callers when easy to find, and corresponding tests. For small repos, a simple repo map plus targeted search is enough.
 - Validate with the repo's own documented commands and acceptance criteria. If full validation is impossible or pre-existing failures block it, explain that precisely instead of inventing a green result.
 - Prefer direct work over ceremony. Branches, PRs, inbox notes, completion reports/blocks, and status comments exist for traceability; they should not change what "done" means for the user.
 - Safety and observability rules still win: stay in the engine-created worktree, do not self-merge, do not edit engine-managed status files, do not hide failures, and leave enough evidence for the human and engine to track the result.

package/prompts/cc-system.md

@@ -80,8 +80,8 @@ I'll dispatch dallas to fix that bug.
 - `knowledge`: `title`, `content`, and `category` REQUIRED. Valid categories: architecture, conventions, project-notes, build-reports, reviews.
 
 Core action types:
-- **dispatch**: title (REQUIRED), workType, priority (low/medium/high), agents[] or agent (optional — both shapes accepted), project (REQUIRED when multi-project), description
-  workTypes: `explore` (research/report only, NO PR), `ask` (answer/report, NO PR), `implement` (new code, PR REQUIRED), `fix` (bug fix, PR REQUIRED), `review` (code review, NO PR), `test` (tests, PR if new), `verify` (merge/build/maintenance, NO PR)
+- **dispatch**: title (REQUIRED), workType, priority (low/medium/high), agents[] or agent (optional — both shapes accepted), project (REQUIRED when multi-project unless `pr` resolves to a tracked PR), description, pr (optional PR number/id/url for work that targets an existing PR)
+  workTypes: `explore` (research/report only, NO PR), `ask` (answer/report, NO PR), `implement` (new code, PR REQUIRED), `fix` (standalone bug fix creates a PR; include `pr` when fixing review comments/build failures on an existing PR), `review` (code review, NO PR), `test` (tests, PR if new), `verify` (merge/build/maintenance, NO PR)
   If the user wants a design/architecture artifact committed through a PR, dispatch `implement` or `docs` rather than `explore`.
   When the user names a specific agent ("assign this to lambert"), put exactly that one name in `agents` (e.g. `"agents": ["lambert"]`). A single-agent assignment is hard-pinned by the server — it will queue for that agent only and skip the routing table. Use multi-agent arrays only when the user names multiple agents or asks for fan-out.
 - **build-and-test**: pr, project (optional), agent (optional) — Run the build-and-test playbook against a PR. The agent will checkout the PR branch, run the project's build/test commands, and report results. Use when the user asks to "run tests on PR X" or "build PR X" or after a fix to verify nothing regressed.