Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Resolves #440: Add a line recommending to avoid rebasing during review process

Chirag Jainb7f0ca1ebc58
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index fbced0de9..b52f30d6a 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,7 +2,7 @@
<!-- What does this PR change, and why? Link the related issue if there is one. -->
-Closes #
+Closes #<add-issue-number-here>
## Changes
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3151c729d..85322a1fc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,11 +10,11 @@ By participating you agree to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
> Please only submit pull requests for an issue when you have received approval from a maintainer.
> While we value good intentions, we require approvals for community code contributions to ensure we use everyone's time effectively.
-- **Report bugs** — open an issue with steps to reproduce, expected vs actual behavior, and your environment.
-- **Improve docs** — typo fixes and clarifications are always welcome.
-- **Fix bugs / build features** — for anything non-trivial, please open an issue first so we can discuss the approach before you invest time
+- **Report bugs** - open an issue with steps to reproduce, expected vs actual behavior, and your environment.
+- **Improve docs** - typo fixes and clarifications are always welcome.
+- **Fix bugs / build features** - for anything non-trivial, please open an issue first so we can discuss the approach before you invest time
-For security vulnerabilities, do **not** open a public issue — see [SECURITY.md](SECURITY.md).
+For security vulnerabilities, do **not** open a public issue - see [SECURITY.md](SECURITY.md).
### Why we require approvals for community code contributions
@@ -57,7 +57,7 @@ Open a feature request in the issue tracker, or upvote an existing request that
- **Node.js 22.14+** (see [`.nvmrc`](.nvmrc); pnpm 11.16 needs 22.13+, and `better-sqlite3` v13 needs Node-API 10)
- **pnpm** (version pinned via `packageManager` in [`package.json`](package.json); `corepack enable` handles it)
-- **Docker** — only needed for Postgres/Redis dev infra, the smoke test, and local SDK generation (maintainers). Fork contributors do not generate the SDK.
+- **Docker** - only needed for Postgres/Redis dev infra, the smoke test, and local SDK generation (maintainers). Fork contributors do not generate the SDK.
## Repository layout
@@ -69,7 +69,7 @@ This is a pnpm workspace:
| `@truefoundry/trueforge-core` | `@truefoundry/trueforge-core` | [`packages/trueforge-core`](packages/trueforge-core) | Library: agent core, sessions, and streaming |
| `@truefoundry/trueforge-ui` | `@truefoundry/trueforge-ui` | [`packages/trueforge-ui`](packages/trueforge-ui) | Embeddable agent chat UI SDK |
| `@truefoundry/trueforge-sdk` | `@truefoundry/trueforge-sdk` | [`packages/trueforge-sdk`](packages/trueforge-sdk) | Generated TypeScript API client |
-| `frontend` | — | [`packages/frontend`](packages/frontend) | Chat UI app (bundled into the server) |
+| `frontend` | - | [`packages/frontend`](packages/frontend) | Chat UI app (bundled into the server) |
## Setup
@@ -84,7 +84,7 @@ There are two dev topologies. Both serve the UI on [http://localhost:3000](http:
### Standalone (zero infra)
-SQLite only — good for most day-to-day development. Standalone mode is intended for local use; it is not a production-safe topology (no login by default, local SQLite). Please do not expose it beyond localhost.
+SQLite only - good for most day-to-day development. Standalone mode is intended for local use; it is not a production-safe topology (no login by default, local SQLite). Please do not expose it beyond localhost.
```bash
pnpm standalone:dev
@@ -94,7 +94,7 @@ pnpm standalone:dev
Use this when working on anything involving Postgres storage or Redis peering (cross-replica turn cancels and stream handoff).
-Terminal 1 — start Postgres (`:5432`) and Redis (`:6379`):
+Terminal 1 - start Postgres (`:5432`) and Redis (`:6379`):
```bash
pnpm dev:infra
@@ -120,7 +120,7 @@ Local server scripts resolve `@truefoundry/trueforge-core` from source, so you d
Dev and production-like runs use different process topologies. Standalone vs multi-replica only changes storage/peering (`STANDALONE`); it does not change how the UI is served.
-**Development** — `pnpm standalone:dev` / `pnpm dev` run two processes in parallel: Vite (UI, with live reload) and the Hono API. The browser talks to Vite; Vite proxies `/api/*` to Hono.
+**Development** - `pnpm standalone:dev` / `pnpm dev` run two processes in parallel: Vite (UI, with live reload) and the Hono API. The browser talks to Vite; Vite proxies `/api/*` to Hono.
```
browser Vite (:3000) Hono (:8790)
@@ -132,7 +132,7 @@ Dev and production-like runs use different process topologies. Standalone vs mul
│────────────────────────────>│─────────────────────────────>│
```
-**Production-like** — after `pnpm build`, `pnpm standalone:start` / `pnpm start` run a single Hono process. It serves the built frontend bundle for non-API routes and handles `/api/*` itself. The Docker container works the same way: one process, one origin.
+**Production-like** - after `pnpm build`, `pnpm standalone:start` / `pnpm start` run a single Hono process. It serves the built frontend bundle for non-API routes and handles `/api/*` itself. The Docker container works the same way: one process, one origin.
```
browser Hono (:8790)
@@ -150,13 +150,13 @@ On one origin (start / Docker): `/api/*` (including OpenAPI) and `/healthz` are
See [`packages/trueforge/.env.example`](packages/trueforge/.env.example) for every env var. Useful dev overrides:
-- `PORT` — API port (default `8790`)
-- `FRONTEND_PORT` — Vite UI port in dev (default `3000`); see [`packages/frontend/README.md`](packages/frontend/README.md)
-- `VITE_SERVER_URL` — point the Vite proxy at a different API
-- `PUBLIC_BASE_URL` — public origin for MCP OAuth / OIDC callbacks. Required for `pnpm standalone:dev` / `pnpm dev` and for distributed mode (e.g. `http://localhost:3000` for Vite). Non-development standalone falls back to `http://localhost:$PORT`.
-- `FRONTEND_DIR` — directory of a built UI for the server to serve
-- `SQLITE_PATH` — SQLite file location in standalone mode
-- `REDIS_URL` / `POSTGRES_*` — used when `STANDALONE=false`
+- `PORT` - API port (default `8790`)
+- `FRONTEND_PORT` - Vite UI port in dev (default `3000`); see [`packages/frontend/README.md`](packages/frontend/README.md)
+- `VITE_SERVER_URL` - point the Vite proxy at a different API
+- `PUBLIC_BASE_URL` - public origin for MCP OAuth / OIDC callbacks. Required for `pnpm standalone:dev` / `pnpm dev` and for distributed mode (e.g. `http://localhost:3000` for Vite). Non-development standalone falls back to `http://localhost:$PORT`.
+- `FRONTEND_DIR` - directory of a built UI for the server to serve
+- `SQLITE_PATH` - SQLite file location in standalone mode
+- `REDIS_URL` / `POSTGRES_*` - used when `STANDALONE=false`
### Migrations
@@ -170,7 +170,7 @@ That script sets `STANDALONE=false` and uses `POSTGRES_*` from `packages/truefor
## Workspace scripts
-Workspace tasks go through `package.json` scripts — if a repeatable workflow is missing, add a script rather than documenting an ad hoc command.
+Workspace tasks go through `package.json` scripts - if a repeatable workflow is missing, add a script rather than documenting an ad hoc command.
| Script | Purpose |
| ---------------------------------------------------- | ----------------------------------------------------- |
@@ -204,7 +204,7 @@ pnpm test:store:local # Postgres suite against local infra
### Smoke test (Docker)
-Full stack in containers — the built server image serves API + UI, in multi-replica mode (`STANDALONE=false`):
+Full stack in containers - the built server image serves API + UI, in multi-replica mode (`STANDALONE=false`):
```bash
pnpm smoke # build, wait for healthy services, check /healthz and UI
@@ -213,7 +213,7 @@ pnpm smoke:down
Open [http://localhost:8791](http://localhost:8791). Credentials come from `packages/trueforge/.env`. Host ports are offset from local dev so they do not collide: Postgres `:5433`, Redis `:6380`, app `:8791`.
-## Generated code — do not edit by hand
+## Generated code - do not edit by hand
- [`packages/trueforge-sdk`](packages/trueforge-sdk), [`.github/fern/openapi/openapi.json`](.github/fern/openapi/openapi.json), and [`docs/openapi.json`](docs/openapi.json) are generated and committed. Edit route handlers under `packages/trueforge/src/routes/` instead; CI regenerates the outputs. To regenerate locally (Docker required): `pnpm sdk:generate`.
- Catalog YAML files under `packages/trueforge/catalog/` are inlined at build time by `build:gen` scripts.
@@ -229,10 +229,10 @@ Open [http://localhost:8791](http://localhost:8791). Credentials come from `pack
The repository-wide rules live in [`AGENTS.md`](AGENTS.md) (some packages have their own nested `AGENTS.md`). Highlights:
-- No type-assertion escapes (`as T`, non-null `!`) to silence errors — fix the types.
+- No type-assertion escapes (`as T`, non-null `!`) to silence errors - fix the types.
- Wrap-and-rethrow must preserve the original error via `{ cause }`.
- Zod-backed types are derived with `z.infer<typeof Schema>`; don't duplicate schemas as interfaces.
-- Static `import` / `import type` only — no `require()`.
+- Static `import` / `import type` only - no `require()`.
- Tests live under a top-level `test`/`tests` directory mirroring `src`, never inline.
- Wire shapes (HTTP/OpenAPI) and database identifiers use `snake_case`.
- Server env reads go through `packages/trueforge/src/config.ts`, never `process.env` directly.
@@ -244,9 +244,10 @@ Prettier and ESLint run as pre-commit hooks via husky + lint-staged.
1. Fork (or branch) and create a topic branch: `git checkout -b my-fix`.
2. Make your change, with tests where it makes sense. Do not commit generated OpenAPI/SDK output (forks: source only; `main` regenerates after merge).
-3. Make sure `pnpm build`, `pnpm test`, `pnpm typecheck`, `pnpm lint:ci`, and `pnpm format:check` pass — CI runs exactly these.
+3. Make sure `pnpm build`, `pnpm test`, `pnpm typecheck`, `pnpm lint:ci`, and `pnpm format:check` pass - CI runs exactly these.
4. Keep PRs focused and reasonably small; describe **what** changed and **why** in the description.
5. Open the PR. A maintainer will review it; squash-merge is the norm.
+6. **Please avoid rebasing or force-pushing once a maintainer has started reviewing.** It can make iterative reviewing harder. To update your branch, merge `main` instead. We squash-merge at the end, so messy in-PR history is fine.
## Releases