docs: split DESIGN_SPEC.md into 7 focused design pages#308
Conversation
Split the 3527-line monolithic DESIGN_SPEC.md into a structured documentation site per issue #303: - 7 design pages under docs/design/ (agents, organization, communication, engine, memory, operations, index) - Supporting pages: tech-stack, roadmap (3 pages), reference (2 pages) - Rewritten decision log as scannable tables by domain - Root DESIGN_SPEC.md replaced with ~40-line pointer file - Deleted old docs/design_spec.md - Rewritten README.md with badges, capability cards, mermaid diagram - Updated all cross-references across 8+ files - ADR files added to mkdocs.yml nav - MkDocs Material features: tabs, collapsible sections, admonitions, mermaid diagrams, grid cards, definition lists Validated by 6 parallel agents checking completeness, factual correctness, statement preservation, link integrity, issue requirements, and clarity. All findings addressed. Closes #303
Update CLAUDE.md, README.md, mkdocs.yml, and all cross-references to point to the new docs/design/ pages instead of monolithic DESIGN_SPEC.md section numbers. Add tech-stack, roadmap, and reference pages to MkDocs navigation.
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (6)
📝 WalkthroughSummary by CodeRabbit
WalkthroughSplits the monolithic DESIGN_SPEC into a multi-page design docs set, adds tech-stack and decision-log pages, reorganizes MkDocs/site navigation and README, adds roadmap/reference content and small site UI tweaks, and updates dozens of module docstrings to point at the new design pages. No runtime code changes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the project's documentation by reorganizing a large, single design specification into a more modular and navigable structure. This change improves the discoverability and readability of critical design information, making it easier for contributors and users to understand the system's architecture, agent behaviors, and operational aspects. The update also streamlines the documentation build process and ensures all internal links are consistent with the new layout. Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
There was a problem hiding this comment.
Code Review
This pull request is a significant and well-executed refactoring of the project's documentation. It splits a monolithic design specification into seven focused pages, improving navigability and maintainability. The README.md has been refreshed for better presentation, and the overall documentation structure is now more logical with new sections for Roadmap and Reference. I've found a couple of minor areas for improvement regarding link consistency and clarity in the new documentation pages.
README.md
Outdated
|
|
||
| ## Status | ||
|
|
||
| Core framework complete — agent engine, multi-agent coordination, API, security, HR, memory, and budget systems are implemented. Remaining: Mem0 adapter backend, approval workflow gates, CLI, web dashboard. See the [roadmap](https://synthorg.io/docs/roadmap/) for details. |
There was a problem hiding this comment.
The link to the roadmap in the 'Status' section is an absolute URL (https://synthorg.io/docs/roadmap/). This is inconsistent with other links in the file, such as those in the 'Documentation' table, which are relative (e.g., docs/design/index.md). Using a relative link here would improve consistency and ensure the link works correctly within the GitHub repository view, even before deployment.
| Core framework complete — agent engine, multi-agent coordination, API, security, HR, memory, and budget systems are implemented. Remaining: Mem0 adapter backend, approval workflow gates, CLI, web dashboard. See the [roadmap](https://synthorg.io/docs/roadmap/) for details. | |
| Core framework complete — agent engine, multi-agent coordination, API, security, HR, memory, and budget systems are implemented. Remaining: Mem0 adapter backend, approval workflow gates, CLI, web dashboard. See the [roadmap](docs/roadmap/index.md) for details. |
| - `COMPLETED` termination: IN_PROGRESS -> IN_REVIEW -> COMPLETED (two-hop | ||
| auto-complete; reviewers planned). |
There was a problem hiding this comment.
The phrase 'two-hop auto-complete' for the COMPLETED termination reason is a bit ambiguous. It could imply that the IN_REVIEW step is automatically skipped. Given the state diagram and the note about 'reviewers planned', it would be clearer to state that the task moves to IN_REVIEW to await approval before being marked as COMPLETED.
| - `COMPLETED` termination: IN_PROGRESS -> IN_REVIEW -> COMPLETED (two-hop | |
| auto-complete; reviewers planned). | |
| - `COMPLETED` termination: `IN_PROGRESS` -> `IN_REVIEW`. The task will then move to `COMPLETED` upon approval. |
There was a problem hiding this comment.
Pull request overview
This PR restructures the project’s documentation by splitting the large DESIGN_SPEC.md into focused pages under docs/design/, updating MkDocs navigation and cross-links across the repo, and refreshing the public landing page + README to point at the new doc structure.
Changes:
- Split the design spec into 7 pages under
docs/design/and updated MkDocs nav accordingly. - Added new documentation sections/pages (Roadmap, Reference, Tech Stack, ADR-003) and rewired internal links.
- Updated external entry points (Astro landing page, README, CLAUDE.md) to reference the new doc URLs/paths.
Reviewed changes
Copilot reviewed 23 out of 25 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| site/src/pages/index.astro | Updates landing-page links from /docs/design_spec/ to /docs/design/. |
| mkdocs.yml | Replaces single design spec page with a multi-page “Design” section; adds Roadmap/Reference sections and ADR entries. |
| docs/user_guide.md | Updates quick start and design spec link to new design pages. |
| docs/roadmap/open-questions.md | Adds a roadmap page capturing open questions and risk tracking. |
| docs/roadmap/index.md | Adds roadmap overview/status and remaining work list. |
| docs/roadmap/future-vision.md | Adds post-MVP future vision and scaling phases. |
| docs/reference/standards.md | Adds a standards reference page (MCP/A2A/OpenAI format). |
| docs/reference/research.md | Adds research/prior-art and comparison tables with citations. |
| docs/index.md | Adds a “Design Specification” section with cards linking to the new design pages and adds roadmap/architecture references. |
| docs/getting_started.md | Updates references to treat DESIGN_SPEC.md as a pointer to design pages. |
| docs/design/organization.md | New organization/templates design page (hierarchy, scaling, template inheritance). |
| docs/design/operations.md | New operations design page (providers, budget, tools, security, HITL). |
| docs/design/memory.md | New memory/persistence design page (protocols, org memory, injection strategies). |
| docs/design/index.md | New design overview/index page linking to the other design pages. |
| docs/design/engine.md | New engine design page (task lifecycle, loops, routing, recovery, shutdown, isolation). |
| docs/design/communication.md | New communication design page (bus patterns, loop prevention, conflict resolution, meetings). |
| docs/design/agents.md | New agents/HR design page (identity, roles, hiring, metrics, promotions). |
| docs/decisions/ADR-003-documentation-architecture.md | Updates ADR-003 implementation section to match new docs layout. |
| docs/architecture/tech-stack.md | Adds a tech stack + engineering conventions page. |
| docs/architecture/index.md | Updates architecture “Further Reading” links to point to new design pages/tech stack/decision log. |
| docs/architecture/decisions.md | Refactors “Design Decisions” into a domain-organized “Decision Log” with embedded summaries. |
| README.md | Refreshes README layout (badges/table), updates doc links and quick start commands. |
| CLAUDE.md | Updates guidance to read docs/design/ pages (with DESIGN_SPEC.md as a pointer) and revises docs structure notes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```yaml | ||
| departments: | ||
| engineering: | ||
| head: "cto" | ||
| budget_percent: 60 | ||
| teams: |
There was a problem hiding this comment.
The department config example uses a mapping keyed by department name (e.g., departments: engineering:), but the validated config shape expects departments to be a list/tuple of department objects with a name field. As written, this YAML would fail RootConfig/Template validation. Update the example to departments: - name: engineering ... (and similarly for other departments).
docs/design/organization.md
Outdated
| `departments` mapping | ||
| : Merged by key (case-insensitive). A child department replaces the parent entry entirely. |
There was a problem hiding this comment.
In the template inheritance merge semantics, departments is described as a "mapping" merged by key. In the implementation, template departments are a list merged by department name (case-insensitive), where a child department with the same name replaces the parent entry. Adjust this bullet to describe list semantics to match src/ai_company/templates/merge.py / RootConfig.departments typing.
| `departments` mapping | |
| : Merged by key (case-insensitive). A child department replaces the parent entry entirely. | |
| `departments` list | |
| : Merged by department `name` (case-insensitive). A child department with the same `name` | |
| replaces the parent entry entirely; departments with new names are appended. |
| cp docker/.env.example docker/.env | ||
| docker compose -f docker/compose.yml up -d | ||
| ``` | ||
|
|
||
| The web dashboard is at [http://localhost:3000](http://localhost:3000). | ||
|
|
||
| All configuration — LLM provider keys, organization setup, templates — is managed through the dashboard. | ||
| All configuration — organization setup, templates — is managed through the dashboard. | ||
|
|
There was a problem hiding this comment.
The quick start now instructs copying docker/.env.example (which contains required settings like LLM_API_KEY), but the guide then says “All configuration … is managed through the dashboard.” This is inaccurate/misleading: at minimum, provider credentials and service ports are configured via docker/.env (and the dashboard is flagged as WIP). Consider clarifying that runtime/env configuration lives in docker/.env, while org/template settings are (planned to be) managed via the dashboard/API.
Greptile SummaryThis PR splits the monolithic 3500-line Key findings:
Confidence Score: 4/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
OLD["DESIGN_SPEC.md\n(3500+ lines monolithic)"]
NEW_PTR["DESIGN_SPEC.md\n(pointer file)"]
OLD -->|split| NEW_PTR
NEW_PTR --> D1["docs/design/index.md\n(Vision, Glossary)"]
NEW_PTR --> D2["docs/design/agents.md\n(Agent System, HR)"]
NEW_PTR --> D3["docs/design/organization.md\n(Company Structure)"]
NEW_PTR --> D4["docs/design/communication.md\n(Message Bus, Meetings)"]
NEW_PTR --> D5["docs/design/engine.md\n(Task Engine, Recovery)"]
NEW_PTR --> D6["docs/design/memory.md\n(Memory, Persistence)"]
NEW_PTR --> D7["docs/design/operations.md\n(Providers, Budget, Security)"]
ADR1["docs/decisions/ADR-001"] -->|consolidated into| DLOG["docs/architecture/decisions.md\n(unified Decision Log)"]
ADR2["docs/decisions/ADR-002"] -->|consolidated into| DLOG
ADR3["docs/decisions/ADR-003"] -->|consolidated into| DLOG
STALE["⚠️ .claude/skills/\npre-pr-review/SKILL.md\naurelio-review-pr/SKILL.md"]
STALE -. "still references §15.3, §9.2 etc.\n(not updated in this PR)" .-> OLD
|
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/design/engine.md`:
- Around line 546-552: The doc wrongly introduces a new state "SUSPENDED" for
shutdown flows causing a second restart state; change the text in Strategy 4 to
use the existing INTERRUPTED state instead of SUSPENDED, i.e., persist the
AgentContext snapshot and transition to INTERRUPTED on shutdown, and reference
the existing [Checkpoint Recovery](`#agent-crash-recovery`) behavior; ensure the
wording around AgentContext, checkpoint loading, and restart semantics aligns
with the lifecycle diagram and task model (do not add or rename states).
In `@docs/design/operations.md`:
- Around line 125-127: The fallback model alias "local-small" in the routing
example is not defined in the provider catalog; update the YAML snippet so the
fallback references an existing provider alias (e.g., change fallback:
"local-small" to fallback: "local-llama" or "local-coder") or add a
corresponding provider entry for "local-small" in the provider catalog; ensure
you modify the keys shown (role_level, preferred_model, fallback) so the routing
example and provider catalog are consistent.
In `@docs/reference/standards.md`:
- Line 11: The table cell containing "LLM API interface" is redundant; update
that cell in the row with "**OpenAI API format** | OpenAI (de facto standard) |
LLM API interface | Via provider abstraction layer (LiteLLM)" to remove the
redundancy by replacing "LLM API interface" with either "LLM API" or "LLM
interface" (choose one consistent term), and keep the rest of the row unchanged
so the table reads e.g. "**OpenAI API format** | OpenAI (de facto standard) |
LLM API | Via provider abstraction layer (LiteLLM)".
In `@README.md`:
- Line 125: Update the README line that currently reads "Read `DESIGN_SPEC.md`
before implementing any feature — it is the mandatory starting point for
architecture, data models, and behavior" to point directly to the new design hub
(e.g., replace the `DESIGN_SPEC.md` link with the new hub target such as
`DESIGN_HUB.md` or the design hub URL) so contributors land on the authoritative
source without the extra redirect; keep the remainder of the sentence and
emphasis about it being the mandatory starting point intact.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 7350b758-b26b-40df-8e0c-a1a5590a4eef
📒 Files selected for processing (25)
CLAUDE.mdDESIGN_SPEC.mdREADME.mddocs/architecture/decisions.mddocs/architecture/index.mddocs/architecture/tech-stack.mddocs/decisions/ADR-003-documentation-architecture.mddocs/design/agents.mddocs/design/communication.mddocs/design/engine.mddocs/design/index.mddocs/design/memory.mddocs/design/operations.mddocs/design/organization.mddocs/design_spec.mddocs/getting_started.mddocs/index.mddocs/reference/research.mddocs/reference/standards.mddocs/roadmap/future-vision.mddocs/roadmap/index.mddocs/roadmap/open-questions.mddocs/user_guide.mdmkdocs.ymlsite/src/pages/index.astro
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Agent
- GitHub Check: Greptile Review
🧰 Additional context used
📓 Path-based instructions (2)
docs/**/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
Use MkDocs for documentation with mkdocstrings for auto-generated API reference from docstrings via Griffe
Files:
docs/user_guide.mddocs/design/organization.mddocs/roadmap/index.mddocs/design/index.mddocs/architecture/decisions.mddocs/roadmap/open-questions.mddocs/design/engine.mddocs/roadmap/future-vision.mddocs/index.mddocs/decisions/ADR-003-documentation-architecture.mddocs/reference/standards.mddocs/design/agents.mddocs/architecture/tech-stack.mddocs/design/memory.mddocs/getting_started.mddocs/reference/research.mddocs/design/communication.mddocs/architecture/index.mddocs/design/operations.md
**/*.yml
📄 CodeRabbit inference engine (CLAUDE.md)
Use YAML for company config loading and validation
Files:
mkdocs.yml
🧠 Learnings (5)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-11T19:36:34.512Z
Learning: Read DESIGN_SPEC.md before implementing any feature — it is the mandatory starting point for architecture, data models, and behavior
📚 Learning: 2026-03-11T19:36:34.512Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-11T19:36:34.512Z
Learning: Read DESIGN_SPEC.md before implementing any feature — it is the mandatory starting point for architecture, data models, and behavior
Applied to files:
docs/user_guide.mddocs/design/index.mddocs/index.mddocs/decisions/ADR-003-documentation-architecture.mddocs/getting_started.mdCLAUDE.mddocs/architecture/index.mdmkdocs.yml
📚 Learning: 2026-03-11T19:36:34.512Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-11T19:36:34.512Z
Learning: Alert the user and explain deviations from DESIGN_SPEC.md — do not silently diverge from the specification
Applied to files:
docs/index.mddocs/getting_started.mdCLAUDE.md
📚 Learning: 2026-03-11T19:36:34.512Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-11T19:36:34.512Z
Learning: Applies to docs/**/*.md : Use MkDocs for documentation with mkdocstrings for auto-generated API reference from docstrings via Griffe
Applied to files:
docs/decisions/ADR-003-documentation-architecture.mdCLAUDE.md
📚 Learning: 2026-03-11T19:36:34.512Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-11T19:36:34.512Z
Learning: Applies to src/ai_company/**/*.py : Use frozen Pydantic models for config/identity — use separate mutable-via-copy models for runtime state that evolves
Applied to files:
docs/architecture/tech-stack.md
🪛 LanguageTool
docs/design/organization.md
[style] ~211-~211: Consider using a different verb to strengthen your wording.
Context: ...ge behavior during template inheritance follows these rules: Scalars (company_name, ...
(FOLLOW_OBEY)
[grammar] ~234-~234: Please add a punctuation mark at the end of paragraph.
Context: ...## Company Builder !!! warning "Planned" The template system already suppor...
(PUNCTUATION_PARAGRAPH_END)
[style] ~243-~243: Using many exclamation marks might seem excessive (in this case: 6 exclamation marks for a text that’s 3590 characters long)
Context: ...mpany`. --- ## Community Marketplace !!! warning "Planned" A future communi...
(EN_EXCESSIVE_EXCLAMATION)
[grammar] ~244-~244: Please add a punctuation mark at the end of paragraph.
Context: ...munity Marketplace !!! warning "Planned" A future community marketplace wou...
(PUNCTUATION_PARAGRAPH_END)
docs/design/index.md
[grammar] ~90-~90: Please add a punctuation mark at the end of paragraph.
Context: ...fo "How to read the design specification" Sections describe the full vision....
(PUNCTUATION_PARAGRAPH_END)
docs/design/engine.md
[style] ~60-~60: Consider using the typographical ellipsis character here instead.
Context: ...del) that tracks status transitions via model_copy(update=...), accumulates TokenUsage cost, a...
(ELLIPSIS)
[grammar] ~510-~510: Please add a punctuation mark at the end of paragraph.
Context: ...s (task.cancel()) -- tasks transition to INTERRUPTED 5. Cleanup phase (`cle...
(PUNCTUATION_PARAGRAPH_END)
[style] ~565-~565: Since ownership is already implied, this phrasing may be redundant.
Context: ...p across agents. Each agent operates in its own git worktree (shared .git object data...
(PRP_OWN)
[typographical] ~616-~616: In American English, use a period after an abbreviation.
Context: ...ping file sets. ### State Coordination vs Workspace Isolation These are compleme...
(MISSING_PERIOD_AFTER_ABBREVIATION)
[style] ~622-~622: Consider using the typographical ellipsis character here instead.
Context: ...tralized single-writer (TaskEngine) | model_copy(update=...) via async queue | | Code and files (a...
(ELLIPSIS)
docs/index.md
[grammar] ~7-~7: Please add a punctuation mark at the end of paragraph.
Context: .... !!! warning "Under Active Development" SynthOrg is under active developme...
(PUNCTUATION_PARAGRAPH_END)
docs/reference/standards.md
[style] ~11-~11: To make your text as clear as possible to all readers, do not use this foreign term. Possible alternatives are ‘in fact’ or ‘in reality’.
Context: ...ity | | OpenAI API format | OpenAI (de facto standard) | LLM API interface | Via pro...
(DE_FACTO)
[style] ~11-~11: This phrase is redundant (‘I’ stands for ‘interface’). Use simply “API”.
Context: ...at** | OpenAI (de facto standard) | LLM API interface | Via provider abstraction layer (LiteL...
(ACRONYM_TAUTOLOGY)
docs/design/agents.md
[style] ~20-~20: Consider using the typographical ellipsis character here instead.
Context: ...n. Represented as Pydantic models using model_copy(update=...) for state transitions -- never mu...
(ELLIPSIS)
[style] ~249-~249: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nality would complement the team? - What model/provider fits the budget? 3. Cand...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~252-~252: Please add a punctuation mark at the end of paragraph.
Context: ...company context, project briefing, team introductions !!! info "Design decisions ([Decision ...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~367-~367: Use a hyphen to join words.
Context: ...- Promotion criteria: Sustained high quality scores, task complexity handled,...
(QB_NEW_EN_HYPHEN)
[style] ~371-~371: Using many exclamation marks might seem excessive (in this case: 9 exclamation marks for a text that’s 4133 characters long)
Context: ...wngrade](operations.md#cost-controls)) !!! info "Design decisions ([Decision Log](...
(EN_EXCESSIVE_EXCLAMATION)
docs/architecture/tech-stack.md
[grammar] ~53-~53: Ensure spelling is correct
Context: ...rotocol (Decision Log). Qdrant embedded + SQLite for persistence. Cust...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[typographical] ~106-~106: In American English, use a period after an abbreviation.
Context: ...py()` for Pydantic models. | | Config vs runtime split | Adopted | Frozen mode...
(MISSING_PERIOD_AFTER_ABBREVIATION)
[style] ~106-~106: Consider using the typographical ellipsis character here instead.
Context: ...ed | Frozen models for config/identity; model_copy(update=...) for runtime state transitions (e.g., ...
(ELLIPSIS)
[style] ~122-~122: Consider using the typographical ellipsis character here instead.
Context: ... Agents submit requests; engine applies model_copy(update=...) sequentially and publishes snapshots....
(ELLIPSIS)
docs/design/memory.md
[style] ~38-~38: Since ownership is already implied, this phrasing may be redundant.
Context: ...------------+ ``` Each agent maintains its own memory store. The storage backend is se...
(PRP_OWN)
[style] ~119-~119: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional.
Context: ...rm future work if organizational memory needs outgrow the Hybrid Prompt + Retrieval a...
(EN_REPEATEDWORDS_NEED)
[grammar] ~122-~122: Please add a punctuation mark at the end of paragraph.
Context: ...arch Direction: GraphRAG Knowledge Graph" Organizational knowledge stored as...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~141-~141: Please add a punctuation mark at the end of paragraph.
Context: ...arch Direction: Temporal Knowledge Graph" Like GraphRAG but tracks how facts...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~171-~171: Please add a punctuation mark at the end of paragraph.
Context: ...backends. !!! tip "Write Access Control" Core policies are human-only. ADRs...
(PUNCTUATION_PARAGRAPH_END)
[style] ~182-~182: Try elevating your writing by using a synonym here.
Context: ...ecisions.md)). Application code depends only on the protocol; the storage engine is ...
(ONLY_SOLELY)
[grammar] ~304-~304: Please add a punctuation mark at the end of paragraph.
Context: ...chivalStore` | !!! abstract "Scope Note" Retention is currently per-categor...
(PUNCTUATION_PARAGRAPH_END)
[style] ~315-~315: Try elevating your writing by using a synonym here.
Context: ...end` protocol. Application code depends only on repository protocols; the storage en...
(ONLY_SOLELY)
[style] ~372-~372: Since ownership is already implied, this phrasing may be redundant.
Context: ...audit_entries Each entity type has its own repository protocol: python @runtim...
(PRP_OWN)
[style] ~451-~451: Since ownership is already implied, this phrasing may be redundant.
Context: .... ### Multi-Tenancy Each company gets its own database. The PersistenceConfig embed...
(PRP_OWN)
[style] ~462-~462: Using many exclamation marks might seem excessive (in this case: 15 exclamation marks for a text that’s 9344 characters long)
Context: ...ct -> migrate -> use -> disconnect ``` !!! warning "Planned" Runtime backend ...
(EN_EXCESSIVE_EXCLAMATION)
[grammar] ~463-~463: Please add a punctuation mark at the end of paragraph.
Context: ... -> disconnect ``` !!! warning "Planned" Runtime backend switching (e.g., m...
(PUNCTUATION_PARAGRAPH_END)
CLAUDE.md
[style] ~17-~17: A comma is missing here.
Context: ...oval - When a spec topic is referenced (e.g. "the Agents page" or "the Engine page's...
(EG_NO_COMMA)
[grammar] ~18-~18: Please add a punctuation mark at the end of paragraph.
Context: ... docs/design/ page to reflect the new reality ## Planning (MANDATORY) - Every imple...
(PUNCTUATION_PARAGRAPH_END)
[uncategorized] ~55-~55: The official name of this software platform is spelled with a capital “H”.
Context: ...riffe (AST-based, no imports) - CI: .github/workflows/pages.yml — builds Astro lan...
(GITHUB)
docs/design/operations.md
[grammar] ~163-~163: Please add a punctuation mark at the end of paragraph.
Context: ...m (30%) -- $15"] ``` !!! abstract "Note" Percentages are illustrative defau...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~233-~233: Please add a punctuation mark at the end of paragraph.
Context: ..."] ``` !!! tip "Auto-Downgrade Boundary" Model downgrades apply only at **t...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~240-~240: Please add a punctuation mark at the end of paragraph.
Context: ...itches. !!! info "Minimal Configuration" The only required field is `total_...
(PUNCTUATION_PARAGRAPH_END)
[typographical] ~471-~471: Insert a space between the numerical value and the unit symbol.
Context: ...thon 3.14 + Node.js LTS + basic utils, <500MB). If Docker is unavailable, the framewo...
(UNIT_SPACE)
[grammar] ~475-~475: Please add a punctuation mark at the end of paragraph.
Context: ...isions.md) D16). !!! info "Scaling Path" In a future Kubernetes deployment ...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~585-~585: Please add a punctuation mark at the end of paragraph.
Context: ...mented. !!! warning "Security Invariant" The standard_to_elevated promoti...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~893-~893: Please add a punctuation mark at the end of paragraph.
Context: ...in. !!! abstract "Park/Resume Mechanism" The park/resume mechanism relies o...
(PUNCTUATION_PARAGRAPH_END)
[grammar] ~969-~969: Please add a punctuation mark at the end of paragraph.
Context: ...## Web UI Features !!! warning "Planned" The Web UI is a planned future com...
(PUNCTUATION_PARAGRAPH_END)
🪛 markdownlint-cli2 (0.21.0)
docs/design/index.md
[warning] 107-107: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
[warning] 139-139: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
docs/design/engine.md
[warning] 50-50: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 105-105: Link fragments should be valid
(MD051, link-fragments)
[warning] 212-212: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 239-239: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 268-268: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 379-379: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 415-415: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 448-448: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 590-590: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/design/agents.md
[warning] 39-39: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 165-165: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 235-235: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 242-242: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 289-289: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 326-326: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/design/memory.md
[warning] 70-70: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 236-236: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
[warning] 246-246: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/design/communication.md
[warning] 108-108: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
🔇 Additional comments (21)
docs/roadmap/open-questions.md (1)
1-42: Well-structured risk documentation.The stable identifier approach for questions (preserving numbers when resolved) is a good practice for maintaining cross-reference integrity. The categorization into Open Questions, Technical Risks, and Architecture Risks provides clear organization.
Minor typography note: Line 38 uses
--which may render inconsistently across Markdown renderers. Consider using an en-dash (–) for numeric ranges like "3–5 agents" for consistent rendering.docs/reference/research.md (1)
1-97: Thorough research documentation with proper MkDocs features.The framework comparison tables, research citations, and build-vs-fork rationale provide valuable context. The
!!! noteadmonition syntax (lines 52-54) correctly uses MkDocs Material notation.The internal links to
../architecture/tech-stack.md(lines 74, 77) align with the new documentation structure.docs/reference/standards.md (1)
1-41: Clear standards documentation.The overview of MCP, A2A, and OpenAI API format integration is well-organized and provides good context for how SynthOrg aligns with industry standards.
docs/getting_started.md (1)
127-127: References correctly updated to new design documentation structure.The DESIGN_SPEC.md description change to "Pointer to design specification pages" and the link update to
design/index.mdaccurately reflect the new multi-page documentation structure.Also applies to: 155-155
docs/user_guide.md (1)
14-14: User guide updates are consistent with the documentation restructure.
- Line 14: The
cp docker/.env.example docker/.envcommand is a helpful addition to the quick start flow.- Line 47: Link correctly updated to point to
design/index.md.Also applies to: 20-20, 47-47
docs/architecture/index.md (1)
62-65: Further Reading section correctly updated with new documentation links.The links to the new design pages (
../design/index.md), tech stack, and decision log align with the restructured documentation. The description "Full design spec split into 7 focused pages" accurately reflects the PR changes.site/src/pages/index.astro (1)
253-253: Landing page links correctly updated to new design documentation path.Both the Open Source section (line 253) and footer navigation (line 320) now point to
/docs/design/instead of the old/docs/design_spec/path. The simplified anchor text "design specification" is appropriate since the monolithic 3500-line file is now split into focused pages.Also applies to: 320-320
docs/roadmap/index.md (1)
1-37: Clear roadmap overview with good organization.The Current Status section provides a comprehensive list of completed subsystems, and the Remaining Work table clearly identifies outstanding items. The links to
open-questions.mdandfuture-vision.mdproperly connect the roadmap documentation.docs/design/organization.md (1)
1-252: LGTM! Well-structured organization documentation.This design page effectively documents the organization and template system with clear examples, proper MkDocs syntax, and helpful visual aids. The template inheritance and merge semantics sections provide comprehensive implementation guidance.
docs/decisions/ADR-003-documentation-architecture.md (1)
119-132: LGTM! ADR accurately reflects the documentation restructuring.The implementation section correctly documents the split from monolithic DESIGN_SPEC.md to 7 focused design pages under
docs/design/, with the root DESIGN_SPEC.md serving as a pointer file. This aligns perfectly with the PR objectives.docs/architecture/tech-stack.md (1)
1-130: LGTM! Comprehensive tech stack documentation.This page provides excellent coverage of the technology choices with clear rationale. The ASCII architecture diagram, technology comparison tables, and engineering conventions table are all well-structured and informative. The Litestar vs FastAPI design decision section provides valuable context for framework selection.
docs/roadmap/future-vision.md (1)
1-47: LGTM! Clear future vision and scaling path.This roadmap document effectively outlines future features with appropriate priority levels and provides a clear incremental scaling narrative from local single-process to cloud deployment. The cross-reference to the implemented promotion system is helpful context.
docs/index.md (3)
7-10: Helpful development status warning added.The "Under Active Development" admonition appropriately sets expectations and directs readers to the roadmap for implementation status.
38-100: Excellent design specification navigation structure.The grid card layout with 7 design topic cards provides clear entry points into the now-modular design documentation. Each card has a focused description and direct link to its respective design page. This significantly improves discoverability compared to a monolithic DESIGN_SPEC.md.
117-126: Improved "Further Reading" section.Renaming from "Documentation" to "Further Reading" better reflects the purpose, and the updated table now includes the new Tech Stack, Decision Log, and Roadmap pages, providing comprehensive navigation to all documentation resources.
docs/architecture/decisions.md (1)
1-3: Good addition of YAML frontmatter.Adding the description metadata to the decision log improves SEO and provides context in navigation. This follows MkDocs best practices.
docs/design/agents.md (1)
1-387: LGTM! Comprehensive agents & HR design documentation.This design page provides excellent coverage of the agent identity system, personality dimensions, seniority levels, role catalog, and HR processes. The two-layer identity model (Config vs Runtime) is clearly explained, and the compatibility scoring algorithm is well-documented. Cross-references to related design pages and the decision log are appropriate and helpful.
The use of MkDocs Material features (tabs, admonitions, definition lists) enhances readability and organization.
Optional: Minor clarity improvement
For line 367, consider adding a hyphen for the compound modifier:
-- **Promotion criteria:** Sustained high quality scores, task complexity handled, peer feedback +- **Promotion criteria:** Sustained high-quality scores, task complexity handled, peer feedbackThis is a minor stylistic improvement for clarity.
CLAUDE.md (3)
9-18: LGTM! Developer guidance properly updated for new design structure.The updates correctly reflect the transition from monolithic DESIGN_SPEC.md to the 7-page design structure, emphasizing that DESIGN_SPEC.md is now a pointer file. The guidance to read relevant
docs/design/pages before implementing features maintains the mandatory design-first approach.
46-57: LGTM! Documentation structure correctly documented.The enumeration of the 7 design pages and updated architecture section accurately reflects the new documentation organization.
93-94: LGTM! Memory and persistence references updated.The updated references correctly point to the Memory & Persistence design page and remove the specific ADR-001 references in favor of the broader design page links.
mkdocs.yml (1)
117-120: No action needed — ADR nav paths are correct.The ADR files are located at
docs/decisions/and the mkdocs.yml nav entries correctly reference them with thedecisions/prefix. The configuration aligns with the actual file layout.
- Fix SUSPENDED→INTERRUPTED state in engine shutdown docs (CodeRabbit) - Fix department YAML to list syntax in organization docs (Copilot) - Fix template merge semantics: mapping→list (Copilot) - Fix absolute roadmap URL to relative in README (Gemini) - Fix local-small→local-coder fallback alias (CodeRabbit) - Fix redundant "API interface" → "LLM API" (CodeRabbit) - Point contributors to Design Overview directly (CodeRabbit) - Clarify docker/.env purpose in user guide (Copilot) - Update 48 source files: replace stale DESIGN_SPEC section numbers with design page references (e.g. "Operations design page") - Remove LLM_API_KEY from docker/.env.example (not a container config) - Remove dead AI_COMPANY_LOG_LEVEL from .env.example and compose override - Landing page: fix "design specification is public" → everything is open - Landing page: proper terminal block with copy button - Landing page: add GitHub star/fork buttons (buttons.github.io) - MkDocs: add homepage: / so logo links back to landing page
…pages - Remove project board and milestone references from docs/roadmap/index.md - Remove individual ADR-001/002/003 pages and docs/decisions/ directory - Keep decision log at docs/architecture/decisions.md (single source) - Clean up mkdocs.yml nav (remove Decisions subsection) - Update CLAUDE.md and memory to remove milestone references - Remove dead AI_COMPANY_LOG_LEVEL from compose.override.yml
🤖 I have created a release *beep* *boop* --- ## [0.1.1](v0.1.0...v0.1.1) (2026-03-11) ### Features * add PR preview deployments via Cloudflare Pages ([#302](#302)) ([b73c45a](b73c45a)) ### Bug Fixes * correct deploy-pages SHA and improve preview cleanup reliability ([#304](#304)) ([584d64a](584d64a)) * harden API key hashing with HMAC-SHA256 and clean up legacy changelog ([#292](#292)) ([5e85353](5e85353)) * upgrade upload-pages-artifact to v4 and add zizmor workflow linting ([#299](#299)) ([2eac571](2eac571)) * use Cloudflare Pages API default per_page for pagination ([#305](#305)) ([9fec245](9fec245)) ### Documentation * remove milestone references and rebrand to SynthOrg ([#289](#289)) ([57a03e0](57a03e0)) * set up documentation site, release CI, and sandbox hardening ([#298](#298)) ([0dec9da](0dec9da)) * split DESIGN_SPEC.md into 7 focused design pages ([#308](#308)) ([9ea0788](9ea0788)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Signed-off-by: Aurelio <19254254+Aureliolo@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 89 out of 91 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <p align="center"> | ||
| <strong>SynthOrg</strong> | ||
| </p> |
There was a problem hiding this comment.
The README no longer has an H1 heading (# … or <h1>). This can hurt document structure for screen readers and GitHub’s rendering/TOC behavior. Consider restoring a semantic H1 (it can still be centered with HTML/CSS) and keep the badge block beneath it.
| <p align="center"> | |
| <strong>SynthOrg</strong> | |
| </p> | |
| <h1 align="center">SynthOrg</h1> |
| document.getElementById('copy-terminal')?.addEventListener('click', function() { | ||
| const text = 'git clone https://github.com/Aureliolo/synthorg\ncd synthorg\ndocker compose -f docker/compose.yml up -d'; | ||
| navigator.clipboard.writeText(text).then(() => { | ||
| const btn = this; | ||
| btn.textContent = 'Copied!'; | ||
| setTimeout(() => { btn.textContent = 'Copy'; }, 2000); | ||
| }); |
There was a problem hiding this comment.
The copy-to-clipboard handler doesn’t handle cases where navigator.clipboard is unavailable or writeText() is rejected (non-secure context, permissions, etc.), which can lead to a silent no-op or unhandled rejection. Consider feature-detecting the API and adding a .catch(...) fallback (and/or UI feedback) so the button degrades gracefully.
| document.getElementById('copy-terminal')?.addEventListener('click', function() { | |
| const text = 'git clone https://github.com/Aureliolo/synthorg\ncd synthorg\ndocker compose -f docker/compose.yml up -d'; | |
| navigator.clipboard.writeText(text).then(() => { | |
| const btn = this; | |
| btn.textContent = 'Copied!'; | |
| setTimeout(() => { btn.textContent = 'Copy'; }, 2000); | |
| }); | |
| document.getElementById('copy-terminal')?.addEventListener('click', function () { | |
| const btn = this; | |
| const text = 'git clone https://github.com/Aureliolo/synthorg\ncd synthorg\ndocker compose -f docker/compose.yml up -d'; | |
| const showCopied = () => { | |
| btn.textContent = 'Copied!'; | |
| setTimeout(() => { | |
| btn.textContent = 'Copy'; | |
| }, 2000); | |
| }; | |
| const showFailed = () => { | |
| btn.textContent = 'Copy failed'; | |
| setTimeout(() => { | |
| btn.textContent = 'Copy'; | |
| }, 2000); | |
| }; | |
| const fallbackCopy = () => { | |
| try { | |
| const textarea = document.createElement('textarea'); | |
| textarea.value = text; | |
| textarea.style.position = 'fixed'; | |
| textarea.style.top = '-9999px'; | |
| document.body.appendChild(textarea); | |
| textarea.focus(); | |
| textarea.select(); | |
| const successful = document.execCommand && document.execCommand('copy'); | |
| document.body.removeChild(textarea); | |
| if (successful) { | |
| showCopied(); | |
| } else { | |
| showFailed(); | |
| } | |
| } catch (e) { | |
| showFailed(); | |
| } | |
| }; | |
| if (typeof navigator !== 'undefined' && navigator.clipboard && navigator.clipboard.writeText) { | |
| navigator.clipboard.writeText(text) | |
| .then(() => { | |
| showCopied(); | |
| }) | |
| .catch(() => { | |
| fallbackCopy(); | |
| }); | |
| } else { | |
| fallbackCopy(); | |
| } |
| <!-- GitHub buttons (https://buttons.github.io/) --> | ||
| <script async defer src="https://buttons.github.io/buttons.js"></script> |
There was a problem hiding this comment.
This loads third-party JavaScript from buttons.github.io on every page. If the site has (or plans to add) a restrictive CSP/SRI policy, or if supply-chain risk is a concern, consider self-hosting/pinning via integrity (if available) and/or only including this script on pages that actually render GitHub buttons.
Summary
DESIGN_SPEC.md(3500+ lines) into 7 focused pages underdocs/design/: index, agents, organization, communication, engine, memory, operationsDESIGN_SPEC.mdis now a lightweight pointer file linking to the individual design pagesmkdocs.ymlnavigation with new Design, Roadmap, and Reference sectionsCLAUDE.md,README.md, architecture docs, roadmap, and reference pages to use page-based links instead of section numbers/docs/design/instead of/docs/design_spec/docs/architecture/tech-stack.md,docs/roadmap/pages, anddocs/reference/pages to MkDocs navTest plan
uv run mkdocs build --strictpassesCloses #303
🤖 Generated with Claude Code