Contributing

AIOS is an open-source project built and maintained by John Ellison and Chetan. Contributions are welcome.

Repos

Repo	What to contribute
`aios-workspace`	CLI, scaffold, validators, harness skills, Tauri GUI
`aios-team-brain`	Next.js dashboard, ingest pipeline, query layer, Supabase migrations
`aios-alpha.github.io`	Docs, guides, this site

The API contract

aios-workspace/docs/brain-api.md is the pinned sync contract. Changes to the sync protocol must be a versioned change in that file first. Open an issue to discuss breaking changes before coding them.

Development setup

Workspace

git clone https://github.com/AIOS-alpha/aios-workspace
cd aios-workspace
npm install

# Run validators against the example workspace
validation/validate-all.sh examples/sample-engagement

Team Brain

git clone https://github.com/AIOS-alpha/aios-team-brain
cd aios-team-brain
npm install
supabase start
cp .env.example .env.local
# fill in from `supabase status -o env`
npm run dev:seed   # seeds demo data
npm run dev

E2E test

cd aios-team-brain
bash scripts/e2e.sh
# → resets, seeds, pushes from sample workspace, pulls, queries, checks 422 guard

Local development per repo

Each repo has its own contributor guide — read the one for the repo you’re touching before you start:

Repo	Read this
`aios-team-brain`	`DEVELOPMENT.md` (run it locally, which test tier catches what) · `CONTRIBUTING.md` (the five things that gate a PR) · `docs/ARCHITECTURE.md` (where data lives)
`aios-workspace`	The repo README and `docs/` — scaffold, validators, harness skills, and the `aios` CLI

Your first contribution

The shape is the same across repos:

Find an issue — look for good first issue in the tracker, or ask a maintainer which epic needs hands.
Work in a git worktree, never a feature branch in the primary checkout. Others work in the primary checkout concurrently:
Terminal window
```
git fetch origin
git worktree add -b feat/<short-task> ../<repo>-<short-task> origin/main
cd ../<repo>-<short-task>
```
Open the PR from the worktree branch; git worktree remove <path> after it merges.
Write spec-first tests in the right tier — assert what the product should do, then run it. A spec-derived test that goes red found a real gap. In the brain, anything touching the DB or access control needs a data-mechanics test on real Postgres.
Keep the docs honest — in the brain, update docs/ARCHITECTURE.md in the same PR; if you add a route, table, or ingestion source, update the drift blocks or npm run check:docs fails.
Green before you open it — run the repo’s lint + tests, paste the output in the PR.

Before you open a PR

Run validation/validate-all.sh on any workspace changes
Run npm run test in the repo you changed
For brain-api.md changes: bump the version in the file header and note it in the PR
For new harness skills: include a rubric in .claude/rubrics/ and a sample output in examples/

Code of conduct

Be kind. This project started from real work with real teams. Contributions that make it more useful for teams doing serious AI work are the north star.