AI Agent Swarm & Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The AI Agent Swarm & Workflow system in KnowledgeVault (RAGAPPv3) is a specialized operational framework designed for deep codebase analysis, auditing, and autonomous remediation. It leverages multiple specialized AI agent roles—including Explorers, SMEs (Subject Matter Experts), Coders, and Critics—to perform systematic, multi-step tasks that ensure software quality and architectural integrity.
This system operates as a "Swarm Mode" that can be enabled for AI coding agents such as Codex, Claude Code, and opencode-swarm. When active, the workflow prioritizes quality as the primary success metric, utilizing parallel subagents to conduct disjoint investigations and reviews without the typical time pressure of standard conversational AI interactions.
Sources: AGENTS.md:1-12, CLAUDE.md:1-20
Swarm Operational Architecture
The swarm architecture is structured around specialized roles that interact through a defined multi-step protocol. This protocol is initiated via the codebase-review-prompt.md and managed by a central Architect role.
Specialized Agent Roles
| Role | Responsibility |
|---|---|
| Architect | Central orchestrator that delegates work, reads inventory, and approves plans. |
| Explorer | Responsible for breadth; performs full codebase ingestion and builds inventory. |
| SME | Researches domain-specific best practices (security, framework, testing). |
| Coder | Executes implementation tasks defined in the implementation plan. |
| Reviewer | Validates candidate findings or implementation quality. |
| Critic | Provides final challenge to confirmed findings or high-impact conclusions. |
Sources: codebase-review-prompt.md:11-20, CLAUDE.md:10-18
Workflow Lifecycle
The swarm workflow follows a rigorous 7-step process to move from initial exploration to final implementation approval.
The diagram above illustrates the linear progression of the Swarm Workflow from exploration to user delivery.
Sources: codebase-review-prompt.md:22-261
Execution Phases
Phase 0: Codebase Inventory (Explorer)
The Explorer must read every file in the project to build a complete inventory stored at .swarm/codebase-inventory.md. This includes identifying the tech stack, file inventory, module structure, and observed coding patterns.
Sources: codebase-review-prompt.md:22-60
Phase 1: Deep Analysis & Categorization
Agents perform targeted reads across seven critical categories to identify specific issues grounded in file paths and line numbers.
| Category | Focus Area |
|---|---|
| Category 1 | Broken, missing, or incomplete code (stubs, TODOs, empty bodies). |
| Category 2 | Security and data handling (secrets, validation gaps, injections). |
| Category 3 | Cross-platform and environment issues (hardcoded paths, shell syntax). |
| Category 4 | Stale comments and documentation drift. |
| Category 5 | AI-generated code smells (unnecessary wrappers, excessive defensive code). |
| Category 6 | Technical debt and architecture (circular dependencies, duplicated logic). |
| Category 7 | Performance and enhancement opportunities (N+1 queries, caching). |
Sources: codebase-review-prompt.md:62-212
Phase 2: Implementation Planning
Findings are converted into an implementation plan (.swarm/plan.md) divided into four priority phases:
- Critical: Security vulnerabilities and blockers.
- Major: Structural fixes with cascading effects.
- Refactoring: Remaining major findings and cross-cutting concerns.
- Minor: Enhancements and documentation cleanup.
Sources: codebase-review-prompt.md:243-261
Technical Governance & Standards
The swarm workflow is governed by strict "Non-negotiables" and behavioral guidelines to prevent common AI coding mistakes.
Behavioral Guidelines
- Quality over Speed: There is no time pressure in Swarm Mode; quality is the only metric.
- Separation of Concerns: Contexts that "invent" findings (Explorer/SME) cannot "approve" them; a separate Reviewer/Critic pass is required.
- Positive Evidence: No approval is granted without positive evidence of what was checked.
- Surgical Changes: Agents must touch only what is necessary and match existing project styles.
Sources: CLAUDE.md:6-18, CLAUDE.md:37-43
Repository Context Files
The swarm relies on specific local files to maintain state and knowledge across sessions:
.swarm/context.md: Stores prior findings, lessons, and SME guidance..swarm/knowledge.jsonl: Captures known issues and project-specific intelligence..claude/session/swarm-mode.md: An existence-based flag that enables swarm-specific behaviors.
Sources: codebase-review-prompt.md:5-9, CLAUDE.md:1-4
Summary
The AI Agent Swarm & Workflow provides a robust, multi-layered mechanism for maintaining the KnowledgeVault codebase. By enforcing a separation between discovery, implementation, and criticism, the system ensures that AI-driven changes are accurate, secure, and idiomatic to the project's established patterns. This workflow is particularly critical given the project's complex tech stack involving Python 3.11, FastAPI, and a React-based frontend.
Sources: AGENTS.md:5-15, CONTRIBUTING.md:5-15