Contributing

How to build, test and change ai-coach. For how it's put together, read ARCHITECTURE.md first; for why, the decision records.

Build and test

The workspace is an Nx monorepo. After npm install:

npx nx run-many -t build          # build everything
npx nx run-many -t test           # run every test
npx nx run-many -t lint typecheck # check style, types and package boundaries
npx nx format:check               # check formatting
npx nx test @ai-coach/domain      # test one package
npx nx graph                      # see how the packages depend on each other

Tests don't need Ollama, Gemini or kb-template: each layer is tested with fakes or a local stub server. The vault adapter has no automated tests yet (ADR-0010), so try changes to it against a copy of a vault.

CI runs format, lint, test, build and typecheck on every push to main and every pull request.

Documentation

The documentation site is built from the Markdown in this repository and deploys from main (ADR-0032). Edit the files where they are; apps/docs only arranges them.

npx nx serve docs                 # preview the site while you edit
npx nx build docs                 # build it and check every link

What you're writing	Where it goes
What ai-coach is, how to start	README.md: keep it to one screen
How to use it	docs/guide/
How to work on it	this file
How it's built	ARCHITECTURE.md and each package's README
Why it's built that way	docs/adr/
Planning with Claude Code	.claude/skills/README.md

Write for someone new: say who a page is for and what they'll be able to do, use short sentences and "you", and link a term to the glossary instead of explaining it twice (ADR-0034).

House rules

• Important changes come with a decision record in docs/adr/, in the same commit. ADR-0001 says what counts. Start from docs/adr/template.md. Accepted records are never rewritten, only superseded.
• No comments in source code. Names and tests carry the meaning (ADR-0011).
• Commit messages follow Conventional Commits: feat(cli): add the review command, fix(domain): …, docs: …, build: …. CI checks every commit in a pull request (ADR-0033); npx commitlint --from origin/main checks yours before you push.
• Rules go in the domain, not in prompts. If a model could talk its way past it, it belongs in code.
• New vault abilities belong in kb-template, not in adapter-vault-mcp, which only wraps what the server offers.
• Never point tests or experiments at your real vault. Use a copy.