gitea_mcp: Instructions file for Codex

AGENTS.md

Uppercase MUST, MUST NOT, and MAY are binding directives; lowercase forms are ordinary words (RFC 2119/8174 convention). FIRST and EXACTLY denote strict precedence and exactness.

This file constrains AI design and development process, rules, and boundaries only; it contains no project description. Project capabilities, deployment, and the MCP client setup guide live in README.md / README.zh-CN.md; the concrete architecture (tech stack, module layout, dependency relationships, core patterns) lives in docs/architecture.md (see §5 Appendix).

1. Agent Guidelines

This section defines how the agent operates on this repository — the workflow to follow and the rules that bind edits and commits.

1.1 Before Running Any Command

• MUST verify the target file or directory exists before operating on it.
• MUST NOT assume make, npm run, or other scripts work until the corresponding target exists; check the Makefile and package.json scripts before invoking.
• The project is an installed ESM workspace — node_modules/ already holds dependencies. Prefer existing tooling over installing new tooling.

1.2 Branch and Worktree Workflow

This project uses a two-remote model: origin is the personal fork (ake131998/gitea_mcp) and upstream is the canonical repo (amonstack/gitea_mcp). Each change MUST follow an isolated branch + worktree workflow:

• MUST NOT edit, stage, commit, merge, rebase, or cherry-pick on master / main. The local master is a read-only integration branch that mirrors upstream and is synchronized only from upstream; the sole permitted advance is git fetch upstream && git merge --ff-only upstream/master. No branch — feature, fix, the working branch, or any origin/* ref — is ever merged into master; master is never the merge target, only the fast-forward target from upstream. It MUST stay free of direct work — not "just this once", not even for a one-line fix.
• master accepts no merges. A branch reaches master exclusively through the upstream round-trip: squash to one commit → push to origin → PR against upstream master → upstream merges → local master fast-forwards from upstream. Assembling master by merging local or origin branches is forbidden.
• Before the first edit of any task, MUST verify the current branch with git branch --show-current; if it is master / main, MUST stop and switch to a feature branch (or a worktree) FIRST, then begin.
• Branch from the latest master as <type>/<name> (feat/..., fix/..., chore/..., docs/..., refactor/..., test/...) + short kebab-case name (e.g. feat/user-issues).
• Work in an isolated git worktree at .opencode/worktrees/<name>, not in the primary checkout; the primary checkout MUST stay clean.
• Before committing, show the full diff and wait for explicit approval; commit only after approval (per 1.6).
• When shipping: squash the branch to a single clean commit, push to origin (the fork), and open a PR against upstream master. Pushing to origin and opening a PR are both user-gated — do neither unless explicitly requested.
• After the PR merges: fetch upstream, advance local master with git merge --ff-only upstream/master, remove the worktree, and delete the branch.