Agent Architecture and Roles

Relevant source files

The following files were used as context for generating this wiki page:

• src/agents/architect.ts
• src/agents/coder.ts
• src/agents/explorer.ts
• src/agents/docs.ts
• src/agents/sme.ts
• src/config/constants.ts
• src/hooks/system-enhancer.ts

The Agent Architecture in this project is a multi-agent swarm system designed to automate software development lifecycles. It utilizes a central orchestrator known as the Architect to manage a collection of specialized subagents, each restricted to specific domains such as coding, testing, documentation, and codebase exploration. The architecture emphasizes strict role boundaries, automated quality gates, and a standardized delegation protocol to ensure code integrity and project consistency.

Sources: src/agents/architect.ts:54-100, src/config/constants.ts:13-35

Core Agent Hierarchy

The system distinguishes between the central orchestrator and subagents. The Architect possesses the largest context window and strongest reasoning capabilities, while subagents are designed for atomic task execution within limited contexts.

The Architect (Orchestrator)

The Architect serves as the "brain" of the swarm. Its primary responsibilities include requirement digestion, task decomposition, and coordination of specialized agents. It is strictly prohibited from writing code directly, except as a fallback after repeated subagent failures.

Key Architect Responsibilities:

• Managing the project plan (.swarm/plan.md) and context (.swarm/context.md).
• Delegating implementation tasks to the Coder.
• Enforcing Tiered QA Gates (Stage A: Automated, Stage B: Agent Review).
• Facilitating SME (Subject Matter Expert) consultations.

Sources: src/agents/architect.ts:182-205, src/agents/architect.ts:258-290

Specialized Subagents

Subagents are categorized by their function within the pipeline:

Agent	Category	Primary Role
Explorer	Discovery	Factual codebase mapping and impact analysis.
Coder	Execution	Implementing code changes based on specific task IDs.
SME	Advisory	Providing deep domain-specific technical guidance.
Reviewer	QA	Evaluating code for correctness, security, and style.
Test Engineer	QA	Generating and executing automated and adversarial tests.
Docs	Support	Synthesizing external documentation and design specs.

Sources: src/config/constants.ts:13-35, src/agents/architect.ts:553-565

Workflow and Delegation Logic

The system follows a structured workflow where the Architect transitions through different "Modes" based on project state.

Operational Modes

The Architect detects the required mode by evaluating the environment, such as the existence of a specification or the status of tasks in the project plan.

Delegation Protocol

Communication between agents is handled via the Task tool. A delegation must follow a mandatory format that includes a TASK description, relevant FILES, and SKILLS propagation.

Delegation Requirements:

1. Declare Scope: The Architect must call declare_scope before delegating to a Coder to permit file writes.
2. One Task per Call: Coder delegations cannot be batched; each task must go through individual QA gates.
3. Skills Propagation: Skills (e.g., engineering-conventions) are injected into subagent prompts to maintain consistency.

Sources: src/agents/architect.ts:211-255, src/agents/architect.ts:586-610

Specialized Agent Analysis

Explorer: The Factual Mapper

The Explorer is strictly a factual reporter. It scans structure, searches patterns, and reports complexity indicators. It operates in multiple modes:

• Standard: Codebase structural analysis.
• Integration Impact: Analyzing how changes to exports affect consumers.
• Documentation Discovery: Indexing .md files into .swarm/doc-manifest.json.

Sources: src/agents/explorer.ts:16-52, src/agents/explorer.ts:127-158

Coder: Implementation Specialist

The Coder implements changes while adhering to an "Anti-Hallucination Protocol." It must verify all import paths via search tools before usage.

Coder Constraints:

• Defensive Coding: Prohibition of any types, empty catch blocks, and platform-specific path separators.
• Reuse Scan: Mandatory semantic search for existing utilities before creating new ones.
• Write Block Protocol: If a file write is blocked by scope, the Coder must stop and request the Architect to re-scope.

Sources: src/agents/coder.ts:60-95, src/agents/coder.ts:114-142, src/agents/coder.ts:192-220

SME (Subject Matter Expert)

The SME provides guidance calibrated by confidence levels (HIGH/MEDIUM/LOW). It follows a research protocol involving framing, constraints analysis, and risk identification.

Quality Assurance and Gating

The architecture enforces a Tiered QA Gate pipeline that must pass for every task before it is marked complete.

Tiered QA Pipeline

1. Stage A (Automated): Includes syntax_check, lint, secretscan, sast_scan, and build_check.
2. Stage B (Agent-Led): Mandatory review by the Reviewer and verification by the Test Engineer.
3. Adversarial Testing: Specialized Test Engineer pass focused on attack vectors (e.g., injection, auth bypass).

Sources: src/agents/architect.ts:394-445, src/agents/architect.ts:672-690

Council Workflow

For high-impact changes or phase completions, the Architect convenes a Phase Council. This involves parallel dispatch of five agents (Critic, Reviewer, SME, Test Engineer, Explorer) to provide a holistic review of the phase work.

Sources: src/agents/architect.ts:1115-1155

Summary

The project's Agent Architecture is a highly structured environment where the Architect acts as a controller, ensuring that specialized subagents operate within strict safety and functional boundaries. By combining automated tool gates with multi-agent reviews and domain-specific expertise, the system maintains high code quality and architectural integrity throughout the automated development process.

Sources: src/agents/architect.ts:54-100, src/agents/coder.ts:1-25