@monoes/monomindcli 1.6.0 → 1.6.3

package/.claude/commands/monomind-createtask.md

@@ -0,0 +1,340 @@
+---
+name: monomind-createtask
+description: "Monomind — Ingest a prompt, file, or folder, deeply understand it, generate a full implementation plan, and create self-contained tasks on monotask that coder agents can pick up"
+---
+
+If `$ARGUMENTS` is empty, output this and STOP:
+
+> **Usage:** `/monomind:createtask <prompt | path-to-file | path-to-folder>`
+>
+> Examples:
+> - `/monomind:createtask Build a webhook delivery system with retries and dead-letter queue`
+> - `/monomind:createtask docs/superpowers/specs/2026-04-27-swarm-tab-redesign-design.md`
+> - `/monomind:createtask docs/superpowers/specs/`
+>
+> This command deeply analyzes your input, generates a full implementation plan, and creates self-contained tasks on monotask that simple coder agents can execute without additional context.
+
+Do NOT proceed further if no arguments were provided.
+
+---
+
+## Step 0: Check monotask CLI
+
+Run:
+```bash
+command -v monotask
+```
+
+If `monotask` is NOT found, attempt to install:
+```bash
+command -v cargo && cargo install monotask
+```
+
+If `cargo` is also missing, output this and STOP:
+> monotask requires Rust. Install Rust first:
+> ```bash
+> curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+> source "$HOME/.cargo/env"
+> cargo install monotask
+> ```
+
+---
+
+## Step 1: Classify and Ingest Input
+
+Parse `$ARGUMENTS` to determine input type:
+
+### 1a: Detect input type
+
+- If `$ARGUMENTS` is an existing **file path** (check with `test -f`): `INPUT_TYPE=file`
+- If `$ARGUMENTS` is an existing **directory path** (check with `test -d`): `INPUT_TYPE=folder`
+- Otherwise: `INPUT_TYPE=prompt`
+
+### 1b: Collect raw content
+
+**If `INPUT_TYPE=prompt`:**
+- Store the text as `RAW_CONTENT`.
+
+**If `INPUT_TYPE=file`:**
+- Read the file using the Read tool.
+- Store the full contents as `RAW_CONTENT`.
+- Store filename as `INPUT_LABEL`.
+
+**If `INPUT_TYPE=folder`:**
+- List all files in the directory (non-recursive, skip hidden files):
+  ```bash
+  find "$ARGUMENTS" -maxdepth 2 -type f ! -name '.*' | head -30
+  ```
+- Read each file using the Read tool (up to 30 files, skip binary files).
+- Concatenate all contents with `--- FILE: <path> ---` separators as `RAW_CONTENT`.
+- Store folder path as `INPUT_LABEL`.
+
+### 1c: Enrich with knowledge systems
+
+Run ALL of the following in parallel (skip any that error):
+
+1. **Knowledge graph — suggest**: Call `mcp__monobrain__graphify_suggest` with the first 200 chars of `RAW_CONTENT`.
+2. **Knowledge graph — query**: If any specific module/component names appear in `RAW_CONTENT`, call `mcp__monobrain__graphify_query` for each (up to 5 queries).
+3. **Memory search**: Call `mcp__monobrain__memory_search` with a summary of the input. Use top 5 results.
+4. **README**: Read `README.md` (first 200 lines). Skip if missing.
+5. **Package manifest**: Read whichever exists first: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`.
+6. **Repo name**: Run `git remote get-url origin`, extract last path segment, strip `.git`. Fallback: `basename` of cwd. Store as `REPO_NAME`.
+
+Bundle everything into `FULL_CONTEXT` = `RAW_CONTENT` + graph results + memory results + README + manifest.
+
+---
+
+## Step 2: Setup Monotask Space and Task Board
+
+### Space
+- Run `monotask space list` and check if a space named `$REPO_NAME` exists.
+- If not, create it: `monotask space create "$REPO_NAME"`.
+- Store `SPACE_ID`.
+
+### Task Board
+- List boards via `monotask board list --json`. For each board ID, run `monotask column list <BOARD_ID> --json` to find one whose columns contain `Todo` (the `monomind-task` board).
+- If the `monomind-task` board does not exist:
+  1. Create it: `monotask board create "monomind-task" --json` — store `TASK_BOARD_ID`.
+  2. Add to space: `monotask space boards add $SPACE_ID $TASK_BOARD_ID`.
+  3. Create columns in order:
+     - `Backlog`
+     - `Todo`
+     - `In Progress`
+     - `Review`
+     - `Human in Loop`
+     - `Done`
+- Store all column IDs mapped by name.
+
+---
+
+## Step 3: Deep Analysis — Understand the Document
+
+Spawn a `Software Architect` agent via the Agent tool. Provide it with:
+
+- The complete `FULL_CONTEXT`
+- The user's original `$ARGUMENTS`
+
+The agent MUST produce a structured analysis:
+
+```json
+{
+  "summary": "2-3 sentence overview of what this document/prompt is about",
+  "goals": ["list of high-level goals or features described"],
+  "components": [
+    {
+      "name": "component or module name",
+      "description": "what it does",
+      "dependencies": ["other components it depends on"],
+      "files_likely_affected": ["paths from graphify or educated guesses"]
+    }
+  ],
+  "technical_constraints": ["any constraints, tech stack requirements, or limitations mentioned"],
+  "acceptance_criteria": ["testable conditions for when this is done"],
+  "risks": ["potential pitfalls, ambiguities, or unknowns"]
+}
+```
+
+Store as `ANALYSIS`.
+
+---
+
+## Step 4: Generate Implementation Plan
+
+Spawn a `planner` agent via the Agent tool. Provide it with:
+
+- The `ANALYSIS` from Step 3
+- The `FULL_CONTEXT`
+- The `REPO_NAME` and project info
+
+The agent MUST produce an ordered list of implementation tasks. Each task must be **completely self-contained** — a coder agent with NO prior context should be able to execute it by reading only the task card.
+
+For each task, produce:
+
+```json
+{
+  "title": "Short action-oriented title (e.g. 'Add webhook retry logic with exponential backoff')",
+  "description": "Detailed description: WHAT to build, WHY it's needed, WHERE it fits in the system",
+  "context": "All relevant context a coder needs: existing patterns to follow, related files, API shapes, data models, config values. Include specific file paths from graphify results when available.",
+  "acceptance_criteria": ["list of testable conditions that prove this task is done"],
+  "checklist": ["step-by-step implementation steps the coder should follow"],
+  "agent_type": "recommended agent type (e.g. coder, backend-dev, Frontend Developer, Security Engineer)",
+  "priority": "critical | high | medium | low",
+  "effort": 1-10,
+  "dependencies": ["titles of other tasks that must complete first, or empty array"]
+}
+```
+
+**Rules for task generation:**
+- Tasks MUST be ordered so dependencies come first.
+- Each task should take a single agent 5-30 minutes to complete.
+- Tasks that are too large MUST be split.
+- Every task MUST include enough context that the coder doesn't need to read the original document.
+- Include a test-writing step in every task's checklist.
+- Assign agent types from available agents (coder, backend-dev, Frontend Developer, Security Engineer, etc.) based on the task domain.
+
+Store as `TASKS` array.
+
+---
+
+## Step 5: Create Tasks on Monotask Board
+
+For each task in the `TASKS` array, in dependency order:
+
+1. **Create the card** in the `Todo` column (dependency-free tasks) or `Backlog` column (has unfinished dependencies):
+   ```bash
+   monotask card create $TASK_BOARD_ID $COL_TODO "<title>" --json
+   ```
+   Store the returned `CARD_ID`.
+
+2. **Set description** with the full context block:
+   ```bash
+   monotask card set-description $TASK_BOARD_ID $CARD_ID "<description>\n\n## Context\n<context>"
+   ```
+
+3. **Add agent assignment comment**:
+   ```bash
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "Assigned agent: <agent_type>"
+   ```
+
+4. **Add acceptance criteria comment**:
+   ```bash
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "Acceptance criteria:\n- <criterion 1>\n- <criterion 2>\n..."
+   ```
+
+5. **Add dependency comment** (if any):
+   ```bash
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "Dependencies: <task title 1>, <task title 2>"
+   ```
+
+6. **Set priority**:
+   ```bash
+   monotask card set-priority $TASK_BOARD_ID $CARD_ID <1-4>
+   ```
+   Map: critical=1, high=2, medium=3, low=4.
+
+7. **Create checklist** with implementation steps:
+   ```bash
+   monotask checklist add $TASK_BOARD_ID $CARD_ID "Implementation Steps" --json
+   ```
+   Store `CHECKLIST_ID`, then for each step:
+   ```bash
+   monotask checklist item-add $TASK_BOARD_ID $CARD_ID $CHECKLIST_ID "<step>"
+   ```
+
+Batch card creation commands where possible to reduce round-trips.
+
+---
+
+## Step 6: Exploration Session — Suggest Missing Pieces
+
+After all tasks are created, spawn a **second** `Software Architect` agent (fresh context) via the Agent tool. Provide it with:
+
+- The `ANALYSIS` from Step 3
+- The complete list of `TASKS` already created (titles + descriptions)
+- The `FULL_CONTEXT`
+
+The agent must act as a **critical reviewer** and identify:
+
+```json
+{
+  "missing_pieces": [
+    {
+      "title": "What's missing",
+      "description": "Why this matters and what should be done",
+      "category": "testing | documentation | error-handling | monitoring | security | performance | accessibility | deployment | migration"
+    }
+  ],
+  "upcoming_plans": [
+    {
+      "title": "Natural follow-up work",
+      "description": "What this would add and why it's worth considering",
+      "category": "enhancement | optimization | scale | integration"
+    }
+  ]
+}
+```
+
+**Areas to explore:**
+- Missing test coverage (unit, integration, e2e)
+- Error handling and edge cases not covered
+- Documentation that should be created or updated
+- Security considerations (input validation, auth, rate limiting)
+- Performance implications (caching, indexing, pagination)
+- Monitoring and observability (logging, metrics, alerts)
+- Migration or backwards compatibility concerns
+- Deployment steps or configuration changes needed
+- Accessibility requirements (for UI tasks)
+
+### Present to User
+
+Output the suggestions in a clear format:
+
+```
+## Missing Pieces
+
+| # | Category     | Title                              | Description                |
+|---|-------------|------------------------------------|----------------------------|
+| 1 | testing     | Add integration tests for webhook  | Currently only unit tests  |
+| 2 | security    | Rate-limit webhook endpoints       | Prevent abuse              |
+
+## Potential Follow-ups
+
+| # | Category     | Title                              | Description                |
+|---|-------------|------------------------------------|----------------------------|
+| 1 | enhancement | Add webhook analytics dashboard    | Track delivery rates       |
+```
+
+Then ask:
+
+> **Found N missing pieces and M potential follow-ups.**
+>
+> Reply with the numbers you want to add as tasks (e.g., `1, 3, 5` or `all` or `none`).
+> Missing pieces will be added to **Todo**. Follow-ups will be added to **Backlog**.
+
+### Process User Selection
+
+If the user selects items:
+1. For each selected **missing piece**: Create a task card in `Todo` with full context (same Step 5 process). Add a comment: `"Source: exploration — missing piece"`.
+2. For each selected **follow-up**: Create a task card in `Backlog` with full context. Add a comment: `"Source: exploration — follow-up suggestion"`.
+
+If the user says `none` or declines, skip.
+
+---
+
+## Step 7: Final Summary
+
+Output:
+
+```
+## Task Creation Complete
+
+**Source:** <prompt text | file path | folder path>
+**Space:** $REPO_NAME (ID: $SPACE_ID)
+**Board:** monomind-task (ID: $TASK_BOARD_ID)
+
+### Tasks Created
+
+| # | Title                                   | Agent        | Priority | Column  |
+|---|----------------------------------------|-------------|----------|---------|
+| 1 | <title>                                | backend-dev | high     | Todo    |
+| 2 | <title>                                | coder       | medium   | Todo    |
+| 3 | <title>                                | Frontend Developer | medium | Backlog |
+
+**Total:** N tasks in Todo, M tasks in Backlog
+**Estimated effort:** X points
+```
+
+---
+
+## Step 8: Offer to Execute
+
+If there are tasks in Todo, ask:
+
+> **N tasks are ready for execution.** Want me to start `/monomind:do` to process them?
+>
+> It will pick up tasks one by one, execute them with the assigned agent, review for bugs, and loop until the queue is empty.
+
+If the user agrees, invoke:
+```
+Skill("monomind-do", "--space $SPACE_ID --board $TASK_BOARD_ID")
+```

package/.claude/commands/monomind-do.md

@@ -55,6 +55,35 @@ If `cargo` is also missing, output this and STOP:
 
 ---
 
+## Step 1.5: Initialize Loop State
+
+Generate a loop ID and write the initial state file so the dashboard can track this run:
+```bash
+mkdir -p .monomind/loops
+export DO_LOOP_ID="do-$(date +%s%3N)"
+cat > ".monomind/loops/${DO_LOOP_ID}.json" << EOF
+{
+  "id": "${DO_LOOP_ID}",
+  "type": "do",
+  "prompt": "/monomind:do $ARGUMENTS",
+  "currentTask": "discovering...",
+  "spaceId": "${SPACE_ID:-}",
+  "boardId": "${TASK_BOARD_ID:-}",
+  "filter": "${FILTER:-}",
+  "startedAt": $(date +%s%3N),
+  "lastRunAt": $(date +%s%3N),
+  "nextRunAt": 0,
+  "status": "running"
+}
+EOF
+```
+
+Also check if a stop was requested from a previous cycle:
+```bash
+[ -f ".monomind/loops/${DO_LOOP_ID}.stop" ] && echo "DO_STOP_REQUESTED=true"
+```
+If `DO_STOP_REQUESTED=true`, output `[monomind:do] Stop requested via dashboard. Halting.`, remove state files, and STOP.
+
 ## Step 2: Find Next Task
 
 1. List cards in `Todo` first (prioritized), then `Backlog`:
@@ -69,6 +98,13 @@ If `cargo` is also missing, output this and STOP:
    ```
    [monomind:do] No tasks in Todo or Backlog. Checking again in 2 minutes...
    ```
+   Update loop state before scheduling:
+   ```bash
+   NEXT_AT=$(( $(date +%s%3N) + 120000 ))
+   cat > ".monomind/loops/${DO_LOOP_ID}.json" << EOF
+   {"id":"${DO_LOOP_ID}","type":"do","prompt":"/monomind:do $ARGUMENTS","currentTask":"queue empty — waiting","spaceId":"${SPACE_ID:-}","boardId":"${TASK_BOARD_ID:-}","filter":"${FILTER:-}","startedAt":$(cat .monomind/loops/${DO_LOOP_ID}.json 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin).get('startedAt',0))" 2>/dev/null || date +%s%3N),"lastRunAt":$(date +%s%3N),"nextRunAt":${NEXT_AT},"status":"waiting"}
+   EOF
+   ```
    Then use `ScheduleWakeup` with `delaySeconds: 120` and prompt `/monomind:do --space $SPACE_ID --board $TASK_BOARD_ID` (plus `--filter` if one was set) to check again. STOP this iteration.
 
 4. Store `CURRENT_CARD_ID` and `CURRENT_CARD_TITLE`.
@@ -273,4 +309,9 @@ If no tasks remain, output:
 [monomind:do] All tasks processed. Queue empty.
 ```
 
