## Status ### Foundation - [x] Core `CLAUDE.md` and `AGENTS.md` at top level and subdirectories (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/229391+s — merged) - [x] `.ai/` directory structure with themed instruction files - [x] `.gitignore` rules for local overrides and `.ai/*` - [x] `scripts/ai_harness/doctor` lint script with `--fix` support ### Enforcement - [x] Lefthook pre-push hook for doctor (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/231246+s) - [x] CI job for doctor in lint stage (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/231416+s) ### Create and maintain eval suites We should have a standardized evals that we run, to be objective and data driven about instruction/harness development: https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents This will avoid guesswork and subjective bikeshedding around instructions, such as the early comments on this epic, and threads like [this](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/232403#note_3274833700). - [ ] Research and create eval suite for monolith, with documentation on how to run and interpret it ### Content Expansion - [ ] Expand domain-specific instruction files based on feedback - [ ] Agent-friendly summaries where docs are too large for context windows - [ ] Adoption guidance for other GitLab-owned repos ### Managing additional AI harness components for individuals and groups **AI Harness UPDATE 2026-05-22: See [this thread below](https://gitlab.com/groups/gitlab-org/-/work_items/20880#note_3363363202) for a discussion of the proposed goals and potential approaches for the harness** Beyond the committed instruction files, contributors may want to manage additional harness components for their own use or for their team/group — skills, commands, hooks, agents, rules, MCP server configurations, and tool-specific config files. The closed https://gitlab.com/gitlab-org/gitlab/-/merge_requests/228415+s (see more links and details below) explored an `install`/`setup` script approach with a guided wizard that would manage a portable, version-controlled config directory containing these components, with symlinking into the monolith checkout. While superseded by the current minimal-instructions-only approach for committed files, it provides a potential direction for opt-in tooling to help individuals and teams manage their local harness setup. Efforts exploring different angles of this space: - Original broader AI harness implementation issue (same one referenced above) - closed to reduce scope, but still contains patterns that we may want to pursue: - AI-managed plan/specification: https://gitlab.com/cwoolley-gitlab/ai-workflow-artifacts/-/blob/master/workflow-artifacts/workitem-594027/a-plan/v29/plan-v29.md - Issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/594027+s - MR: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/228415+s - [Kamil's POC agent harness](https://gitlab.com/ayufan-repos/gitlab-r-and-d/poc-gitlab-rails-agent-harness) — fully containerized parallel environment for running multiple Claude Code agents against gitlab-rails, with per-worktree isolated stacks (postgres, redis, spring) and mounted agent rules, commands, and skills. - [Chad's `gitlab-ai-harness` project](https://gitlab.com/cwoolley-gitlab/gitlab-ai-harness) - **Have your own custom harness you are using with the monolith or other projects? Add it here as an example!** ### Reusable skills library https://gitlab.com/gitlab-org/ai/skills provides reusable agent skills following the [Agent Skills](https://agentskills.io) open format — structured prompt files that AI coding assistants can load on demand for domain-specific knowledge and workflows. Includes skills for glab CLI, commit messages, GitLab database inspection, performance testing, and more. Installable via OpenCode native discovery, Claude Code Plugin Marketplace, or the `@dgruzd/skills` CLI. ## Summary This epic tracks the effort to add shared AI agent configuration to the GitLab repository, enabling developers to use tools like Claude Code, OpenCode, Cursor, and other AI coding assistants effectively when contributing to GitLab. The approach establishes a minimal, non-intrusive standard: only markdown instruction files (`CLAUDE.md`, `AGENTS.md`, and referenced `.ai/` files) are committed to the repo. No skills, hooks, commands, or other harness components are checked in. Users retain full control over their own tooling configuration. **Related workstream:** This epic supports [WS2: Prepare the monolith for agentic code tooling](https://gitlab.com/groups/gitlab-org/-/work_items/21410) (confidential), part of the Code Review Lifecycle Transformation initiative. ## Background An [initial MR](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216) attempted to add comprehensive OpenCode configuration, but accumulated significant discussion across 28+ threads. Per [Chad's suggestion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3071893040), we embraced iteration: 1. A minimal foundation was shipped first (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/222867+s — `opencode.json` + skeleton `AGENTS.md`) 2. Separate issues were created for each contentious topic 3. A [revised, more focused approach](https://gitlab.com/gitlab-org/gitlab/-/work_items/594821) was proposed, gaining [Slack consensus](https://gitlab.slack.com/archives/C0ANZ4SHRUH/p1774459948642069), and was implemented via https://gitlab.com/gitlab-org/gitlab/-/merge_requests/229391+s (merged April 13, 2026). This superseded the [original broader implementation issue](https://gitlab.com/gitlab-org/gitlab/-/work_items/594027). ## Guiding Principles 1. No potentially unwanted tooling/harness/config should be forced on contributors. 2. Only "instructions" (`CLAUDE.md`/`AGENTS.md` and other markdown files they refer to) will be committed to git. 3. No other harness components will be committed: no skills, commands, hooks, or agents. 4. Individuals/groups/teams can create/curate/customize harness components to meet their own needs, using standard tooling support for user-level configs. 5. In the future, we may provide opt-in recommendations of harness components, as well as tooling to help create/curate them and manage local gitignored versions of instruction files. ## Established Conventions 1. **Dual core files:** `CLAUDE.md` and `AGENTS.md` at each directory level contain identical content, so various agentic tools can reliably find them. 2. **Syncing, not symlinks:** Files are kept in sync via tooling/linting, not symlinks (symlinks are less reliably found by agentic tools). 3. **Multiple directory levels:** Instruction files exist at multiple directory levels, containing only instructions specific to that directory hierarchy. 4. **`.ai/` directories for references:** Referenced instruction files must reside in an `.ai/` directory at the same level as the core instruction files. 5. **Local overrides:** `CLAUDE.local.md` and `AGENTS.local.md` are gitignored, allowing users to add their own directory-level instructions. 6. **gitignore wildcard for `.ai/`:** `.ai/` folders use a `*` wildcard in `.gitignore`; committed files are added with `git add --force`. 7. **Doctor lint script:** All conventions are enforced by `scripts/ai_harness/doctor` with `--fix` support for automatic corrections. ## Key Decisions Made ### SSOT: Link to Docs, Don't Duplicate Strong consensus that instruction files should link to official docs rather than duplicate content. Duplication leads to contradictions. See [discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3045267629). ### Themed Review Documents Point agents to existing themed review documents rather than writing custom guidance: - `doc/development/code_review.md` - `doc/development/database_review.md` - `doc/development/graphql_guide/reviewing.md` See [@pedropombeiro's suggestion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3063542377). ## Open Questions - **Duo integration:** Should we reference existing `.gitlab/duo/` files (`mr-review-instructions.yaml`, `chat-rules.md`)? - **Branch naming convention:** `username-issue-description` vs `issue-username-description`, and enforcement level. - **Content expansion:** Which domains need agent-friendly instruction files next (database, frontend/Vue, testing, etc.)? ## Alternative Approaches ### Harness/Symlink Approach A separate "harness" project with symlinks rather than committing configs directly remains a valid option for users wanting cross-project consistency and richer tooling (skills, hooks, commands). See: - https://gitlab.com/cwoolley-gitlab/gitlab-ai-harness - https://gitlab.com/gitlab-org/fulfillment/developer-tools/skills This complements (rather than conflicts with) the committed instruction files. ## Feedback User experience and implementation feedback is tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/596611+s. ## Related - https://gitlab.com/gitlab-org/gitlab/-/work_items/594821+s — Introduce GitLab monorepo agent instructions (implementation issue) - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/229391+s — Core instructions and doctor script (merged) - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/231246+s — Lefthook pre-push hook (in review) - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/231416+s — CI job for doctor (in review) - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216+s — Original comprehensive MR (closed, preserved for discussion context) - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/222867+s — Earlier minimal foundation MR (merged, superseded) --- <details> <summary>Original epic description (prior to April 2026 update)</summary> ## Summary This epic tracks the effort to add shared AI agent configuration to the GitLab repository, enabling developers to use tools like OpenCode, Claude, Cursor, and other AI coding assistants effectively when contributing to GitLab. ## Background An initial MR ( https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216+s ) attempted to add comprehensive OpenCode configuration, but accumulated significant bikeshedding across 28+ discussion threads. Per [Chad's suggestion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3071893040), we're embracing iteration by: 1. Starting with a minimal, non-controversial foundation 2. Creating separate issues for each contentious topic 3. Iterating on guidelines incrementally **Foundation shipped:** https://gitlab.com/gitlab-org/gitlab/-/merge_requests/222867+s merged the minimal `opencode.json` + skeleton `AGENTS.md`. ## Key Decisions Made ### 1. opencode.json: Example File, Not Committed Don't commit `opencode.json` directly (prevents user customization). Instead, provide `opencode.json.example` with recommended settings that users copy to their own gitignored `opencode.json`. See [discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3045242498). ### 2. SSOT: Link to Docs, Don't Duplicate Strong consensus that `AGENTS.md` should link to official docs rather than duplicate content. Duplication leads to contradictions (e.g., `dependent:` guidance contradicted [official docs](https://docs.gitlab.com/development/database/foreign_keys/#dependent-removals)). See [discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3045267629). ### 3. Themed Review Documents Point agents to existing themed review documents rather than custom guidance: - `doc/development/code_review.md` - `doc/development/database_review.md` - `doc/development/graphql_guide/reviewing.md` See [@pedropombeiro's suggestion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3063542377). ## Key Decisions Needed ### 1. File Organization - Root level `AGENTS.md` vs `.ai/` directory structure - Modular files (`.ai/git.md`, `.ai/database.md`, `.ai/testing.md`) with conditional loading - Reference: [Agent Skills standard](https://agentskills.io) - See [detailed proposal](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3045197564) ### 2. Security/Permissions Configuration OpenCode in "build" mode executes commands without consent. Recommended restrictive config: - `"default_agent": "plan"` - `"*": "ask"` for most operations - Only auto-allow safe read-only commands - See [security discussion](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3045214929) and [@pedropombeiro's config](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216#note_3063542377) ### 3. Existing Duo Instructions Integration Consider referencing existing `.gitlab/duo/` files: - `.gitlab/duo/mr-review-instructions.yaml` - `.gitlab/duo/chat-rules.md` ### 4. Branch Naming Convention - `username-issue-description` vs `issue-username-description` - Should this be enforced or just guidance? ## Alternative Approaches Considered ### Harness/Symlink Approach @cwoolley-gitlab proposed a separate "harness" project with symlinks rather than committing configs directly: - Benefits: Works across multiple projects, supports multiple AI tools - Project: https://gitlab.com/cwoolley-gitlab/gitlab-ai-harness - Similar approach: https://gitlab.com/gitlab-org/fulfillment/developer-tools/skills This remains a valid alternative for users who want cross-project consistency. ## Iteration Plan ### Phase 1: Foundation ✅ - [x] Basic `opencode.json` pointing to instructions file (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/222867+s merged) - [x] Skeleton `AGENTS.md` with links to existing docs - [x] `.gitignore` entry for OpenCode (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220171+s merged) ### Phase 2: Content Strategy - [ ] Finalize SSOT approach - [ ] Identify which docs need agent-friendly summaries - [ ] Create templates for domain-specific contexts - [ ] Decide on `.ai/` directory structure ### Phase 3: Domain-Specific Guidelines - [ ] Database development guidelines - [ ] Frontend/Vue guidelines - [ ] Testing guidelines - [ ] Code review guidelines ## Related - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/222867+s — Minimal foundation MR (merged) - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220216+s — Original comprehensive MR (closed, preserved for discussion context) - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/220171+s — Added `.gitignore` entry for OpenCode (merged) </details>