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
Future With ML
Future With ML
Machine Learning Design Patterns, MLOps, and AI Engineering insights by Christian Picon Calderon
Zola2026-01-06T12:00:00+00:00https://futurewithml.netlify.app/atom.xml
The Inheritance Paradox: Tool Scoping in Multi-Agent Systems
2026-01-06T12:00:00+00:00
2026-01-06T12:00:00+00:00
Christian Picon Calderon
https://futurewithml.netlify.app/posts/claude-code-plugin-journey-part2/
<h1 id="the-inheritance-paradox-tool-scoping-in-multi-agent-systems">The Inheritance Paradox: Tool Scoping in Multi-Agent Systems</h1>
<blockquote>
<p><em>This is Part 2 of a three-part series. See <a href="/posts/claude-code-plugin-journey-part0/">Part 0</a> for the plugin overview and installation, or <a href="/posts/claude-code-plugin-journey-part1/">Part 1</a> for the development journey.</em></p>
</blockquote>
<p><strong>Abstract</strong>: This article presents empirical observations from developing a Claude Code plugin, revealing fundamental patterns in multi-agent AI system design. Through documented development sessions, we identify three key findings: (1) implicit tool inheritance models consistently fail in practice, requiring explicit scope contracts; (2) platform-enforced topology constraints drive the emergence of specific architectural patterns; and (3) agent naming conventions become functional requirements in AI systems. These findings have implications for the design of agent frameworks beyond the specific platform studied.</p>
<span id="continue-reading"></span>
<hr />
<h2 id="1-introduction">1. Introduction</h2>
<p>Agent-based development platforms represent an emerging paradigm in software engineering, where AI instances collaborate on complex tasks through structured orchestration. These platforms offer extension mechanisms—plugins, commands, agents—that allow developers to customize behavior for specific domains.</p>
<p>This article examines Claude Code as a case study in agent framework design. Claude Code enables developers to build custom plugins with commands (user-invoked shortcuts), agents (specialized Claude instances), skills (context providers), hooks (event handlers), and MCP integrations (external service connections).</p>
<p>During the development of <code>agent-team-creator</code>, a plugin for generating project-specific AI agents, we documented systematic observations about platform behavior. These observations reveal patterns relevant to multi-agent system design more broadly.</p>
<h3 id="research-questions">Research Questions</h3>
<ol>
<li>How do tool inheritance models behave in practice versus documentation?</li>
<li>What architectural patterns emerge from platform topology constraints?</li>
<li>How do naming conventions influence agent behavior in AI systems?</li>
</ol>
<hr />
<h2 id="2-platform-architecture-analysis">2. Platform Architecture Analysis</h2>
<h3 id="2-1-component-type-taxonomy">2.1 Component Type Taxonomy</h3>
<p>Claude Code plugins support five distinct extension types, each with different triggering mechanisms and scope:</p>
<table><thead><tr><th>Component</th><th>Trigger</th><th>Invocation</th><th>Scope</th></tr></thead><tbody>
<tr><td>Skills</td><td>Auto (Claude decides)</td><td>Implicit</td><td>Cross-product</td></tr>
<tr><td>Commands</td><td>User (<code>/syntax</code>)</td><td>Explicit</td><td>Claude Code</td></tr>
<tr><td>Agents</td><td>Spawn (Task tool)</td><td>Explicit/Implicit</td><td>Claude Code</td></tr>
<tr><td>Hooks</td><td>Events</td><td>Automatic</td><td>Claude Code</td></tr>
<tr><td>MCPs</td><td>Tool calls</td><td>Explicit</td><td>Claude Code</td></tr>
</tbody></table>
<p><strong>Key Observation</strong>: Skills are unique in being cross-product (functional in web UI, API, and CLI), while all other components are Claude Code-specific. This suggests different inheritance models may apply to different component types.</p>
<h3 id="2-2-tool-inventory">2.2 Tool Inventory</h3>
<p>The platform provides 15 built-in tools available to agents:</p>
<ol>
<li>Read, Write, Edit, MultiEdit (file operations)</li>
<li>Glob, Grep, LS (search operations)</li>
<li>Bash (system commands)</li>
<li>WebFetch, WebSearch (web access)</li>
<li>NotebookRead, NotebookEdit (Jupyter support)</li>
<li>TodoRead, TodoWrite (task tracking)</li>
<li>exit_plan_mode (workflow control)</li>
</ol>
<p>Additionally, MCP (Model Context Protocol) servers provide external service integrations—database access, API connections, third-party services.</p>
<h3 id="2-3-lifecycle-events">2.3 Lifecycle Events</h3>
<p>Nine hook events define the agent lifecycle:</p>
<table><thead><tr><th>Event</th><th>Trigger</th></tr></thead><tbody>
<tr><td>PreToolUse</td><td>Before any tool execution</td></tr>
<tr><td>PostToolUse</td><td>After tool execution</td></tr>
<tr><td>UserPromptSubmit</td><td>User message received</td></tr>
<tr><td>Stop</td><td>Agent completion</td></tr>
<tr><td>SubagentStop</td><td>Subagent completion</td></tr>
<tr><td>SessionStart</td><td>Session initialization</td></tr>
<tr><td>SessionEnd</td><td>Session termination</td></tr>
<tr><td>PreCompact</td><td>Before context compaction</td></tr>
<tr><td>Notification</td><td>System notification</td></tr>
</tbody></table>
<p>Hook exit codes follow Unix conventions: 0 for success, 2 for blocking errors (Claude processes stderr), other codes for non-blocking errors.</p>
<hr />
<h2 id="3-key-findings">3. Key Findings</h2>
<h3 id="3-1-the-inheritance-paradox">3.1 The Inheritance Paradox</h3>
<p><strong>Documentation Claim</strong>:</p>
<blockquote>
<p>“MCP Tools: Subagents can access MCP tools from configured MCP servers. When the tools field is omitted, subagents inherit all MCP tools available to the main thread.”</p>
</blockquote>
<p><strong>Observed Behavior</strong>: Plugin-defined subagents cannot access MCP tools under any tested configuration.</p>
<p>This discrepancy is documented across four GitHub issues (#13605, #15810, #14496, #7296), each describing a different manifestation of scope inheritance failure:</p>
<table><thead><tr><th>Issue</th><th>Failure Mode</th><th>Scope Context</th></tr></thead><tbody>
<tr><td>#13605</td><td>Plugin agents can’t access MCP</td><td>Plugin vs built-in</td></tr>
<tr><td>#15810</td><td>Subagents don’t inherit MCP</td><td>Parent-child hierarchy</td></tr>
<tr><td>#14496</td><td>Complex prompts break MCP access</td><td>Prompt complexity</td></tr>
<tr><td>#7296</td><td>Task-launched agents lack MCP</td><td>User-scoped inheritance</td></tr>
</tbody></table>
<p><strong>Analysis</strong>: The pattern suggests a fundamental architectural issue rather than isolated bugs. Tool inheritance operates differently across scope boundaries:</p>
<ol>
<li><strong>Built-in agents</strong> inherit MCP tools correctly</li>
<li><strong>Plugin-defined agents</strong> do not inherit MCP tools</li>
<li><strong>Task-launched agents</strong> receive a fresh scope without user-level configurations</li>
</ol>
<p><strong>Implication for Framework Design</strong>: Implicit tool inheritance models require explicit contracts at scope boundaries. Assuming tools propagate through agent hierarchies creates fragile dependencies. Explicit tool declarations at each scope level, while verbose, produce predictable behavior.</p>
<h3 id="3-2-topology-constraints-and-emergent-patterns">3.2 Topology Constraints and Emergent Patterns</h3>
<p><strong>Discovery</strong>: The platform enforces a single-level nesting limit for agent spawning.</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 = ['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>When an agent attempts to spawn a nested subagent, the platform returns:</p>
<pre class="z-code"><code><span class="z-text z-plain">Error: Subagents cannot spawn subagents
</span></code></pre>
<p><strong>Design Rationale (Inferred)</strong>:</p>
<ul>
<li>Prevents infinite recursion in autonomous systems</li>
<li>Maintains bounded resource consumption</li>
<li>Ensures predictable execution topology</li>
<li>Simplifies debugging and monitoring</li>
</ul>
<p><strong>Emergent Architecture: Hub-and-Spoke</strong></p>
<div class="hub-spoke-container" id="hub-spok">
<canvas class="hub-spoke-canvas" aria-label="Hub-and-spoke agent topology visualization"></canvas>
<div class="hub-spoke-info">
<span class="info-label">Topology</span>
<span class="info-value">Hub-and-Spoke</span>
</div>
</div>
<script>
(function() {
const containerId = 'hub-spok';
// Decode HTML entities (Tera encodes / as /)
function decodeHTML(str) {
const textarea = document.createElement('textarea');
textarea.innerHTML = str;
return textarea.value;
}
const hubName = decodeHTML('Main Agent');
const spokeNames = [decodeHTML('Agent 1'), decodeHTML('Agent 2'), decodeHTML('Agent 3')];
const showUser = true;
const showCommand = true;
function initHubSpoke() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.hub-spoke-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
// Colors
const colors = {
user: '#ff0080',
command: '#ff8800',
hub: '#00d4ff',
spoke: '#8b5cf6',
particle: '#00ff88',
connection: 'rgba(0, 212, 255, 0.3)'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 300;
}
resize();
window.addEventListener('resize', resize);
// Get node positions
function getNodes() {
const centerX = canvas.width / 2;
const centerY = canvas.height / 2 + 20;
const spokeRadius = Math.min(canvas.width * 0.35, 120);
const nodes = [];
// User node
if (showUser) {
nodes.push({
type: 'user',
label: 'User',
x: centerX,
y: 40,
radius: 20,
color: colors.user
});
}
// Command node
if (showCommand) {
nodes.push({
type: 'command',
label: 'Command',
x: centerX,
y: showUser ? 100 : 50,
radius: 22,
color: colors.command
});
}
// Hub node
const hubY = showUser && showCommand ? centerY : centerY - 30;
nodes.push({
type: 'hub',
label: hubName,
x: centerX,
y: hubY,
radius: 32,
color: colors.hub
});
// Spoke nodes
const spokeCount = spokeNames.length;
const angleStep = Math.PI / (spokeCount + 1);
const startAngle = Math.PI;
spokeNames.forEach((name, i) => {
const angle = startAngle - angleStep * (i + 1);
nodes.push({
type: 'spoke',
label: name,
x: centerX + Math.cos(angle) * spokeRadius,
y: hubY + Math.sin(angle) * spokeRadius * 0.7,
radius: 24,
color: colors.spoke
});
});
return nodes;
}
function createParticle(from, to) {
return {
fromX: from.x,
fromY: from.y,
toX: to.x,
toY: to.y,
progress: Math.random(),
speed: 0.005 + Math.random() * 0.003,
x: from.x,
y: from.y
};
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
const command = nodes.find(n => n.type === 'command');
const user = nodes.find(n => n.type === 'user');
// Draw connections
ctx.lineWidth = 2;
ctx.strokeStyle = colors.connection;
// User -> Command
if (user && command) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(command.x, command.y - command.radius);
ctx.stroke();
}
// Command -> Hub
if (command && hub) {
ctx.beginPath();
ctx.moveTo(command.x, command.y + command.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
} else if (user && hub) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
}
// Hub -> Spokes
spokes.forEach(spoke => {
ctx.beginPath();
ctx.moveTo(hub.x, hub.y);
ctx.lineTo(spoke.x, spoke.y);
ctx.stroke();
});
// Draw nodes
nodes.forEach(node => {
// Glow
const gradient = ctx.createRadialGradient(
node.x, node.y, 0,
node.x, node.y, node.radius * 2
);
gradient.addColorStop(0, node.color.replace(')', ', 0.3)').replace('#', 'rgba(').replace(/^rgba\(([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})/, (m, r, g, b) => `rgba(${parseInt(r, 16)}, ${parseInt(g, 16)}, ${parseInt(b, 16)}`));
gradient.addColorStop(1, 'transparent');
// Simpler glow approach
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 = node.color;
ctx.lineWidth = 2;
ctx.stroke();
// Label
ctx.fillStyle = '#e0e0e4';
ctx.font = node.type === 'hub' ? 'bold 11px JetBrains Mono' : '10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
// Wrap long labels
const maxWidth = node.radius * 1.8;
const words = node.label.split(' ');
if (words.length > 1 && ctx.measureText(node.label).width > maxWidth) {
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);
}
// Type indicator below node
if (node.type === 'hub') {
ctx.fillStyle = '#8888a0';
ctx.font = '9px JetBrains Mono';
ctx.fillText('(Hub)', node.x, node.y + node.radius + 14);
}
});
// Update and draw particles
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.progress = 0;
// Reverse direction
[p.fromX, p.toX] = [p.toX, p.fromX];
[p.fromY, p.toY] = [p.toY, p.fromY];
}
const ease = p.progress * p.progress * (3 - 2 * p.progress);
p.x = p.fromX + (p.toX - p.fromX) * ease;
p.y = p.fromY + (p.toY - p.fromY) * ease;
ctx.fillStyle = colors.particle;
ctx.beginPath();
ctx.arc(p.x, p.y, 3, 0, Math.PI * 2);
ctx.fill();
// Glow
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 10;
ctx.beginPath();
ctx.arc(p.x, p.y, 3, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
spokes.forEach(spoke => {
particles.push(createParticle(hub, spoke));
});
// Respect reduced motion
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const nodes = getNodes();
const hub = nodes.find(n => n.type === 'hub');
const spokes = nodes.filter(n => n.type === 'spoke');
const command = nodes.find(n => n.type === 'command');
const user = nodes.find(n => n.type === 'user');
ctx.lineWidth = 2;
ctx.strokeStyle = colors.connection;
if (user && command) {
ctx.beginPath();
ctx.moveTo(user.x, user.y + user.radius);
ctx.lineTo(command.x, command.y - command.radius);
ctx.stroke();
}
if (command && hub) {
ctx.beginPath();
ctx.moveTo(command.x, command.y + command.radius);
ctx.lineTo(hub.x, hub.y - hub.radius);
ctx.stroke();
}
spokes.forEach(spoke => {
ctx.beginPath();
ctx.moveTo(hub.x, hub.y);
ctx.lineTo(spoke.x, spoke.y);
ctx.stroke();
});
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 = '#e0e0e4';
ctx.font = node.type === 'hub' ? 'bold 11px JetBrains Mono' : '10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(node.label, node.x, node.y);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initHubSpoke);
} else {
initHubSpoke();
}
})();
</script>
<style>
.hub-spoke-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.hub-spoke-canvas {
width: 100%;
height: 300px;
display: block;
}
.hub-spoke-info {
position: absolute;
bottom: 1rem;
right: 1rem;
background: rgba(0, 0, 0, 0.6);
padding: 0.5rem 0.75rem;
border-radius: 6px;
font-family: 'JetBrains Mono', monospace;
font-size: 0.75rem;
}
.hub-spoke-info .info-label {
color: var(--meta-color);
display: block;
margin-bottom: 0.25rem;
}
.hub-spoke-info .info-value {
color: #00d4ff;
}
@media (max-width: 768px) {
.hub-spoke-canvas {
height: 250px;
}
}
</style>
<p>This constraint eliminates tree-structured agent hierarchies in favor of flat, hub-coordinated topologies. The “hub” agent coordinates parallel execution of “spoke” agents. No spoke can spawn additional agents.</p>
<p><strong>Observed Trade-off</strong>:</p>
<table><thead><tr><th>Lost Capability</th><th>Gained Property</th></tr></thead><tbody>
<tr><td>Recursive decomposition</td><td>Bounded execution depth</td></tr>
<tr><td>Dynamic hierarchy</td><td>Predictable topology</td></tr>
<tr><td>Arbitrary nesting</td><td>Simplified resource management</td></tr>
</tbody></table>
<p><strong>Implication for Framework Design</strong>: Topology constraints are design decisions, not merely limitations. The hub-and-spoke pattern that emerges from single-level nesting produces systems that are easier to reason about, debug, and monitor than arbitrary recursive structures.</p>
<h3 id="3-3-naming-as-behavior">3.3 Naming as Behavior</h3>
<p><strong>Discovery</strong>: Claude Code infers agent behavior from agent names.</p>
<p>An agent named <code>code-reviewer</code> triggers built-in review behaviors that may override custom system prompt instructions. The platform applies heuristics based on naming conventions.</p>
<p><strong>Observed Pattern</strong>:</p>
<table><thead><tr><th>Agent Name</th><th>Inferred Behavior</th></tr></thead><tbody>
<tr><td><code>code-reviewer</code></td><td>Generic code review patterns</td></tr>
<tr><td><code>test-writer</code></td><td>Test generation patterns</td></tr>
<tr><td><code>implementation-planner</code></td><td>Less inference, more custom control</td></tr>
</tbody></table>
<p><strong>Analysis</strong>: This represents a “convention over configuration” paradigm applied to AI agent systems. The platform assumes semantically meaningful names carry behavioral intent.</p>
<p><strong>Implications</strong>:</p>
<ol>
<li>Naming conventions become functional requirements</li>
<li>Distinctive, non-generic names preserve custom behavior</li>
<li>Agent system design must consider name-based inference</li>
</ol>
<hr />
<h2 id="4-emergent-patterns">4. Emergent Patterns</h2>
<h3 id="4-1-i-o-separation-hybrid-architecture">4.1 I/O Separation (Hybrid Architecture)</h3>
<p>In response to MCP access limitations, a clear architectural pattern emerged: separating I/O operations from intelligence operations.</p>
<p><strong>Layer Model</strong>:</p>
<table><thead><tr><th>Layer</th><th>Responsibilities</th><th>Components</th></tr></thead><tbody>
<tr><td>I/O</td><td>MCP access, file ops, user interaction, caching</td><td>Commands</td></tr>
<tr><td>Intelligence</td><td>Reasoning, analysis, formatting, decisions</td><td>Agents</td></tr>
</tbody></table>
<p><strong>6-Phase Pipeline Example</strong>:</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": "Availability", "io": "external"},
{"phase": 1, "owner": "Command", "label": "Data Resolve", "io": "external"},
{"phase": 2, "owner": "Command", "label": "Load Content", "io": "local"},
{"phase": 3, "owner": "Command", "label": "Validation", "io": "external"},
{"phase": 4, "owner": "Agent", "label": "Reasoning", "io": "none"},
{"phase": 5, "owner": "Agent", "label": "Formatting", "io": "none"},
{"phase": 6, "owner": "Command", "label": "Delivery", "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><strong>Generalizability</strong>: This separation applies to any framework where tool access constraints exist. The intelligence layer becomes portable and testable in isolation. The I/O layer becomes the platform-specific adapter.</p>
<h3 id="4-2-phase-based-validation">4.2 Phase-Based Validation</h3>
<p>Each phase transition represents a validation checkpoint:</p>
<table><thead><tr><th>Checkpoint</th><th>Validation</th></tr></thead><tbody>
<tr><td>Pre-phase</td><td>Input contract verification</td></tr>
<tr><td>Mid-phase</td><td>Progress checkpoint</td></tr>
<tr><td>Post-phase</td><td>Output contract enforcement</td></tr>
<tr><td>Inter-phase</td><td>Data transformation validation</td></tr>
</tbody></table>
<p><strong>Error Recovery Strategies</strong>:</p>
<ol>
<li>Rollback to last valid state</li>
<li>Retry with modified parameters</li>
<li>Escalate to fallback mode</li>
<li>Preserve partial results</li>
</ol>
<h3 id="4-3-graceful-degradation">4.3 Graceful Degradation</h3>
<p><strong>FALLBACK_MODE Pattern</strong>:</p>
<p>When external services become unavailable, the system degrades gracefully:</p>
<div class="comparison-container" id="comparis">
<canvas class="comparison-canvas" aria-label="Mode comparison visualization"></canvas>
</div>
<script>
(function() {
const containerId = 'comparis';
const mode1Title = 'Normal Mode';
const mode1Steps = ['Phase 1: MCP Resolve', 'Phase 3: Dup Check', 'Phase 6: Create Issue'];
const mode2Title = 'Fallback Mode';
const mode2Steps = ['Phase 1: Skip', 'Phase 3: Skip', 'Phase 6: Local File'];
const sharedTitle = 'Intelligence Layer (Always Active)';
const sharedSteps = ['Phase 4: Reasoning', 'Phase 5: Formatting'];
function initComparison() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.comparison-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
const colors = {
mode1: '#00d4ff',
mode2: '#ff8800',
shared: '#00ff88',
skip: '#444466',
particle: '#00ff88',
connection: 'rgba(255, 255, 255, 0.2)',
text: '#e0e0e4',
subtext: '#8888a0'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = 320;
}
resize();
window.addEventListener('resize', resize);
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const leftX = canvas.width * 0.25;
const rightX = canvas.width * 0.75;
const centerX = canvas.width / 2;
const headerY = 35;
const stepsStartY = 80;
const stepSpacing = 45;
const sharedY = 240;
// Draw mode headers
function drawHeader(x, title, color) {
ctx.fillStyle = color;
ctx.font = 'bold 14px JetBrains Mono';
ctx.textAlign = 'center';
ctx.shadowColor = color;
ctx.shadowBlur = 10;
ctx.fillText(title, x, headerY);
ctx.shadowBlur = 0;
// Underline
ctx.strokeStyle = color;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.moveTo(x - 60, headerY + 8);
ctx.lineTo(x + 60, headerY + 8);
ctx.stroke();
}
drawHeader(leftX, mode1Title, colors.mode1);
drawHeader(rightX, mode2Title, colors.mode2);
// Draw steps for each mode
function drawStep(x, y, text, color, isSkip) {
const width = 130;
const height = 32;
ctx.shadowColor = color;
ctx.shadowBlur = isSkip ? 0 : 12;
ctx.fillStyle = isSkip ? colors.skip : color;
ctx.beginPath();
ctx.roundRect(x - width/2, y - height/2, width, height, 6);
ctx.fill();
ctx.shadowBlur = 0;
if (!isSkip) {
ctx.strokeStyle = '#00ff88';
ctx.lineWidth = 1;
ctx.stroke();
} else {
ctx.setLineDash([4, 4]);
ctx.strokeStyle = '#666';
ctx.lineWidth = 1;
ctx.stroke();
ctx.setLineDash([]);
}
ctx.fillStyle = isSkip ? '#666' : '#0a0a0f';
ctx.font = isSkip ? '10px JetBrains Mono' : 'bold 10px JetBrains Mono';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(text, x, y);
return { x, y, width, height };
}
// Mode 1 steps
const mode1Nodes = [];
mode1Steps.forEach((step, i) => {
const y = stepsStartY + i * stepSpacing;
mode1Nodes.push(drawStep(leftX, y, step, colors.mode1, false));
});
// Mode 2 steps
const mode2Nodes = [];
mode2Steps.forEach((step, i) => {
const y = stepsStartY + i * stepSpacing;
const isSkip = step.toLowerCase().includes('skip');
mode2Nodes.push(drawStep(rightX, y, step, colors.mode2, isSkip));
});
// Connections between steps
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 1;
for (let i = 0; i < mode1Nodes.length - 1; i++) {
const from = mode1Nodes[i];
const to = mode1Nodes[i + 1];
ctx.beginPath();
ctx.moveTo(from.x, from.y + from.height/2);
ctx.lineTo(to.x, to.y - to.height/2);
ctx.stroke();
}
for (let i = 0; i < mode2Nodes.length - 1; i++) {
const from = mode2Nodes[i];
const to = mode2Nodes[i + 1];
ctx.beginPath();
ctx.moveTo(from.x, from.y + from.height/2);
ctx.lineTo(to.x, to.y - to.height/2);
ctx.stroke();
}
// Shared section
ctx.fillStyle = colors.shared;
ctx.font = 'bold 13px JetBrains Mono';
ctx.textAlign = 'center';
ctx.shadowColor = colors.shared;
ctx.shadowBlur = 10;
ctx.fillText(sharedTitle, centerX, sharedY - 25);
ctx.shadowBlur = 0;
// Shared steps box
const sharedWidth = 200;
const sharedHeight = 50;
ctx.fillStyle = 'rgba(0, 255, 136, 0.15)';
ctx.strokeStyle = colors.shared;
ctx.lineWidth = 2;
ctx.beginPath();
ctx.roundRect(centerX - sharedWidth/2, sharedY - 10, sharedWidth, sharedHeight, 8);
ctx.fill();
ctx.stroke();
// Shared step text
ctx.fillStyle = colors.text;
ctx.font = '11px JetBrains Mono';
sharedSteps.forEach((step, i) => {
ctx.fillText(step, centerX, sharedY + 8 + i * 16);
});
// Arrows from both modes to shared
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 2;
// Left arrow
const lastMode1 = mode1Nodes[mode1Nodes.length - 1];
ctx.beginPath();
ctx.moveTo(lastMode1.x, lastMode1.y + lastMode1.height/2);
ctx.quadraticCurveTo(lastMode1.x, sharedY - 30, centerX - sharedWidth/2, sharedY + 15);
ctx.stroke();
// Right arrow
const lastMode2 = mode2Nodes[mode2Nodes.length - 1];
ctx.beginPath();
ctx.moveTo(lastMode2.x, lastMode2.y + lastMode2.height/2);
ctx.quadraticCurveTo(lastMode2.x, sharedY - 30, centerX + sharedWidth/2, sharedY + 15);
ctx.stroke();
// "Always Active" badge
ctx.fillStyle = colors.shared;
ctx.font = 'bold 9px JetBrains Mono';
ctx.fillText('✓ ALWAYS ACTIVE', centerX, sharedY + sharedHeight + 8);
// Animate particles
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.progress = 0;
p.side = p.side === 'left' ? 'right' : 'left';
}
const nodes = p.side === 'left' ? mode1Nodes : mode2Nodes;
const segmentIndex = Math.floor(p.progress * nodes.length);
const segmentProgress = (p.progress * nodes.length) % 1;
if (segmentIndex < nodes.length - 1) {
const from = nodes[segmentIndex];
const to = nodes[segmentIndex + 1];
const x = from.x + (to.x - from.x) * segmentProgress;
const y = from.y + (to.y - from.y) * segmentProgress;
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
particles.push({ side: 'left', progress: 0, speed: 0.008 });
particles.push({ side: 'right', progress: 0.5, speed: 0.008 });
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
draw();
// Just draw once for static
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initComparison);
} else {
initComparison();
}
})();
</script>
<style>
.comparison-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
}
.comparison-canvas {
width: 100%;
height: 320px;
display: block;
}
@media (max-width: 768px) {
.comparison-container {
overflow-x: auto;
}
.comparison-canvas {
min-width: 500px;
}
}
</style>
<p>The intelligence layers (Phases 4-5) function identically in both modes. Core reasoning is preserved even when I/O capabilities are reduced.</p>
<hr />
<h2 id="5-framework-design-implications">5. Framework Design Implications</h2>
<h3 id="5-1-tool-access-philosophy">5.1 Tool Access Philosophy</h3>
<p><strong>Recommendation</strong>: Prefer explicit tool declarations over implicit inheritance.</p>
<p>The inheritance paradox demonstrates that implicit models create unexpected scope boundaries. Explicit declarations, while verbose, produce predictable behavior:</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-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Explicit (recommended)
</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">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">Grep</span>
</span><span class="z-source z-yaml">
</span><span class="z-source z-yaml"><span class="z-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Implicit (problematic)
</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 class="z-string z-unquoted z-plain z-out z-yaml">inherit</span> <span class="z-comment z-line z-number-sign z-yaml"><span class="z-punctuation z-definition z-comment z-line z-number-sign z-yaml">#</span> Behavior varies by context
</span></span></code></pre>
<h3 id="5-2-documentation-fidelity">5.2 Documentation Fidelity</h3>
<p><strong>Requirement</strong>: Implementation must match documentation.</p>
<p>The gap between documented and actual MCP behavior consumed significant debugging effort. Automated testing of documented behaviors would catch such discrepancies before they reach users.</p>
<h3 id="5-3-testing-in-real-contexts">5.3 Testing in Real Contexts</h3>
<p><strong>Requirement</strong>: Test with actual platform constraints.</p>
<p>MCP access works in isolation testing but fails in plugin contexts. Integration tests must execute in production-like environments with actual scope boundaries.</p>
<h3 id="5-4-developer-experience-considerations">5.4 Developer Experience Considerations</h3>
<p><strong>Observation</strong>: Complex deployment requirements discourage experimentation.</p>
<p>The three-location sync requirement, lack of hot reload, and strict schema validation add friction to the development cycle. Each constraint adds approximately 2-5 minutes per change cycle versus seconds for hot-reload systems.</p>
<p><strong>Trade-off Analysis</strong>:</p>
<table><thead><tr><th>Constraint</th><th>Benefit</th><th>Cost</th></tr></thead><tbody>
<tr><td>Three-location sync</td><td>Version consistency</td><td>Manual sync overhead</td></tr>
<tr><td>No hot reload</td><td>State predictability</td><td>Restart delay</td></tr>
<tr><td>Strict schema</td><td>Early error detection</td><td>Debugging difficulty</td></tr>
</tbody></table>
<hr />
<h2 id="6-conclusion">6. Conclusion</h2>
<h3 id="summary-of-contributions">Summary of Contributions</h3>
<p>This empirical study of Claude Code plugin development reveals patterns applicable to multi-agent AI system design:</p>
<ol>
<li>
<p><strong>The Inheritance Paradox</strong>: Tool access inheritance models documented in specifications may not function across all scope boundaries. Explicit contracts prevent unexpected behavior.</p>
</li>
<li>
<p><strong>Topology-Driven Architecture</strong>: Platform-enforced constraints (like single-level nesting) drive the emergence of specific patterns (hub-and-spoke) that may be superior to unconstrained designs.</p>
</li>
<li>
<p><strong>Naming as Behavior</strong>: In AI agent systems, naming conventions carry functional implications beyond labeling.</p>
</li>
<li>
<p><strong>I/O Separation</strong>: Separating I/O from intelligence creates portable, testable, gracefully-degrading systems.</p>
</li>
</ol>
<h3 id="limitations">Limitations</h3>
<p>This study is based on observations from a single platform (Claude Code) during a specific development period. Findings may not generalize to all agent frameworks. Additionally, platform behavior may change as bugs are resolved.</p>
<h3 id="future-research-directions">Future Research Directions</h3>
<ol>
<li>Comparative analysis of tool inheritance models across agent platforms</li>
<li>Formal specification of scope contracts for multi-agent systems</li>
<li>Empirical studies of naming-behavior coupling in other AI systems</li>
<li>Framework design patterns that explicitly leverage topology constraints</li>
</ol>
<hr />
<h2 id="appendix-evidence-summary">Appendix: Evidence Summary</h2>
<h3 id="github-issues-referenced">GitHub Issues Referenced</h3>
<table><thead><tr><th>Issue</th><th>Description</th></tr></thead><tbody>
<tr><td>#13605</td><td>Custom plugin agents can’t access MCP</td></tr>
<tr><td>#15810</td><td>Subagents don’t inherit MCP 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>
<h3 id="research-metrics">Research Metrics</h3>
<ul>
<li><strong>Observation Period</strong>: January 3-4, 2026</li>
<li><strong>Token Investment</strong>: ~265,000 tokens across sessions</li>
<li><strong>Distinct Observations</strong>: 13 documented findings</li>
<li><strong>Finding Types</strong>: 4 Decisions, 8 Discoveries, 1 Change</li>
</ul>
<h3 id="methodology">Methodology</h3>
<p>Observations were collected through development sessions using the claude-mem persistent memory system. Each finding was cross-referenced against documentation and, where applicable, GitHub issue reports. Workarounds were developed through iterative experimentation.</p>
<hr />
<h2 id="get-the-plugin">Get the Plugin</h2>
<p>The plugin discussed in this research 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>: <a href="/posts/claude-code-plugin-journey-part1/">The Hybrid Architecture Pattern</a> — Building the plugin, lessons learned</li>
<li><strong>Part 2</strong> (You are here): Research insights, patterns</li>
</ul>
<hr />
<p><em>This article is based on empirical observations from developing the agent-team-creator Claude Code plugin. For practical implementation guidance, see Part 1.</em></p>
The Inheritance Paradox: Tool Scoping in Multi-Agent Systems
This is Part 2 of a three-part series. See Part 0 for the plugin overview and installation, or Part 1 for the development journey.
Abstract: This article presents empirical observations from developing a Claude Code plugin, revealing fundamental patterns in multi-agent AI system design. Through documented development sessions, we identify three key findings: (1) implicit tool inheritance models consistently fail in practice, requiring explicit scope contracts; (2) platform-enforced topology constraints drive the emergence of specific architectural patterns; and (3) agent naming conventions become functional requirements in AI systems. These findings have implications for the design of agent frameworks beyond the specific platform studied.
…
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.
…
Claude Code Plugin Journey Part 0: Agent Team Creator
2026-01-06T10:00:00+00:00
2026-01-06T10:00:00+00:00
Christian Picon Calderon
https://futurewithml.netlify.app/posts/claude-code-plugin-journey-part0/
<h1 id="claude-code-plugin-journey-part-0-agent-team-creator">Claude Code Plugin Journey Part 0: Agent Team Creator</h1>
<p>What if you could point an AI at your project and have it generate specialists who actually understand your stack? Not generic assistants—agents that know your architecture, your patterns, your conventions.</p>
<p>That’s what <code>agent-team-creator</code> does. Let me show you the workflow.</p>
<span id="continue-reading"></span>
<hr />
<h2 id="scenario-1-generate-your-agent-team">Scenario 1: Generate Your Agent Team</h2>
<p>You start a new project—or join an existing one. The codebase is unfamiliar. You need help, but generic AI advice isn’t cutting it.</p>
<p><strong>Step 1: Generate your agent team</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-agent-team
</span></code></pre>
<p>Watch as the plugin analyzes your project:</p>
<pre class="z-code"><code><span class="z-text z-plain">Analyzing codebase...
</span><span class="z-text z-plain">├── Languages: Python (75%), TypeScript (20%), SQL (5%)
</span><span class="z-text z-plain">├── Frameworks: FastAPI, React, SQLAlchemy
</span><span class="z-text z-plain">├── Architecture: Monorepo with backend/frontend split
</span><span class="z-text z-plain">├── Patterns: Repository pattern, dependency injection
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Generating specialized agents...
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ fastapi-expert
</span><span class="z-text z-plain"> Knows: Your endpoint patterns, Pydantic models, middleware stack
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ react-specialist
</span><span class="z-text z-plain"> Knows: Your component library, state management, hook patterns
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ database-architect
</span><span class="z-text z-plain"> Knows: Your SQLAlchemy models, migration patterns, query conventions
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ test-strategist
</span><span class="z-text z-plain"> Knows: Your pytest fixtures, mocking patterns, test utilities
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Team saved to .claude/agents/
</span></code></pre>
<p><strong>Step 2: Use your agents immediately</strong></p>
<p>Now you have project-aware specialists. Here’s how to use them:</p>
<p><strong>Ask about architecture:</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Use the fastapi-expert agent to explain how authentication
</span><span class="z-text z-plain">works in this project
</span></code></pre>
<p><strong>Implement a feature:</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Use the react-specialist agent to help me add a new dashboard
</span><span class="z-text z-plain">component following our existing patterns
</span></code></pre>
<p><strong>Debug an issue:</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Use the database-architect agent to help me understand why
</span><span class="z-text z-plain">this query is slow - check src/repositories/user_repo.py
</span></code></pre>
<p><strong>Write tests:</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Use the test-strategist agent to write integration tests for
</span><span class="z-text z-plain">the new payment endpoint following our test conventions
</span></code></pre>
<p><strong>The difference?</strong> These agents don’t give generic advice. They reference <em>your</em> files, <em>your</em> patterns, <em>your</em> conventions.</p>
<hr />
<h2 id="scenario-2-advanced-debugging-workflow">Scenario 2: Advanced Debugging Workflow</h2>
<p>After you’ve generated your agent team, you can create a <strong>Project Debugger</strong>—an orchestrator that coordinates your specialists to diagnose complex issues.</p>
<p><strong>Step 1: Generate the Project Debugger</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-debugger
</span></code></pre>
<pre class="z-code"><code><span class="z-text z-plain">Discovering project agents...
</span><span class="z-text z-plain">├── Found: fastapi-expert, react-specialist, database-architect, test-strategist
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Analyzing project architecture...
</span><span class="z-text z-plain">├── Entry points identified
</span><span class="z-text z-plain">├── Error handling patterns mapped
</span><span class="z-text z-plain">├── Logging conventions detected
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Generating project-debugger.md...
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">✓ Created: .claude/agents/project-debugger.md
</span><span class="z-text z-plain"> - Orchestrates your 4 specialist agents
</span><span class="z-text z-plain"> - Produces structured debugging reports
</span><span class="z-text z-plain"> - Identifies root causes with file:line references
</span></code></pre>
<p><strong>Step 2: Use the Debugger to investigate</strong></p>
<p>When you hit a bug, invoke the project debugger:</p>
<pre class="z-code"><code><span class="z-text z-plain">Use the project-debugger agent to investigate: Users are
</span><span class="z-text z-plain">getting 500 errors when submitting the checkout form
</span></code></pre>
<p>The debugger orchestrates your specialists:</p>
<pre class="z-code"><code><span class="z-text z-plain">Consulting fastapi-expert...
</span><span class="z-text z-plain">├── Traced request flow through api/routes/checkout.py
</span><span class="z-text z-plain">├── Found: PaymentService.process() raises unhandled exception
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Consulting database-architect...
</span><span class="z-text z-plain">├── Checked transaction handling in repositories/order_repo.py
</span><span class="z-text z-plain">├── Found: Missing rollback on payment failure
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Consulting test-strategist...
</span><span class="z-text z-plain">├── Reviewed test coverage for checkout flow
</span><span class="z-text z-plain">├── Found: No test for payment failure scenario
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Generating debugging report...
</span></code></pre>
<p><strong>Step 3: Generate a debugging report</strong></p>
<p>The debugger produces a structured report saved to <code>.claude/reports/debugging/</code> :</p>
<pre data-lang="markdown" class="language-markdown z-code"><code class="language-markdown" data-lang="markdown"><span class="z-text z-html z-markdown"><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-1 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">#</span> </span><span class="z-markup z-heading z-1 z-markdown"><span class="z-entity z-name z-section z-markdown">Debugging Report: Checkout 500 Errors</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown">
</span><span class="z-text z-html z-markdown"><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-2 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">##</span> </span><span class="z-markup z-heading z-2 z-markdown"><span class="z-entity z-name z-section z-markdown">Root Cause</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown"><span class="z-meta z-paragraph z-markdown">Missing exception handling in PaymentService.process()
</span></span><span class="z-text z-html z-markdown"><span class="z-meta z-paragraph z-markdown">(src/services/payment.py:45) combined with missing
</span></span><span class="z-text z-html z-markdown"><span class="z-meta z-paragraph z-markdown">transaction rollback (src/repositories/order_repo.py:78)
</span></span><span class="z-text z-html z-markdown"><span class="z-meta z-paragraph z-markdown">
</span></span><span class="z-text z-html z-markdown"><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-2 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">##</span> </span><span class="z-markup z-heading z-2 z-markdown"><span class="z-entity z-name z-section z-markdown">Evidence</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-bullet z-markdown"><span class="z-punctuation z-definition z-list_item z-markdown">-</span></span><span class="z-markup z-list z-unnumbered z-markdown"> <span class="z-meta z-paragraph z-list z-markdown">File: src/services/payment.py:45-52
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-unnumbered z-bullet z-markdown"><span class="z-punctuation z-definition z-list_item z-markdown">-</span></span><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"> File: src/repositories/order_repo.py:78-85
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-unnumbered z-bullet z-markdown"><span class="z-punctuation z-definition z-list_item z-markdown">-</span></span><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"> Missing test: tests/integration/test_checkout.py
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-unnumbered z-markdown">
</span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-markdown"></span><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-2 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">##</span> </span><span class="z-markup z-heading z-2 z-markdown"><span class="z-entity z-name z-section z-markdown">Recommended Fix</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-bullet z-markdown">1<span class="z-punctuation z-definition z-list_item z-markdown">.</span></span><span class="z-markup z-list z-numbered z-markdown"> <span class="z-meta z-paragraph z-list z-markdown">Add try/except in payment.py:45
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-numbered z-bullet z-markdown">2<span class="z-punctuation z-definition z-list_item z-markdown">.</span></span><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"> Implement rollback in order_repo.py:78
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-numbered z-bullet z-markdown">3<span class="z-punctuation z-definition z-list_item z-markdown">.</span></span><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"> Add failure scenario test
</span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-markdown"><span class="z-meta z-paragraph z-list z-markdown"></span></span><span class="z-markup z-list z-numbered z-markdown">
</span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-numbered z-markdown"></span><span class="z-meta z-block-level z-markdown"><span class="z-markup z-heading z-2 z-markdown"><span class="z-punctuation z-definition z-heading z-begin z-markdown">##</span> </span><span class="z-markup z-heading z-2 z-markdown"><span class="z-entity z-name z-section z-markdown">Side Effects</span><span class="z-meta z-whitespace z-newline z-markdown">
</span></span></span></span><span class="z-text z-html z-markdown"><span class="z-markup z-list z-unnumbered z-bullet z-markdown"><span class="z-punctuation z-definition z-list_item z-markdown">-</span></span><span class="z-markup z-list z-unnumbered z-markdown"> <span class="z-meta z-paragraph z-list z-markdown">Orders may be in inconsistent state (needs migration)
</span></span></span></code></pre>
<p><strong>Step 4: Create a Jira ticket from the report</strong></p>
<p>Now turn that report into a Jira task. The command automatically finds the most recent debugging report:</p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-jira-task
</span></code></pre>
<pre class="z-code"><code><span class="z-text z-plain">Finding latest debugging report...
</span><span class="z-text z-plain">├── Found: .claude/reports/debugging/report-2026-01-06-1430.md
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Loading debugging report...
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">Checking for similar issues...
</span><span class="z-text z-plain">├── Searching: "checkout payment exception rollback"
</span><span class="z-text z-plain">├── Found 2 potentially related issues:
</span><span class="z-text z-plain">
</span><span class="z-text z-plain"> PROJ-234: "Payment processing timeout errors"
</span><span class="z-text z-plain"> Status: In Progress
</span><span class="z-text z-plain">
</span><span class="z-text z-plain"> PROJ-189: "Checkout form validation issues"
</span><span class="z-text z-plain"> Status: Done
</span><span class="z-text z-plain">
</span><span class="z-text z-plain">How would you like to proceed?
</span><span class="z-text z-plain">> Create new task anyway
</span><span class="z-text z-plain">> Abort - I'll update an existing issue
</span></code></pre>
<p>If you choose to create a new task:</p>
<pre class="z-code"><code><span class="z-text z-plain">Creating Jira issue...
</span><span class="z-text z-plain">✓ Created: PROJ-456 "Fix checkout 500 errors: missing exception handling"
</span><span class="z-text z-plain"> https://yourcompany.atlassian.net/browse/PROJ-456
</span></code></pre>
<p>The duplicate check prevents cluttering your backlog with related issues. If the bug is a variant of an existing issue, you can update that ticket instead of creating a new one.</p>
<p><strong>No Jira configured?</strong> The command gracefully falls back to generating a ready-to-paste markdown file in <code>.claude/reports/jira-drafts/</code>.</p>
<hr />
<h2 id="scenario-3-repeatable-workflow-for-multiple-bugs">Scenario 3: Repeatable Workflow for Multiple Bugs</h2>
<p>Each bug investigation creates its own debugging report, which leads to its own Jira ticket. Here’s how the workflow scales across multiple issues:</p>
<p><strong>Monday: API performance issue</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Use the project-debugger agent to investigate: Why are
</span><span class="z-text z-plain">API response times spiking during peak hours?
</span></code></pre>
<p>Report saved: <code>.claude/reports/debugging/report-2026-01-06-0900.md</code></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-jira-task
</span></code></pre>
<p>Created: <code>PROJ-457 "Optimize database connection pooling for peak load"</code></p>
<hr />
<p><strong>Tuesday: Frontend rendering bug</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Use the project-debugger agent to investigate: The dashboard
</span><span class="z-text z-plain">chart isn't updating when new data arrives
</span></code></pre>
<p>Report saved: <code>.claude/reports/debugging/report-2026-01-07-1100.md</code></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-jira-task
</span></code></pre>
<p>Created: <code>PROJ-458 "Fix React state synchronization in DashboardChart component"</code></p>
<hr />
<p><strong>Wednesday: Authentication edge case</strong></p>
<pre class="z-code"><code><span class="z-text z-plain">Use the project-debugger agent to investigate: Users are
</span><span class="z-text z-plain">being logged out randomly after password changes
</span></code></pre>
<p>Report saved: <code>.claude/reports/debugging/report-2026-01-08-1400.md</code></p>
<pre class="z-code"><code><span class="z-text z-plain">/generate-jira-task
</span></code></pre>
<p>Created: <code>PROJ-459 "Handle session invalidation on password change correctly"</code></p>
<hr />
<p>Each investigation is independent. The debugger creates timestamped reports, and <code>/generate-jira-task</code> always picks up the most recent one. Your debugging history accumulates in <code>.claude/reports/debugging/</code>, giving you a searchable archive of past investigations.</p>
<hr />
<h2 id="the-complete-workflow">The Complete Workflow</h2>
<div class="workflow-container" id="workflow">
<canvas class="workflow-canvas" aria-label="Workflow visualization"></canvas>
</div>
<script>
(function() {
const containerId = 'workflow';
// Decode HTML entities (Tera encodes / as /)
function decodeHTML(str) {
const textarea = document.createElement('textarea');
textarea.innerHTML = str;
return textarea.value;
}
const stepsData = [
{ title: decodeHTML('/generate-agent-team'), desc: decodeHTML('Creates specialist agents') },
{ title: decodeHTML('Use agents daily'), desc: decodeHTML('fastapi-expert react-specialist') },
{ title: decodeHTML('/generate-debugger'), desc: decodeHTML('Creates project-debugger') },
{ title: decodeHTML('Debug issues'), desc: decodeHTML('Saves to .claude/reports/') },
{ title: decodeHTML('/generate-jira-task'), desc: decodeHTML('Creates Jira ticket') }
];
function initWorkflow() {
const container = document.getElementById(containerId);
if (!container) return;
const canvas = container.querySelector('.workflow-canvas');
const ctx = canvas.getContext('2d');
let particles = [];
let time = 0;
const colors = {
primary: '#00d4ff',
secondary: '#8b5cf6',
accent: '#00ff88',
particle: '#00ff88',
connection: 'rgba(0, 212, 255, 0.4)',
text: '#e0e0e4',
subtext: '#8888a0'
};
function resize() {
const rect = container.getBoundingClientRect();
canvas.width = rect.width;
canvas.height = Math.max(550, stepsData.length * 130 + 100);
container.style.height = canvas.height + 'px';
}
resize();
window.addEventListener('resize', resize);
function getStepPositions() {
const centerX = canvas.width / 2;
const startY = 70;
const stepHeight = 120;
return stepsData.map((step, i) => ({
...step,
x: centerX,
y: startY + i * stepHeight,
width: Math.min(450, canvas.width * 0.85),
height: 90,
color: i % 2 === 0 ? colors.primary : colors.secondary
}));
}
function createParticle(from, to) {
return {
fromX: from.x,
fromY: from.y + from.height / 2,
toX: to.x,
toY: to.y - to.height / 2,
progress: Math.random(),
speed: 0.008 + Math.random() * 0.004
};
}
function draw() {
ctx.clearRect(0, 0, canvas.width, canvas.height);
const positions = getStepPositions();
// Draw connections
ctx.strokeStyle = colors.connection;
ctx.lineWidth = 3;
for (let i = 0; i < positions.length - 1; i++) {
const from = positions[i];
const to = positions[i + 1];
ctx.beginPath();
ctx.moveTo(from.x, from.y + from.height / 2);
ctx.lineTo(to.x, to.y - to.height / 2);
ctx.stroke();
// Arrow
const midY = (from.y + from.height / 2 + to.y - to.height / 2) / 2;
ctx.fillStyle = colors.connection;
ctx.beginPath();
ctx.moveTo(from.x - 6, midY - 4);
ctx.lineTo(from.x, midY + 6);
ctx.lineTo(from.x + 6, midY - 4);
ctx.closePath();
ctx.fill();
}
// Draw step boxes
positions.forEach((pos, i) => {
const x = pos.x - pos.width / 2;
const y = pos.y - pos.height / 2;
// Glow
ctx.shadowColor = pos.color;
ctx.shadowBlur = 20;
// Box with rounded corners
ctx.fillStyle = pos.color;
ctx.beginPath();
const radius = 8;
ctx.moveTo(x + radius, y);
ctx.lineTo(x + pos.width - radius, y);
ctx.quadraticCurveTo(x + pos.width, y, x + pos.width, y + radius);
ctx.lineTo(x + pos.width, y + pos.height - radius);
ctx.quadraticCurveTo(x + pos.width, y + pos.height, x + pos.width - radius, y + pos.height);
ctx.lineTo(x + radius, y + pos.height);
ctx.quadraticCurveTo(x, y + pos.height, x, y + pos.height - radius);
ctx.lineTo(x, y + radius);
ctx.quadraticCurveTo(x, y, x + radius, y);
ctx.closePath();
ctx.fill();
ctx.shadowBlur = 0;
// Border
ctx.strokeStyle = colors.accent;
ctx.lineWidth = 2;
ctx.stroke();
// Step number
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 18px JetBrains Mono, monospace';
ctx.textAlign = 'left';
ctx.textBaseline = 'middle';
ctx.fillText((i + 1) + '.', x + 16, pos.y);
// Title
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 16px JetBrains Mono, monospace';
ctx.textAlign = 'center';
ctx.fillText(pos.title, pos.x + 12, pos.y - 10);
// Description (if exists)
if (pos.desc) {
ctx.fillStyle = 'rgba(10, 10, 15, 0.8)';
ctx.font = '14px JetBrains Mono, monospace';
ctx.fillText(pos.desc, pos.x + 12, pos.y + 16);
}
});
// Update and draw particles
particles.forEach(p => {
p.progress += p.speed;
if (p.progress >= 1) {
p.progress = 0;
}
const ease = p.progress * p.progress * (3 - 2 * p.progress);
const x = p.fromX + (p.toX - p.fromX) * ease;
const y = p.fromY + (p.toY - p.fromY) * ease;
ctx.fillStyle = colors.particle;
ctx.shadowColor = colors.particle;
ctx.shadowBlur = 12;
ctx.beginPath();
ctx.arc(x, y, 4, 0, Math.PI * 2);
ctx.fill();
ctx.shadowBlur = 0;
});
time++;
requestAnimationFrame(draw);
}
// Initialize particles
const positions = getStepPositions();
for (let i = 0; i < positions.length - 1; i++) {
const p = createParticle(positions[i], positions[i + 1]);
p.progress = i * 0.3;
particles.push(p);
}
if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
draw();
} else {
// Static version
const positions = getStepPositions();
positions.forEach((pos, i) => {
const x = pos.x - pos.width / 2;
const y = pos.y - pos.height / 2;
ctx.fillStyle = pos.color;
ctx.beginPath();
ctx.roundRect(x, y, pos.width, pos.height, 8);
ctx.fill();
ctx.fillStyle = '#0a0a0f';
ctx.font = 'bold 16px JetBrains Mono';
ctx.textAlign = 'center';
ctx.fillText(pos.title, pos.x, pos.y);
});
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initWorkflow);
} else {
initWorkflow();
}
})();
</script>
<style>
.workflow-container {
background: var(--bg-0);
border: 1px solid var(--divider-color);
border-radius: 12px;
padding: 1rem;
margin: 1.5rem 0;
position: relative;
min-height: 550px;
}
.workflow-canvas {
width: 100%;
display: block;
}
@media (max-width: 768px) {
.workflow-container {
padding: 0.5rem;
}
}
</style>
<hr />
<h2 id="quick-start">Quick Start</h2>
<h3 id="installation">Installation</h3>
<p>Install directly from the GitHub marketplace—no cloning required:</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"> Add the marketplace (one-time setup)</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">/plugin</span></span><span class="z-meta z-function-call z-arguments z-shell"> marketplace add Cpicon/claude-code-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"> Install the plugin</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">/plugin</span></span><span class="z-meta z-function-call z-arguments z-shell"> install agent-team-creator</span>
</span></code></pre>
<p>That’s it. The plugin is ready to use immediately.</p>
<h3 id="first-commands">First Commands</h3>
<ol>
<li>Navigate to your project</li>
<li>Run <code>/generate-agent-team</code> to create your specialist agents</li>
<li>Start using your specialists: <code>Use the [agent-name] agent to...</code></li>
<li>Run <code>/generate-debugger</code> to create your project debugger</li>
<li>Use the debugger to investigate bugs: <code>Use the project-debugger agent to investigate...</code></li>
<li>Run <code>/generate-jira-task</code> to convert the debugging report to a ticket</li>
</ol>
<hr />
<h2 id="what-you-get">What You Get</h2>
<table><thead><tr><th>Command</th><th>Output</th><th>Value</th></tr></thead><tbody>
<tr><td><code>/generate-agent-team</code></td><td>3-6 specialist agents</td><td>Project-aware help for features, questions, debugging</td></tr>
<tr><td><code>/generate-debugger</code></td><td>Orchestrator agent</td><td>Coordinates specialists for complex investigations</td></tr>
<tr><td><code>/generate-jira-task</code></td><td>Jira ticket or markdown</td><td>Auto-finds latest report, creates actionable ticket</td></tr>
</tbody></table>
<h3 id="time-savings">Time Savings</h3>
<table><thead><tr><th>Task</th><th>Before</th><th>After</th></tr></thead><tbody>
<tr><td>Get project-aware help</td><td>N/A (generic only)</td><td>Immediate</td></tr>
<tr><td>Debug complex issues</td><td>Hours of investigation</td><td>Structured reports</td></tr>
<tr><td>Write Jira tickets</td><td>15-30 min</td><td>2-5 min</td></tr>
</tbody></table>
<hr />
<h2 id="try-it-yourself">Try It Yourself</h2>
<p>The plugin is open source and available on GitHub: <a href="https://github.com/Cpicon/claude-code-plugins">Cpicon/claude-code-plugins</a></p>
<p>Install it with two commands, run <code>/generate-agent-team</code>, and see what specialists emerge for your project.</p>
<h3 id="contributing-feedback">Contributing & Feedback</h3>
<p>Have ideas for improvements? Found a bug? The <a href="https://github.com/Cpicon/claude-code-plugins/issues">GitHub Issues</a> tab is where you can:</p>
<ul>
<li><strong>Request features</strong> — Suggest new capabilities or enhancements</li>
<li><strong>Report bugs</strong> — Help improve reliability by reporting issues you encounter</li>
<li><strong>Discuss improvements</strong> — Share ideas for plugin maintenance and development</li>
</ul>
<p>Your feedback shapes the plugin’s roadmap.</p>
<p>In <a href="/posts/claude-code-plugin-journey-part1/">Part 1</a>, I’ll show you how I built this plugin—the bugs I hit, the patterns I discovered, and why the architecture works the way it does.</p>
<hr />
<p><strong>Series Navigation:</strong></p>
<ul>
<li><strong>Part 0</strong> (You are here): What the plugin does and how to use it</li>
<li><strong>Part 1</strong>: <a href="/posts/claude-code-plugin-journey-part1/">The Hybrid Architecture Pattern</a> — Building the plugin</li>
<li><strong>Part 2</strong>: <a href="/posts/claude-code-plugin-journey-part2/">The Inheritance Paradox</a> — Research insights</li>
</ul>
Claude Code Plugin Journey Part 0: Agent Team Creator
What if you could point an AI at your project and have it generate specialists who actually understand your stack? Not generic assistants—agents that know your architecture, your patterns, your conventions.
That’s what agent-team-creator does. Let me show you the workflow.
…
Ml patterns design
2023-03-04T00:00:00+00:00
2023-03-04T00:00:00+00:00
Christian Picon Calderon
https://futurewithml.netlify.app/posts/chapter01-ml-pattern-design/
<h1 id="machine-learning-patterns"><strong>Machine Learning Patterns</strong></h1>
<p>Hello! First and foremost, I am embarking on a journey to highlight the main aspects presented in the book “<a href="https://www.oreilly.com/library/view/machine-learning-design/9781098115777/">Machine Learning Design Patterns</a>” This series is intended for machine learning engineers, data engineers, and data scientists. I will skip the explanation of basic terminology and focus on the nuances of facing the most common challenges when deploying machine learning models. The concept of patterns was introduced in the field of civil engineering/architecture by Christopher Alexander and five co-authors in the book titled “A Pattern Language” (1977). The main idea is that in a situation that happens recurrently, the pattern describes the core solution for this context and can be applied several times for this or similar ones. Here, we will explore the most general patterns that can be applied to machine learning system design.</p>
<span id="continue-reading"></span>
<hr />
<p>However we can’t proceed without defining the most common challenges in ML:</p>
<h2 id="data-quality"><strong>Data Quality</strong></h2>
<p>As you may know, in ML, “Garbage in, garbage out” applies, we must to check accuracy, completeness, consistency and timeliness of data</p>
<ul>
<li><strong>Data accuracy</strong> refers to the great and harness job that data engineers carry out. These engineers play an essential role in checking and handling typos, duplicate entries, measurement inconsistencies, missing features, and the particularities of unstructured data. For instance, duplicates can lead the model to assign more weight to those duplicated samples during learning. Also, incorrectly labeled training examples introduce bias in the model.</li>
<li><strong>Data Completeness</strong> ensures that your training data contains a varied representation of each label. It has the same effect on learning as the duplicated examples in the training data. To deal with data accuracy and completeness issues, you should perform an Exploratory Data Analysis (EDA). I encourage you to take a look at Pandas profile or Dtale to facilitate this analysis.</li>
<li><strong>Data consistency</strong> is another common aspect of machine learning. As you know, in supervised learning, you need labeled data, so here, we should ask for labeled data or start labeling it. The problem arises when labelers introduce bias, especially if the data requires domain knowledge (like in medical images). One common technique is to divide the work among a group of people, then have multiple people labeling each example and take the most commonly applied label (we will see this in-depth in Fairness Lens pattern design). Inconsistent features are also considered in this section as they can change over time (think about sensors with different offset of calibration).</li>
<li><strong>Timelines</strong> in data refers to the latency between the event occurrence and the addition to the database. It is more important in real-time machine learning applications, so in this case, you should record as much data as possible. For example, add a timestamp when a data point was generated and when it was added to the storage.</li>
</ul>
<h2 id="reproducibility"><strong>Reproducibility</strong></h2>
<p>Machine learning, unlike traditional software, has an inherent element of randomness. For example, matrix weights are initialized with random values, so the model converges to different outputs for different training executions. This can make it difficult to run comparisons across experiments. Fixing a value for seed can solve this issue.</p>
<p>Training an ML model involves several artifacts that need to be fixed to ensure reproducibility: the data used, the splitting mechanism used to generate datasets for training and validation, data preparation and model hyperparameters, and variables like batch size and learning rate schedule. It also applies to ML framework dependencies. Running ML workloads in containers and standardizing library versions can help ensure repeatability.</p>
<h2 id="data-drift"><strong>Data Drift</strong></h2>
<p>Data drift is an important concept in ML, especially in production. Data drift refers to the challenge of ensuring that your machine learning models remain relevant. To solve for drift, it’s essential to continually update your training dataset, retrain your model, and modify the weight your model assigns to particular groups of input data. Exploratory data analysis is a technique required here to understand the behavior of the data. For example, predicting the likelihood of a storm requires exploring the data available from the sensors for this scenario. In the next image, we can see that training a model on data before 2000 would lead to inaccurate predictions.</p>
<p><img src="https://futurewithml.netlify.app/posts/chapter01-ml-pattern-design/chap1_datadrift.png" alt="chap1_datadrift.png" /></p>
<blockquote>
<p>Copyright 2020 Google Inc. Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a> Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.</p>
</blockquote>
<h2 id="scale"><strong>Scale</strong></h2>
<p>You will encounter scaling challenges in different phases of your ML application, such as data collection and preprocessing, training, and serving. The size of your data willl dictate the tooling required for your solution. ML engineers are responsible for determining the neccesary infrastructure for a specific training job. If your dataset is big enough, model training can be time consuming and computationally expensive. In the context of model serving, the infrastructure required to support a team of data scientist getting predictions is entirely different from the infrastructure necessary to support a production model for millions of predictions by hour. We will see resilience and reproducibility in chapter 6 and 7.</p>
<h2 id="multiple-objectives-the-hidden-big-challenge"><strong>Multiple Objectives</strong> (The hidden big challenge)</h2>
<p>Model in production introduce a big challenge for a Ml engineer because the model is being used by different teams/roles in the organization. Having this scenario, we will see that defining a sucessful model is not easy. Each user/team/role has his own definition of a success model given his needs. For example, a data scientist/ML research is interest in minimize the loss function of the model. The project manager is interested in generate value by linking this model into the organization products, so here we start dealing with how to define a KPI that mimics the behavior of the loss function. Finally, the executive team is insterested in increase the revenue by using this model but they understand the KPI more that a mathematical function like loss function. As you saw, it is responsability of the data scientist work together with the project manager to define this KPI, then move this into executive team.</p>
<h2 id="thanks">Thanks</h2>
<p>Dear <a href="https://www.linkedin.com/in/jameshclrk/">James Clark</a>, I just wanted to take a moment to thank you for inspiring/helping me to start my own personal blog. Your blog, https://jamesclark.dev/, has been a source of inspiration for me, and your willingness to share your experiences and knowledge has been invaluable. Thanks to your guidance, I now have a platform to express my thoughts, share my ideas, and connect with others who share my passions. Your support and encouragement have been instrumental in helping me get started, and I am truly grateful for all that you have done for me. Thank you again for everything, James!</p>
Machine Learning Patterns
Hello! First and foremost, I am embarking on a journey to highlight the main aspects presented in the book “Machine Learning Design Patterns” This series is intended for machine learning engineers, data engineers, and data scientists. I will skip the explanation of basic terminology and focus on the nuances of facing the most common challenges when deploying machine learning models. The concept of patterns was introduced in the field of civil engineering/architecture by Christopher Alexander and five co-authors in the book titled “A Pattern Language” (1977). The main idea is that in a situation that happens recurrently, the pattern describes the core solution for this context and can be applied several times for this or similar ones. Here, we will explore the most general patterns that can be applied to machine learning system design.
…