@fro.bot/systematic 2.8.1 → 2.9.0

package/README.md

@@ -297,6 +297,20 @@ Configuration is loaded from multiple locations and merged (later sources overri
 {
   "disabled_skills": ["git-worktree"],
   "disabled_agents": [],
+  "categories": {
+    "review": {
+      "temperature": 0.1,
+      "steps": 12
+    }
+  },
+  "agents": {
+    "security-sentinel": {
+      "model": "anthropic/claude-sonnet-4-5"
+    },
+    "workflow/systematic-implementer": {
+      "steps": 20
+    }
+  },
   "bootstrap": {
     "enabled": true
   }
@@ -307,9 +321,21 @@ Configuration is loaded from multiple locations and merged (later sources overri
 |--------|------|---------|-------------|
 | `disabled_skills` | `string[]` | `[]` | Skills to exclude from registration |
 | `disabled_agents` | `string[]` | `[]` | Agents to exclude from registration |
+| `categories` | `object` | `{}` | Overlay bundled agents by category (`design`, `docs`, `document-review`, `research`, `review`, `workflow`) |
+| `agents` | `object` | `{}` | Overlay exact bundled agents by unique stem or `<category>/<stem>` key |
 | `bootstrap.enabled` | `boolean` | `true` | Inject the `using-systematic` guide into system prompts |
 | `bootstrap.file` | `string` | — | Custom bootstrap file path (overrides default) |
 
+Agent overlays support `model`, `variant`, `temperature`, `top_p`, `permission`, `mode`, `color`, `steps`, `hidden`, exact-agent-only `disable`, and managed `skills`. `skills` uses bundled skill frontmatter names like `ce:review`; it is a shortcut that writes OpenCode `permission.skill` rules, not a native OpenCode agent field. Because `permission` and `skills` control tool access, they are only accepted from user config or `$OPENCODE_CONFIG_DIR/systematic.json`; project config may tune behavior but cannot loosen a user's permission policy.
+
+Systematic separates config-source precedence from overlay precedence. Config files merge in this order: user config, project config, then `$OPENCODE_CONFIG_DIR/systematic.json` if set. Higher-priority `agents.<key>` and `categories.<id>` entries replace lower-priority entries wholesale, while unrelated keys survive. Project overlays are the exception for security fields: same-key project overlays preserve user-level `permission` and `skills` fields instead of erasing them. After the effective config is built, exact `agents` overlays beat category overlays, which beat built-in policy defaults, bundled markdown defaults, and OpenCode inherited defaults.
+
+Bundled agents omit `model` by default so OpenCode model inheritance keeps working. Systematic emits a `model` only when you configure one explicitly; provider-specific zero-config model defaults are intentionally deferred.
+
+Native OpenCode agents with the same emitted key are full replacements. An exact Systematic overlay for that key conflicts, while category overlays skip native replacements and continue applying to other bundled agents. Use one canonical agent key form across config sources (`security-sentinel` or `review/security-sentinel`) because alias collisions fail duplicate-target validation.
+
+Category IDs are V1 public API because broad policy overlays are a core use case; future agent reorganizations must preserve aliases or provide migration warnings. Category overlays also apply to future bundled agents added to that category. V1 does not include an MCP allowlist shortcut.
+
 ### Project-Specific Content
 
 Add your own skills and agents alongside bundled ones:

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths
-} from "./index-k9tdxh0p.js";
+} from "./index-488txzkn.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/{index-k9tdxh0p.js → index-488txzkn.js}

@@ -807,6 +807,43 @@ var ParseErrorCode;
   ParseErrorCode2[ParseErrorCode2["InvalidEscapeCharacter"] = 15] = "InvalidEscapeCharacter";
   ParseErrorCode2[ParseErrorCode2["InvalidCharacter"] = 16] = "InvalidCharacter";
 })(ParseErrorCode || (ParseErrorCode = {}));
+function printParseErrorCode(code) {
+  switch (code) {
+    case 1:
+      return "InvalidSymbol";
+    case 2:
+      return "InvalidNumberFormat";
+    case 3:
+      return "PropertyNameExpected";
+    case 4:
+      return "ValueExpected";
+    case 5:
+      return "ColonExpected";
+    case 6:
+      return "CommaExpected";
+    case 7:
+      return "CloseBraceExpected";
+    case 8:
+      return "CloseBracketExpected";
+    case 9:
+      return "EndOfFileExpected";
+    case 10:
+      return "InvalidCommentToken";
+    case 11:
+      return "UnexpectedEndOfComment";
+    case 12:
+      return "UnexpectedEndOfString";
+    case 13:
+      return "UnexpectedEndOfNumber";
+    case 14:
+      return "InvalidUnicode";
+    case 15:
+      return "InvalidEscapeCharacter";
+    case 16:
+      return "InvalidCharacter";
+  }
+  return "<unknown ParseErrorCode>";
+}
 
 // src/lib/config.ts
 var DEFAULT_CONFIG = {
@@ -815,17 +852,43 @@ var DEFAULT_CONFIG = {
   disabled_commands: [],
   bootstrap: {
     enabled: true
-  }
+  },
+  agents: {},
+  categories: {}
 };
