clikit-plugin 0.2.35 → 0.2.37

package/dist/skills/index.d.ts

@@ -1,8 +1,18 @@
+export declare function resolveSkillsDir(): string;
 export interface SkillConfig {
     name: string;
     description: string;
     content: string;
     location: string;
+    from?: string;
+    model?: string;
+    agent?: string;
+    subtask?: boolean;
+    "argument-hint"?: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, unknown>;
+    "allowed-tools"?: string[];
 }
 export declare function getBuiltinSkills(): Record<string, SkillConfig>;
 export declare function findSkill(skills: Record<string, SkillConfig>, query: string): SkillConfig | null;

package/dist/skills/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAuC9D;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAgChG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAUA,wBAAgB,gBAAgB,IAAI,MAAM,CAOzC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAuC9D;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAgChG"}

package/dist/tools/cass-memory.d.ts

@@ -0,0 +1,61 @@
+export interface CassMemoryExecOptions {
+    cmPath?: string;
+    cwd?: string;
+    timeoutMs?: number;
+}
+export interface CassMemoryResult<T = unknown> {
+    ok: boolean;
+    command: string[];
+    data?: T;
+    raw?: string;
+    error?: string;
+    source?: "cm" | "embedded";
+}
+export interface CassMemoryContextParams extends CassMemoryExecOptions {
+    task: string;
+    limit?: number;
+    history?: number;
+    days?: number;
+    noHistory?: boolean;
+}
+export interface CassMemoryMarkParams extends CassMemoryExecOptions {
+    bulletId: string;
+    helpful?: boolean;
+    harmful?: boolean;
+    reason?: string;
+}
+export interface CassMemoryReflectParams extends CassMemoryExecOptions {
+    days?: number;
+    maxSessions?: number;
+    dryRun?: boolean;
+    workspace?: string;
+}
+export interface CassMemoryOutcomeParams extends CassMemoryExecOptions {
+    status: "success" | "failure" | "mixed" | "partial";
+    rules: string;
+    summary?: string;
+    duration?: number;
+    errors?: number;
+}
+export interface CassMemoryDoctorParams extends CassMemoryExecOptions {
+    fix?: boolean;
+}
+export declare function cassMemoryContext(params: unknown): Promise<CassMemoryResult>;
+export declare function cassMemoryMark(params: unknown): Promise<CassMemoryResult>;
+export declare function cassMemoryReflect(params?: unknown): Promise<CassMemoryResult>;
+export declare function cassMemoryOutcome(params: unknown): Promise<CassMemoryResult>;
+export declare function cassMemoryDoctor(params?: CassMemoryExecOptions): Promise<CassMemoryResult>;
+/**
+ * Check whether the real cm binary is available.
+ * Useful for conditional logic in hooks/skills.
+ */
+export declare function cassIsAvailable(cmPath?: string): Promise<{
+    available: boolean;
+    version?: string;
+    path?: string;
+}>;
+/**
+ * Reset the cached cm binary path. Useful after installation.
+ */
+export declare function cassResetCache(): void;
+//# sourceMappingURL=cass-memory.d.ts.map

package/dist/tools/cass-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cass-memory.d.ts","sourceRoot":"","sources":["../../src/tools/cass-memory.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,IAAI,GAAG,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAwB,SAAQ,qBAAqB;IACpE,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAuB,SAAQ,qBAAqB;IACnE,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAuVD,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA0BlF;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwB/E;AAED,wBAAsB,iBAAiB,CAAC,MAAM,GAAE,OAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkBvF;AAED,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2BlF;AAED,wBAAsB,gBAAgB,CAAC,MAAM,GAAE,qBAA0B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAWpG;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAYvH;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/tools/index.d.ts

