NEXUS — Organizational Intelligence System

Your org has made thousands of decisions. NEXUS knows where every one lives in your architecture — and acts before the next agent makes the same mistake your team made in September.

Comment

Inspiration

Agents are shipping code faster than any engineering org can govern.

A junior developer asks: "What calls this function?" The answer lives across fourteen repositories, six teams, three time zones. Nobody knows. She implements the change. Three services break in production.

A platform architect needs to deprecate a library. She sends an email to forty-three teams. Eleven don't respond. One team never got it — they joined after the email was sent. Six months later the library is still running. A new service was just built against it last week. The migration coordinator missed teams from transitive dependencies nobody knew about.

An engineering manager splits a team on a spreadsheet. Three weeks later two services have no clear owner. The actual dependency graph said this would happen. Nobody looked at it.

A senior engineer returns from three months of maternity leave. Her team shipped four features while she was gone. Two architectural decisions were made that affect services she owns. One migration started that needs her. She has a one-hour catchup meeting — then she's expected to be productive.

A new engineer joins. Two weeks in, she still does not know who to ask about the auth module, or why there is a comment that says DO NOT TOUCH when the person who wrote it left in January.

These are not knowledge problems. They are coordination problems. The knowledge exists — in your codebase, your commit history, your call graph. The problem is that nothing connects it to the people who need it and acts on it automatically.

GitLab Orbit changed what is possible. A live traversable knowledge graph of your entire SDLC: code definitions, call relationships, contributors, pipelines, vulnerabilities — all connected across every project in your org.

We built NEXUS to answer one question: what happens when you anchor every architectural decision to that graph and let autonomous agents act on it?

The answer: migrations coordinate themselves. Reorgs get simulated before anyone moves. Developers get full org context before writing a line. Engineers returning from leave get a personalized catch-up brief. And agents govern themselves.

What it does

NEXUS is a multi-agent flow system on the GitLab Duo Agent Platform. It uses GitLab Orbit to connect every architectural decision to the specific code it governs — and takes autonomous action when those decisions matter.

When NEXUS runs, real things happen in GitLab that didn't exist before: issues are created across teams, migrations are coordinated, reorgs are simulated, and the next developer who touches governed code sees the decision that should stop them from repeating a mistake.

This is not a chatbot. NEXUS does the work.

Your situation What NEXUS does Artifacts created
Developer creates an issue to refactor payments nexus-pre-act queries Orbit for blast radius (11 callers found), searches decision registry, predicts 5 failure modes, generates engineering spec Pre-mortem comment, nexus-pre-act label, consultation sub-issues
MR lands with architectural decisions in the diff nexus-decision-capture extracts decisions using semantic reasoning from diff AND discussion, anchors to Orbit graph nodes Decision comment on MR, wiki pages via nexus sync
Architect needs to deprecate a library across the org nexus-migration-coordinator queries Orbit for every consumer (direct + transitive), creates phased migration plan via topological sort, assigns to SMEs 7 child issues across 2 projects, phased, assigned, linked
Manager wants to split a team into two squads nexus-reorg-simulator queries Orbit for actual ownership (commit history, not org chart), simulates coupling cost change, finds orphaned services Impact report with coordination cost score, recommendations
Engineer returns from maternity leave after 3 months nexus-catchup scans MRs merged during absence, finds decisions captured, locates active migrations needing attention Personalized catch-up brief with prioritized action items
Need to audit what AI agents have been doing nexus-agent-auditor identifies agent-authored changes, computes blast radius, flags unreviewed MRs and governance gaps Permanent audit issue with anomaly report
Anyone asks "What decisions govern auth?" nexus-ask agent searches decision wiki, answers like a teammate who was there Conversational response in Duo Chat
Anyone asks "What happens if I change validate_token?" nexus-impact agent queries Orbit via MCP for callers, cross-references with decision governance 7-caller table with risk-rated verdict
CLI: Need org health score before a leadership meeting nexus stats runs offline, shows health 80/100 Grade B Terminal output or JSON
CLI: Need to preview migration impact before triggering the flow nexus simulate runs topological sort locally with sample data Phased plan with critical path
CLI: Need a dashboard to share with stakeholders nexus dashboard generates self-contained HTML with Mermaid.js HTML file or live GitLab Pages
CI: MR merged to main Pipeline automatically runs nexus sync → wiki updated, nexus dashboard → Pages rebuilt Wiki pages + live dashboard

How GitLab Orbit Powers Everything

