@wpro-eng/opencode-config 1.6.0 → 1.7.1

package/README.md

@@ -62,9 +62,36 @@ Create `~/.config/opencode/wpromote.json` or `~/.config/opencode/wpromote.jsonc`
 |--------|------|---------|-------------|
 | `disable` | `string[]` | `[]` | Assets to disable (see below) |
 | `installMethod` | `"link"` \| `"copy"` | `"link"` | How to install skills/plugins/MCPs |
+| `agentNames` | `"lotr"` \| `"descriptive"` | `"descriptive"` | Agent naming theme (see below) |
 | `dryRun` | `boolean` | `false` | Preview changes without installing |
 | `orchestration` | `object` | defaults | Runtime orchestration controls, limits, and fallback policy |
 
+### Agent Name Themes
+
+Agents can be displayed with either plain role-based names or Tolkien character names. Set `agentNames` in your config:
+
+```json
+{
+  "agentNames": "lotr"
+}
+```
+
+| Role | `"descriptive"` (default) | `"lotr"` |
+|------|--------------------------|----------|
+| Orchestrator | `orchestrator` | `gandalf` |
+| Explorer | `explorer` | `legolas` |
+| Researcher | `researcher` | `radagast` |
+| Planner | `planner` | `treebeard` |
+| Implementer | `implementer` | `celebrimbor` |
+| Architect | `architect` | `elrond` |
+| Analyst | `analyst` | `galadriel` |
+| TDD | `tdd` | `aragorn` |
+| Deep Work | `deepwork` | `samwise` |
+
+The theme affects agent names everywhere: in the agent list, slash commands, delegation routing, and cross-references between agents. Agent markdown files use template variables (e.g. `{{explorer}}`) so cross-references resolve correctly regardless of theme.
+
+When using the disable list, use the **themed name** (the name that appears after applying your chosen theme). For example, with `"descriptive"` theme, disable with `"agent:orchestrator"` instead of `"agent:gandalf"`.
+
 ### Orchestration Runtime Configuration
 
 All fields below show their **defaults**. You only need to include fields you want to override.
@@ -251,26 +278,26 @@ EOF
 
 ### Agents (`agent/`)
 
-Pre-configured agent definitions with model, temperature, and system prompts. There are two **primary** agents (you talk to them directly) and seven **subagents** (they run in the background, delegated by the primary agent).
+Pre-configured agent definitions with model, temperature, and system prompts. There are two **primary** agents (you talk to them directly) and seven **subagents** (they run in the background, delegated by the primary agent). Names shown below use the default `"descriptive"` theme, with `"lotr"` names in parentheses.
 
 #### Primary Agents
 
 | Agent | Model | What it does |
 |-------|-------|--------------|
-| `gandalf` | Claude Opus 4 | The default orchestrator. Classifies your request, breaks it into tasks, delegates to the right subagents in parallel, and assembles the final result. Handles everything from quick fixes to multi-step projects. |
-| `samwise` | Claude Opus 4 | A higher-rigor variant of Gandalf for long-running complex work. Runs a sustained execution loop with tighter milestone verification, aggressive parallelism, and continuous health monitoring. Use when a task needs hours of autonomous work without hand-holding. |
+| `orchestrator` (`gandalf`) | Claude Opus 4 | The default orchestrator. Classifies your request, breaks it into tasks, delegates to the right subagents in parallel, and assembles the final result. Handles everything from quick fixes to multi-step projects. |
+| `deepwork` (`samwise`) | Claude Opus 4 | A higher-rigor variant for long-running complex work. Runs a sustained execution loop with tighter milestone verification, aggressive parallelism, and continuous health monitoring. Use when a task needs hours of autonomous work without hand-holding. |
 
 #### Subagents
 
