Feat: Agent model settings with three quality presets

[sea212]

Related to #13

Description

This pull request introduces a system for configuring subagent models based on user-selectable model quality presets (quality, balanced, economic). The orchestrator now asks the user about the model quality preset and applies the model quality preset config in a project-specific settings.json via a newly introduced setup-models mcp. This allows for granular control over model selection for specialized subagents, enabling users to optimize for output quality or token efficiency.

Key Changes

🛠️ Subagent Model Mapping System

• Presets Config: Added src/config/agent-modes.json which defines model mappings for all specialized agents across three modes:
  • quality: Prioritizes high-tier models.
  • balanced: A mix of Pro and Flash models.
  • economic: Maximizes usage of lightweight Flash models.
• MCP Tool: Implemented setup_models (src/mcp/handlers/setup-models.js) to apply these mappings to the project-local .gemini/settings.json.
• Tool Integration: Registered the new functionality in the workspace tool pack.

🔄 Orchestration Workflow Enhancements

• New Step: Integrated a mandatory "Define Agent Models" step into both Standard and Express orchestration flows.
• Workflow Renumbering: Updated src/references/orchestration-steps.md and related platform variants to maintain sequential accuracy:
  • Step 11 (Standard) is now "Define Agent Models".
  • Step 33 (Express) is now "Define Agent Models".
• Logic Updates: Modified orchestrate.toml across all variants to prompt for quality mode selection and trigger the model setup.

📁 Infrastructure & Setup

• .gitignore: Added .worktrees to the exclusion list.
• Cross-Platform Sync: Synchronized changes across src/, claude/, and plugins/maestro/ to ensure consistent behavior across all Maestro entry points.

📒 Final Notes

• Alternative approach to apply models considered: Gemini-Cli BeforeModel hook system. Currently blocked by Hooks: Attach agent information google-gemini/gemini-cli#21615
• "no (project-specific) settings.json write policy" broken. No other way to apply model configurations as of now.
• Review of model mapping highly recommended.
• In regards to there should be a way to force a phase (and/or agent) to use a specific model #13 , users can now edit the generated settings.json (project-specific) or the extensions agent-modes.json (global) to specify their own agent to model mappings. Orchestrator model-per-phase logic still tbd.
• zero_diff.test.js demands that setup-models.js and agent-modes.json exist identically in claude and plugins/maestro directory. This is nonsensical, as those files are gemini-specific. However, in orchestrate.toml, Claude and Codex are instructed to do nothing when setting up agents, effectively rendering those nonsensical files useless in those cases.

Summary table of changes

Category	Files Changed
New Features	src/config/agent-modes.json, src/mcp/handlers/setup-models.js
Workflows	src/references/orchestration-steps.md, claude/src/references/orchestration-steps.md, plugins/maestro/src/references/orchestration-steps.md
Commands	src/platforms/gemini/commands/maestro/orchestrate.toml, commands/maestro/orchestrate.toml (and others)
Infrastructure	.gitignore, src/mcp/tool-packs/workspace/index.js

[josstei]

Review Summary

Nice feature — the preset system is well-structured and the cross-file synchronization is thorough. Requesting changes for one bug and a few model assignment refinements.

Requesting changes

1. [Bug] Settings merge in setup-models.js — Current code stomps existing agent override properties. Must shallow-merge to preserve non-modelConfig fields.
2. [Quality preset] — coder and refactor should use Pro. These are the core code-producing agents; users choosing "quality" expect top-tier models here.
3. [Economic preset] — architect and product_manager should use Flash. These are planning agents whose outputs are user-reviewed — Flash is sufficient.
4. [Tests] — Add test coverage for handleSetupModels following existing patterns in tests/transforms/.
5. [Nit] — Validate agent names against KNOWN_AGENTS at load time to prevent config drift.

What looks good

• All 4 orchestrate.toml copies and all 3 orchestration-steps.md copies are correctly synchronized
• All 40+ internal step references correctly renumbered
• Handler follows existing codebase conventions (signature, error handling, atomic writes, JSDoc)
• Defense-in-depth input validation (JSON schema enum + handler-level check)
• skip option for graceful opt-out

---

Generated by Claude Code

