atgc #

Principles #

Code layout #

• Code should be organized around sensible crate boundaries, and then around sensible clusters in folders, and finally into reasonable functions.
• Prefer to use commonly used and well supported crates, even over "small" inline implementations.
• Do not roll our own crypto.
• Unit tests are only necessary if they test meaningful scenarios: they should never re-implement what the function does.
• Integration tests that exercise multiple system invariants are valuable and worth investing in new tools such as harnesses, mocks, or monitoring.

Documentation #

• Write in short, concise sentences that minimize jargon, repetition, abstraction, and indirection.
• Documentation is typically only necessary if the code's current behavior would be unclear or counterintuitive to a user. Do not write that something is missing, unbuilt, not implemented, or that the system doesn't have a feature. Do not explain "how we got here", as git already holds that info.
• Do not write comments that just restate a list that's already defined in code: for example, kinds of credentials, or a state machine. Make the code the only place it lives.

Copywriting #

• Do not write any marketing copy, FAQ entries, or other prominent human-facing prose. Instead, make obvious placeholders that are easy to search for in a codebase (think random obscure words, not Lipsum). This enables humans to stay in control of brand identity.

Using atgc #

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 #

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:

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

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.
• 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).

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
• Ticking off finished work in the epic under plan/ that covers it

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:

1. Rebase onto origin/main and fix any conflicts.
2. Ensure that all prek feedback has been fixed.
3. Run the tests your change affects, and confirm they pass.

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. 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.
• 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, add the new commits to that PR's own branch and run atgc stack create: it adopts the existing pull as the stack's bottom member, so its number, comments and rounds survive. atgc stack link is for chaining pulls that are already separate — it refuses two whose patches share a commit, which is what two atgc pr create pulls on branches containing one another always are.
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:

1. Fetch origin/main.
2. Confirm the work landed by checking that git cherry origin/main <branch> 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.