diff --git a/AGENTS.md b/AGENTS.md index d0fa6e322..5bee08279 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,11 +47,17 @@ build caches, model weights, `node_modules`) into every worktree is how 86 workt | Branch | Who writes to it | |---|---| -| `work/` | You. All work happens here. | -| `develop` | Merged into from work branches after verification. Never commit to it directly. | +| `feat/` | You. All work happens here. Never name a branch `work/...`. | +| `develop` | Merged into from `feat/` branches after verification. Never commit to it directly. | | `release` | **CI only.** Not a standing branch: CI regenerates it from every push to `develop`, in the main-only file layout, and opens the PR into `main`. It may not exist. Never write to it. | | `main` | **Pull request from `release` only.** Never push or merge to it directly. | +Only `main`, `develop` and `release` are standing branches. A `feat/` branch lives until its pull +request merges: merge with `gh pr merge --delete-branch`, then delete the local branch and its +worktree. Periodically delete every branch already merged into `develop`, remote and local +(`git branch -r --merged origin/develop`); an unmerged branch older than a few days is either +landed or reported, not left. Branches named `release-*` are preserved snapshots: keep them. + `main` carries a reduced layout: of the Markdown files, only `README.md` stays at the repository root, and `docs/` keeps only its subdirectories (no Markdown files directly under `docs/`). CI runs `tools/release/sync-release.sh` (`.github/workflows/release-sync.yml`) to produce that layout; do not hand-edit `release` or `main`. @@ -63,7 +69,7 @@ Every new feature goes through an issue and a pull request: 1. Before starting, search the repository's issues (`gh issue list --state all --search ""`). 2. If no issue covers the work, open one (`gh issue create`) stating what and why, and the completion criterion — which tests must pass. -3. Work on a `work/` branch, push every commit, and open a pull request into `develop` +3. Work on a `feat/` branch, push every commit, and open a pull request into `develop` whose body contains `Closes #`. 4. Merge into `develop` through that pull request (`gh pr merge`), not by a local merge, so the issue is linked.