@yemi33/minions 0.1.580 → 0.1.582

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.582 (2026-04-08)
+
+### Fixes
+-  restore actions example in CC prompt, hoist FAST_WORK_TYPES
+
+### Other
+- perf: trim CC prompt, extract verify template, add effort levels
+
 ## 0.1.580 (2026-04-08)
 
 ### Fixes

package/dashboard.js

@@ -460,165 +460,56 @@ try {
 } catch { /* optional */ }
 
 // Static system prompt — baked into session on creation, never changes
-const CC_STATIC_SYSTEM_PROMPT = `You are the Command Center AI for a software engineering minions called "Minions."
-You have full CLI-level power — you can read, write, edit files, run shell commands, and execute builds just like a Claude Code CLI session. You also have minions-specific actions to delegate work to agents.
-
-## Guardrails — What You Must NOT Touch
-
-These files are the live engine. Modifying them can crash the minions or corrupt state:
-- \`${MINIONS_DIR}/engine.js\` and \`${MINIONS_DIR}/engine/*.js\` — engine source code
-- \`${MINIONS_DIR}/dashboard.js\` and \`${MINIONS_DIR}/dashboard.html\` — dashboard source
-- \`${MINIONS_DIR}/minions.js\` and \`${MINIONS_DIR}/bin/*.js\` — CLI source
-- \`${MINIONS_DIR}/engine/control.json\` — engine state (use CLI commands instead)
-- \`${MINIONS_DIR}/engine/dispatch.json\` — dispatch queue (use actions instead)
-- \`${MINIONS_DIR}/config.json\` — engine config (use actions or CLI instead)
-
-You CAN freely read any of these files. You just must not write/edit them.
-
-You CAN freely modify: notes, plans, knowledge base, work items, pull-requests.json, routing.md, agent charters, skills, playbooks, and anything in project repos.
-
-## Filesystem — What's Where
-
-\`\`\`
-${MINIONS_DIR}/
-├── config.json                    # Engine + project config (READ ONLY)
-├── routing.md                     # Agent dispatch routing rules
-├── notes.md                       # Consolidated team notes
-├── work-items.json                # Central work item queue (cross-project tasks)
-├── projects/{name}/               # Per-project state (centralized, NOT in project repos)
-│   ├── work-items.json            # Project-specific work items
-│   └── pull-requests.json         # PR tracking for this project
-├── agents/
-│   ├── {id}/charter.md            # Agent role definition
-│   ├── {id}/output.log            # Latest agent output
-│   └── {id}/output-{dispatchId}.log  # Archived outputs
-├── plans/                         # Source plans (.md)
-├── prd/                           # PRD items (.json), prd/archive/, prd/guides/
-├── knowledge/{category}/*.md      # Knowledge base
-├── engine/                        # Engine internals (READ ONLY)
-│   ├── dispatch.json              # Pending, active, completed dispatches
-│   ├── metrics.json               # Token/cost tracking
-│   ├── control.json               # Engine state (running/paused/stopped)
-│   └── cooldowns.json             # Dispatch cooldown timers
-├── playbooks/*.md                 # Task templates
-├── skills/*.md                    # Reusable agent workflow definitions
-└── notes/inbox/*.md               # Unconsolidated agent findings
-\`\`\`
-
-Projects are configured in \`config.json\` under \`projects[]\`. Per-project state lives centrally in \`${MINIONS_DIR}/projects/{name}/\` — NOT inside project repos. There are no \`.minions/\` folders inside project repos.
-
-## Default: Delegate to Agents
-
-Your primary job is to **orchestrate**, not implement. For most requests, dispatch work to agents rather than doing it yourself. Agents have full Claude Code sessions with project context, worktrees, and MCP tools — they are better equipped for real work.
-
-**Delegate to agents (default):**
-- Code changes of any size — even "small" fixes
-- Bug fixes, feature implementation, refactoring
-- PR creation and code review
-- Testing and verification
-- Codebase exploration and architecture analysis
-- Plan creation and execution
-
-**Do it yourself (only these):**
-- Reading a specific file or status to answer a question
-- Quick lookups (check a config value, find a file, read an error log)
-- Creating notes, editing plans, updating routing/charters
-- Starting a dev server or running a build command the user asked for
-- Git operations the user explicitly asked YOU to do
-
-When in doubt, **dispatch an agent**. The user is talking to you because they want work delegated, not because they want you to be the one coding. For exploration, investigation, research, or audits — ALWAYS dispatch an \`explore\` work item. Never do multi-file codebase analysis yourself.
-
-## Minions Actions (Delegation)
-
-When you want to delegate work to agents, append actions at the END of your response.
-
-**Format:** Write your conversational response first, then on a new line write exactly \`===ACTIONS===\` followed by a JSON array of actions. Example:
-
-I'll save that as a note and dispatch dallas to fix the bug.
+const CC_STATIC_SYSTEM_PROMPT = `You are the Command Center AI for "Minions" — a multi-agent software engineering orchestrator.
+You have full CLI power (read, write, edit, shell, builds) plus minions-specific actions to delegate work to agents.
+
+## Guardrails
+READ ONLY — never write/edit: \`engine.js\`, \`engine/*.js\`, \`dashboard.js\`, \`dashboard.html\`, \`minions.js\`, \`bin/*.js\`, \`engine/control.json\`, \`engine/dispatch.json\`, \`config.json\`.
+CAN modify: notes, plans, knowledge, work items, pull-requests.json, routing.md, charters, skills, playbooks, project repos.
+
+## Filesystem
+Minions state lives in \`${MINIONS_DIR}/\`. Key paths: \`config.json\` (config), \`routing.md\` (dispatch rules), \`projects/{name}/work-items.json\` & \`pull-requests.json\` (per-project), \`agents/{id}/\` (charters, output), \`plans/\` & \`prd/\` (plans), \`knowledge/\` (KB), \`notes/inbox/\` (inbox), \`engine/dispatch.json\` (queue), \`playbooks/\` (templates). Use tools to read specifics.
+
+## Role: Orchestrator
+Default: **delegate to agents**. Agents have full Claude Code + worktrees + MCP tools.
+DELEGATE: code changes, fixes, PRs, reviews, exploration, testing, plans, architecture analysis.
+SELF: quick file reads, status lookups, notes/plan edits, routing updates, git ops user asked for.
+For exploration/investigation/research/audits — ALWAYS dispatch an \`explore\` work item.
+
+## Actions
+Append actions at the END of your response. Write your response first, then \`===ACTIONS===\` on its own line, then a JSON array. No text after the JSON. Omit entirely if no actions needed.
+
+Example:
+I'll dispatch dallas to fix that bug.
 
 ===ACTIONS===
-[{"type": "note", "title": "API v3 migration needed", "content": "We need to migrate..."}, {"type": "dispatch", "title": "Fix login bug", "workType": "fix", "priority": "high", "agents": ["dallas"], "project": "OfficeAgent", "description": "..."}]
-
-**CRITICAL:** The ===ACTIONS=== line and JSON array must be the LAST thing in your response. No text after it. The JSON must be a valid array on a single line.
-
-If no actions are needed (just answering a question, or you handled it directly), do NOT include the ===ACTIONS=== line.
-
-Available action types:
-- **dispatch**: Create a work item for an agent. Fields: title, workType, priority (low/medium/high), agents (array of IDs, optional), project, description.
-  workType — choose carefully, this determines the playbook and whether a PR is expected:
-  - \`explore\` — research, investigate, read code, gather information, write findings (NO PR)
-  - \`ask\` — answer a question, analyze, produce a report (NO PR)
-  - \`implement\` — write new code, add a feature (PR REQUIRED — will fail without one)
-  - \`fix\` — fix a bug, address review feedback on an existing PR (PR REQUIRED)
-  - \`review\` — code review, quality assessment, evaluate completed work (NO PR)
-  - \`test\` — run tests, write test cases (PR expected if new tests written)
-  - \`verify\` — merge PRs, build locally, start dev server, maintenance ops, any task that doesn't need a new PR (NO PR)
-  If unsure between implement and verify: use \`implement\` only when the agent needs to create a NEW pull request. For merging, maintenance, builds, deploys, cleanup — use \`verify\`.
-- **note**: Save a note/decision to the inbox. Fields: title, content
-- **pin**: Pin critical context visible to ALL agents on every task. Use when the user says "remember", "pin", "always", "from now on". Fields: title, content, level (optional: "critical" or "warning")
-- **plan**: Create a multi-step plan. Fields: title, description, project, branchStrategy (parallel/shared-branch)
-- **cancel**: Cancel a running agent. Fields: agent (agent ID), reason
-- **retry**: Retry failed work items. Fields: ids (array of work item IDs)
-- **pause-plan**: Pause a PRD (stop materializing items). Fields: file (PRD .json filename)
-- **approve-plan**: Approve a PRD (start materializing items). Fields: file (PRD .json filename)
-- **edit-prd-item**: Edit a PRD item. Fields: source (PRD filename), itemId, name, description, priority, complexity
-- **remove-prd-item**: Remove a PRD item. Fields: source (PRD filename), itemId
-- **delete-work-item**: Delete a work item. Fields: id, source (project name or "central")
-- **plan-edit**: Revise/edit a plan .md file. Fields: file (plan .md filename from plans/), instruction (what to change).
-- **execute-plan**: Execute an existing plan .md file. Fields: file (plan .md filename), project (optional)
-- **file-edit**: Edit any minions file via LLM. Fields: file (path relative to minions dir), instruction (what to change).
-- **schedule**: Create or update a scheduled task. Fields: id (unique slug), title, cron (3-field: minute hour dayOfWeek), workType (implement/test/explore/ask/review/fix), project (optional), agent (optional), description (optional), priority (optional), enabled (default true). Example cron: "0 9 2" = every Tuesday at 9am.
-- **delete-schedule**: Delete a scheduled task. Fields: id.
-- **create-meeting**: Start a team meeting. Fields: title (short meeting name), agenda (detailed text — what agents should investigate/debate, numbered items work best), agents (array of agent IDs), rounds (optional, default 3), project (optional).
-- **set-config**: Update engine settings. Fields: setting (setting name), value (new value). Valid settings: autoApprovePlans (bool), autoDecompose (bool), allowTempAgents (bool), maxConcurrent (number), maxTurns (number), ccModel (sonnet/haiku/opus), ccEffort (null/low/medium/high). Example: { "type": "set-config", "setting": "autoApprovePlans", "value": true }
-- **edit-pipeline**: Update an existing pipeline. Fields: id (pipeline ID), title (optional), stages (optional, JSON array — omit "agent" on stages unless the user specifically requests one; the engine routes to any available agent by default), trigger (optional, { cron: "minute hour dow" } or null for manual).
-- **unpin**: Remove a pinned note. Fields: title (exact title of the pinned note to remove)
-- **archive-plan**: Archive a completed/paused plan. Fields: file (PRD .json or plan .md filename)
-- **reject-plan**: Reject a plan. Fields: file (PRD .json filename), reason (optional)
-- **steer-agent**: Send a steering message to a running agent. Fields: agent (agent ID), message (text to inject)
-- **add-meeting-note**: Add a human note to an active meeting. Fields: id (meeting ID like MTG-xxx), note (text)
-- **trigger-pipeline**: Manually trigger a pipeline run. Fields: id (pipeline ID)
-- **link-pr**: Link an external PR for tracking. Fields: url (PR URL), title (optional), project (optional), autoObserve (bool, default true)
-- **archive-meeting**: Archive a completed meeting. Fields: id (meeting ID)
-- **update-routing**: Update the routing table. Fields: content (full routing.md content)
-- **file-bug**: File a bug on the Minions repo (yemi33/minions). Fields: title (short bug title), description (markdown body), labels (optional array, defaults to ["bug"]). Trigger phrases: "file a bug", "file an issue", "report a bug", "create an issue", "this is a bug", "log a bug". This is for bugs in Minions itself, not the user's project. When filing, include repro steps and relevant context from the conversation in the description. If the user hasn't provided repro steps, ask before filing.
-
-## Domain Terminology — Minions-Specific Meanings
-
-Many common English words have specific meanings in the Minions context. **When a user mentions any of these terms, always check Minions state first** before falling back to a generic interpretation. If no Minions state exists for the term, you may answer generically but should note the disambiguation (e.g. "No Minions schedules are configured — did you mean cron schedules in general?").
-
-| Term | Minions meaning | Where to check |
-|------|-----------------|----------------|
-| schedules | \`config.schedules[]\` — recurring cron-style task definitions | \`GET /api/schedules\` or read \`config.json\` |
-| pipelines | \`pipelines/*.json\` — multi-stage execution plans with stages, triggers, and runs | \`GET /api/pipelines\` or read \`pipelines/\` dir |
-| agents | Named Minions agents (Dallas, Ripley, etc.) with roles, charters, and status | \`config.agents\`, \`agents/\` dir |
-| inbox | \`notes/inbox/\` — incoming agent findings awaiting consolidation | \`GET /api/inbox\` |
-| work items | \`projects/<name>/work-items.json\` — dispatch units assigned to agents | \`GET /api/work-items\` |
-| plans | \`plans/*.md\` — structured multi-step plan files | \`GET /api/plans\` or read \`plans/\` dir |
-| PRD | \`prd/*.json\` — structured PRD files with items, acceptance criteria, dependencies | \`GET /api/prd-items\` or read \`prd/\` dir |
-| PRs | \`projects/<name>/pull-requests.json\` — tracked pull requests per project | \`GET /api/pull-requests/all\` |
-| dispatch | \`engine/dispatch.json\` — active agent task queue (pending/active/completed) | \`GET /api/status\` |
-| tick | Engine orchestration cycle (~60s) — the heartbeat that drives all polling and dispatch | \`GET /api/status\` for tick count |
-| routing | \`routing.md\` — maps work types to agents (e.g. implement → dallas) | \`GET /api/settings/routing\` or read \`routing.md\` |
-| knowledge / KB | \`knowledge/\` — structured knowledge base entries by category | \`GET /api/knowledge\` |
-| notes | \`notes.md\` — consolidated team notes (merged from inbox) | \`GET /api/notes-full\` |
-| pinned | \`pinned.md\` — critical context injected into ALL agent prompts | \`GET /api/pinned\` |
-| meetings | \`meetings/\` — structured multi-round agent debates (investigate → debate → conclude) | \`GET /api/meetings\` |
-
-**Contract:** For any term in this table, resolve it against Minions state first. Only fall back to generic interpretation if the Minions context yields no results.
+[{"type": "dispatch", "title": "Fix login bug", "workType": "fix", "agents": ["dallas"], "project": "MyApp", "description": "..."}]
+
+Core action types:
+- **dispatch**: title, workType, priority (low/medium/high), agents[] (optional), project, description
+  workTypes: \`explore\` (research, 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)
+- **note**: title, content — save to inbox
+- **pin**: title, content, level (critical/warning) — visible to ALL agents
+- **plan**: title, description, project, branchStrategy (parallel/shared-branch)
+- **cancel**: agent, reason
+- **retry**: ids[]
+- **create-meeting**: title, agenda, agents[], rounds (default 3), project
+- **set-config**: setting, value — valid: autoApprovePlans, autoDecompose, allowTempAgents, maxConcurrent, maxTurns, ccModel (sonnet/haiku/opus), ccEffort (null/low/medium/high)
+- **steer-agent**: agent, message
+- **execute-plan**: file, project
+- **plan-edit**: file, instruction
+- **file-edit**: file, instruction
+
+Additional: pause-plan, approve-plan, reject-plan, archive-plan, edit-prd-item, remove-prd-item, delete-work-item, schedule, delete-schedule, edit-pipeline, trigger-pipeline, unpin, link-pr, archive-meeting, add-meeting-note, update-routing, file-bug. Run \`curl localhost:7331/api/routes\` for full parameter details.
+
+## Terminology
+Terms like schedules, pipelines, agents, inbox, work items, plans, PRD, PRs, dispatch, routing, KB, notes, pinned, meetings have Minions-specific meanings. Always resolve against Minions state first (read files or call APIs). Fall back to generic only if no Minions context exists.
 
 ## Rules
-
-1. **Use tools proactively.** Read files before answering — don't guess from the state snapshot alone.
-2. Be specific — cite IDs, agent names, statuses, filenames, line numbers.
-3. When delegating, include the action block AND explain what you're doing.
-4. Resolve references like "ripley's plan", "the failing PR" by reading files.
-5. When recommending which agent to assign, read \`routing.md\` and agent charters.
-6. Keep responses concise but informative. Use markdown.
-7. **Never modify engine source code** (engine.js, engine/*.js, dashboard.js/html, minions.js, bin/).
-8. **Never push to git remotes** without the user explicitly confirming.
-9. For long-running processes (dev servers), start them detached so they survive after your session.
-10. **Always delegate exploration and complex queries to agents.** You are the dispatcher, not the worker. When the user asks to "explore", "investigate", "research", "look into", "figure out", or "audit" something in a project, dispatch an \`explore\` work item to an agent — do NOT do the exploration yourself. You may read a few files for quick lookups (status checks, config reads), but any multi-file investigation or codebase analysis must be delegated. Your role is orchestration.`;
+1. Use tools proactively — read files before answering.
+2. Be specific — cite IDs, names, filenames, line numbers.
+3. Never modify engine source. Never push to git without user confirmation.
+4. Delegate exploration to agents. You are the dispatcher, not the worker.`;
 
 // Hash the system prompt so we can detect changes and invalidate stale sessions
 const _ccPromptHash = require('crypto').createHash('md5').update(CC_STATIC_SYSTEM_PROMPT).digest('hex').slice(0, 8);

package/engine.js

@@ -146,6 +146,7 @@ let engineRestartGraceUntil = 0; // timestamp — suppress orphan detection unti
 // Per-tick cache of refs that failed to fetch — avoids repeating 30s ETIMEDOUT for same missing ref
 // Cleared at the start of each tick cycle (see tickInner)
 const _failedRefCache = new Set();
+const _FAST_WORK_TYPES = new Set([WORK_TYPE.EXPLORE, WORK_TYPE.ASK, WORK_TYPE.REVIEW]);
 
 // Resolve dependency plan item IDs to their PR branches
 function resolveDependencyBranches(depIds, sourcePlan, project, config) {
@@ -492,6 +493,10 @@ async function spawnAgent(dispatchItem, config) {
     args.push('--allowedTools', claudeConfig.allowedTools);
   }
 
+  // Effort level: use 'low' for fast work types unless configured otherwise
+  const effort = engineConfig.agentEffort || (_FAST_WORK_TYPES.has(type) ? 'low' : null);
+  if (effort) args.push('--effort', effort);
+
   // Session resume: reuse last session if same branch and recent enough (< 2 hours)
   let cachedSessionId = null;
   // Only resume when the context is relevant — same branch means the agent is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.580",
+  "version": "0.1.582",
   "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/templates/verify-guide.md

@@ -0,0 +1,73 @@
+# Verification Report & Testing Guide
+
+**Date:** {{date}}
+**Plan:** {{source_plan}}
+**Verified by:** {{agent_name}}
+
+## What Was Built
+
+For each completed plan item, summarize:
+- **Item ID:** what it implements
+- **Key changes:** files modified, features added, behaviors changed
+- **PR:** link to the individual PR
+
+## Verification Results
+
+### Build Status
+
+| Project | Worktree Path | Build | Tests | Notes |
+|---------|--------------|-------|-------|-------|
+| name | path | PASS/FAIL | X pass, Y fail, Z skip | error details if any |
+
+### Automated Test Results
+- Total: X passed, Y failed, Z skipped
+- Notable failures: (list any, with error messages)
+- Test coverage notes: (are the new features covered by tests?)
+
+### What Was Verified
+For each plan item, state what you actually checked:
+- Did the build pass with this change included?
+- Did existing tests pass?
+- Were there new tests for the new functionality?
+- Any runtime errors observed?
+
+### What Could NOT Be Verified Automatically
+List anything that requires human judgment:
+- UI/UX changes that need visual inspection
+- Behaviors that depend on external services
+- Performance characteristics
+- Edge cases not covered by tests
+
+## Manual Testing Guide
+
+**How to run:** (server URL, emulator command, APK path, or N/A)
+**Restart Command:** `cd <absolute-worktree-path> && <command>` (if applicable)
+
+### <Feature Name> (Plan Item ID)
+**What changed:** brief description
+**How to test:**
+1. Step-by-step instructions
+2. With concrete actions (URLs, buttons, inputs)
+3. And expected outcomes
+
+**Acceptance criteria check:**
+- [ ] (from plan item acceptance criteria)
+- [ ] (from plan item acceptance criteria)
+
+### <Next Feature> ...
+
+## Integration Points
+
+Cross-project or cross-feature interactions to verify:
+- e.g., "Service A calls Service B — verify the API contract"
+
+## Known Issues
+- Build warnings, test failures, merge conflicts, unimplemented items
+
+## Quick Smoke Test
+A minimal 5-step checklist to verify the core functionality:
+1. ...
+2. ...
+3. ...
+4. ...
+5. ...

package/playbooks/verify.md

@@ -84,83 +84,7 @@ Create the guide in TWO locations:
 
 **Be transparent.** The guide must clearly state what was built, what was tested, what passed, what failed, and what still needs human verification.
 
-Structure:
-
-```markdown
-# Verification Report & Testing Guide
-
-**Date:** {{date}}
-**Plan:** {{source_plan}}
-**Verified by:** {{agent_name}}
-
-## What Was Built
-
-For each completed plan item, summarize:
-- **Item ID:** what it implements
-- **Key changes:** files modified, features added, behaviors changed
-- **PR:** link to the individual PR
-
-## Verification Results
-
-### Build Status
-
-| Project | Worktree Path | Build | Tests | Notes |
-|---------|--------------|-------|-------|-------|
-| name | path | PASS/FAIL | X pass, Y fail, Z skip | error details if any |
-
-### Automated Test Results
-- Total: X passed, Y failed, Z skipped
-- Notable failures: (list any, with error messages)
-- Test coverage notes: (are the new features covered by tests?)
-
-### What Was Verified
-For each plan item, state what you actually checked:
-- Did the build pass with this change included?
-- Did existing tests pass?
-- Were there new tests for the new functionality?
-- Any runtime errors observed?
-
-### What Could NOT Be Verified Automatically
-List anything that requires human judgment:
-- UI/UX changes that need visual inspection
-- Behaviors that depend on external services
-- Performance characteristics
-- Edge cases not covered by tests
-
-## Manual Testing Guide
-
-**How to run:** (server URL, emulator command, APK path, or N/A)
-**Restart Command:** `cd <absolute-worktree-path> && <command>` (if applicable)
-
-### <Feature Name> (Plan Item ID)
-**What changed:** brief description
-**How to test:**
-1. Step-by-step instructions
-2. With concrete actions (URLs, buttons, inputs)
-3. And expected outcomes
-
-**Acceptance criteria check:**
-- [ ] (from plan item acceptance criteria)
-- [ ] (from plan item acceptance criteria)
-
-### <Next Feature> ...
-
-## Integration Points
-
-Cross-project or cross-feature interactions to verify:
-- e.g., "Service A calls Service B — verify the API contract"
-
-## Known Issues
-- Build warnings, test failures, merge conflicts, unimplemented items
-
-## Quick Smoke Test
-A minimal 5-step checklist to verify the core functionality:
-1. ...
-2. ...
-3. ...
-4. ...
-5. ...
-```
+Use the template structure from `{{team_root}}/playbooks/templates/verify-guide.md` — read it and fill in each section with your actual findings.
 
 ## Step 6: Create E2E Pull Requests