https://futurewithml.netlify.app
|
This is a web feed, also known as an Atom feed. Subscribe by copying the URL from the address bar into your newsreader. Visit About Feeds to learn more and get started. It's free.
Visit website
Recent posts
Updated on $DATE
date
Hybrid Architecture
Future With ML - Hybrid Architecture
Machine Learning Design Patterns, MLOps, and AI Engineering insights by Christian Picon Calderon
Zola2026-01-06T11:00:00+00:00https://futurewithml.netlify.app/tags/hybrid-architecture/atom.xml
The Hybrid Architecture Pattern: Lessons from agent-team-creator
2026-01-06T11:00:00+00:00
2026-01-06T11:00:00+00:00
Christian Picon Calderon
https://futurewithml.netlify.app/posts/claude-code-plugin-journey-part1/
<h1 id="the-hybrid-architecture-pattern-lessons-from-agent-team-creator">The Hybrid Architecture Pattern: Lessons from agent-team-creator</h1>
<blockquote>
<p><em>This is Part 1 of a three-part series. Start with <a href="/posts/claude-code-plugin-journey-part0/">Part 0: Agent Team Creator</a> to see what the plugin does, or continue here for the development journey.</em></p>
</blockquote>
<p>I thought building a Claude Code plugin would take a weekend. Three days into wrestling with MCP tool access bugs, three-location file synchronization, and documentation that promised features that didn’t work, I realized I was building something more valuable than a plugin—I was mapping uncharted territory.</p>
<p>This is the story of building <strong>agent-team-creator</strong>, a Claude Code plugin that analyzes codebases and generates project-specific AI agents. Along the way, I discovered a pattern that turned platform limitations into architectural clarity: the <strong>Hybrid Architecture Pattern</strong>.</p>
<span id="continue-reading"></span>
<hr />
<h2 id="act-i-the-setup">Act I: The Setup</h2>
<h3 id="the-vision">The Vision</h3>
<p>The idea was simple: analyze any codebase and automatically generate a team of specialized Claude Code agents tailored to that project. A React frontend? Generate a component-designer agent. A Python ML pipeline? Spawn a model-trainer agent. The plugin would understand your code and create AI collaborators that speak your project’s language.</p>
<p>I had read the documentation. Claude Code plugins support five component types—commands, agents, skills, hooks, and MCP integrations. Agents can spawn subagents using the Task tool. MCP servers provide external service access. It seemed straightforward.</p>
<p>Here’s what I expected versus what I found:</p>
<table><thead><tr><th>Expectation</th><th>Reality</th></tr></thead><tbody>
<tr><td>Plugin agents can access MCP tools</td><td>Plugin agents <strong>cannot</strong> access MCP (documented bug)</td></tr>
<tr><td>Agents can spawn nested subagents</td><td>Single-level nesting only</td></tr>
<tr><td>Documentation describes actual behavior</td><td>Docs claim MCP works, but it doesn’t</td></tr>
<tr><td>Changes propagate automatically</td><td>3-location manual sync required</td></tr>
<tr><td>Model inheritance works</td><td>Defaults to Sonnet 4 regardless of settings</td></tr>
</tbody></table>
<p>The gap between expectation and reality would become my curriculum.</p>
<h3 id="understanding-the-terrain">Understanding the Terrain</h3>
<p>Before diving into the pain points, let me share the landscape. Claude Code plugins have five component types, each with distinct triggering mechanisms:</p>
<table><thead><tr><th>Component</th><th>Trigger</th><th>Purpose</th></tr></thead><tbody>
<tr><td><strong>Skills</strong></td><td>Auto-invoked</td><td>Context providers based on description matching</td></tr>
<tr><td><strong>Commands</strong></td><td>User-initiated (<code>/command</code>)</td><td>Slash command shortcuts</td></tr>
<tr><td><strong>Agents</strong></td><td>Spawned via Task tool</td><td>Separate Claude instances for specialized work</td></tr>
<tr><td><strong>Hooks</strong></td><td>Event-driven</td><td>Automation handlers (PreToolUse, PostToolUse, etc.)</td></tr>
<tr><td><strong>MCPs</strong></td><td>Tool calls</td><td>External service integrations</td></tr>
</tbody></table>
<p>The directory structure follows a predictable pattern:</p>
<div class="tree-container" id="tree-202">
<canvas class="tree-canvas" aria-label="Directory structure visualization"></canvas>
</div>
<script>
(function() {
const containerId = 'tree-202';
// Decode HTML entities (Tera encodes / as /)
function decodeHTML(str) {
const textarea = document.createElement('textarea');
textarea.innerHTML = str;
return textarea.value;
}
const rootName = decodeHTML('plugin-root');
const nodeData = decodeHTML('.claude-plugin/:marketplace.json;plugin.json,commands/:*.md,agents/:*.md,skills/:SKILL.md,hooks/:*.md,.mcp.json:config');
function parseNodes(data) {
const folders = [];
data.split(',').forEach(folder => {
const [name, childrenStr] = folder.split(':');
const children = childrenStr ? childrenStr.split(';').map(c => c.trim()) : [];
folders.push({ name: name.trim(), children, type: 'folder' });
});
return folders;
}
function initTree() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.tree-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
const colors = {
root: '#ff0080',
folder: '#00d4ff',
file: '#8b5cf6',
config: '#ff8800',
accent: '#00ff88',
connection: 'rgba(0, 212, 255, 0.3)',
text: '#e0e0e4'
};
const folders = parseNodes(nodeData);
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 320;
}
resize();
window.addEventListener('resize', resize);
function getNodePositions() {
const nodes = [];
const centerX = canvas.width / 2;
const rootY = 50;
const folderY = 140;
const fileY = 230;
// Root node
nodes.push({
type: 'root',
label: rootName,
x: centerX,
y: rootY,
radius: 28,
color: colors.root
});
// Folder nodes
const folderSpacing = Math.min(120, (canvas.width - 100) / folders.length);
const startX = centerX - ((folders.length - 1) * folderSpacing) / 2;
folders.forEach((folder, i) => {
const x = startX + i * folderSpacing;
const isConfig = folder.name.includes('.') || folder.name.includes('json');
nodes.push({
type: 'folder',
label: folder.name,
x: x,
y: folderY,
radius: 22,
color: isConfig ? colors.config : colors.folder,
parentIndex: 0,
children: folder.children
});
});
// File nodes (spread under their parent folders)
let fileIndex = 0;
folders.forEach((folder, folderIdx) => {
const parentNode = nodes[folderIdx + 1];
const childCount = folder.children.length;
folder.children.forEach((child, childIdx) => {
const offset = (childIdx - (childCount - 1) / 2) * 50;
nodes.push({
type: 'file',
label: child,
x: parentNode.x + offset,
y: fileY + (childIdx % 2) * 35,
radius: 18,
color: colors.file,
parentIndex: folderIdx + 1
});
fileIndex++;
});
});
return nodes;
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const nodes = getNodePositions();
// Draw connections
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 2;
nodes.forEach((node, i) => {
if (node.parentIndex !== undefined) {
const parent = nodes[node.parentIndex];
ctx.beginPath();
ctx.moveTo(parent.x, parent.y + parent.radius);
ctx.lineTo(node.x, node.y - node.radius);
ctx.stroke();
}
});
// Draw nodes
nodes.forEach((node, i) => {
// Glow effect
ctx.shadowColor = node.color;
ctx.shadowBlur = 15;
// Node circle
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
// Border
ctx.strokeStyle = colors.accent;
ctx.lineWidth = 2;
ctx.stroke();
// Icon based on type
ctx.fillStyle = '#0a0a0f';
ctx.font = node.type === 'root' ? '16px sans-serif' : '12px sans-serif';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
if (node.type === 'root') {
ctx.fillText('📁', node.x, node.y);
} else if (node.type === 'folder') {
ctx.fillText('📂', node.x, node.y);
} else {
ctx.fillText('📄', node.x, node.y);
}
// Label
ctx.fillStyle = colors.text;
ctx.font = node.type === 'root' ? 'bold 12px JetBrains Mono' : '10px JetBrains Mono';
ctx.fillText(node.label, node.x, node.y + node.radius + 14);
});
// Animated particles
if (time % 60 === 0 && particles.length < 8) {
const randomFolder = Math.floor(Math.random() * folders.length) + 1;
const parentNode = nodes[randomFolder];
if (parentNode) {
particles.push({
x: nodes[0].x,
y: nodes[0].y,
targetX: parentNode.x,
targetY: parentNode.y,
progress: 0,
speed: 0.02
});
}
}
particles = particles.filter(p => p.progress < 1);
particles.forEach(p => {
p.progress += p.speed;
const ease = p.progress * p.progress * (3 - 2 * p.progress);
const x = p.x + (p.targetX - p.x) * ease;
const y = p.y + (p.targetY - p.y) * ease;
ctx.fillStyle = colors.accent;
ctx.shadowColor = colors.accent;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(x, y, 4, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
});
time++;
requestAnimationFrame(draw);
}
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const nodes = getNodePositions();
nodes.forEach(node => {
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = colors.text;
ctx.font = '10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.fillText(node.label, node.x, node.y + node.radius + 14);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initTree);
} else {
initTree();
}
})();
</script>
<style>
.tree-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.tree-canvas {
width: 100%;
height: 320px;
display: block;
}
@media (max-width: 768px) {
.tree-container {
overflow-x: auto;
}
.tree-canvas {
min-width: 500px;
}
}
</style>
<p>Armed with this knowledge, I built my first prototype. It worked—sort of. The commands executed. The agents spawned. And then everything started breaking in ways the documentation didn’t prepare me for.</p>
<hr />
<h2 id="act-ii-the-descent">Act II: The Descent</h2>
<h3 id="pain-point-1-the-mcp-tool-access-bug">Pain Point #1: The MCP Tool Access Bug</h3>
<p>My agent-team-creator plugin needed to integrate with Jira. The Atlassian MCP plugin was installed and working beautifully in the main Claude Code session. Following the documentation, I configured my plugin agent to access these MCP tools.</p>
<p>The error was immediate and confusing:</p>
<pre class="z-code"><code><span class="z-text z-plain">Error: No such tool available: mcp__plugin_atlassian__getJiraIssue
</span></code></pre>
<p>I spent hours debugging. Was my configuration wrong? Did I misname the tool? Then I found them—four GitHub issues documenting the same problem:</p>
<table><thead><tr><th>Issue</th><th>Description</th></tr></thead><tbody>
<tr><td>#13605</td><td>Custom plugin subagents cannot access MCP tools</td></tr>
<tr><td>#15810</td><td>Subagents don’t inherit MCP tools from plugin-defined agents</td></tr>
<tr><td>#14496</td><td>Inconsistent MCP access with complex prompts</td></tr>
<tr><td>#7296</td><td>Scope inheritance failure for Task-launched agents</td></tr>
</tbody></table>
<p>The documentation said:</p>
<blockquote>
<p>“When the tools field is omitted, subagents inherit all MCP tools available to the main thread.”</p>
</blockquote>
<p>Reality disagreed. Plugin-defined agents live in a different scope—they can see the MCP tools listed in the main session, but they cannot invoke them.</p>
<hr />
<p><strong>★ Teaching Moment: The MCP Scope Reality</strong></p>
<p>MCP tools work reliably in two contexts:</p>
<ol>
<li>The main Claude Code session</li>
<li>Commands (which run in the main session’s scope)</li>
</ol>
<p>MCP tools <strong>do not work</strong> in:</p>
<ul>
<li>Plugin-defined agents spawned via Task tool</li>
<li>Subagents of any kind</li>
</ul>
<p>If your plugin needs external service access, your <strong>commands</strong> must handle it, not your agents.</p>
<hr />
<h3 id="pain-point-2-three-location-sync-hell">Pain Point #2: Three-Location Sync Hell</h3>
<p>After modifying my agent definitions, I reloaded Claude Code. My changes weren’t there. I edited again. Still nothing.</p>
<p>It turns out Claude Code plugins exist in three separate locations that must be manually synchronized:</p>
<table><thead><tr><th>Location</th><th>Path</th><th>Purpose</th></tr></thead><tbody>
<tr><td>Marketplace Source</td><td><code>~/.claude/local-marketplace/</code></td><td>Where you edit</td></tr>
<tr><td>Installed Plugin</td><td><code>~/.claude/plugins/plugin-name/</code></td><td>Where Claude reads</td></tr>
<tr><td>Cache</td><td><code>~/.claude/plugins/cache/marketplace/plugin/version/</code></td><td>Versioned backup</td></tr>
</tbody></table>
<p>There’s no hot reload. There’s no auto-sync. You edit in one place, but Claude reads from another.</p>
<p>The solution? A sync script:</p>
<pre data-lang="bash" class="language-bash z-code"><code class="language-bash" data-lang="bash"><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell">!/bin/bash</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-variable z-other z-readwrite z-assignment z-shell">PLUGIN_NAME</span><span class="z-keyword z-operator z-assignment z-shell">=</span><span class="z-string z-unquoted z-shell"><span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span>agent-team-creator<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-variable z-other z-readwrite z-assignment z-shell">MARKETPLACE</span><span class="z-keyword z-operator z-assignment z-shell">=</span><span class="z-string z-unquoted z-shell"><span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">HOME</span></span>/.claude/local-marketplace<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-variable z-other z-readwrite z-assignment z-shell">INSTALLED</span><span class="z-keyword z-operator z-assignment z-shell">=</span><span class="z-string z-unquoted z-shell"><span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">HOME</span></span>/.claude/plugins/<span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">PLUGIN_NAME</span></span><span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-variable z-other z-readwrite z-assignment z-shell">CACHE</span><span class="z-keyword z-operator z-assignment z-shell">=</span><span class="z-string z-unquoted z-shell"><span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">HOME</span></span>/.claude/plugins/cache/local-marketplace/<span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">PLUGIN_NAME</span></span>/1.0.0<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">rsync</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>av</span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">MARKETPLACE</span></span>/commands/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">INSTALLED</span></span>/commands/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">rsync</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>av</span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">MARKETPLACE</span></span>/commands/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">CACHE</span></span>/commands/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">rsync</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>av</span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">MARKETPLACE</span></span>/agents/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">INSTALLED</span></span>/agents/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">rsync</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>av</span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">MARKETPLACE</span></span>/agents/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span><span class="z-meta z-group z-expansion z-parameter z-shell"><span class="z-punctuation z-definition z-variable z-shell">$</span><span class="z-variable z-other z-readwrite z-shell">CACHE</span></span>/agents/<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-support z-function z-echo z-shell">echo</span></span><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-string z-quoted z-double z-shell"><span class="z-punctuation z-definition z-string z-begin z-shell">"</span>Plugin synced to all locations<span class="z-punctuation z-definition z-string z-end z-shell">"</span></span></span>
</span></code></pre>
<p>After every change: sync, quit Claude Code, restart. This became muscle memory.</p>
<hr />
<p><strong>★ Teaching Moment: Debugging Your Plugin</strong></p>
<p>When things go wrong, these commands are your friends:</p>
<pre data-lang="bash" class="language-bash z-code"><code class="language-bash" data-lang="bash"><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Check if plugin is loaded</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">ls</span></span><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/plugins/</span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Verify cache sync</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">diff</span></span><span class="z-meta z-function-call z-arguments z-shell"><span class="z-variable z-parameter z-option z-shell"><span class="z-punctuation z-definition z-parameter z-shell"> -</span>r</span> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/plugins/agent-team-creator/ <span class="z-punctuation z-separator z-continuation z-line z-shell">\
</span></span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/plugins/cache/local-marketplace/agent-team-creator/1.0.0/</span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> Validate marketplace.json syntax</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">cat</span></span><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/local-marketplace/.claude-plugin/marketplace.json</span> <span class="z-keyword z-operator z-logical z-pipe z-shell">|</span> <span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">jq</span></span><span class="z-meta z-function-call z-arguments z-shell"> .</span>
</span><span class="z-source z-shell z-bash">
</span><span class="z-source z-shell z-bash"><span class="z-comment z-line z-number-sign z-shell"><span class="z-punctuation z-definition z-comment z-begin z-shell">#</span></span><span class="z-comment z-line z-number-sign z-shell"> View plugin structure</span><span class="z-comment z-line z-number-sign z-shell">
</span></span><span class="z-source z-shell z-bash"><span class="z-meta z-function-call z-shell"><span class="z-variable z-function z-shell">tree</span></span><span class="z-meta z-function-call z-arguments z-shell"> <span class="z-meta z-group z-expansion z-tilde"><span class="z-variable z-language z-tilde z-shell">~</span></span>/.claude/plugins/agent-team-creator/</span>
</span></code></pre>
<hr />
<h3 id="pain-point-3-schema-validation-gotchas">Pain Point #3: Schema Validation Gotchas</h3>
<p>My first marketplace.json was rejected with cryptic errors:</p>
<pre class="z-code"><code><span class="z-text z-plain">owner: Expected object, received string
</span><span class="z-text z-plain">source: Invalid input
</span></code></pre>
<p>The schema is strict and underdocumented. Here’s what works:</p>
<pre data-lang="json" class="language-json z-code"><code class="language-json" data-lang="json"><span class="z-source z-json"><span class="z-meta z-mapping z-json"><span class="z-punctuation z-section z-mapping z-begin z-json">{</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>$schema<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>https://anthropic.com/claude-code/marketplace.schema.json<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>local-marketplace<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>description<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>Local plugins for Claude Code<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>owner<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-json"><span class="z-punctuation z-section z-mapping z-begin z-json">{</span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>Your Name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>email<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>your@email.com<span class="z-punctuation z-definition z-string z-end z-json">"</span></span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-value z-json"> <span class="z-punctuation z-section z-mapping z-end z-json">}</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>plugins<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-punctuation z-section z-sequence z-begin z-json">[</span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"> <span class="z-meta z-mapping z-json"><span class="z-punctuation z-section z-mapping z-begin z-json">{</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>plugin-name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>description<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>Plugin description<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>version<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>1.0.0<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>author<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-json"><span class="z-punctuation z-section z-mapping z-begin z-json">{</span>
</span></span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>Author Name<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>email<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>author@email.com<span class="z-punctuation z-definition z-string z-end z-json">"</span></span>
</span></span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-mapping z-value z-json"> <span class="z-punctuation z-section z-mapping z-end z-json">}</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>source<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>./<span class="z-punctuation z-definition z-string z-end z-json">"</span></span><span class="z-punctuation z-separator z-mapping z-pair z-json">,</span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> </span><span class="z-meta z-mapping z-key z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>category<span class="z-punctuation z-definition z-string z-end z-json">"</span></span></span><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-separator z-mapping z-key-value z-json">:</span> </span><span class="z-meta z-mapping z-value z-json"><span class="z-string z-quoted z-double z-json"><span class="z-punctuation z-definition z-string z-begin z-json">"</span>development<span class="z-punctuation z-definition z-string z-end z-json">"</span></span>
</span></span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"><span class="z-meta z-mapping z-value z-json"> <span class="z-punctuation z-section z-mapping z-end z-json">}</span></span>
</span></span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-meta z-sequence z-json"> <span class="z-punctuation z-section z-sequence z-end z-json">]</span></span>
</span></span><span class="z-source z-json"><span class="z-meta z-mapping z-value z-json"><span class="z-punctuation z-section z-mapping z-end z-json">}</span></span>
</span></code></pre>
<p>Key gotchas:</p>
<ul>
<li><code>owner</code> must be an object with <code>name</code> and <code>email</code>, not a string</li>
<li><code>source</code> must be <code>"./"</code> with the trailing slash</li>
<li>Missing any required field causes silent failures</li>
</ul>
<hr />
<h2 id="act-iii-the-discovery">Act III: The Discovery</h2>
<h3 id="the-documentation-vs-reality-gap">The Documentation vs. Reality Gap</h3>
<p>The breaking point came when I built an entire multi-agent architecture based on documented behavior—only to have it fail completely.</p>
<p>The docs promised:</p>
<blockquote>
<p>“MCP Tools: Subagents can access MCP tools from configured MCP servers.”</p>
</blockquote>
<p>I tested extensively. Plugin-defined subagents <strong>cannot</strong> access MCP tools. This isn’t a configuration issue—it’s a known bug tracked across multiple GitHub issues.</p>
<p><strong>The lesson</strong>: Documentation represents <em>intended</em> behavior, not <em>guaranteed</em> behavior. Always validate assumptions empirically before building dependent architectures.</p>
<h3 id="the-nesting-wall">The Nesting Wall</h3>
<p>My original design had agents spawning specialized sub-agents in a recursive tree structure. Elegant in theory. Impossible in practice.</p>
<p>When I tried:</p>
<div class="blocked-flow-container" id="blocked-">
<canvas class="blocked-flow-canvas" aria-label="Flow diagram with blocked step"></canvas>
</div>
<script>
(function() {
const containerId = 'blocked-';
const nodeNames = ['User', 'Command', 'Agent', 'SubAgent'];
const blockedName = 'SubSubAgent';
function initBlockedFlow() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.blocked-flow-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
let pulsePhase = 0;
const colors = {
nodes: ['#ff0080', '#00d4ff', '#00ff88', '#8b5cf6'],
blocked: '#ff4444',
blockedBg: '#442222',
particle: '#00ff88',
connection: 'rgba(0, 212, 255, 0.4)',
blockedConnection: 'rgba(255, 68, 68, 0.5)',
text: '#e0e0e4'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 180;
}
resize();
window.addEventListener('resize', resize);
function getNodePositions() {
const allNodes = [...nodeNames, blockedName];
const margin = 60;
const spacing = (canvas.width - margin * 2) / (allNodes.length - 1);
const y = canvas.height / 2;
return allNodes.map((name, i) => ({
label: name,
x: margin + i * spacing,
y: y,
radius: 26,
isBlocked: i === allNodes.length - 1,
color: i < nodeNames.length ? colors.nodes[i % colors.nodes.length] : colors.blockedBg
}));
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const nodes = getNodePositions();
pulsePhase += 0.05;
// Draw connections
for (let i = 0; i < nodes.length - 1; i++) {
const from = nodes[i];
const to = nodes[i + 1];
const isBlockedConnection = to.isBlocked;
ctx.beginPath();
ctx.moveTo(from.x + from.radius, from.y);
ctx.lineTo(to.x - to.radius, to.y);
if (isBlockedConnection) {
ctx.strokeStyle = colors.blockedConnection;
ctx.setLineDash([8, 4]);
} else {
ctx.strokeStyle = colors.connection;
ctx.setLineDash([]);
}
ctx.lineWidth = 3;
ctx.stroke();
ctx.setLineDash([]);
// Arrow
if (!isBlockedConnection) {
const midX = (from.x + to.x) / 2;
ctx.fillStyle = colors.connection;
ctx.beginPath();
ctx.moveTo(midX - 5, from.y - 6);
ctx.lineTo(midX + 8, from.y);
ctx.lineTo(midX - 5, from.y + 6);
ctx.closePath();
ctx.fill();
}
}
// Draw "BLOCKED" label on the blocked connection
const lastNormal = nodes[nodes.length - 2];
const blocked = nodes[nodes.length - 1];
const midX = (lastNormal.x + blocked.x) / 2;
ctx.save();
ctx.fillStyle = colors.blocked;
ctx.font = 'bold 11px JetBrains Mono';
ctx.textAlign = 'center';
// Pulsing X
const pulse = Math.sin(pulsePhase) * 0.3 + 1;
ctx.font = `bold ${14 * pulse}px JetBrains Mono`;
ctx.fillText('❌', midX, nodes[0].y - 20);
ctx.font = 'bold 10px JetBrains Mono';
ctx.fillText('BLOCKED', midX, nodes[0].y + 32);
ctx.restore();
// Draw nodes
nodes.forEach((node, i) => {
if (node.isBlocked) {
// Blocked node - pulsing red border
ctx.shadowColor = colors.blocked;
ctx.shadowBlur = 10 + Math.sin(pulsePhase) * 5;
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.strokeStyle = colors.blocked;
ctx.lineWidth = 3;
ctx.setLineDash([4, 4]);
ctx.stroke();
ctx.setLineDash([]);
ctx.shadowBlur = 0;
// Strikethrough effect
ctx.strokeStyle = colors.blocked;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.moveTo(node.x - node.radius + 5, node.y - node.radius + 5);
ctx.lineTo(node.x + node.radius - 5, node.y + node.radius - 5);
ctx.stroke();
} else {
// Normal node
ctx.shadowColor = node.color;
ctx.shadowBlur = 15;
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
ctx.strokeStyle = '#00ff88';
ctx.lineWidth = 2;
ctx.stroke();
}
// Label
ctx.fillStyle = node.isBlocked ? '#666' : '#0a0a0f';
ctx.font = 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
// Wrap text if needed
const words = node.label.split(/(?=[A-Z])/);
if (words.length > 1 && node.label.length > 8) {
ctx.fillText(words[0], node.x, node.y - 6);
ctx.fillText(words.slice(1).join(''), node.x, node.y + 6);
} else {
ctx.fillText(node.label, node.x, node.y);
}
});
// Particles (only on valid connections)
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.segmentIndex++;
p.progress = 0;
if (p.segmentIndex >= nodes.length - 2) {
p.segmentIndex = 0;
}
}
const from = nodes[p.segmentIndex];
const to = nodes[p.segmentIndex + 1];
if (from && to && !to.isBlocked) {
const ease = p.progress * p.progress * (3 - 2 * p.progress);
const x = from.x + (to.x - from.x) * ease;
const y = from.y + (to.y - from.y) * ease;
ctx.fillStyle = colors.particle;
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(x, y, 4, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
}
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
for (let i = 0; i < 2; i++) {
particles.push({
segmentIndex: i,
progress: 0,
speed: 0.015
});
}
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const nodes = getNodePositions();
nodes.forEach(node => {
ctx.fillStyle = node.color;
ctx.beginPath();
ctx.arc(node.x, node.y, node.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = node.isBlocked ? '#666' : '#0a0a0f';
ctx.font = 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.fillText(node.label, node.x, node.y);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initBlockedFlow);
} else {
initBlockedFlow();
}
})();
</script>
<style>
.blocked-flow-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.blocked-flow-canvas {
width: 100%;
height: 180px;
display: block;
}
@media (max-width: 768px) {
.blocked-flow-container {
overflow-x: auto;
}
.blocked-flow-canvas {
min-width: 500px;
}
}
</style>
<p>Claude Code responded:</p>
<pre class="z-code"><code><span class="z-text z-plain">Error: Subagents cannot spawn subagents
</span></code></pre>
<p>This is a hard platform limit. Single-level nesting only. The constraint exists for good reasons—preventing infinite recursion, maintaining bounded resource consumption, ensuring predictable execution. But it invalidated my entire architecture.</p>
<h3 id="model-inheritance-that-doesn-t-inherit">Model Inheritance That Doesn’t Inherit</h3>
<p>I configured my agents to use <code>model: inherit</code>, expecting them to use whatever model the parent session used. Every single subagent defaulted to Sonnet 4, regardless of:</p>
<ul>
<li>Parent model</li>
<li>Global settings</li>
<li>Local settings</li>
<li>Explicit agent configuration</li>
</ul>
<p>Another discovery: Claude Code infers agent behavior from naming. An agent named “code-reviewer” triggers built-in review behaviors that may override your custom instructions. Naming isn’t just labeling—it’s functional.</p>
<hr />
<h2 id="act-iv-the-solution">Act IV: The Solution</h2>
<h3 id="the-hybrid-architecture-pattern">The Hybrid Architecture Pattern</h3>
<p>Constraints breed creativity. Facing MCP access bugs, nesting limits, and model inheritance failures, I developed what I now call the <strong>Hybrid Architecture Pattern</strong>.</p>
<p>The core insight: <strong>Commands and Agents have different capabilities. Use each for what it does well.</strong></p>
<p><strong>Command Layer (I/O)</strong>:</p>
<ul>
<li>MCP tool access (works reliably)</li>
<li>File system operations</li>
<li>User interaction (AskUserQuestion)</li>
<li>Response caching</li>
<li>External service communication</li>
</ul>
<p><strong>Agent Layer (Intelligence)</strong>:</p>
<ul>
<li>Pure reasoning and analysis</li>
<li>Content formatting</li>
<li>Decision making</li>
<li>Pattern recognition</li>
<li><strong>No direct I/O dependencies</strong></li>
</ul>
<p>Commands become the I/O adapters. Agents become the reasoning engines. Neither tries to do the other’s job.</p>
<h3 id="the-6-phase-pipeline">The 6-Phase Pipeline</h3>
<p>Here’s how this plays out in my <code>/generate-jira-task</code> command:</p>
<div class="pipeline-container" id="pipeline">
<canvas class="pipeline-canvas" aria-label="Pipeline flow visualization"></canvas>
<div class="pipeline-legend">
<span class="legend-item"><span class="legend-dot command"></span> Command (I/O)</span>
<span class="legend-item"><span class="legend-dot agent"></span> Agent (Intelligence)</span>
</div>
</div>
<script>
(function() {
const containerId = 'pipeline';
const phasesData = [
{"phase": 0, "owner": "Command", "label": "MCP Check", "io": "external"},
{"phase": 1, "owner": "Command", "label": "Project Resolve", "io": "external"},
{"phase": 2, "owner": "Command", "label": "Load Report", "io": "local"},
{"phase": 3, "owner": "Command", "label": "Dup Check", "io": "external"},
{"phase": 4, "owner": "Agent", "label": "Reasoning", "io": "none"},
{"phase": 5, "owner": "Agent", "label": "Formatting", "io": "none"},
{"phase": 6, "owner": "Command", "label": "Output", "io": "external"}
];
function initPipeline() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.pipeline-canvas');
const ctx = canvas.getContext('2d');
// Responsive sizing
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 180;
}
resize();
window.addEventListener('resize', resize);
// Colors
const colors = {
command: '#00d4ff',
agent: '#00ff88',
external: '#8b5cf6',
local: '#ff8800',
none: '#444466',
particle: '#00ff88',
bg: 'rgba(10, 10, 15, 0.8)'
};
// Animation state
let particles = [];
let time = 0;
// Get phase positions
function getPhasePositions() {
const phases = phasesData;
const margin = 60;
const spacing = (canvas.width - margin * 2) / (phases.length - 1);
return phases.map((p, i) => ({
...p,
x: margin + i * spacing,
y: canvas.height / 2,
radius: 24
}));
}
// Create particle
function createParticle(positions) {
return {
phaseIndex: 0,
progress: 0,
speed: 0.01 + Math.random() * 0.01,
x: positions[0].x,
y: positions[0].y
};
}
// Draw
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const positions = getPhasePositions();
// Draw connections
ctx.lineWidth = 2;
ctx.strokeStyle = 'rgba(0, 212, 255, 0.3)';
ctx.beginPath();
positions.forEach((pos, i) => {
if (i === 0) ctx.moveTo(pos.x, pos.y);
else ctx.lineTo(pos.x, pos.y);
});
ctx.stroke();
// Draw arrows
for (let i = 0; i < positions.length - 1; i++) {
const from = positions[i];
const to = positions[i + 1];
const midX = (from.x + to.x) / 2;
const midY = (from.y + to.y) / 2;
ctx.fillStyle = 'rgba(0, 212, 255, 0.5)';
ctx.beginPath();
ctx.moveTo(midX - 6, midY - 4);
ctx.lineTo(midX + 6, midY);
ctx.lineTo(midX - 6, midY + 4);
ctx.closePath();
ctx.fill();
}
// Draw phase nodes
positions.forEach((pos, i) => {
const isCommand = pos.owner === 'Command';
const color = isCommand ? colors.command : colors.agent;
// Glow
const gradient = ctx.createRadialGradient(pos.x, pos.y, 0, pos.x, pos.y, pos.radius * 2);
gradient.addColorStop(0, color.replace(')', ', 0.3)').replace('rgb', 'rgba'));
gradient.addColorStop(1, 'transparent');
ctx.fillStyle = gradient;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius * 2, 0, Math.PI * 2);
ctx.fill();
// Node
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius, 0, Math.PI * 2);
ctx.fill();
// Phase number
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 14px JetBrains Mono, monospace';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(pos.phase, pos.x, pos.y);
// Label
ctx.fillStyle = '#e0e0e4';
ctx.font = '11px JetBrains Mono, monospace';
ctx.fillText(pos.label, pos.x, pos.y + pos.radius + 16);
// I/O indicator
if (pos.io !== 'none') {
ctx.fillStyle = pos.io === 'external' ? colors.external : colors.local;
ctx.font = '9px JetBrains Mono, monospace';
ctx.fillText(pos.io.toUpperCase(), pos.x, pos.y - pos.radius - 10);
}
});
// Update and draw particles
particles.forEach(p => {
if (p.phaseIndex >= positions.length - 1) {
p.phaseIndex = 0;
p.progress = 0;
}
const from = positions[p.phaseIndex];
const to = positions[p.phaseIndex + 1];
p.progress += p.speed;
if (p.progress >= 1) {
p.phaseIndex++;
p.progress = 0;
}
if (to) {
p.x = from.x + (to.x - from.x) * p.progress;
p.y = from.y + (to.y - from.y) * p.progress;
}
// Draw particle
ctx.fillStyle = colors.particle;
ctx.beginPath();
ctx.arc(p.x, p.y, 4, 0, Math.PI * 2);
ctx.fill();
// Particle glow
const pGrad = ctx.createRadialGradient(p.x, p.y, 0, p.x, p.y, 12);
pGrad.addColorStop(0, 'rgba(0, 255, 136, 0.4)');
pGrad.addColorStop(1, 'transparent');
ctx.fillStyle = pGrad;
ctx.beginPath();
ctx.arc(p.x, p.y, 12, 0, Math.PI * 2);
ctx.fill();
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
const positions = getPhasePositions();
for (let i = 0; i < 3; i++) {
const p = createParticle(positions);
p.phaseIndex = i * 2;
particles.push(p);
}
// Respect reduced motion
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const positions = getPhasePositions();
ctx.clearRect(0, 0, canvas.width, canvas.height);
ctx.lineWidth = 2;
ctx.strokeStyle = 'rgba(0, 212, 255, 0.5)';
ctx.beginPath();
positions.forEach((pos, i) => {
if (i === 0) ctx.moveTo(pos.x, pos.y);
else ctx.lineTo(pos.x, pos.y);
});
ctx.stroke();
positions.forEach((pos) => {
const color = pos.owner === 'Command' ? colors.command : colors.agent;
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(pos.x, pos.y, pos.radius, 0, Math.PI * 2);
ctx.fill();
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 14px JetBrains Mono, monospace';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(pos.phase, pos.x, pos.y);
ctx.fillStyle = '#e0e0e4';
ctx.font = '11px JetBrains Mono, monospace';
ctx.fillText(pos.label, pos.x, pos.y + pos.radius + 16);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initPipeline);
} else {
initPipeline();
}
})();
</script>
<style>
.pipeline-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1.5rem 1rem 1rem;
margin: 1.5rem 0;
position: relative;
}
.pipeline-canvas {
width: 100%;
height: 180px;
display: block;
}
.pipeline-legend {
display: flex;
justify-content: center;
gap: 2rem;
margin-top: 0.5rem;
font-family: 'JetBrains Mono', monospace;
font-size: 0.8rem;
color: var(--meta-color);
}
.legend-item {
display: flex;
align-items: center;
gap: 0.5rem;
}
.legend-dot {
width: 12px;
height: 12px;
border-radius: 50%;
}
.legend-dot.command {
background: #00d4ff;
}
.legend-dot.agent {
background: #00ff88;
}
@media (max-width: 768px) {
.pipeline-container {
overflow-x: auto;
}
.pipeline-canvas {
min-width: 600px;
}
}
</style>
<p>Commands handle all external communication (cyan nodes). Agents handle all thinking (green nodes). The boundary is clean—notice how I/O operations (marked EXTERNAL/LOCAL) cluster at the Command layer.</p>
<h3 id="graceful-degradation">Graceful Degradation</h3>
<p>What if MCP isn’t available? The pattern handles this elegantly:</p>
<pre class="z-code"><code><span class="z-text z-plain">FALLBACK_MODE activates when:
</span><span class="z-text z-plain"> - Atlassian MCP plugin unavailable
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Actions:
</span><span class="z-text z-plain"> - Skip Phase 1 (project resolution)
</span><span class="z-text z-plain"> - Skip Phase 3 (duplicate check)
</span><span class="z-text z-plain"> - Phase 6: Output markdown to .claude/reports/jira-drafts/
</span></code></pre>
<p>The intelligence layer (Phases 4-5) works identically whether connected to Jira or not. The I/O layer gracefully degrades to local file output.</p>
<hr />
<p><strong>★ Teaching Moment: Command and Agent Frontmatter</strong></p>
<p><strong>Command Template</strong>:</p>
<pre data-lang="yaml" class="language-yaml z-code"><code class="language-yaml" data-lang="yaml"><span class="z-source z-yaml"><span class="z-entity z-other z-document z-begin z-yaml">---</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">name</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">generate-jira-task</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">description</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Generate Jira task from debugging report</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">allowed-tools</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Read</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Write</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Glob</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Grep</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Task</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">AskUserQuestion</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">argument-hint</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-quoted z-double z-yaml"><span class="z-punctuation z-definition z-string z-begin z-yaml">"</span>[report-file]<span class="z-punctuation z-definition z-string z-end z-yaml">"</span></span>
</span><span class="z-source z-yaml"><span class="z-entity z-other z-document z-begin z-yaml">---</span>
</span></code></pre>
<p><strong>Agent Template</strong>:</p>
<pre data-lang="yaml" class="language-yaml z-code"><code class="language-yaml" data-lang="yaml"><span class="z-source z-yaml"><span class="z-entity z-other z-document z-begin z-yaml">---</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">name</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">implementation-planner</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">description</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-keyword z-control z-flow z-block-scalar z-literal z-yaml">|</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-block z-yaml"> Use this agent to analyze debugging reports and create implementation plans.
</span></span><span class="z-source z-yaml"><span class="z-string z-unquoted z-block z-yaml"></span><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">model</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">inherit</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">color</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span> <span class="z-string z-unquoted z-plain z-out z-yaml">cyan</span>
</span><span class="z-source z-yaml"><span class="z-string z-unquoted z-plain z-out z-yaml"><span class="z-entity z-name z-tag z-yaml">tools</span></span><span class="z-punctuation z-separator z-key-value z-mapping z-yaml">:</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Read</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Grep</span>
</span><span class="z-source z-yaml"> <span class="z-punctuation z-definition z-block z-sequence z-item z-yaml">-</span> <span class="z-string z-unquoted z-plain z-out z-yaml">Glob</span>
</span><span class="z-source z-yaml"><span class="z-entity z-other z-document z-begin z-yaml">---</span>
</span></code></pre>
<p>Note: Agents should <strong>not</strong> include MCP tools in their tools list—they won’t work anyway.</p>
<hr />
<h2 id="act-v-the-return">Act V: The Return</h2>
<h3 id="what-works-now">What Works Now</h3>
<p>The agent-team-creator plugin now functions reliably with three commands:</p>
<ul>
<li><code>/generate-agent-team</code> - Analyzes codebases and generates specialized agents</li>
<li><code>/generate-debugger</code> - Creates project-specific debugging agents</li>
<li><code>/generate-jira-task</code> - Converts debugging reports to Jira tasks</li>
</ul>
<p>Each follows the Hybrid Architecture Pattern. Commands handle I/O. Agents handle reasoning. The system degrades gracefully when services are unavailable.</p>
<h3 id="lessons-learned">Lessons Learned</h3>
<table><thead><tr><th>Lesson</th><th>Implication</th></tr></thead><tbody>
<tr><td>Trust but verify documentation</td><td>Build minimal proofs-of-concept before committing to architectures</td></tr>
<tr><td>Constraints reveal clarity</td><td>The hybrid pattern is cleaner than my original unconstrained design</td></tr>
<tr><td>Sync is your responsibility</td><td>Automate it. Make it muscle memory.</td></tr>
<tr><td>Naming is functional</td><td>Agent names influence platform behavior</td></tr>
<tr><td>Explicit over implicit</td><td>Never assume tool inheritance; declare everything</td></tr>
</tbody></table>
<h3 id="quick-start-checklist-for-new-plugin-developers">Quick-Start Checklist for New Plugin Developers</h3>
<ol>
<li><strong>Setup</strong>: Create marketplace structure with proper JSON schema</li>
<li><strong>Develop</strong>: Edit files in marketplace source only</li>
<li><strong>Sync</strong>: Run rsync script after every change</li>
<li><strong>Restart</strong>: Quit and restart Claude Code (no hot reload)</li>
<li><strong>Test</strong>: Verify command availability with <code>/help</code></li>
<li><strong>Debug</strong>: Use <code>diff -r</code> and <code>jq</code> for validation</li>
</ol>
<p>The key lesson: <strong>Commands for I/O, Agents for reasoning</strong>. This pattern works around every bug I encountered.</p>
<hr />
<h2 id="conclusion">Conclusion</h2>
<p>Building agent-team-creator taught me more about AI agent architecture than any documentation could. The bugs weren’t obstacles—they were teachers. The constraints weren’t limitations—they were design principles in disguise.</p>
<p>The Hybrid Architecture Pattern emerged from necessity, but I now believe it’s superior to unconstrained designs. Clear boundaries between I/O and intelligence layers make systems easier to test, debug, and extend. Graceful degradation becomes natural when you’ve already separated concerns.</p>
<p>In Part 2 of this series, I’ll step back from the practical details and examine what these discoveries reveal about agent framework design more broadly. Why do inheritance models break down in multi-agent systems? What makes the hub-and-spoke topology emerge naturally? And what does naming-as-behavior tell us about AI systems in general?</p>
<p>For now, if you’re building Claude Code plugins: embrace the constraints. They’ll teach you things the documentation can’t.</p>
<hr />
<h2 id="get-the-plugin">Get the Plugin</h2>
<p>The plugin is open source: <a href="https://github.com/Cpicon/claude-code-plugins">Cpicon/claude-code-plugins</a></p>
<p>Use the <a href="https://github.com/Cpicon/claude-code-plugins/issues">GitHub Issues</a> tab to request features, report bugs, or discuss improvements.</p>
<hr />
<p><strong>Series Navigation:</strong></p>
<ul>
<li><strong>Part 0</strong>: <a href="/posts/claude-code-plugin-journey-part0/">Agent Team Creator</a> — What the plugin does and how to use it</li>
<li><strong>Part 1</strong> (You are here): Building the plugin, lessons learned</li>
<li><strong>Part 2</strong>: <a href="/posts/claude-code-plugin-journey-part2/">The Inheritance Paradox</a> — Research insights, patterns</li>
</ul>
<hr />
<p><em>This post is based on empirical observations from building the agent-team-creator plugin. All pain points and solutions were documented through real development sessions.</em></p>
The Hybrid Architecture Pattern: Lessons from agent-team-creator
This is Part 1 of a three-part series. Start with Part 0: Agent Team Creator to see what the plugin does, or continue here for the development journey.
I thought building a Claude Code plugin would take a weekend. Three days into wrestling with MCP tool access bugs, three-location file synchronization, and documentation that promised features that didn’t work, I realized I was building something more valuable than a plugin—I was mapping uncharted territory.
This is the story of building agent-team-creator, a Claude Code plugin that analyzes codebases and generates project-specific AI agents. Along the way, I discovered a pattern that turned platform limitations into architectural clarity: the Hybrid Architecture Pattern.
…