Living Architecture Agent

Inspiration

Developer READMEs go stale the moment architecture changes. Nobody updates diagrams manually - they're outdated before the MR is even reviewed.

What it does

Triggers on every MR merge, queries GitLab Orbit's knowledge graph for real component relationships, passes them to Claude Sonnet 4.6, and auto-commits an updated Mermaid.js architecture diagram directly into the README

How we built it

Built on GitLab Duo Agent Platform using a custom flow (architecture_flow.yml), an Agent Skill (SKILL.md) for reusable diagram expertise, orbit_client.py calling the real Orbit REST API (POST /api/v4/orbit/query), and diagram_generator.py for precise README marker injection. Published to AI Catalog

Challenges we ran into

• Orbit API is experimental - built a mock fallback for when it's unavailable
• Preventing infinite CI loops when the agent commits back to main ([skip ci])
• Keeping Mermaid output clean - no double fences, no hallucinated syntax

Accomplishments that we're proud of

• Full end-to-end automation: MR merge → Orbit query → Claude → README commit
• Zero developer effort after setup
• Reusable /living-architecture slash command via Agent Skill

What we learned

GitLab Duo Agent Platform is powerful but the boundary between CI execution and Duo agent execution requires careful design. Orbit's graph traversal API is genuinely useful for understanding real codebase relationships. Learnt to create skills for the agent to build upon.

What's next for Living Architecture Agent

• Multi-file diagram support (one per service/module)
• Slack/Teams notification when diagram updates
• Drift detection - alert when README diagram doesn't match actual code
• (also controls for gitlab README since the current file only supports static version interactive controls to move aroynd the diagram and to be able to zoom in and out)

Built With

• gitlab
• gitlab-duo
• gitlab-orbit
• python
• skills