diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 20 |
1 files changed, 9 insertions, 11 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 93ae71e..aa73342 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,15 +39,13 @@ npm pack --dry-run ## Architecture -Read [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) before making a non-trivial change. It covers: +Get the shape of the codebase from the source before making a non-trivial change: -- the layer diagram and which directories a `domains/*` file may and may not import from, -- the typed and runtime-validated CDP boundary in `src/cdp/commands.ts` and `src/cdp/events.ts`, and how to add a command, -- the nine-rule tool authoring contract, -- an end-to-end worked example of adding a tool and testing it against the fake client, -- the conventions in this codebase that look like mistakes but are not. - -The source carries almost no comments by policy, so that document is where the non-obvious conventions live. +- `scripts/check-boundaries.ts` and `scripts/boundary-allowlist.ts` encode the layer rules — which directories a `domains/*` file may and may not import from. `npm run boundaries` enforces them. +- `src/cdp/commands.ts` and `src/cdp/events.ts` are the typed, runtime-validated CDP boundary. Add a command by adding it to that table. +- `src/util/tool.ts` defines `defineBrowserTool`, the contract every tool in `src/domains/` follows. +- `src/domains/` holds one file per tool; read a neighbouring one before writing a new one. +- `test/domains/` shows how tools are tested against the fake client. --- @@ -86,8 +84,8 @@ Use the normal browser workflow when testing: screenshot → act → screenshot - Write TypeScript and keep the project passing `npm run check`. - Keep `strict` TypeScript mode clean. Do not introduce implicit `any` values. -- No unchecked casts. `npm run boundaries` fails the build on `as any`, `as {`, `as unknown as`, `@ts-ignore`, and non-null assertions in `src/`. A green `tsc` is not evidence of type safety — see `docs/ARCHITECTURE.md` section 3. -- Prefer no comments. Explain a non-obvious convention in `docs/ARCHITECTURE.md`, not inline. +- No unchecked casts. `npm run boundaries` fails the build on `as any`, `as {`, `as unknown as`, `@ts-ignore`, and non-null assertions in `src/`. A green `tsc` is not evidence of type safety. +- Prefer no comments. Explain a non-obvious convention in the commit message or PR description, not inline. - Prefer small, focused changes over broad rewrites. - Keep tool descriptions, parameter descriptions, and prompt guidelines clear and user-facing. - Preserve the existing error-handling style: return useful, actionable messages to the agent instead of leaking low-level details when possible. @@ -98,7 +96,7 @@ Use the normal browser workflow when testing: screenshot → act → screenshot ## Adding a new browser tool -The full worked example is in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — section 4 (the contract) and section 5 (the steps). In short: one file under `src/domains/`, a typebox args schema at the top, a `defineBrowserTool` call carrying its own `concurrency`, an entry in `ALL_TOOLS` in `src/registry.ts`, and a test under `test/domains/` written against `createFakeClient`. +One file under `src/domains/`, a typebox args schema at the top, a `defineBrowserTool` call carrying its own `concurrency`, an entry in `ALL_TOOLS` in `src/registry.ts`, and a test under `test/domains/` written against `createFakeClient`. Beyond that: |