diffinery/AGENTS.md
| 1 | # AGENTS.md |
| 2 | |
| 3 | Guidance for AI coding agents (Claude Code, Codex, Cursor and others) working on this |
| 4 | repository. People should read [CONTRIBUTING.md](CONTRIBUTING.md); everything here agrees |
| 5 | with it. |
| 6 | |
| 7 | ## What this repository is |
| 8 | |
| 9 | Diffinery: an open-source git forge with GitHub Actions–compatible CI that runs entirely on |
| 10 | Cloudflare. One Cloudflare Worker serves the web UI, git over HTTPS, a GitHub-compatible |
| 11 | REST and GraphQL API and an MCP server; each repository is a Durable Object with its own |
| 12 | SQLite database; CI jobs run in Cloudflare Containers. Development happens at |
| 13 | https://diffinery.com/codician/diffinery; https://github.com/codician-team/diffinery is a |
| 14 | mirror. |
| 15 | |
| 16 | ## Layout |
| 17 | |
| 18 | ``` |
| 19 | apps/diffinery the Worker: src/ (web UI, git, REST/GraphQL, MCP, Actions), migrations/ (D1), |
| 20 | docs/ (served at diffinery.com/docs), site/ (marketing pages), test/ (unit and e2e) |
| 21 | apps/cli the `diffinery` command-line client |
| 22 | apps/vscode the VS Code, Cursor and Windsurf extension |
| 23 | apps/jetbrains the JetBrains IDE plugin |
| 24 | plugins the Claude Code and Codex plugins |
| 25 | containers/runner the runner agent, sandbox server and container image |
| 26 | packages/git-core git objects, packfiles, deltas, diff and merge, in pure TypeScript |
| 27 | packages/workflow-yaml the GitHub Actions workflow parser, expressions, matrices and cron |
| 28 | packages/shared types shared by the Worker and the runner |
| 29 | scripts setup and deploy scripts for Cloudflare |
| 30 | ``` |
| 31 | |
| 32 | ## Commands |
| 33 | |
| 34 | Node.js 22 and pnpm 10 (`corepack enable`). No Cloudflare account is needed to develop. |
| 35 | |
| 36 | ```sh |
| 37 | pnpm install |
| 38 | pnpm -r build # runner agent, web islands and docs |
| 39 | pnpm -r typecheck |
| 40 | pnpm -r test # unit tests (Vitest) |
| 41 | pnpm --filter @diffinery/app db:migrate:local # local D1 |
| 42 | pnpm dev # http://localhost:8787, signed in as dev@diffinery.local |
| 43 | cd apps/diffinery && node --test --test-timeout=600000 test/e2e/<file>.test.mjs # one e2e file |
| 44 | ``` |
| 45 | |
| 46 | Run repository tools with `pnpm exec`, never bare `npx`. Run the typecheck and the unit |
| 47 | tests before you ask for review, and the end-to-end file closest to your change. Tests must |
| 48 | not depend on the speed of the machine they run on. |
| 49 | |
| 50 | ## Rules |
| 51 | |
| 52 | - **Docs ship with the feature.** Any user- or admin-visible change updates the Markdown in |
| 53 | `apps/diffinery/docs` (and `apps/diffinery/site` for product pages). Write for people and |
| 54 | agents: short sentences, exact names of buttons, settings, endpoints and flags. |
| 55 | - **Follow GitHub where GitHub has an API, event or workflow feature**, so git, `gh`, |
| 56 | Octokit and actions keep working. Document any difference in |
| 57 | `apps/diffinery/docs/actions/compatibility.md` or the relevant page. |
| 58 | - **D1 migrations** live in `apps/diffinery/migrations`. Use the next free number and never |
| 59 | edit a migration that has shipped. |
| 60 | - **Security:** guardrails for agents are enforced on the server for git, REST, MCP and the |
| 61 | web UI alike. Never add a bypass, never log secrets or tokens, and never weaken push |
| 62 | protection, branch protection or the runner sandbox to make something pass. |
| 63 | - **UI:** passkeys first, no passwords; Kumo components through `KSelect`, `KCheckbox` and |
| 64 | `KRadio`, never a native `<select>`, checkbox or radio. See |
| 65 | [docs/PREFERENCES.md](docs/PREFERENCES.md). |
| 66 | - **Code style:** strict TypeScript, few dependencies, comments that say why, matching the |
| 67 | density and style of the code around your change. |
| 68 | - **Pull requests:** one change each, a title that says what it does, an `intent` that says |
| 69 | what it is for, and the person you work for in the description. Changes under |
| 70 | `.github/workflows` need a maintainer to merge them. Never skip or disable a test to get |
| 71 | green. |
| 72 | |
| 73 | ## Reading the docs as an agent |
| 74 | |
| 75 | Every docs page is Markdown at `https://diffinery.com/docs/<page>.md`, the whole set is in |
| 76 | https://diffinery.com/llms.txt and https://diffinery.com/llms-full.txt, and the MCP server |
| 77 | at `https://diffinery.com/mcp` has `search_docs` and `read_docs`. See |
| 78 | [Docs for AI agents](https://diffinery.com/docs/agents/docs-for-agents). |