efficient-gitlab-mcp: Instructions file for Codex

Agent Conventions — efficient-gitlab-mcp

Project-specific conventions that complement CLAUDE.md. CLAUDE.md covers architecture, build, and the progressive disclosure pattern; this file covers workflow (branches, commits, tickets) and patterns (test idioms, schema choices) used inside the codebase.

Verification commands

Always run before declaring a task done:

bun test         # 220+ tests, ~500ms — fast enough to run on every change
bun run check    # Biome lint + format, auto-fix

bun run build is run automatically by the pre-commit hook (via the Build step). Do not skip the hook.

Git workflow

This repo uses git-spice (git-spice -h), not raw git for stack management.

• Trunk is detailobsessed, NOT main. main is a read-only mirror of zereight/gitlab-mcp upstream.
• Stack branches are named port/<short-kebab-description> (e.g. port/labels-as-array, port/get-file-contents-auto-ref).
• Use git-spice bc <name> -a -m "<msg>" to create a new branch on top of the current one, staging tracked changes in one step.
• Use git-spice ca -a --no-edit to amend the current branch's commit.
• Use git-spice stack submit --update-only to push updates after amending.
• Use git-spice ls to visualise the stack (top of stack at top, trunk at bottom).

Commit conventions

Conventional commits with these prefixes:

• feat(<scope>): new behaviour (tool, feature, capability)
• fix(<scope>): bug fix
• docs(<scope>): documentation only (including doctring/description text)
• test(<scope>): test-only changes
• chore(<scope>): infrastructure / non-functional

Scope examples: tools, disclosure, schemas, users, repositories, labels, mcp-server, projects, merge-requests.

The body should explain why, not just what. The bottom should always carry a Closes DOT-NNN (or Refs DOT-NNN) line for Linear auto-close on merge.

Do not add Co-Authored-By: Claude / Devin / etc. trailers — ~/.claude/CLAUDE.md disables the harness's auto-trailer and we don't want manual ones either.