docs: expand AGENTS.md, add replication/DESIGN.md#141
Merged
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
Contributor
|
Reviewed; no blockers found. Commit |
cb1kenobi
approved these changes
May 21, 2026
heskew
approved these changes
May 21, 2026
Ethan-Arrowood
approved these changes
May 21, 2026
|
|
||
| ### Submodule | ||
|
|
||
| - **`core/`** — the Harper OSS core (`HarperFast/harper`). Has its own AGENTS.md, DESIGN.md, and now per-folder DESIGN.md docs. **When touching substrate behavior, edit there, not here.** |
Member
There was a problem hiding this comment.
Implying the developer has another copy of harper on their system?
Should these instructions potentially include how to link the submodule to the local git copy of harper when doing cross-repo development?
Member
Author
There was a problem hiding this comment.
Should these instructions potentially include how to link the submodule to the local git copy of harper when doing cross-repo development?
Sure, I would also like instructions on how to do that! How do you do that?
Member
There was a problem hiding this comment.
git submodule add /path/to/local/repo [folder_name]
Replace the 19-line AGENTS.md with a more substantive guide: full npm command reference, a "Where should this change go? (Pro vs core)" routing table, a folder map covering every top-level Pro directory, and cross-references into core's new per-folder docs. Add replication/DESIGN.md as a section index for the replication subsystem (~4200 lines across 6 files). Covers: file-level map, key abstractions (NodeReplicationConnection, Replicator, shared status buffers, hdb_nodes schema), the binary protocol command table with verified line numbers, subsystems (connection mgmt, protocol, data propagation, latency awareness, node discovery/TLS), and non-obvious behaviors including the auth-failure-without-DISCONNECT pattern relevant to issue #135 JWT/cluster lineage. Also flags that the cluster:* npm scripts reference utility/dev/ docker-compose files that aren't present in the repo. Generated by Claude Opus 4.7 (1M context). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Bare line numbers drift on every edit to replicationConnection.ts. Every referenced line corresponded to a named class, function, or top-level const — so references now use the symbol name. Reader uses grep or go-to-symbol to jump. No source-file changes; doc-only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
kriszyp
force-pushed
the
docs/agent-navigation
branch
from
d023688 to
69abd5a
Compare
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
5 participants
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
Replaces the thin (19-line)
AGENTS.mdand adds a newreplication/DESIGN.mdso agents can navigate Pro without grepping unfamiliar folders or reading the 2288-linereplicationConnection.tstop-to-bottom.AGENTS.md— full npm command reference, a "Where should this change go? (Pro vs core)" routing table that maps common change types to the right repo/folder, a folder map for every top-level Pro directory, and cross-references into core's new per-folder docs (core PR #522). The 19-line original was too thin to do its job.replication/DESIGN.md— section index for the replication subsystem (6 files, ~4200 lines). Includes: file-level map, key abstractions (NodeReplicationConnection,Replicator, sharedFloat64Arraystatus buffers,hdb_nodesschema), the binary protocol command table with verified line numbers, subsystem breakdown, and non-obvious behaviors.Goal
Reduce the overhead of starting a task in Pro. Pain points (raised by the user): too many files to grep, too many large files to review. Replication is also actively being debugged (issue #135 lineage on JWT/cluster auth), so a navigation guide there is highest-value.
Where to put attention
replicateOverWS(replicationConnection.ts:339+). Reviewer who's been debugging that area should confirm the framing is accurate before this becomes a "known fact" agents repeat.cluster:*scripts inpackage.jsonreferenceutility/dev/docker-compose.*.ymlfiles that don't exist in the repo (verified in both the docs worktree and the main checkout).AGENTS.mdnow notes this. If these files live somewhere or are produced by a private step, we should either commit them or remove the scripts.Test plan
replicationConnection.ts(197, 339, 192) andreplicator.ts(326, 334, 376)bin/,cloneNode/,licensing/,security/,analytics/utility/dev/anddocker-compose*files are absentThis is documentation only — no code or test changes.
Pairs with HarperFast/harper#522. Generated by Claude Opus 4.7 (1M context) via the
harper-engineering-guidelinesskill.