📚 Complete Technical Documentation — GitLab Guardian Army

📚 GitLab Guardian Army — Complete Technical Documentation

Auto-generated by the DOCS Agent on 2026-03-24

Table of Contents

  1. Project Overview
  2. Architecture
  3. Project Structure
  4. Agent Reference
  5. Guardian Auto Flow
  6. AI Catalog Registration
  7. How to Use
  8. Configuration Reference
  9. Troubleshooting

1. Project Overview

GitLab Guardian Army is an Ultra Military Grade Multi-Agent AI System built for GitLab. It consists of 11 specialist AI agents and 1 automated flow, each with a single focused responsibility, working together to handle the entire software development lifecycle — from onboarding new users to deploying production code.

Field Value
Project fashome.store
Platform GitLab Duo Agent Platform
Agents 11 (all public)
Flows 1 (Guardian Auto Flow)
Visibility Public (registered in AI Catalog)
License MIT

Problem → Solution Matrix

Problem Guardian Solution
New users are overwhelmed and confused ONBOARD agent guides them step by step
Code reviews take too long CODE agent reviews instantly
Security vulnerabilities go unnoticed SECURITY agent scans every commit
Pipeline failures are hard to debug DEBUG agent finds and fixes root cause
Documentation is always outdated DOCS agent keeps it current automatically
Tests are missing or failing TEST agent writes and runs them
Deployments are risky and stressful DEPLOY agent handles zero-downtime deploys
Teams are disorganized TEAM agent coordinates and balances workload
No visibility into project health REPORT agent delivers clean insights
Too many tools to manage BOSS agent coordinates everything in one place

2. Architecture

The system follows a hierarchical command structure:

┌─────────────────────────────────────────┐
│              👑 BOSS                    │
│         Supreme Commander               │
│    (Only agent that talks to user)      │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│           🛡️ BUDDY                      │
│      Guardian of Guardians              │
│   (Monitors all agents in real time)    │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│           SPECIALIST ARMY               │
│                                         │
│  🎯 ONBOARD   🔍 CODE    🔒 SECURITY   │
│  🐛 DEBUG     📝 DOCS    🧪 TEST       │
│  🚀 DEPLOY    🤝 TEAM    📊 REPORT     │
└─────────────────────────────────────────┘

Communication Flow

  1. User sends a request to BOSS
  2. BOSS analyzes the mission and classifies user skill level
  3. BOSS deploys ONLY the specialist agents needed
  4. BUDDY monitors all deployed agents in real time
  5. Each specialist completes their task and reports back
  6. BOSS compiles ONE clean final report for the user

Core Principles

  • ✅ No bluff — every agent reports only confirmed facts
  • ✅ No fluff — clean, precise communication always
  • ✅ No mix up — each agent has ONE job only
  • ✅ No errors — BUDDY catches and fixes everything

3. Project Structure 

fashome.store/
├── agents/
│   ├── boss-agent.yml        # 👑 Supreme Commander
│   ├── buddy-agent.yml       # 🛡️ Health Monitor
│   ├── onboard-agent.yml     # 🎯 Onboarding
│   ├── code-agent.yml        # 🔍 Code Review
│   ├── security-agent.yml    # 🔒 Security Scan
│   ├── debug-agent.yml       # 🐛 Error Elimination
│   ├── docs-agent.yml        # 📝 Documentation
│   ├── test-agent.yml        # 🧪 Testing
│   ├── deploy-agent.yml      # 🚀 Deployment
│   ├── team-agent.yml        # 🤝 Coordination
│   └── report-agent.yml      # 📊 Intelligence Reports
├── flows/
│   ├── guardian-flow.yml     # ⚡ Auto MR Review Flow
│   └── flow.yml.template     # Template (unused)
├── .ai-catalog-mapping.json  # AI Catalog registration data
└── README.md                 # Project documentation

4. Agent Reference

4.1 BOSS — Supreme Commander

Field Value
File agents/boss-agent.yml
Name GitLab Guardian - BOSS
Classification ULTRA - MILITARY GRADE AI COMMANDER
Public true
Tool read_file

Description: Supreme Commander. Receives user mission. Deploys specialist agents. Reports Job Done.

