Orbit Feature Architect

Plan any feature in seconds using real codebase context from GitLab Orbit not generic AI advice.

Comment

Inspiration

Every developer knows this moment: you receive a ticket that says "implement OAuth login" and you open a repository with 50,000 lines of code and no idea where to start.

You spend two hours reading files, asking teammates, and tracing imports manually just to figure out which files to touch and who to ask. Generic AI tools make this worse, not better. They produce the same boilerplate plan regardless of your actual codebase:

"Create a User model. Add session management. Write tests."

That advice is true for every project and useful for none of them.

GitLab Orbit changes this. It indexes your entire SDLC files, functions, merge requests, contributors, pipelines — as a queryable knowledge graph. The question was: could an agent use that graph to answer the question every developer actually needs answered?

"Where exactly do I make this change in THIS codebase?"

That question is what inspired Orbit Feature Architect.

What it does

Orbit Feature Architect is a GitLab Duo Agent that takes a plain-English feature request and returns an implementation plan grounded entirely in real codebase data from GitLab Orbit.

It has three capabilities:

Plan: Feature implementation roadmap

Plan: implement OAuth login for my-group/my-project

Traverses Orbit to find real files, real functions, real MR history, and real contributors. Returns a dependency-ordered implementation plan with risk flags specific to your repository.

Impact: Blast radius analysis

Impact: src/auth/login.py in my-group/my-project

Finds every file that imports the target, every function that calls into it, recent MR activity, and a risk score. Tells you what breaks before you change it.

Compare: Gap analysis

Compare: implement OAuth login for my-group/my-project

Maps what already exists in your codebase against what the feature requires. Shows exactly what to build versus what to reuse including real bugs in existing code that would affect the new feature.

Zero hallucinations. Every claim comes from Orbit.

In one real test, the agent found:

  • GitLabClient in gitlab_client.py already uses PRIVATE-TOKEN header — must switch to Bearer for OAuth consistency, not create a new auth module from scratch
  • A pre-existing db.IntegrityError bug in register() that would silently break OAuth user provisioning
  • Two disconnected session systems that would cause a production bug if not resolved before OAuth was added
  • Six items from a generic OAuth plan that already existed in the codebase and required zero new code

A generic planner would say: "Create an OAuth module."

Orbit Feature Architect said: "Modify GitLabClient in gitlab_client.py — the PRIVATE-TOKEN header specifically because RemoteGraphSource already uses Bearer auth and both must stay consistent. And your GL_TOKEN env var is load-bearing in CI, so the OAuth fallback must be strictly additive."

How I built it

Orbit Feature Architect is built on the GitLab Duo Agent Platform using GitLab Orbit as its primary data source.

The agent uses four native Orbit tools available in the platform:

  • Orbit: Query Graph: traverses the knowledge graph
  • Orbit: Get Graph Schema: understands available entities and relationships
  • Orbit: List Commands: discovers available graph operations
  • Orbit: Invoke Command: executes specific graph operations

When a user submits a feature request, the agent follows this sequence:

1. Extract 2-4 technical keywords from the request
2. Query Orbit for File entities matching those keywords
3. Traverse DEFINES edges → real function and class names
4. Traverse HAS_DIFF edges → MR history on those files
5. Traverse AUTHORED edges → real contributors
6. Reason over complete graph data → grounded implementation plan

The system prompt enforces strict grounding rules the agent is explicitly prohibited from inventing file names, function names, or contributor names. Every claim must come from an Orbit query result. If Orbit returns no data for a keyword, the agent says so explicitly rather than hallucinating an answer.

The repository includes a SKILL.md file with Orbit query recipes and DSL guidance aligned with the official GitLab Orbit skill patterns, and an AGENTS.md file that defines agent behavior rules for flows and additional context.

Tech stack: GitLab Duo Agent Platform, GitLab Orbit, glab CLI, Python, Flask, JWT, SQLite, GitLab CI/CD

Challenges i ran into

Understanding the platform boundary. Early versions tried to invoke glab orbit remote query shell commands directly from the skill which is not how the platform works. Duo Chat can read skill instructions but cannot execute terminal commands. The breakthrough came from discovering that the Duo Agent Platform exposes Orbit as native tools the agent can call directly, without any shell access.

Orbit Query DSL format. The Query DSL uses different JSON shapes for single-node versus multi-node traversal. Early queries returned HTTP 400 errors due to incorrect column specifications. Reading the official recipes.md from the installed Orbit skill and testing each query pattern manually resolved these issues.

Data sparsity on a new project. Testing against an empty repository produces unimpressive output. The solution was populating the demo repository with real Python code so Orbit could index real definitions and relationships, and identifying existing participant repositories in the hackathon namespace with richer codebases for comparison.

Feature flag discovery. Orbit Remote is gated by the knowledge_graph feature flag. Understanding which level of the group hierarchy the flag applies to and verifying it was already enabled for the hackathon namespace required working through the glab CLI status commands and reading the prerequisites documentation carefully.

Accomplishments that i am proud of

The agent found a real pre-existing bug in our demo codebase — db.IntegrityError referenced in register() when the correct reference is sqlite3.IntegrityError without being told to look for bugs. It found it by reading the actual source code through Orbit and reasoning over what it saw. That is the core capability working as intended.

The Compare mode produces a table that explicitly contrasts what a generic AI would recommend against what Orbit actually found in the codebase. In one test it identified six items from a standard OAuth implementation plan that already existed and required zero new code. Showing that contrast clearly is something no generic planning tool can do.

The Blast Radius analysis correctly identified that session.py has zero production callers today but will become load-bearing the moment OAuth is wired in and flagged that risk proactively. That kind of forward-looking dependency analysis is only possible with graph traversal.

What we learned

GitLab Orbit's knowledge graph is significantly more powerful than its surface documentation suggests. The combination of SDLC data merge requests, contributors, pipelines with source code structure definitions, imports, call graphs creates a uniquely grounded context layer that no external AI tool can replicate, because no external tool has authorized access to this depth of repository relationship data.

The most important insight: Orbit does not just answer questions about code. It answers questions about the relationship between code and the people and processes surrounding it. Who last touched this file, which MRs changed it, which pipelines run against it that SDLC context is what transforms a generic plan into an actionable one.

The agent platform's native Orbit tool integration is the right abstraction level. Building a skill that teaches the agent how to use Orbit's built-in tools rather than trying to build a wrapper around the REST API produces better results with significantly less complexity.

What's next for Orbit Feature Architect

Pipeline-aware planning. Incorporate Orbit's CI/CD graph data to show which pipelines will trigger on each changed file and estimate test runtime impact before a single line of code is written.

Cross-project blast radius. Orbit indexes entire groups. A future version could trace blast radius across every project in an organization that shares a dependency answering "if I change this library, what breaks across all 50 of our services?"

Developer Flow integration. Connect Orbit Feature Architect's planning output directly to GitLab's Developer Flow so the implementation plan automatically becomes the context for the coding agent that executes it closing the loop from planning to implementation in a single workflow.

Built With

  • agent
  • gitlab-ci/cd
  • gitlab-duo-agent-platform
  • gitlab-orbit-knowledge-graph
  • glab-cli
  • python-(demo-codebase)
  • skill.md-skill-definition
  • yaml
Share this project:

Updates