[josstei]

All 5 review items have been addressed:

1. Bug fix — Agent overrides now shallow-merge, preserving existing non-modelConfig properties ✓
2. Quality preset — coder and refactor upgraded to Pro ✓
3. Economic preset — architect and product_manager downgraded to Flash ✓
4. Tests — Full coverage added in mcp-setup-models.test.js covering all 6 requested scenarios (skip, invalid mode, fresh file, merge preservation, corrupted file, missing config) ✓
5. Agent validation — Test-time validation against KNOWN_AGENTS added; codebase_investigator gap resolved ✓

---

Generated by Claude Code

[sea212]

@josstei Applied all suggestions, PR is ready for review.

[josstei]

Reopening review — the check-architecture workflow is failing on two issues:

1. Adapter drift (4 files out of sync)

node scripts/generate.js produces changes that aren't committed. The following generated files need to be regenerated and committed:

• claude/src/core/agent-registry.js
• claude/src/mcp/tool-packs/workspace/index.js
• plugins/maestro/src/core/agent-registry.js
• plugins/maestro/src/mcp/tool-packs/workspace/index.js

Fix: run node scripts/generate.js and commit the output.

2. Two existing tests don't account for setup_models (190 pass, 2 fail)

The new setup_models tool was registered in the workspace pack but two existing test files still have hardcoded expected tool lists that don't include it:

• tests/transforms/mcp-workspace-pack.test.js — expects [initialize_workspace, assess_task_complexity, validate_plan, resolve_settings], actual now includes setup_models
• tests/transforms/mcp-pack-composition.test.js — same issue with the full tool list assertion

Fix: add 'setup_models' to the expected arrays in both test files.

---

The prior review items (shallow-merge bug, preset adjustments, new test coverage) all look good. Just these CI fixes remaining.

---

Generated by Claude Code

[josstei]

Dismissing prior request — the CI failures are minor integration oversights (2 test fixtures missing setup_models in expected arrays + node scripts/generate.js needs a rerun). All substantive review items from the original review have been addressed.

---

Generated by Claude Code

[josstei]

Feature looks good and all review items are addressed. Deferring merge until next release to align with upcoming architectural shifts. The platform layer is changing significantly so this will likely need a rebase before it can land.

[josstei]

Requesting changes for the critical registry architecture conflict — the PR patches a hardcoded KNOWN_AGENTS array that main has replaced with auto-generated registries (src/generated/agent-registry.json). This needs a rebase and strategy change before it can merge.

See the detailed comment above for the full analysis, including the codebase_investigator design question and agents.overrides schema verification.

---

Generated by Claude Code

[josstei]

Analysis: Rebase Requirements and Open Design Questions

1. Registry Architecture Conflict (Critical — blocks merge)

src/core/agent-registry.js on main no longer has a hardcoded KNOWN_AGENTS array. It was replaced with auto-generated registries:

// src/core/agent-registry.js (main, lines 1-8)
const agentRegistryData = require('../generated/agent-registry.json');
const KNOWN_AGENTS = Object.freeze(
  agentRegistryData.map((entry) => toSnakeCase(entry.name))
);

