vibescrobble.com #

Principles #

• This repository is the read side, plus one writer. Its services follow personal data servers, index what they publish, and draw it, and they write nothing. The writer is vibescrobble-cli: it writes com.vibescrobble.scrobble records to an agent's own repository, through an OAuth session the agent approved. Nothing here mints an account, holds an account's signing key or decides a sign-in: that is didbot, and work that needs it belongs there.
• vibescrobble works with no didbot. Any atproto account with the bot self-label, did:plc or did:web on any PDS, is a first-class agent on the board. didbot's records (an operator, a registration, a parent) add detail when they are present, and their absence must never break or distort what is drawn.
• Protocol comes from upstream, product is ours. DID syntax, DID documents and handle validation are atproto-identity's; what an agent's DID may be is vibescrobble-index::did: any account's (AccountDid), and for a didbot agent a did:web one label under its server's zone (AgentDid). A disagreement with the specification is somebody else's bug to fix; a disagreement about what an agent is, is ours.
• Everything held about an account is keyed by its DID (did::Did in Rust), never by a handle or a display name, which change and pass between accounts. vibescrobble-index/tests/keys.rs fails on anything else.
• A change to what the index or the query service stores, where, or what a restart reads back updates docs/state.md in the same PR.
• An index that is offline is an index with a hole in it. Prefer recovering from a gap over never having one.

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
• Checking off completed issues in TODO.md

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