# Agent System Guide

> Last Verified: 2026-02-17 | Owner: John

# Agent System Guide — Consolidated

**Last Updated:** 2026-02-10
**Consolidated From:** 7 original documents (2026-01-28 to 2026-02-09)
**Maintained By:** John (AI Director)

---

## Table of Contents

1. [Overview](#overview)
2. [Architecture](#architecture)
3. [Agent Roster](#agent-roster)
4. [Delegation Guidelines](#delegation-guidelines)
5. [Multi-Agent Orchestration](#multi-agent-orchestration)
6. [Agent Teams (Parallel Execution)](#agent-teams-parallel-execution)
7. [Tools & Commands](#tools--commands)
8. [Best Practices](#best-practices)
9. [Cost Control](#cost-control)
10. [Related Documents](#related-documents)

---

## Overview

BasicAS Group operates three types of agents:

1. **John (Orchestrator)** - AI Director, primary coordinator (Claude Opus)
2. **Claude Subagents** - Builder and Validator (Claude Sonnet)
3. **Ollama Agents** - Advisory/research agents (local LLM, text-only)

**John's Role:** Alem's right hand. Delegates work to specialized agents when their expertise is needed. Manages 15+ specialized agents across teams and projects.

---

## Architecture

### Three-Layer System

```
┌─────────────────────────────────────────────┐
│              ALAI Orchestration              │
├─────────────────────────────────────────────┤
│                                             │
│  ┌─── Persistence Layer (GOTCHA) ────────┐  │
│  │  MC Tasks (210+ tasks, cross-session) │  │
│  │  HiveMind (683+ entries, SQLite)      │  │
│  │  SESSION-STATE.md                     │  │
│  │  GOTCHA Framework (6 layers)          │  │
│  └───────────────────────────────────────┘  │
│                    │                         │
│                    ▼                         │
│  ┌─── Execution Layer (HYBRID) ──────────┐  │
│  │                                       │  │
│  │  John (Opus) ── Primary Orchestrator  │  │
│  │    │                                  │  │
│  │    ├── Builder (Sonnet) ─┐            │  │
│  │    ├── Builder (Sonnet) ─┤ Parallel   │  │
│  │    ├── Builder (Sonnet) ─┤ via Agent  │  │
│  │    ├── Builder (Sonnet) ─┘ Teams      │  │
│  │    │                                  │  │
│  │    └── Validator (Sonnet) ── Review   │  │
│  │                                       │  │
│  └───────────────────────────────────────┘  │
│                    │                         │
│  ┌─── Advisory Layer (OLLAMA) ───────────┐  │
│  │  15 agents (text only, no execution)  │  │
│  │  Managed by agent-scheduler.js        │  │
│  └───────────────────────────────────────┘  │
│                                             │
│  ┌─── Monitoring (T-MUX) ────────────────┐  │
│  │  Each agent = own tmux pane           │  │
│  │  Visual real-time monitoring          │  │
│  │  Prefix: Ctrl+A                       │  │
│  └───────────────────────────────────────┘  │
│                                             │
└─────────────────────────────────────────────┘
```

### GOTCHA Framework (Foundation)

Every agent operates within the GOTCHA 6-layer framework:

**GOT (Engine):**
- **Goals** - What needs to happen (specs/, rules/)
- **Orchestration** - John coordinates execution
- **Tools** - Deterministic scripts (tools/)

**CHA (Context):**
- **Context** - Domain knowledge (context/)
- **Hard Prompts** - Instruction templates (prompts/)
- **Args** - Behavioral config (config/)

**Principle:** AI error is cumulative (90%^5 = 59%). Reliability comes from tools, flexibility from LLM.

---

## Agent Roster

### John (Primary Orchestrator)
- **Model:** Claude Opus 4.6
- **Role:** AI Director, right hand to Alem
- **Tools:** Full system access (Read, Write, Edit, Bash, Glob, Grep, Task, etc.)
- **Responsibilities:**
  - Task delegation and coordination
  - System architecture decisions
  - Security and compliance enforcement
  - Mission Control management
  - HiveMind knowledge curation

### Claude Subagents (Execution)

#### Builder
- **Model:** Claude Sonnet 4.5
- **Role:** Implementation agent (one task, then dies)
- **Tools:** Read, Write, Edit, Bash, Glob, Grep, Task
- **Protocol:** ~/.claude/agents/builder.md
- **Lifecycle:** Ephemeral (30 turns max)
- **GOTCHA Compliance:** Mandatory checklist before code
- **Anti-Hallucination:** Enforced via ~/system/rules/agent-anti-hallucination.md

#### Validator
- **Model:** Claude Sonnet 4.5
- **Role:** Verification agent (one task, then dies)
- **Tools:** Read, Bash, Glob, Grep (READ-ONLY, no Write/Edit)
- **Protocol:** ~/.claude/agents/validator.md
- **Lifecycle:** Ephemeral (20 turns max)
- **GOTCHA Compliance:** Checklist + compliance verification
- **Anti-Hallucination:** Enforced

### Ollama Agents (Advisory)

**Location:** ~/system/agents/identities/
**Runtime:** Ollama (local LLM, Mac Studio M3 Ultra)
**Execution:** node ~/system/tools/agent-runner.js <agent> --task "X"
**Output:** Text only (no file operations, no execution)

#### SnowIT Team (8 agents)

| Agent | File | Role | Specialty |
|-------|------|------|-----------|
| **Amina Hadžić** | amina.md | PM | Project oversight, client escalations |
| **Emir Delić** | emir.md | Scrum Master | Sprint ceremonies, team facilitation |
| **Lejla Kovačević** | lejla.md | Tech Lead | Architecture, technical feasibility |
| **Tarik Begović** | tarik.md | QA Lead | Test strategy, quality gates |
| **Nermin Šabić** | nermin.md | DevOps | Infrastructure, CI/CD, monitoring |
| **Selma Mustafić** | selma.md | Business Analyst | Requirements, client communication |
| **Dženan Rizvanović** | dzenan.md | Risk & Compliance | HIPAA, PSD2, audits |
| **Kerim** | kerim.md | Business Dev | Sales, partnerships, market analysis |

#### Specialized Agents (7+ agents)

| Agent | File | Role | Specialty |
|-------|------|------|-----------|
| **Ops Agent** | ops.md | Operations | Service monitoring, incident response |
| **Dev** | dev.md | Developer | Full-stack development |
| **DevOps** | devops.md | DevOps | Infrastructure as code, CI/CD |
| **Designer** | designer.md | Designer | UI/UX, visual design |
| **Product** | product.md | Product Manager | Roadmap, feature prioritization |
| **Marketer** | marketer.md | Marketer | Campaigns, content, SEO |
| **Finance** | finance.md | Finance | Budgets, invoicing, reporting |
| **Legal** | legal.md | Legal | Contracts, compliance, IP |
| **Security** | security.md | Security | Threat analysis, audits |
| **Support** | support.md | Support | Customer support, documentation |
| **Auditor** | auditor.md | Auditor | Code review, compliance checks |
| **Trainer** | trainer.md | Trainer | Onboarding, documentation |
| **Data Engineer** | data-engineer.md | Data Engineer | ETL, analytics, ML pipelines |
| **Deploy** | deploy.md | Deploy | Deployment automation |
| **Monitor** | monitor.md | Monitor | Observability, alerting |
| **Nick Saraev** | nicksaraev.md | Trading | Crypto trading, portfolio mgmt |

---

## Delegation Guidelines

### When to Delegate

**Delegate when:**
- Task requires specialized expertise (not in John's domain)
- Need multiple perspectives on a decision
- Workload is too high for serial execution
- Want to validate John's own plan (second opinion)

**Don't delegate when:**
- Task is trivial (reading a file, listing tasks)
- Immediate action required (incident response)
- Context is too complex to transfer
- Result is needed in <5 minutes

### How to Delegate

#### Option 1: Claude Subagent (Execution)

```javascript
// For implementation tasks
Task({
  subagent_type: "builder",
  name: "implement-api-endpoint",
  description: "Build POST /api/users endpoint with validation",
  accept_criteria: ["Endpoint returns 201 on success", "Validation errors return 400", "Tests pass"]
});

// For verification tasks
Task({
  subagent_type: "validator",
  name: "verify-security-compliance",
  description: "Check all API endpoints have auth middleware",
  accept_criteria: ["All routes have auth", "No SQL injection risks", "Report generated"]
});
```

**Model Budget:**
- **ALWAYS:** Use "sonnet" or "haiku" for subagents
- **NEVER:** Use "opus" for builders/validators (too expensive)

#### Option 2: Ollama Agent (Advisory)

```bash
# Research/advisory (no execution)
node ~/system/tools/agent-runner.js lejla --task "Evaluate RBAC architecture options for multi-tenant SaaS"

# Get text output, then John implements
```

#### Option 3: Agent Scheduler (Parallel Advisory)

```bash
# Spawn multiple Ollama agents in parallel
node ~/system/kernel/agent-scheduler.js spawn lejla "Architecture review"
node ~/system/kernel/agent-scheduler.js spawn tarik "Test strategy"
node ~/system/kernel/agent-scheduler.js spawn dzenan "Compliance check"
```

### Choosing the Right Agent

**Decision Tree:**

```
Need execution (Write/Edit files)?
  ├─ YES → Claude Subagent (Builder)
  └─ NO → Need validation?
      ├─ YES → Claude Subagent (Validator)
      └─ NO → Need advisory?
          └─ YES → Ollama Agent (agent-runner.js)
```

**By Domain:**
- **Project management issue?** → Amina (Ollama)
- **Sprint/team issue?** → Emir (Ollama)
- **Technical architecture?** → Lejla (Ollama) OR Builder (if implementing)
- **Testing/quality?** → Tarik (Ollama) OR Validator (if verifying)
- **Deployment/infrastructure?** → Nermin (Ollama) OR Builder (if deploying)
- **Requirements unclear?** → Selma (Ollama)
- **Compliance risk?** → Dženan (Ollama)
- **Security audit?** → Auditor (Ollama) OR Validator (if checking code)
- **Implementation?** → Builder (Claude)
- **Verification?** → Validator (Claude)

---

## Multi-Agent Orchestration

### Coordination Patterns

#### Pattern 1: Sequential (Pipeline)
```
John → Agent A (approves) → Agent B (designs) → Agent C (implements) → Agent D (validates)
```

**Example:** New feature
```
John → Amina (approves) → Selma (requirements) → Lejla (design) → Builder (implements) → Validator (checks)
```

#### Pattern 2: Parallel (Broadcast)
```
                  ┌─→ Agent A (task 1)
John → Broadcast ──┼─→ Agent B (task 2)
                  └─→ Agent C (task 3)
```

**Example:** Independent tasks
```
                     ┌─→ Builder 1 (API route /users)
John → Agent Team ───┼─→ Builder 2 (API route /posts)
                     └─→ Builder 3 (API route /comments)
```

#### Pattern 3: Review (Circle)
```
John → Agent A (initial) → Agent B (review) → Agent C (compliance) → John (approval)
```

**Example:** Architecture decision
```
John → Lejla (design) → Tarik (test plan) → Dženan (compliance) → Amina (approval) → John
```

### Multi-Agent Scenarios

| Scenario | Agents | Order |
|----------|--------|-------|
| **New feature planning** | Amina → Selma → Lejla → Tarik | PM approves → BA defines → Tech designs → QA plans |
| **Production incident** | Nermin → Lejla → Tarik | DevOps investigates → Tech diagnoses → QA verifies |
| **Client escalation** | Amina → Selma → specialist | PM takes call → BA clarifies → Specialist delivers |
| **Compliance audit** | Dženan → Lejla → Nermin → Tarik | Compliance scopes → Tech reviews → DevOps checks → QA validates |
| **New deployment** | Lejla → Tarik → Nermin | Tech confirms → QA signs off → DevOps deploys |
| **Security review** | Security → Auditor → Validator | Threat analysis → Code review → Automated check |

---

## Agent Teams (Parallel Execution)

### Overview

Agent Teams enable parallel execution of independent tasks using Claude Code's native team system.

**Prerequisites:**
- tmux 3.6a installed
- `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in ~/.zshrc
- ~/.tmux.conf configured (Ctrl+A prefix)

### Workflow Comparison

#### Standard (Serial) — Existing
```
John → MC task → spawn Builder → wait → spawn Validator → done
```

**Time:** Sequential (5 + 5 + 5 = 15 minutes for 3 tasks)

#### Parallel (New) — Agent Teams
```
John → MC tasks → create Team → spawn 4 Builders → parallel work → Validator → delete Team
```

**Time:** Parallel (max(5, 5, 5) = 5 minutes for 3 tasks)

### When to Use Parallel

**Use parallel when:**
- Multiple independent tasks (e.g., 4 API routes)
- Cross-project work (e.g., frontend + backend + tests)
- Bulk operations (e.g., 8 file migrations)
- Tasks have no dependencies on each other
- Time is critical

**Stay serial when:**
- Single complex task requiring deep context
- Tasks with dependencies (B needs A's output)
- Validation/review (always single Validator)
- Cost is a concern (parallel = expensive)

### Agent Teams Tools

| Tool | Purpose |
|------|---------|
| `Teammate(operation: "spawnTeam")` | Create named agent team |
| `Task` with `team_name` + `name` | Spawn teammate in team |
| `TaskCreate` | Add task to team backlog |
| `TaskList` | View all team tasks |
| `TaskGet` | Get full task details |
| `TaskUpdate` | Update status/assignment |
| `SendMessage` | Inter-agent messaging |
| `Teammate(operation: "cleanup")` | Delete team (cleanup contexts) |

### Example: Parallel API Implementation

```javascript
// 1. Create team
Teammate({
  operation: "spawnTeam",
  team_name: "api-dev",
  description: "Build 4 API endpoints in parallel"
});

// 2. Create tasks
TaskCreate({ subject: "POST /api/users", description: "User creation endpoint" });
TaskCreate({ subject: "GET /api/users/:id", description: "User retrieval endpoint" });
TaskCreate({ subject: "PUT /api/users/:id", description: "User update endpoint" });
TaskCreate({ subject: "DELETE /api/users/:id", description: "User deletion endpoint" });

// 3. Spawn teammates (builders) - one per task
Task({
  subagent_type: "builder",
  team_name: "api-dev",
  name: "builder-1",
  description: "Implement POST /api/users"
});

Task({
  subagent_type: "builder",
  team_name: "api-dev",
  name: "builder-2",
  description: "Implement GET /api/users/:id"
});

// ... (builder-3, builder-4)

// 4. Monitor progress (auto-delivered messages)
// Teammates send updates when tasks complete

// 5. After all complete, validate
Task({
  subagent_type: "validator",
  description: "Verify all 4 API endpoints work correctly"
});

// 6. Cleanup
Teammate({
  operation: "cleanup"
});
```

### T-Mux Monitoring

Each agent runs in a separate tmux pane for visual monitoring.

**Commands:**
```bash
# Start session
tmux new -s alai

# Split panes
Ctrl+A |    # horizontal split
Ctrl+A -    # vertical split

# Navigate panes
Ctrl+A h/j/k/l

# Scroll mode (view agent output)
Ctrl+A [    # enter scroll, q to exit

# Kill session
tmux kill-session -s alai
```

---

## Tools & Commands

### Mission Control (Primary Task System)

```bash
# List tasks
node ~/system/tools/mc.js list
node ~/system/tools/mc.js list --owner john

# Start task (unlocks Write/Edit)
node ~/system/tools/mc.js start <id>

# Complete task
node ~/system/tools/mc.js done <id> "outcome"

# Pause/resume
node ~/system/tools/mc.js pause <id>
node ~/system/tools/mc.js resume <id>

# Active tasks
node ~/system/tools/mc.js active

# Stats
node ~/system/tools/mc.js stats
```

### HiveMind (Knowledge Base)

```bash
# Read recent entries
node ~/system/agents/hivemind/hivemind.js read 10

# Search
node ~/system/agents/hivemind/hivemind.js query "keyword"

# Add knowledge
node ~/system/agents/hivemind/hivemind.js post builder knowledge "Built X: key learnings"

# Status
node ~/system/agents/hivemind/hivemind.js status
```

### Agent Execution

```bash
# Ollama agent (advisory, no execution)
node ~/system/tools/agent-runner.js <agent> --task "task description"

# List available agents
node ~/system/tools/agent-runner.js list

# Parallel advisory agents
node ~/system/kernel/agent-scheduler.js spawn <agent> "task"
```

---

## Best Practices

### DO:

✅ **Use specific context** - Include project, state, constraints
✅ **Ask for options** - "Give me 3 approaches with trade-offs"
✅ **Respect agent expertise** - Trust Dženan on compliance, Lejla on architecture
✅ **Log delegations** - Use HiveMind to record decisions
✅ **Choose right model** - Sonnet for agents, Haiku for trivial, NEVER Opus for subagents
✅ **Update HiveMind** - Builders MUST post to HiveMind before completing
✅ **Verify acceptance criteria** - Validators check ALL criteria before approving
✅ **Delete teams immediately** - After parallel work, cleanup to avoid cost leakage

### DON'T:

❌ **Don't override specialties** - Don't ask Emir for architecture advice
❌ **Don't skip context** - "Design RBAC" is too vague, provide project context
❌ **Don't ignore warnings** - If Dženan says "compliance risk", investigate
❌ **Don't delegate everything** - John should handle simple tasks (reading files, listing tasks)
❌ **Don't use Opus for subagents** - Too expensive, Sonnet is sufficient
❌ **Don't leave teams running** - Ephemeral agents accumulate cost, cleanup immediately
❌ **Don't skip GOTCHA checklist** - Builders must follow anti-hallucination rules

---

## Cost Control

Agent Teams can burn through API credits quickly. Enforce limits:

### Rules:
1. **Max 4 parallel agents at once**
2. **Always use sonnet/haiku for team members** (NEVER opus)
3. **Delete team immediately after completion** (cleanup)
4. **Short-lived agents** (one task, then die - 30 turns max)
5. **Serial by default** (parallel only when justified)

### Cost Estimate:
- **Serial (3 tasks):** 3 × 5 min = 15 min total (affordable)
- **Parallel (3 tasks):** 3 × 5 min = 5 min wall-clock, but 3× API cost (expensive)

**ROI Threshold:** Use parallel only when time savings justify 3× cost.

---

## Integration with Mission Control

MC remains the source of truth for persistent task tracking.
Agent Teams tasks are ephemeral — used only during execution.

```
MC Task #208 (persistent)
  → Agent Team created
  → 4 builders work subtasks in parallel
  → Team deleted
  → MC Task #208 marked done with summary
```

**Workflow:**
1. John creates MC task (persistent)
2. John spawns Agent Team (ephemeral)
3. Builders execute subtasks in parallel
4. Validator checks output
5. John completes MC task with outcome
6. John deletes Agent Team (cleanup)

---

## Related Documents

### Agent Protocols
- **Builder Protocol:** ~/.claude/agents/builder.md
- **Validator Protocol:** ~/.claude/agents/validator.md
- **Anti-Hallucination Rules:** ~/system/rules/agent-anti-hallucination.md

### Agent Identities (Ollama)
**Location:** ~/system/agents/identities/
- amina.md, emir.md, lejla.md, tarik.md, nermin.md, selma.md, dzenan.md, kerim.md
- ops.md, dev.md, devops.md, designer.md, product.md, marketer.md, finance.md, legal.md, security.md, support.md, auditor.md, trainer.md, data-engineer.md, deploy.md, monitor.md, nicksaraev.md

### System Documentation
- **GOTCHA Framework:** ~/system/CLAUDE.md
- **Tool-First Protocol:** ~/system/rules/tool-first-protocol.md
- **Development Standards:** ~/system/rules/development.md
- **Task Management:** ~/system/rules/task-management.md

### Original Files (Archived)
- AGENT-SYSTEM-README.md (8.6KB)
- AGENT-SYSTEM-VERIFICATION.md (8.4KB)
- AGENTS-QUICKREF.md (3.3KB)
- AGENTS-SYSTEM.md (9.5KB)
- AGENTS.md (9.0KB)
- agents-registry.md (8.5KB)
- multi-agent-orchestration.md (5.3KB)

All originals preserved in: ~/system/context/docs/agents/ (timestamped)

---

**Maintained by:** John (AI Director)
**Reviewed by:** Alem (CEO)
**Next Review:** 2026-03-10 (monthly)