## Background The Knowledge Graph (Orbit) team has built a 135K-line Rust codebase in which roughly 95% of the code was generated by AI coding agents. A 4-person core team produced 259 MRs across multiple repos in about 2 weeks. The engineers applied structured agentic engineering practices, not ad hoc prompting, but rather deliberate guardrails, agent context files, custom skills, and CI enforcement. Read more here: https://docs.google.com/document/d/1NPTAtoikQvhuyBi456pI4was9YYaq240JizI-drfKto/edit?tab=t.0#heading=h.3obbbykezhyl Other teams at GitLab have expressed interest in understanding and replicating these practices. This issue documents what already exists in the knowledge-graph repo and what remains to be done to make it a reference implementation for agentic engineering at GitLab. ## What already exists The knowledge-graph repo has built up agentic engineering infrastructure over approximately 4 weeks: - `AGENTS.md` and `CLAUDE.md` with CI-enforced sync (`agent-file-sync-check` job) providing architecture context, development workflow, and code quality standards - skills like: `debug-clickhouse-queries`, `related-repositories`, `remove-llm-comments` - GitLab Duo MR review instructions with 3 specialized AI reviewers (security, performance, logging security) - Conventional commit enforcement via commitlint on MR titles - Documentation linting with markdownlint, Vale (50+ `gitlab_base` rules), and lychee link checking - Comprehensive CI with 15+ jobs across lint, security, test, build, deploy, and release stages - Security tooling including cargo-audit, cargo-deny, cargo-geiger, and Semgrep SAST - Structured issue and MR templates with auto-labeling - Semantic release with automated changelog and Docker image tagging - `mise.toml` with version-pinned tools and task definitions ### Relevant MRs that built this infrastructure - !5 chore: add duo review instructions (Jan 24) - !23 docs: add AGENTS.md for AI agent context (Jan 25) - !19 feat: add related-repositories SKILL (Jan 25) - !32 feat: add etl-engine AGENTS.md (Jan 25) - !75 chore: add minimal comments guideline (Jan 27) - !178 feat(ci): add sync check between AGENTS.md and CLAUDE.md (Jan 31) - !266 ci: add markdown linting with markdownlint, Vale, and lychee (Feb 18) ## What remains to be done - [x] Move design documents from the handbook into the repo (in progress) - [x] Add skills for design document validation and keeping them current - [x] Add ADR (Architecture Decision Record) tracking via automated skills - [x] Create PRD (Product Requirements Document) templates that agents can validate against - [x] Add test case generation skills that derive from PRDs - [x] Improve AGENTS.md with more detailed architectural guidance for brownfield codebases - [x] Document the agentic engineering practices for other teams to adopt - [x] Add a skill for ontology-driven test generation - [x] Explore continuous agent loops for maintaining documentation freshness (inspired by the Ralph pattern) ## Lessons from OpenAI's Harness engineering OpenAI built an internal product with 0 lines of manually-written code over 5 months, resulting in \~1M lines of code, 1500 PRs, and 3 engineers. They treat AGENTS.md as a table of contents, not an encyclopedia. Repository knowledge lives in structured `docs/` directories rather than a single monolithic file. Architecture is enforced mechanically via custom linters and structural tests, not documentation alone. They also run recurring "garbage collection" agents that scan for deviations from intended patterns and open cleanup PRs. Agent legibility is the design goal: anything the agent can't access in-context effectively doesn't exist. To support this, they continuously push context into the repo. Slack discussions, architectural decisions, and product specs all get encoded as versioned artifacts. We already do this with [orbit-artifacts](https://gitlab.com/gitlab-org/orbit/documentation/orbit-artifacts), where offsite transcripts and session notes are stored as versioned markdown alongside the code. ## Inspiration and references We are drawing from several sources in the agentic engineering space. [Harness Engineering at OpenAI](https://openai.com/index/harness-engineering/) describes OpenAI's approach to scaling engineering with AI agents. [Ralph](https://github.com/snarktank/ralph) ([blog post](https://ghuntley.com/ralph/)) is a bash-loop technique for autonomous AI agent iterations. It uses fresh context per iteration, git-based memory via `progress.txt` and `prd.json`, and `AGENTS.md` as institutional memory. The pattern demonstrates how repeated agent invocations with good guardrails converge on solutions. [@arscontexta's thread](https://x.com/arscontexta/status/2023957499183829467) covers agentic engineering practices in production. The team's approach borrows from these concepts while being responsible about quality. Every agent-generated change still goes through CI, security scanning, and code review.