AI Agents -- Your Digital Team

In the previous chapters, you learned how GOD CRM stores data in tables, organizes work into [Spaces

In the previous chapters, you learned how GOD CRM stores data in tables, organizes work into Spaces and Projects, and presents data through multiple layers. Now it is time to meet the most distinctive part of the system: AI Agents.

Agents are not an add-on feature. They are core to what GOD CRM is. That is why this chapter comes before Modules and Widgets -- because agents are woven into every layer of the architecture.

What Are AI Agents?

An AI Agent is an autonomous digital worker that lives inside GOD CRM. It can read your tables, create and update data, write code, run tests, deploy software, manage documents, and coordinate other agents -- all on its own.

Think of it this way. Imagine you hire a team of specialists for your company:

• A backend programmer who writes server code
• A frontend designer who builds the user interface
• A quality inspector who runs every test
• An IT administrator who manages the servers
• A project manager who keeps everyone on track

Now imagine those specialists are AI. They work around the clock. They never forget a step. They follow strict rules. And they live right inside your CRM, where all the data already is.

That is what AI Agents are in GOD CRM.

Agents Are Not Chatbots

When most people hear "AI in a CRM," they picture a chatbot -- a text box where you type a question and get an answer. GOD CRM agents go far beyond that.

A chatbot answers questions. An agent takes action.

Here is what agents can actually do:

• Read tables -- look at your customer list, task board, or sales data and understand what is there.
• Create and update data -- add new rows, update existing records, or mark tasks as complete.
• Write code -- write backend logic, frontend components, and database queries.
• Run tests -- execute the test suite and report whether everything passes.
• Deploy software -- push code to a server, restart services, and verify the deployment.
• Coordinate other agents -- assign tasks to other agents and track their progress.

In short, agents are workers, not just advisors.

The Agent Roster

GOD CRM ships with a team of specialist agents. Each one has a defined role, like employees in a company. Here is the full roster:

                      Orchestrator
                     (Team Lead)
                          |
          ----------------------------------------
          |         |         |         |        |
     Developer  Frontend  Test     Sysadmin  Document
     Ralph      + QA      Runner             Agent
          |
     Table Architect
     Widget Developer
     Architect

Developer -- A full-stack programmer. Writes both backend (server) and frontend (browser) code. Follows TDD strictly: writes a failing test first (Red), writes code to make it pass (Green), then cleans up (Refactor). Every line of code gets a test before it ships.

Developer Ralph -- A backend specialist with one defining trait: persistence. Ralph uses a loop approach -- it starts with a behavior description, converts it into tests, writes code, runs tests, and repeats until every criterion is met. Ralph does not stop until the task is fully done. If something breaks, Ralph fixes it and continues.

Architect -- Designs the overall system structure. Does not write feature code directly. Instead, creates ADRs (Architecture Decision Records) that describe what to build, why, and how. Thinks about the big picture: how components fit together and what patterns to follow.

Frontend -- Specializes in React UI components. Builds the visual parts of GOD CRM: buttons, forms, tables, modals, sidebars. Knows React 19, modern CSS, and accessibility best practices.

Frontend QA -- The quality inspector for the user interface. Checks that components look correct, layouts do not break on different screens, colors meet accessibility standards, and interactive elements behave as expected.

Test Runner -- Runs the entire test suite: unit tests (Vitest), end-to-end tests (Playwright), and any other automated checks. Analyzes results, identifies failures, and reports back with a clear summary. When a build breaks, the Test Runner is the first to know.

Sysadmin -- Handles infrastructure. Manages servers, configures deployments, restarts services, checks system health, and troubleshoots operational issues. Think of it as the IT department in a single agent.

Table Architect -- Creates and manages database tables through the GOD CRM API. Designs columns, sets data types, and builds tables at Layer 1 (Raw Tables) and Layer 2 (Universal Tables) of the four-layer architecture.

Widget Developer -- Builds dashboard widgets -- the small summary cards that appear on dashboards (Layer 4). Charts, number cards, mini-calendars, Kanban boards -- this agent creates them.

Orchestrator -- The conductor of the orchestra. Does not play an instrument itself. Instead, it reads the task list, assigns work to the right specialists, monitors progress, and ensures everything comes together. The most important agent because it coordinates all the others.

Document Agent -- Manages documentation. Creates, imports, organizes, and updates documents inside the Documents module. Handles batch operations like importing ADRs or converting markdown files into CRM documents.

All agent definitions live in two places:

• .opencode/agents/ -- contains the full behavior specification for each agent
• .github/prompts/ -- contains prompt files used by the coding environment

How Agents Communicate -- The @mention System

You talk to agents using @mentions, just like mentioning someone on social media or in a team chat. Type the @ symbol followed by the agent name and describe what you need:

@developer add a phone column to the contacts table
@frontend fix the alignment bug in the sidebar
@architect create an ADR for the new export feature
@test-runner run all tests and report failures
@sysadmin deploy the latest build to production

When you write @developer add a phone column to the contacts table, here is what actually happens:

1. The system reads the developer agent's behavior file.
2. It launches the developer agent with your instruction.
3. The developer writes a test first (the test fails because the column does not exist yet).
4. The developer writes the code to add the column (the test now passes).
5. The developer cleans up and verifies everything works.
6. The result comes back to you.

You did not need to know how to write code, run tests, or deploy anything. You just described what you wanted in plain English.

Here is the full list of available @mentions:

The Rules Agents Follow

Every agent in GOD CRM follows strict rules. These are not suggestions -- they are enforced requirements:

TDD is mandatory. Every agent that writes code must follow the Red-Green- Refactor cycle. Write a failing test first. Write code to pass the test. Clean up the code. No exceptions.

No console.log. Agents use the structured logger instead. On the frontend: logger.debug() and logger.error(). On the backend: Pino logger. This keeps logs clean and useful in production.

No : any in TypeScript. Agents use proper types, generics, and unknown with type guards. This catches bugs at compile time instead of runtime.

Backup before editing. Before modifying any file, agents copy the original to /root/backups/temp/. If something goes wrong, you can always restore.

Security first. Parameterized SQL queries (never string concatenation), Zod validation for inputs, transactions for multi-step operations.

These rules exist because agents work autonomously. Without strict guardrails, an autonomous worker could create messes. With them, agent output is consistently high quality.

Agents Work in Parallel

GOD CRM can run up to 10 agents at the same time. This means:

• The Developer can write backend code while the Frontend builds the UI.
• The Test Runner can validate one feature while the Architect designs the next.
• The Sysadmin can deploy to staging while Developer Ralph finishes a bug fix.

The Orchestrator coordinates this parallelism. It knows which tasks depend on each other (you cannot test code that has not been written yet) and which can run simultaneously (backend and frontend for different features).

Agents Across the Four Layers

Agents are not a fifth layer. They are cross-cutting -- they work across all four layers at once. See The Four Layers for the full explanation of layers.

A single agent action can ripple through every layer. When an agent adds rows to a table (Layer 2), the Calendar module automatically shows new events (Layer 3), and the dashboard Number widget recalculates its total (Layer 4).

  Layer 4: Widgets       <--- Agents CONFIGURE
  Layer 3: Modules       <--- Agents BUILD
  Layer 2: Universal     <--- Agents CREATE / UPDATE
  Layer 1: Raw Tables    <--- Agents READ

  Agents span ALL layers (cross-cutting)

The Orchestrator Pattern

The Orchestrator is the heart of agent coordination. It is described in detail in Architecture Decision Record ADR-055. Here is how it works:

1. You give the Orchestrator a high-level goal (for example, "implement the search feature described in this ADR").
2. The Orchestrator reads the goal and extracts acceptance criteria -- the list of things that must be true when the work is done.
3. It breaks the goal into smaller tasks and assigns each to the right agent: backend work to Developer Ralph, UI work to Frontend, testing to Test Runner.
4. Specialist agents work on their tasks and update their status in the table.
5. When a specialist finishes, the Orchestrator checks the result. If quality gates pass (tests pass, no security issues), the task is marked complete. If not, the Orchestrator creates a fix task and the cycle repeats.
6. The Orchestrator does not stop until every acceptance criterion is met.

A key property of the Orchestrator is persistence. It runs in a loop. Every 30 minutes, it checks for incomplete projects. If a task failed, it creates a recovery task. If a task is stalled, it reassigns it. The Orchestrator only stops when everything is done.

This "never stop until done" behavior is what separates the Orchestrator from a simple task runner. A task runner executes a list and stops. The Orchestrator pursues a goal.

Agent-as-User

Every agent has its own user account in GOD CRM. This is a deliberate design decision described in ADR-023, not a workaround. Each agent has:

• A username (like "developer-ralph" or "orchestrator")
• An email address for identification in the system
• An activity log (every action is recorded in the Agent Activity table)
• Permissions (agents can only access authorized Spaces and tables)

This means you can look at the activity log and see exactly what each agent did, when, and what the result was. You can build a dashboard widget showing "Tasks completed by Developer Ralph this week" right next to "Tasks completed by the sales team."

From the system's perspective, an agent is just another user -- one that happens to be powered by AI instead of a human brain. The same tables, dashboards, and widgets you use to track human activity work for agent activity too.

A Real Example

Let us walk through a complete scenario.

You type: @developer add a search feature to the Contacts module

What happens behind the scenes:

1. The Orchestrator reads your request and creates three sub-tasks:

   • "Backend: Add search API endpoint for contacts" -- assigned to Developer Ralph
   • "Frontend: Build search input and results UI" -- assigned to Frontend
   • "Tests: Write unit and integration tests for search" -- assigned to Test Runner

2. Developer Ralph writes a test for the new API endpoint (test fails -- Red). Then writes the endpoint code (test passes -- Green). Cleans up (Refactor). Updates status to "Done."

3. Frontend creates the search input component, wires it to the API, styles it to match the Contacts module. Updates status to "Done."

4. Test Runner runs the full suite: unit tests, integration tests, end-to-end tests. Everything passes. Creates a quality report. Status: "Done."

5. Orchestrator sees all sub-tasks complete with passing quality checks. Marks the parent task as "Complete."

6. Next time you open the Contacts module, the search feature is there and working. The Kanban board on the Development dashboard shows the task in the "Done" column.

You described what you wanted in one sentence. The agents handled everything else -- without you managing any of them directly.

Why This Matters

Most CRM systems treat AI as an afterthought -- a chatbot bolted onto the side. In GOD CRM, agents are built into the foundation:

• Automation is native. No third-party tools needed. The agents are already there.
• The system improves itself. Agents write code, test it, and deploy it inside the very CRM they are building.
• Everything is visible. Agent actions are logged in CRM tables. You can build dashboards and reports on agent activity, just like human activity.
• It scales. Need more capacity? The system supports up to 10 parallel agents, each working independently but coordinating through the Orchestrator.

What Is Next?

Agents build and manage Modules. But what exactly are Modules? How many exist? What can each one do?

Read Modules -- Apps for Your Data to find out.