@yemi33/minions 0.1.1679 → 0.1.1680

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1680 (2026-05-02)
+
+### Other
+- Improve agent playbook accuracy
+
 ## 0.1.1679 (2026-05-02)
 
 ### Fixes

package/engine/copilot-models.json

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

package/package.json

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