Repository navigation
Use project-prefixed keys in the README, usage guide, and project-init docs - #29
Merged
Merged
Conversation
A key identifies one document across the whole store; project only filters reads. The README still showed the legacy unprefixed form, where the same key (state:current) is used in several projects. Those calls all address one document, so each project's write replaces the others'. - Prefix every project example key with its project name, including the multi-project opening example, the AGENTS.md template, and the preview/apply examples. - State the rule in Key Conventions and show the prefix in its table; unprefixed keys belong to the default project (ref:devbrain-usage). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The seed usage guide (ref:devbrain-usage) is what agents read first, and it still taught the legacy unprefixed keys and described documents as "scoped by project". project-init.md said documents are "namespaced by the project parameter". Neither matches the store: a key identifies one document across all projects, and project only filters reads. - Lead the usage guide with the rule: every key starts with its project name and every call passes the project; unprefixed keys belong to the default project, which holds this guide. - Prefix the startup, query, metadata, and compare examples, show the prefix in the key table, and add a prefix check to troubleshooting. - Prefix every key and heading in project-init.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dsghi
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A key identifies one document across the whole store.
UpsertDocumentstores the item withid = keyand partition keykey;projectis a field that reads filter on, not part of the document's identity. The docs still showed the legacy unprefixed key format from before keys carried the project:Following that pattern, all three projects address the same stored document, so each project's write replaces the others'. To the agent, the other projects' documents seem to disappear after a successful write. This happened in practice when two agents initialized two projects in parallel using the documented startup pattern.
Changes (docs only)
{project}:forms in its table.docs/seed/ref-devbrain-usage.md(the guide agents load from thedefaultproject): it now leads with the rule, replacing "Documents Are Scoped by Project". Every key starts with its project name, every call passes the project, and unprefixed keys belong todefault, which holds this guide. The startup, query, metadata, and compare examples are prefixed, the key table shows the prefix, and troubleshooting checks for it first.docs/project-init.md: replaces "namespaced by theprojectparameter" with the prefix rule, and prefixes every key and heading.The only unprefixed key left in the docs is
ref:devbrain-usageindefault. Instances that already seeded the guide should re-seed it from the updated file.🤖 Generated with Claude Code