-| Agent | Model | When Gandalf calls it | What it does |
-|-------|-------|-----------------------|--------------|
-| `legolas` | Claude Sonnet 4.6 | "Where is X in the codebase?" | Searches the repo fast. Uses LSP, grep, glob, and git to find files, symbols, call paths, and code patterns. Returns structured results with absolute paths and a direct answer, not just a file list. Read-only by default. |
-| `radagast` | GPT-5.2 | "How does library X work?" | Researches external docs, OSS repos, and the web. Classifies the question (conceptual, implementation, history, or comprehensive), fetches official sources, and returns evidence-backed recommendations with links. |
-| `treebeard` | GPT-5.2 | "Is this plan solid?" | Reviews plans for ambiguity, risk, and executability before implementation starts. Surfaces hidden assumptions, produces concrete acceptance criteria, and gives a clear OKAY or REJECT verdict with at most 3 blocking issues. |
-| `celebrimbor` | GPT-5.2 Codex | "Build this end-to-end." | The workhorse implementation agent. Operates like a senior staff engineer: explores context, plans edits, executes changes, runs tests, and iterates until done. Does not stop at partial progress or ask permission for normal engineering work. |
-| `elrond` | GPT-5.2 | "What's the right architecture?" | Read-only strategic advisor. Analyzes codebases, evaluates tradeoffs, and returns a bottom-line recommendation with an action plan and effort estimate. Biases toward simplicity and existing patterns over speculative complexity. |
-| `galadriel` | Gemini 3.1 Pro | "What's in this image/PDF?" | Multimodal analysis specialist. Handles PDFs, images, diagrams, and charts that other agents cannot process as plain text. Extracts targeted information and returns concise findings with confidence notes. |
-| `aragorn` | GPT-5.2 Codex | "Write tests for this." | Strict TDD specialist following Red-Green-Refactor. Writes a failing test first, makes it pass with minimal code, then refactors under green. Produces a test plan, TDD log, execution results, and a quality scorecard. Never writes production code without a failing test. |
+| Agent | Model | When called | What it does |
+|-------|-------|-------------|--------------|
+| `explorer` (`legolas`) | Claude Sonnet 4.6 | "Where is X in the codebase?" | Searches the repo fast. Uses LSP, grep, glob, and git to find files, symbols, call paths, and code patterns. Returns structured results with absolute paths and a direct answer, not just a file list. Read-only by default. |
+| `researcher` (`radagast`) | GPT-5.2 | "How does library X work?" | Researches external docs, OSS repos, and the web. Classifies the question (conceptual, implementation, history, or comprehensive), fetches official sources, and returns evidence-backed recommendations with links. |
+| `planner` (`treebeard`) | GPT-5.2 | "Is this plan solid?" | Reviews plans for ambiguity, risk, and executability before implementation starts. Surfaces hidden assumptions, produces concrete acceptance criteria, and gives a clear OKAY or REJECT verdict with at most 3 blocking issues. |
+| `implementer` (`celebrimbor`) | GPT-5.2 Codex | "Build this end-to-end." | The workhorse implementation agent. Operates like a senior staff engineer: explores context, plans edits, executes changes, runs tests, and iterates until done. Does not stop at partial progress or ask permission for normal engineering work. |
+| `architect` (`elrond`) | GPT-5.2 | "What's the right architecture?" | Read-only strategic advisor. Analyzes codebases, evaluates tradeoffs, and returns a bottom-line recommendation with an action plan and effort estimate. Biases toward simplicity and existing patterns over speculative complexity. |
+| `analyst` (`galadriel`) | Gemini 3.1 Pro | "What's in this image/PDF?" | Multimodal analysis specialist. Handles PDFs, images, diagrams, and charts that other agents cannot process as plain text. Extracts targeted information and returns concise findings with confidence notes. |
+| `tdd` (`aragorn`) | GPT-5.2 Codex | "Write tests for this." | Strict TDD specialist following Red-Green-Refactor. Writes a failing test first, makes it pass with minimal code, then refactors under green. Produces a test plan, TDD log, execution results, and a quality scorecard. Never writes production code without a failing test. |
 
 ### Commands (`command/`)
 

package/agent/{gandalf.md → orchestrator.md}

@@ -25,12 +25,12 @@ Orchestration workflow:
 
 Delegation routing:
 
-- `legolas` for internal codebase discovery.
-- `radagast` for external docs and OSS references.
-- `treebeard` for pre-planning analysis and plan review.
-- `celebrimbor` for end-to-end implementation execution.
-- `elrond` for architecture/security/performance tradeoff consultation.
-- `galadriel` for image/PDF/diagram interpretation.
+- `{{explorer}}` for internal codebase discovery.
+- `{{researcher}}` for external docs and OSS references.
+- `{{planner}}` for pre-planning analysis and plan review.
+- `{{implementer}}` for end-to-end implementation execution.
+- `{{architect}}` for architecture/security/performance tradeoff consultation.
+- `{{analyst}}` for image/PDF/diagram interpretation.
 
 Delegation prompt quality:
 

package/command/diagnostics.md

@@ -17,15 +17,15 @@ Instructions:
 
 4. Spawn 4 subagent probes in parallel using the `task` tool. Each probe must be a trivial, fast, read-only task that proves the delegation pipeline works end-to-end. Do NOT run destructive or write operations.
 
