Skip to content

Commit 2e9442a

Browse files
committed
Merge main into dev: repo governance config (CodeRabbit, AGENTS.md, branch docs)
2 parents 79e5067 + 9e68ed6 commit 2e9442a

4 files changed

Lines changed: 266 additions & 0 deletions

File tree

‎.coderabbit.yaml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# yaml-language-server: $schema=https://storage.googleapis.com/coderabbit_public_assets/schema.v2.json
2+
# CodeRabbit configuration for opencodex.
3+
# This file is the single source of truth for CodeRabbit behavior; prefer editing
4+
# this file over the dashboard so settings are versioned and reviewable.
5+
6+
language: en-US
7+
tone_instructions: >-
8+
Always review in English. Be very detailed and specific: cite exact files and
9+
lines, explain the failure mode, and propose a concrete fix. Prefer
10+
evidence-backed findings over style nitpicks.
11+
12+
reviews:
13+
profile: assertive
14+
high_level_summary: true
15+
auto_review:
16+
enabled: true
17+
drafts: false
18+
# Default branch (main) is included automatically; these are additional
19+
# base branches (anchored regex).
20+
base_branches:
21+
- "^dev$"
22+
- "^preview$"
23+
path_instructions:
24+
- path: "src/**"
25+
instructions: >-
26+
Runtime is Bun-native TypeScript (no separate compile step). Flag
27+
Node-only APIs that break under Bun, provider/adapter contract drift,
28+
and changes that bypass the shared routing/config layers. Watch for
29+
credential handling: tokens and OAuth material must never be logged or
30+
serialized into responses.
31+
- path: "tests/**"
32+
instructions: >-
33+
Tests are flat Bun tests under tests/. A behavior change in src/ should
34+
come with a focused regression test near the existing tests for that
35+
subsystem. Flag PRs that change shared routing, adapters, config, or
36+
server behavior without touching tests.
37+
- path: "gui/**"
38+
instructions: >-
39+
React dashboard built with Vite. Check that GUI state changes stay
40+
consistent with the management API responses and that user-visible
41+
strings go through the i18n locale files rather than hardcoded text.
42+
- path: ".github/**"
43+
instructions: >-
44+
Security boundary. Workflow changes, release automation, and dependency
45+
installation steps require explicit security review per MAINTAINERS.md.
46+
Flag any new secret usage, permission escalation, or third-party action
47+
pinned to a mutable ref.
48+
- path: "scripts/**"
49+
instructions: >-
50+
scripts/release.ts is the release authority and a security boundary.
51+
Flag changes that weaken CI gating, alter npm publish behavior, or
52+
bypass the release workflow's dry-run default.
53+
- path: "docs-site/**"
54+
instructions: >-
55+
Astro + Starlight docs site. Check that user-facing docs stay in sync
56+
with actual CLI/API behavior and that translated locale pages (ja, ko,
57+
ru, zh-cn) are not left contradicting the English source.
58+
59+
issue_enrichment:
60+
auto_enrich:
61+
enabled: true
62+
planning:
63+
enabled: true
64+
auto_planning:
65+
enabled: true
66+
labels:
67+
- plan-me
68+
69+
chat:
70+
auto_reply: true

