Skip to content

Docs: feat/<topic> branches and periodic cleanup #100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
b-re-w merged 1 commit into from
Oct 3, 2026
Merged

Docs: feat/<topic> branches and periodic cleanup #100

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 9 additions & 3 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,17 @@ build caches, model weights, `node_modules`) into every worktree is how 86 workt

| Branch | Who writes to it |
|---|---|
| `work/<topic>` | You. All work happens here. |
| `develop` | Merged into from work branches after verification. Never commit to it directly. |
| `feat/<topic>` | 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`.
Expand All @@ -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 "<keywords>"`).
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/<topic>` branch, push every commit, and open a pull request into `develop`
3. Work on a `feat/<topic>` branch, push every commit, and open a pull request into `develop`
whose body contains `Closes #<number>`.
4. Merge into `develop` through that pull request (`gh pr merge`), not by a local merge, so the
issue is linked.
Expand Down
Loading