AI: Add Multiagent Workflows with Orchestrator

[jlukic]

This adds a new multiagent workflow for the repo including including subagents and an orchestrator agent which can be used together to create components and update docs.

This was originally implemented as a separate MCP server serving subinstances using spawn to create new processes served with claude mcp serve. This approach was eventually modified to instead use a single agent with the Task tool which is more memory efficient and also provides better UX experience (as tool use through mcp is kind of janky right now with permissions).

Feature Proposal :

---

MCP Agent Architecture for Semantic UI

Overview

This proposal outlines the implementation of a specialized agent system using Model Context Protocol (MCP) to handle complex development workflows in the Semantic UI codebase. The system addresses the need for domain-specific expertise while maintaining coordination across different aspects of development.

Problem Statement

The Semantic UI codebase consists of multiple specialized packages (Component, Query, Templating, Reactivity, Utils) each with distinct patterns, APIs, and architectural concerns. A single agent attempting to handle all domains simultaneously suffers from:

1. Context dilution - Unable to maintain deep expertise across all domains
2. Pattern conflicts - Different packages have different conventions that conflict
3. Quality inconsistency - Lack of specialized focus on testing, types, documentation
4. Coordination overhead - No systematic way to ensure cross-package compatibility

Proposed Solution

Multi-Agent Architecture

Domain-Specific Implementation Agents (Package Experts):

• Component Implementation Agent - Web component lifecycle, Shadow DOM, settings/state patterns
• Query Implementation Agent - DOM traversal, element selection, chaining patterns
• Templating Implementation Agent - AST compilation, expression evaluation, reactive binding
• Reactivity Implementation Agent - Signals, reactions, dependency tracking
• Utils Implementation Agent - Utility functions, performance optimization, type checking

Cross-Domain Process Agents (Quality Specialists):

• Types Agent - TypeScript patterns, overloads, developer experience (works across ALL packages)
• Testing Agent - Testing strategies, edge cases, quality assurance (works across ALL packages)
• Documentation Agent - API communication, examples, user experience (works across ALL packages)
• Releasing Agent - Branching, commit messages, release notes
• Build Tools Agent - Build processes, internal packages, npm scripts

Main Orchestration Agent:

• Coordinates workflow execution
• Manages context passing between agents
• Resolves conflicts between agent recommendations

Sequential Workflow Pattern

Unlike parallel execution, the workflow is inherently sequential:

Implementation → Testing → Types → Documentation → Integration → Releasing

Each agent builds upon the previous agent's work with full context accumulation.

Argumentative Theory Implementation

Following Mercier's Argumentative Theory, agents provide specialized perspectives that create productive tension:

Domain vs Domain Conflicts:

• Component Agent: "This API should follow component lifecycle patterns"
• Query Agent: "But this breaks Query chaining conventions"

Process vs Domain Conflicts:

• Types Agent: "This API signature will confuse TypeScript users"
• Component Agent: "But this is how the component architecture works"

Process vs Process Conflicts:

• Documentation Agent: "This API is too complex for users"
• Types Agent: "But without these overloads, there's no type safety"

Technical Implementation

MCP Server Architecture

Location: /ai/mcp/agents-server.js

The MCP server provides tools that spawn Claude Code instances as specialized sub-agents:

// Main orchestrator calls:
const result = await mcp_query_implementation_agent({
  task: "Implement Query.data() method",
  context: accumulated_context
});

// Sub-agent returns structured result
// Main agent continues with next step

Agent Context System

Location: /ai/agents/{domain|process}/[agent-name]/context.md

Each agent has specialized context files that define:

• Domain expertise and patterns
• Argumentative stance and challenges
• Success criteria and quality metrics
• Tool usage strategies

Communication Protocol

Sequential Context Accumulation:

{
  "original_task": "Add Query.data() method",
  "implementation": {
    "files_changed": ["query.js"],
    "patterns_used": ["getter/setter", "chaining"],
    "concerns": ["performance with large datasets"]
  },
  "testing": {
    "test_files": ["query.test.js"],
    "coverage_areas": ["single element", "multiple elements"],
    "performance_benchmarks": "established"
  }
  // ... continues accumulating
}

Structured Agent Responses:

{
  "status": "complete|needs_input|blocked",
  "deliverables": {
    "files_changed": ["path/to/file.js"],
    "summary": "work completed"
  },
  "handoff_context": {
    "for_next_agent": "key information",
    "concerns": ["issues raised"],
    "recommendations": ["next steps"]
  },
  "questions": [
    {
      "for_agent": "types_agent",
      "question": "Does this API signature work?"
    }
  ]
}

Files and Directories

/ai/
├── agents/
│   ├── domain/
│   │   ├── component/context.md
│   │   ├── query/context.md
│   │   ├── templating/context.md
│   │   ├── reactivity/context.md
│   │   └── utils/context.md
│   └── process/
│       ├── testing/context.md
│       ├── types/context.md
│       ├── documentation/context.md
│       ├── integration/context.md
│       ├── releasing/context.md
│       └── build-tools/context.md
├── mcp/
│   ├── agents-server.js
│   └── package.json (to be created)
└── proposals/
    └── mcp-agent-architecture.md (this file)

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
semantic-next	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 1, 2025 9:24pm