Skip to content

Commit a47aa3f

Browse files
authored
docs: harden and scope agent guidance (#583)
Adds nested AGENTS.md files and CODEOWNERS coverage for agent guidance. Keeps the owner Transition intake rule already on dev (merge to dev, carry onto dev2-go, port go/ only when needed).
1 parent 2bbac19 commit a47aa3f

7 files changed

Lines changed: 152 additions & 0 deletions

File tree

‎.github/AGENTS.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# GitHub automation instructions
2+
3+
This file applies to `.github/` and inherits the repository-wide rules in `/AGENTS.md`.
4+
5+
## Security boundary
6+
7+
Every workflow, ownership, branch-enforcement, release, or repository-automation
8+
change requires explicit security review under `MAINTAINERS.md`.
9+
10+
## Workflow rules
11+
12+
- Grant the minimum required `permissions`.
13+
- Pin third-party actions to immutable full commit SHAs.
14+
- Preserve the human-readable version comment beside each pinned action.
15+
- Do not run untrusted pull-request code with secrets or write permissions.
16+
- Treat `pull_request_target`, workflow dispatch, reusable workflows, artifacts, caches, and generated command input as trust boundaries.
17+
- Do not broaden triggers, write permissions, token exposure, release eligibility, or publish capability without an explicit task requirement.
18+
- Preserve cross-platform coverage where the workflow currently promises Linux, macOS, and Windows behavior.
19+
- Keep branch-enforcement text synchronized with `AGENTS.md`, `MAINTAINERS.md`, and the public contributing guide.
20+
21+
## Validation
22+
23+
- Inspect the complete workflow diff, including event triggers, permissions, conditions, interpolation, and shell behavior.
24+
- Run the local commands represented by changed workflow steps where possible.
25+
- Run `bun run prepush` for CI, release, dependency, packaging, or cross-platform workflow changes.
26+
- Do not claim the workflow itself passed until GitHub Actions reports success for the exact commit.

‎.github/CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,7 @@
1414
/src/server/management-api.ts @lidge-jun @Ingwannu
1515

1616
# Governance and security policy
17+
/AGENTS.md @lidge-jun @Ingwannu
18+
**/AGENTS.md @lidge-jun @Ingwannu
1719
/MAINTAINERS.md @lidge-jun @Ingwannu
1820
/SECURITY.md @lidge-jun @Ingwannu

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,16 @@ Bun-native TypeScript with no separate server compile step.
1616
`tests/helpers/`, broader scenarios in `tests/e2e-style/`.
1717
- `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.
1818
- `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.
19+
- `go/` — Go native runtime (primary on the `dev2-go` line during transition).
1920
- `structure/` — maintainer invariants and architecture notes; read before
2021
changing shared subsystems.
2122
- `scripts/` — release and maintenance tooling; `scripts/release.ts` is the
2223
release authority.
2324
- `devlog/` — planning and investigation artifacts (mostly gitignored).
2425

26+
Read the nearest nested `AGENTS.md` before changing files in a scoped
27+
directory (`src/`, `gui/`, `docs-site/`, `scripts/`, `.github/`).
28+
2529
## Commands
2630

2731
```bash

‎docs-site/AGENTS.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Documentation-site instructions
2+
3+
This file applies to `docs-site/` and inherits the repository-wide rules in `/AGENTS.md`.
4+
5+
## Source-of-truth rules
6+
7+
- `docs-site/` is the public user-documentation source.
8+
- Document current shipped or intentionally pending behavior. Do not copy claims from historical `docs/` or `devlog/` material without verifying them against current code and configuration.
9+
- English documentation is the canonical source. Translated content must not contradict it.
10+
- Keep commands, paths, configuration keys, defaults, branch names, and URLs synchronized with the repository.
11+
- Do not edit generated build output.
12+
13+
## Editing rules
14+
15+
- Reuse the existing Astro and Starlight structure, navigation, components, and style.
16+
- Update all directly affected pages when a user workflow changes.
17+
- Do not add duplicated policy text when a stable canonical document can be linked instead.
18+
- Use repository-relative links for repository files and site-relative links for documentation pages where the existing site does so.
19+
20+
## Required validation
21+
22+
Run:
23+
24+
```bash
25+
cd docs-site
26+
bun install --frozen-lockfile
27+
bun run build
28+
```
29+
30+
Do not claim documentation validation passed unless this build completes successfully.

‎gui/AGENTS.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
# OpenCodex GUI — agent rules
22

3+
This file applies to `gui/` and inherits the repository-wide rules in `/AGENTS.md`.
4+
5+
## Ownership and generated output
6+
7+
- `gui/` is the React + Vite dashboard.
8+
- `gui/dist/` is generated packaged output. Do not edit it by hand.
9+
- Use the existing component, state, routing, styling, and data-access patterns before introducing a new abstraction.
10+
- Keep dashboard behavior aligned with the management API and provider configuration model.
11+
312
## Text and i18n
413

514
- **No hardcoded visible UI text** in `src/pages`, `src/components`, `src/App.tsx`, or `src/ui.tsx`.
@@ -19,7 +28,33 @@
1928
- Keep **code comments** (including shell `# …` comments in samples). Never strip them to “satisfy” i18n.
2029
- Run `bun run lint:i18n` after UI copy changes; fix real violations before committing. If a hit is technical, extend the allowlist or put the string in `<pre>`/`<code>` — do not invent nonsense translation keys.
2130

31+
## Implementation rules
32+
33+
- Preserve accessibility: keyboard operation, labels, focus behavior, semantic controls, and readable validation errors.
34+
- Do not introduce a dependency for behavior already provided by the current stack or a small local implementation.
35+
- Dependency changes require explicit security review.
36+
- Update `docs-site/` when dashboard behavior, setup, or configuration changes for users.
2237

2338
## Failure mode
2439

2540
Hardcoding English (or German) in JSX to “fix” a bad translation is **not** allowed. Add or fix the key in all locale files instead.
41+
42+
## Required validation
43+
44+
Run all of the following for every functional `gui/` change:
45+
46+
```bash
47+
cd gui
48+
bun test tests
49+
bun run lint
50+
bun run build
51+
```
52+
53+
After any UI-copy or locale change, also run:
54+
55+
```bash
56+
cd gui
57+
bun run lint:i18n
58+
```
59+
60+
Run the repository-level checks required by any non-GUI files changed in the same work.

‎scripts/AGENTS.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Script and release-tooling instructions
2+
3+
This file applies to `scripts/` and inherits the repository-wide rules in `/AGENTS.md`.
4+
5+
## Safety boundary
6+
7+
- `scripts/release.ts` is the release authority.
8+
- Release, publish, version-bump, deployment, and package-signing behavior is maintainer-controlled.
9+
- Never run `bun run release`, a publish command, or a deployment command unless the task explicitly requires the action and `MAINTAINERS.md` permits it.
10+
- Changes to release, packaging, dependency-installation, credential, or repository-automation scripts require explicit security review.
11+
12+
## Implementation rules
13+
14+
- Preserve Linux, macOS, and Windows behavior. Do not add shell-specific assumptions to cross-platform scripts.
15+
- Use explicit paths, deterministic inputs, bounded resource use, and actionable failures.
16+
- Use atomic replacement for files whose partial write would corrupt configuration, package metadata, release state, or recovery data.
17+
- Do not log secrets, tokens, request bodies, account identifiers, private paths, or personal data.
18+
- Do not weaken dry-run, exact-commit, CI-success, or explicit-confirmation gates.
19+
- Generated package assets must be produced by the owning preparation command, not edited manually.
20+
21+
## Required validation
22+
23+
- Run focused tests or probes for the changed script.
24+
- Run `bun run typecheck`.
25+
- Run `bun run privacy:scan` when the script handles configuration, credentials, requests, logs, or account data.
26+
- Run `bun run prepush` for release, packaging, dependency, or cross-platform tooling changes.
27+
- Report any platform-specific validation that was not executed.

‎src/AGENTS.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Source runtime instructions
2+
3+
This file applies to `src/` and inherits the repository-wide rules in `/AGENTS.md`.
4+
5+
## Runtime and module rules
6+
7+
- `src/` is Bun-native TypeScript in strict mode and uses ES modules only.
8+
- Do not assume a separate server compilation step.
9+
- Prefer Bun and Web-platform APIs. Introduce a Node-only runtime dependency only when the task explicitly requires compatibility code and the owning module already has that role.
10+
- Preserve existing public exports and configuration compatibility unless the task explicitly changes them.
11+
- Read the applicable documents in `structure/` before changing shared routing, adapters, transports, sidecars, authentication, configuration, or server architecture.
12+
13+
## Implementation rules
14+
15+
- Follow the existing subsystem boundaries and naming patterns.
16+
- Do not combine unrelated responsibilities to avoid creating another large shared module.
17+
- Handle asynchronous failures at request, transport, and sidecar boundaries. Optional integrations must degrade through the existing failure representation rather than crash the request path.
18+
- Provider catalog metadata belongs in the canonical provider registry and derivation flow. Do not duplicate provider facts across independent pickers or seeds.
19+
- Adapter changes must preserve the internal event contract, streaming behavior, tool calls, cancellation, error mapping, and image handling relevant to that adapter.
20+
- Authentication, OAuth, token, credential, management API, and CORS changes are security-boundary changes.
21+
22+
## Tests and validation
23+
24+
- Place focused regression coverage near the existing tests for the affected subsystem.
25+
- For focused behavior, run the relevant `bun test tests/<name>.test.ts` and `bun run typecheck`.
26+
- For shared routing, adapters, config, OAuth, or server behavior, also run `bun run test`.
27+
- For logging, requests, credentials, account data, or fixtures, also run `bun run privacy:scan`.
28+
- Update `docs-site/` when the change affects user-visible behavior or configuration.

0 commit comments

Comments
 (0)