+Remove the loop state file:
+```bash
+rm -f ".monomind/loops/${DO_LOOP_ID}.json" ".monomind/loops/${DO_LOOP_ID}.stop"
+```
+
 Do NOT schedule another wake-up. STOP.

package/.claude/commands/monomind-repeat.md

@@ -37,6 +37,27 @@ Extract:
 - `MAX_REPS` — from `--times` flag, default `10`
 - `PROMPT` — everything remaining after flags are removed
 - `CURRENT_REP` — starts at `1`
+- `LOOP_ID` — generate as `repeat-<unix-timestamp-ms>` (use `date +%s000`)
+
+Write the initial loop state file so the dashboard can track this run:
+```bash
+mkdir -p .monomind/loops
+LOOP_ID="repeat-$(date +%s%3N)"
+cat > ".monomind/loops/${LOOP_ID}.json" << EOF
+{
+  "id": "${LOOP_ID}",
+  "type": "repeat",
+  "prompt": "PROMPT",
+  "interval": INTERVAL,
+  "currentRep": 1,
+  "maxReps": MAX_REPS,
+  "startedAt": $(date +%s%3N),
+  "lastRunAt": $(date +%s%3N),
+  "nextRunAt": $(date +%s%3N),
+  "status": "running"
+}
+EOF
+```
 
 Output:
 ```
@@ -58,6 +79,16 @@ Run the `PROMPT` as if the user typed it directly. This means:
 
 ## Step 3: Report and Schedule Next
 
+Before scheduling the next run, check if a stop was requested:
+```bash
+[ -f ".monomind/loops/${LOOP_ID}.stop" ] && echo "STOP_REQUESTED=true"
+```
+If `STOP_REQUESTED=true`, output `[monomind:repeat] Stop requested via dashboard. Halting.` and remove the state files:
+```bash
+rm -f ".monomind/loops/${LOOP_ID}.json" ".monomind/loops/${LOOP_ID}.stop"
+```
+Then STOP.
+
 After execution completes, output:
 ```
 [monomind:repeat] Run CURRENT_REP/MAX_REPS complete. Next in INTERVAL minutes...