@@ -4,4 +4,5 @@ export { swarm, type SwarmParams, type SwarmTask, type SwarmResult, type SwarmPl
 export { beadsMemorySync, type BeadsMemorySyncParams, type BeadsMemorySyncResult, } from "./beads-memory-sync";
 export { quickResearch, type QuickResearchParams, type QuickResearchResult, } from "./quick-research";
 export { contextSummary, type ContextSummaryParams, type ContextSummaryResult, } from "./context-summary";
+export { cassMemoryContext, cassMemoryMark, cassMemoryReflect, cassMemoryDoctor, cassMemoryOutcome, cassIsAvailable, cassResetCache, type CassMemoryContextParams, type CassMemoryMarkParams, type CassMemoryReflectParams, type CassMemoryOutcomeParams, type CassMemoryDoctorParams, type CassMemoryExecOptions, type CassMemoryResult, } from "./cass-memory";
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,SAAS,EACT,cAAc,EACd,YAAY,EACZ,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,KAAK,EACL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,SAAS,EACT,cAAc,EACd,YAAY,EACZ,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,KAAK,EACL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clikit-plugin",
-  "version": "0.2.35",
-  "description": "OpenCode plugin with 10 agents, 19 commands, 48 skills, 10 hooks",
+  "version": "0.2.37",
+  "description": "OpenCode plugin with 7 agents, 19 commands, 48 skills, 10 hooks",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/skill/cass-village/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: cass-village
+description: Use when delegating multi-agent tasks with persistent memory. Combines CASS procedural memory with beads-village coordination so agents learn from every delegation cycle.
+---
+
+# CASS Village Skill
+
+You are running the **cass-village** skill. Memory-informed multi-agent delegation with learning feedback loops.
+
+## How It Works
+
+CliKit integrates with the real [CASS Memory System](https://github.com/Dicklesworthstone/cass_memory_system) (`cm` CLI) when available. If `cm` is not installed, it falls back to an embedded SQLite-based implementation with reduced capabilities.
+
+**With `cm` installed** (recommended): Full playbook management, Bayesian rule scoring, real reflection that distills sessions into rules, outcome tracking, and cross-agent memory sharing.
+
+**Without `cm`** (embedded fallback): Basic context retrieval via FTS5 search, feedback recording, and anti-pattern promotion. Reflection is a stub.
+
+## The Problem
+
+Without shared memory, subagents repeat the same mistakes across sessions. Knowledge dies when a session ends. Tasks get assigned without context about what worked or failed before. This skill closes the loop: memory informs delegation, outcomes feed back into memory.
+
+## Core Loop
+
+```
+PLAN    cm context per task     Hydrate tasks with relevant rules
+  |                                |
+  v                                v
+ENRICH  beads-village_add       Tasks carry CASS context in description
+  |                                |
+  v                                v
+EXECUTE subagents claim         Follow rules, leave inline feedback
+  |                                |
+  v                                v
+LEARN   cm outcome + reflect    Session knowledge becomes persistent rules
+```
+
+## Phase 1: Plan with Memory
+
+Before creating tasks, query CASS for relevant knowledge.
+
+```bash
+# For each task you're about to delegate:
+cm context "<task description>" --json
+```
+
+This returns:
+- **Playbook rules** scored against the task (with rule IDs like `b-8f3a2c`)
+- **History snippets** from past sessions where similar work was done
+- **Anti-patterns** to avoid (rules previously marked harmful)
+
+Extract the top 3-5 rules. These go into the task description.
+
+## Phase 2: Enrich and Delegate
+
+When creating beads-village tasks, embed CASS context directly in the task description.
+
+**Task description template:**
+
+```
+## Task
+<what needs to be done>
+
+## Memory Context
+Following rules from CASS playbook:
+- b-8f3a2c: <rule content> (score: 8.2, proven)
+- b-def456: <rule content> (score: 6.1, established)
+
+Avoid anti-patterns:
+- b-xyz789: PITFALL: <what not to do>
+
+## Prior History
+<relevant snippet from cm context output, if any>
+
+## Feedback Protocol
+When following a rule, comment: // [cass: helpful b-XXXX] - reason
+When a rule causes problems, comment: // [cass: harmful b-XXXX] - reason
+```
+
+**Delegation commands:**
+
+```
+beads-village_add   title, desc (with CASS context), tags, deps
+beads-village_assign  id, role
+```
+
+Tag tasks with roles (`fe`, `be`, `qa`, `devops`, `mobile`) so the right subagent picks them up.
+
+## Phase 3: Subagent Execution
+
+Subagents follow the standard beads cycle with one addition -- inline CASS feedback:
+
+```
+1. beads-village_claim          Pick up the task
+2. Read the Memory Context      Note which rules apply
+3. beads-village_reserve        Lock files
+4. Work                         Follow the rules, write code
+5. Leave inline feedback        // [cass: helpful b-XXX] or // [cass: harmful b-XXX]
+6. beads-village_done           Complete the task
+```
+
+### Inline Feedback Rules
+
+- Reference rule IDs when following them: `"Following b-8f3a2c, using retry with backoff"`
+- Mark rules helpful when they prevent a mistake or speed up work
+- Mark rules harmful when they cause a regression, waste time, or are wrong
+- Be specific in the reason -- vague feedback is discarded during reflection
+
+## Phase 4: Learn from Outcomes
+
+After a batch of tasks completes, the leader records outcomes and triggers reflection.
+
+### Record Task Outcomes
+
+For each completed task, record whether it succeeded or failed and which rules were used:
+
+```bash
+# Successful task that followed specific rules
+cm outcome success b-8f3a2c,b-def456 --json
+
+# Failed task where a rule caused problems
+cm outcome failure b-xyz789 --text "Rate limiter approach caused deadlock" --json
+
+# Mixed results
+cm outcome mixed b-8f3a2c,b-def456 --json
+```
+
+### End-of-Session Reflection
+
+At session end, trigger reflection to distill new rules from the work done:
+
+```bash
+cm reflect --days 1 --json
+```
+
+This processes all session activity (including inline feedback) into:
+- New candidate rules from patterns detected
+- Score updates for existing rules (helpful/harmful counts)
+- Anti-pattern inversions for consistently harmful rules
+- Maturity promotions for consistently helpful rules
+
+### Review Playbook Health
+
+```bash
+# Top performing rules
+cm top 10
+
+# Find stale rules without recent feedback
+cm stale --days 60
+
+# Understand why a rule exists
+cm why b-8f3a2c
+
+# Overall playbook health metrics
+cm stats --json
+```
+
+## Decision Matrix
+
+| Situation | Action |
+|-----------|--------|
+| Creating a new task | Run `cm context` first, embed top rules |
+| Task similar to past failure | Include anti-patterns prominently in description |
+| Subagent following a rule successfully | Leave `// [cass: helpful b-XXX]` inline |
+| Rule caused a problem during execution | Leave `// [cass: harmful b-XXX]` inline |
+| Batch of tasks completed | Run `cm outcome` for each, then `cm reflect` |
+| Starting a new session | `cm context` for the overall goal to prime memory |
+
+## Configuration
+
+In `clikit.config.json`:
+
+```json
+{
+  "hooks": {
+    "cass_memory": {
+      "enabled": true,
+      "cm_path": "/path/to/cm",
+      "context_on_session_created": true,
+      "reflect_on_session_idle": true,
+      "context_limit": 5,
+      "reflect_days": 7,
+      "log": true
+    }
+  }
+}
+```
+
+The `cm_path` option lets you specify a custom path to the `cm` binary. If omitted, it looks for `cm` on your PATH.
+
+## Graceful Degradation
+
+| Component Missing | Behavior |
+|-------------------|----------|
+| `cm` not installed | Falls back to embedded SQLite mode (basic context, no real reflection) |
+| No playbook rules match | Delegate without memory context |
+| `cm context` returns empty | Proceed -- the task is novel, learning starts now |
+| `cm reflect` fails | Outcomes are still recorded, retry later |
+| `cm outcome` without `cm` | Skipped (requires real cm CLI) |
+
+## Leader Checklist
+
+```
+[ ] Run cm context before creating tasks
+[ ] Embed top rules + anti-patterns in task descriptions
+[ ] Include feedback protocol instructions in each task
+[ ] After batch completion, run cm outcome for each task
+[ ] At session end, run cm reflect --days 1
+[ ] Review new/updated rules: cm top 10
+```
+
+## Anti-Patterns
+
+- Dumping the entire playbook into a task description (token waste, noise)
+- Skipping inline feedback (the learning loop breaks)
+- Never running reflection (knowledge stays ephemeral)
+- Assigning tasks without checking CASS first (repeating past mistakes)
+- Ignoring anti-patterns in task descriptions (same failures recur)

package/src/agents/AGENTS.md

@@ -9,7 +9,8 @@ Each `.md` file in this directory defines an agent. The frontmatter sets model,
 - @vision — prompt-to-UI, image-to-code, variant exploration. Loads skills like `frontend-aesthetics` and `mockup-to-code`.
 - @explore — fast read-only codebase navigation. Has restricted bash (grep, find, git read-only).
 - @review — code review and security audit. Use before merging.
-- @oracle, @scout, @librarian, @looker, @general — see individual agent files for details.
+- @oracle — merged deep analysis + architecture advisor (from previous oracle + looker).
+- @research — merged external research + GitHub evidence specialist (from previous scout + librarian).
 
 ## Rules
 

package/src/agents/build.md

@@ -46,14 +46,14 @@ Before ANY action, silently classify the user's intent:
 |---|---|---|
 | **Trivial** | Single file, obvious fix, typo | Do it yourself immediately |
 | **Explicit** | Clear task, defined scope | Create todos → implement → verify |
-| **Exploratory** | "How does X work?", "Find Y" | Fire Explore/Looker in background, report findings |
-| **Research** | "What's the best way to...", external APIs | Fire Scout + Librarian in background |
+| **Exploratory** | "How does X work?", "Find Y" | Fire Explore in background, report findings |
+| **Research** | "What's the best way to...", external APIs | Fire Research in background, synthesize results |
 | **Open-ended** | Vague goal, multiple approaches | Assess codebase first (Phase 1), then plan |
 | **Ambiguous** | Can't determine intent | Ask ONE clarifying question, then act |
 
 **Key triggers (check every message):**
 - 2+ modules involved → fire `Explore` in background immediately
-- External library/API mentioned → fire `Scout` in background immediately
+- External library/API mentioned → fire `Research` in background immediately
 - Architecture question → fire `Oracle` (wait for result before answering)
 - UI/design work → delegate to `Vision`
 - Security-sensitive → delegate to `Review`
@@ -72,7 +72,7 @@ Skip this for explicit/trivial tasks. For open-ended work:
 
 ## Phase 2A: Exploration & Research (parallel, background-first)
 
-**CRITICAL: Explore and Scout are CHEAP. Fire them liberally and in PARALLEL.**
+**CRITICAL: Explore and Research are CHEAP. Fire them liberally and in PARALLEL.**
 
 For codebase questions, fire multiple Explore tasks simultaneously:
 ```
@@ -81,12 +81,13 @@ Task 2: "Find how <pattern> is used across the codebase"
 Task 3: "Find test patterns for <module>"
 ```
 
-For external knowledge, fire Scout + Librarian simultaneously:
+For external knowledge, fire Research:
 ```
-Scout: "Find docs for <library> <specific API>"
-Librarian: "Find real-world usage of <pattern> on GitHub"
+Research: "Find docs for <library> <specific API> + real-world usage + migration notes"
 ```
 
+Require Research to include a re-check section (confirmed/contradicted/unknown) before consuming results.
+
 Collect results only when needed for implementation. Never wait synchronously for background research.
 
 ## Phase 2B: Implementation
@@ -115,22 +116,21 @@ Execute directly:
 | Tier | Tool/Agent | When |
 |---|---|---|
 | **FREE** | read, glob, grep, lsp_* | Always prefer first |
-| **CHEAP** | Explore, Scout, Librarian | Fire liberally in background for any uncertainty |
-| **MODERATE** | General, Vision | Delegate bounded subtasks |
-| **EXPENSIVE** | Oracle, Looker | Hard problems, after 2+ failed attempts, architecture |
+| **CHEAP** | Explore, Research | Fire liberally in background for uncertainty |
+| **MODERATE** | Vision, Review | Delegate bounded subtasks |
+| **EXPENSIVE** | Oracle | Hard problems, after 2+ failed attempts or architecture decisions |
 
 #### Delegation Table
 
 | Domain | Delegate To | Mode |
 |---|---|---|
 | Codebase navigation, find files/usages | **Explore** | background, parallel |
-| Deep code analysis, architecture review | **Looker** | foreground |
-| External docs, library APIs | **Scout** | background, parallel |
-| Open-source internals, GitHub evidence | **Librarian** | background, parallel |
-| Architecture decisions, stuck 3+ failures | **Oracle** | foreground, MUST collect result |
+| Deep local analysis, architecture review | **Oracle** | foreground |
+| External docs, library APIs | **Research** | background, parallel |
+| Open-source internals, GitHub evidence | **Research** | background, parallel |
 | UI/UX design + implementation | **Vision** | foreground |
 | Code review, security audit, quality gate | **Review** | foreground |
-| Multi-step utility tasks | **General** | foreground |
+| Multi-step utility tasks | **Self** | foreground |
 
 #### 7-Section Prompt (MANDATORY for every Task() delegation)
 
@@ -149,6 +149,7 @@ CONTEXT: File paths, constraints, related decisions, code snippets
 - If Oracle is running in background, **MUST collect its result** before delivering any final answer
 - Never cancel Oracle prematurely
 - Oracle is for HARD problems only — don't waste it on simple lookups
+- Require Oracle to re-check incoming Research findings before final recommendations
 
 ## Phase 2C: Failure Recovery
 
@@ -217,7 +218,7 @@ AST-grep: `$VAR` = single node, `$$$` = multiple nodes, pattern must be valid co
 - Silently ignore failing acceptance criteria
 - Add unnecessary comments, logging, or "improvements" beyond scope
 - Over-engineer: build the simplest thing that works
-- Wait synchronously for Explore/Scout when you could fire them in background
+- Wait synchronously for Explore/Research when you could fire them in background
 
 ## Inputs
 

package/src/agents/index.ts

@@ -4,11 +4,25 @@ import * as path from "path";
 import matter from "gray-matter";
 
 const AGENTS_DIR_CANDIDATES = [
+  // Dev: running from src/agents
   import.meta.dir,
+  // Packaged plugin: running from dist/, agents live in src/agents/
+  path.join(import.meta.dir, "../src/agents"),
+  // Additional fallbacks for non-standard layouts
   path.join(import.meta.dir, "../../src/agents"),
+  path.join(import.meta.dir, "../agents"),
 ];
 
 function resolveAgentsDir(): string {
+  for (const dir of AGENTS_DIR_CANDIDATES) {
+    if (!fs.existsSync(dir)) continue;
+    try {
+      const hasAgentFiles = fs.readdirSync(dir).some((f) => f.endsWith(".md") && f !== "AGENTS.md");
+      if (hasAgentFiles) return dir;
+    } catch {
+      // Ignore unreadable candidate and continue.
+    }
+  }
   for (const dir of AGENTS_DIR_CANDIDATES) {
     if (fs.existsSync(dir)) {
       return dir;
@@ -75,14 +89,29 @@ export function loadAgents(): Record<string, AgentConfig> {
 }
 
 let _cachedAgents: Record<string, AgentConfig> | null = null;
-let _cachedAgentsMtime = 0;
+let _cachedAgentsFingerprint = "";
+
+function getAgentsFingerprint(agentsDir: string): string {
+  const files = fs.readdirSync(agentsDir)
+    .filter((f) => f.endsWith(".md") && f !== "AGENTS.md")
+    .sort();
+
+  const parts = files.map((file) => {
+    const fullPath = path.join(agentsDir, file);
+    const stat = fs.statSync(fullPath);
+    return `${file}:${stat.mtimeMs}`;
+  });
+
+  return parts.join("|");
+}
 
 export function getBuiltinAgents(): Record<string, AgentConfig> {
   try {
-    const mtime = fs.statSync(resolveAgentsDir()).mtimeMs;
-    if (_cachedAgents && _cachedAgentsMtime === mtime) return _cachedAgents;
+    const agentsDir = resolveAgentsDir();
+    const fingerprint = getAgentsFingerprint(agentsDir);
+    if (_cachedAgents && _cachedAgentsFingerprint === fingerprint) return _cachedAgents;
     _cachedAgents = loadAgents();
-    _cachedAgentsMtime = mtime;
+    _cachedAgentsFingerprint = fingerprint;
     return _cachedAgents;
   } catch {
     return _cachedAgents ?? loadAgents();