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