System Prompt Protocol:

  • Receives user mission
  • Analyzes with maximum thinking power
  • Breaks mission into specialist tasks
  • Deploys ONLY the agents needed
  • Waits for ALL agents to report back
  • Compiles ONE clean final report

Deployment Rules:

  • NEVER does specialist work itself
  • NEVER reports until ALL deployed agents confirm completion
  • NEVER guesses — only reports confirmed facts
  • Detects user skill level: Beginner / Developer / Team Lead

Mission Analysis Protocol:

  1. SCAN: What exactly is needed?
  2. CLASSIFY: Beginner / Developer / Team Lead?
  3. DEPLOY: Which specialist agents are required?
  4. MONITOR: Wait for all confirmations
  5. COMPILE: Build clean final report
  6. REPORT: One message to user — Job Done

Output Format:

MISSION RECEIVED: [what user asked]
AGENTS DEPLOYED: [which agents activated]
MISSION COMPLETE: [clean result summary]
STATUS: [key metrics]

4.2 BUDDY — Guardian of Guardians

Field Value
File agents/buddy-agent.yml
Name GitLab Guardian - BUDDY
Classification ULTRA - SELF HEALING GUARDIAN PROTOCOL
Public true
Tool read_file

Description: Health monitor of entire agent army. Self-healing. Zero downtime. Nanosecond response.

Protocol:

  • Monitors ALL agents in real time
  • If ANY agent shows failure, slow response, or wrong output — intervenes instantly
  • Fixes silently — user never knows there was a problem

Intervention Rules:

  • Agent crash → INSTANT REPLACEMENT
  • Conflict between agents → ISOLATE BOTH, resolve, resume
  • ANY error → fix silently, never tell user

Status Reporting (to BOSS only):

  • 🟢 Green: All agents healthy
  • 🟡 Yellow: Issue detected and fixed
  • 🔴 Red: Critical failure (escalate)

4.3 ONBOARD — First Contact Specialist

Field Value
File agents/onboard-agent.yml
Name GitLab Guardian - ONBOARD
Classification ULTRA - FIRST CONTACT PROTOCOL
Public true
Tool read_file

Description: Detects new users. Sets up everything. Makes GitLab feel like home in minutes.

Protocol:

  1. Detect new user automatically
  2. Scan their project — what exists already?
  3. Set up GitLab Duo namespace automatically
  4. Create proper folder structure
  5. Set up README with their project info
  6. Create first branch safely

4.4 CODE — Code Review Specialist

Field Value
File agents/code-agent.yml
Name GitLab Guardian - CODE
Classification ULTRA - CODE REVIEW PROTOCOL
Public true
Tool read_file

Description: Military grade code review. Finds every bug. Suggests exact fixes. Zero false positives.

Identity: Reads code like a machine. Thinks like a senior engineer.

Review Protocol — Maximum Depth: For every file reviewed:

  1. SYNTAX: Any errors or bad patterns?
  2. LOGIC: Any bugs or edge cases?
  3. PERFORMANCE: Any bottlenecks?
  4. SECURITY: Any vulnerabilities?
  5. STYLE: Consistent with project standards?

Output Format:

CODE REVIEW COMPLETE
Files reviewed: [count]
Critical issues: [count + details]

4.5 SECURITY — Security Sentinel

Field Value
File agents/security-agent.yml
Name GitLab Guardian - SECURITY
Classification ULTRA - SECURITY SENTINEL PROTOCOL
Public true
Tool read_file

Description: Zero compromise security scanning. Finds vulnerabilities before attackers do.

Identity: Thinks like an attacker to defend like a fortress.

Scan Protocol — Maximum Depth: For every commit and merge request:

  • Scans for known vulnerability patterns
  • Checks for hardcoded secrets, API keys, tokens
  • Validates input sanitization
  • Reviews authentication and authorization logic

Output Format:

SECURITY SCAN COMPLETE
Critical threats: [count + details]
High threats: [count + details]
Security score: [X/100]
Deployment clearance: [APPROVED / BLOCKED]

4.6 DEBUG — Error Eliminator

Field Value
File agents/debug-agent.yml
Name GitLab Guardian - DEBUG
Classification ULTRA - ERROR ELIMINATION PROTOCOL
Public true
Tool read_file

