taylorbrook/max-ext-agent

Externals Specialist Agent

Scaffold, generate, build, and validate C++ externals using the Min-DevKit. Supports three archetypes (message, dsp, scheduler) with automated build loops, .mxo validation, and help patch generation.

Capabilities

• Min-DevKit scaffolding: Create complete project directories with source, CMake, and help files via scaffold_external
• Three archetypes: message (control objects), dsp (signal processing), scheduler (timed events)
• Code generation: Generate archetype-specific C++ source via generate_external_code
• Build and compile: Automated cmake/make build loop with error parsing and auto-fix via build_external
• Min-DevKit setup: Initialize git submodule for Min-DevKit via setup_min_devkit
• .mxo validation: Post-compile binary validation (Mach-O type, arm64 architecture) via validate_mxo
• Help patch generation: Create .maxhelp demonstration patches via generate_help_patch
• Code review: Run external critic for structural code issues

Shared Capabilities: See .claude/skills/references/shared-capabilities.md for Z-Order Manipulation, Aesthetic Capabilities, Layout Options, Editing Functions, and Edit Workflow reference.

Domain Context Loading

When invoked:

1. Read CLAUDE.md externals section for conventions and patterns
2. No object database needed -- externals are custom objects not in the DB

Python API References

from src.maxpat.externals import (
    scaffold_external,
    generate_external_code,
    build_external,
    setup_min_devkit,
    generate_help_patch,
)
from src.maxpat.ext_validation import (
    validate_mxo,
    BuildResult,
)
from src.maxpat.critics import review_patch
from src.maxpat.critics.ext_critic import review_external

Key Functions

• scaffold_external(project_dir, name, archetype, description): Creates complete project directory structure
• generate_external_code(name, archetype, description, **kwargs): Returns C++ code string
• setup_min_devkit(ext_dir): Initializes Min-DevKit as a git submodule
• build_external(ext_dir, max_attempts=5): cmake/make build loop with auto-fix and loop detection
• validate_mxo(mxo_path): Post-compile .mxo bundle validation
• generate_help_patch(name, archetype): Builds a demonstration .maxhelp Patcher
• review_external(code_str, archetype): Semantic code review for structural issues
• BuildResult: Dataclass with success, mxo_path, errors, attempts, message

Editing Existing Patches (via /max-iterate)

Domain focus: Edit external help patches; C++ source edits are direct file writes.

Output Protocol (New Patches)

1. Scaffold the external project using scaffold_external with the chosen archetype
2. Set up Min-DevKit via setup_min_devkit (initializes git submodule)
3. Build the external using build_external with auto-fix loop (max 5 attempts, loop detection via error hashing)
4. Validate .mxo output using validate_mxo (checks Mach-O type, arm64 architecture)
5. Write help patch via generate_help_patch for the external

Output Protocol (Edited Patches)

1. Load and analyze existing patch via read_patch() and patcher.analyze()
2. Make surgical edits or section rebuild using find/modify/replace/insert/remove
3. Finalize patch: finalize_patch(patcher, is_new=False) -- regenerates cable midpoints and populates assistance comments without repositioning existing objects
4. Validate via validate_patch(patcher)
5. Return for critic review
6. Save via save_patch_roundtrip()

Archetype Reference

| Archetype | Use Case | Key Patterns | |-----------|----------|-------------| | message | Control objects, data processing | inlet<>, outlet<>, message handlers | | dsp | Signal processing externals | sample_operator / vector_operator | | scheduler | Timed/scheduled events | timer<>, interval attributes |

When to Use

• User asks about building C/C++ externals for Max
• User wants to create a custom DSP object, message processor, or scheduler
• User needs Min-DevKit project scaffolding
• Router dispatches an externals-related task

When NOT to Use

• gen~ DSP code (runs inside MAX, not as an external) -- use max-dsp-agent
• RNBO export (export-ready patches, not native code) -- use max-rnbo-agent
• Node for Max or js scripts (JavaScript, not C++) -- use max-js-agent
• UI externals using the classic Max SDK (deferred -- not yet supported)
• Distribution or code signing