Splitting design review into three pipelines: how I configured WorkBuddy SubAgent

I misunderstood multi-agent at first — I thought it just meant opening several windows at once and letting a few AIs chat with themselves. After getting WorkBuddy's SubAgent working, my view changed. What it really solves is task queuing — finish one job before dispatching the next, so everything doesn't pile up in the same context waiting.

A SubAgent is a temp worker dispatched by the main Agent. The main Agent doesn't do the actual work — it only breaks down tasks, dispatches jobs, and collects results; the temp workers each carry their own context, do the work, report back, and get destroyed. I buy this metaphor because it's exactly like my experience managing outsourced help — the thing I fear most is several people stepping on each other over the same file, not the work being hard per se.

My environment is the macOS desktop version of WorkBuddy, with the model going through a custom entry point connected to a third-party OpenAI-compatible API. By "OpenAI-compatible API" I mean the address and call format the other side provides match OpenAI's, so you just fill it in and it works. May not apply to everyone, but the approach holds.

It started last Wednesday — I had a batch of backend screenshots, a PRD, and three design-tokens.json files piled up, and I needed to do a visual review for a new backend. My old approach was to look at them one by one myself, and by the fortieth image my eyes started lying to me — I couldn't even tell a two-degree color difference.

First I went into Settings, then Model Services, selected Custom Model, and filled in the Base URL and Key. One detail here — the main Agent and SubAgent use the same Key and Base URL, so don't configure them in two places, otherwise when something goes wrong you'll have to check both ends. I learned this the hard way the first time — spent almost half an hour before realizing the SubAgent side was still pointing at the old endpoint.

After configuring, I created a new session, opened SubAgent from the skill entry next to the input box, and picked a type. I commonly use three types in WorkBuddy. general-purpose has full capabilities — can read/write files and run commands; Explore is read-only — can look but not modify; Plan leans toward analysis and planning. Picking the wrong type is the source of a whole pile of pitfalls later.

My breakdown was three parallel tracks. The first went to Explore — have it read-only scan the screenshot directory and output the page module and current color values for each image. The second went to Explore — have it read the three design-tokens.json files, align variable names with actual colors used, and list the mismatches. The third went to general-purpose — have it read the PRD and break design constraints into verifiable fields: Context, Goal, Inputs, Constraints, each of which must be reducible to a single sentence.

Here's a key point — task briefs can't contain adjectives. If you write "the style should be a bit cleaner," what it gives you will definitely not be clean. You have to write "background color may only come from the --bg-* series in tokens; a third gray scale is forbidden." The main Agent's job is translating your vague requirements into verifiable fields — that's something only you can do, it can't replace you.

It ran for about twenty minutes, way faster than flipping through them one by one. The three tracks' results didn't contaminate each other — that felt great. When Explore was scanning images it didn't drag in the PRD context, and the output was as clean as a freshly washed cup.

But there were plenty of pitfalls too. The first time, to save effort, I gave all three tracks general-purpose, and the one reading the PRD went ahead and renamed the original images in my assets directory, adding a bunch of prefixes. My blood pressure spiked. Later I learned my lesson — anything touching file read/write, always give it to Explore first, confirm it only needs to read, then consider granting permissions. I wrote a post about this two months ago saying I only dared let it touch the assets directory after hooking up DeepSeek — looking back, that was still too optimistic. Grading by tool alone isn't enough; you have to grade by SubAgent type.

Another pitfall is that context isn't shared. After the main Agent breaks down tasks and dispatches them, SubAgents can't see each other's results, so the aggregation step must be done by the main Agent. My approach is to add a line at the end of the task description requiring each track to output fixed fields, like "module name / current value / expected value / consistent?" — only when the four columns align can it aggregate. If a field name is off by one character, the whole column comes back empty — I wrangled with it over this for a long time.

On collaboration, here's how I split it. Design source files and tokens files go in a shared directory that all three people on the team can read.

SubAgent configs and task templates only I can modify — once parameters get messy, the output is all noise. After review conclusions are exported as a table, they get dropped in the group chat; anyone with objections annotates on the table instead of discussing verbally.

Day-to-day ops is just two things. First, after every run, always look at the SubAgent's report — don't just look at the main Agent's summary. What the temp workers say often hides problems they didn't dare escalate. Second, close the session when the task ends — don't leave long sessions running continuously; the more the context piles up, the dirtier it gets, like an unwashed palette.

Up to now, I've genuinely gone from executor to someone who only dispatches work and does acceptance.