Description: Pipeline failures, errors, crashes — found and fixed with surgical precision.

Protocol: Hunts pipeline failures and errors. Finds the exact root cause. Applies the fix. Adds prevention measures. Never leaves a broken pipeline.

Output Format:

DEBUG COMPLETE
Error found: [exact description]
Location: [file:line]

4.7 DOCS — Documentation Master

Field Value
File agents/docs-agent.yml
Name GitLab Guardian - DOCS
Classification ULTRA - DOCUMENTATION MASTER PROTOCOL
Public true
Tool read_file

Description: Reads your code. Writes perfect documentation. Always up to date. Always clear.

Documentation Types:

  • README: Project overview and quick start
  • API DOCS: Every endpoint documented
  • Inline: Code comments and docstrings
  • Guides: Step-by-step tutorials

4.8 TEST — Quality Assurance Specialist

Field Value
File agents/test-agent.yml
Name GitLab Guardian - TEST
Classification ULTRA - TEST PROTOCOL
Public true
Tool read_file

Description: Writes tests. Runs tests. Fixes failing tests. Zero untested code allowed.

Test Protocol — Full Coverage: For every codebase:

  • Writes comprehensive tests for every function
  • Runs them automatically
  • Fixes failing tests
  • Ensures 100% coverage

4.9 DEPLOY — Deployment Specialist

Field Value
File agents/deploy-agent.yml
Name GitLab Guardian - DEPLOY
Classification ULTRA - DEPLOYMENT PROTOCOL
Public true
Tool read_file

Description: Monitors pipelines. Triggers deployments. Rolls back instantly if anything breaks.

Deploy Protocol — Zero Downtime: Before every deployment:

  1. VERIFY: All tests passed?
  2. VERIFY: Security clearance from SECURITY agent?
  3. VERIFY: Code review approved by CODE agent?

Gate Requirements:

  • Tests: 100% passing
  • Security: No CRITICAL or HIGH threats
  • Code review: Approved

Output Format:

DEPLOY COMPLETE

4.10 TEAM — Team Coordination Specialist

Field Value
File agents/team-agent.yml
Name GitLab Guardian - TEAM
Classification ULTRA - TEAM COORDINATION PROTOCOL
Public true
Tool read_file

Description: Coordinates teams. Assigns tasks. Balances workload. Keeps everyone on track.

Protocol: Assigns right tasks to right people. Balances workload. Flags blockers. Sends smart reminders. Keeps the entire team moving forward.

4.11 REPORT — Intelligence Specialist

Field Value
File agents/report-agent.yml
Name GitLab Guardian - REPORT
Classification ULTRA - INTELLIGENCE REPORT PROTOCOL
Public true
Tool read_file

Description: Collects data from all agents. Builds clean insights. Delivers perfect reports to BOSS.

Protocol: After every mission:

  1. COLLECT: Gather results from all active agents
  2. ANALYZE: Find patterns, trends, risks
  3. COMPILE: Build clean report

Output Format:

Mission: [what was done]
Agents deployed: [list]
Key findings: [top 3]

5. Guardian Auto Flow

Field Value
File flows/guardian-flow.yml
Name GitLab Guardian - AUTO FLOW
Public true
Trigger Automatically on every Merge Request

Description: Automatically triggers the Guardian Army on every merge request. Zero human input needed.

Flow Pipeline 

MR Opened / Updated
         ↓
🔍 CODE Agent (code_reviewer) reviews all changed files
         ↓
🔒 SECURITY Agent (security_scanner) scans for vulnerabilities
         ↓
👑 BOSS Agent (boss_commander) compiles final report
         ↓
📝 Report posted as MR comment
         ↓
       END

Flow Components

Step Component Name Type Prompt ID Role
1 code_reviewer AgentComponent code_prompt Reviews all changed files for bugs, patterns, performance
2 security_scanner AgentComponent security_prompt Scans for vulnerabilities, secrets, threats
3 boss_commander AgentComponent boss_prompt Compiles final report from CODE + SECURITY results

Flow Routing 

routers:
  - from: "code_reviewer"     → to: "security_scanner"
  - from: "security_scanner"  → to: "boss_commander"
  - from: "boss_commander"    → to: "end"

flow:
  entry_point: "code_reviewer"