‎AGENTS.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# AGENTS.md
2+
3+
Guidance for AI agents (and humans) working on or reviewing this repository.
4+
5+
## What this project is
6+
7+
opencodex (`ocx`) is a universal provider proxy for OpenAI Codex and Claude Code:
8+
one local proxy that lets Codex CLI/App/SDK and Claude Code use many LLM
9+
providers (Claude, Gemini, Grok, DeepSeek, Ollama, and more). The runtime is
10+
Bun-native TypeScript with no separate server compile step.
11+
12+
## Repository layout
13+
14+
- `src/` — proxy runtime: routing, provider adapters, config, management API.
15+
- `tests/` — flat Bun tests (`tests/*.test.ts`); shared fixtures in
16+
`tests/helpers/`, broader scenarios in `tests/e2e-style/`.
17+
- `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.
18+
- `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.
19+
- `structure/` — maintainer invariants and architecture notes; read before
20+
changing shared subsystems.
21+
- `scripts/` — release and maintenance tooling; `scripts/release.ts` is the
22+
release authority.
23+
- `devlog/` — planning and investigation artifacts (mostly gitignored).
24+
25+
## Commands
26+
27+
```bash
28+
bun install
29+
bun run typecheck # bun x tsc --noEmit (strict)
30+
bun run test # full tests/ suite
31+
bun run lint:gui # GUI eslint
32+
bun run privacy:scan # credential/privacy scan used by CI
33+
bun run build:gui # Vite GUI build
34+
```
35+
36+
Run `bun run typecheck` and `bun run test` before proposing or approving any
37+
non-trivial change. CI runs these on Linux, Windows, and macOS.
38+
39+
## Branch policy
40+
41+
- `dev` — integration branch. All normal pull requests target `dev`.
42+
- `main` — release branch. It only moves by maintainer-controlled promotion
43+
from `dev` (releases, docs deploys). Do not open feature PRs against `main`.
44+
- `preview` — prerelease train (`x.y.z-preview.*` versions).
45+
- `claudedesktop` — ongoing in-development branch. Parts of it have already
46+
been merged into `dev` (e.g. 418d29b1); the remaining commits are integrated
47+
only by maintainer action. Its divergence from `main`/`dev` is expected and
48+
is not a bug. Do not merge or rebase it in a PR without maintainer direction.
49+
50+
[`MAINTAINERS.md`](./MAINTAINERS.md) is authoritative for review and merge
51+
policy (approvals, CI requirements, security review, promotion). This file
52+
summarizes; it never overrides it.
53+
54+
## Review guidelines
55+
56+
These rules apply to all code reviews on this repository, including automated
57+
reviewers (Codex, CodeRabbit).
58+
59+
- **Language:** always review in English, regardless of the PR or issue
60+
language. Be detailed and specific: name the file and line, describe the
61+
concrete failure mode, and suggest a fix. Avoid vague or purely stylistic
62+
commentary.
63+
- **Branch targeting:** flag any pull request that targets `main` instead of
64+
`dev` (releases and maintainer promotions are the only exceptions).
65+
- **Security boundary (highest priority):** changes touching authentication,
66+
credential/token handling, OAuth flows, GitHub Actions workflows, release
67+
automation (`scripts/release.ts`, `.github/workflows/release.yml`), or
68+
dependency installation require explicit security review per
69+
`MAINTAINERS.md`. Treat token logging/serialization, secret exposure,
70+
workflow permission escalation, and mutable third-party action refs as
71+
release blockers.
72+
- **Runtime constraints:** the proxy is Bun-native. Flag Node-only APIs,
73+
assumptions about a compile step, or code paths that break `bun run
74+
typecheck` / `bun run test`.
75+
- **Tests:** behavior changes in `src/` need a focused regression test near
76+
the existing tests for that subsystem. Shared routing, adapter, config, or
77+
server changes need the full suite green.
78+
- **Docs sync:** user-facing behavior changes should update `docs-site/` (and
79+
keep translated locales from contradicting the English source).
80+
- **Privacy:** `bun run privacy:scan` must stay green; never introduce logging
81+
of request bodies, API keys, or account identifiers.

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,15 @@ Thanks for helping with opencodex.
88
- Maintainer roles and merge policy live in [`MAINTAINERS.md`](./MAINTAINERS.md)
99
- Historical investigations live in [`docs/`](./docs)
1010

