From fde4167634dff88f67975766eb1f709f9af003e1 Mon Sep 17 00:00:00 2001 From: "@permadeath.com" Date: Tue, 18 Aug 2026 14:20:09 -0400 Subject: [PATCH] docs: sync CLAUDE.md with the current atgc guidance Ports the atgc repo's rewritten agent instructions into this one. The atgc note is now one line pointing at `atgc agent`, and the workflow gains the shared-machine points, entering the worktree, passing tests before submitting, pushing the branch as a step separate from opening the PR, and cleaning up after a merge. --- CLAUDE.md | 66 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 18 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8b06a58..c8d741d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ ## Using atgc -Use the globally installed `atgc` CLI for repo operations. If needed, use `--help` options to query what features are enabled in that version. +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. ## Using goat @@ -30,33 +30,63 @@ Write `description` the way published lexicons do. Read some first: ## 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 (other than making subtrees 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. + Before starting work on a feature: -- Ensure that `main` and `origin/main` are up to date -- Create a new branch like "claude/short-feature-name" -- Create a worktree in `.claude` for working on it -- Ensure that the repo-local `.git/config` `[user]` section is using an ATProto `@-` handle as a `name`, and a `did:plc` instead of an email +- 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 +- 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 + +Each feature branch should include supporting work: + +- Maintenance work to reduce duplicated or dead code +- Adding new debug log lines or similar observability +- An update to any high-level documentation (if needed) +- A few of high-value tests (if applicable) +- Checking off completed issues in TODO/ Structure your commits: - Break work into logical commits, typically 1-5 for an average feature. -- Don't write more than 3 short paragraphs in a commit body. This often means you did too much work in a single commit. - 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. -Each feature branch should include supporting work: +Before submitting a PR: -- Adding any new debug log lines or similar observability -- An update to any high-level documentation, but only if needed -- A few of the most high-value tests -- Updating anything relevant in TODO/ +- Check for a rebase against `origin/main` and fix any conflicts +- Ensure that all `prek` feedback has been fixed +- Ensure that relevant tests pass -When ready to submit: +When writing any PRs, updates to PRs, or comments on PRs: -- Check for a rebase against `main` and fix any conflicts -- Ensure that all `prek` feedback has been fixed -- Submit the PR with the installed `atgc` CLI: `atgc pr create` +- The PR title should be simple and descriptive, and should use Conventional Commits. +- 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. + +To submit a PR: + +- 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. + +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`. -If asked to iterate post-submission: +After a feature is merged: -- Update the existing PR via `atgc pr resubmit`, rather than with a new `atgc pr create`. -- Make sure to update the PR body with `atgc pr edit`, not just the patches. +- Clean up your own worktree. +- Delete both the local and the remote feature branch. +- Leave any temporary artifacts (like Docker images). -- 2.51.2