-   **Probe A — legolas (codebase exploration)**:
+   **Probe A — {{explorer}} (codebase exploration)**:
    - Task: "List the top-level directories and count of files in this repo. Return the directory listing."
    - Expected: completes with a directory listing.
 
-   **Probe B — radagast (external research)**:
+   **Probe B — {{researcher}} (external research)**:
    - Task: "What license does the tmux terminal multiplexer use? Search the web and return the license name (e.g. MIT, BSD, ISC, GPL)."
    - Expected: completes with a license name (ISC).
 
-   **Probe C — treebeard (planning)**:
+   **Probe C — {{planner}} (planning)**:
    - Task: "Review this single-sentence plan and identify one risk: 'We will migrate all configs to YAML next sprint.' Return your risk assessment in 2-3 sentences."
    - Expected: completes with a short risk assessment.
 

package/dist/index.js

@@ -8346,6 +8346,7 @@ function logWarn(message) {
 var UserConfigSchema = exports_external.object({
   disable: exports_external.array(exports_external.string()).default([]),
   installMethod: exports_external.enum(["link", "copy"]).default("link"),
+  agentNames: exports_external.enum(["lotr", "descriptive"]).default("descriptive"),
   dryRun: exports_external.boolean().default(false),
   orchestration: exports_external.object({
     providerMode: exports_external.enum(["copilot", "native"]).default("copilot"),
@@ -8396,6 +8397,7 @@ var UserConfigSchema = exports_external.object({
 var DEFAULT_CONFIG = {
   disable: [],
   installMethod: "link",
+  agentNames: "descriptive",
   dryRun: false,
   orchestration: {
     providerMode: "copilot",
@@ -8610,16 +8612,50 @@ function discoverInstructions(repoPath) {
   return instructions;
 }
 
+// src/agent-names.ts
+var AGENT_NAME_TABLE = [
+  { canonical: "orchestrator", role: "orchestrator", themed: { lotr: "gandalf", descriptive: "orchestrator" } },
+  { canonical: "explorer", role: "explorer", themed: { lotr: "legolas", descriptive: "explorer" } },
+  { canonical: "researcher", role: "researcher", themed: { lotr: "radagast", descriptive: "researcher" } },
+  { canonical: "planner", role: "planner", themed: { lotr: "treebeard", descriptive: "planner" } },
+  { canonical: "implementer", role: "implementer", themed: { lotr: "celebrimbor", descriptive: "implementer" } },
+  { canonical: "architect", role: "architect", themed: { lotr: "elrond", descriptive: "architect" } },
+  { canonical: "analyst", role: "analyst", themed: { lotr: "galadriel", descriptive: "analyst" } },
+  { canonical: "tdd", role: "tdd", themed: { lotr: "aragorn", descriptive: "tdd" } },
+  { canonical: "deepwork", role: "deepwork", themed: { lotr: "samwise", descriptive: "deepwork" } }
+];
+var BY_CANONICAL = new Map(AGENT_NAME_TABLE.map((e) => [e.canonical, e]));
+function resolveAgentName(canonical, theme) {
+  const entry = BY_CANONICAL.get(canonical);
+  if (!entry)
+    return canonical;
+  return entry.themed[theme];
+}
+function buildTemplateVars(theme) {
+  const vars = {};
+  for (const entry of AGENT_NAME_TABLE) {
+    vars[entry.role] = entry.themed[theme];
+  }
+  return vars;
+}
+function resolveTemplateVars(text, vars) {
+  return text.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    if (key in vars)
+      return vars[key];
+    return match;
+  });
+}
+
 // src/assets.ts
 var DISCOVERY_LIMITS = {
   maxFiles: 100,
   maxFileSize: 256 * 1024,
   maxDepth: 10
 };
-async function discoverAssets(packageRoot) {
+async function discoverAssets(packageRoot, theme = "descriptive") {
   const skills = await discoverSkills(packageRoot);
-  const agents = await discoverAgents(packageRoot);
-  const commands = await discoverCommands(packageRoot);
+  const agents = await discoverAgents(packageRoot, theme);
+  const commands = await discoverCommands(packageRoot, theme);
   const plugins = await discoverPlugins(packageRoot, REPO_SHORT_NAME);
   const instructions = discoverInstructions(packageRoot);
   const mcps = await discoverMcps(packageRoot);
@@ -8668,13 +8704,14 @@ async function discoverSkills(repoPath) {
   findSkills(skillDir, 0);
   return skills;
 }
-async function discoverAgents(repoPath) {
+async function discoverAgents(repoPath, theme = "descriptive") {
   const agents = [];
   let filesProcessed = 0;
   let warned = false;
   const agentDir = path.join(repoPath, "agent");
   if (!fs.existsSync(agentDir))
     return agents;
+  const templateVars = buildTemplateVars(theme);
   const walk = (dir, depth) => {
     if (depth > DISCOVERY_LIMITS.maxDepth) {
       if (!warned) {
@@ -8708,7 +8745,7 @@ async function discoverAgents(repoPath) {
           }
           filesProcessed++;
           const content = fs.readFileSync(fullPath, "utf-8");
-          const parsed = parseAgentMarkdown(fullPath, content, agentDir);
+          const parsed = parseAgentMarkdown(fullPath, content, agentDir, theme, templateVars);
           if (parsed)
             agents.push(parsed);
         } catch (err) {
@@ -8720,7 +8757,7 @@ async function discoverAgents(repoPath) {
   walk(agentDir, 0);
   return agents;
 }
-function parseAgentMarkdown(filePath, content, agentDir) {
+function parseAgentMarkdown(filePath, content, agentDir, theme, templateVars) {
   let md;
   try {
     const yamlEngine = require_engines().yaml;
@@ -8754,15 +8791,21 @@ function parseAgentMarkdown(filePath, content, agentDir) {
     logError(`Invalid agent config in ${filePath}: ${JSON.stringify(result.error.format())}`);
     return null;
   }
-  return { name: agentName, path: filePath, config: result.data };
+  const themedName = resolveAgentName(agentName, theme);
+  const resolvedConfig = { ...result.data };
+  if (resolvedConfig.prompt) {
+    resolvedConfig.prompt = resolveTemplateVars(resolvedConfig.prompt, templateVars);
+  }
+  return { name: themedName, path: filePath, config: resolvedConfig };
 }
-async function discoverCommands(repoPath) {
+async function discoverCommands(repoPath, theme = "descriptive") {
   const commands = [];
   let filesProcessed = 0;
   let warned = false;
   const commandDir = path.join(repoPath, "command");
   if (!fs.existsSync(commandDir))
     return commands;
+  const templateVars = buildTemplateVars(theme);
   const walk = (dir, depth) => {
     if (depth > DISCOVERY_LIMITS.maxDepth) {
       if (!warned) {
@@ -8796,7 +8839,7 @@ async function discoverCommands(repoPath) {
           }
           filesProcessed++;
           const content = fs.readFileSync(fullPath, "utf-8");
-          const parsed = parseCommandMarkdown(fullPath, content, commandDir);
+          const parsed = parseCommandMarkdown(fullPath, content, commandDir, templateVars);
           if (parsed)
             commands.push(parsed);
         } catch (err) {
@@ -8808,7 +8851,7 @@ async function discoverCommands(repoPath) {
   walk(commandDir, 0);
   return commands;
 }
-function parseCommandMarkdown(filePath, content, commandDir) {
+function parseCommandMarkdown(filePath, content, commandDir, templateVars) {
   let md;
   try {
     const yamlEngine = require_engines().yaml;
@@ -8840,7 +8883,11 @@ function parseCommandMarkdown(filePath, content, commandDir) {
     logError(`Invalid command config in ${filePath}: ${JSON.stringify(result.error.format())}`);
     return null;
   }
-  return { name: commandName, path: filePath, config: result.data };
+  const resolvedConfig = { ...result.data };
+  if (resolvedConfig.template) {
+    resolvedConfig.template = resolveTemplateVars(resolvedConfig.template, templateVars);
+  }
+  return { name: commandName, path: filePath, config: resolvedConfig };
 }
 async function discoverPlugins(repoPath, repoShortName) {
   const plugins = [];
@@ -10083,7 +10130,7 @@ var DEFAULT_OPENCODE_AGENTS_TO_DISABLE = ["build", "plan"];
 async function performLoad(config) {
   const disableMatcher = createDisableMatcher(config.disable);
   log(config.dryRun ? "[DRY-RUN] Analyzing team configuration..." : "Loading team configuration...");
-  const result = await discoverAssets(PACKAGE_ROOT);
+  const result = await discoverAssets(PACKAGE_ROOT, config.agentNames);
   if (!config.dryRun) {
     const brokenUnmanagedLinks = findBrokenUnmanagedPluginLinks();
     if (brokenUnmanagedLinks.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wpro-eng/opencode-config",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Wpromote OpenCode plugin to sync team config assets on startup",
   "repository": {
     "type": "git",