@@ -69,9 +100,32 @@ If `CURRENT_REP > MAX_REPS`, output:
 ```
 [monomind:repeat] All MAX_REPS repetitions complete.
 ```
+Remove the state file:
+```bash
+rm -f ".monomind/loops/${LOOP_ID}.json"
+```
 STOP. Do NOT schedule another wake-up.
 
-Otherwise, use `ScheduleWakeup` with:
+Otherwise, update the loop state before scheduling:
+```bash
+NEXT_AT=$(( $(date +%s%3N) + INTERVAL * 60 * 1000 ))
+cat > ".monomind/loops/${LOOP_ID}.json" << EOF
+{
+  "id": "${LOOP_ID}",
+  "type": "repeat",
+  "prompt": "PROMPT",
+  "interval": INTERVAL,
+  "currentRep": CURRENT_REP,
+  "maxReps": MAX_REPS,
+  "startedAt": STARTED_AT,
+  "lastRunAt": $(date +%s%3N),
+  "nextRunAt": ${NEXT_AT},
+  "status": "running"
+}
+EOF
+```
+
+Use `ScheduleWakeup` with:
 - `delaySeconds`: `INTERVAL * 60`
 - `prompt`: `/monomind:repeat --every INTERVAL --times MAX_REPS --rep CURRENT_REP PROMPT`
 - `reason`: `"repeat run CURRENT_REP/MAX_REPS of: PROMPT"`