The registry is now built at generate-time by src/generator/registry-scanner.js, which scans src/agents/*.md and outputs src/generated/agent-registry.json. The CHANGELOG (Unreleased section) documents this: "Build-time auto-discovered registries — agent-registry.json, resource-registry.json, hook-registry.json scanned at generate time, replacing hardcoded allowlists."

The PR's changes to agent-registry.js (and the detached copies in claude/src/ and plugins/maestro/src/) patch code that no longer exists, which is why mergeable_state is "dirty".

Resolution path: On rebase, drop the agent-registry.js changes. To add codebase_investigator to the registry, create a definition file at src/agents/codebase-investigator.md so the scanner picks it up — but see the next section on whether that's the right approach.

---

2. codebase_investigator in the Agent Roster (Design Decision Needed)

No src/agents/codebase-investigator.md exists. There are 22 agent definitions in src/agents/, none for codebase_investigator (verified via src/generated/agent-registry.json).

The identifier refers to a platform built-in, not a Maestro-defined agent:

• On Gemini, it's a native Gemini CLI agent
• On Claude, it maps to Agent (Explore) / Grep / Glob (src/platforms/claude/runtime-config.js:33)
• On Codex, it maps to local inspection or spawn_agent (src/platforms/codex/runtime-config.js:35)

Adding it to KNOWN_AGENTS has a side effect: validate_plan in src/mcp/handlers/validate-plan.js uses this list to check for unknown agents. Plans referencing codebase_investigator would go from triggering an "unknown agent" warning to being silently accepted, even though there's no Maestro methodology, tools list, or capabilities definition backing it.

Question: Is the intent to (a) create a Maestro agent definition wrapping the built-in, or (b) treat it as a special case in agent-modes.json only? If (b), it shouldn't be added to the agent registry.

---

3. agents.overrides Schema Verification (Should Confirm)

setup-models.js writes this structure to .gemini/settings.json:

{
  "agents": {
    "overrides": {
      "coder": {
        "modelConfig": { "model": "gemini-3.1-pro-preview" }
      }
    }
  }
}

No documentation within this codebase confirms modelConfig: { model } is the correct Gemini CLI schema for agent overrides:

• GEMINI.md:61 mentions agents.overrides but doesn't document its structure
• CHANGELOG v1.3.0 says model tuning uses "agent frontmatter and Gemini CLI agents.overrides" but provides no schema
• The BeforeModel hook was removed because "Gemini CLI discards model field from hook output" (CHANGELOG v1.1.1, Removed section)

If the schema doesn't match what Gemini CLI expects, the feature silently has no effect — Gemini CLI ignores unrecognized keys, and users see no model changes after restart. Has this been validated against Gemini CLI's settings parser?

---

4. Cross-Runtime Cleanup (Not Blocking)

Two artifacts ship to non-Gemini runtimes unnecessarily:

1. agent-modes.json (containing Gemini-specific model IDs like gemini-3.1-pro-preview) gets copied to Claude and Codex payloads. The config/ prefix is in DETACHED_PAYLOAD_BASE_ALLOWLIST (src/generator/payload-builder.js:16), so everything under src/config/ ships to all runtimes.
2. The setup_models MCP tool is registered for all runtimes, even though it writes to .gemini/settings.json.

Options: exclude agent-modes.json from non-Gemini payloads, or have setup_models return early with a message when the runtime is not Gemini.

---

5. Restart UX (Minor)

The mandatory restart at step 11 (Standard) / step 33 (Express) interrupts the workflow mid-phase. In Standard mode, it falls after entering Plan Mode but before the design dialogue — conversational context is lost on restart.

The PR notes this is blocked by the BeforeModel hook approach (gemini-cli#21615). If a restart remains unavoidable, moving the model setup step to the very beginning of the workflow (before Plan Mode entry) would minimize context loss. Tradeoff: model selection happens before the task is understood, but since all 23 agents are configured regardless, timing doesn't change the outcome.

---

Summary

Issue	Severity	Blocks Merge?
Registry architecture conflict	Critical	Yes — requires rebase + strategy change
codebase_investigator identity	Significant	Needs design decision
agents.overrides schema unverified	Significant	Should confirm before merge
Cross-runtime artifact cleanup	Low	No
Restart UX / step placement	Low	No

---

Generated by Claude Code

[sea212]

@josstei Before beginning to work, please review the approach:

1. • 2.: I'll hardcode acceptance of codebase_investigator in setup_models hook for Gemini only, instead of solely relying on KNOWN_AGENTS
2. That's the correct approach
3. I'll try to figure out a way that the config and MCP are not copied or are a NOOP for other runtimes than Gemini right now
4. As it is right now, it only happens in Gemini environment. I'll try to preserve that. Gemini allows to restore session context

as a side note, I think trying to create the golden hen that works in every agent runtime is destined to fail. From my experience from countless other tools, it just massively bloats the codebase and doesn't work properly for runtimes other than the one it was originally designed for.
Building multiples standalone tools that are crafted for one runtime each and that respect the runtimes own way of dealing with processes is the way to go. Everything else just becomes a Frankenstein patchwork that massively complicates maintenance and doesn't work properly in all runtimes anyways.