MAX-MSP_CC_Framework: Skill for Claude Code

Patch Generation Specialist

The Patch agent generates MAX/MSP .maxpat files focused on control-rate operations: object routing, message passing, subpatcher organization, MIDI handling, and data management.

Domain Context Loading

Before any generation:

1. Read CLAUDE.md at project root -- follow every rule (Rules #1-#9) and the patch style guidelines
2. Use ObjectDatabase from src.maxpat.db_lookup for all object lookups -- it loads all domains, resolves aliases, checks PD blocklist, and provides relationship data automatically
3. Read .claude/max-objects/relationships.json for common object pairings (if needed for design decisions)
4. Read project config.json via load_project_config() from src.maxpat.project for allowed packages. Pass allowed_packages to Patcher(allowed_packages=allowed) so package objects outside the project's selection are blocked at creation time. If load_project_config() returns None (no config.json), use allowed = [] (core-only), never None -- None allows every package.

Domain focus: Max control/data/UI objects. Signal processing and RNBO are handled by their respective agents.

Capabilities

Patch Construction

• Create Patcher instances with boxes and connections via src.maxpat.patcher
• Create standard objects with patcher.add_box(name, args, x, y) -- it looks the name up in ObjectDatabase (Rule #1) and returns the Box
• Create structural objects with the dedicated builders: add_subpatcher(), add_bpatcher(), add_gen()
• Connect boxes with Patcher.add_connection(src_box, src_outlet, dst_box, dst_inlet)

Key Functions

• Patcher() -- create a new patch
• Patcher.add_box(name, args=None, x=0.0, y=0.0) -- create a DB-validated box and add it to the patch (returns the Box). An explicit position is kept unless the box would truly overlap another; then it moves down in 15px steps and a BoxMovedWarning names the move (box.nudged_from holds the requested position).
• Patcher.add_connection(src_box, src_outlet, dst_box, dst_inlet) -- connect boxes
• Patcher.add_subpatcher(name, inlets=1, outlets=1, x=0.0, y=0.0, inlet_comments=None, outlet_comments=None) -- add a subpatcher with labeled I/O
• Patcher.populate_assistance_comments() -- auto-fill empty inlet/outlet comments from connection context
• finalize_patch(patcher, is_new=True, force_layout=False) -- single-call layout cleanup: styling, layout, comments, midpoints (new); comments + routing of new or touched cords that have no midpoints, never moving boxes or clearing midpoints (edit). With is_new=True it raises LayoutRefusedError (from src.maxpat.layout) before changing anything when a patcher it would lay out has >120 boxes or was saved by MAX; see "Output Protocol (New Patches)"
• apply_layout(patcher, options=None, force=False) -- row-based topological layout positioning (accepts LayoutOptions); same refusal, force=True overrides
• validate_patch(patcher.to_dict(), db=patcher.db) -- run the validation pipeline (Layers 1-5, every scope; pass patch_path= to resolve abstractions beside the file)
• save_patch_roundtrip(patcher.to_dict(), path) -- write .maxpat to disk
• Patcher.add_comment(text, x, y) -- add a comment box (for inline annotations, critic notes)
• Patcher.add_message(text, x, y) -- add a message box (for triggering messages, storing values)
• Patcher.add_box("node.script", ["myscript.js"], x=0.0, y=0.0) -- add a node.script box for Node for Max (DB entry: fixed 1 inlet / 2 outlets); write the script file with write_js(code, path)
• Patcher.add_js(filename, code=None, num_inlets=1, num_outlets=1, x=0.0, y=0.0) -- add a js object box (Legacy Engine, ES5 JavaScript) (returns tuple of Box and code string)