Add design doc, restructure project docs#16
Merged
Conversation
Translates the theoretical design (renormalization/physics framing) into concrete engineering terms: data structures, algorithms, APIs, and implementation details. Self-contained for engineers who haven't read the companion papers.
Retains load-bearing theoretical concepts (entanglement structure,
boundary-based maintenance) explained in engineering-accessible language.
Tighter overall: 281 lines vs 683, with better motivation ("Why This
Design Works"), dual serve examples, and merged CLI/build phases.
Eat our own dogfood: README now serves as the Tier 1 constitution for agents working on this repo. Contains current state, repo layout, conventions, commands, and routing to the design doc and vision doc.
Describes what Aiome actually does (multi-scale knowledge infrastructure), links to the design doc and vision doc, keeps the honest current state.
One constitution, multiple entry points. Dogfooding the design doc's "same knowledge, multiple delivery formats" principle.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures and expands the project documentation to establish a single “project constitution” (README) and add a design/vision narrative for the intended Analyze → Generate → Serve architecture.
Changes:
- Added new docs: a detailed architecture design doc and a “vision & foundations” doc.
- Rewrote README.md to serve as the canonical constitution (current state, layout, conventions, commands, next steps).
- Updated HUMANS.md and added additional entry-point files intended to point users/agents at the canonical README.
Reviewed changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/vision.md | Adds the project’s vision/foundational concepts (BRAIN pattern, stigmergy, scaffolding). |
| docs/design-doc.md | Adds a comprehensive architecture/design document for the intended pipeline and CLI. |
| README.md | Rewrites README as the canonical constitution: current state, repo layout, conventions, commands, roadmap. |
| HUMANS.md | Updates the human-oriented overview and links to the new docs. |
| CLAUDE.md | Adds an agent entry-point file intended to direct to the canonical README. |
| AGENTS.md | Adds an agent entry-point file intended to direct to the canonical README. |
| GEMINI.md | Adds an agent entry-point file intended to direct to the canonical README. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Add arXiv link for Vasilopoulos (2026) citation in design doc - Match clippy command in README to CI flags (--all-targets --all-features -D warnings)
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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
docs/design-doc.md— engineering architecture doc covering Analyze → Generate → Serve pipeline, data model, maintenance loop, CLI design, open questionsVISION.mdtodocs/vision.mdREADME.mdas the project constitution: current state, repo layout, conventions, commandsHUMANS.mdto reflect current project direction and link to new docsCLAUDE.md,AGENTS.md,GEMINI.mdas symlinks toREADME.md— one constitution, multiple entry pointsTest plan