11+
## Branches
12+
13+
- `dev` — integration target for all normal pull requests.
14+
- `main` — releases only; moves by maintainer-controlled promotion from `dev`.
15+
- `preview` — prerelease train.
16+
- `claudedesktop` — work in progress; maintainer-integrated only.
17+
18+
Agent-facing repository and review rules live in [`AGENTS.md`](./AGENTS.md).
19+
1120
For local development commands, architecture notes, and release workflow details, use the hosted
1221
contributing guide above instead of duplicating instructions here.
1322

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# 260722 repo governance config — plan (P)
2+
3+
## Objective
4+
5+
Land repository-level governance/config artifacts on `main` (then sync to `dev`) so both
6+
CodeRabbit (installed 2026-07-22) and Codex-style agents review PRs with the project's real
7+
rules: dev-branch-first flow, `claudedesktop` in-development status, security-boundary
8+
review requirements.
9+
10+
Scope split (audit blocker #2): PR lane = CodeRabbit review + Codex Cloud code review.
11+
Issue lane = CodeRabbit issue enrichment + planning (NOT "code review"; Codex has no
12+
issue-review product surface, so Codex-on-issues is out of scope).
13+
English/detail guarantee applies to PR reviews (language + tone_instructions + profile);
14+
issue outputs are validated empirically post-merge with a test issue.
15+
16+
## Deliverables
17+
18+
1. `.coderabbit.yaml` (new, repo root)
19+
- `language: en-US` — reviews always in English (user amendment 2026-07-22).
20+
- `reviews.profile: assertive` — most feedback-heavy profile (schema enum
21+
quiet|chill|assertive; schema wording is "more feedback", not a completeness
22+
guarantee — detail is driven by profile + tone_instructions + path instructions
23+
together).
24+
- `tone_instructions` (top-level string): demand very detailed, specific,
25+
evidence-backed findings in English. Max 250 chars per schema.
26+
- `reviews.auto_review.enabled: true`, `drafts: false`,
27+
`base_branches: ["^dev$", "^preview$"]` (regex-anchored; default branch `main`
28+
is auto-included by CodeRabbit, so it is not listed).
29+
- Path instructions: `src/**` (Bun-native TS, no Node-only APIs), `tests/**`,
30+
`gui/**`, `.github/**` + `scripts/release.ts` (security boundary), `docs-site/**`.
31+
- Issue lane (YAML is the single source of truth; no separate dashboard step):
32+
33+
```yaml
34+
issue_enrichment:
35+
auto_enrich:
36+
enabled: true
37+
planning:
38+
enabled: true
39+
auto_planning:
40+
enabled: true
41+
labels:
42+
- plan-me
43+
```
44+
45+
Manual trigger stays `@coderabbitai plan` on any issue.
46+
2. `AGENTS.md` (new, repo root)
47+
- Written in English (review agents consume it; reviews are English).
48+
- Repo orientation: what opencodex is, layout map (src/tests/gui/docs-site/structure).
49+
- Branch policy: PRs target `dev`; `main` is release-promoted; `preview` is the
50+
prerelease lane; `claudedesktop` is an ongoing in-development branch whose
51+
changes may be PARTIALLY integrated into `dev` already (418d29b1 merged an
52+
earlier snapshot); remaining commits are maintainer-controlled — do not treat
53+
its divergence as a bug and do not merge it without maintainer action.
54+
- Commands: `bun run typecheck`, `bun run test`, `bun run privacy:scan`, `bun run lint:gui`.
55+
- `## Review guidelines` (exact heading — this is the section name Codex GitHub
56+
code review consumes): reviews in English, detailed and evidence-backed;
57+
security-boundary list (auth, credential handling, GitHub Actions, release
58+
automation, dependency install) requiring explicit security review;
59+
test-coverage expectations; devlog/structure conventions. Note: Codex reviews
60+
are P0/P1-focused by design; guidelines steer focus, they do not force
61+
low-priority nitpick volume.
62+
- AGENTS.md summarizes but never redefines merge policy: add an explicit
63+
"MAINTAINERS.md is authoritative for review/merge policy" pointer; do not
64+
restate approval counts or merge permissions.
65+
3. `CONTRIBUTING.md` (edit, minimal)
66+
- Add a short "Branches" section: `dev` = integration target for all normal PRs,
67+
`main` = releases only, `preview` = prerelease train, `claudedesktop` = WIP.
68+
- Keep the pointer-style doc; do not duplicate the hosted guide.
69+
4. Codex Cloud review enablement (post-merge, web UI)
70+
- Codex settings -> repository `lidge-jun/opencodex` -> enable **Code review**
71+
and **Automatic reviews**; manual trigger stays `@codex review`.
72+
73+
## Landing strategy
74+
75+
- Work on a `codex/repo-governance-config` branch off `main`; commit; push; merge to
76+
`main` (fast, config-only, no runtime code). Then bring the same files to `dev`
77+
via `git merge main` into dev ONLY (no cherry-pick — duplicate commits would
78+
create friction at the next dev->main promotion). This main-first landing is an
79+
explicit governance exception to the normal dev->main promotion flow; record it
80+
in the commit/PR description.
81+
- User instruction "main에 설정해놔" = explicit approval to land on main and push.
82+
83+
## Out of scope
84+
85+
- No runtime/src changes, no workflow changes, no release.
86+
- No rewrite of docs-site contributing guide.
87+
88+
## Verification (C)
89+
90+
- Schema validation: validate `.coderabbit.yaml` against
91+
https://storage.googleapis.com/coderabbit_public_assets/schema.v2.json (not just
92+
YAML syntax parse).
93+
- `git diff --stat` limited to the three files.
94+
- Files render on GitHub after push (spot check).
95+
- Post-merge smoke tests (D notes / follow-up): CodeRabbit auto-review on a
96+
non-draft PR targeting dev; `@coderabbitai review` manual trigger; `plan-me`
97+
labeled test issue produces English enrichment/plan; `@codex review` works after
98+
enabling Code review in Codex settings; both services reflect AGENTS.md security
99+
rules.
100+
101+
## Risks
102+
103+
- `.coderabbit.yaml` schema drift → validate keys against current CodeRabbit docs
104+
during build; keep config minimal to stay schema-safe.
105+
- CONTRIBUTING.md divergence from hosted docs-site guide → keep the section short and
106+
pointer-first.

0 commit comments

Comments
 (0)