Every NEXUS flow uses query_graph and get_graph_schema as native DAP tools — zero-rated, no credits consumed. Orbit provides what no single REST API call can:

Orbit Capability How NEXUS Uses It
CALLS edges on Definition nodes Blast radius — "validate_token is called by 11 functions across 4 services"
AUTHORED edges on MergeRequest nodes SME discovery from real commit history, not stale CODEOWNERS
Vulnerability nodes Security exposure flagged in blast radius — "this caller has an open CVE"
Pipeline nodes CI/CD health — "3 services in your blast radius have failing pipelines"
Cross-project traversal Org-wide consumer mapping — migration coordinator found 14 call sites across 2 projects
User + MergeRequest relationships Reorg simulator computes actual ownership vs org chart

Confirmed working via glab orbit remote query: CALLS traversal on validate_token → 14 nodes, 12 edges across 2 projects.

The Six Flows in Detail

Flow 1: nexus-pre-act — 3 agents: Orbit Scout → Decision Searcher → Pre-Mortem Writer

Step What happens Orbit query
1. Orbit Scout Finds all functions matching issue keywords, traverses CALLS edges for blast radius, finds SMEs via AUTHORED Definition traversal, CALLS edges, User-MergeRequest join
2. Decision Searcher Reads NEXUS-INDEX wiki, semantically matches past decisions (not keyword matching — Claude reasons about failure modes) N/A (wiki read)
3. Pre-Mortem Writer Posts structured pre-mortem: blast radius table, decision conflicts, predicted failure modes, engineering spec N/A (writes comment)

Demonstrated result: Issue "Add Redis caching to auth token validation" → 11 callers found. Implicit conflict detected from is_revoked sibling function — the code was designed to never trust cached auth state, even though nobody wrote that decision down. 5 failure modes predicted including "Revocation Window (2am page)."

Flow 2: nexus-decision-capture — 3 agents: Diff Analyzer → Discussion Extractor → Memory Writer

Step What happens How decisions are extracted
1. Diff Analyzer Reads full MR diff via build_review_merge_request_context Looks for: NEVER/DO NOT comments, caching flags, auth patterns, retry constants
2. Discussion Extractor Reads all MR comments via list_all_merge_request_notes Distinguishes "LGTM" (noise) from "We chose X over Y because Z" (decision)
3. Memory Writer Queries Orbit for Definition nodes of changed files, posts structured decision Anchors decision to Orbit graph nodes, not just file paths

Storage: Decisions are posted as MR comments immediately. nexus sync CLI writes them to wiki pages (NEXUS-DECISION-NNN) via GitLab REST API. Flows cannot write to wiki directly in the DAP environment — we discovered this empirically and built nexus sync as the bridge.

Demonstrated result: Extracted "Never cache validate_token. CACHE_ENABLED = False enforced permanently." Redis TTL identified as rejected alternative. Security-relevant: yes.

Flow 3: nexus-migration-coordinator — 3 agents: Consumer Mapper → Plan Generator → Issue Creator

Step What happens Why this replaces 2 weeks of manual work
1. Consumer Mapper Queries Orbit for every consumer of deprecated target — direct AND transitive via CALLS graph No manual codebase search. No missed transitive consumers
2. Plan Generator Topological sort of consumer graph → dependency-ordered phases, critical path, effort estimates No spreadsheet. Dependency ordering is automatic
3. Issue Creator Creates child issues in each affected project, assigns to Orbit-identified SMEs, links to parent No email chains. No Slack broadcasts. Work lands in team backlogs directly

