{"slug": "building-with-agents-what-actually-changes-when-you-delegate-to-a-swarm", "title": "Building with Agents: What Actually Changes When You Delegate to a Swarm", "summary": "Shift from the common \"autocomplete at conversational scale\" workflow, where engineers manually copy-paste AI outputs, to a more advanced \"dual-agent architecture.\" This system uses specialized AI agents (Claude and Gemini) that operate against a shared, persistent \"vault\" of structured knowledge and a SQLite-based semantic memory, enabling cross-session continuity and collaborative problem-solving. The architecture enforces explicit knowledge ownership and structured protocols, allowing agents to inherit findings from each other and avoid redundant work.", "body_md": "# AI-Native Development with a Dual-Agent Architecture: A Technical Account\n\n**Author:** Abhinav Pangaria\n**Date:** May 2026\n\n\n\n---\n\n# The Wrong Mental Model\n\nMost engineers who describe themselves as “using AI heavily” mean something narrower than that phrase implies.\n\nThey write a prompt, read the output, paste what looks right into their editor, fix what breaks, and repeat.\n\nThis is autocomplete at conversational scale. It is not a fundamentally different mode of working. It is the same lone-engineer workflow with a faster drafting tool in the loop. \n\nThe productivity ceiling of that pattern is real and arrives quickly. It appears when:\n\n* The problem exceeds one agent’s context window\n* A task requires sustained research alongside implementation\n* Decisions must persist beyond a single session\n* Cross-session continuity becomes necessary\n* Architecture understanding spans multiple domains simultaneously\n\nWhat follows is a different operational model: a dual-agent architecture refined across 18 months of production projects and hackathons, where specialized AI systems operate against shared memory, structured protocols, and persistent knowledge infrastructure. \n\n---\n\n# System Overview\n\nThe architecture consists of four tightly integrated components:\n\n| Component       | Responsibility                        |\n| --------------- | ------------------------------------- |\n| Claude Code     | Implementation agent                  |\n| Gemini CLI      | Research and long-context agent       |\n| Obsidian Vault  | Shared persistent knowledge substrate |\n| agent-brain MCP | Semantic memory and retrieval layer   |\n\n\n\nThese systems are not loosely coupled. They share state, communicate through explicit schemas, and maintain enforced role boundaries so each agent operates only within domains where it is structurally strongest. \n\n---\n\n# The Obsidian Vault as Shared Knowledge Substrate\n\nThe vault is not a note-taking tool. It functions as the persistent source of truth across:\n\n* Sessions\n* Agents\n* Projects\n* Ecosystems\n* Architectural decisions\n\nBoth Claude Code and Gemini interact with the vault through the `brain-vault MCP server`, which exposes filesystem operations as callable tools. \n\n---\n\n# Vault Structure\n\n```text\n~/Documents/Brain/\n├── 00-Identity/\n│   ├── USER.md\n│   ├── MODES.md\n│   ├── STACK.md\n│   ├── agent-configs-final/\n│   │   ├── CLAUDE.md\n│   │   ├── GEMINI.md\n│   │   └── PERPLEXITY.md\n│   └── agent-skills/\n│       ├── INDEX.md\n│       ├── session-open/\n│       ├── session-close/\n│       ├── code-plan/\n│       ├── error-memory/\n│       └── ...\n│\n├── 10-Projects/\n│   └── [project-slug]/\n│       ├── CLAUDE.md\n│       ├── GEMINI.md\n│       ├── HANDOFF.md\n│       ├── PROJECT-STATE.md\n│       ├── decision-log.md\n│       ├── session-log.md\n│       ├── specs/\n│       ├── research/\n│       └── skills/\n│\n├── 20-Areas/\n│   └── ecosystems/\n│       ├── circle/\n│       ├── xrpl/\n│       ├── stellar/\n│       └── midnight/\n│\n├── 30-Resources/\n│\n├── 40-Memory/\n│   ├── agent-brain.db\n│   ├── decision-log.md\n│   ├── error-log.md\n│   └── learned-patterns.md\n│\n└── 50-Archive/\n```\n\n\n\n---\n\n# Knowledge Hierarchy and the Non-Duplication Rule\n\nThe system enforces explicit ownership of knowledge.\n\nCanonical ecosystem facts exist once, under:\n\n```text\n20-Areas/ecosystems/[name]/\n```\n\nProjects reference these notes using Obsidian backlinks:\n\n```text\n[[folder/filename]]\n```\n\nThey do not duplicate or paraphrase shared knowledge. \n\nThis matters because both agents consume the same vault.\n\nExample:\n\n* Gemini researches ARC chain behavior\n* Findings are written into:\n\n```text\n20-Areas/ecosystems/circle/circle-overview.md\n```\n\n* Claude automatically inherits those findings in later sessions without re-fetching documentation\n\nThe vault becomes a shared persistent memory substrate rather than ephemeral conversational context. \n\n---\n\n# Vault Write Constraints\n\nEvery new note requires:\n\n* YAML frontmatter\n* Minimum two backlinks\n* Source attribution\n* Ecosystem or project association\n* Tag metadata\n\nThese constraints are enforced through the `vault-write` skill shared by both agents. \n\n---\n\n# The Two-Layer Memory Architecture\n\nThe architecture separates memory into:\n\n1. Human-readable structured knowledge\n2. Machine-queryable semantic memory\n\n---\n\n# Layer 1 — agent-brain (Semantic Memory)\n\n`agent-brain` is a custom MCP server located at:\n\n```text\n~/Documents/Brain/agent-infra/\n```\n\nIt wraps a SQLite-based semantic memory system with:\n\n| Feature       | Implementation                           |\n| ------------- | ---------------------------------------- |\n| Embeddings    | sentence-transformers/all-MiniLM-L6-v2   |\n| Vector Size   | 384 dimensions                           |\n| Search        | FTS5 + cosine similarity reranking       |\n| Storage Types | technical, error, workflow, meta, growth |\n| Scope Flags   | agent, project, validated                |\n\n\n\nBoth Claude and Gemini connect to the same database:\n\n* Claude: `~/.claude/.mcp.json`\n* Gemini: `~/.gemini/settings.json`\n\nThe MCP server exposes:\n\n* 9 memory operations\n* 4 Gemini bridge tools\n\n\n\n---\n\n# Operational Memory Flow\n\nBefore starting complex work:\n\n1. Claude queries `memory_search`\n2. Prior solutions are retrieved\n3. Validated fixes and architectural decisions are reused\n4. Repeated debugging cycles are avoided\n\nAfter meaningful work:\n\n* Agents write validated patterns back into shared memory\n* Scope is controlled via:\n\n  * `agent=\"both\"`\n  * `agent=\"claude\"`\n  * `agent=\"gemini\"`\n\n\n\n---\n\n# Layer 2 — claude-mem (Episodic Memory)\n\n`claude-mem` records session-level observations automatically through lifecycle hooks:\n\n* SessionStart\n* PostToolUse\n* Stop\n* PreCompact\n\n\n\nThis layer tracks:\n\n* What happened\n* Which files were accessed\n* Task progression\n* Session events\n\nThe distinction is explicit:\n\n| System      | Purpose       |\n| ----------- | ------------- |\n| agent-brain | What is true  |\n| claude-mem  | What happened |\n\n\n\n---\n\n# Role Boundaries\n\nThe architecture works because the agents are not treated as interchangeable. \n\n## Claude Code Responsibilities\n\nClaude handles:\n\n* Code generation\n* Code editing\n* Sequential execution\n* Tool orchestration\n* Error diagnosis\n* Live system interaction\n* Session state management\n\n\n\n---\n\n## Gemini Responsibilities\n\nGemini handles:\n\n* Large-document synthesis\n* SDK digestion\n* Architecture review\n* Ecosystem research\n* Security audits\n* Cross-source synthesis\n\n\n\n---\n\n# Enforced Behavioral Constraints\n\nRole boundaries are encoded as workflow memory entries.\n\nExample constraints:\n\n> “Do not do market research (Perplexity has live web). Do not read full SDKs mid-session (Gemini is better for long-context doc reading). Do not design architecture. Do not run full codebase security audit.”\n\nThese are persistent retrieval-enforced rules, not informal guidelines. \n\n---\n\n# Dual-Lane Communication Architecture\n\nThe agents communicate through two distinct coordination lanes:\n\n| Lane             | Purpose                 |\n| ---------------- | ----------------------- |\n| MCP Bridge Tools | Synchronous interaction |\n| File Protocol    | Asynchronous delegation |\n\n---\n\n# Lane 1 — MCP Bridge Tools\n\nThe MCP server exposes four bridge tools:\n\n| Tool                   | Function                       |\n| ---------------------- | ------------------------------ |\n| `gemini_research`      | Structured research delegation |\n| `gemini_review`        | Architecture/code review       |\n| `gemini_read_context`  | Large-document summarization   |\n| `gemini_explore_vault` | Semantic vault exploration     |\n\n\n\nBridge calls return structured JSON rather than prose.\n\nExample response structures:\n\n```json\n{\n  \"summary\": \"...\",\n  \"findings\": [...],\n  \"confidence\": 0.94,\n  \"sources\": [...]\n}\n```\n\nor\n\n```json\n{\n  \"verdict\": \"...\",\n  \"issues\": [...],\n  \"suggestions\": [...],\n  \"confidence\": 0.88\n}\n```\n\nClaude immediately commits validated findings back into semantic memory after retrieval. \n\n---\n\n# Lane 2 — File Protocol\n\nWhen implementation encounters high-context blockers:\n\n1. Claude writes `RESEARCH-REQUEST.md`\n2. Context is compacted\n3. Gemini fulfills the request asynchronously\n4. Gemini writes `RESEARCH-RESPONSE.md`\n5. Claude resumes implementation\n\n\n\n---\n\n# RESEARCH-REQUEST.md Schema\n\n```markdown\n- Context\n- Blocker\n- Attempted Solutions\n- Git State\n- Specific Question\n- Files Gemini Should Read\n```\n\n---\n\n# RESEARCH-RESPONSE.md Schema\n\n```markdown\n- Direct Answer\n- Evidence Citations\n- Copy-Paste Ready Code\n- Numbered Next Steps\n- Implementation-Ready: YES/NO\n```\n\nThis protocol eliminates ambiguous state reconstruction between agents. \n\n---\n\n# Skills and Plugins\n\nSkills are shared behavioral protocols stored in:\n\n```text\n~/.agents/skills/\n```\n\nThey are Markdown-defined execution frameworks activated contextually rather than globally. \n\n---\n\n# Global Skills\n\n| Skill                  | Trigger                       |\n| ---------------------- | ----------------------------- |\n| session-open           | Session initialization        |\n| session-close          | Session termination           |\n| code-plan              | Before implementation         |\n| anti-hallucination     | Before architecture execution |\n| error-memory           | On failures or build breaks   |\n| research-method        | Claude research tasks         |\n| research-method-gemini | Gemini research tasks         |\n| codebase-audit         | Full security review          |\n| vault-write            | Vault modifications           |\n\n\n\n---\n\n# Project-Scoped Skills\n\nProject-specific skills live under:\n\n```text\n10-Projects/[slug]/skills/\n```\n\nThese contain:\n\n* Exact API patterns\n* Error handling logic\n* Adapter references\n* Integration constraints\n* Operational playbooks\n\nExample skills:\n\n* `use-circle-wallets`\n* `bridge-stablecoin`\n* `swap-tokens`\n* `use-arc`\n* `use-developer-controlled-wallets`\n\n\n\nThis eliminates repeated rediscovery of implementation knowledge.\n\n---\n\n# Context Window Asymmetry\n\nThe architecture intentionally exploits the asymmetry between models.\n\n## Claude Code\n\nOptimized for:\n\n* Precision\n* Incremental execution\n* Tight context discipline\n* Active token budgeting\n* Focused implementation\n\n## Gemini\n\nOptimized for:\n\n* Massive context ingestion\n* Full SDK visibility\n* Multi-document synthesis\n* Codebase-wide review\n* Cross-specification reasoning\n\n\n\nThe operational pattern becomes:\n\n* Claude implements selectively\n* Gemini performs wide-aperture analysis\n* Structured findings return to Claude as compact actionable state\n\n\n\n---\n\n# Session Continuity via HANDOFF.md\n\nEvery project maintains a continuously overwritten:\n\n```text\nHANDOFF.md\n```\n\nWritten by `session-close`, it contains:\n\n* Current implementation state\n* Open blockers\n* Git status\n* Decisions made\n* Next execution steps\n\n\n\nAt session start:\n\n* `session-open` loads the handoff\n* Work resumes from prior state\n* Append-only logs preserve historical traceability\n\n\n\nThe handoff becomes the baton transferred between:\n\n* Sessions\n* Modes\n* Agents\n\n---\n\n# Tesseract Protocol: Concrete Demonstration\n\nThe architecture was stress-tested during the Tesseract Protocol hackathon project:\n\nScope delivered in 48 hours:\n\n* Six ZK circuits\n* Merkle tree implementation\n* CLI integration harness\n* React frontend\n* Midnight Network indexer integration\n\n\n\n---\n\n# Explicit Task Decomposition\n\n| Responsibility            | Owner         |\n| ------------------------- | ------------- |\n| ZK circuit specifications | Human         |\n| Circuit implementation    | Claude        |\n| Integration tests         | Claude        |\n| Ecosystem research        | Gemini        |\n| Debugging                 | Collaborative |\n| Architectural decisions   | Human         |\n\n\n\nThe non-delegable category was architecture:\n\n* Trust boundaries\n* State ownership\n* Propagation tradeoffs\n* Reliability constraints\n* “Good enough” judgment\n\n\n\nThe swarm handles execution. Human bandwidth is reserved for irreducible judgment problems.\n\n---\n\n# Infrastructure Summary\n\n```text\n~/.claude/.mcp.json\n~/.gemini/settings.json\n~/.agents/skills/\n\n~/Documents/Brain/\n  agent-infra/\n    brain/\n      memory.py\n      embeddings.py\n      bridge.py\n      db.py\n    mcp_server.py\n\n40-Memory/agent-brain.db\n```\n\n\n\nBoth agents register the same MCP server. Memory ownership is shared and immediately visible across systems. \n\n---\n\n# What This Is Not\n\nThis is not an autonomous agent loop.\n\nThere is:\n\n* No orchestrator selecting agents\n* No unsupervised execution chain\n* No removal of human oversight\n\nThe human:\n\n* Makes every delegation decision\n* Reviews every important output\n* Owns all architectural judgment\n\n\n\nThe architecture does not reduce human importance. It compresses execution overhead so human cognition is reserved for tradeoffs, judgment, and system-level reasoning.\n\nThe core operational question becomes:\n\n> Which parts of this problem require human judgment, and which parts can be specified clearly enough to delegate?\n\nThat distinction is the defining skill of AI-native development. \n", "url": "https://wpnews.pro/news/building-with-agents-what-actually-changes-when-you-delegate-to-a-swarm", "canonical_source": "https://gist.github.com/18Abhinav07/ab85e7515d9d1694044fee734ed89269", "published_at": "2026-05-22 05:15:23+00:00", "updated_at": "2026-05-22 05:41:08.516450+00:00", "lang": "en", "topics": ["artificial-intelligence", "large-language-models", "developer-tools", "enterprise-software"], "entities": ["Abhinav Pangaria"], "alternates": {"html": "https://wpnews.pro/news/building-with-agents-what-actually-changes-when-you-delegate-to-a-swarm", "markdown": "https://wpnews.pro/news/building-with-agents-what-actually-changes-when-you-delegate-to-a-swarm.md", "text": "https://wpnews.pro/news/building-with-agents-what-actually-changes-when-you-delegate-to-a-swarm.txt", "jsonld": "https://wpnews.pro/news/building-with-agents-what-actually-changes-when-you-delegate-to-a-swarm.jsonld"}}