From c7b033d77fbe2eb4bb2c05b4401b56ececad76e1 Mon Sep 17 00:00:00 2001 From: "@permadeath.com" Date: Wed, 26 Aug 2026 11:18:24 -0400 Subject: [PATCH] docs: sync the feature branch workflow with atgc 0.15 Numbered steps, a prek install step, and the stack, round and merge guidance the current CLI actually offers. --- CLAUDE.md | 142 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 59 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c79e004..2cf05a8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,34 +15,22 @@ checkout's git config names, so check `atgc auth status` before assuming. ## Feature branch workflow -If asked to do work, unless directly instructed otherwise, do not make changes to -the user's top-level git checkout (other than making worktrees attached to it). -All of your work will be on feature branches. +If asked to do work, unless directly instructed otherwise, do not make changes +to the user's top-level git checkout. All of your work will be on feature +branches and inside git worktrees. To start work on a feature branch: -- Create a new branch like "claude/short-feature-name", based on `origin/main` -- Create a git worktree in `.claude/worktrees` for working on the feature branch -- Enter the worktree so that all commands run inside of it -- Double check that the repo-local `.git/config` `[user]` section has an ATProto - `@-` handle as a `name` and its `did:plc` as an email +1. Run `git fetch origin main` +2. Create the branch and its worktree: + `git worktree add -b claude/short-feature-name .claude/worktrees/short-feature-name origin/main` +3. Enter the worktree so that all commands run inside of it +4. Double check that the repo-local `.git/config` `[user]` section has an + ATProto `@-` handle as a `name` and its `did:plc` as an email. If it does + not, run `atgc repo configure` +5. Ensure that `prek` is installed in your worktree via `prek install` -Each feature branch should include supporting work: - -- Maintenance work to reduce duplicated or dead code -- Adding new debug log lines, counters, or similar observability -- An update to any high-level documentation (if needed) -- A few of high-value tests (if applicable) -- Checking off completed work in the epic in `plan/` that the work belongs to - -Structure your commits: - -- Break work into logical commits, typically 1-5 for an average feature. -- Use Conventional Commits, including adding "!" indicators for breaking behavior - changes. -- Don't write more than 1 short sentence + 1 short paragraph into a commit body. - -While doing work, respect other agents running on the system: +While doing work, be a good neighbor to humans and agents on your machine: - Do not restart, reload, or otherwise modify the configuration of shared services. @@ -50,60 +38,96 @@ While doing work, respect other agents running on the system: worktree (such as Docker images), reduce conflicts by tagging them with your current branch and/or SHA. - Check available system resources before running expensive commands (memory or - CPU). A match is two thinking bots and a server in one container; `--jobs` - defaults to 2 for that reason. + CPU). +- A match is two thinking bots and a server in one container, so `--jobs` + defaults to 2. - Never run `sds clean` while somebody's benchmark is running. It kills every match container on the machine, including theirs. -Before submitting a PR: +Make sure your work includes a "maintenance budget" for code directly related to +your current feature: + +- Reducing duplicated or dead code +- Adding new debug log lines, counters, and similar observability +- Updating documentation pages or test suites +- Checking off completed work in the epic in `plan/` that the work belongs to + +Structure your commits for human review: + +- Break work into a sequence of logical commits, typically 1-5 for an average + feature. +- Use Conventional Commits, including adding "!" indicators for breaking + behavior changes. +- Don't write more than 1 short sentence + 1 short paragraph into a commit body. + +Confirm your work is acceptable before submitting a PR: -- Check for new commits on `origin/main`. Rebase and fix any conflicts -- Ensure that all `prek` feedback has been fixed -- Ensure that relevant tests pass: `cargo test -j 2 --workspace` and - `python3 -m unittest discover -s tests -t .` -- If the change could plausibly affect play, run `./sds.sh control` and say what - it came out at. A harness change that was not controlled is not finished. +1. Rebase onto `origin/main` and fix any conflicts. +2. Ensure that all `prek` feedback has been fixed. +3. Run the relevant tests: `cargo test -j 2 --workspace` and + `python3 -m unittest discover -s tests -t .`. +4. If the change could plausibly affect play, run `./sds.sh control` and say + what it came out at. A harness change that was not controlled is not + finished. -When writing any PRs, updates to PRs, or comments on PRs: +When your work is ready for review, you must create a pull request. When writing +any PRs, updates to PRs, or comments on PRs: - The PR title should be simple and descriptive, and should use Conventional Commits. +- The PR body should be three paragraphs at most. Focus on a concise, + descriptive explanation of what changed. Avoid commentary on implementation + details or future work. - The PR body should contain a before/after screenshot if the change has a visible effect (UI, rendered output, a CLI's printed text). Attach this with Markdown image syntax and a local image path: the `atgc` commands will upload - it for you. + it for you. The file does not need to be committed anywhere, and each image + must be under 1 MB or the command refuses it before sending anything. - A change meant to improve play carries its `comparison.md` in the body, and says what was predicted before the numbers are shown. - All code will be human-reviewed. All commentary about feature implementation should be concise, avoid flowery or verbose language, and focus on what the change accomplishes. - -When your work is ready for review, submit a PR. Do not claim your work is -"done" without following these steps: - -- Push the feature branch to the origin. Tangled uses patch-based rounds, so - pushing a remote and submitting a PR are different operations. -- If the PR is a handful of commits with no subfeatures expected, submit the - change via `atgc pr create` -- If the PR would be more than a handful of commits or will be followed up by - additional feature PRs with a dependency order, prefer `atgc stack create` to - break the change into logical sequences of reviewable PRs. -- When the PR has been created, post the Tangled PR link for the user to review. - -If asked to iterate post-submission, each iteration should: - -- Rebase against the latest `origin/main`, implement the changes, and repeat - verification. -- Push the latest updates to the feature branch. -- Push a new patch to the existing PR via `atgc pr resubmit` or - `atgc stack resubmit`. -- Push a new PR title/body (including new screenshots) with `atgc pr edit`. +- Do not report your work as "done" until you post the Tangled PR link for the + user to review. + +If the branch is a single reviewable feature, create the PR using +`atgc pr create`. + +If the branch holds several separable but related feature PRs that must land in +a given order, use `atgc stack create` instead: + - Each PR carries multiple commits, and its own description and screenshots. + - Use `atgc stack mark` when you need to turn commit ranges into stacked + feature PRs. + - Use `atgc stack resubmit` when you need to reconcile the upstream stack + after any rebase, amend or reorder. + +When review feedback arrives, you will need to submit a new "round" on the +existing PR. Follow these steps for each round: + +1. Rebase against the latest `origin/main`, or if stacked, use + `atgc stack sync`. +2. Implement the requested changes. +3. Repeat the required verification steps. +4. If your PR is not yet stacked and you need to begin stacking a new feature on + top of it, use `atgc stack link`. +5. Append a new review round to the PR with `atgc pr resubmit` (non-stacked) or + `atgc stack resubmit` (stacked). Both republish the branch themselves, leased + against the head the last round recorded, so do not `git push` first; if one + refuses because the branch is somewhere neither of you expected, look at what + is there rather than forcing past it. +6. Update the PR title, body and any new screenshots with `atgc pr edit`. After a feature is merged: -- Clean up your own worktree. -- Delete both the local and the remote feature branch. -- Leave any temporary artifacts (like Docker images). +1. Fetch `origin/main`. +2. Confirm the work landed by checking that `git cherry origin/main ` + prints no `+` lines. +3. Clean up your own worktree. +4. Delete both the local and the remote feature branch, passing `-D` to account + for the patch-based workflow. +5. Leave any temporary artifacts (like Docker images). Another agent may be + using them, and they are a shared cache. ## The plan -- 2.51.2