🏛️ System Overview: The 5-Layer Cake
Forget single-agent prompting. This is a full system architecture with separation of concerns. Each layer handles one job well.
👤 Layer 1: User Interface
Where you interact — Telegram, CLI, or Web Dashboard. You describe what you want in natural language.
🧠 Layer 2: Orchestrator
The brain. Decomposes tasks, assigns agents, manages state, handles failures. This is where the magic happens.
🤖 Layer 3: Specialized Agents
Focused workers — Coder, Reviewer, Tester, Researcher. Each is an instance of Claude Code with a specific role.
💾 Layer 4: Memory and Context
Persistent knowledge — project memory, skills, session history, codebase index. Feeds context to agents.
🔄 The Agentic Workflow
Here's how a task flows through the system:
User Request (Telegram/CLI)
│
▼
┌─────────────────────────────────────────┐
│ ORCHESTRATOR │
│ 1. Parse request │
│ 2. Load project memory + skills │
│ 3. Decompose into subtasks │
│ 4. Create execution plan │
└─────────────┬───────────────────────────┘
│
┌─────────┼─────────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│RESEARCH│ │ CODER │ │ CODER │ ← Parallel execution
│ Agent │ │ Agent │ │ Agent │
└───┬────┘ └───┬────┘ └───┬────┘
│ │ │
└──────────┼──────────┘
▼
┌──────────────┐
│ TESTER │ ← Automated verification
│ Agent │
└──────┬───────┘
│
┌──────┴───────┐
▼ ▼
┌─────────┐ ┌──────────┐
│ PASS ✅ │ │ FAIL ❌ │──→ Back to Coder
└────┬────┘ └──────────┘
▼
┌──────────┐
│ REVIEWER │ ← Human-like review
│ Agent │
└────┬─────┘
▼
┌──────────┐
│ DEPLOYER │ ← Ship it
│ Agent │
└──────────┘
💾 Memory Architecture
The memory system is what separates this from "just using Claude Code." Three tiers:
🧠 Tier 1: Project Memory
- Architecture decisions
- Tech stack choices
- Coding conventions
- Known gotchas
Stored: MEMORY.md in project root
📚 Tier 2: Skills Library
- Reusable patterns
- API documentation
- Tool-specific guides
- Proven workflows
Stored: ~/.hermes/skills/
🕐 Tier 3: Session History
- Recent decisions
- Code changes made
- Test results
- User feedback
Stored: session transcripts
Key design decision: Memory is FILE-BASED, not database-based. This means any Claude Code session can read it, you can edit it manually, and Git tracks changes. Simple beats complex on a Mac Mini.
📁 Project Structure
The complete directory layout for the agentic system:
agentic-dev/
├── orchestrator.yaml
├── agents.yaml
├── memory/
│ ├── MEMORY.md
│ ├── DECISIONS.md
│ └── skills/
├── agents/
│ ├── orchestrator.py
│ ├── researcher.py
│ ├── coder.py
│ ├── tester.py
│ ├── reviewer.py
│ └── deployer.py
├── tools/
│ ├── context_manager.py
│ ├── git_ops.py
│ ├── test_runner.py
│ └── notifier.py
├── pipelines/
│ ├── feature.py
│ ├── bugfix.py
│ └── refactor.py
├── dashboard/
│ └── index.html
└── config/
├── models.yaml
└── quality.yaml
⚡ Model Routing Strategy
Not every task needs the most expensive model. Route intelligently:
🟢 Fast/Cheap (Haiku/GPT-4o-mini)
- Code formatting
- Simple file edits
- Test execution
- Documentation updates
- Search and indexing
🔴 Powerful (Sonnet/Opus)
- Architecture decisions
- Complex debugging
- Multi-file refactoring
- Code review
- Security analysis
Cost optimization: Route 70% of tasks to cheap models, 30% to powerful ones. Estimated savings: 60% vs using Sonnet for everything. Your Mac Mini handles the routing — no cloud dependency.
🔐 Quality Gates
Every piece of code passes through these gates before reaching you:
Code Generated by Coder Agent
│
▼
┌──────────────────────────┐
│ Gate 1: Syntax + Types │ → ruff, mypy, typescript
├──────────────────────────┤
│ Gate 2: Unit Tests │ → pytest, jest, go test
├──────────────────────────┤
│ Gate 3: Integration │ → docker-compose test env
├──────────────────────────┤
│ Gate 4: Security Scan │ → bandit, semgrep
├──────────────────────────┤
│ Gate 5: Code Review │ → Reviewer Agent
├──────────────────────────┤
│ Gate 6: Human Approval │ → You (optional for minor)
└──────────────────────────┘
│
▼
MERGED ✅