AGENTS.md · synthetic-sciences/openscience

Sections

1. Map
2. Commands
3. Conventions
4. Releases

First lines (shown under the repo's Apache-2.0 license)

# Working in this repository

This file is for coding agents and new contributors alike. It says where things
are, how to verify a change, and the conventions the code follows. Product
behaviour for the OpenScience agent itself lives in `backend/cli/src/agent/prompt/`
and `backend/cli/AGENTS.md` (the instructions the shipped agent reads when it
works inside `backend/cli` as a project); this file is about the repository.

## Map

| Path                 | What lives there                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `backend/cli`        | The `openscience` CLI and local server: sessions, tools, providers, skills, and the harness units in `src/harness` |
| `frontend/workspace` | The browser workspace (SolidJS), embedded into the CLI at build time                                               |
| `frontend/ui`        | Shared components, themes, icons (`@synsci/ui`)                                                                    |
| `frontend/desktop`   | The Electron shell and its signed self-updater                                                                     |
| `frontend/docs`      | The documentation site                                                                                             |
| `frontend/landing`   | openscience.sh (own lockfile, not a workspace member)                                                              |
| `tooling/sdk/js`     | The TypeScript SDK, generated from the server's OpenAPI contract                                                   |
| `tooling/plugin`     | The plugin runtime (`@synsci/plugin`)                                                                              |
| `tooling/util`       | Small helpers shared by backend and frontend (`@synsci/util`)                                                      |
| `tooling/repo`       | Setup, SDK regeneration, test sharding, release scripts                                                            |
| `tooling/harbor`     | Harbor / Terminal-Bench adapter for the headless `openscience run` contract                                        |
| `evals`              | Launch evals, cadence lab, and Harbor science-benchmark campaigns                                                  |
| `docs/notes`         | Engineering notes: verification loop, release process, extension guides                                            |

`ARCHITECTURE.md` explains how the pieces fit; `CONTRIBUTING.md` covers the
dev loops and PR expectations; `docs/notes/release-process.md` is how releases
are cut.

## Commands

```bash
bun run setup                     # verify Bun, install, embed the workspace UI once
bun run check                     # format, typecheck, backend + frontend + sdk unit tests
bun run typecheck                 # turbo, ~5 s warm
bun run --cwd backend/cli test    # backend suite with the 15 s per-test timeout
bun test --timeout 15000 ./test/<dir>            # one backend directory (from backend/cli)
bun test --timeout 15000 ./test/<dir>/<file>.test.ts -t "<name>"
bun run test:workspace            # frontend/workspace unit tests (happy-dom, ~40 s)
bun run test:ui                   # @synsci/ui unit tests
bun run --cwd frontend/workspace build           # the workspace bundle the CLI embeds
./tooling/repo/generate.ts        # regenerate the SDK after changing backend/cli/src/server
```

Things that bite:

- Use the pinned Bun (`packageManager` in package.json). Other versions
  produce a different install layout and the frozen lockfile fails.
- Bare `bun test` in `backend/cli` uses Bun's 5 s default timeout and fails
  spuriously; the package script adds `--timeout 15000`.
- Bun treats a bare `test/<dir>` argument as a name filter; pass `./test/<dir>`.
- `frontend/workspace` unit tests live under `src/`; the Playwright specs in
  `e2e/` run through `bun run --cwd frontend/workspace test`, not `bun test`.
- Generated, gitignored files: `backend/cli/src/web/assets.generated.ts`
  (the embedded UI; `bun run setup --web` makes it), `src/provider/models-snapshot.ts`
  (written by the build; the runtime falls back to a live fetch), and
  `src/skill/bundled.generated.ts` (build only). Tests are hermetic and do not
  need them.
- The Fast CI `Test` job runs only the backend tests affected by the diff; the
  full backend suite, native ownership tests, and the web builds run in Deep
  CI (`gh workflow run deep-ci.yml --ref <branch>`, ~5 min).

## Conventions

- Keep things in one function unless composable or reusable.
- Avoid unnecessary destructuring: `obj.a` and `obj.b` keep context; `const { a, b } = obj` loses it.
- Avoid `try`/`catch` where a result type or `.catch(() => undefined)` reads better.
- No `any`. Rely on inference; annotate exports and anything a reader would otherwise have to look up.
- Prefer `const`; avoid `let` plus if/else reassignment (use a ternary or an `iife`).
- Prefer early returns to `else`.
- Prefer single-word names when one word is precise.
- Use Bun APIs (`Bun.file()`, `Bun.spawn`, `$`) over Node equivalents.
- Comments explain why, not what. Do not narrate a change in a comment.

### Tests

- Test behaviour, not text. A test that reads a component's source and asserts
  substrings is not a test; it is a snapshot of the current markup and it breaks
  on every refactor. The only source-reading tests that stay are the
  cross-cutting design contracts under `frontend/*/src/styles`.
- No mocks where the real implementation can run. Fixtures live next to the
  tests that use them.
- New backend tests go in the `backend/cli/test/<area>` directory whose shard
  they belong to (`tooling/repo/test-shards.ts` balances by directory).

### Changes that need a matching update

- `backend/cli/src/server` → run `./tooling/repo/generate.ts` and commit `tooling/sdk`.
- User-visible behaviour → a line under `Unreleased` in `CHANGELOG.md` and, when
  it changes how something is used, the page in `frontend/docs`.
- A new skill, connector, tool, or plugin → the guide in `docs/notes/adding-*.md`
  or `writing-a-plugin.md` says what else must change.
- A skill or code taken from another project → its author and license stay
  with it: `metadata.upstream*` in the skill's frontmatter,
  `backend/cli/skills/ATTRIBUTION.md`, and `NOTICE` for a new source or license.
- Never edit package versions in a PR; `publish.yml` bumps them.

## Releases

Stable releases are cut from `main` by the `publish` workflow after a green
release rehearsal at the same commit; see `docs/notes/release-process.md`.
Once npm packages for a version are staged, only release infrastructure may
change before publish, or the resume refuses the drift.

<!-- BEGIN:turborepo-agent-rules -->

# This is NOT the Turborepo you know

Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`.

Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.

This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
<!-- END:turborepo-agent-rules -->