@yemi33/minions 0.1.2146 → 0.1.2148

package/docs/completion-reports.md

@@ -84,6 +84,71 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `tests` | string | `pass`, `fail`, `skipped`, `N/A`, or a free-form note like `skipped — relying on PR pipeline`. |
 | `pending` | string | Any remaining work, or `none`. |
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |
+| `meta.review` | object | Optional, review tasks only. Records project-local review-skill outcome — see [Review skill outcomes](#review-skill-outcomes). Aliased by the generalized `meta.skill` (W-mq1cczi90006b21f). |
+| `meta.skill` | object | Optional. Records project-local skill outcome for ANY playbook type that surfaces a `## Project skills` block (implement / fix / plan / review / etc.). See [Project skill outcomes](#project-skill-outcomes). |
+
+## Project skill outcomes
+
+W-mq1cczi90006b21f. Generalizes the PR-82 review-only `meta.review.skill*` fields to the full Minions lifecycle. When the playbook renders a `## Project skills` block (via `engine/playbook-intents.js` → `engine/discover-project-skills.js`) and the agent acts on a discovered skill, record the outcome under `meta.skill` so later evaluation can compare skill-driven vs. first-principles work across implement / fix / plan / review dispatches uniformly.
+
+All `meta.skill` fields are optional and backward-compatible — older agents that never set them stay valid.
+
+```json
+{
+  "status": "success",
+  "meta": {
+    "skill": {
+      "invoked": {
+        "name": "bump-fmf-android",
+        "path": ".claude/skills/bump-fmf-android/SKILL.md",
+        "kind": "skill",
+        "intent": "build"
+      },
+      "findings": 3
+    }
+  }
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `meta.skill.invoked` | object | The project skill the agent actually ran. Shape: `{name, path, kind, intent}` where `kind` is one of `skill`, `command`, `slash-command` (mirrors the discovery layer in `engine/discover-project-skills.js`) and `intent` is the bucket it served (`build`, `review`, `fix`, `test`, `plan`, `research`, `deploy`, `observability`, `meta`). Omit when no skill was invoked. |
+| `meta.skill.findings` | number | Count of findings/artifacts the invoked skill returned. Semantics is per-skill; treat as opaque integer. Omit when no skill was invoked. |
+| `meta.skill.skipped` | object | Set when a project skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope, meta-work on the skill itself, etc.). Shape: `{name, reason}`. Mirror the skip rationale into the PR comment / completion summary so a human sees the reasoning. |
+
+Dispatchers can suppress the block entirely by setting `meta.skipProjectSkills: true` on the work item — the playbook then renders without the skills block. Use this for meta-work that targets the skill itself; the engine still accepts `meta.skill.skipped` in the report regardless. The PR-82 `meta.skipProjectReviewSkills` flag is preserved as an alias (suppresses the block on every dispatch type, not just review).
+
+## Review skill outcomes
+
+W-mq16xtdx001a347e. **Original PR-82 fields, preserved as aliases.** New code should prefer the generalized `meta.skill.*` fields above (W-mq1cczi90006b21f) — those work for every playbook type, not just review.
+
+Review playbook renders a `## Project review skills` block at dispatch time when the target project ships `.claude/skills/*` or `.claude/commands/*` with `review` / `swarm` in the name or description (or when `.github/copilot-instructions.md` / `CLAUDE.md` mention a canonical `/…review…` slash-command). When the agent acts on that block, it records the outcome under `meta.review` so later evaluation can compare skill-driven reviews vs. first-principles reviews.
+
+All `meta.review` fields are optional and backward-compatible — older agents that never set them stay valid.
+
+```json
+{
+  "status": "success",
+  "meta": {
+    "review": {
+      "skillInvoked": {
+        "name": "code-reviewer",
+        "path": ".claude/skills/code-reviewer/SKILL.md",
+        "kind": "skill"
+      },
+      "skillFindings": 3
+    }
+  }
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `meta.review.skillInvoked` | object | The project review skill the agent actually ran. Shape: `{name, path, kind}` where `kind` is one of `skill`, `command`, `slash-command` (mirrors the discovery layer in `engine/discover-project-skills.js`). Omit when no skill was invoked. Aliased by `meta.skill.invoked`. |
+| `meta.review.skillFindings` | number | Count of findings the invoked skill returned. Used later to measure skill quality and the value-add of first-principles review on top. Omit when no skill was invoked. Aliased by `meta.skill.findings`. |
+| `meta.review.skillSkipped` | object | Set when a project review skill was available but the agent intentionally chose not to run it (trivial diff, out-of-scope diff, meta-review of the skill itself, etc.). Shape: `{name, reason}`. Aliased by `meta.skill.skipped`. |
+
+Dispatchers can suppress the block entirely by setting `meta.skipProjectReviewSkills: true` on the review work item — the playbook then renders identically to the pre-W-mq16xtdx 8-step contract. Use this for meta-reviews of the review skill itself; the engine still accepts `meta.review.skillSkipped` in the report regardless. (W-mq1cczi90006b21f generalized this to `meta.skipProjectSkills`, which suppresses the block on every dispatch type — both flags are honored.)
 
 ## `failure_class` enum
 

package/docs/project-skills.md

@@ -0,0 +1,133 @@
+# Project skill discovery & intent vocabulary
+
+W-mq1cczi90006b21f (follow-on to PR #82, W-mq16xtdx001a347e).
+
+Minions' project-local **skill discovery layer** surfaces purpose-built tooling that a project ships (`.claude/skills/`, `.claude/commands/`, slash-command mentions in `CLAUDE.md` / `.github/copilot-instructions.md`) so dispatched agents steer toward the right skill instead of reinventing the flow from first principles.
+
+This document is the contract every playbook author and project teammate needs to know.
+
+## Where the code lives
+
+| File | Role |
+|---|---|
+| `engine/discover-project-skills.js` | Bounded filesystem walk + classification heuristic. The crash-safe primitive. |
+| `engine/playbook-intents.js` | Single source of truth for the playbook → intent set mapping. |
+| `engine/playbook.js` | Calls discovery + filter at render time, injects `{{project_skills_block}}` into the rendered prompt. |
+| `engine/discover-review-skills.js` | Thin re-export shim. Backward-compat only — new code uses `discover-project-skills.js`. |
+
+## What gets discovered
+
+Per project worktree, the discovery walk visits:
+
+- `<projectRoot>/.claude/skills/*/SKILL.md` — top-level skill packs.
+- `<projectRoot>/.claude/commands/*.md` — top-level slash-commands.
+- `<projectRoot>/<area>/.claude/skills/*/SKILL.md` — **nested per-area skills** (one level deep). This is how OCM / loop / officemobile organize their skills in a monorepo.
+- `<projectRoot>/<area>/.claude/commands/*.md` — same, for nested commands.
+- `<projectRoot>/.github/copilot-instructions.md` — slash-command mentions (top 32 KB).
+- `<projectRoot>/CLAUDE.md` — slash-command mentions (top 32 KB).
+
+Each discovery entry has shape:
+
+```js
+{
+  kind: 'skill' | 'command' | 'slash-command',
+  name: string,                   // e.g. "code-reviewer" or "/review-swarm"
+  path: string,                   // relative to projectRoot
+  oneLineDescription: string,     // ≤200 chars
+  intents: string[]               // closed enum, see below
+}
+```
+
+The walk is **cheap and bounded** — preserve every guardrail in
+`engine/discover-project-skills.js`:
+
+- ≤ 50 files per surface
+- 8 KB per skill / 32 KB per docs file
+- 250 ms walltime budget — bails rather than blocks dispatch
+- ≤ 50 nested areas probed
+- Missing worktree / unreadable → `[]` (never throws)
+
+## The intent vocabulary (CLOSED)
+
+| Intent | What belongs here |
+|---|---|
+| `review` | code review, PR review, swarm review (`code-reviewer`, `/review-swarm`, `/code-review`, etc.) |
+| `build` | scaffold, generate, bump, migrate, codemod, refactor (`bump-fmf-android`, `workspace`, `vhd`, etc.) |
+| `fix` | debug, triage, repro, regression, flake-killing (`triage-flake`, `cover-pr` for missing tests on PR…) |
+| `test` | author tests, increase coverage, validate (`integration-tests`, `run-tests`, `qa-validate`) |
+| `plan` | PRD authoring, ADR, design-doc, decompose (`substitute-scheduler-template-vars`, `decompose`) |
+| `research` | investigate, gather-impact, telemetry-query, audit (`gather-impact`, `audit-deprecated`) |
+| `deploy` | release, publish, buddy-build, rollout, ship (`buddy-build`, `track-pr`) |
+| `observability` | telemetry, logs, kusto, monitoring, metrics dashboards (`kusto-telemetry-lmf-quality-report`, `weekly-repo-summary`) |
+| `meta` | meta-tooling about the skill system itself. **Do NOT use as a catch-all** — empty `intents: []` is the honest signal when the heuristic doesn't fire. |
+
+### How intents are assigned
+
+For each discovered entry, `classifyIntents(...)` does:
+
+1. **Honor explicit author intent first.** A skill's `SKILL.md` frontmatter may declare `intents:` (or `tags:` / `intent:`) — only values that match the closed vocabulary above are accepted. Example:
+   ```yaml
+   ---
+   name: bump-fmf-android
+   description: Bump the FMF SDK version pin in OCM Android
+   intents: [build, deploy]
+   ---
+   ```
+2. **Fall back to keyword heuristics.** The skill's `name`, frontmatter `description`, first heading, and filename are matched against the per-intent keyword regexes in `INTENT_KEYWORDS` (engine/discover-project-skills.js). A skill matching multiple regexes carries multiple intents.
+3. **Empty intents are honest.** Zero matches → `intents: []`. The entry is still discovered and returned, but no intent-filtered playbook will surface it. NEVER default to `meta` just to satisfy the field.
+
+### Slash-commands scraped from docs
+
+For `/foo` mentions in `CLAUDE.md` / `.github/copilot-instructions.md`, the discovery layer is more conservative: it only surfaces slash-commands whose **name itself** matches at least one intent keyword. This keeps doc-scrape noise out of every prompt (a doc may name 50 `/foo` commands; we don't want to dump them all into an `implement` prompt).
+
+## The playbook → intent map
+
+Defined in `engine/playbook-intents.js`. The default mapping at time of writing:
+
+| Playbook | Intents surfaced |
+|---|---|
+| `review` | `['review']` |
+| `fix` | `['fix', 'test', 'review']` |
+| `implement` / `implement-shared` | `['build', 'test', 'research']` |
+| `plan` / `plan-to-prd` / `decompose` | `['plan', 'research']` |
+| `docs` | `['research']` |
+| `verify` | `['test', 'review']` |
+| `build-and-test` | `['build', 'test']` |
+| `test` / `qa-validate` | `['test']` |
+| `explore` | `['research']` |
+| (all others) | `[]` — no block rendered |
+
+When a playbook's intent set is empty (or maps to none), the `{{project_skills_block}}` template variable resolves to the empty string and the splice fence collapses cleanly (no stray header, no padding).
+
+The `followup-dispatch` template **inherits** its parent dispatch's intent set via `vars.parent_dispatch_type` — there's no row in the map for it.
+
+## Adding a new playbook
+
+1. Add a row to `PLAYBOOK_INTENTS` in `engine/playbook-intents.js` mapping your playbook name to the intent set it should surface.
+2. Splice the conditional template fence into your playbook markdown at the position where the agent should see purpose-built tooling — typically between the task-intake step and the first "actually do the work" step:
+   ```md
+   {{#project_skills_block}}
+   {{project_skills_block}}
+
+   {{/project_skills_block}}
+   ```
+3. If the playbook should opt out for some dispatches, the dispatcher can set `meta.skipProjectSkills: true` (or the PR-82 alias `meta.skipProjectReviewSkills: true`) on the work item.
+
+## Adding a new intent
+
+1. Add a regex to `INTENT_KEYWORDS` in `engine/discover-project-skills.js`. Use `\b` word boundaries.
+2. Add the value to `INTENT_VOCABULARY` so explicit frontmatter `intents:` entries with the new name are accepted.
+3. Add a row to the table above, with a one-line description of what belongs.
+4. Update one or more playbook entries in `engine/playbook-intents.js` to include the new intent.
+
+Keep the vocabulary tight — every additional intent is noise risk in every prompt that surfaces it.
+
+## Completion-report contract
+
+When an agent acts on a discovered skill, record the outcome in the completion report's `meta.skill` block. See [docs/completion-reports.md](completion-reports.md#project-skill-outcomes) for the full schema. The legacy `meta.review.skill*` fields (PR #82) remain accepted as aliases — new code should prefer `meta.skill.*`.
+
+## Tests
+
+- `test/unit/discover-project-skills.test.js` — discovery + classification + intent filtering + render + per-playbook splice coverage.
+
+When you change discovery, classification, or the playbook→intent map, extend or update this test file.

package/engine/cli.js

@@ -163,18 +163,30 @@ function handleCommand(cmd, args) {
     //
     // `minions work --help` used to create ghost work items with title='--help'
     // because the bare-string `title` was truthy and bypassed the `!title`
-    // usage check. The fix lives in per-command guards (`_isHelpArg` /
-    // `looksLikeFlagOrHelp`) on `work`/`spawn`/`plan`/`complete`, which print
-    // command-specific `Usage:` output. `pr` and `bridge` handle help inline.
+    // usage check. Same class of bug exists in `spawn`/`plan`/`complete` —
+    // every command that takes a positional arg and tests it with `if (!arg)`.
     //
-    // For other commands (start/stop/status/etc.), fall back to printing the
-    // global command list — they take no positional args so `--help` is
-    // otherwise harmless. Commands with per-command help handling are excluded
-    // so their `Usage:` text is what the user sees.
-    const COMMANDS_WITH_OWN_HELP = new Set(['pr', 'bridge', 'work', 'spawn', 'plan', 'complete']);
-    if (!COMMANDS_WITH_OWN_HELP.has(cmd) && isHelpToken(args && args[0])) {
-      console.log('Commands:');
-      for (const line of formatCliCommandHelpLines()) console.log(line);
+    // Intercept here so a single guard covers the whole command set. `pr` and
+    // `bridge` already handle `help`/`--help`/`-h` inline (see their own
+    // first-arg branches), so let them route through unchanged.
+    //
+    // W-mq60aco9: print the *per-command* usage (matching the convention from
+    // PR #3054 which added per-positional `Usage:` for work/spawn/plan/complete).
+    // Previously this branch printed the global `Commands:` list and short-
+    // circuited the per-command guards — so `minions work --help` advertised
+    // the wrong help text. Fall back to the global list only for commands
+    // missing from CLI_COMMAND_DOCS. The per-command `_isHelpArg` guards in
+    // work/spawn/plan/complete remain as defense-in-depth for any caller that
+    // bypasses handleCommand.
+    if (cmd !== 'pr' && cmd !== 'bridge' && isHelpToken(args && args[0])) {
+      const doc = CLI_COMMAND_DOCS[cmd];
+      if (doc) {
+        console.log(`Usage: minions ${cmd}${doc.args ? ' ' + doc.args : ''}`);
+        if (doc.summary) console.log(`  ${doc.summary}`);
+      } else {
+        console.log('Commands:');
+        for (const line of formatCliCommandHelpLines()) console.log(line);
+      }
       return;
     }
     return commands[cmd](...args);