feat(config): add agent configuration overlays (#343)

* docs: add agent configuration overlay plan

* feat(config): load agent overlay config

* feat(config): validate agent overlays

* feat(config): apply agent overlays

* docs: document agent overlay config

* test: cover agent overlay integration

* fix(config): protect agent permission overlays

* docs(plan): mark agent overlay plan complete

Author: marcusrbrown

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:

docs/plans/2026-05-09-001-feat-agent-model-configuration-plan.md

@@ -9,10 +9,11 @@ Systematic works out of the box with sensible defaults, but it provides several
 
 ## Plugin Configuration
 
-You can customize the plugin by creating a configuration file. Systematic looks for configuration in two places:
+You can customize the plugin by creating a configuration file. Systematic looks for configuration in three places:
 
 1.  **Global:** `~/.config/opencode/systematic.json`
-2.  **Project-specific:** `.opencode/systematic.json` (takes precedence)
+2.  **Project-specific:** `.opencode/systematic.json`
+3.  **Custom config directory:** `$OPENCODE_CONFIG_DIR/systematic.json`
 
 ### Disabling Bundled Content
 
@@ -25,6 +26,57 @@ If you want to hide certain bundled skills or agents, you can list them in the `
 }
 ```
 
+### Bundled Agent Overlays
+
+Use top-level `agents` and `categories` maps to tune bundled Systematic agents without copying their markdown files into native OpenCode agent definitions.
+
+```jsonc
+{
+  "categories": {
+    // Applies to bundled agents in agents/review/*.md unless that agent has
+    // been replaced by a native OpenCode agent with the same emitted key.
+    "review": {
+      "temperature": 0.1,
+      "steps": 12
+    }
+  },
+  "agents": {
+    // Unqualified unique stem form.
+    "security-sentinel": {
+      "model": "anthropic/claude-sonnet-4-5",
+      "variant": "thinking",
+      "steps": 20
+    },
+
+    // Qualified form for the same inventory model: <category>/<agent-stem>.
+    "workflow/systematic-implementer": {
+      "mode": "subagent",
+      "color": "cyan"
+    }
+  }
+}
+```
+
+Valid category IDs are `design`, `docs`, `document-review`, `research`, `review`, and `workflow`. These IDs are V1 public API because broad policy overlays are a primary use case; future reorganizations must preserve aliases or ship migration warnings. Category overlays also apply to future bundled agents added to that category, so use them for policies you want to inherit broadly.
+
+Exact agent overlays accept the unique file stem (`security-sentinel`) or the qualified key (`review/security-sentinel`). Pick one canonical form across all config sources. Systematic merges config sources before resolving aliases, so cross-source alias collisions like user `agents.security-sentinel` plus project `agents.review/security-sentinel` fail duplicate-target validation instead of silently overriding.
+
+Supported overlay fields are `model`, `variant`, `temperature`, `top_p`, `permission`, `mode`, `color`, `steps`, `hidden`, exact-agent-only `disable`, and `skills`.
+
+`skills` is a Systematic-managed shortcut that writes OpenCode `permission.skill` rules using bundled skill frontmatter names such as `ce:review`. It is not a native OpenCode agent field. Because `permission` and `skills` control tool access, they are accepted only from user config or `$OPENCODE_CONFIG_DIR/systematic.json`; project config may tune agent behavior but cannot loosen a user's permission policy. Systematic does not expose an `mcps` shortcut in V1; MCP-specific permission mapping is out of scope for this config surface.
+
+Bundled agent markdown intentionally omits `model`. By default, emitted bundled agents also omit `model` so OpenCode inheritance keeps working. Systematic only emits a model when you configure `agents.<key>.model`; provider-specific zero-config model defaults are intentionally deferred.
+
+Overlay application precedence for a Systematic-owned bundled agent is strongest first:
+
+1. Exact `agents.<key>` overlay
+2. `categories.<category-id>` overlay
+3. Built-in Systematic policy defaults, such as temperature defaults
+4. Bundled markdown/frontmatter defaults
+5. OpenCode inherited defaults
+
+Native OpenCode agents with the same emitted key are full replacements. If `config.agent.security-sentinel` already exists in OpenCode config, `agents.security-sentinel` or `agents.review/security-sentinel` conflicts because ownership would be ambiguous. Category overlays skip native replacements and continue applying to the remaining Systematic-owned bundled agents in that category.
+
 ## Project-Specific Content
 
 One of Systematic's most powerful features is the ability to add your own skills and agents that live alongside (or override) the bundled ones.
@@ -50,11 +102,14 @@ If you create a project-specific asset with the same name as a bundled one, your
 
 Systematic resolves configuration and content in the following order (highest priority first):
 
-1.  **Project-level assets:** Files in `.opencode/`
-2.  **Project-level config:** `.opencode/systematic.json`
-3.  **User-level assets:** Files in `~/.config/opencode/`
-4.  **User-level config:** `~/.config/opencode/systematic.json`
-5.  **Bundled assets:** Content shipped with the plugin package
+1.  **Custom config directory:** `$OPENCODE_CONFIG_DIR/systematic.json` and assets under `$OPENCODE_CONFIG_DIR/systematic/`
+2.  **Project-level assets:** Files in `.opencode/`
+3.  **Project-level config:** `.opencode/systematic.json`
+4.  **User-level assets:** Files in `~/.config/opencode/`
+5.  **User-level config:** `~/.config/opencode/systematic.json`
+6.  **Bundled assets:** Content shipped with the plugin package
+
+Config-source merge precedence is separate from overlay application precedence. Across Systematic config files, `disabled_*` arrays are union-merged, `bootstrap` is shallow-merged, and top-level `agents`/`categories` maps merge by key. A higher-priority source replaces the whole object for the same `agents.<key>` or `categories.<id>` entry; unrelated keys survive. Project overlays are the exception for security fields: they cannot define `permission` or `skills`, and same-key project overlays preserve user-level `permission`/`skills` fields instead of erasing them. After that effective config is built, Systematic applies category and exact overlays to bundled agents using the overlay precedence above.
 
 ## Advanced Configuration
 
@@ -64,8 +119,19 @@ The Systematic configuration file is parsed as JSONC, meaning you can include co
 {
   // Disable git-worktree as we use a different branching model
   "disabled_skills": ["git-worktree"],
-  
-  // Custom agents are added in .opencode/agents/
-  "disabled_agents": []
+
+  // Custom agents are added in .opencode/agents/; bundled agents can also be
+  // tuned with overlays instead of copied.
+  "disabled_agents": [],
+  "categories": {
+    "research": {
+      "temperature": 0.2
+    }
+  },
+  "agents": {
+    "repo-research-analyst": {
+      "model": "anthropic/claude-sonnet-4-5"
+    }
+  }
 }
 ```

docs/src/content/docs/getting-started/configuration.mdx

@@ -155,6 +155,12 @@ export interface AgentModelViolation {
   message: string
 }
 
+export interface AgentStemViolation {
+  stem: string
+  files: string[]
+  message: string
+}
+
 export interface CheckResult {
   rootDir: string
   categories: string[]
@@ -164,6 +170,7 @@ export interface CheckResult {
   bannedPatterns: BannedPatternHit[]
   frontmatterViolations: FrontmatterViolation[]
   agentModelViolations: AgentModelViolation[]
+  agentStemViolations: AgentStemViolation[]
   exemptHits: ExemptHit[]
   scanStats: {
     markdownFiles: number
@@ -722,6 +729,34 @@ export function checkAgentModel(
   return violations
 }
 
+export function checkAgentStemUniqueness(
+  rootDir: string,
+  markdownFiles: readonly string[],
+): AgentStemViolation[] {
+  const filesByStem = new Map<string, string[]>()
+
+  for (const relPath of markdownFiles) {
+    if (!isAgentFile(relPath)) continue
+    if (!fs.existsSync(path.join(rootDir, relPath))) continue
+
+    const stem = path.basename(relPath, '.md')
+    const files = filesByStem.get(stem) ?? []
+    files.push(relPath)
+    filesByStem.set(stem, files)
+  }
+
+  return [...filesByStem.entries()]
+    .filter(([, files]) => files.length > 1)
+    .map(([stem, files]) => ({
+      stem,
+      files: [...files].sort(),
+      message:
+        `Duplicate bundled agent stem \`${stem}\` found in ${files.length} files. ` +
+        'V1 emits stem-only OpenCode agent keys, so bundled agent filenames must be globally unique across categories.',
+    }))
+    .sort((a, b) => a.stem.localeCompare(b.stem))
+}
+
 function isAgentFile(relPath: string): boolean {
   const parts = relPath.split('/')
   return (
@@ -836,6 +871,10 @@ export function checkContentIntegrity(rootDir: string): CheckResult {
   const brokenSubfileRefs = checkSubfileReferences(rootDir, targets.markdown)
   const frontmatterViolations = checkFrontmatter(rootDir, targets.markdown)
   const agentModelViolations = checkAgentModel(rootDir, targets.markdown)
+  const agentStemViolations = checkAgentStemUniqueness(
+    rootDir,
+    targets.markdown,
+  )
   const { hits: bannedPatterns, exempt: exemptHits } = checkBannedPatterns(
     rootDir,
     allScannedFiles,
@@ -851,6 +890,7 @@ export function checkContentIntegrity(rootDir: string): CheckResult {
     bannedPatterns,
     frontmatterViolations,
     agentModelViolations,
+    agentStemViolations,
     exemptHits,
     scanStats: {
       markdownFiles: targets.markdown.length,
@@ -890,6 +930,7 @@ function printResult(result: CheckResult, verbose: boolean): void {
   printBannedPatterns(result.bannedPatterns)
   printFrontmatterViolations(result.frontmatterViolations)
   printAgentModelViolations(result.agentModelViolations)
+  printAgentStemViolations(result.agentStemViolations)
 
   if (totalViolations(result) === 0) {
     process.stdout.write(
@@ -906,6 +947,7 @@ function printResult(result: CheckResult, verbose: boolean): void {
         `scanStats: ${result.scanStats.markdownFiles} md + ${result.scanStats.typescriptFiles} ts\n` +
         `frontmatterViolations: ${result.frontmatterViolations.length}\n` +
         `agentModelViolations: ${result.agentModelViolations.length}\n` +
+        `agentStemViolations: ${result.agentStemViolations.length}\n` +
         `exemptHits: ${result.exemptHits.length}\n`,
     )
   }
@@ -965,13 +1007,29 @@ function printAgentModelViolations(
   }
 }
 
+function printAgentStemViolations(
+  violations: readonly AgentStemViolation[],
+): void {
+  if (violations.length === 0) return
+  process.stderr.write(
+    `\nDuplicate bundled agent stems (${violations.length}):\n`,
+  )
+  for (const v of violations) {
+    process.stderr.write(`  ${v.stem}  ${v.message}\n`)
+    for (const file of v.files) {
+      process.stderr.write(`    ${file}\n`)
+    }
+  }
+}
+
 function totalViolations(result: CheckResult): number {
   return (
     result.phantomRefs.length +
     result.brokenSubfileRefs.length +
     result.bannedPatterns.length +
     result.frontmatterViolations.length +
-    result.agentModelViolations.length
+    result.agentModelViolations.length +
+    result.agentStemViolations.length
   )
 }