diff --git a/CLAUDE.md b/CLAUDE.md index 945b51d..83e777f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,41 +2,39 @@ ## Using atgc -When doing repo operations, always use the global install of `atgc` (not the one from your in-progress branch). To get a briefing, run `atgc agent` at the start of a session or when the version changes. +When doing repo operations, always use the global install of `atgc`. `atgc agent` is compiled into the binary and provides an up-to-date view of the current version's capabilities. ## Feature branch workflow -Some points to keep in mind: +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. -- 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). -- While doing work, you are one of many agents running on a system: - - Do not restart, reload, or otherwise modify the configuration of shared services. - - If you need temporary folders or other artifacts that exist outside your 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). -- 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. +To start work on a feature branch: -Before starting work on a feature: - -- Create a new branch like "claude/short-feature-name", based on `origin/main` -- Create a worktree in `.claude/worktrees` for working on the feature branch +- Run `git fetch origin main` +- Create the branch and its worktree: `git worktree add -b claude/short-feature-name .claude/worktrees/short-feature-name origin/main` - 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 +- 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` + +While doing work, be a good neighbor to humans and agents on your machine: -Each feature branch should include supporting work: +- Do not restart, reload, or otherwise modify the configuration of shared services. +- If you need temporary folders or other artifacts that exist outside your 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). -- Maintenance work to reduce duplicated or dead code -- Adding new debug log lines, OAuth log entries, or similar observability -- An update to any high-level documentation (if needed) -- A few of high-value tests (if applicable) +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 and similar observability +- Updating documentation pages or test suites - Checking off completed issues in TODO.md -Structure your commits: +Structure your commits for human review: - 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. -Before submitting a PR: +Confirm your work is acceptable before submitting a PR: - Run `git fetch origin main`, rebase onto it, and fix any conflicts - Ensure that all `prek` feedback has been fixed @@ -45,27 +43,27 @@ Before submitting a PR: 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. +- 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. 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. -To submit a PR: +When your work is ready for review, you must create a pull request. Do not report your work as "done" until you: -- Push the rebased 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, submit it via `atgc pr create` -- If the PR would be more than a handful of commits, prefer `atgc stack create` to break it into reviewable PRs for logical sub-features. `atgc stack resubmit` reconciles the chain after a rebase or reorder. -- When the PR has been created, post the Tangled PR link for the user to review. +- Push the feature branch to the origin. +- If the branch is one reviewable change, submit it via `atgc pr create` +- If the branch holds several logically separate changes, or changes that must land in a given order, use `atgc stack create` instead. It opens one PR per change, each with its own screenshots. `atgc stack resubmit` reconciles the chain after any rebase, amend or reorder. +- Post the Tangled PR link for the user to review. -When review feedback arrives, act on it without waiting to be asked. Each iteration, in this order: +When review feedback arrives, submit a new round of work. Follow these steps for each round: 1. Rebase against the latest `origin/main`, implement the changes, and repeat verification. 2. Push the updated feature branch. -3. Append a round with `atgc pr resubmit ` or `atgc stack resubmit`. This is what a reviewer sees; the push in step 2 shows them nothing on its own. -4. Update the title, body and any new screenshots with `atgc pr edit `. Resubmitting does not touch them. - -`pr list` and `pr status` read an index that can lag. When one of them disagrees with a direct `atgc pr view `, trust the direct read. +3. Append a round with `atgc pr resubmit ` or `atgc stack resubmit`. +4. Update the title, body and any new screenshots with `atgc pr edit `. After a feature is merged: +- Fetch `origin/main`. +- Confirm the work landed by checking that `git cherry origin/main ` prints no `+` lines. - Clean up your own worktree. -- Delete both the local and the remote feature branch. -- Leave any temporary artifacts (like Docker images). +- Delete both the local and the remote feature branch, passing `-D` to account for the patch-based workflow. +- Leave any temporary artifacts (like Docker images). Another agent may be using them, and they are a shared cache.