package/.claude/helpers/hook-handler.cjs

@@ -433,6 +433,7 @@ const handlers = {
           confidence: result.confidence,
           reason: result.reason,
           semanticRouting: result.semanticRouting || false,
+          llmRouting: result.llmRouting || false,
           updatedAt: new Date().toISOString(),
         };
         if (result.extrasMatches && result.extrasMatches.length > 0) {

package/.claude/helpers/router.cjs

@@ -167,6 +167,127 @@ function isNonDevTask(taskLower) {
   return false;
 }
 
+// ─── Two-Stage LLM Router (for non-dev and ambiguous tasks) ─────────────────
+// Stage 1: LLM picks category from ~9 categories
+// Stage 2: LLM picks specific agent from agents in that category
+// Falls back to keyword scoring if API unavailable
+
+function getAnthropicKey() {
+  return process.env.ANTHROPIC_API_KEY || '';
+}
+
+function buildCategoryList() {
+  const registry = loadExtrasRegistry();
+  const cats = {};
+  for (const e of registry.extras) {
+    if (!cats[e.category]) cats[e.category] = [];
+    cats[e.category].push(e.name);
+  }
+  return Object.entries(cats).map(([name, agents]) => ({
+    name,
+    count: agents.length,
+    examples: agents.slice(0, 4).join(', '),
+  }));
+}
+
+function getAgentsInCategory(category) {
+  const registry = loadExtrasRegistry();
+  return registry.extras
+    .filter(e => e.category === category)
+    .map(e => ({ slug: e.slug, name: e.name, description: (e.description || '').slice(0, 120) }));
+}
+
+async function llmPick(systemPrompt, userPrompt) {
+  const key = getAnthropicKey();
+  if (!key) return null;
+  try {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 2000);
+    const resp = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': key,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify({
+        model: 'claude-haiku-4-5-20251001',
+        max_tokens: 60,
+        system: systemPrompt,
+        messages: [{ role: 'user', content: userPrompt }],
+      }),
+      signal: ac.signal,
+    });
+    clearTimeout(timer);
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    const text = (data.content && data.content[0] && data.content[0].text) || '';
+    return text.trim();
+  } catch { return null; }
+}
+
+async function routeTaskLLM(task) {
+  const categories = buildCategoryList();
+  if (!categories.length) return null;
+
+  // Stage 1: pick category
+  const catList = categories.map((c, i) => `${i + 1}. ${c.name} (${c.count} agents, e.g. ${c.examples})`).join('\n');
+  const stage1System = 'You route tasks to agent categories. Reply with ONLY the category name, nothing else.';
+  const stage1User = `Task: "${task}"\n\nCategories:\n${catList}\n\nWhich category best fits this task? Reply with the category name only.`;
+
+  const pickedCat = await llmPick(stage1System, stage1User);
+  if (!pickedCat) return null;
+
+  // Normalize — find closest category match
+  const catLower = pickedCat.toLowerCase().replace(/[^a-z-]/g, '');
+  const matchedCat = categories.find(c => c.name.toLowerCase().replace(/[^a-z-]/g, '') === catLower);
+  const categoryName = matchedCat ? matchedCat.name : categories.find(c => catLower.includes(c.name.toLowerCase().replace(/[^a-z-]/g, '')))?.name;
+  if (!categoryName) return null;
+
+  // Stage 2: pick agent within category
+  const agents = getAgentsInCategory(categoryName);
+  if (!agents.length) return null;
+
+  const agentList = agents.map((a, i) => `${i + 1}. ${a.name} — ${a.description}`).join('\n');
+  const stage2System = 'You pick the best agent for a task. Reply with ONLY the agent name exactly as listed, nothing else.';
+  const stage2User = `Task: "${task}"\n\nAgents in ${categoryName}:\n${agentList}\n\nWhich agent is the best fit? Reply with the exact agent name only.`;
+
+  const pickedAgent = await llmPick(stage2System, stage2User);
+  if (!pickedAgent) return null;
+
+  // Find the agent entry — exact match only, fall back to keyword routing
+  const agentLower = pickedAgent.toLowerCase().trim();
+  const matched = agents.find(a => a.name.toLowerCase() === agentLower);
+  if (!matched) return null;
+
+  return {
+    agent: matched.name,
+    agentSlug: matched.slug,
+    confidence: 0.9,
+    reason: `LLM 2-stage: ${categoryName} → ${matched.name}`,
+    category: categoryName,
+    allInCategory: agents.map(a => ({ slug: a.slug, label: a.name, note: categoryName })),
+  };
+}
+
+/**
+ * Route multiple subtasks for swarm agent selection.
+ * Each subtask description gets its own 2-stage LLM routing.
+ * Returns array of { subtask, agent, agentSlug, confidence, reason }.
+ */
+async function routeSwarmAgents(subtasks) {
+  if (!Array.isArray(subtasks) || !subtasks.length) return [];
+  const results = await Promise.all(subtasks.map(async (sub) => {
+    const desc = typeof sub === 'string' ? sub : sub.description || sub.task || '';
+    if (!desc) return { subtask: desc, agent: 'coder', agentSlug: 'coder', confidence: 0.5, reason: 'empty subtask' };
+    const llm = await routeTaskLLM(desc);
+    if (llm) return { subtask: desc, agent: llm.agent, agentSlug: llm.agentSlug, confidence: llm.confidence, reason: llm.reason };
+    const kw = routeTask(desc);
+    return { subtask: desc, agent: kw.agent, agentSlug: kw.agentSlug, confidence: kw.confidence, reason: kw.reason };
+  }));
+  return results;
+}
+
 // ─── RouteLayer bridge (GAP-002) ─────────────────────────────────────────────
 // Cache a Promise so concurrent callers all await the same load operation.
 var _routeLayerPromise = null;
