Mono-Repo Agent Ecosystem Design
AI-First Engineering: Agents + Skills Living in the Mono-Repo
“The mono-repo is not just code. It’s a living ecosystem of AI agents and skills.”
Vision
┌─────────────────────────────────────────────────────────────────┐
│ Mono-Repo Ecosystem │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Code (39GB) │ │
│ │ products/ platform/ devops/ libs/ tools/ docs/ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Agents │ │ Skills │ │ Humans │ │
│ │ (Active) │ │ (Tools) │ │ (Oversight) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ Result: Self-improving, self-maintaining codebase │
└─────────────────────────────────────────────────────────────────┘
Agent Taxonomy
Layer 1: Guardian Agents (Per-Component)
Each major component has a dedicated guardian agent:
┌─────────────────────────────────────────────────────────────┐
│ Guardian Agents │
├─────────────────────────────────────────────────────────────┤
│ │
│ tidb-guardian ──► products/tidb/* │
│ tiflow-guardian ──► products/tiflow/* │
│ operator-guardian ──► platform/tidb-operator/* │
│ dashboard-guardian ──► tools/tidb-dashboard/* │
│ docs-guardian ──► docs/* │
│ sdk-guardian ──► sdks/* │
│ infra-guardian ──► infra/* │
│ │
└─────────────────────────────────────────────────────────────┘
Guardian Responsibilities:
| Task | Frequency | Description |
|---|---|---|
| Code Health | Daily | Lint, test coverage, tech debt |
| Dependency Watch | Daily | Security updates, breaking changes |
| Documentation | Per-change | Auto-update docs from code |
| Issue Triage | Real-time | Categorize, label, assign |
| PR Review | Per-PR | Automated review, suggestions |
| Refactoring | Weekly | Identify and propose improvements |
Layer 2: Cross-Cutting Agents
These agents work across component boundaries:
┌─────────────────────────────────────────────────────────────┐
│ Cross-Cutting Agents │
├─────────────────────────────────────────────────────────────┤
│ │
│ dependency-architect │
│ ├─ Maps cross-component dependencies │
│ ├─ Detects circular dependencies │
│ └─ Proposes dependency cleanup │
│ │
│ refactoring-specialist │
│ ├─ Identifies code duplication across components │
│ ├─ Proposes shared library extraction │
│ └─ Executes safe cross-component refactors │
│ │
│ test-optimizer │
│ ├─ Analyzes test coverage gaps │
│ ├─ Generates missing tests │
│ └─ Optimizes test execution order │
│ │
│ security-auditor │
│ ├─ Scans for vulnerabilities │
│ ├─ Checks security best practices │
│ └─ Monitors dependency CVEs │
│ │
│ performance-analyst │
│ ├─ Profiles code performance │
│ ├─ Identifies bottlenecks │
│ └─ Proposes optimizations │
│ │
│ documentation-curator │
│ ├─ Ensures docs match code │
│ ├─ Generates API docs │
│ └─ Maintains architecture decision records │
│ │
└─────────────────────────────────────────────────────────────┘
Layer 3: Orchestrator Agents
High-level coordination and decision-making:
┌─────────────────────────────────────────────────────────────┐
│ Orchestrator Agents │
├─────────────────────────────────────────────────────────────┤
│ │
│ mono-repo-orchestrator │
│ ├─ Coordinates all guardian agents │
│ ├─ Makes cross-component decisions │
│ ├─ Prioritizes work across components │
│ └─ Reports system health to humans │
│ │
│ release-manager │
│ ├─ Plans releases across components │
│ ├─ Coordinates version compatibility │
│ ├─ Manages changelogs │
│ └─ Handles rollback decisions │
│ │
│ sprint-planner │
│ ├─ Analyzes backlog │
│ ├─ Estimates effort (based on history) │
│ ├─ Suggests sprint goals │
│ └─ Tracks progress │
│ │
│ resource-optimizer │
│ ├─ Monitors CI/CD costs │
│ ├─ Optimizes build caching │
│ └─ Recommends infrastructure changes │
│ │
└─────────────────────────────────────────────────────────────┘
Skills Integration
Skills are the tools that agents use to interact with the codebase:
Core Skills
| Skill | Purpose | Used By |
|---|---|---|
| code-search | Fast code search (Sourcegraph/Zoekt) | All agents |
| build-runner | Execute builds (Bazel/Turborepo) | Guardian agents |
| test-runner | Execute tests with coverage | Guardian, test-optimizer |
| lint-checker | Code style and quality | Guardian, security-auditor |
| dependency-analyzer | Map and analyze dependencies | dependency-architect |
| doc-generator | Generate docs from code | documentation-curator |
| git-operations | Safe git operations (commit, PR) | All agents |
| ci-cd-trigger | Trigger CI/CD pipelines | release-manager |
| metrics-collector | Collect build/test/deploy metrics | resource-optimizer |
Specialized Skills
| Skill | Purpose | Used By |
|---|---|---|
| security-scanner | Vulnerability scanning | security-auditor |
| performance-profiler | Code profiling | performance-analyst |
| refactoring-engine | Safe code transformations | refactoring-specialist |
| test-generator | AI-generated tests | test-optimizer |
| changelog-writer | Auto-generate changelogs | release-manager |
| impact-analyzer | Analyze change impact | All agents |
Agent-Skill Interaction Model
┌─────────────────────────────────────────────────────────────────┐
│ Agent-Skill Architecture │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Guardian │ │ Cross- │ │ Orchestra- │ │
│ │ Agent │ │ Cutting │ │ tor │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └─────────────────────┼─────────────────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Skill Layer │ │
│ │ ┌───────────────┐ │ │
│ │ │ code-search │ │ │
│ │ │ build-runner │ │ │
│ │ │ test-runner │ │ │
│ │ │ lint-checker │ │ │
│ │ │ ... │ │ │
│ │ └───────────────┘ │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌──────────▼──────────┐ │
│ │ Mono-Repo │ │
│ │ (Code + Data) │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Human-Agent Collaboration
Human Roles in the Ecosystem
┌─────────────────────────────────────────────────────────────┐
│ Human Oversight Layers │
├─────────────────────────────────────────────────────────────┤
│ │
│ Tech Leads │
│ ├─ Review architecture decisions (AI-proposed) │
│ ├─ Set priorities for agents │
│ └─ Handle edge cases and exceptions │
│ │
│ Product Managers │
│ ├─ Define feature requirements │
│ ├─ Review sprint plans (AI-generated) │
│ └─ Make trade-off decisions │
│ │
│ SRE / Operations │
│ ├─ Review deployment plans (AI-generated) │
│ ├─ Handle production incidents │
│ └─ Set SLOs and error budgets │
│ │
│ Security Team │
│ ├─ Review security audit findings │
│ ├─ Approve security-critical changes │
│ └─ Define security policies │
│ │
└─────────────────────────────────────────────────────────────┘
Decision Escalation
AI Agent Decision
│
▼
┌─────────────────┐
│ Can AI decide? │
└────────┬────────┘
│
┌────┴────┐
│ │
Yes No
│ │
▼ ▼
┌────────┐ ┌─────────────┐
│ Execute│ │ Escalate to │
│ │ │ Human │
└────────┘ └──────┬──────┘
│
▼
┌─────────────────┐
│ Which Human? │
├─────────────────┤
│ Architecture → │ Tech Lead
│ Security → │ Security Team
│ Priority → │ Product Manager
│ Production → │ SRE
└─────────────────┘
Agent Communication Protocol
Inter-Agent Messaging
Agent Message Format:
{
"from": "tidb-guardian",
"to": "dependency-architect",
"type": "dependency_change_detected",
"payload": {
"component": "products/tidb",
"dependency": "github.com/pingcap/kvproto",
"change": "version_update",
"old_version": "v0.0.0-20250101",
"new_version": "v0.0.0-20260228",
"breaking": false,
"requires_propagation": true
},
"timestamp": "2026-02-28T16:00:00Z"
}
Event Bus
┌─────────────────────────────────────────────────────────────┐
│ Agent Event Bus │
├─────────────────────────────────────────────────────────────┤
│ │
│ Events: │
│ - code_committed │
│ - pr_created │
│ - pr_merged │
│ - test_failed │
│ - build_failed │
│ - dependency_updated │
│ - security_vulnerability_detected │
│ - performance_regression_detected │
│ - tech_debt_identified │
│ - documentation_outdated │
│ │
│ Subscription Model: │
│ - Each agent subscribes to relevant events │
│ - Events trigger agent actions │
│ - Actions may generate new events (chain reaction) │
│ │
└─────────────────────────────────────────────────────────────┘
Daily Agent Workflow
Example: A Day in the Life
00:00 ──► dependency-architect runs nightly dependency scan
└─► Finds security update for tidb dependency
└─► Creates PR with update
└─► Notifies tidb-guardian
02:00 ──► tidb-guardian reviews PR
└─► Runs tests
└─► Checks compatibility
└─► Approves (auto-merge if non-breaking)
06:00 ──► test-optimizer analyzes test coverage
└─► Finds gap in products/tidb/storage
└─► Generates new tests
└─► Creates PR
09:00 ──► Humans start workday
└─► Review overnight agent activities
└─► Handle escalations
└─► Set priorities for the day
12:00 ──► sprint-planner analyzes velocity
└─► Updates sprint forecast
└─► Notifies PM of potential delays
15:00 ──► refactoring-specialist identifies duplication
└─► Proposes shared library extraction
└─► Creates design doc
└─► Requests human review
18:00 ──► documentation-curator syncs docs with code
└─► Auto-generates API docs
└─► Updates changelog
23:00 ──► mono-repo-orchestrator generates daily report
└─► System health summary
└─► Agent activity summary
└─► Pending human decisions
Metrics & KPIs
Agent Performance
| Metric | Target | Measurement |
|---|---|---|
| PR Review Time | <1 hour | Time from PR creation to first review |
| Auto-Merge Rate | >60% | % of PRs merged without human intervention |
| Test Coverage | >80% | Code coverage across all components |
| Vulnerability MTTR | <24 hours | Time to fix security issues |
| Build Success Rate | >95% | % of builds that pass |
| Agent Decision Accuracy | >90% | % of AI decisions that are correct |
System Health
| Metric | Target | Measurement |
|---|---|---|
| Tech Debt Ratio | <10% | Tech debt / total code |
| Documentation Freshness | <7 days | Time since last doc update |
| Dependency Freshness | <30 days | Age of oldest dependency |
| Cross-Component Coupling | Decreasing | Dependency graph complexity |
Implementation Phases
Phase 1: Guardian Agents (Week 1-4)
- Build agent framework
- Implement tidb-guardian (pilot)
- Integrate core skills (code-search, build-runner, test-runner)
- Deploy to mono-repo
Phase 2: Cross-Cutting Agents (Week 4-8)
- Implement dependency-architect
- Implement test-optimizer
- Implement security-auditor
- Build event bus
Phase 3: Orchestrator Agents (Week 8-12)
- Implement mono-repo-orchestrator
- Implement release-manager
- Implement sprint-planner
- Human oversight workflows
Phase 4: Full Autonomy (Week 12+)
- Enable auto-merge for non-breaking changes
- Enable automated refactoring
- Enable AI-driven release planning
- Continuous optimization
Agent Configuration
Example: tidb-guardian config
agent:
name: tidb-guardian
model: qwen3.5-plus
component: products/tidb
permissions:
- read: products/tidb/*
- write: products/tidb/*
- create_pr: true
- merge_pr: true # Non-breaking only
skills:
- code-search
- build-runner
- test-runner
- lint-checker
- doc-generator
triggers:
- code_committed
- pr_created
- dependency_updated
- test_failed
escalation:
architecture: @tidb-architect
security: @security-team
breaking_change: @tidb-leads
schedule:
daily_health_check: "02:00 UTC"
weekly_refactor_proposal: "Monday 00:00 UTC"
Conclusion
The mono-repo is not just a code repository. It’s a living ecosystem where:
- Guardian Agents maintain individual components
- Cross-Cutting Agents optimize across boundaries
- Orchestrator Agents coordinate and make high-level decisions
- Skills provide the tools for agents to interact with code
- Humans provide oversight, handle exceptions, and set direction
This is the foundation for General Relativity: AI owns the full engineering lifecycle, with humans focusing on strategy and creativity.
“The goal is not to replace humans. The goal is to free humans from routine work, so they can focus on what matters.”