+var SECURITY_OVERLAY_FIELDS = new Set(["permission", "skills"]);
+function isErrorWithCode(error) {
+  return error instanceof Error && "code" in error;
+}
 function loadJsoncFile(filePath) {
+  let content;
   try {
-    if (!fs.existsSync(filePath))
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch (error) {
+    if (isErrorWithCode(error) && error.code === "ENOENT")
       return null;
-    const content = fs.readFileSync(filePath, "utf-8");
-    return parse2(content);
-  } catch {
-    return null;
+    throw new Error(`Invalid Systematic config in ${filePath}: unable to read file`, { cause: error });
+  }
+  const errors = [];
+  const parsed = parse2(content, errors);
+  if (errors.length > 0) {
+    const error = errors[0];
+    const message = error ? `${printParseErrorCode(error.error)} at offset ${error.offset}` : "unknown parse error";
+    throw new Error(`Invalid Systematic config in ${filePath}: JSONC parse error: ${message}`);
   }
+  if (!isRecord(parsed)) {
+    throw new Error(`Invalid Systematic config in ${filePath}: root must be an object`);
+  }
+  return parsed;
+}
+function loadConfigSource(filePath, trust) {
+  const config = loadJsoncFile(filePath);
+  if (!config)
+    return null;
+  return { path: filePath, config, trust };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function mergeArraysUnique(arr1, arr2) {
   const set = new Set;
@@ -838,10 +901,18 @@ function mergeArraysUnique(arr1, arr2) {
   return Array.from(set);
 }
 function loadConfig(projectDir) {
+  return loadConfigWithSources(projectDir).config;
+}
+function loadConfigWithSources(projectDir) {
   const paths = getConfigPaths(projectDir);
-  const userConfig = loadJsoncFile(paths.userConfig);
-  const projectConfig = loadJsoncFile(paths.projectConfig);
-  const customConfig = paths.customConfig ? loadJsoncFile(paths.customConfig) : null;
+  const userSource = loadConfigSource(paths.userConfig, "user");
+  const projectSource = loadConfigSource(paths.projectConfig, "project");
+  const customSource = paths.customConfig ? loadConfigSource(paths.customConfig, "custom") : null;
+  const sources = [userSource, projectSource, customSource].filter((source) => source !== null);
+  const overlays = mergeOverlaySources(sources);
+  const userConfig = userSource?.config;
+  const projectConfig = projectSource?.config;
+  const customConfig = customSource?.config;
   const result = {
     disabled_skills: mergeArraysUnique(mergeArraysUnique(mergeArraysUnique(DEFAULT_CONFIG.disabled_skills, userConfig?.disabled_skills), projectConfig?.disabled_skills), customConfig?.disabled_skills),
     disabled_agents: mergeArraysUnique(mergeArraysUnique(mergeArraysUnique(DEFAULT_CONFIG.disabled_agents, userConfig?.disabled_agents), projectConfig?.disabled_agents), customConfig?.disabled_agents),
@@ -851,10 +922,73 @@ function loadConfig(projectDir) {
       ...userConfig?.bootstrap,
       ...projectConfig?.bootstrap,
       ...customConfig?.bootstrap
-    }
+    },
+    agents: overlayValues(overlays.agents),
+    categories: overlayValues(overlays.categories)
+  };
+  return { config: result, overlays };
+}
+function mergeOverlaySources(sources) {
+  const result = {
+    agents: {},
+    categories: {}
   };
+  for (const source of sources) {
+    mergeOverlayMap(result.agents, source, "agents");
+    mergeOverlayMap(result.categories, source, "categories");
+  }
+  return result;
+}
+function mergeOverlayMap(target, source, mapKey) {
+  const overlayMap = source.config[mapKey];
+  if (overlayMap === undefined)
+    return;
+  if (!isRecord(overlayMap)) {
+    throwInvalidOverlay(source.path, mapKey);
+  }
+  for (const [key, value] of Object.entries(overlayMap)) {
+    const keyPath = `${mapKey}.${key}`;
+    if (!isRecord(value)) {
+      throwInvalidOverlay(source.path, keyPath);
+    }
+    if (source.trust === "project") {
+      rejectProjectSecurityOverlay(source.path, keyPath, value);
+    }
+    const previous = target[key];
+    const nextValue = source.trust === "project" && previous ? preserveSecurityFields(previous.value, value) : value;
+    target[key] = {
+      value: nextValue,
+      sourcePath: source.path,
+      keyPath
+    };
+  }
+}
+function rejectProjectSecurityOverlay(sourcePath, keyPath, value) {
+  for (const field of SECURITY_OVERLAY_FIELDS) {
+    if (Object.hasOwn(value, field)) {
+      throw new Error(`Invalid Systematic config in ${sourcePath}: ${keyPath}.${field} is only valid in user config or OPENCODE_CONFIG_DIR config`);
+    }
+  }
+}
+function preserveSecurityFields(previous, next) {
+  const result = { ...next };
+  for (const field of SECURITY_OVERLAY_FIELDS) {
+    if (Object.hasOwn(previous, field)) {
+      result[field] = previous[field];
+    }
+  }
   return result;
 }
+function overlayValues(overlays) {
+  const result = {};
+  for (const [key, overlay] of Object.entries(overlays)) {
+    result[key] = overlay.value;
+  }
+  return result;
+}
+function throwInvalidOverlay(sourcePath, keyPath) {
+  throw new Error(`Invalid Systematic config in ${sourcePath}: ${keyPath} must be an object`);
+}
 function getConfigPaths(projectDir) {
   const homeDir = os.homedir();
   const customConfigDir = process.env.OPENCODE_CONFIG_DIR?.trim();
@@ -909,14 +1043,14 @@ function formatFrontmatter(data) {
 }
 
 // src/lib/validation.ts
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isPermissionSetting(value) {
   return value === "ask" || value === "allow" || value === "deny";
 }
 function isToolsMap(value) {
-  if (!isRecord(value))
+  if (!isRecord2(value))
     return false;
   return Object.values(value).every((entry) => typeof entry === "boolean");
 }
@@ -935,7 +1069,7 @@ function extractBashPermission(data) {
   const bash = data.bash;
   if (isPermissionSetting(bash))
     return bash;
-  if (isRecord(bash)) {
+  if (isRecord2(bash)) {
     const entries = Object.entries(bash);
     if (entries.every(([, setting]) => isPermissionSetting(setting))) {
       return Object.fromEntries(entries);
@@ -962,7 +1096,7 @@ function buildPermissionObject(edit, bash, webfetch, doom_loop, external_directo
   return Object.keys(permission).length > 0 ? permission : undefined;
 }
 function normalizePermission(value) {
-  if (!isRecord(value))
+  if (!isRecord2(value))
     return;
   const bash = extractBashPermission(value);
   if (bash === null)
@@ -1071,6 +1205,7 @@ function extractAgentFrontmatter(content) {
     description: extractString(data, "description"),
     prompt: body.trim(),
     model: extractNonEmptyString(data, "model"),
+    variant: extractNonEmptyString(data, "variant"),
     temperature: extractNumber(data, "temperature"),
     top_p: extractNumber(data, "top_p"),
     tools: isToolsMap(data.tools) ? data.tools : undefined,
@@ -1420,7 +1555,7 @@ function extractFrontmatter(filePath) {
     }
     const metadataRaw = data.metadata;
     let metadata;
-    if (isRecord(metadataRaw)) {
+    if (isRecord2(metadataRaw)) {
       const entries = Object.entries(metadataRaw);
       if (entries.every(([, v]) => typeof v === "string")) {
         metadata = Object.fromEntries(entries);
@@ -1477,4 +1612,4 @@ function findSkillsInDir(dir, maxDepth = 3) {
   return skills;
 }
 
-export { parseFrontmatter, loadConfig, getConfigPaths, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, convertContent, convertFileWithCache, findSkillsInDir };
+export { parseFrontmatter, loadConfig, loadConfigWithSources, getConfigPaths, isRecord2 as isRecord, isPermissionSetting, isAgentMode, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, convertContent, convertFileWithCache, findSkillsInDir };

package/dist/index.js

@@ -6,13 +6,17 @@ import {
   findAgentsInDir,
   findCommandsInDir,
   findSkillsInDir,
+  isAgentMode,
+  isPermissionSetting,
+  isRecord,
   loadConfig,
+  loadConfigWithSources,
   parseFrontmatter
-} from "./index-k9tdxh0p.js";
+} from "./index-488txzkn.js";
 
 // src/index.ts
-import fs3 from "fs";
-import path4 from "path";
+import fs4 from "fs";
+import path5 from "path";
 import { fileURLToPath } from "url";
 
 // src/lib/bootstrap.ts
@@ -72,8 +76,304 @@ ${toolMapping}
 </SYSTEMATIC_WORKFLOWS>`;
 }
 
-// src/lib/skill-loader.ts
+// src/lib/agent-overlays.ts
+import fs2 from "fs";
 import path2 from "path";
+var ALLOWED_OVERLAY_FIELDS = new Set([
+  "model",
+  "variant",
+  "temperature",
+  "top_p",
+  "permission",
+  "mode",
+  "color",
+  "steps",
+  "hidden",
+  "disable",
+  "skills"
+]);
+function buildBundledAgentInventory(agentsDir, disabledAgents) {
+  const categories = readCategoryDirs(agentsDir);
+  const agentsByQualifiedId = {};
+  const stemCategories = new Map;
+  const disabledSet = new Set(disabledAgents);
+  for (const category of categories) {
+    for (const fileName of readMarkdownFiles(path2.join(agentsDir, category))) {
+      const key = fileName.replace(/\.md$/, "");
+      const id = `${category}/${key}`;
+      agentsByQualifiedId[id] = {
+        id,
+        key,
+        category,
+        file: path2.join(agentsDir, category, fileName),
+        disabled: disabledSet.has(key) || disabledSet.has(id)
+      };
+      const existing = stemCategories.get(key) ?? [];
+      existing.push(category);
+      stemCategories.set(key, existing);
+    }
+  }
+  const duplicateStems = Array.from(stemCategories.entries()).filter(([, seenCategories]) => seenCategories.length > 1);
+  if (duplicateStems.length > 0) {
+    const details = duplicateStems.map(([stem, seenCategories]) => `Duplicate bundled agent stem "${stem}" in categories: ${seenCategories.join(", ")}`).join("; ");
+    throw new Error(details);
+  }
+  const aliases = {};
+  for (const entry of Object.values(agentsByQualifiedId)) {
+    aliases[entry.id] = entry.id;
+    aliases[entry.key] = entry.id;
+  }
+  return { agentsByQualifiedId, aliases, categories };
+}
+function validateAgentOverlays({
+  inventory,
+  overlays,
+  nativeAgents = {},
+  enabledSkills
+}) {
+  const skillSet = enabledSkills ? new Set(enabledSkills) : undefined;
+  const agents = validateExactAgentOverlays(inventory, overlays, nativeAgents, skillSet);
+  const categories = validateCategoryOverlays(inventory, overlays, skillSet);
+  return { agents, categories };
+}
+function resolveAgentOverlaySet(overlays) {
+  return {
+    agentsByTargetId: new Map(overlays.agents.map((overlay) => [overlay.target.id, overlay])),
+    categoriesByKey: new Map(overlays.categories.map((overlay) => [overlay.key, overlay]))
+  };
+}
+function inferBuiltInTemperature(name, description) {
+  const sample = `${name} ${description ?? ""}`.toLowerCase();
+  if (/(review|audit|security|sentinel|oracle|lint|verification|guardian)/.test(sample)) {
+    return 0.1;
+  }
+  if (/(plan|planning|architecture|strategist|analysis|research)/.test(sample)) {
+    return 0.2;
+  }
+  if (/(doc|readme|changelog|editor|writer)/.test(sample)) {
+    return 0.3;
+  }
+  if (/(brainstorm|creative|ideate|design|concept)/.test(sample)) {
+    return 0.6;
+  }
+  return 0.3;
+}
+function validateExactAgentOverlays(inventory, overlays, nativeAgents, enabledSkills) {
+  const result = [];
+  const seenTargets = new Map;
+  for (const [key, overlay] of Object.entries(overlays.agents)) {
+    const targetId = inventory.aliases[key];
+    if (!targetId) {
+      throwConfigError(overlay.sourcePath, overlay.keyPath, `unknown bundled agent. Valid agents: ${validAgentKeys(inventory).join(", ")}`);
+    }
+    const previousKeyPath = seenTargets.get(targetId);
+    if (previousKeyPath) {
+      throwConfigError(overlay.sourcePath, overlay.keyPath, `Duplicate Systematic agent overlay target "${targetId}" from ${previousKeyPath} and ${overlay.keyPath}`);
+    }
+    seenTargets.set(targetId, overlay.keyPath);
+    const target = inventory.agentsByQualifiedId[targetId];
+    if (!target) {
+      throwConfigError(overlay.sourcePath, overlay.keyPath, `unknown bundled agent target "${targetId}"`);
+    }
+    if (Object.hasOwn(nativeAgents, target.key)) {
+      throwConfigError(overlay.sourcePath, overlay.keyPath, `conflicts with native OpenCode agent.${target.key}; native agents are replacements for bundled agents`);
+    }
+    validateOverlayFields(overlay, "agent", enabledSkills);
+    result.push({
+      key,
+      target,
+      value: overlay.value,
+      sourcePath: overlay.sourcePath,
+      keyPath: overlay.keyPath
+    });
+  }
+  return result;
+}
+function validateCategoryOverlays(inventory, overlays, enabledSkills) {
+  const categories = new Set(inventory.categories);
+  const result = [];
+  for (const [key, overlay] of Object.entries(overlays.categories)) {
+    if (!categories.has(key)) {
+      throwConfigError(overlay.sourcePath, overlay.keyPath, `unknown bundled agent category. Valid categories: ${inventory.categories.join(", ")}`);
+    }
+    validateOverlayFields(overlay, "category", enabledSkills);
+    result.push({
+      key,
+      value: overlay.value,
+      sourcePath: overlay.sourcePath,
+      keyPath: overlay.keyPath
+    });
+  }
+  return result;
+}
+function validateOverlayFields(overlay, targetType, enabledSkills) {
+  if (Object.hasOwn(overlay.value, "skills") && hasPermissionSkill(overlay.value.permission)) {
+    throwConfigError(overlay.sourcePath, overlay.keyPath, "cannot set both skills and permission.skill in the same overlay object");
+  }
+  for (const [field, value] of Object.entries(overlay.value)) {
+    const keyPath = `${overlay.keyPath}.${field}`;
+    if (!ALLOWED_OVERLAY_FIELDS.has(field)) {
+      throwConfigError(overlay.sourcePath, keyPath, `unsupported agent overlay field "${field}"`);
+    }
+    if (targetType === "category" && field === "disable") {
+      throwConfigError(overlay.sourcePath, keyPath, "disable is only valid for exact agent overlays");
+    }
+    validateOverlayFieldValue(overlay.sourcePath, keyPath, field, value, enabledSkills);
+  }
+}
+function hasPermissionSkill(permission) {
+  return isRecord(permission) && Object.hasOwn(permission, "skill");
+}
+function validateOverlayFieldValue(sourcePath, keyPath, field, value, enabledSkills) {
+  switch (field) {
+    case "model":
+      validateModel(sourcePath, keyPath, value);
+      return;
+    case "variant":
+      validateNonEmptyString(sourcePath, keyPath, value);
+      return;
+    case "temperature":
+      validateTemperature(sourcePath, keyPath, value);
+      return;
+    case "top_p":
+      validateTopP(sourcePath, keyPath, value);
+      return;
+    case "permission":
+      validatePermission(sourcePath, keyPath, value);
+      return;
+    case "mode":
+      validateMode(sourcePath, keyPath, value);
+      return;
+    case "color":
+      validateColor(sourcePath, keyPath, value);
+      return;
+    case "steps":
+      validatePositiveInteger(sourcePath, keyPath, value);
+      return;
+    case "hidden":
+    case "disable":
+      validateBoolean(sourcePath, keyPath, value);
+      return;
+    case "skills":
+      validateSkills(sourcePath, keyPath, value, enabledSkills);
+      return;
+  }
+}
+function validateModel(sourcePath, keyPath, value) {
+  if (typeof value !== "string") {
+    throwConfigError(sourcePath, keyPath, "must be a provider/model string");
+  }
+  if (value !== value.trim() || /\s/.test(value)) {
+    throwConfigError(sourcePath, keyPath, "must be a provider/model string");
+  }
+  const slashIndex = value.indexOf("/");
+  if (value === "" || slashIndex <= 0 || slashIndex === value.length - 1) {
+    throwConfigError(sourcePath, keyPath, "must be a provider/model string");
+  }
+}
+function validateNonEmptyString(sourcePath, keyPath, value) {
+  if (typeof value !== "string" || value === "" || value !== value.trim()) {
+    throwConfigError(sourcePath, keyPath, "must be a non-empty string");
+  }
+}
+function validateTemperature(sourcePath, keyPath, value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throwConfigError(sourcePath, keyPath, "must be a non-negative finite number");
+  }
+}
+function validateTopP(sourcePath, keyPath, value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throwConfigError(sourcePath, keyPath, "must be a number from 0 to 1");
+  }
+}
+function validatePositiveInteger(sourcePath, keyPath, value) {
+  if (!Number.isInteger(value) || value < 1) {
+    throwConfigError(sourcePath, keyPath, "must be a positive integer");
+  }
+}
+function validateBoolean(sourcePath, keyPath, value) {
+  if (typeof value !== "boolean") {
+    throwConfigError(sourcePath, keyPath, "must be a boolean");
+  }
+}
+function validateMode(sourcePath, keyPath, value) {
+  if (!isAgentMode(value)) {
+    throwConfigError(sourcePath, keyPath, "must be one of: subagent, primary, all");
+  }
+}
+function validateColor(sourcePath, keyPath, value) {
+  if (typeof value !== "string" || value !== value.trim() || !isOpenCodeColor(value)) {
+    throwConfigError(sourcePath, keyPath, "must be an OpenCode-compatible color string");
+  }
+}
+function isOpenCodeColor(value) {
+  if (value === "")
+    return false;
+  if (/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value))
+    return true;
+  return /^[a-zA-Z][a-zA-Z0-9-]*$/.test(value);
+}
+function validateSkills(sourcePath, keyPath, value, enabledSkills) {
+  if (!Array.isArray(value) || !value.every((skill) => typeof skill === "string" && skill !== "" && skill === skill.trim())) {
+    throwConfigError(sourcePath, keyPath, "must be an array of non-empty strings");
+  }
+  if (!enabledSkills)
+    return;
+  for (const skill of value) {
+    if (!enabledSkills.has(skill)) {
+      throwConfigError(sourcePath, keyPath, `unknown or disabled skill "${skill}"`);
+    }
+  }
+}
+function validatePermission(sourcePath, keyPath, value) {
+  if (!isRecord(value)) {
+    throwConfigError(sourcePath, keyPath, "must be an object");
+  }
+  for (const [toolKey, rule] of Object.entries(value)) {
+    if (toolKey.trim() === "") {
+      throwConfigError(sourcePath, `${keyPath}.${toolKey}`, "must use a non-empty tool key");
+    }
+    validatePermissionRule(sourcePath, `${keyPath}.${toolKey}`, rule);
+  }
+}
+function validatePermissionRule(sourcePath, keyPath, value) {
+  if (isPermissionSetting(value))
+    return;
+  if (!isRecord(value)) {
+    throwConfigError(sourcePath, keyPath, "must be ask, allow, deny, or an object of pattern rules");
+  }
+  for (const [pattern, setting] of Object.entries(value)) {
+    if (pattern.trim() === "") {
+      throwConfigError(sourcePath, `${keyPath}.${pattern}`, "must use a non-empty permission pattern");
+    }
+    if (!isPermissionSetting(setting)) {
+      throwConfigError(sourcePath, `${keyPath}.${pattern}`, "must be ask, allow, or deny");
+    }
+  }
+}
+function readCategoryDirs(agentsDir) {
+  try {
+    return fs2.readdirSync(agentsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function readMarkdownFiles(categoryDir) {
+  try {
+    return fs2.readdirSync(categoryDir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith(".md")).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function validAgentKeys(inventory) {
+  return Object.keys(inventory.aliases).sort();
+}
+function throwConfigError(sourcePath, keyPath, message) {
+  throw new Error(`Invalid Systematic config in ${sourcePath}: ${keyPath} ${message}`);
+}
+
+// src/lib/skill-loader.ts
+import path3 from "path";
 var SKILL_PREFIX = "systematic:";
 var SKILL_DESCRIPTION_PREFIX = "(Systematic - Skill) ";
 function formatSkillCommandName(name) {
@@ -90,7 +390,7 @@ function formatSkillDescription(description, fallbackName) {
   return `${SKILL_DESCRIPTION_PREFIX}${desc}`;
 }
 function wrapSkillTemplate(skillPath, body) {
-  const skillDir = path2.dirname(skillPath);
+  const skillDir = path3.dirname(skillPath);
   return `<skill-instruction>
 Base directory for this skill: ${skillDir}/
 File references (@path) in this skill are relative to this directory.
@@ -154,6 +454,7 @@ function loadAgentAsConfig(agentInfo) {
       description,
       prompt,
       model,
+      variant,
       temperature,
       top_p,
       tools,
@@ -170,6 +471,8 @@ function loadAgentAsConfig(agentInfo) {
     };
     if (model !== undefined)
       config.model = model;
+    if (variant !== undefined)
+      config.variant = variant;
     if (temperature !== undefined)
       config.temperature = temperature;
     if (top_p !== undefined)
@@ -237,19 +540,122 @@ function loadSkillAsCommand(loaded) {
     config.subtask = loaded.subtask;
   return config;
 }
-function collectAgents(dir, disabledAgents) {
+function collectAgents(dir, disabledAgents, nativeAgents, overlays) {
   const agents = {};
   const agentList = findAgentsInDir(dir);
+  const disabledSet = new Set(disabledAgents);
   for (const agentInfo of agentList) {
-    if (disabledAgents.includes(agentInfo.name))
+    const id = agentInfo.category ? `${agentInfo.category}/${agentInfo.name}` : agentInfo.name;
+    if (disabledSet.has(agentInfo.name) || disabledSet.has(id))
+      continue;
+    if (Object.hasOwn(nativeAgents, agentInfo.name))
+      continue;
+    const exactOverlay = overlays.agentsByTargetId.get(id);
+    if (exactOverlay?.value.disable === true)
       continue;
     const config = loadAgentAsConfig(agentInfo);
     if (config) {
-      agents[agentInfo.name] = config;
+      agents[agentInfo.name] = applyAgentOverlays(config, agentInfo, overlays);
     }
   }
   return agents;
 }
+function applyAgentOverlays(config, agentInfo, overlays) {
+  const id = agentInfo.category ? `${agentInfo.category}/${agentInfo.name}` : agentInfo.name;
+  const categoryOverlay = agentInfo.category ? overlays.categoriesByKey.get(agentInfo.category) : undefined;
+  const exactOverlay = overlays.agentsByTargetId.get(id);
+  const result = { ...config };
+  const permissionRules = createPermissionRuleAccumulator();
+  const hasPermissionOverlay = overlayControlsPermission(categoryOverlay?.value) || overlayControlsPermission(exactOverlay?.value);
+  if (hasPermissionOverlay && isRecord(config.permission)) {
+    addPermissionRules(permissionRules, config.permission);
+  }
+  result.temperature = inferBuiltInTemperature(agentInfo.name, result.description);
+  if (categoryOverlay) {
+    applyOverlayObject(result, categoryOverlay.value, permissionRules);
+  }
+  if (exactOverlay) {
+    applyOverlayObject(result, exactOverlay.value, permissionRules);
+  }
+  if (hasPermissionOverlay) {
+    const permission = permissionFromRules(permissionRules);
+    if (permission) {
+      result.permission = permission;
+    } else {
+      delete result.permission;
+    }
+  }
+  return result;
+}
+function overlayControlsPermission(overlay) {
+  return overlay !== undefined && (Object.hasOwn(overlay, "permission") || Object.hasOwn(overlay, "skills"));
+}
+var OVERLAY_ASSIGN_FIELDS = [
+  "model",
+  "variant",
+  "temperature",
+  "top_p",
+  "mode",
+  "color",
+  "steps",
+  "hidden"
+];
+function applyOverlayObject(target, overlay, permissionRules) {
+  for (const field of OVERLAY_ASSIGN_FIELDS) {
+    if (Object.hasOwn(overlay, field)) {
+      target[field] = overlay[field];
+    }
+  }
+  if (isRecord(overlay.permission)) {
+    addPermissionRules(permissionRules, overlay.permission);
+  }
+  if (Array.isArray(overlay.skills)) {
+    addManagedSkillRules(permissionRules, overlay.skills);
+  }
+}
+function createPermissionRuleAccumulator() {
+  return new Map;
+}
+function addPermissionRules(accumulator, permission) {
+  for (const [tool, rule] of Object.entries(permission)) {
+    if (isPermissionSettingValue(rule)) {
+      setPermissionRule(accumulator, tool, "*", rule);
+      continue;
+    }
+    if (!isRecord(rule))
+      continue;
+    for (const [pattern, setting] of Object.entries(rule)) {
+      if (isPermissionSettingValue(setting)) {
+        setPermissionRule(accumulator, tool, pattern, setting);
+      }
+    }
+  }
+}
+function addManagedSkillRules(accumulator, skills) {
+  setPermissionRule(accumulator, "skill", "*", "deny");
+  for (const skill of skills) {
+    if (typeof skill === "string") {
+      setPermissionRule(accumulator, "skill", skill, "allow");
+    }
+  }
+}
+function permissionFromRules(accumulator) {
+  const permission = {};
+  for (const [tool, rules] of accumulator) {
+    permission[tool] = Object.fromEntries(rules);
+  }
+  return Object.keys(permission).length > 0 ? permission : undefined;
+}
+function setPermissionRule(accumulator, tool, pattern, setting) {
+  const rules = accumulator.get(tool) ?? new Map;
+  if (rules.has(pattern))
+    rules.delete(pattern);
+  rules.set(pattern, setting);
+  accumulator.set(tool, rules);
+}
+function isPermissionSettingValue(value) {
+  return value === "ask" || value === "allow" || value === "deny";
+}
 function collectCommands(dir, disabledCommands) {
   const commands = {};
   const commandList = findCommandsInDir(dir);
@@ -280,19 +686,32 @@ function collectSkillsAsCommands(dir, disabledSkills) {
   }
   return commands;
 }
+function collectEnabledSkillNames(dir, disabledSkills) {
+  const disabledSet = new Set(disabledSkills);
+  return findSkillsInDir(dir).filter((skillInfo) => !disabledSet.has(skillInfo.name)).map((skillInfo) => skillInfo.name);
+}
 function createConfigHandler(deps) {
   const { directory, bundledSkillsDir, bundledAgentsDir, bundledCommandsDir } = deps;
   return async (config) => {
-    const systematicConfig = loadConfig(directory);
-    const bundledAgents = collectAgents(bundledAgentsDir, systematicConfig.disabled_agents);
-    const bundledCommands = collectCommands(bundledCommandsDir, systematicConfig.disabled_commands);
+    const { config: systematicConfig, overlays } = loadConfigWithSources(directory);
+    const existingAgents = { ...config.agent ?? {} };
+    const existingCommands = { ...config.command ?? {} };
     const bundledSkills = collectSkillsAsCommands(bundledSkillsDir, systematicConfig.disabled_skills);
-    const existingAgents = config.agent ?? {};
+    const enabledSkillNames = collectEnabledSkillNames(bundledSkillsDir, systematicConfig.disabled_skills);
+    const inventory = buildBundledAgentInventory(bundledAgentsDir, systematicConfig.disabled_agents);
+    const validatedOverlays = validateAgentOverlays({
+      inventory,
+      overlays,
+      nativeAgents: existingAgents,
+      enabledSkills: enabledSkillNames
+    });
+    const resolvedOverlays = resolveAgentOverlaySet(validatedOverlays);
+    const bundledAgents = collectAgents(bundledAgentsDir, systematicConfig.disabled_agents, existingAgents, resolvedOverlays);
+    const bundledCommands = collectCommands(bundledCommandsDir, systematicConfig.disabled_commands);
     config.agent = {
       ...bundledAgents,
       ...existingAgents
     };
-    const existingCommands = config.command ?? {};
     config.command = {
       ...bundledCommands,
       ...bundledSkills,
@@ -303,11 +722,12 @@ function createConfigHandler(deps) {
 }
 function registerSkillsPaths(config, skillsDir) {
   const extended = config;
-  extended.skills ??= {};
-  extended.skills.paths ??= [];
-  if (!extended.skills.paths.includes(skillsDir)) {
-    extended.skills.paths.push(skillsDir);
-  }
+  const paths = extended.skills?.paths ?? [];
+  const nextPaths = paths.includes(skillsDir) ? [...paths] : [...paths, skillsDir];
+  extended.skills = {
+    ...extended.skills,
+    paths: nextPaths
+  };
 }
 
 // src/lib/plugin-singleton.ts
@@ -342,8 +762,8 @@ async function plugInOnce({
 }
 
 // src/lib/skill-tool.ts
-import fs2 from "fs";
-import path3 from "path";
+import fs3 from "fs";
+import path4 from "path";
 import { pathToFileURL } from "url";
 import { tool } from "@opencode-ai/plugin/tool";
 function formatSkillsXml(skills) {
@@ -369,17 +789,17 @@ function discoverSkillFiles(dir, limit = 10) {
   function handleEntry(entry, currentDir) {
     if (entry.isDirectory()) {
       if (!shouldSkipDirectory(entry.name)) {
-        recurse(path3.resolve(currentDir, entry.name));
+        recurse(path4.resolve(currentDir, entry.name));
       }
     } else if (shouldIncludeFile(entry.name)) {
-      files.push(path3.resolve(currentDir, entry.name));
+      files.push(path4.resolve(currentDir, entry.name));
     }
   }
   function recurse(currentDir) {
     if (files.length >= limit)
       return;
     try {
-      const entries = fs2.readdirSync(currentDir, { withFileTypes: true });
+      const entries = fs3.readdirSync(currentDir, { withFileTypes: true });
       for (const entry of entries) {
         if (files.length >= limit)
           break;
@@ -460,7 +880,7 @@ function createSkillTool(options) {
         throw new Error(`Skill "${requestedName}" not found. Available systematic skills: ${availableSystematic.join(", ")}`);
       }
       const body = extractSkillBody(matchedSkill.wrappedTemplate);
-      const dir = path3.dirname(matchedSkill.skillFile);
+      const dir = path4.dirname(matchedSkill.skillFile);
       const base = pathToFileURL(dir).href;
       const files = discoverSkillFiles(dir);
       await context.ask({
@@ -497,12 +917,12 @@ function createSkillTool(options) {
 }
 
 // src/index.ts
-var __dirname2 = path4.dirname(fileURLToPath(import.meta.url));
-var packageRoot = path4.resolve(__dirname2, "..");
-var bundledSkillsDir = path4.join(packageRoot, "skills");
-var bundledAgentsDir = path4.join(packageRoot, "agents");
-var bundledCommandsDir = path4.join(packageRoot, "commands");
-var packageJsonPath = path4.join(packageRoot, "package.json");
+var __dirname2 = path5.dirname(fileURLToPath(import.meta.url));
+var packageRoot = path5.resolve(__dirname2, "..");
+var bundledSkillsDir = path5.join(packageRoot, "skills");
+var bundledAgentsDir = path5.join(packageRoot, "agents");
+var bundledCommandsDir = path5.join(packageRoot, "commands");
+var packageJsonPath = path5.join(packageRoot, "package.json");
 var hasLoggedInit = false;
 var applyBootstrapContent = (output, content) => {
   if (output.system.length > 0) {
@@ -515,9 +935,9 @@ ${content}`;
 };
 var getPackageVersion = () => {
   try {
-    if (!fs3.existsSync(packageJsonPath))
+    if (!fs4.existsSync(packageJsonPath))
       return "unknown";
-    const content = fs3.readFileSync(packageJsonPath, "utf8");
+    const content = fs4.readFileSync(packageJsonPath, "utf8");
     const parsed = JSON.parse(content);
     return parsed.version ?? "unknown";
   } catch {

package/dist/lib/agent-overlays.d.ts

@@ -0,0 +1,44 @@
+import type { SourcedOverlayConfigMap } from './config.js';
+export interface BundledAgentInventoryEntry {
+    id: string;
+    key: string;
+    category: string;
+    file: string;
+    disabled: boolean;
+}
+export interface BundledAgentInventory {
+    agentsByQualifiedId: Record<string, BundledAgentInventoryEntry>;
+    aliases: Record<string, string>;
+    categories: string[];
+}
+export interface ValidatedAgentOverlay {
+    key: string;
+    target: BundledAgentInventoryEntry;
+    value: Record<string, unknown>;
+    sourcePath: string;
+    keyPath: string;
+}
+export interface ValidatedCategoryOverlay {
+    key: string;
+    value: Record<string, unknown>;
+    sourcePath: string;
+    keyPath: string;
+}
+export interface ValidatedAgentOverlays {
+    agents: ValidatedAgentOverlay[];
+    categories: ValidatedCategoryOverlay[];
+}
+export interface ValidateAgentOverlaysOptions {
+    inventory: BundledAgentInventory;
+    overlays: SourcedOverlayConfigMap;
+    nativeAgents?: Record<string, unknown>;
+    enabledSkills?: string[];
+}
+export interface ResolvedAgentOverlaySet {
+    agentsByTargetId: Map<string, ValidatedAgentOverlay>;
+    categoriesByKey: Map<string, ValidatedCategoryOverlay>;
+}
+export declare function buildBundledAgentInventory(agentsDir: string, disabledAgents: string[]): BundledAgentInventory;
+export declare function validateAgentOverlays({ inventory, overlays, nativeAgents, enabledSkills, }: ValidateAgentOverlaysOptions): ValidatedAgentOverlays;
+export declare function resolveAgentOverlaySet(overlays: ValidatedAgentOverlays): ResolvedAgentOverlaySet;
+export declare function inferBuiltInTemperature(name: string, description?: string): number;

package/dist/lib/agents.d.ts

@@ -8,6 +8,8 @@ export interface AgentFrontmatter {
     prompt: string;
     /** Model to use (provider/model format) */
     model?: string;
+    /** Model variant to use */
+    variant?: string;
     /** Temperature for generation */
     temperature?: number;
     /** Top-p sampling */

package/dist/lib/config-handler.d.ts

@@ -13,8 +13,9 @@ export declare function formatAgentDescription(name: string, description: string
  * This follows the pattern used by oh-my-opencode to inject bundled agents,
  * skills (as commands), and commands into OpenCode's configuration.
  *
- * Only bundled content is loaded. User/project overrides are not supported.
- * Existing OpenCode config is preserved and takes precedence.
+ * Bundled content is loaded and then tuned with Systematic agent overlays.
+ * Existing native OpenCode agents with the same emitted key are preserved as
+ * replacements for bundled agents.
  */
 export declare function createConfigHandler(deps: ConfigHandlerDeps): (config: Config) => Promise<void>;
 /** Register a directory for OpenCode's native skill discovery (`skill` tool). */

package/dist/lib/config.d.ts

@@ -2,14 +2,32 @@ export interface BootstrapConfig {
     enabled: boolean;
     file?: string;
 }
+export type OverlayConfig = Record<string, unknown>;
+export type OverlayConfigMap = Record<string, OverlayConfig>;
+export interface SourcedOverlayConfig {
+    value: OverlayConfig;
+    sourcePath: string;
+    keyPath: string;
+}
+export interface SourcedOverlayConfigMap {
+    agents: Record<string, SourcedOverlayConfig>;
+    categories: Record<string, SourcedOverlayConfig>;
+}
+export interface SourceAwareConfigResult {
+    config: SystematicConfig;
+    overlays: SourcedOverlayConfigMap;
+}
 export interface SystematicConfig {
     disabled_skills: string[];
     disabled_agents: string[];
     disabled_commands: string[];
     bootstrap: BootstrapConfig;
+    agents?: OverlayConfigMap;
+    categories?: OverlayConfigMap;
 }
 export declare const DEFAULT_CONFIG: SystematicConfig;
 export declare function loadConfig(projectDir: string): SystematicConfig;
+export declare function loadConfigWithSources(projectDir: string): SourceAwareConfigResult;
 export declare function getConfigPaths(projectDir: string): {
     customConfig?: string | undefined;
     customDir?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",