didbot #

Principles #

Overall system #

• didbot instances will be on the public internet, and hold sensitive credentials. They must be as secure as we can manage.
• didbot instances (or their managed accounts) that go permanently offline break other apps. They must be high reliability.
• Do not add a new type of credential without a human explicitly approving doing so.
• Do not add a state, a field, or a lifecycle without a human reviewing the state machine it belongs to.

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:

• 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. If it does not, run atgc repo configure

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
• Checking off completed items in the ## Done list of the epic's plan/ file

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.

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
• Run the tests your change affects, and confirm they pass

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.

When your work is ready for review, you must create a pull request. Do not report your work as "done" until you:

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

Conflicts in plan/ #

plan/README.md's tables are generated from plan/*.md, and plan/order.txt is a flat list. Two branches that each add an epic conflict in both, over rows carrying no information. .gitattributes handles it, once you register the driver it names:

git config merge.plan-readme.name "keep one side; scripts/gen-plan-readme.py makes it true"
git config merge.plan-readme.driver "true"

order.txt then union-merges on its own. After any merge or rebase touching plan/, run scripts/resolve-plan.sh: it regenerates the tables, checks the register, and catches a duplicated id the union merge could leave behind.

Adding a new epic to order.txt is optional — an unlisted epic sorts to the end of its table. Leaving it out is one fewer line to conflict over, and worth doing unless where the epic sits is worth saying.

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 <pr> or atgc stack resubmit.
4. Update the title, body and any new screenshots with atgc pr edit <pr>.

After a feature is merged:

• Fetch origin/main.
• Confirm the work landed by checking that git cherry origin/main <branch> prints no + lines.
• Clean up your own worktree.
• 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.