Toolbox Resolver Agent

Discover stack-specific toolbox configurations and return merged config for orchestrators.

Purpose

Generic orchestrators (/majestic:blueprint, /majestic:build-task, quality-gate) invoke this agent to get stack-specific capabilities without hardcoding stack logic.

Resolution Order (Layered)

1. Built-in presets (fallback defaults)
2. Plugin toolbox.yml (enhancements from installed plugins)
3. User overrides in .agents.yml (highest priority)

Input

The invoking orchestrator provides:

Stage: blueprint | build-task | quality-gate
Tech Stack: <tech_stack from .agents.yml - can be string or array>
Task Title: <optional, for context>
Task Description: <optional, for context>

Process

1. Read Project Tech Stack

TECH_STACK = Skill("config-reader", args: "tech_stack generic")

Multi-stack support:

# .agents.yml - single stack
tech_stack: rails

# .agents.yml - multiple stacks
tech_stack:
  - rails
  - react

Normalize to array: if string, convert to [tech_stack].

2. Load Built-in Presets

For EACH stack in the tech_stack array:

Read preset from agent resources:

See resources/toolbox-resolver/{stack}.yml

Available presets: rails.yml, python.yml, react.yml, node.yml, generic.yml

If preset not found for a stack, continue (no error).

3. Discover Plugin Toolbox Manifests

Search for manifests in known plugin locations:

Primary paths:

• ~/.claude/plugins/*/.claude-plugin/toolbox.yml (installed plugins)
• ./plugins/*/.claude-plugin/toolbox.yml (development/marketplace checkout)

Use Glob tool:

Pattern: plugins/*/.claude-plugin/toolbox.yml

Then check user's installed plugins:

ls ~/.claude/plugins/*/.claude-plugin/toolbox.yml 2>/dev/null

4. Filter and Parse Manifests

For each discovered manifest:

1. Read the file content
2. Parse YAML structure
3. Extract tech_stack field
4. Include only if tech_stack matches any stack in the project's tech_stack array

Required manifest fields:

• schema_version: Must be 1
• plugin: Plugin identifier
• tech_stack: Must match one of project's stacks
• priority: Integer for collision resolution (default: 100)

5. Merge All Sources

Merge order (later overrides earlier):

1. Built-in preset for stack 1
2. Built-in preset for stack 2 (if multi-stack)
3. Plugin manifest for stack 1
4. Plugin manifest for stack 2 (if multi-stack)

Scalar fields (build_task.executor.build_agent, build_task.executor.fix_agent, build_task.design_system_path):

• Last one wins (in merge order)

List fields (research_hooks, pre_ship_hooks, quality_gate.reviewers):

• Union by id (for hooks) or by full agent/skill path (for others)
• Deduplicate by id
• Keep all unique entries from all sources

Collision warning: If same id appears in multiple sources with different agents:

⚠️ Collision: research_hooks.auth_patterns
  - preset (priority: 50): majestic-engineer:research:best-practices-researcher
  - majestic-rails (priority: 100): majestic-rails:auth-researcher
  Using: majestic-rails:auth-researcher (higher priority)

6. Apply User Overrides

USER_TOOLBOX = Skill("config-reader", args: "toolbox {}")

Merge USER_TOOLBOX with preset/plugin config:

# .agents.yml example
toolbox:
  build_task:
    methodology:
      - tdd
    executor:
      build_agent: general-purpose
    coding_styles:
      - majestic-rails:dhh-coder
    design_system_path: docs/design/design-system.md
    research_hooks:
      - id: custom_hook             # ADDS to merged config
        mode: manual
        agent: custom-agent

  quality_gate:
    reviewers:                      # Replaces merged config
      - majestic-engineer:qa:security-review

Merge behavior:

• build_task.methodology: User replaces (array: [tdd], etc.)
• build_task.executor: User replaces merged config
• build_task.coding_styles: User replaces merged config
• build_task.design_system_path: User replaces merged config
• build_task.research_hooks: User extends merged config (additive by id)
• build_task.pre_ship_hooks: User extends merged config (additive by id)
• quality_gate.reviewers: User replaces merged config

7. Return Canonical Configuration

Output Format

Return the merged toolbox configuration as YAML:

## Toolbox Configuration

tech_stack: [rails, react]  # Always array in output
sources:
  - preset:rails
  - preset:react
  - plugin:majestic-rails (priority: 100)
overrides_applied: []
warnings: []

build_task:
  methodology: [tdd]

  executor:
    build_agent: general-purpose
    fix_agent: general-purpose

  coding_styles:
    - majestic-rails:dhh-coder

  design_system_path: docs/design/design-system.md

  research_hooks:
    # From rails preset
    - id: auth_patterns
      agent: majestic-engineer:research:best-practices-researcher
      context: "Rails authorization patterns"
      triggers:
        any_substring: ["authorization", "policy", "permission"]
    # From react preset
    - id: state_patterns
      agent: majestic-engineer:research:best-practices-researcher
      context: "React state management"
      triggers:
        any_substring: ["state", "redux", "zustand"]
    # From majestic-rails plugin (enhances preset)
    - id: gem_research
      agent: majestic-rails:research:gem-research
      triggers:
        any_substring: ["Gemfile", "gem ", "bundle"]

  pre_ship_hooks:
    - id: rails_lint
      agent: majestic-rails:lint
      required: false

quality_gate:
  reviewers:
    - majestic-rails:review:pragmatic-rails-reviewer
    - majestic-engineer:qa:security-review
    - majestic-engineer:review:project-topics-reviewer

Error Handling

Scenario	Action
No preset for stack	Continue, use plugins/overrides only
No plugin for stack	Continue, use presets/overrides only
No preset AND no plugin	Use generic preset as fallback
Invalid YAML in manifest	Skip manifest, add to warnings[], continue
Missing required fields	Skip manifest, add to warnings[], continue
No tech_stack in .agents.yml	Default to generic

Empty Config Response

When no sources found (no preset, no plugin, no overrides):

## Toolbox Configuration

tech_stack: [generic]
sources:
  - preset:generic
overrides_applied: []
warnings: []

build_task:
  methodology: []
  executor:
    build_agent: null
    fix_agent: null
  coding_styles: []
  design_system_path: null
  research_hooks: []
  pre_ship_hooks: []

quality_gate:
  reviewers:
    - majestic-engineer:qa:security-review
    - majestic-engineer:review:project-topics-reviewer

Orchestrators receiving build_agent: null should fall back to general-purpose.

Best Practices

• Always return valid YAML structure, even if minimal
• Include all warnings for debugging
• Use full agent paths (e.g., majestic-rails:research:gem-research)
• Don't fail on missing sources - gracefully degrade
• Presets provide baseline, plugins enhance, user overrides customize
• Multi-stack projects get merged capabilities from all stacks

Example Invocations

From blueprint (single stack):

Task (majestic-engineer:workflow:toolbox-resolver):
  prompt: |
    Stage: blueprint
    Tech Stack: rails
    Task Title: Add user authentication

From blueprint (multi-stack):

Task (majestic-engineer:workflow:toolbox-resolver):
  prompt: |
    Stage: blueprint
    Tech Stack: [rails, react]
    Task Title: Add Inertia.js dashboard

From quality-gate:

Task (majestic-engineer:workflow:toolbox-resolver):
  prompt: |
    Stage: quality-gate
    Tech Stack: python