@yemi33/minions 0.1.1563 → 0.1.1565

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1565 (2026-04-27)
+
+### Other
+- docs(sched-weekly-docs-cleanup-1776960000531): sync stale references with current source (#1750)
+
+## 0.1.1564 (2026-04-27)
+
+### Other
+- Harden skill creation guidance
+
 ## 0.1.1563 (2026-04-27)
 
 ### Fixes

package/README.md

@@ -457,7 +457,7 @@ All playbooks use `{{template_variables}}` filled from project config. Condition
 
 Every playbook has an explicit "When to Stop" section telling agents exactly what constitutes completion. Code-pushing playbooks enforce **build → test → repo checks → push** ordering. Per-type max-turns prevent runaway tool loops (explore=30, ask=20, implement=75, verify=100).
 
-Playbooks are fully customizable — edit them to match your workflow. System prompts for CC and plan advisor live in `prompts/` with `{{variable}}` substitution.
+Playbooks are fully customizable — edit the shared templates in `playbooks/` to change the repo-wide defaults. You can also create machine-local overrides in `projects/<name>/playbooks/<type>.md`; Minions will prefer those for that project, but they are treated as user data and remain gitignored. System prompts for CC and plan advisor live in `prompts/` with `{{variable}}` substitution.
 
 ## Health Monitoring
 
@@ -503,7 +503,7 @@ When a reviewer flags issues, the engine creates `feedback-<author>-from-<review
 `engine/metrics.json` tracks per agent: tasks completed, errors, PRs created/approved/rejected, reviews done. Visible in CLI (`status`) and dashboard with color-coded approval rates.
 
 ### 5. Skills
-Agents save repeatable workflows to `skills/<name>.md` with Claude Code-compatible frontmatter. Engine builds an index injected into all prompts. Skills can also be stored per-project at `<project>/.claude/skills/<name>/SKILL.md` (requires a PR). Visible in the dashboard Skills section.
+Agents save Minions-wide repeatable workflows as user-level Claude skills in `~/.claude/skills/<name>/SKILL.md`, so they are usable both inside Minions and in normal Claude windows. Repo-specific skills can also be stored per-project at `<project>/.claude/skills/<name>/SKILL.md` (requires a PR). Visible in the dashboard Skills section.
 
 See `docs/self-improvement.md` for the full breakdown.
 
@@ -730,5 +730,3 @@ Per-project engine state remains centralized:
     work-items.json      <- Per-project work queue
     pull-requests.json   <- PR tracker
 ```
-
-

package/docs/auto-discovery.md

@@ -11,8 +11,8 @@ tick()
   1. checkTimeouts()            Kill stale/hung agents (>heartbeatTimeout)
   2. consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
   2.5 runCleanup()              Periodic cleanup (every 10 ticks ≈ 10min)
-  2.6 pollPrStatus()            Poll ADO for build, review, merge status (every 6 ticks ≈ 6min)
-  2.7 pollPrHumanComments()     Poll PR threads for human @minions comments (every 12 ticks ≈ 12min)
+  2.6 pollPrStatus()            Poll ADO + GitHub for build, review, merge status (every prPollStatusEvery ticks, default 12 ≈ 12min)
+  2.7 pollPrHumanComments()     Poll PR threads for human @minions comments (every prPollCommentsEvery ticks, default 12 ≈ 12min)
   3. discoverWork()             Scan ALL linked projects for new tasks
   4. updateSnapshot()           Write identity/now.md
   5. dispatch                   Spawn agents for pending items (up to maxConcurrent)
@@ -118,11 +118,11 @@ priority: high
 
 Both write to `work-items.json` and are picked up by Source 3 on the same or next tick.
 
-## ADO PR Status Polling (`pollPrStatus`)
+## PR Status Polling (`pollPrStatus`)
 
-**Runs:** Every 6 ticks (≈ 6 minutes), independently of work discovery. Replaces the retired agent-based `pr-sync`.
+**Runs:** Every `prPollStatusEvery` ticks (default 12, ≈ 12 minutes), independently of work discovery. ADO polling lives in `engine/ado.js`; GitHub polling lives in `engine/github.js` — both run in parallel each cycle (`Promise.allSettled`) and write to the same per-project `pull-requests.json` schema. Replaces the retired agent-based `pr-sync`.
 
-The engine directly polls the Azure DevOps REST API for **all** PR metadata: build/CI status, human review votes, and completion state. Two API calls per PR — no agent dispatch needed.
+The engine directly polls the host REST API for **all** PR metadata: build/CI status, human review votes, and completion state. Two API calls per PR — no agent dispatch needed.
 
 **Per PR:**
 1. `GET pullrequests/{id}` → `status` (active/completed/abandoned), `mergeStatus`, `reviewers[].vote`
@@ -137,7 +137,7 @@ The engine directly polls the Azure DevOps REST API for **all** PR metadata: bui
 | `buildStatus` | PR statuses (codecoverage/deploy/build/ci contexts) | `passing` / `failing` / `running` / `none` |
 | `buildFailReason` | Failed status description | Set on failure, cleared otherwise |
 
-**Auth:** Bearer token via `azureauth ado token --output token --timeout 1` (cached 30 minutes). The `--timeout 1` flag is required — without it, azureauth can hang indefinitely in headless sessions.
+**Auth:** Bearer token via `azureauth ado token --mode iwa --mode broker --output token --timeout 1` (cached 30 minutes). The `--timeout 1` flag is required — without it, azureauth can hang indefinitely in headless sessions. (GitHub polling uses the ambient `gh` CLI credentials, not azureauth.)
 
 This feeds `discoverFromPrs` — when `buildStatus` flips to `"failing"`, the next discovery tick dispatches a fix agent. When `status` becomes `"merged"`, the PR drops out of active polling.
 
@@ -244,9 +244,12 @@ Combines:
 
 ### 5. Spawn Claude CLI
 ```bash
-claude -p <prompt-file> --system-prompt <sysprompt-file> \
-  --output-format json --max-turns 100 --verbose \
-  --allowedTools Edit,Write,Read,Bash,Glob,Grep,Agent,WebFetch,WebSearch
+claude -p --system-prompt-file <sysprompt-file> \
+  --output-format stream-json --max-turns 100 --verbose \
+  --permission-mode bypassPermissions
+# Prompt text is piped via stdin (not passed as an arg).
+# Agent dispatches route through engine/spawn-agent.js; CC / doc-chat use a direct
+# spawn path in engine/llm.js that bypasses spawn-agent.js entirely.
 ```
 
 - Process runs in the worktree directory (or rootDir for reviews)
@@ -325,8 +328,8 @@ docs/**/*.md (specs)┤  (each tick)      ┌──────────┐
   plans/*.md ─────┘       ▼                 │
                      addToDispatch()────────┘
                                             │
-ADO REST API ─── pollPrBuildStatus() ──► pull-requests.json
-(every 6min)      (buildStatus field)       │
+ADO + GitHub REST ── pollPrStatus() ──► pull-requests.json
+(every ~12min)       (buildStatus field)      │
                                        spawnAgent()
                                             │
                                ┌────────────┼────────────┐

package/docs/command-center.md

@@ -13,7 +13,7 @@ CC maintains a true multi-turn session using Claude CLI's `--resume` flag. Unlik
 **Session lifecycle:**
 - **Created** on first message (or after the system prompt changes, or when you click **New Session**)
 - **Resumed** on subsequent messages via `--resume <sessionId>`
-- **Invalidated** only when the CC system prompt changes — detected by hashing `CC_STATIC_SYSTEM_PROMPT` into `_ccPromptHash` and comparing on each call. There is no time-based expiry and no turn cap (`CC_SESSION_MAX_TURNS = Infinity`).
+- **Invalidated** when the CC system prompt changes — detected by hashing `CC_STATIC_SYSTEM_PROMPT` into `_ccPromptHash` and comparing on each call. Sessions are also bounded by `ENGINE_DEFAULTS.ccMaxTurns` (default 50 turns) and `ENGINE_DEFAULTS.ccSessionTtlMs` (default 2h — resumed sessions older than this get rotated).
 - **Persisted** to `engine/cc-session.json` — survives dashboard restarts
 - **Frontend messages** saved to `localStorage` — survive page refresh
 
@@ -117,9 +117,10 @@ POST /api/command-center  (or /api/doc-chat, /api/steer-document)
     │     timeout: 600s (CC) or 300s (doc-plan) or 60s (doc-other)
     │
     ▼
-spawn-agent.js
+engine/llm.js callLLM({ direct: true })  (bypasses engine/spawn-agent.js — CC + doc-chat only)
     │
-    ├── If --resume: skip system prompt file, pass -p --resume <id>
+    ├── Resolves claude CLI binary path from engine/claude-caps.json
+    ├── If --resume: pass -p --resume <id> (no system prompt file)
     ├── If new: pass -p --system-prompt-file <file>
     │
     ▼
@@ -143,8 +144,8 @@ Frontend
 
 | File | Role |
 |------|------|
-| `engine/llm.js` | `callLLM()` — single LLM function with optional `sessionId` for resume |
-| `engine/spawn-agent.js` | Spawns claude CLI; skips system prompt on `--resume` |
+| `engine/llm.js` | `callLLM()` / `callLLMStreaming()` — single LLM function with optional `sessionId` for resume; `direct: true` spawns claude CLI directly (used by CC + doc-chat) |
+| `engine/spawn-agent.js` | Agent dispatch wrapper — resolves claude CLI path and invokes it. **Not used by CC/doc-chat** (direct spawn path). |
 | `engine/shared.js` | `parseStreamJsonOutput()` extracts `sessionId` from result |
 | `engine/cc-session.json` | Persisted session state (sessionId, turnCount, timestamps) |
 | `dashboard.js` | CC endpoint, `buildCCStatePreamble()`, `ccDocCall()`, `parseCCActions()` |

package/docs/design-state-storage.md

@@ -22,7 +22,7 @@ Minions persists all runtime state as flat JSON files guarded by file-lock-based
 | `engine/metrics.json` | 5 KB | Per-agent stats | R/W on PR approval/merge | Low | Low |
 | `engine/control.json` | 169 B | Single object | R/W on start/stop/heartbeat | Low | Low |
 | `projects/*/work-items.json` | 370 KB | 180 items | R/W every 1-2 ticks; dashboard reads on-demand | **High** — engine + lifecycle + dashboard | High |
-| `projects/*/pull-requests.json` | 241 KB | 128 PRs | R/W every 6 ticks (polling); lifecycle writes | Medium | Medium |
+| `projects/*/pull-requests.json` | 241 KB | 128 PRs | R/W every `prPollStatusEvery` ticks (default 12, polling); lifecycle writes | Medium | Medium |
 | `engine/pipeline-runs.json` | 36 KB | Pipeline state | R/W on pipeline execution | Low | Low |
 | `engine/schedule-runs.json` | 115 B | Last-run times | R every 10 ticks; W on schedule execution | Low | Low |
 
@@ -56,7 +56,7 @@ Key properties:
 | Engine tick cycle | ~15 | ~3 | Heavy read, selective write |
 | Dashboard (per page load) | ~8 | 0 | Read-only display |
 | Dashboard (user action) | ~2 | ~2 | Read-modify-write |
-| PR polling (every 6 ticks) | ~4 | ~2 | Batch read-modify-write |
+| PR polling (every `prPollStatusEvery` ticks, default 12) | ~4 | ~2 | Batch read-modify-write |
 | Consolidation (every 10 ticks) | ~3 | ~2 | Read inbox files, write notes.md |
 
 **Read:write ratio is approximately 8:1.** This strongly favors a system that can serve reads without locking (e.g., WAL mode).

package/docs/human-vs-automated.md

@@ -46,7 +46,7 @@ These run continuously without you:
 - **Work discovery** — engine scans all project queues every tick (~60s)
 - **Agent dispatch** — engine picks the right agent, builds the prompt, spawns Claude
 - **Worktree management** — create on dispatch, pull on shared-branch, clean after merge
-- **PR status polling** — checks ADO for build status, review votes, merge state every ~6 min
+- **PR status polling** — checks ADO + GitHub for build status, review votes, merge state every ~12 min
 - **Build failure detection** — auto-files fix tasks when CI fails
 - **Inbox consolidation** — LLM-powered dedup and categorization when inbox hits threshold
 - **Knowledge base classification** — auto-assigns category to consolidated notes

package/docs/pr-review-fix-loop.md

@@ -52,7 +52,7 @@ How the engine manages the lifecycle of a PR from creation through review, fix,
 
 ## 6. Re-review cycle
 
-- Poller (~3min): detects new commit (`head.sha` changed) → sets `lastPushedAt`
+- Poller (every `prPollStatusEvery` ticks, default ~12min): detects new commit (`head.sha` changed) → sets `lastPushedAt`
 - Platform review state drives next action:
   - Reviewer approves → `approved` → done
   - Reviewer re-requests changes → `changes-requested` → triggers another fix

package/docs/self-improvement.md

@@ -158,7 +158,7 @@ Without this, review findings only exist in the inbox file under the reviewer's
 
 ## 4. Human Feedback on PRs
 
-Humans can leave comments on ADO PRs containing `@minions` to trigger fix tasks. The engine polls PR threads every ~6 minutes and dispatches fixes to the PR's author agent.
+Humans can leave comments on ADO or GitHub PRs containing `@minions` to trigger fix tasks. The engine polls PR threads every ~12 minutes (see `prPollCommentsEvery` in `engine/shared.js`) and dispatches fixes to the PR's author agent.
 
 ### Flow
 
@@ -257,14 +257,14 @@ Metrics are currently informational — displayed in status and dashboard. Plann
 
 When an agent discovers a repeatable multi-step procedure, it can save it as a **skill** — a structured, reusable workflow compatible with Claude Code's skill system. Skills are stored in two locations:
 
-- **Minions-wide:** `~/.minions/skills/<name>.md` — shared across all agents, no PR required
+- **Minions-wide:** `~/.claude/skills/<name>/SKILL.md` — user-level Claude skill, shared across Minions and normal Claude windows, no PR required
 - **Project-specific:** `<project>/.claude/skills/<name>/SKILL.md` — scoped to one repo, requires a PR
 
 ### Flow
 
 ```
 Agent discovers repeatable pattern during task
-  → writes skills/<name>.md with frontmatter (name, description, trigger, allowed-tools)
+  → writes ~/.claude/skills/<name>/SKILL.md with frontmatter (name, description, trigger, allowed-tools)
   → engine detects new skill files on next tick
   → builds skill index (name + trigger + file path)
   → index injected into every agent's system prompt
@@ -314,10 +314,11 @@ When a git merge or rebase produces conflicts in yarn.lock.
 
 ### When agents should create skills
 
-- Multi-step procedures they had to figure out (build setup, deployment, migration)
-- Error recovery patterns (how to fix a specific class of failure)
-- Project-specific workflows that aren't documented elsewhere
-- Cross-repo coordination steps
+- Only when the workflow is durable, multi-step, and likely to be reused on future tasks
+- Only when the workflow is not already documented in repo docs, notes, playbooks, or existing skills
+- Good candidates: build setup, deployment, migrations, recurring error-recovery patterns, cross-repo coordination steps
+- Prefer zero skills over a weak skill; one-off findings and task-specific notes belong in inbox notes or `notes.md`
+- Do not create skills for isolated fixes, obvious repository facts, or instructions already covered elsewhere
 
 ## Configuration
 

package/engine/playbook.js

@@ -362,14 +362,15 @@ function renderPlaybook(type, vars) {
   content += `- Conventions to follow\n`;
   content += `- **SOURCE REFERENCES for every finding** — file paths with line numbers, PR URLs, API endpoints, config keys. Format: \`(source: path/to/file.ts:42)\` or \`(source: PR-12345)\`. Without references, findings cannot be verified.\n\n`;
   content += `### Skill Extraction (IMPORTANT)\n\n`;
-  content += `If during this task you discovered a **repeatable workflow** — a multi-step procedure, workaround, build process, or pattern that other agents should follow in similar situations — output it as a fenced skill block. The engine will automatically extract it.\n\n`;
+  content += `If during this task you discovered a **repeatable workflow** — a multi-step procedure, workaround, build process, or pattern that other agents should follow in similar situations — only output it as a fenced skill block when **all** of these are true: (1) you had to discover it during this task, (2) it is not already captured in team memory, repo docs, existing playbooks, or existing skills, and (3) another agent is likely to reuse it on future tasks. **Zero skills is the default.** Prefer the inbox findings for one-off notes, repo facts, and task-specific observations.\n\n`;
   content += `Format your skill as a fenced code block with the \`skill\` language tag:\n\n`;
   content += '````\n```skill\n';
   content += `---\nname: short-descriptive-name\ndescription: One-line description of what this skill does\nallowed-tools: Bash, Read, Edit\ntrigger: when should an agent use this\nscope: minions\nproject: any\n---\n\n# Skill Title\n\n## Steps\n1. ...\n2. ...\n\n## Notes\n...\n`;
   content += '```\n````\n\n';
-  content += `- Set \`scope: minions\` for cross-project skills (engine writes to ~/.claude/skills/ automatically)\n`;
-  content += `- Set \`scope: project\` + \`project: <name>\` for repo-specific skills (engine queues a PR to <project>/.claude/skills/)\n`;
-  content += `- Only output a skill block if you genuinely discovered something reusable — don't force it\n`;
+  content += `- Set \`scope: minions\` for cross-project or Minions-wide skills; the engine writes them to ~/.claude/skills/ so they are available in normal Claude windows too\n`;
+  content += `- Set \`scope: project\` + \`project: <name>\` only for repo-specific skills; the engine queues a PR to <project>/.claude/skills/\n`;
+  content += `- Emit at most one skill block per task unless you uncovered two clearly distinct reusable workflows\n`;
+  content += `- Do NOT create a skill for one-off bug fixes, isolated command output, obvious repo facts, or anything already covered by existing docs/playbooks/skills\n`;
 
   // Inject project-level variables from config
   const config = getConfig();
@@ -471,7 +472,7 @@ function buildSystemPrompt(agentId, config, project) {
   prompt += `3. Follow the project conventions in CLAUDE.md if present\n`;
   prompt += `4. Write learnings to the path specified in the task prompt (format: \`notes/inbox/{agent}-{work-item-id}-{date}-{time}.md\`)\n`;
   prompt += `5. Agent status is managed by the engine via dispatch.json — agents do not need to track their own status\n`;
-  prompt += `6. If you discover a repeatable workflow, output it as a \\\`\\\`\\\`skill fenced block — the engine auto-extracts it to ~/.claude/skills/\n\n`;
+  prompt += `6. If you discover a repeatable workflow, output it as a \\\`\\\`\\\`skill fenced block — minions-scoped skills are auto-extracted to ~/.claude/skills/ so they are available in normal Claude windows too\n\n`;
 
   return prompt;
 }
@@ -504,7 +505,7 @@ function buildAgentContext(agentId, config, project) {
 
   // KB and skills: NOT injected — agents can Glob/Read when needed
   // This saves ~27KB per dispatch. Reference note so agents know they exist:
-  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`. Skills are in \`skills/*.md\` and \`.claude/skills/\`. Use Glob/Read to browse when relevant.\n\n`;
+  context += `## Reference Files\n\nKnowledge base entries are in \`knowledge/{category}/*.md\`. User-level Minions skills live in \`~/.claude/skills/\`, and project-specific skills live in \`<project>/.claude/skills/\`. Use Glob/Read when relevant.\n\n`;
 
   // Minions awareness: what's in flight, who's doing what
   const dispatch = getDispatch();

package/package.json

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

@@ -60,7 +60,7 @@ Use subagents only for genuinely parallel, independent tasks. For reading files,
 - Use the appropriate MCP tools for PR creation — check available tools before starting.
 - Do NOT checkout branches in the main working tree — use worktrees.
 - Read `notes.md` for all team rules before starting.
-- If you discover a repeatable workflow, output it as a ```skill block (the engine auto-extracts it to ~/.claude/skills/)
+- Only emit a ```skill block if you uncovered a durable reusable workflow that is not already documented and is likely to help future tasks; zero skills is the default, and one-off findings belong in the inbox notes instead.
 
 ## When to Stop
 

package/playbooks/shared-rules.md

@@ -33,7 +33,7 @@ Your context window may be compacted or summarized mid-task by Claude's automati
   5. Previous agent output in `agents/*/live-output.log` for related tasks
   6. Work item descriptions and `resultSummary` for prior completed work on the same topic
   Only after exhausting team memory should you look outside (web search, codebase exploration, external docs). This avoids duplicating research another agent already completed and ensures team decisions are respected.
-- If you discover a repeatable workflow, output it as a fenced skill block. The engine auto-extracts it to `~/.claude/skills/<name>/SKILL.md`. Required format:
+- Only output a fenced skill block when **all** of these are true: (1) you discovered a durable multi-step workflow that was not already documented in team memory, repo docs, existing playbooks, or existing skills, (2) another agent is likely to need it on future tasks, and (3) the workflow is specific enough to be actionable but general enough to stand alone. **Zero skills is the default.** Prefer writing one-off findings, repo facts, or task-specific notes to the inbox findings instead of creating a skill. Emit **at most one skill block per task** unless the task clearly uncovered two unrelated reusable workflows. The engine auto-extracts valid skill blocks to `~/.claude/skills/<name>/SKILL.md`, so `scope: minions` skills become user-level Claude skills available in normal Claude windows too. Required format:
   ````
   ```skill
   ---
@@ -45,14 +45,15 @@ Your context window may be compacted or summarized mid-task by Claude's automati
   Instructions for the skill go here.
   ```
   ````
-  The `name` and `description` fields are required. `scope` defaults to `minions` (global). Use `scope: project` + `project: ProjectName` for project-specific skills.
+  The `name` and `description` fields are required. `scope` defaults to `minions` (global). Use `scope: minions` for user-level reusable skills; use `scope: project` + `project: ProjectName` only for repo-specific skills that should land in that project via PR.
+  Do **not** create a skill for one-off bug fixes, isolated command outputs, obvious repo facts, or anything already covered by existing docs/playbooks/skills.
 - Do TDD where it makes sense — write failing tests first, then implement, then verify tests pass. Especially for bug fixes (write a test that reproduces the bug) and new utility functions.
 
 ## Checking PR and Build Status
 
 When asked to check build status, CI results, or review state for a PR:
 
-**Preferred — read cached state (always fresh within ~3 min when engine is running):**
+**Preferred — read cached state (refreshed every `prPollStatusEvery` ticks, default ~12 min when engine is running):**
 Find the PR in `projects/<project-name>/pull-requests.json` by `prNumber`. Key fields:
 - `buildStatus` — `passing` | `failing` | `running` | `none`
 - `buildErrorLog` — compiler/pipeline errors when `buildStatus` is `failing`