chore: add AGENTS.md, Dependabot, CodeRabbit config and hygiene check

- AGENTS.md records the clean-room rule, the generated files and their commands, and the four places the opencode version is pinned. - Dependabot updates Bun dependencies and GitHub Actions, and leaves @opencode/* alone because that pin moves with the workflow pins. - CodeRabbit skips generated and recorded files. - Hygiene calls the org workflow that rejects machine-local paths. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-09 02:09:44 -10:00 · 2026-10-11 20:34:18 -04:00
4 changed files with 76 additions and 0 deletions
@@ -0,0 +1,15 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: en-US
+reviews:
+  profile: chill
+  poem: false
+  review_status: false
+  # Generated or recorded files: reviewed by the commands that produce them.
+  path_filters:
+    - "!bun.lock"
+    - "!COMPATIBILITY.md"
+    - "!e2e/golden/**"
+    - "!e2e/targets.lock.json"
+  auto_review:
+    enabled: true
+    drafts: false
@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: bun
+    directory: /
+    schedule:
+      interval: weekly
+    ignore:
+      # The opencode version is pinned in four places that move together. See AGENTS.md.
+      - dependency-name: "@opencode/*"
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
@@ -0,0 +1,15 @@
+name: Hygiene
+
+# Keeps machine-local paths out of tracked files. The check itself lives in Heretek-AI/.github.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  hygiene:
+    uses: Heretek-AI/.github/.github/workflows/hygiene.yml@8d22f62f11936b3ae00bcb6a98b0fcb88419bc76 # main
@@ -0,0 +1,33 @@
+# AGENTS.md
+
+## Evidence
+
+Back every claim about behavior with something executed or read: test output, command output, a file and line. State what was not run.
+
+## Clean room
+
+The implementation is written from Claude Code's public documentation and checked against Claude Code's observable behavior. Take behavior from the docs or from running `claude`, and say which. Code from Claude Code, or from reimplementations of it, stays out of this repository; `review/` holds third-party reference source for reading and is gitignored.
+
+## Canonical surfaces
+
+- Generated files, regenerated and never hand-edited:
+  - `COMPATIBILITY.md`: `bun run e2e`, then `bun run e2e:report`.
+  - `e2e/golden/`: `bun run e2e:oracle`, which needs Claude Code installed.
+  - `e2e/targets.lock.json`: `bun e2e/drift.ts`. The weekly Drift workflow moves these pins and opens the pull request.
+- The opencode version is spelled in four places that move together: `@opencode/plugin` in `package.json`, the matrix in `.github/workflows/e2e.yml`, and two installs in `.github/workflows/nightly.yml`. Dependabot ignores `@opencode/*` for that reason.
+- `docs/research/opencode-v2-findings.md` records how the opencode v2 plugin API behaves where this project depends on it. Read it before changing `src/runtime/`, and update it when an observation changes.
+
+## Commands
+
+- `bun run test`, never a bare `bun test`: the bare form also collects anything under `review/`.
+- `bun run e2e` drives the real `opencode` binary on `PATH` in a throwaway home directory. `OPENCODE_BIN` selects another build.
+- `bun run format` after editing any file, Markdown and YAML included: CI runs `format:check` across the repository.
+- The live tier (`bun test ./e2e/live`) needs `OPENCODE_API_KEY` and spends. Run it only when asked.
+
+## Workflow
+
+- Work on a topic branch and open a pull request. A maintainer merges.
+- A `v*` tag publishes to npm through `.github/workflows/release.yml`. Pushing one is a maintainer's step.
+- Stage explicit paths.
+- After a push, check every workflow run.
+- Write repo-relative paths in tracked files, and `owner/name` for another repository.