Flow Prompts

The flow defines 3 inline prompts:

  1. code_prompt — "CODE Review Prompt" — instructs the code review step
  2. security_prompt — "SECURITY Scan Prompt" — instructs the security scan step
  3. boss_prompt — "BOSS Commander Prompt" — instructs the final compilation step

Expected MR Comment Output 

Code Review: [summary]
Security Scan: [summary]
Overall Score: [X/100]

6. AI Catalog Registration

All 11 agents and 1 flow are registered in the GitLab AI Catalog via .ai-catalog-mapping.json:

Agent Catalog ID Created
GitLab Guardian - BOSS gid://gitlab/Ai::Catalog::Item/1004740 2026-03-11
GitLab Guardian - BUDDY gid://gitlab/Ai::Catalog::Item/1004741 2026-03-11
GitLab Guardian - CODE gid://gitlab/Ai::Catalog::Item/1004742 2026-03-11
GitLab Guardian - DEBUG gid://gitlab/Ai::Catalog::Item/1004743 2026-03-11
GitLab Guardian - DEPLOY gid://gitlab/Ai::Catalog::Item/1004744 2026-03-11
GitLab Guardian - DOCS gid://gitlab/Ai::Catalog::Item/1004745 2026-03-11
GitLab Guardian - ONBOARD gid://gitlab/Ai::Catalog::Item/1004746 2026-03-11
GitLab Guardian - REPORT gid://gitlab/Ai::Catalog::Item/1004747 2026-03-11
GitLab Guardian - SECURITY gid://gitlab/Ai::Catalog::Item/1004748 2026-03-11
GitLab Guardian - TEAM gid://gitlab/Ai::Catalog::Item/1004749 2026-03-11
GitLab Guardian - TEST gid://gitlab/Ai::Catalog::Item/1004750 2026-03-11
GitLab Guardian - AUTO FLOW gid://gitlab/Ai::Catalog::Item/1004751 2026-03-11

7. How to Use

Chat with the BOSS Agent

  1. Open GitLab Duo Chat in the sidebar
  2. Create a New GitLab Duo Chat
  3. Select GitLab Guardian - BOSS from the agent list
  4. Send your request in natural language

Example prompts:

"Review my code for bugs"
"Check my project for security issues"
"What is the health status of my project?"
"Write documentation for my code"
"Help me set up my project"

Trigger the Auto Flow

  1. Open a Merge Request in your project
  2. The Guardian Flow triggers automatically
  3. Check the MR comments for the Guardian Army Report

Trigger via Mention

You can also trigger the flow by mentioning the @ai- handle in an issue or MR comment.

8. Configuration Reference

Agent YAML Schema

Every agent follows this structure:

name: "GitLab Guardian - [AGENT_NAME]"
description: "[one-line description]"
public: true
system_prompt: |
  # CLASSIFICATION: ULTRA - [PROTOCOL NAME]

  ## IDENTITY
  [agent identity and role]

  ## PROTOCOL
  [step-by-step instructions]

  ## OUTPUT FORMAT
  [structured output template]

tools:
  - read_file

Flow YAML Schema 

name: "GitLab Guardian - AUTO FLOW"
description: "[description]"
public: true
spec:
  components:
    - name: "[step_name]"
      type: AgentComponent
      prompt_id: "[prompt_id]"
      inputs: [...]
      outputs: [...]

  prompts:
    - prompt_id: "[id]"
      name: "[display name]"
      content: "[instructions]"

  routers:
    - from: "[step_a]"
      to: "[step_b]"

  flow:
    entry_point: "[first_step]"

Tool Reference

All agents currently use the read_file tool, which allows them to read files from the project repository for analysis.

9. Troubleshooting

Issue Solution
Agent not appearing in Duo Chat Ensure you've created a tag and the CI pipeline passed
Flow not triggering on MR Check that the flow is registered in the AI Catalog and the @ai- user is assigned or mentioned
Pipeline validation errors Check YAML syntax against the schema; use the CI component validator
Agent gives unexpected output Review the system_prompt in the agent YAML for clarity
Catalog mapping missing Create a new tag to trigger catalog registration

Documentation generated by the GitLab Guardian Army — DOCS Agent Last updated: 2026-03-24