What this replaces: Email to 43 teams (half don't respond). Shared spreadsheet (outdated by Tuesday). DMs to team leads (3 don't know they're affected because of transitive dependencies). Teams that joined after the announcement. 2 weeks of coordination → 2 minutes.

Demonstrated result: 7 child issues created across 2 projects in 2 phases. @monika_k1 and @rogerkorantenng assigned as SMEs. Critical path: payments-processor → auth-client-wrapper. Bus factor 1 flagged. Race condition in refresh_token flagged separately.

Flow 4: nexus-reorg-simulator — 3 agents: Ownership Mapper → Dependency Mapper → Reorg Simulator

Step What happens Why a spreadsheet can't do this
1. Ownership Mapper Queries Orbit AUTHORED edges → actual ownership from commit history, bus factor per service The org chart says Alice owns auth. Orbit says she hasn't committed in 90 days
2. Dependency Mapper Queries CALLS edges between projects → coupling strength per pair (strong ≥10, medium 3-9, weak 1-2) No human can trace 13 call edges across 5 services manually
3. Reorg Simulator Overlays proposed team assignments against both graphs → coordination cost delta, ownership gaps, orphaned services A spreadsheet can't compute that splitting Team Alpha increases cross-team coupling from 0 to 1

Demonstrated result: validate_token handles 54% of all CALLS edges — universal dependency hub. src/notifications/sender.py orphaned (calls both squads, assigned to neither). Coordination cost: 0 → 1 cross-team coupled pair. Recommendation: adjust before proceeding with 4 specific changes.

Flow 5: nexus-catchup — 3 agents: Change Scanner → Decision Scanner → Catchup Writer

Step What happens Why this saves 2 weeks of catching up
1. Change Scanner Finds MRs merged during absence, categorizes into architectural/feature/fix No reading 50 MR threads manually
2. Decision Scanner Reads NEXUS-INDEX for decisions captured in that period, finds active migrations and reorg reports No asking 5 colleagues to repeat context they already explained
3. Catchup Writer Generates structured brief: top 3 things that matter, decisions made, action items, who to talk to, reading list One issue comment replaces 2 weeks of Slack archaeology

Demonstrated: 7 prioritized action items (IMMEDIATE/THIS WEEK), 3 people to talk to with specific reasons, 4-item reading list in priority order, Team Alpha lead (reorg proposal needs your input)

Flow 6: nexus-agent-auditor — 3 agents: Activity Tracker → Anomaly Detector → Governance Reporter

Timed with GitLab's Transcend AI Governance announcement. NEXUS governs itself and other agents.

Demonstrated result: Detected MR !1 mergeable with zero human reviewers (MEDIUM). Activity tracker polling loop flagged (LOW-MEDIUM). Permanent audit issue created with labels governance, audit, nexus.

nexus-cli: The Offline Product Layer

Runs completely offline. No Orbit credits. No DAP environment. 63 passing tests. Judges can evaluate with pip install and zero GitLab tokens.

Command What it does Why it exists
nexus sync Reads MR decision comments → writes wiki pages via REST API Flows can't write wiki. This is the bridge
nexus validate Checks decision format, DFS cycle detection on dependency graph Catch circular dependencies before they corrupt the registry
nexus stats Org health score (80/100 Grade B), coverage, carbon impact Quick offline health check before a leadership meeting
nexus simulate Migration plan with topological sort, critical path, effort estimate Preview impact before triggering the full migration flow
nexus dashboard Self-contained HTML: Mermaid.js decision graph, coverage map, security inventory Share with stakeholders. Live at https://39330880-6ff71c.gitlab.io/

CI/CD Pipeline: NEXUS Runs Itself

Stage When What it does Why it matters
validate Every push DFS cycle detection on decision dependencies Catches circular dependency chains before they corrupt the registry
test Every push 63 tests: topological sort, carbon math, coordination cost scoring Ensures algorithms NEXUS flows depend on are correct
sync Every merge to main nexus sync runs automatically Decision flows from MR comment → CI → wiki. No manual step. Governance loop closes automatically
pages Every merge to main Dashboard rebuilt and deployed https://39330880-6ff71c.gitlab.io/ always reflects current state

The result: Developer merges MR → Decision Capture extracts decision → CI syncs to wiki → dashboard rebuilds → Pre-Act reads the new decision on the next issue. Fully automated. No stale data.

Sustainability: Decisions Have a Carbon Footprint

Every decision includes a carbon impact estimate. When a decision prevents a bad pattern, the avoided compute is estimable:

  • "Never cache auth token responses" → prevents Redis infrastructure layer → ~120 kWh/month saved
  • "Use fixed retry intervals" → prevents thundering herd cascades → thousands of redundant requests avoided
Metric How it's calculated
kWh/month saved Claude reasons about compute implications from diff context
kg CO₂/month IEA global average grid intensity: 0.4 kg CO₂/kWh
Trees equivalent EPA figure: 21 kg CO₂ absorbed per mature tree per year

Order-of-magnitude estimates, not accounting-grade. The goal: make energy cost visible in architectural trade-offs engineers are already making.

How we built it

Architecture

┌──────────────────────────────────────────────────────────┐
│                      NEXUS SYSTEM                        │
│                                                          │
│  6 Flows (18 agents)          2 Agents    3 Skills       │
│  ┌─────────────────────┐     ┌─────────┐ ┌──────────┐  │
│  │ nexus-pre-act       │     │nexus-ask│ │orbit-    │  │
│  │ nexus-decision-     │     │nexus-   │ │queries   │  │
│  │   capture           │     │impact   │ │nexus-    │  │
│  │ nexus-migration-    │     └────┬────┘ │impact    │  │
│  │   coordinator       │          │      │skill     │  │
│  │ nexus-reorg-        │          │      └──────────┘  │
│  │   simulator         │          │                     │
│  │ nexus-catchup       │    Duo Chat               │
│  │ nexus-agent-auditor │    (interactive)           │
│  └──────────┬──────────┘                                │
│             │ query_graph (zero-rated DAP tool)          │
│             ▼                                            │
│     GitLab Orbit Knowledge Graph                        │
│  (Definition · File · User · MR · Pipeline · Vuln)      │
│                                                          │
│  nexus-cli (offline, 63 tests)                          │
│  ┌──────────────────────────────────────────────┐       │
│  │ sync → validate → stats → simulate → dashboard│       │
│  │ GitLab REST API · no Orbit · runs in CI       │       │
│  └──────────────────────────────────────────────┘       │
│                                                          │
│  CI/CD: validate → test → sync → pages                  │
│  Live dashboard: https://39330880-6ff71c.gitlab.io/     │
└──────────────────────────────────────────────────────────┘

Notable Engineering Decisions

DFS Cycle Detection in Decision Dependencies Decisions can declare Blocks and Depends on relationships, forming a dependency graph. nexus validate runs DFS-based cycle detection — a Decision #1 blocking #2, #2 blocking #3, #3 blocking #1 would silently corrupt downstream enforcement. We catch this at validate time, not runtime.

Topological Sort for Migration Phase Ordering The Migration Coordinator computes migration order via Kahn's algorithm variant. Service B must migrate before Service A if A depends on B's migrated interface. Services in the same phase can migrate simultaneously — minimizing calendar time while respecting dependency ordering. Critical path = longest phase chain.

Semantic Decision Conflict Detection The Decision Searcher uses Claude's semantic reasoning, not keyword matching or embedding similarity. "Redis token cache" and "in-memory auth dict" are the same failure mode — both bypass real-time revocation checks. In testing: "Add Redis caching" correctly surfaced the is_revoked design intent as a conflict even though "Redis" didn't appear anywhere in the existing decision.

Coordination Cost Scoring The Reorg Simulator computes a Coordination Cost Score — the number of cross-team strongly-coupled service pairs before and after the restructure. Positive delta = reorg makes coordination worse. Gives managers an Orbit-grounded metric instead of gut feeling.

Multi-Format MR Note Parser Decision Capture flows produced decisions in different markdown formats across iterations. Rather than requiring a fixed format, nexus sync parses all of them — markdown tables, plain text, inline key-value. Strips bold, removes links, cleans backticks. Resilient to LLM output variation.

Wiki Sync via REST API Flows cannot write to wiki directly in the DAP environment — create_wiki_page and GraphQL wikiPageCreate mutations were unavailable. Rather than treating this as a blocker, we built nexus sync as an explicit bridge: flows handle real-time intelligence, CLI handles durable persistence. The CI pipeline runs nexus sync on every merge — closing the loop automatically.

Orbit Query DSL Discovery The correct format uses relationships (not edges), entity (not type). Documented working recipes in skills/nexus-orbit-queries/SKILL.md — confirmed against live data. A reusable community contribution.

Orbit MCP for Custom Agents Custom agents cannot access query_graph directly (DAP-internal tool). Solution: Orbit MCP endpoint (https://gitlab.com/api/v4/orbit/mcp) with invoke_command → query_graph via .gitlab/duo/mcp.json config.

Tech Stack

  • GitLab Duo Agent Platform — 6 flows (18 agents), 2 standalone agents
  • GitLab Orbit — query_graph, get_graph_schema (zero-rated DAP), invoke_command via MCP
  • Orbit MCP — https://gitlab.com/api/v4/orbit/mcp for custom agent access
  • glab orbit remote query — CLI testing and skill development
  • Anthropic Claude Sonnet 4.6 — semantic reasoning across all flows
  • GitLab REST API — nexus sync wiki operations
  • Python — nexus-cli (click, rich, requests, pytest)
  • Mermaid.js — decision dependency graph visualization
  • GitLab CI/CD — validate → test → sync → pages pipeline
  • GitLab Pages — live dashboard at https://39330880-6ff71c.gitlab.io/

Challenges we ran into

Challenge How we solved it
Wiki write tools unavailable in DAP Built nexus sync CLI as a REST API bridge. CI runs it on every merge — turns limitation into cleaner architecture
Custom agents can't access query_graph Discovered Orbit MCP endpoint + invoke_command wrapper. Documented in .gitlab/duo/mcp.json
Orbit query DSL took iteration edges vs relationships, type vs entity. Used glab orbit remote query for local testing, documented recipes in skill
Agent loops (repeated tool calls) Explicit "call exactly once... stop" in every prompt. Agent Auditor now detects this pattern in production
Multi-format decision parsing Multi-pattern parser: markdown tables + plain text + inline key-value. Resilient to LLM output variation
Decision Capture flow timeout Removed Orbit queries from Diff Analyzer (too slow). Moved to Memory Writer where full context is available

Accomplishments that we're proud of

  • 6 flows with 18 agents that create real GitLab artifacts — issues, wiki pages, migration plans, governance reports, catch-up briefs
  • 63 passing tests — DFS cycle detection, topological sort, coordination cost scoring, carbon math, dashboard generation
  • Cross-project migration — 7 child issues across 2 projects in under 2 minutes, replacing 2 weeks of email chains and spreadsheets
  • Reorg simulation from live Orbit data — coordination cost delta computed from actual commit history and call graph. Not org charts. Not gut feeling
  • NEXUS audits itself — Agent Auditor flagged NEXUS's own flows for an unreviewed MR. The system is honest about its own behavior
  • Self-maintaining CI/CD — governance loop closes automatically on every merge. Wiki syncs. Dashboard rebuilds. No manual steps
  • Live dashboard — https://39330880-6ff71c.gitlab.io/ — visit right now, no setup needed
  • Orbit query recipes — skills/nexus-orbit-queries/SKILL.md documents confirmed-working DSL for the community
  • Maternity leave catch-up — a flow nobody else has built. The returning engineer problem is real and unsolved

What we learned

  • Flows are more powerful than agents for autonomous action — agents answer questions, flows do work. The distinction matters
  • Orbit's graph is the key differentiator — CALLS edges enable blast radius analysis REST APIs cannot replicate. Every NEXUS flow depends on graph traversal
  • Semantic reasoning beats keyword matching — Claude catches failure mode equivalence that embeddings miss. "Redis cache" and "in-memory dict" are the same pattern when revocation bypass is the failure mode
  • The CLI is what makes it feel like a product — nexus validate with DFS cycle detection and nexus stats showing Grade B/80 is what makes judges say "this could ship"
  • Platform limitations are architecture opportunities — wiki write unavailability led to cleaner nexus sync design. Agent Orbit limitation led to MCP discovery and community skill contribution
  • CI closes the governance loop — without automated sync and pages deployment, NEXUS requires manual operation. The pipeline is what makes it self-maintaining

What's next for NEXUS

  • MR Guardian — 5-layer MR review: decision conflicts + promise verification + Orbit blast radius + vulnerability cross-reference + SME auto-assignment
  • SME Finder flow — @nexus who owns X? → live expertise map from Orbit with evidence: "Alice: 47 commits, 12 architectural, last active 3 days ago"
  • Auto-trigger on MR merge — Decision Capture on merge event closes the loop without manual assignment
  • Decision graph in Orbit — surface NEXUS decision nodes directly in the Orbit Data Explorer
  • Multi-project wiki — group-level decision registry shared across all projects
  • nexus migrate cold-start — scan past MR history to seed the registry retroactively
  • Real carbon measurement — cloud provider API integration for actual compute metrics

Try it

git clone https://gitlab.com/gitlab-ai-hackathon/transcend/39330880.git nexus
cd nexus
pip install ./nexus-cli

nexus dashboard --output demo.html    # open in browser — no token needed
nexus stats                            # org health score
nexus simulate                         # migration plan preview
nexus validate .                       # DFS cycle detection

Live dashboard: https://39330880-6ff71c.gitlab.io/ Live project: https://gitlab.com/gitlab-ai-hackathon/transcend/39330880 Wiki decisions: https://gitlab.com/gitlab-ai-hackathon/transcend/39330880/-/wikis/NEXUS-INDEX

Built With

  • anthropic-claude
  • claude-sonnet-4.6
  • click
  • dfs-cycle-detection
  • gitlab-ci-cd
  • gitlab-duo-agent-platform
  • gitlab-orbit
  • gitlab-pages
  • gitlab-rest-api
  • gitlab-wiki
  • glab-cli
  • mermaid.js
  • orbit-mcp
  • pytest
  • python
  • requests
  • rich
  • topological-sort
  • yaml
Share this project:

Updates