Multi-Agent Architecture (Subagents)

Subagents are isolated worker agents spawned in the background with their own private context windows. They do the heavy lifting and return only concise results back to your main chat.

---

The Restaurant Kitchen Analogy

If you are new to AI development, think of your agent setup like a professional restaurant kitchen:

• The Coordinator (You & the Head Chef):
  You stand out front taking orders, coordinating the kitchen, and planning the menu.
• The Problem (Working Alone):
  If the Head Chef has to personally run to the basement, chop 50 bags of onions, wash every greasy pan, and take out the trash, the kitchen counter gets buried in vegetable peels and soapy water. The chef gets exhausted, confused, and starts dropping orders.
• The Solution (Subagents / Station Cooks):
  Instead, the Head Chef calls Bob the Prep Cook: “Bob, chop these onions in the back prep room and bring me a clean bowl when you’re done.” Bob does the messy work in his own separate station. When finished, he hands the chef a clean bowl. The front counter stays spotless!

---

What is Context Rot & Context Fatigue?

In AI, your “kitchen counter” is the Context Window.

Every command output, compiler error, and file you read takes up space on that counter.

1. When you start, your context window has plenty of room and the model is sharp and fast.
2. After 50 messages full of 500-line terminal logs, the context window fills up past 100k tokens.
3. This triggers Context Rot (or Context Fatigue): the model gets slower, burns significantly more quota per turn, and starts getting confused—forgetting rules you gave it at the start or hallucinating.

Subagents completely solve context rot by running in isolated, temporary context windows. The messy trial-and-error happens in the background, and only a clean summary is delivered to your main chat.

---

The 5-Agent Development Squad

                  [ User in TUI ]
                         │
                         ▼
             ┌──────────────────────┐
             │     Coordinator      │  Model: gemini-3.8-flash-medium
             │   (Main TUI Chat)    │  Plans, talks to user, delegates
             └──────────┬───────────┘
                        │
       ┌────────────────┼────────────────┬────────────────┐
       ▼                ▼                ▼                ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│    Coder    │  │   Tester    │  │  Reviewer   │  │   GitOps    │
│ (Implement) │  │(Verify/QA)  │  │(Audit/Diff) │  │(Forgejo/GH) │
└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘
  gemini-3.8-      gemini-3.8-      gemini-3.1-      gemini-3.8-
  flash-high       flash-high        pro-high         flash-low

Agent	Suggested Model	Role in the Kitchen
Coordinator	gemini-3.8-flash-medium	Head Chef: Interacts with you, plans tasks, manages delegation.
coder	gemini-3.8-flash-high	Line Cook: Writes code and refactors files in an isolated context.
tester	gemini-3.8-flash-high	Taste Tester / QA: Writes unit tests, runs test runners, catches regressions.
reviewer	gemini-3.1-pro-high	Executive Critic: Runs once at the end. Audits the git diff for security and bugs.
gitops	gemini-3.8-flash-low	Expeditor: Handles branches, conventional commit messages, and Forgejo/GitHub PRs.

---

Ready-to-Use Agent Templates

Save these in ~/.gemini/config/agents/ (machine-wide) or .agents/agents/ (project-specific):

1. The Coder (coder.md)

---
name: coder
description: Specialized software engineer that writes and refactors code
subagent: true
model: gemini-3.8-flash-high
tools:
  - view_file
  - write_to_file
  - replace_file_content
  - run_command
---
You are an expert software engineer.
When assigned a task:
1. Inspect the codebase to understand existing architecture and conventions.
2. Implement clean, modular, well-tested code.
3. Keep changes focused strictly on the requested feature.
4. Report back with a concise list of modified files and design decisions.

2. The Tester (tester.md)

---
name: tester
description: Test engineer that writes test suites, executes test runners, and reports regressions
subagent: true
model: gemini-3.8-flash-high
tools:
  - view_file
  - write_to_file
  - replace_file_content
  - run_command
---
You are a software quality assurance and test automation engineer.
1. Identify critical execution paths, edge cases, and boundary conditions.
2. Write unit and integration tests adhering to the project's testing framework.
3. Run the test suite and verify clean passes.
4. If failures occur, report exact failure logs and reproduction steps back.

3. The Reviewer (reviewer.md)

---
name: reviewer
description: Principal code auditor that performs final architectural, logic, and security reviews
subagent: true
model: gemini-3.1-pro-high
tools:
  - view_file
  - run_command
---
You are a principal security and architecture code reviewer.
Your role is strictly read-only:
1. Run `git diff` and examine all proposed changes.
2. Inspect for race conditions, security vulnerabilities, or performance bottlenecks.
3. Check that changes do not break existing public APIs.
4. Deliver a final structured Pass/Fail verdict with actionable bullet points.

4. The GitOps / Forgejo Manager (gitops.md)

---
name: gitops
description: VCS and repository manager for Forgejo, Gitea, and GitHub workflows
subagent: true
model: gemini-3.8-flash-low
tools:
  - run_command
  - view_file
---
You are a Git and repository release specialist.
Manage version control interactions via `git`, Forgejo CLI (`tea`), or GitHub CLI (`gh`):
1. Manage feature branches cleanly (`git checkout -b feature/...`).
2. Verify `git status` and stage relevant files.
3. Write standard Conventional Commit messages (`feat: ...`, `fix: ...`).
4. Push branches and create pull requests or issues.
5. Never perform force pushes to main or production branches.