**Feedback issue:** https://gitlab.com/gitlab-org/gitlab/-/work_items/596611+s ## Summary Establish a minimal, non-intrusive standard for AI agent instructions in the GitLab monorepo. Only markdown instruction files (`CLAUDE.md`, `AGENTS.md`, and referenced `.ai/` files) will be committed — no skills, hooks, commands, or other harness components. Users retain full control over their own tooling configuration. This is initially scoped to the GitLab monorepo, but may be adopted as guidance for other GitLab-owned project repos. This replaces the broader approach in the [original implementation issue](https://gitlab.com/gitlab-org/gitlab/-/work_items/594027+s), which will be closed in favor of this work. ## References - This issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/594821+s - MR: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/229391+s - Branch: https://gitlab.com/gitlab-org/gitlab/-/tree/594821-agent-instructions - Parent epic: https://gitlab.com/groups/gitlab-org/-/work_items/20880+s - Grandparent epic: https://gitlab.com/groups/gitlab-org/-/work_items/21410+s (confidential, cannot be linked from parent epic which is non-confidential) - [Internal Proposal document](https://gitlab.com/cwoolley-gitlab/ai-workflow-artifacts/-/blob/master/workflow-artifacts/general-20260325-aaa-monorepo-agent-instructions/proposal.md) - [Internal Slack thread](https://gitlab.slack.com/archives/C0ANZ4SHRUH/p1774459948642069) confirming consensus on this approach. - Supersedes: https://gitlab.com/gitlab-org/gitlab/-/work_items/594027+s and its associated MR - [Implementation plan (v06)](https://gitlab.com/cwoolley-gitlab/ai-workflow-artifacts/-/blob/master/workflow-artifacts/workitem-594821/v06-plan.md) - [Task tracker](https://gitlab.com/cwoolley-gitlab/ai-workflow-artifacts/-/blob/master/workflow-artifacts/workitem-594821/tasks.md) ## Details ### 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 these harness components to meet their own specific needs, using standard tooling support for user-level configs. 5. In the future, we may provide opt-in recommendations of harness components for users, as well as tooling to help create/curate them. We may also provide tooling to help manage local gitignored versions of the instruction files. The original https://gitlab.com/gitlab-org/gitlab/-/work_items/594027+s and [plan](https://gitlab.com/cwoolley-gitlab/ai-workflow-artifacts/-/blob/master/workflow-artifacts/workitem-594027/a-plan/plan-latest.md) can serve as a basis for tooling to support this. ### Conventions 1. **Core instruction files:** `CLAUDE.md` and `AGENTS.md` are the core agent instruction files. They will be committed to the repo. 2. **Dual files with identical content:** `CLAUDE.md` and `AGENTS.md` in a given directory level will always contain identical content, so various agentic tools can reliably find them. 3. **Syncing, not symlinks:** `CLAUDE.md` and `AGENTS.md` will both be actual files kept in sync via tooling/linting, not symlinks. Symlinks are reported to be less reliably found by agentic tools. 4. **Exist at multiple levels:** `CLAUDE.md` and `AGENTS.md` files will exist at multiple directory levels of the repo, containing only the instructions specific to that directory hierarchy. For example, the top level will contain instructions applicable to the entire repo, and `app/assets/javascripts` will contain instructions specific to JavaScript files. 5. **Convention for references to other instruction files:** `CLAUDE.md` and `AGENTS.md` may contain references to other markdown files that may be progressively/conditionally loaded. These files **must** exist in an `.ai` directory at the same level as the `CLAUDE.md` and `AGENTS.md` files. 6. **Local gitignored core instruction files:** `CLAUDE.local.md` and `AGENTS.local.md` will be referenced by the committed `CLAUDE.md` and `AGENTS.md` files as `@` file references and added to root `.gitignore`, allowing users to add their own directory-level specific instructions. (Alternate: possibly just `AGENTS.local.md` only, referenced by both, which should work since it's an `@` reference.) 7. **gitignore rule for `.ai` folders:** The `.ai` folders will have a `*` wildcard in the root `.gitignore`, so users can add their own custom instruction files. All files added to the folder for inclusion in the repo will be added with `git add --force`. 8. **`doctor` lint/fix script:** All of the above rules and consistency conventions will be enforced by a CLI linting tool at `scripts/ai_harness/doctor`. It will support a `--fix` option to automatically correct any errors. The core logic can be based on the `doctor` script from the original MR for https://gitlab.com/gitlab-org/gitlab/-/work_items/594027+s. ## Tasks ### MR 1: Core agent instructions and doctor script (merged) https://gitlab.com/gitlab-org/gitlab/-/merge_requests/229391+s - [x] Add top-level `CLAUDE.md` and `AGENTS.md` with identical repo-wide instructions - [x] Add `.ai/` directory at top level with referenced instruction files - [x] Add `.gitignore` rules for `*.local.md` files and `.ai/*` wildcard pattern - [x] Implement `scripts/ai_harness/doctor` lint script with `--fix` support - [x] Validate `CLAUDE.md` / `AGENTS.md` parity at each directory level - [x] Validate `.ai/` reference resolution (referenced files exist) - [x] Validate `.gitignore` coverage for local override files - [x] Validate no forbidden tool-specific files are committed - [x] Create MR - [x] Merge MR ### MR 2: Add lefthook pre-push hook for doctor (in review) https://gitlab.com/gitlab-org/gitlab/-/merge_requests/231246+s - [x] Add `ai-harness-doctor` entry to `lefthook.yml` pre-push commands - [x] Configure glob patterns for AI-related files - [x] Hook blocks push on doctor failure - [x] Create MR - [x] Merge MR ### MR 3: Add CI job for doctor (in review, fixing pipeline) https://gitlab.com/gitlab-org/gitlab/-/merge_requests/231416+s SUB-TASK WORKITEM: https://gitlab.com/gitlab-org/gitlab/-/work_items/596595+ (sub-task workitem created to have a workitem ID for AI planning workflow skill usage) - [x] Add CI job to run `scripts/ai_harness/doctor` on AI file changes - [x] Create MR - [x] Merge MR ### Announce internally - [ ] TODO: determine where to announce - `#engineering-fyi` slack/channel, elsewhere??? --- - [x] Close superseded https://gitlab.com/gitlab-org/gitlab/-/work_items/594027+s and associated MR - [~] Reparent https://gitlab.com/groups/gitlab-org/-/work_items/20880+s under https://gitlab.com/groups/gitlab-org/-/work_items/21410+s (not possible, parent is confidential)