From 8f8c900e7bf5363f48672d5755050cdaa4dff285 Mon Sep 17 00:00:00 2001 From: "@conglomerate-dipper.test.pds.did.bot" Date: Mon, 26 Oct 2026 12:00:28 -0400 Subject: [PATCH] docs: adopt the standard agent rules from did.bot Replaces the generic workflow, commit and PR sections with the shared text from did.bot's AGENTS.md, keeps the tally-specific sections, and adds a CLAUDE.md that loads AGENTS.md. Co-Authored-By: Claude Opus 5.5 Change-Id: I1e3ebf9a5bcb5632b4f80e265cc6506933d3d1e2 --- AGENTS.md | 128 ++++++++++++++++++++++++++++++++---------------------- CLAUDE.md | 1 + 2 files changed, 77 insertions(+), 52 deletions(-) create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index 8856285..53f70a6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,11 +8,29 @@ The app is a Rust worker plus plain HTML/CSS/JS. There is no server in the request path. AWS infrastructure lives in the private platform repo; this repository is application code only. +## 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 -Use the global `atgc` install for repo operations. Run `atgc agent` at the start -of a session or when the version changes; it is the up-to-date briefing for the -binary you are actually running. +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. This repo is owned by `@permadeath.com`. `atgc` acts as whichever account the checkout's git config names, so check `atgc auth status --agent` before assuming. @@ -29,45 +47,70 @@ Do not `git push`. The patch is the review artifact. ## Feature branch workflow -If asked to do work, unless directly instructed otherwise, do not make changes -to the user's top-level checkout. Work on a feature branch, preferably in a -worktree: +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: -1. `git fetch origin main` -2. `git worktree add -b claude/short-feature-name .claude/worktrees/short-feature-name origin/main` -3. Enter the worktree so all commands run there. -4. Check the repo-local `.git/config` `[user]` section. `name` should be an - ATProto `@-` handle and `email` its `did:plc`. If not, run - `atgc repo configure`. +- 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). -One branch and one PR per reviewable feature. If a branch holds separable -features that must land in order, use `atgc stack create` and -`atgc stack resubmit` rather than one large PR. +Make sure your work includes a "maintenance budget" for code directly related to your current feature: -## Working alongside other agents +- Reducing duplicated or dead code +- Adding new debug log lines and similar observability +- Updating documentation pages or test suites +- Keeping the dashboard's copy short; numbers should carry the page -- Do not restart, reload, or change the configuration of shared services. -- Tag temporary images or artifacts with the branch or SHA. -- Check memory, CPU, and disk before expensive builds or crawls. -- Keep generated state out of the repo: SQLite, `dist/`, tokens, salts and - Python caches are ignored. -- A denied tool call is a hard stop. Report it; do not route around it. +Structure your commits for human review: -## Maintenance budget +- 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. -Leave the feature's immediate area better than you found it: +Confirm your work is acceptable before submitting a PR: -- remove dead code or duplicate paths the change exposes -- add counters or log lines where the behavior is otherwise opaque -- update README, `docs/mockup.html`, or tests touched by the feature -- keep the dashboard's copy short; numbers should carry the page +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. -## Commits +When your work is ready for review, you must create a pull request. When writing any PRs, updates to PRs, or comments on PRs: -- Use Conventional Commits, with `!` for breaking behavior. -- Break work into 1–5 logical commits for an ordinary feature. -- Keep the body to one short sentence plus one short paragraph. -- Do not collapse a reviewable series into one large commit. +- 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 --patch-only`. + +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. Append a new review round to the PR with `atgc pr resubmit` (non-stacked) or `atgc stack resubmit` (stacked). +5. 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 ` 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. ## Verification @@ -85,25 +128,6 @@ For dashboard changes, regenerate `docs/mockup.html` and the committed preview images when the environment can render them. For scanner changes, test both the personal and work labels, including the hashed work path. -## Pull requests - -- Title: concise Conventional Commits subject. -- Body: three short paragraphs at most. Say what changed and how it was - verified. Avoid implementation narration, apologetics, and future-work - promises. -- Attach a before/after screenshot for visible UI or printed-output changes - when possible. `atgc` uploads local image paths in the body; each must be - under 1 MB. -- Do not call work done until the Tangled PR link is posted. - -## After merge - -1. `git fetch origin main` -2. `git cherry origin/main ` should show no `+` lines. -3. Remove your worktree. -4. Delete the local branch with `-D` (patch-only PRs leave no remote branch). -5. Leave temporary Docker images and caches; another agent may be using them. - ## Data handling - `--label work` hashes every repository, public or private. Never send work diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md -- knotmirror 0.0.1