Universal Agent OS

Project Story Inspiration Most agent-driven repositories fail in predictable ways: they lack a stable startup interview, a durable planning surface, and reliable handoffs between sessions. The GitLab Transcend Hackathon's mission to "Give AI true context" deeply resonated with this problem. We realized that true context isn't just about reading code—it's about strict governance, boundaries, and collective memory. We were inspired to use the GitLab Orbit Knowledge Graph not just as a passive reading tool, but as an active enforcer of architectural decisions.

What it does Not another coding agent. A governance layer for GitLab Duo agents that turns Orbit context into enforceable plans, memory, gates, and reviews.

Universal Agent OS is a consultation-first governance framework for AI coding agents. It acts as a "governance compiler," replacing chaotic, trial-and-error AI loops with a Predictable, Secure, and Collective Memory-Driven Generation Lifecycle.

Instead of jumping straight into coding, agents governed by this OS must:

Query the Orbit Knowledge Graph: The agent actively traverses the Knowledge Graph via the Orbit API to pull active MRs, pipeline statuses, security findings, and source code dependencies. Conduct a "Phase-0 Alignment Contract": Using the rich SDLC data pulled from Orbit, it conducts a strict scoping interview before any code is generated. Update Collective Memory: It logs its decisions and identified code-graph constraints into AGENT_MEMORY_AND_LESSONS.md. Enforce Integrity Locks (IL): It follows strict rules to prevent infinite loops and scope drift. How we built it We integrated Universal Agent OS directly into the GitLab Duo Agent Platform using the Showcase Track guidelines, deeply leveraging the Orbit Knowledge Graph.

AI Catalog Metadata & CI/CD Sync: We structured our agent definitions (universal-agent-os.yml) specifically for the GitLab AI Catalog and integrated a catalog-sync CI pipeline that automates GraphQL registration. Its system prompt is heavily hardened to execute Orbit blast-radius analysis before coding. Custom Orbit Flow: We orchestrated a .gitlab/duo/agent-os-flow.yaml workflow that extracts requirements and directly queries the Orbit API (via curl and GraphQL) to load the Collective Memory context and security findings before executing the Phase-0 alignment. Custom Skill: We built skills/agent-os-memory/SKILL.md to allow GitLab Duo to dynamically read/write to the 4 collective memory pillars based on the source graph. Challenges we ran into The biggest challenge was translating a "bureaucratic" governance philosophy into automated CI/CD and AI Agent steps. Unstructured prompting is easy, but forcing an AI to stop, query the Orbit Knowledge Graph for real-time MR and security status, plan, and log its mistakes requires carefully engineered boundaries. We had to move our constraints out of standard prompts and deep into the AI Catalog's System Prompts to ensure zero-leak governance.

What's Next (Production Status) This repository is not a prototype; it is a fully functional, production-ready governance layer that you can inject into any repository today. It actively secures agent behavior and enforces documentation using GitLab Duo. For our long-term roadmap, we plan to publish a standardized agent-os init NPM package and a public gate-run toolchain to make team onboarding even faster. If you want a long-lived agent-built repo to stay legible and governable without accumulating technical debt, Universal Agent OS is the answer.

Built With

• bash
• express.js
• gitlab-ai-catalog
• gitlab-ci-cd
• gitlab-duo
• gitlab-orbit
• graphql
• markdown
• node.js
• powershell
• pytest
• python
• yaml