opencode-hive 1.0.3 → 1.0.5

package/README.md

@@ -165,6 +165,7 @@ Hive uses a config file at `~/.config/opencode/agent_hive.json`. You can customi
 | `dispatching-parallel-agents` | Use when facing 2+ independent tasks. Dispatches multiple agents to work concurrently on unrelated problems. |
 | `test-driven-development` | Use when implementing any feature or bugfix. Enforces write-test-first, red-green-refactor cycle. |
 | `systematic-debugging` | Use when encountering any bug or test failure. Requires root cause investigation before proposing fixes. |
+| `code-reviewer` | Use when reviewing implementation changes against an approved plan or task to catch missing requirements, YAGNI, dead code, and risky patterns. |
 | `verification-before-completion` | Use before claiming work is complete. Requires running verification commands and confirming output before success claims. |
 
 #### Available MCPs
@@ -178,7 +179,7 @@ Hive uses a config file at `~/.config/opencode/agent_hive.json`. You can customi
 
 ### Per-Agent Skills
 
-Each agent can have specific skills enabled. If configured, only those skills are available:
+Each agent can have specific skills enabled. If configured, only those skills appear in `hive_skill()`:
 
 ```json
 {
@@ -205,7 +206,7 @@ Note: Wildcards like `["*"]` are **not supported** - use explicit skill names or
 
 ### Auto-load Skills
 
-Use `autoLoadSkills` to automatically inject skills into an agent's system prompt (in addition to any skills selected by the agent).
+Use `autoLoadSkills` to automatically inject skills into an agent's system prompt at session start.
 
 ```json
 {
@@ -221,6 +222,25 @@ Use `autoLoadSkills` to automatically inject skills into an agent's system promp
 }
 ```
 
+**Supported skill sources:**
+
+`autoLoadSkills` accepts both Hive builtin skill IDs and file-based skill IDs. Resolution order:
+
+1. **Hive builtin** — Skills bundled with opencode-hive (always win if ID matches)
+2. **Project OpenCode** — `<project>/.opencode/skills/<id>/SKILL.md`
+3. **Global OpenCode** — `~/.config/opencode/skills/<id>/SKILL.md`
+4. **Project Claude** — `<project>/.claude/skills/<id>/SKILL.md`
+5. **Global Claude** — `~/.claude/skills/<id>/SKILL.md`
+
+Skill IDs must be safe directory names (no `/`, `\`, `..`, or `.`). Missing or invalid skills emit a warning and are skipped—startup continues without failure.
+
+**How `skills` and `autoLoadSkills` interact:**
+
+- `skills` controls what appears in `hive_skill()` — the agent can manually load these on demand
+- `autoLoadSkills` injects skills unconditionally at session start — no manual loading needed
+- These are **independent**: a skill can be auto-loaded but not appear in `hive_skill()`, or vice versa
+- User `autoLoadSkills` are **merged** with defaults (use global `disableSkills` to remove defaults)
+
 **Default auto-load skills by agent:**
 
 | Agent | autoLoadSkills default |

package/dist/agents/hygienic.d.ts

@@ -4,7 +4,7 @@
  * Inspired by Momus from OmO (Greek god of satire who found fault in everything).
  * Reviews plans for documentation gaps, NOT design decisions.
  */
-export declare const HYGIENIC_BEE_PROMPT = "# Hygienic (Consultant/Reviewer/Debugger)\n\nNamed after Momus - finds fault in everything. Reviews DOCUMENTATION, not DESIGN.\n\n## Core Mandate\n\nReview plan WITHIN the stated approach. Question DOCUMENTATION gaps, NOT design decisions.\n\nSelf-check before every critique:\n> \"Am I questioning APPROACH or DOCUMENTATION?\"\n> APPROACH \u2192 Stay silent\n> DOCUMENTATION \u2192 Raise it\n\n## Four Core Criteria\n\n### 1. Clarity of Work Content\n- Are reference sources specified with file:lines?\n- Can the implementer find what they need?\n\n### 2. Verification & Acceptance Criteria\n- Are criteria measurable and concrete?\n- Red flags: \"should work\", \"looks good\", \"properly handles\"\n\n### 3. Context Completeness (90% Confidence)\n- Could a capable worker execute with 90% confidence?\n- What's missing that would drop below 90%?\n\n### 4. Big Picture & Workflow\n- Is the WHY clear (not just WHAT and HOW)?\n- Does the flow make sense?\n\n## Red Flags Table\n\n| Pattern | Problem |\n|---------|---------|\n| Vague verbs | \"Handle appropriately\", \"Process correctly\" |\n| Missing paths | Task mentions file but no path |\n| Subjective criteria | \"Should be clean\", \"Well-structured\" |\n| Assumed context | \"As discussed\", \"Obviously\" |\n| Magic numbers | Timeouts, limits without rationale |\n\n## Active Implementation Simulation\n\nBefore verdict, mentally execute 2-3 tasks:\n1. Pick a representative task\n2. Simulate: \"I'm starting this task now...\"\n3. Where do I get stuck? What's missing?\n4. Document gaps found\n\n## Output Format\n\n```\n[OKAY / REJECT]\n\n**Justification**: [one-line explanation]\n\n**Assessment**:\n- Clarity: [Good/Needs Work]\n- Verifiability: [Good/Needs Work]\n- Completeness: [Good/Needs Work]\n- Big Picture: [Good/Needs Work]\n\n[If REJECT - Top 3-5 Critical Improvements]:\n1. [Specific gap with location]\n2. [Specific gap with location]\n3. [Specific gap with location]\n```\n\n## When to OKAY vs REJECT\n\n| Situation | Verdict |\n|-----------|---------|\n| Minor gaps, easily inferred | OKAY with notes |\n| Design seems suboptimal | OKAY (not your call) |\n| Missing file paths for key tasks | REJECT |\n| Vague acceptance criteria | REJECT |\n| Unclear dependencies | REJECT |\n| Assumed context not documented | REJECT |\n\n## Iron Laws\n\n**Never:**\n- Reject based on design decisions\n- Suggest alternative architectures\n- Block on style preferences\n- Review implementation (plans only)\n\n**Always:**\n- Self-check: approach vs documentation\n- Simulate 2-3 tasks before verdict\n- Cite specific locations for gaps\n- Focus on worker success, not perfection\n";
+export declare const HYGIENIC_BEE_PROMPT = "# Hygienic (Consultant/Reviewer/Debugger)\n\nNamed after Momus - finds fault in everything. Reviews DOCUMENTATION, not DESIGN.\n\n## Core Mandate\n\nReview plan WITHIN the stated approach. Question DOCUMENTATION gaps, NOT design decisions.\n\nIf you are asked to review IMPLEMENTATION (code changes, diffs, PRs) instead of a plan:\n1. Load `hive_skill(\"code-reviewer\")`\n2. Apply it and return its output format\n3. Still do NOT edit code (review only)\n\nSelf-check before every critique:\n> \"Am I questioning APPROACH or DOCUMENTATION?\"\n> APPROACH \u2192 Stay silent\n> DOCUMENTATION \u2192 Raise it\n\n## Four Core Criteria\n\n### 1. Clarity of Work Content\n- Are reference sources specified with file:lines?\n- Can the implementer find what they need?\n\n### 2. Verification & Acceptance Criteria\n- Are criteria measurable and concrete?\n- Red flags: \"should work\", \"looks good\", \"properly handles\"\n\n### 3. Context Completeness (90% Confidence)\n- Could a capable worker execute with 90% confidence?\n- What's missing that would drop below 90%?\n\n### 4. Big Picture & Workflow\n- Is the WHY clear (not just WHAT and HOW)?\n- Does the flow make sense?\n\n## Red Flags Table\n\n| Pattern | Problem |\n|---------|---------|\n| Vague verbs | \"Handle appropriately\", \"Process correctly\" |\n| Missing paths | Task mentions file but no path |\n| Subjective criteria | \"Should be clean\", \"Well-structured\" |\n| Assumed context | \"As discussed\", \"Obviously\" |\n| Magic numbers | Timeouts, limits without rationale |\n\n## Active Implementation Simulation\n\nBefore verdict, mentally execute 2-3 tasks:\n1. Pick a representative task\n2. Simulate: \"I'm starting this task now...\"\n3. Where do I get stuck? What's missing?\n4. Document gaps found\n\n## Output Format\n\n```\n[OKAY / REJECT]\n\n**Justification**: [one-line explanation]\n\n**Assessment**:\n- Clarity: [Good/Needs Work]\n- Verifiability: [Good/Needs Work]\n- Completeness: [Good/Needs Work]\n- Big Picture: [Good/Needs Work]\n\n[If REJECT - Top 3-5 Critical Improvements]:\n1. [Specific gap with location]\n2. [Specific gap with location]\n3. [Specific gap with location]\n```\n\n## When to OKAY vs REJECT\n\n| Situation | Verdict |\n|-----------|---------|\n| Minor gaps, easily inferred | OKAY with notes |\n| Design seems suboptimal | OKAY (not your call) |\n| Missing file paths for key tasks | REJECT |\n| Vague acceptance criteria | REJECT |\n| Unclear dependencies | REJECT |\n| Assumed context not documented | REJECT |\n\n## Iron Laws\n\n**Never:**\n- Reject based on design decisions\n- Suggest alternative architectures\n- Block on style preferences\n- Review implementation unless explicitly asked (default is plans only)\n\n**Always:**\n- Self-check: approach vs documentation\n- Simulate 2-3 tasks before verdict\n- Cite specific locations for gaps\n- Focus on worker success, not perfection\n";
 export declare const hygienicBeeAgent: {
     name: string;
     description: string;

package/dist/index.js

@@ -14,6 +14,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/index.ts
 import * as path7 from "path";
 import * as fs9 from "fs";
+import * as os from "os";
 
 // ../../node_modules/zod/v4/classic/external.js
 var exports_external = {};
@@ -12336,7 +12337,7 @@ function tool(input) {
 }
 tool.schema = exports_external;
 // src/skills/registry.generated.ts
-var BUILTIN_SKILL_NAMES = ["brainstorming", "dispatching-parallel-agents", "executing-plans", "onboarding", "parallel-exploration", "systematic-debugging", "test-driven-development", "verification-before-completion", "writing-plans"];
+var BUILTIN_SKILL_NAMES = ["brainstorming", "code-reviewer", "dispatching-parallel-agents", "executing-plans", "onboarding", "parallel-exploration", "systematic-debugging", "test-driven-development", "verification-before-completion", "writing-plans"];
 var BUILTIN_SKILLS = [
   {
     name: "brainstorming",
@@ -12388,6 +12389,213 @@ Start by understanding the current project context, then ask questions one at a
 - **Explore alternatives** - Always propose 2-3 approaches before settling
 - **Incremental validation** - Present design in sections, validate each
 - **Be flexible** - Go back and clarify when something doesn't make sense`
+  },
+  {
+    name: "code-reviewer",
+    description: "Use when reviewing implementation changes against an approved plan or task (especially before merging or between Hive tasks) to catch missing requirements, YAGNI, dead code, and risky patterns",
+    template: `# Code Reviewer
+
+## Overview
+
+This skill teaches a reviewer to evaluate implementation changes for:
+- Adherence to the approved plan/task (did we build what we said?)
+- Correctness (does it work, including edge cases?)
+- Simplicity (YAGNI, dead code, over-abstraction)
+- Risk (security, performance, maintainability)
+
+**Core principle:** The best change is the smallest correct change that satisfies the plan.
+
+## Iron Laws
+
+- Review against the task/plan first. Code quality comes second.
+- Bias toward deletion and simplification. Every extra line is a liability.
+- Prefer changes that leverage existing patterns and dependencies.
+- Be specific: cite file paths and (when available) line numbers.
+- Do not invent requirements. If the plan/task is ambiguous, mark it and request clarification.
+
+## What Inputs You Need
+
+Minimum:
+- The task intent (1-3 sentences)
+- The plan/task requirements (or a link/path to plan section)
+- The code changes (diff or list of changed files)
+
+If available (recommended):
+- Acceptance criteria / verification steps from the plan
+- Test output or proof the change was verified
+- Any relevant context files (design decisions, constraints)
+
+## Review Process (In Order)
+
+### 1) Identify Scope
+
+1. List all files changed.
+2. For each file, state why it changed (what requirement it serves).
+3. Flag any changes that do not map to the task/plan.
+
+**Rule:** If you cannot map a change to a requirement, treat it as suspicious until justified.
+
+### 2) Plan/Task Adherence (Non-Negotiable)
+
+Create a simple checklist:
+- What the task says must happen
+- Evidence in code/tests that it happens
+
+Flag as issues:
+- Missing requirements (implemented behavior does not match intent)
+- Partial implementation with no follow-up task (TODO-driven shipping)
+- Behavior changes that are not in the plan/task
+
+### 3) Correctness Layer
+
+Review for:
+- Edge cases and error paths
+- Incorrect assumptions about inputs/types
+- Inconsistent behavior across platforms/environments
+- Broken invariants (e.g., state can become invalid)
+
+Prefer "fail fast, fail loud": invalid states should become clear errors, not silent fallbacks.
+
+### 4) Simplicity / YAGNI Layer
+
+Be ruthless and concrete:
+- Remove dead branches, unused flags/options, unreachable code
+- Remove speculative TODOs and "reserved for future" scaffolding
+- Remove comments that restate the code or narrate obvious steps
+- Inline one-off abstractions (helpers/classes/interfaces used once)
+- Replace cleverness with obvious code
+- Reduce nesting with guard clauses / early returns
+
+Prefer clarity over brevity:
+- Avoid nested ternary operators; use \`if/else\` or \`switch\` when branches matter
+- Avoid dense one-liners that hide intent or make debugging harder
+
+### 4b) De-Slop Pass (AI Artifacts / Style Drift)
+
+Scan the diff (not just the final code) for AI-generated slop introduced in this branch:
+- Extra comments that a human would not add, or that do not match the file's tone
+- Defensive checks or try/catch blocks that are abnormal for that area of the codebase
+  - Especially swallowed errors ("ignore and continue") and silent fallbacks
+  - Especially redundant validation in trusted internal codepaths
+- TypeScript escape hatches used to dodge type errors (\`as any\`, \`as unknown as X\`) without necessity
+- Style drift: naming, error handling patterns, logging style, and structure inconsistent with nearby code
+
+Default stance:
+- Prefer deletion over justification.
+- If validation is needed, do it at boundaries; keep internals trusting parsed inputs.
+- If a cast is truly unavoidable, localize it and keep the justification to a single short note.
+
+When recommending simplifications, do not accidentally change behavior. If the current behavior is unclear, request clarification or ask for a test that pins it down.
+
+**Default stance:** Do not add extensibility points without an explicit current requirement.
+
+### 5) Risk Layer (Security / Performance / Maintainability)
+
+Only report what you are confident about.
+
+Security checks (examples):
+- No secrets in code/logs
+- No injection vectors (shell/SQL/HTML) introduced
+- Authz/authn checks preserved
+- Sensitive data not leaked
+
+Performance checks (examples):
+- Avoid unnecessary repeated work (N+1 queries, repeated parsing, repeated filesystem hits)
+- Avoid obvious hot-path allocations or large sync operations
+
+Maintainability checks:
+- Clear naming and intent
+- Consistent error handling
+- API boundaries not blurred
+- Consistent with local file patterns (imports, export style, function style)
+
+### 6) Make One Primary Recommendation
+
+Provide one clear path to reach approval.
+Mention alternatives only when they have materially different trade-offs.
+
+### 7) Signal the Investment
+
+Tag the required follow-up effort using:
+- Quick (<1h)
+- Short (1-4h)
+- Medium (1-2d)
+- Large (3d+)
+
+## Confidence Filter
+
+Only report findings you believe are >=80% likely to be correct.
+If you are unsure, explicitly label it as "Uncertain" and explain what evidence would confirm it.
+
+## Output Format (Use This Exactly)
+
+---
+
+**Files Reviewed:** [list]
+
+**Plan/Task Reference:** [task name + link/path to plan section if known]
+
+**Overall Assessment:** [APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION]
+
+**Bottom Line:** 2-3 sentences describing whether it matches the task/plan and what must change.
+
+### Critical Issues
+- None | [file:line] - [issue] (why it blocks approval) + (recommended fix)
+
+### Major Issues
+- None | [file:line] - [issue] + (recommended fix)
+
+### Minor Issues
+- None | [file:line] - [issue] + (suggested fix)
+
+### YAGNI / Dead Code
+- None | [file:line] - [what to remove/simplify] + (why it is unnecessary)
+
+### Positive Observations
+- [at least one concrete good thing]
+
+### Action Plan
+1. [highest priority change]
+2. [next]
+3. [next]
+
+### Effort Estimate
+[Quick | Short | Medium | Large]
+
+---
+
+## Common Review Smells (Fast Scan)
+
+Task/plan adherence:
+- Adds features not mentioned in the plan/task
+- Leaves TODOs as the mechanism for correctness
+- Introduces new configuration modes/flags "for future"
+
+YAGNI / dead code:
+- Options/config that are parsed but not used
+- Branches that do the same thing on both sides
+- Comments like "reserved for future" or "we might need this"
+
+AI slop / inconsistency:
+- Commentary that restates code, narrates obvious steps, or adds process noise
+- try/catch that swallows errors or returns defaults without a requirement
+- \`as any\` used to silence type errors instead of fixing types
+- New helpers/abstractions with a single call site
+
+Correctness:
+- Silent fallbacks to defaults on error when the task expects a hard failure
+- Unhandled error paths, missing cleanup, missing returns
+
+Maintainability:
+- Abstractions used once
+- Unclear naming, "utility" grab-bags
+
+## When to Escalate
+
+Use NEEDS_DISCUSSION (instead of REQUEST_CHANGES) when:
+- The plan/task is ambiguous and multiple implementations could be correct
+- The change implies a product/architecture decision not documented
+- Fixing issues requires changing scope, dependencies, or public API`
   },
   {
     name: "dispatching-parallel-agents",
@@ -13933,6 +14141,107 @@ function getFilteredSkills(disabledSkills = [], agentSkills) {
   return filtered;
 }
 
+// src/skills/file-loader.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+function validateSkillId(skillId) {
+  if (!skillId || skillId.trim() === "") {
+    return "Skill ID cannot be empty";
+  }
+  if (skillId.includes("/")) {
+    return `Invalid skill ID "${skillId}": contains path traversal character "/"`;
+  }
+  if (skillId.includes("\\")) {
+    return `Invalid skill ID "${skillId}": contains path traversal character "\\"`;
+  }
+  if (skillId.includes("..")) {
+    return `Invalid skill ID "${skillId}": contains path traversal sequence ".."`;
+  }
+  if (skillId === "." || skillId.includes(".")) {
+    return `Invalid skill ID "${skillId}": contains path traversal character "."`;
+  }
+  return;
+}
+function stripQuotes(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match)
+    return null;
+  const frontmatter = match[1];
+  const body = match[2];
+  const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+  const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+  if (!nameMatch || !descMatch)
+    return null;
+  return {
+    name: stripQuotes(nameMatch[1]),
+    description: stripQuotes(descMatch[1]),
+    body
+  };
+}
+function getSearchPaths(skillId, projectRoot, homeDir) {
+  return [
+    path.join(projectRoot, ".opencode", "skills", skillId, "SKILL.md"),
+    path.join(homeDir, ".config", "opencode", "skills", skillId, "SKILL.md"),
+    path.join(projectRoot, ".claude", "skills", skillId, "SKILL.md"),
+    path.join(homeDir, ".claude", "skills", skillId, "SKILL.md")
+  ];
+}
+async function tryReadFile(filePath) {
+  try {
+    const content = await fs.readFile(filePath, "utf-8");
+    return content;
+  } catch {
+    return null;
+  }
+}
+async function loadFileSkill(skillId, projectRoot, homeDir) {
+  const validationError = validateSkillId(skillId);
+  if (validationError) {
+    return { found: false, error: validationError };
+  }
+  const searchPaths = getSearchPaths(skillId, projectRoot, homeDir);
+  for (const skillPath of searchPaths) {
+    const content = await tryReadFile(skillPath);
+    if (content === null) {
+      continue;
+    }
+    const parsed = parseFrontmatter(content);
+    if (!parsed) {
+      return {
+        found: false,
+        error: `Invalid frontmatter in skill file: ${skillPath}. Expected YAML frontmatter with "name" and "description" fields.`
+      };
+    }
+    if (parsed.name !== skillId) {
+      return {
+        found: false,
+        error: `Skill name mismatch in ${skillPath}: frontmatter name "${parsed.name}" does not match skill ID "${skillId}"`
+      };
+    }
+    const skill = {
+      name: parsed.name,
+      description: parsed.description,
+      template: parsed.body
+    };
+    return {
+      found: true,
+      skill,
+      source: skillPath
+    };
+  }
+  return {
+    found: false,
+    error: `Skill "${skillId}" not found in any of the search paths`
+  };
+}
+
 // src/agents/hive.ts
 var QUEEN_BEE_PROMPT = `# Hive (Hybrid)
 
@@ -14535,6 +14844,11 @@ Named after Momus - finds fault in everything. Reviews DOCUMENTATION, not DESIGN
 
 Review plan WITHIN the stated approach. Question DOCUMENTATION gaps, NOT design decisions.
 
+If you are asked to review IMPLEMENTATION (code changes, diffs, PRs) instead of a plan:
+1. Load \`hive_skill("code-reviewer")\`
+2. Apply it and return its output format
+3. Still do NOT edit code (review only)
+
 Self-check before every critique:
 > "Am I questioning APPROACH or DOCUMENTATION?"
 > APPROACH → Stay silent
@@ -14612,7 +14926,7 @@ Before verdict, mentally execute 2-3 tasks:
 - Reject based on design decisions
 - Suggest alternative architectures
 - Block on style preferences
-- Review implementation (plans only)
+- Review implementation unless explicitly asked (default is plans only)
 
 **Always:**
 - Self-check: approach vs documentation
@@ -14663,10 +14977,10 @@ var createBuiltinMcps = (disabledMcps = []) => {
 
 // ../hive-core/dist/index.js
 import { createRequire as createRequire2 } from "node:module";
-import * as path from "path";
-import * as fs from "fs";
 import * as path2 from "path";
 import * as fs2 from "fs";
+import * as path22 from "path";
+import * as fs22 from "fs";
 import * as fs3 from "fs";
 import * as fs4 from "fs";
 import * as fs5 from "fs";
@@ -15556,7 +15870,7 @@ var DEFAULT_HIVE_CONFIG = {
     "hygienic-reviewer": {
       model: DEFAULT_AGENT_MODELS["hygienic-reviewer"],
       temperature: 0.3,
-      skills: ["systematic-debugging"],
+      skills: ["systematic-debugging", "code-reviewer"],
       autoLoadSkills: []
     }
   }
@@ -15572,82 +15886,85 @@ var STATUS_FILE = "status.json";
 var REPORT_FILE = "report.md";
 var APPROVED_FILE = "APPROVED";
 var JOURNAL_FILE = "journal.md";
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
 function getHivePath(projectRoot) {
-  return path.join(projectRoot, HIVE_DIR);
+  return path2.join(projectRoot, HIVE_DIR);
 }
 function getJournalPath(projectRoot) {
-  return path.join(getHivePath(projectRoot), JOURNAL_FILE);
+  return path2.join(getHivePath(projectRoot), JOURNAL_FILE);
 }
 function getFeaturesPath(projectRoot) {
-  return path.join(getHivePath(projectRoot), FEATURES_DIR);
+  return path2.join(getHivePath(projectRoot), FEATURES_DIR);
 }
 function getFeaturePath(projectRoot, featureName) {
-  return path.join(getFeaturesPath(projectRoot), featureName);
+  return path2.join(getFeaturesPath(projectRoot), featureName);
 }
 function getPlanPath(projectRoot, featureName) {
-  return path.join(getFeaturePath(projectRoot, featureName), PLAN_FILE);
+  return path2.join(getFeaturePath(projectRoot, featureName), PLAN_FILE);
 }
 function getCommentsPath(projectRoot, featureName) {
-  return path.join(getFeaturePath(projectRoot, featureName), COMMENTS_FILE);
+  return path2.join(getFeaturePath(projectRoot, featureName), COMMENTS_FILE);
 }
 function getFeatureJsonPath(projectRoot, featureName) {
-  return path.join(getFeaturePath(projectRoot, featureName), FEATURE_FILE);
+  return path2.join(getFeaturePath(projectRoot, featureName), FEATURE_FILE);
 }
 function getContextPath(projectRoot, featureName) {
-  return path.join(getFeaturePath(projectRoot, featureName), CONTEXT_DIR);
+  return path2.join(getFeaturePath(projectRoot, featureName), CONTEXT_DIR);
 }
 function getTasksPath(projectRoot, featureName) {
-  return path.join(getFeaturePath(projectRoot, featureName), TASKS_DIR);
+  return path2.join(getFeaturePath(projectRoot, featureName), TASKS_DIR);
 }
 function getTaskPath(projectRoot, featureName, taskFolder) {
-  return path.join(getTasksPath(projectRoot, featureName), taskFolder);
+  return path2.join(getTasksPath(projectRoot, featureName), taskFolder);
 }
 function getTaskStatusPath(projectRoot, featureName, taskFolder) {
-  return path.join(getTaskPath(projectRoot, featureName, taskFolder), STATUS_FILE);
+  return path2.join(getTaskPath(projectRoot, featureName, taskFolder), STATUS_FILE);
 }
 function getTaskReportPath(projectRoot, featureName, taskFolder) {
-  return path.join(getTaskPath(projectRoot, featureName, taskFolder), REPORT_FILE);
+  return path2.join(getTaskPath(projectRoot, featureName, taskFolder), REPORT_FILE);
 }
 function getTaskSpecPath(projectRoot, featureName, taskFolder) {
-  return path.join(getTaskPath(projectRoot, featureName, taskFolder), "spec.md");
+  return path2.join(getTaskPath(projectRoot, featureName, taskFolder), "spec.md");
 }
 function getApprovedPath(projectRoot, featureName) {
-  return path.join(getFeaturePath(projectRoot, featureName), APPROVED_FILE);
+  return path2.join(getFeaturePath(projectRoot, featureName), APPROVED_FILE);
 }
 var SUBTASKS_DIR = "subtasks";
 var SPEC_FILE = "spec.md";
 function getSubtasksPath(projectRoot, featureName, taskFolder) {
-  return path.join(getTaskPath(projectRoot, featureName, taskFolder), SUBTASKS_DIR);
+  return path2.join(getTaskPath(projectRoot, featureName, taskFolder), SUBTASKS_DIR);
 }
 function getSubtaskPath(projectRoot, featureName, taskFolder, subtaskFolder) {
-  return path.join(getSubtasksPath(projectRoot, featureName, taskFolder), subtaskFolder);
+  return path2.join(getSubtasksPath(projectRoot, featureName, taskFolder), subtaskFolder);
 }
 function getSubtaskStatusPath(projectRoot, featureName, taskFolder, subtaskFolder) {
-  return path.join(getSubtaskPath(projectRoot, featureName, taskFolder, subtaskFolder), STATUS_FILE);
+  return path2.join(getSubtaskPath(projectRoot, featureName, taskFolder, subtaskFolder), STATUS_FILE);
 }
 function getSubtaskSpecPath(projectRoot, featureName, taskFolder, subtaskFolder) {
-  return path.join(getSubtaskPath(projectRoot, featureName, taskFolder, subtaskFolder), SPEC_FILE);
+  return path2.join(getSubtaskPath(projectRoot, featureName, taskFolder, subtaskFolder), SPEC_FILE);
 }
 function getSubtaskReportPath(projectRoot, featureName, taskFolder, subtaskFolder) {
-  return path.join(getSubtaskPath(projectRoot, featureName, taskFolder, subtaskFolder), REPORT_FILE);
+  return path2.join(getSubtaskPath(projectRoot, featureName, taskFolder, subtaskFolder), REPORT_FILE);
 }
 function ensureDir(dirPath) {
-  if (!fs.existsSync(dirPath)) {
-    fs.mkdirSync(dirPath, { recursive: true });
+  if (!fs2.existsSync(dirPath)) {
+    fs2.mkdirSync(dirPath, { recursive: true });
   }
 }
 function fileExists(filePath) {
-  return fs.existsSync(filePath);
+  return fs2.existsSync(filePath);
 }
 function readJson(filePath) {
-  if (!fs.existsSync(filePath))
+  if (!fs2.existsSync(filePath))
     return null;
-  const content = fs.readFileSync(filePath, "utf-8");
+  const content = fs2.readFileSync(filePath, "utf-8");
   return JSON.parse(content);
 }
 function writeJson(filePath, data) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+  ensureDir(path2.dirname(filePath));
+  fs2.writeFileSync(filePath, JSON.stringify(data, null, 2));
 }
 var DEFAULT_LOCK_OPTIONS = {
   timeout: 5000,
@@ -15659,7 +15976,7 @@ function getLockPath(filePath) {
 }
 function isLockStale(lockPath, staleTTL) {
   try {
-    const stat2 = fs.statSync(lockPath);
+    const stat2 = fs2.statSync(lockPath);
     const age = Date.now() - stat2.mtimeMs;
     return age > staleTTL;
   } catch {
@@ -15677,12 +15994,12 @@ function acquireLockSync(filePath, options = {}) {
   });
   while (true) {
     try {
-      const fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
-      fs.writeSync(fd, lockContent);
-      fs.closeSync(fd);
+      const fd = fs2.openSync(lockPath, fs2.constants.O_CREAT | fs2.constants.O_EXCL | fs2.constants.O_WRONLY);
+      fs2.writeSync(fd, lockContent);
+      fs2.closeSync(fd);
       return () => {
         try {
-          fs.unlinkSync(lockPath);
+          fs2.unlinkSync(lockPath);
         } catch {}
       };
     } catch (err) {
@@ -15692,7 +16009,7 @@ function acquireLockSync(filePath, options = {}) {
       }
       if (isLockStale(lockPath, opts.staleLockTTL)) {
         try {
-          fs.unlinkSync(lockPath);
+          fs2.unlinkSync(lockPath);
           continue;
         } catch {}
       }
@@ -15705,14 +16022,14 @@ function acquireLockSync(filePath, options = {}) {
   }
 }
 function writeAtomic(filePath, content) {
-  ensureDir(path.dirname(filePath));
+  ensureDir(path2.dirname(filePath));
   const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
   try {
-    fs.writeFileSync(tempPath, content);
-    fs.renameSync(tempPath, filePath);
+    fs2.writeFileSync(tempPath, content);
+    fs2.renameSync(tempPath, filePath);
   } catch (error45) {
     try {
-      fs.unlinkSync(tempPath);
+      fs2.unlinkSync(tempPath);
     } catch {}
     throw error45;
   }
@@ -15755,13 +16072,13 @@ function patchJsonLockedSync(filePath, patch, options = {}) {
   }
 }
 function readText(filePath) {
-  if (!fs.existsSync(filePath))
+  if (!fs2.existsSync(filePath))
     return null;
-  return fs.readFileSync(filePath, "utf-8");
+  return fs2.readFileSync(filePath, "utf-8");
 }
 function writeText(filePath, content) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, content);
+  ensureDir(path2.dirname(filePath));
+  fs2.writeFileSync(filePath, content);
 }
 function detectContext(cwd) {
   const result = {
@@ -15771,7 +16088,8 @@ function detectContext(cwd) {
     isWorktree: false,
     mainProjectRoot: null
   };
-  const worktreeMatch = cwd.match(/(.+)\/\.hive\/\.worktrees\/([^/]+)\/([^/]+)/);
+  const normalizedCwd = normalizePath(cwd);
+  const worktreeMatch = normalizedCwd.match(/(.+)\/\.hive\/\.worktrees\/([^/]+)\/([^/]+)/);
   if (worktreeMatch) {
     result.mainProjectRoot = worktreeMatch[1];
     result.feature = worktreeMatch[2];
@@ -15780,18 +16098,19 @@ function detectContext(cwd) {
     result.projectRoot = worktreeMatch[1];
     return result;
   }
-  const gitPath = path2.join(cwd, ".git");
-  if (fs2.existsSync(gitPath)) {
-    const stat2 = fs2.statSync(gitPath);
+  const gitPath = path22.join(cwd, ".git");
+  if (fs22.existsSync(gitPath)) {
+    const stat2 = fs22.statSync(gitPath);
     if (stat2.isFile()) {
-      const gitContent = fs2.readFileSync(gitPath, "utf-8").trim();
+      const gitContent = fs22.readFileSync(gitPath, "utf-8").trim();
       const gitdirMatch = gitContent.match(/gitdir:\s*(.+)/);
       if (gitdirMatch) {
         const gitdir = gitdirMatch[1];
-        const worktreePathMatch = gitdir.match(/(.+)\/\.git\/worktrees\/(.+)/);
+        const normalizedGitdir = normalizePath(gitdir);
+        const worktreePathMatch = normalizedGitdir.match(/(.+)\/\.git\/worktrees\/(.+)/);
         if (worktreePathMatch) {
           const mainRepo = worktreePathMatch[1];
-          const cwdWorktreeMatch = cwd.match(/\.hive\/\.worktrees\/([^/]+)\/([^/]+)/);
+          const cwdWorktreeMatch = normalizedCwd.match(/\.hive\/\.worktrees\/([^/]+)\/([^/]+)/);
           if (cwdWorktreeMatch) {
             result.mainProjectRoot = mainRepo;
             result.feature = cwdWorktreeMatch[1];
@@ -15808,9 +16127,9 @@ function detectContext(cwd) {
 }
 function listFeatures(projectRoot) {
   const featuresPath = getFeaturesPath(projectRoot);
-  if (!fs2.existsSync(featuresPath))
+  if (!fs22.existsSync(featuresPath))
     return [];
-  return fs2.readdirSync(featuresPath, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  return fs22.readdirSync(featuresPath, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
 }
 var JOURNAL_TEMPLATE = `# Hive Journal
 
@@ -21470,7 +21789,13 @@ function isValidPromptFilePath(filePath, workspaceRoot) {
   try {
     const normalizedFilePath = path5.resolve(filePath);
     const normalizedWorkspace = path5.resolve(workspaceRoot);
-    if (!normalizedFilePath.startsWith(normalizedWorkspace + path5.sep) && normalizedFilePath !== normalizedWorkspace) {
+    let normalizedFilePathForCompare = normalizePath(normalizedFilePath);
+    let normalizedWorkspaceForCompare = normalizePath(normalizedWorkspace);
+    if (process.platform === "win32") {
+      normalizedFilePathForCompare = normalizedFilePathForCompare.toLowerCase();
+      normalizedWorkspaceForCompare = normalizedWorkspaceForCompare.toLowerCase();
+    }
+    if (!normalizedFilePathForCompare.startsWith(normalizedWorkspaceForCompare + "/") && normalizedFilePathForCompare !== normalizedWorkspaceForCompare) {
       return false;
     }
     return true;
@@ -22891,6 +23216,36 @@ function formatSkillsXml(skills) {
 ${skillsXml}
 </available_skills>`;
 }
+async function buildAutoLoadedSkillsContent(agentName, configService, projectRoot) {
+  const agentConfig = configService.getAgentConfig(agentName);
+  const autoLoadSkills = agentConfig.autoLoadSkills ?? [];
+  if (autoLoadSkills.length === 0) {
+    return "";
+  }
+  const homeDir = process.env.HOME || os.homedir();
+  const skillTemplates = [];
+  for (const skillId of autoLoadSkills) {
+    const builtinSkill = BUILTIN_SKILLS.find((entry) => entry.name === skillId);
+    if (builtinSkill) {
+      skillTemplates.push(builtinSkill.template);
+      continue;
+    }
+    const fileResult = await loadFileSkill(skillId, projectRoot, homeDir);
+    if (fileResult.found && fileResult.skill) {
+      skillTemplates.push(fileResult.skill.template);
+      continue;
+    }
+    console.warn(`[hive] Unknown skill id "${skillId}" for agent "${agentName}"`);
+  }
+  if (skillTemplates.length === 0) {
+    return "";
+  }
+  return `
+
+` + skillTemplates.join(`
+
+`);
+}
 function createHiveSkillTool(filteredSkills) {
   const base = `Load a Hive skill to get detailed instructions for a specific workflow.
 
@@ -23072,22 +23427,6 @@ To unblock: Remove .hive/features/${feature}/BLOCKED`;
   return {
     "experimental.chat.system.transform": async (input, output) => {
       output.system.push(HIVE_SYSTEM_PROMPT);
-      const agentInput = input;
-      const agentName = agentInput?.agent;
-      if (agentName && isHiveAgent(agentName)) {
-        const agentConfig = configService.getAgentConfig(agentName);
-        const autoLoadSkills = agentConfig.autoLoadSkills ?? [];
-        if (autoLoadSkills.length > 0) {
-          for (const skillId of autoLoadSkills) {
-            const skill = BUILTIN_SKILLS.find((entry) => entry.name === skillId);
-            if (!skill) {
-              console.warn("Unknown skill id", skillId);
-              continue;
-            }
-            output.system.push(skill.template);
-          }
-        }
-      }
       const activeFeature = resolveFeature();
       if (activeFeature) {
         const info = featureService.getInfo(activeFeature);
@@ -23485,7 +23824,7 @@ ${priorTasksFormatted}
           });
           const hiveDir = path7.join(directory, ".hive");
           const workerPromptPath = writeWorkerPromptFile(feature, task, workerPrompt, hiveDir);
-          const relativePromptPath = path7.relative(directory, workerPromptPath);
+          const relativePromptPath = normalizePath(path7.relative(directory, workerPromptPath));
           const PREVIEW_MAX_LENGTH = 200;
           const workerPromptPreview = workerPrompt.length > PREVIEW_MAX_LENGTH ? workerPrompt.slice(0, PREVIEW_MAX_LENGTH) + "..." : workerPrompt;
           const hiveBackgroundInstructions = `## Delegation Required
@@ -24042,11 +24381,12 @@ Make the requested changes, then call hive_request_review again.`;
     config: async (opencodeConfig) => {
       configService.init();
       const hiveUserConfig = configService.getAgentConfig("hive-master");
+      const hiveAutoLoadedSkills = await buildAutoLoadedSkillsContent("hive-master", configService, directory);
       const hiveConfig = {
         model: hiveUserConfig.model,
         temperature: hiveUserConfig.temperature ?? 0.5,
         description: "Hive (Hybrid) - Plans + orchestrates. Detects phase, loads skills on-demand.",
-        prompt: QUEEN_BEE_PROMPT,
+        prompt: QUEEN_BEE_PROMPT + hiveAutoLoadedSkills,
         permission: {
           question: "allow",
           skill: "allow",
@@ -24058,11 +24398,12 @@ Make the requested changes, then call hive_request_review again.`;
         }
       };
       const architectUserConfig = configService.getAgentConfig("architect-planner");
+      const architectAutoLoadedSkills = await buildAutoLoadedSkillsContent("architect-planner", configService, directory);
       const architectConfig = {
         model: architectUserConfig.model,
         temperature: architectUserConfig.temperature ?? 0.7,
         description: "Architect (Planner) - Plans features, interviews, writes plans. NEVER executes.",
-        prompt: ARCHITECT_BEE_PROMPT,
+        prompt: ARCHITECT_BEE_PROMPT + architectAutoLoadedSkills,
         permission: {
           edit: "deny",
           task: "deny",
@@ -24077,11 +24418,12 @@ Make the requested changes, then call hive_request_review again.`;
         }
       };
       const swarmUserConfig = configService.getAgentConfig("swarm-orchestrator");
+      const swarmAutoLoadedSkills = await buildAutoLoadedSkillsContent("swarm-orchestrator", configService, directory);
       const swarmConfig = {
         model: swarmUserConfig.model,
         temperature: swarmUserConfig.temperature ?? 0.5,
         description: "Swarm (Orchestrator) - Orchestrates execution. Delegates, spawns workers, verifies, merges.",
-        prompt: SWARM_BEE_PROMPT,
+        prompt: SWARM_BEE_PROMPT + swarmAutoLoadedSkills,
         permission: {
           question: "allow",
           skill: "allow",
@@ -24093,12 +24435,13 @@ Make the requested changes, then call hive_request_review again.`;
         }
       };
       const scoutUserConfig = configService.getAgentConfig("scout-researcher");
+      const scoutAutoLoadedSkills = await buildAutoLoadedSkillsContent("scout-researcher", configService, directory);
       const scoutConfig = {
         model: scoutUserConfig.model,
         temperature: scoutUserConfig.temperature ?? 0.5,
         mode: "subagent",
         description: "Scout (Explorer/Researcher/Retrieval) - Researches codebase + external docs/data.",
-        prompt: SCOUT_BEE_PROMPT,
+        prompt: SCOUT_BEE_PROMPT + scoutAutoLoadedSkills,
         permission: {
           edit: "deny",
           skill: "allow",
@@ -24106,23 +24449,25 @@ Make the requested changes, then call hive_request_review again.`;
         }
       };
       const foragerUserConfig = configService.getAgentConfig("forager-worker");
+      const foragerAutoLoadedSkills = await buildAutoLoadedSkillsContent("forager-worker", configService, directory);
       const foragerConfig = {
         model: foragerUserConfig.model,
         temperature: foragerUserConfig.temperature ?? 0.3,
         mode: "subagent",
         description: "Forager (Worker/Coder) - Executes tasks directly in isolated worktrees. Never delegates.",
-        prompt: FORAGER_BEE_PROMPT,
+        prompt: FORAGER_BEE_PROMPT + foragerAutoLoadedSkills,
         permission: {
           skill: "allow"
         }
       };
       const hygienicUserConfig = configService.getAgentConfig("hygienic-reviewer");
+      const hygienicAutoLoadedSkills = await buildAutoLoadedSkillsContent("hygienic-reviewer", configService, directory);
       const hygienicConfig = {
         model: hygienicUserConfig.model,
         temperature: hygienicUserConfig.temperature ?? 0.3,
         mode: "subagent",
         description: "Hygienic (Consultant/Reviewer/Debugger) - Reviews plan documentation quality. OKAY/REJECT verdict.",
-        prompt: HYGIENIC_BEE_PROMPT,
+        prompt: HYGIENIC_BEE_PROMPT + hygienicAutoLoadedSkills,
         permission: {
           edit: "deny",
           skill: "allow"

package/dist/skills/file-loader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * File-based Skill Loader
+ *
+ * Resolves and loads skill files from OpenCode and Claude-compatible paths.
+ * Implements strict skill ID validation and deterministic search order.
+ */
+import type { SkillLoadResult } from './types.js';
+/**
+ * Load a skill from file-based locations.
+ *
+ * Searches for skill files in the following order:
+ * 1. Project OpenCode: `<projectRoot>/.opencode/skills/<skillId>/SKILL.md`
+ * 2. Global OpenCode: `~/.config/opencode/skills/<skillId>/SKILL.md`
+ * 3. Project Claude-compatible: `<projectRoot>/.claude/skills/<skillId>/SKILL.md`
+ * 4. Global Claude-compatible: `~/.claude/skills/<skillId>/SKILL.md`
+ *
+ * @param skillId - The skill ID to load
+ * @param projectRoot - The project root directory
+ * @param homeDir - The user's home directory
+ * @returns The skill load result
+ */
+export declare function loadFileSkill(skillId: string, projectRoot: string, homeDir: string): Promise<SkillLoadResult>;

package/dist/skills/index.d.ts

@@ -5,3 +5,4 @@
  */
 export type { SkillDefinition, SkillLoadResult } from './types.js';
 export { BUILTIN_SKILLS, loadBuiltinSkill, getBuiltinSkills, getFilteredSkills, getBuiltinSkillsXml, type BuiltinSkillName } from './builtin.js';
+export { loadFileSkill } from './file-loader.js';

package/dist/skills/registry.generated.d.ts

@@ -7,7 +7,7 @@ import type { SkillDefinition } from './types.js';
 /**
  * List of builtin skill names.
  */
-export declare const BUILTIN_SKILL_NAMES: readonly ["brainstorming", "dispatching-parallel-agents", "executing-plans", "onboarding", "parallel-exploration", "systematic-debugging", "test-driven-development", "verification-before-completion", "writing-plans"];
+export declare const BUILTIN_SKILL_NAMES: readonly ["brainstorming", "code-reviewer", "dispatching-parallel-agents", "executing-plans", "onboarding", "parallel-exploration", "systematic-debugging", "test-driven-development", "verification-before-completion", "writing-plans"];
 /**
  * All builtin skill definitions.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-hive",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "OpenCode plugin for Agent Hive - from vibe coding to hive coding",
   "license": "MIT WITH Commons-Clause",

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: code-reviewer
+description: Use when reviewing implementation changes against an approved plan or task (especially before merging or between Hive tasks) to catch missing requirements, YAGNI, dead code, and risky patterns
+---
+
+# Code Reviewer
+
+## Overview
+
+This skill teaches a reviewer to evaluate implementation changes for:
+- Adherence to the approved plan/task (did we build what we said?)
+- Correctness (does it work, including edge cases?)
+- Simplicity (YAGNI, dead code, over-abstraction)
+- Risk (security, performance, maintainability)
+
+**Core principle:** The best change is the smallest correct change that satisfies the plan.
+
+## Iron Laws
+
+- Review against the task/plan first. Code quality comes second.
+- Bias toward deletion and simplification. Every extra line is a liability.
+- Prefer changes that leverage existing patterns and dependencies.
+- Be specific: cite file paths and (when available) line numbers.
+- Do not invent requirements. If the plan/task is ambiguous, mark it and request clarification.
+
+## What Inputs You Need
+
+Minimum:
+- The task intent (1-3 sentences)
+- The plan/task requirements (or a link/path to plan section)
+- The code changes (diff or list of changed files)
+
+If available (recommended):
+- Acceptance criteria / verification steps from the plan
+- Test output or proof the change was verified
+- Any relevant context files (design decisions, constraints)
+
+## Review Process (In Order)
+
+### 1) Identify Scope
+
+1. List all files changed.
+2. For each file, state why it changed (what requirement it serves).
+3. Flag any changes that do not map to the task/plan.
+
+**Rule:** If you cannot map a change to a requirement, treat it as suspicious until justified.
+
+### 2) Plan/Task Adherence (Non-Negotiable)
+
+Create a simple checklist:
+- What the task says must happen
+- Evidence in code/tests that it happens
+
+Flag as issues:
+- Missing requirements (implemented behavior does not match intent)
+- Partial implementation with no follow-up task (TODO-driven shipping)
+- Behavior changes that are not in the plan/task
+
+### 3) Correctness Layer
+
+Review for:
+- Edge cases and error paths
+- Incorrect assumptions about inputs/types
+- Inconsistent behavior across platforms/environments
+- Broken invariants (e.g., state can become invalid)
+
+Prefer "fail fast, fail loud": invalid states should become clear errors, not silent fallbacks.
+
+### 4) Simplicity / YAGNI Layer
+
+Be ruthless and concrete:
+- Remove dead branches, unused flags/options, unreachable code
+- Remove speculative TODOs and "reserved for future" scaffolding
+- Remove comments that restate the code or narrate obvious steps
+- Inline one-off abstractions (helpers/classes/interfaces used once)
+- Replace cleverness with obvious code
+- Reduce nesting with guard clauses / early returns
+
+Prefer clarity over brevity:
+- Avoid nested ternary operators; use `if/else` or `switch` when branches matter
+- Avoid dense one-liners that hide intent or make debugging harder
+
+### 4b) De-Slop Pass (AI Artifacts / Style Drift)
+
+Scan the diff (not just the final code) for AI-generated slop introduced in this branch:
+- Extra comments that a human would not add, or that do not match the file's tone
+- Defensive checks or try/catch blocks that are abnormal for that area of the codebase
+  - Especially swallowed errors ("ignore and continue") and silent fallbacks
+  - Especially redundant validation in trusted internal codepaths
+- TypeScript escape hatches used to dodge type errors (`as any`, `as unknown as X`) without necessity
+- Style drift: naming, error handling patterns, logging style, and structure inconsistent with nearby code
+
+Default stance:
+- Prefer deletion over justification.
+- If validation is needed, do it at boundaries; keep internals trusting parsed inputs.
+- If a cast is truly unavoidable, localize it and keep the justification to a single short note.
+
+When recommending simplifications, do not accidentally change behavior. If the current behavior is unclear, request clarification or ask for a test that pins it down.
+
+**Default stance:** Do not add extensibility points without an explicit current requirement.
+
+### 5) Risk Layer (Security / Performance / Maintainability)
+
+Only report what you are confident about.
+
+Security checks (examples):
+- No secrets in code/logs
+- No injection vectors (shell/SQL/HTML) introduced
+- Authz/authn checks preserved
+- Sensitive data not leaked
+
+Performance checks (examples):
+- Avoid unnecessary repeated work (N+1 queries, repeated parsing, repeated filesystem hits)
+- Avoid obvious hot-path allocations or large sync operations
+
+Maintainability checks:
+- Clear naming and intent
+- Consistent error handling
+- API boundaries not blurred
+- Consistent with local file patterns (imports, export style, function style)
+
+### 6) Make One Primary Recommendation
+
+Provide one clear path to reach approval.
+Mention alternatives only when they have materially different trade-offs.
+
+### 7) Signal the Investment
+
+Tag the required follow-up effort using:
+- Quick (<1h)
+- Short (1-4h)
+- Medium (1-2d)
+- Large (3d+)
+
+## Confidence Filter
+
+Only report findings you believe are >=80% likely to be correct.
+If you are unsure, explicitly label it as "Uncertain" and explain what evidence would confirm it.
+
+## Output Format (Use This Exactly)
+
+---
+
+**Files Reviewed:** [list]
+
+**Plan/Task Reference:** [task name + link/path to plan section if known]
+
+**Overall Assessment:** [APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION]
+
+**Bottom Line:** 2-3 sentences describing whether it matches the task/plan and what must change.
+
+### Critical Issues
+- None | [file:line] - [issue] (why it blocks approval) + (recommended fix)
+
+### Major Issues
+- None | [file:line] - [issue] + (recommended fix)
+
+### Minor Issues
+- None | [file:line] - [issue] + (suggested fix)
+
+### YAGNI / Dead Code
+- None | [file:line] - [what to remove/simplify] + (why it is unnecessary)
+
+### Positive Observations
+- [at least one concrete good thing]
+
+### Action Plan
+1. [highest priority change]
+2. [next]
+3. [next]
+
+### Effort Estimate
+[Quick | Short | Medium | Large]
+
+---
+
+## Common Review Smells (Fast Scan)
+
+Task/plan adherence:
+- Adds features not mentioned in the plan/task
+- Leaves TODOs as the mechanism for correctness
+- Introduces new configuration modes/flags "for future"
+
+YAGNI / dead code:
+- Options/config that are parsed but not used
+- Branches that do the same thing on both sides
+- Comments like "reserved for future" or "we might need this"
+
+AI slop / inconsistency:
+- Commentary that restates code, narrates obvious steps, or adds process noise
+- try/catch that swallows errors or returns defaults without a requirement
+- `as any` used to silence type errors instead of fixing types
+- New helpers/abstractions with a single call site
+
+Correctness:
+- Silent fallbacks to defaults on error when the task expects a hard failure
+- Unhandled error paths, missing cleanup, missing returns
+
+Maintainability:
+- Abstractions used once
+- Unclear naming, "utility" grab-bags
+
+## When to Escalate
+
+Use NEEDS_DISCUSSION (instead of REQUEST_CHANGES) when:
+- The plan/task is ambiguous and multiple implementations could be correct
+- The change implies a product/architecture decision not documented
+- Fixing issues requires changing scope, dependencies, or public API