@@ -187,11 +308,33 @@ async function tryLoadRouteLayer() {
 }
 
 /**
- * Async variant — tries RouteLayer semantic routing first, falls back to keywords.
- * hook-handler.cjs route handler should call this instead of routeTask().
+ * Async variant — tries LLM 2-stage routing for non-dev tasks,
+ * RouteLayer semantic routing for dev tasks, falls back to keywords.
  */
 async function routeTaskSemantic(task) {
   if (typeof task !== 'string' || !task) return routeTask(task);
+  const taskLower = task.toLowerCase();
+
+  // For non-dev tasks or ambiguous defaults, try LLM 2-stage routing first
+  if (isNonDevTask(taskLower)) {
+    const llmResult = await routeTaskLLM(task);
+    if (llmResult) {
+      const extrasMatches = matchExtras(task);
+      return {
+        agent: llmResult.agent,
+        agentSlug: llmResult.agentSlug,
+        confidence: llmResult.confidence,
+        reason: llmResult.reason,
+        skillMatches: [],
+        extrasMatches,
+        specificAgents: llmResult.allInCategory.slice(0, 5),
+        llmRouting: true,
+      };
+    }
+    // LLM failed — fall through to keyword-based extras matching
+  }
+
+  // Dev tasks: try RouteLayer semantic routing
   const rl = await tryLoadRouteLayer();
   if (rl && rl.route) {
     try {
@@ -216,7 +359,25 @@ async function routeTaskSemantic(task) {
       }
     } catch (e) { /* fall through to keyword */ }
   }
-  return routeTask(task);
+
+  // Default keyword fallback — also try LLM if no dev pattern matched
+  const keywordResult = routeTask(task);
+  if (keywordResult.confidence <= 0.5) {
+    const llmResult = await routeTaskLLM(task);
+    if (llmResult) {
+      return {
+        agent: llmResult.agent,
+        agentSlug: llmResult.agentSlug,
+        confidence: llmResult.confidence,
+        reason: llmResult.reason,
+        skillMatches: keywordResult.skillMatches,
+        extrasMatches: matchExtras(task),
+        specificAgents: llmResult.allInCategory.slice(0, 5),
+        llmRouting: true,
+      };
+    }
+  }
+  return keywordResult;
 }
 
 // ─── Main routing ─────────────────────────────────────────────────────────────
@@ -288,7 +449,7 @@ function loadExtrasAgent(slug) {
   } catch (e) { return null; }
 }
 
-module.exports = { routeTask, routeTaskSemantic, matchSkills, matchExtras, loadExtrasAgent, loadExtrasRegistry, loadSkillRegistry, AGENT_CAPABILITIES, TASK_PATTERNS };
+module.exports = { routeTask, routeTaskSemantic, routeTaskLLM, routeSwarmAgents, matchSkills, matchExtras, loadExtrasAgent, loadExtrasRegistry, loadSkillRegistry, buildCategoryList, getAgentsInCategory, AGENT_CAPABILITIES, TASK_PATTERNS };
 
 // CLI
 if (require.main === module) {