Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 20 additions & 23 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,34 @@
# Contributing to Builder

Builder turns an idea into approved documents, a design and a working web app:
a coordinator agent talks with the person and hands work to specialist agents,
on a hub built on vendored Interchange. What it is and why is in
[PRODUCT.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/PRODUCT.md),
how it is structured in
[ARCHITECTURE.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/ARCHITECTURE.md),
and the concrete choices, layout and Interchange docs map in
[IMPLEMENTATION.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md).
Running it is in
[DEV.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/DEV.md),
Builder turns an idea into approved documents, a design and a working web app,
on a hub built on vendored Interchange. Start with
[ARCHITECTURE.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/ARCHITECTURE.md)
and
[IMPLEMENTATION.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md);
running it is in
[DEV.md](https://github.com/corbitsdev/corbits-builder/blob/main/docs/DEV.md)
and sending a change in
[CONTRIBUTING.md](https://github.com/corbitsdev/corbits-builder/blob/main/CONTRIBUTING.md).
These conventions apply to every change, whoever or whatever writes it.

- Every dependency is pinned to an exact version: no `^`, `~`, ranges or
`latest`.
- Interchange's packages (`@intx/*`) are meant to be used. Import them by
package name wherever they fit; the interface talks to the hub through
`@corbits-builder/client`. Build on Interchange's agent loop, retries, waits, timeouts, mail,
approvals and failure handling rather than reimplementing them, and read the
area's Interchange doc first.
The scripts in
[CONTRIBUTING.md](https://github.com/corbitsdev/corbits-builder/blob/main/CONTRIBUTING.md#making-a-change)
and the
[Corbits Triage policy](https://github.com/corbitsdev/corbits-builder/blob/main/.corbits-triage.yml)
enforce most code conventions; run them before saying the tree passes.
These are the ones no check catches:

- Build on Interchange's agent loop, retries, waits, timeouts, mail, approvals
and failure handling rather than reimplementing them, and read the area's
Interchange doc first.
- The interface talks to the hub through `@corbits-builder/client`.
- A change to `vendor/interchange` is its own `(vendor)` commit that also
updates `vendor/interchange.manifest.json`; `bun run vendor:verify` fails on
anything unrecorded.
updates `vendor/interchange.manifest.json`.
- User-visible wording lives in configuration: `apps/hub/src/config/` for the
hub and agents, `apps/web/src/config.ts` for the interface.
- Secrets stay out of responses, logs, documents and prompts; the interface
shows only whether a secret is set.
- Comments explain why, not what the code already says.
- `bun run check` is the gate: lint (oxlint), format (`bun fmt`), typecheck and
tests. Run it before saying the tree passes.
- Conventional Commits (`<type>(<scope>): <description>`), one logical change
per commit and per pull request.
- Comments explain why, not what the code already says.
- Prompts describe the task and the domain. Turn order, reply termination and
loop detection are the inference loop's job.