docs: comprehensive documentation refresh#1050
Merged
Conversation
Contributor
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (8)
WalkthroughThis pull request updates documentation across the repository, with the most significant changes in the README and roadmap sections. The README removes "Work in Progress" messaging, restructures content with a new hero tagline and "What's Inside" section, simplifies Quick Start commands, and updates the architecture diagram to explicitly show React Dashboard and Go CLI components. Container image references are standardized from 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
Contributor
There was a problem hiding this comment.
Code Review
This pull request significantly updates the project's documentation to reflect its transition from early development to active development (v0.6.x). The README has been overhauled to emphasize the framework's focus on synthetic organizations, and the roadmap now includes detailed lists of implemented features and planned milestones for versions v0.7 and v0.8. Feedback points out a terminology contradiction regarding dependency pinning in the architecture decisions and an inconsistency in the mitigation status of context window exhaustion in the risk assessment.
docs/architecture/decisions.md
Outdated
| |----|----------|-----------|------------------------| | ||
| | D16 | Docker MVP via `aiodocker`; `SandboxBackend` protocol for future backends | Docker cold start (1-2s) invisible against LLM latency (2-30s). Pre-built image + user config. Fail if Docker unavailable -- no unsafe subprocess fallback. gVisor as config-level hardening upgrade | Docker + WASM (CPython can't run pip packages in WASM), Docker + Firecracker (Linux-only, requires KVM), docker-py (sync, no 3.14 support). Precedents: E2B, major cloud providers, Daytona -- none offer unsandboxed fallback | | ||
| | D17 | Official `mcp` Python SDK, pinned `==1.26.0`; `MCPBridgeTool` adapter | Used by every major framework (LangChain, CrewAI, major agent SDKs, Pydantic AI). Python 3.14 compatible. Pydantic 2.12.5 compatible. Thin adapter isolates codebase from SDK changes | Custom MCP client (must implement protocol handshake, track spec changes manually) | | ||
| | D17 | Official `mcp` Python SDK, pinned to latest stable; `MCPBridgeTool` adapter | Used by every major framework (LangChain, CrewAI, major agent SDKs, Pydantic AI). Python 3.14 compatible. Pydantic v2 compatible. Thin adapter isolates codebase from SDK changes | Custom MCP client (must implement protocol handshake, track spec changes manually) | |
Contributor
There was a problem hiding this comment.
The phrase "pinned to latest stable" is a contradiction in terms. "Pinned" typically refers to locking a dependency to a specific, immutable version (e.g., ==1.26.0), whereas "latest stable" implies a floating reference. This also conflicts with the technical risk mitigation strategy in docs/roadmap/open-questions.md which states that "All versions pinned (==)". Consider rephrasing to "tracked to latest stable" or specifying the versioning policy more clearly to align with the project's risk management strategy.
docs/roadmap/open-questions.md
Outdated
| | Memory retrieval quality | Medium | Mem0 selected as initial backend (see [Decision Log](../architecture/decisions.md)). LMEB evaluation ([arXiv:2603.12572](https://arxiv.org/abs/2603.12572)) shows MTEB scores do not predict memory retrieval quality (Spearman: -0.130). Embedding model selection should be guided by LMEB episodic + procedural scores. Optional domain fine-tuning (+10-27%) via an offline pipeline configured with `EmbeddingFineTuneConfig`. Checkpoint lookup is wired into the Mem0 adapter; pipeline stages (data generation, hard negative mining, contrastive training) are not yet implemented (see #1001). See [Embedding Evaluation](../reference/embedding-evaluation.md). | | ||
| | Agent personality inconsistency | Low | Strong system prompts, few-shot examples, personality tests. | | ||
| | WebSocket scaling | Low | Start local, add Redis pub/sub when needed. | | ||
| | Context window exhaustion on complex tasks | Medium | **Mitigated**: context budget management tracks fill, injects indicators, and compacts at turn boundaries. Remaining: LLM-based summarization for higher-quality summaries. | |
Contributor
There was a problem hiding this comment.
The status for "Context window exhaustion" has been changed from **Partially mitigated** to **Mitigated**, but the notes still indicate Remaining: LLM-based summarization. To maintain accuracy in the roadmap, this should remain labeled as **Partially mitigated** until the listed enhancements are implemented.
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Snapshot WarningsEnsure that dependencies are being submitted on PR branches. Re-running this action after a short time may resolve the issue. See the documentation for more information and troubleshooting advice. Scanned FilesNone |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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/architecture/decisions.md`:
- Line 65: The wording in decision D17 is ambiguous about dependency pinning for
the `mcp` Python SDK; update the D17 line to explicitly state the exact-pin
policy (e.g., "pinned with `==` to a specific stable version" or "pinned to the
current stable release (update as needed)"), and mention the `MCPBridgeTool`
adapter so readers know the SDK is tied to an exact `mcp==x.y.z` entry in
pyproject.toml rather than automatically tracking the newest release.
In `@docs/guides/quickstart.md`:
- Line 14: The docs reference the template as "Solo Founder" while the actual
template's name is "Solo Builder" in solo_founder.yaml; fix by making the two
consistent: either change the name field in solo_founder.yaml from "Solo
Builder" to "Solo Founder", or update the quickstart documentation text to say
"Solo Builder" wherever "Solo Founder" appears so the UI selection matches the
docs.
🪄 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: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 5cd58e85-9471-47cc-88ec-397017833b74
📒 Files selected for processing (8)
README.mddocs/architecture/decisions.mddocs/design/memory.mddocs/guides/deployment.mddocs/guides/quickstart.mddocs/roadmap/future-vision.mddocs/roadmap/index.mddocs/roadmap/open-questions.md
📜 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). (4)
- GitHub Check: Agent
- GitHub Check: Analyze (python)
- GitHub Check: Analyze (go)
- GitHub Check: Dependency Review
🧰 Additional context used
🧠 Learnings (27)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-30T10:41:40.176Z
Learning: Update the relevant `docs/design/` page to reflect new reality when approved deviations from spec occur
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:28:28.895Z
Learning: Applies to docs/**/*.md : Documentation files in `docs/` (Markdown, built with Zensical, config: `mkdocs.yml`); design spec in `docs/design/` (11 pages)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:31:11.894Z
Learning: Applies to docs/design/*.md : Update the relevant `docs/design/` page when approved deviations occur to reflect the new reality
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-18T08:23:08.912Z
Learning: When approved deviations occur, update the relevant `docs/design/` page to reflect the new reality.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:31:11.894Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/memory/**/*.py : Use MemoryBackend protocol with pluggable backends (Mem0 adapter available at backends/mem0/) for persistent agent memory
Applied to files:
docs/design/memory.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/memory/**/*.py : Memory package (memory/): pluggable MemoryBackend protocol, backends/ (Mem0 adapter), retrieval pipeline (ranking, RRF fusion, injection, formatting, non-inferable filtering), shared org memory (org/), consolidation/archival (density-aware: DensityClassifier, AbstractiveSummarizer, ExtractivePreserver, DualModeConsolidationStrategy)
Applied to files:
docs/design/memory.mddocs/architecture/decisions.md
📚 Learning: 2026-04-01T21:17:42.724Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-01T21:17:42.724Z
Learning: Applies to pyproject.toml : Required runtime dependencies: `mem0ai` (default and currently only memory backend), `cryptography` (Fernet encryption), `faker` (multi-locale name generation)
Applied to files:
docs/design/memory.md
📚 Learning: 2026-03-31T14:28:28.895Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:28:28.895Z
Learning: Applies to docker/**/Dockerfile* : Docker images: backend (Chainguard distroless, non-root), web (nginx-unprivileged, SPA + API proxy), sandbox (Python + Node.js, non-root)
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-15T18:17:43.675Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:17:43.675Z
Learning: Applies to docker/{Dockerfile*,compose.yml} : Docker: Backend uses 3-stage build (builder → setup → distroless runtime), Chainguard Python, non-root (UID 65532), CIS-hardened. Web uses nginxinc/nginx-unprivileged, Vue 3 SPA with PrimeVue + Tailwind CSS, SPA routing, API/WebSocket proxy to backend.
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to Dockerfile* : Backend images must use Chainguard distroless with non-root user; web image must use nginx-unprivileged with non-root user; sandbox image must use Python + Node.js with non-root user. All Docker files in `docker/` -- Dockerfiles, compose, `.env.example`. Single root `.dockerignore`. All images build with `context: .`
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Applied to files:
docs/guides/deployment.mddocs/roadmap/future-vision.mddocs/roadmap/index.mdREADME.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/api/**/*.py : API package (api/): Litestar REST + WebSocket with controllers, guards, channels, JWT + API key + WS ticket auth, approval gate integration, coordination endpoint, collaboration endpoint, settings endpoint, provider management endpoint (CRUD + test + presets), backup endpoint, RFC 9457 structured errors, AppState hot-reload slots, service auto-wiring (Phase 1 at construction, Phase 2 on startup), lifecycle helpers
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile : Docker: 3-stage build (builder → setup → distroless runtime) for backend, Chainguard Python, non-root (UID 65532), CIS-hardened
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-31T14:18:02.890Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:02.890Z
Learning: Applies to Dockerfile : All Docker images must be non-root and use distroless/unprivileged base images (backend: Chainguard distroless, web: nginx-unprivileged, sandbox: Python + Node.js non-root)
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/workflows/docker.yml : Docker workflow: builds backend + web + sandbox images, pushes to GHCR, signs with cosign. SLSA L3 provenance attestations via actions/attest-build-provenance. Scans: Trivy (CRITICAL = hard fail, HIGH = warn) + Grype (critical cutoff) + CIS Docker Benchmark v1.6.0 compliance (informational). CVE triage via .github/.trivyignore.yaml and .github/.grype.yaml. Images only pushed after scans pass. Triggers on push to main and version tags (v*).
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/api/**/*.py : Use Litestar for REST + WebSocket API. Controllers, guards, channels, JWT + API key + WS ticket auth, RFC 9457 structured errors.
Applied to files:
docs/guides/deployment.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile.sandbox : Docker sandbox: `synthorg-sandbox` — Python 3.14 + Node.js + git, non-root (UID 10001), agent code execution sandbox
Applied to files:
docs/guides/deployment.mdREADME.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/roadmap/future-vision.mdREADME.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Applied to files:
docs/roadmap/future-vision.mdREADME.mddocs/roadmap/open-questions.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Applied to files:
docs/roadmap/index.mdREADME.md
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Version bumping (pre-1.0): `fix:` = patch, `feat:` = patch, `feat!:` = minor, `BREAKING CHANGE` trailer = minor. Update version in `pyproject.toml` (`[tool.commitizen].version`) and `src/synthorg/__init__.py` (`__version__`)
Applied to files:
README.md
📚 Learning: 2026-03-26T15:18:16.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-26T15:18:16.848Z
Learning: Applies to src/synthorg/api/**/*.py : Litestar API must include setup wizard, auth/, auto-wiring, and lifecycle management
Applied to files:
README.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/security/**/*.py : Security module includes SecOps agent, rule engine (soft-allow/hard-deny), audit log, output scanner, risk classifier, autonomy levels (4 strategies), timeout policies.
Applied to files:
README.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/security/**/*.py : Security package (security/): SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume)
Applied to files:
README.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/hr/**/*.py : HR engine must provide: hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, trend detection), promotion/demotion
Applied to files:
README.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/engine/**/*.py : Engine package (engine/): agent orchestration, parallel execution, task decomposition, routing, TaskEngine (centralized single-writer), task lifecycle/recovery/shutdown, workspace isolation, coordination (4 dispatchers: SAS/centralized/decentralized/context-dependent, wave execution), approval gates (escalation detection, context parking/resume), stagnation detection (ToolRepetitionDetector, corrective prompt injection), AgentRuntimeState (execution status), context budget management, conversation compaction (oldest-turns summarizer)
Applied to files:
README.md
📚 Learning: 2026-03-14T15:43:05.601Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
README.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Applied to files:
README.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Applied to files:
README.md
📚 Learning: 2026-03-15T18:38:44.202Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Applied to files:
README.md
🔇 Additional comments (2)
docs/guides/quickstart.md (1)
103-103: Same template name mismatch here.See comment on Line 14 - this reference to "Solo Founder" will also cause confusion when the actual template is named "Solo Builder".
docs/architecture/decisions.md (1)
104-104: LGTM! Clear tracking reference.The update to reference
#1001for the fine-tuning pipeline provides a clear tracking reference for in-progress work.
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation-wide refresh to bring public docs (README + roadmap + guides + design/architecture notes) in line with the current v0.6.x feature set and naming, removing stale/pinned details that tend to drift.
Changes:
- Rewrites
README.mdto lead with positioning/tagline, updated quickstart, and a linked “What’s Inside” overview. - Rebuilds roadmap docs (
docs/roadmap/*) with “what works today / what’s not yet”, version targets, and updated risks. - Fixes specific guide/design/decision-log staleness (template naming, container image name, decision log pinning language).
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | README rewrite: new tagline, restructured quickstart, “What’s Inside”, updated docs table, architecture diagram, compare link. |
| docs/roadmap/index.md | Rewritten current status + “works today / not yet” + version-bucketed next steps. |
| docs/roadmap/future-vision.md | Converts “future features” into planned features with versions; adds “recently shipped” section. |
| docs/roadmap/open-questions.md | Removes resolved questions; updates risk mitigations with current state. |
| docs/guides/quickstart.md | Renames “Solo Builder” → “Solo Founder” in tutorial narrative and template selection step. |
| docs/guides/deployment.md | Fixes backend container image reference to synthorg-backend. |
| docs/design/memory.md | Removes stale cross-reference in config comment for memory backend options. |
| docs/architecture/decisions.md | Removes pinned MCP version language; updates fine-tuning pipeline status text. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/roadmap/open-questions.md
Outdated
| | Context window exhaustion on complex tasks | Medium | **Mitigated**: context budget management tracks fill, injects indicators, and compacts at turn boundaries. Remaining: LLM-based summarization for higher-quality summaries. | | ||
| | Cost explosion from agent loops | High | Budget hard stops, loop detection, max iterations per task, auto-downgrade at task boundaries. | | ||
| | Agent quality degradation with cheap models | Medium | Capability-aware prompt profiles (#805) adapt prompts to model tier. Quality gates and minimum model requirements per task type. | | ||
| | Third-party library breaking changes | Medium | All versions pinned (`==`), integration tests, abstraction layers, Dependabot daily updates. | |
There was a problem hiding this comment.
The mitigation claim "All versions pinned (==)" is inaccurate for this repo as a whole: the JS dashboards/site use semver ranges (e.g. ^ in web/package.json and site/package.json), even though Python deps in pyproject.toml are pinned with ==. Please reword to reflect the actual policy (e.g., Python deps are exact-pinned and JS is range-based but enforced via lockfiles / Dependabot).
Suggested change
| | Third-party library breaking changes | Medium | All versions pinned (`==`), integration tests, abstraction layers, Dependabot daily updates. | | |
| | Third-party library breaking changes | Medium | Python deps exact-pinned (`==`); JS uses semver ranges enforced via lockfiles, integration tests, abstraction layers, and Dependabot daily updates. | |
docs/roadmap/future-vision.md
Outdated
Comment on lines
+29
to
+36
| - **Visual workflow editor** -- shipped in v0.5.9 (PR #1018) | ||
| - **Network hosting / multi-user access** -- shipped in v0.5.9 (PR #1032) | ||
| - **Workflow execution from graph definitions** -- shipped in v0.6.0 (PR #1040) | ||
| - **Local model management** (Ollama/LM Studio) -- shipped in v0.6.0 (PR #1037) | ||
| - **Ceremony scheduling** (8 strategies) -- shipped across v0.5.5--v0.5.7 | ||
| - **Reporting system** -- in progress (v0.6.5) | ||
| - **Agent promotions** -- core promotion/demotion system shipped in v0.5.0 | ||
| - **Integration APIs** -- external service integration planned for v0.7 |
There was a problem hiding this comment.
This "Recently Shipped" list contains items that are explicitly not shipped (e.g., "Reporting system — in progress" and "Integration APIs — planned"). That contradicts the section heading and intro sentence (“have since been implemented”) and can confuse readers about what is actually available. Consider moving non-shipped items back to Planned Features (or renaming the section to include "In Progress").
docs/architecture/decisions.md
Outdated
| |----|----------|-----------|------------------------| | ||
| | D16 | Docker MVP via `aiodocker`; `SandboxBackend` protocol for future backends | Docker cold start (1-2s) invisible against LLM latency (2-30s). Pre-built image + user config. Fail if Docker unavailable -- no unsafe subprocess fallback. gVisor as config-level hardening upgrade | Docker + WASM (CPython can't run pip packages in WASM), Docker + Firecracker (Linux-only, requires KVM), docker-py (sync, no 3.14 support). Precedents: E2B, major cloud providers, Daytona -- none offer unsandboxed fallback | | ||
| | D17 | Official `mcp` Python SDK, pinned `==1.26.0`; `MCPBridgeTool` adapter | Used by every major framework (LangChain, CrewAI, major agent SDKs, Pydantic AI). Python 3.14 compatible. Pydantic 2.12.5 compatible. Thin adapter isolates codebase from SDK changes | Custom MCP client (must implement protocol handshake, track spec changes manually) | | ||
| | D17 | Official `mcp` Python SDK, pinned to latest stable; `MCPBridgeTool` adapter | Used by every major framework (LangChain, CrewAI, major agent SDKs, Pydantic AI). Python 3.14 compatible. Pydantic v2 compatible. Thin adapter isolates codebase from SDK changes | Custom MCP client (must implement protocol handshake, track spec changes manually) | |
There was a problem hiding this comment.
D17 currently says the mcp SDK is "pinned to latest stable", but the repo uses exact version pinning (e.g. mcp==... in pyproject.toml) with Dependabot to keep it updated. "Pinned to latest stable" is ambiguous and may read like an unpinned floating dependency; consider stating the concrete policy (exact pins + automated updates) or removing the pinning claim from the decision text.
Suggested change
| | D17 | Official `mcp` Python SDK, pinned to latest stable; `MCPBridgeTool` adapter | Used by every major framework (LangChain, CrewAI, major agent SDKs, Pydantic AI). Python 3.14 compatible. Pydantic v2 compatible. Thin adapter isolates codebase from SDK changes | Custom MCP client (must implement protocol handshake, track spec changes manually) | | |
| | D17 | Official `mcp` Python SDK, exact-version pinned with automated Dependabot updates; `MCPBridgeTool` adapter | Used by every major framework (LangChain, CrewAI, major agent SDKs, Pydantic AI). Python 3.14 compatible. Pydantic v2 compatible. Thin adapter isolates codebase from SDK changes | Custom MCP client (must implement protocol handshake, track spec changes manually) | |
Comment on lines
27
to
30
| | Container | Image | Purpose | | ||
| |-----------|-------|---------| | ||
| | **backend** | `ghcr.io/aureliolo/synthorg` | Litestar API server (Chainguard distroless, non-root) | | ||
| | **backend** | `ghcr.io/aureliolo/synthorg-backend` | Litestar API server (Chainguard distroless, non-root) | | ||
| | **web** | `ghcr.io/aureliolo/synthorg-web` | Nginx + React 19 SPA (proxies API and WebSocket) | |
There was a problem hiding this comment.
The backend image name is updated here to ghcr.io/aureliolo/synthorg-backend, but other docs still reference the old backend image (ghcr.io/aureliolo/synthorg, e.g. in docs/user_guide.md). Please update those references too to avoid users deploying mismatched images.
docs/guides/quickstart.md
Outdated
| ## What You Will Build | ||
|
|
||
| You will create a **Solo Builder** organization -- a lean two-agent team designed for rapid prototyping: | ||
| You will create a **Solo Founder** organization -- a lean two-agent team designed for rapid prototyping: |
There was a problem hiding this comment.
The built-in solo_founder template’s display name is currently "Solo Builder" (see src/synthorg/templates/builtins/solo_founder.yaml), so calling it "Solo Founder" here may not match what users see in the setup wizard. Please either align the docs with the current template name or rename the template metadata to "Solo Founder" in code.
Suggested change
| You will create a **Solo Founder** organization -- a lean two-agent team designed for rapid prototyping: | |
| You will create a **Solo Builder** organization -- a lean two-agent team designed for rapid prototyping: |
docs/guides/quickstart.md
Outdated
| 1. **Name your company** -- pick any name (e.g. "My First Org"). | ||
| 2. **Add an LLM provider** -- enter your provider's API key. Local providers like Ollama are auto-detected. | ||
| 3. **Select a template** -- choose **Solo Builder** (the minimal 2-agent template). | ||
| 3. **Select a template** -- choose **Solo Founder** (the minimal 2-agent template). |
There was a problem hiding this comment.
Same as above: the setup wizard template list will likely show this template as "Solo Builder" (metadata name in solo_founder.yaml), not "Solo Founder". Updating only the docs can lead to users not finding the template during onboarding.
Aureliolo
added a commit
that referenced
this pull request
Apr 3, 2026
- Revert quickstart.md 'Solo Founder' back to 'Solo Builder' (actual template display name) - decisions.md: 'exact-pinned, updated via Dependabot' replaces contradictory 'pinned to latest stable' - open-questions.md: 'Partially mitigated' for context window (LLM summarization still missing) - open-questions.md: clarify Python exact-pinned vs JS range-based with lockfiles - future-vision.md: remove in-progress/planned items from 'Recently Shipped' section - user_guide.md: fix backend image name (synthorg -> synthorg-backend) - README.md: all doc links now point to synthorg.io/docs/ (website URLs)
Contributor
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 @.slopconfig.yaml:
- Around line 1-4: Remove the undocumented configuration file or document and
integrate its keys: either delete the .slopconfig.yaml file entirely from the PR
if it's unused, or alternatively add inline comments explaining the top-level
"weights" object and its fields "ldr", "inflation", and "ddc", add documentation
in the relevant guide describing their purpose and valid ranges, and implement
loading/usage in the codebase (e.g., read the "weights" config and wire it into
the appropriate initializer/module) so the fields are actually referenced;
choose one of these two paths and update the PR accordingly.
In `@docs/architecture/decisions.md`:
- Line 104: The decision doc currently implies the fine-tuning pipeline is
available; update the sentence about "The fine-tuning pipeline (data generation,
hard negative mining, contrastive training) is tracked in `#1001`" to explicitly
state that all four pipeline stages currently raise NotImplementedError at
runtime and are not implemented yet; mention that EmbeddingFineTuneConfig exists
and that when enabled the Mem0 adapter expects a checkpoint path as the model
identifier but the actual training functions in fine_tune.py are placeholders
that validate inputs and raise NotImplementedError, and keep the reference to
issue `#1001` as the implementation roadmap.
In `@docs/roadmap/open-questions.md`:
- Line 26: Docs disagree about the domain fine-tuning pipeline status; the code
in src/synthorg/memory/embedding/fine_tune.py explicitly states it is "not yet
implemented" and raises NotImplementedError, so make both docs consistent with
that reality: update the sentence in docs/roadmap/open-questions.md (the "in
progress (`#1001`)" entry) and the wording in docs/architecture/decisions.md (the
"tracked in `#1001`" entry) to a single consistent phrase such as "not yet
implemented (raises NotImplementedError; tracked in `#1001`)" or alternatively
change the module docstring/exception to reflect true in-progress status—pick
one approach and apply it to both docs or the code so all three places
(open-questions, architecture/decisions, and
src/synthorg/memory/embedding/fine_tune.py) say the same thing.
In `@README.md`:
- Around line 76-90: The README incorrectly states "configurable autonomy levels
(5 tiers)"; update that text to "configurable autonomy levels (4 tiers)" to
match the codebase where the AutonomyLevel enum defines FULL, SEMI, SUPERVISED,
LOCKED; locate the phrase near "Security & Trust" and replace "5 tiers" with "4
tiers" so the documentation aligns with the AutonomyLevel enum.
🪄 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: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 0f0d456e-0ffa-4ac3-991a-4337746433a2
📒 Files selected for processing (6)
.slopconfig.yamlREADME.mddocs/architecture/decisions.mddocs/roadmap/future-vision.mddocs/roadmap/open-questions.mddocs/user_guide.md
📜 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). (3)
- GitHub Check: Deploy Preview
- GitHub Check: Dependency Review
- GitHub Check: Analyze (python)
🧰 Additional context used
🧠 Learnings (30)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Version bumping (pre-1.0): `fix:` = patch, `feat:` = patch, `feat!:` = minor, `BREAKING CHANGE` trailer = minor. Update version in `pyproject.toml` (`[tool.commitizen].version`) and `src/synthorg/__init__.py` (`__version__`)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-30T10:41:40.176Z
Learning: Update the relevant `docs/design/` page to reflect new reality when approved deviations from spec occur
📚 Learning: 2026-03-31T14:28:28.895Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:28:28.895Z
Learning: Applies to docker/**/Dockerfile* : Docker images: backend (Chainguard distroless, non-root), web (nginx-unprivileged, SPA + API proxy), sandbox (Python + Node.js, non-root)
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-15T18:17:43.675Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:17:43.675Z
Learning: Applies to docker/{Dockerfile*,compose.yml} : Docker: Backend uses 3-stage build (builder → setup → distroless runtime), Chainguard Python, non-root (UID 65532), CIS-hardened. Web uses nginxinc/nginx-unprivileged, Vue 3 SPA with PrimeVue + Tailwind CSS, SPA routing, API/WebSocket proxy to backend.
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-21T14:12:17.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T14:12:17.848Z
Learning: Applies to Dockerfile* : Backend images must use Chainguard distroless with non-root user; web image must use nginx-unprivileged with non-root user; sandbox image must use Python + Node.js with non-root user. All Docker files in `docker/` -- Dockerfiles, compose, `.env.example`. Single root `.dockerignore`. All images build with `context: .`
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Applied to files:
docs/user_guide.mdREADME.mddocs/roadmap/future-vision.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile : Docker: 3-stage build (builder → setup → distroless runtime) for backend, Chainguard Python, non-root (UID 65532), CIS-hardened
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docker/Dockerfile.sandbox : Docker sandbox: `synthorg-sandbox` — Python 3.14 + Node.js + git, non-root (UID 10001), agent code execution sandbox
Applied to files:
docs/user_guide.mdREADME.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/api/**/*.py : API package (api/): Litestar REST + WebSocket with controllers, guards, channels, JWT + API key + WS ticket auth, approval gate integration, coordination endpoint, collaboration endpoint, settings endpoint, provider management endpoint (CRUD + test + presets), backup endpoint, RFC 9457 structured errors, AppState hot-reload slots, service auto-wiring (Phase 1 at construction, Phase 2 on startup), lifecycle helpers
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-15T21:32:02.880Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:32:02.880Z
Learning: Applies to .github/workflows/docker.yml : Docker workflow: builds backend + web + sandbox images, pushes to GHCR, signs with cosign. SLSA L3 provenance attestations via actions/attest-build-provenance. Scans: Trivy (CRITICAL = hard fail, HIGH = warn) + Grype (critical cutoff) + CIS Docker Benchmark v1.6.0 compliance (informational). CVE triage via .github/.trivyignore.yaml and .github/.grype.yaml. Images only pushed after scans pass. Triggers on push to main and version tags (v*).
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-19T11:33:01.580Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T11:33:01.580Z
Learning: Applies to docker/Dockerfile.web : `nginxinc/nginx-unprivileged` base with non-root user (UID 101), Vue 3 SPA (PrimeVue + Tailwind CSS), SPA routing, API/WebSocket proxy to backend
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-31T14:18:02.890Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:18:02.890Z
Learning: Applies to Dockerfile : All Docker images must be non-root and use distroless/unprivileged base images (backend: Chainguard distroless, web: nginx-unprivileged, sandbox: Python + Node.js non-root)
Applied to files:
docs/user_guide.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/memory/**/*.py : Memory package (memory/): pluggable MemoryBackend protocol, backends/ (Mem0 adapter), retrieval pipeline (ranking, RRF fusion, injection, formatting, non-inferable filtering), shared org memory (org/), consolidation/archival (density-aware: DensityClassifier, AbstractiveSummarizer, ExtractivePreserver, DualModeConsolidationStrategy)
Applied to files:
docs/architecture/decisions.md
📚 Learning: 2026-04-03T20:24:03.685Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-03T20:24:03.685Z
Learning: Applies to pyproject.toml : Python versions in `pyproject.toml` use `==` pinning. All versions are pinned, not ranges.
Applied to files:
docs/roadmap/open-questions.md
📚 Learning: 2026-04-02T15:36:44.680Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-02T15:36:44.680Z
Learning: Applies to pyproject.toml : All versions in `pyproject.toml` use `==` (pinned)
Applied to files:
docs/roadmap/open-questions.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Applied to files:
docs/roadmap/open-questions.mdREADME.mddocs/roadmap/future-vision.md
📚 Learning: 2026-03-21T12:54:22.557Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-21T12:54:22.557Z
Learning: Version bumping (pre-1.0): `fix:` = patch, `feat:` = patch, `feat!:` = minor, `BREAKING CHANGE` trailer = minor. Update version in `pyproject.toml` (`[tool.commitizen].version`) and `src/synthorg/__init__.py` (`__version__`)
Applied to files:
README.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Applied to files:
README.md
📚 Learning: 2026-04-02T07:18:02.381Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-02T07:18:02.381Z
Learning: Applies to {pyproject.toml,src/synthorg/__init__.py} : Update version in `pyproject.toml` (`[tool.commitizen].version`) and `src/synthorg/__init__.py` (`__version__`)
Applied to files:
README.md
📚 Learning: 2026-03-26T15:18:16.848Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-26T15:18:16.848Z
Learning: Applies to src/synthorg/api/**/*.py : Litestar API must include setup wizard, auth/, auto-wiring, and lifecycle management
Applied to files:
README.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/security/**/*.py : Security module includes SecOps agent, rule engine (soft-allow/hard-deny), audit log, output scanner, risk classifier, autonomy levels (4 strategies), timeout policies.
Applied to files:
README.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to src/synthorg/hr/**/*.py : HR engine must provide: hiring, firing, onboarding, offboarding, agent registry, performance tracking (task metrics, collaboration scoring, trend detection), promotion/demotion
Applied to files:
README.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/security/**/*.py : Security package (security/): SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume)
Applied to files:
README.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/engine/**/*.py : Engine package (engine/): agent orchestration, parallel execution, task decomposition, routing, TaskEngine (centralized single-writer), task lifecycle/recovery/shutdown, workspace isolation, coordination (4 dispatchers: SAS/centralized/decentralized/context-dependent, wave execution), approval gates (escalation detection, context parking/resume), stagnation detection (ToolRepetitionDetector, corrective prompt injection), AgentRuntimeState (execution status), context budget management, conversation compaction (oldest-turns summarizer)
Applied to files:
README.md
📚 Learning: 2026-03-14T15:43:05.601Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
README.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Applied to files:
README.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Applied to files:
README.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
README.md
📚 Learning: 2026-03-15T18:38:44.202Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Applied to files:
README.md
📚 Learning: 2026-04-03T20:24:03.685Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-03T20:24:03.685Z
Learning: Read the relevant `docs/design/` page before implementing any feature or planning any issue. The design spec is the starting point for architecture, data models, and behavior.
Applied to files:
README.md
📚 Learning: 2026-04-03T20:24:03.685Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-03T20:24:03.685Z
Learning: Docs built with Zensical. Config: `mkdocs.yml`. OpenAPI reference auto-generated by `scripts/export_openapi.py`. Comparison page auto-generated by `scripts/generate_comparison.py`.
Applied to files:
README.md
🔇 Additional comments (10)
docs/user_guide.md (1)
48-48: LGTM! Image naming now consistent with deployment docs.The backend image reference correctly updated to
ghcr.io/aureliolo/synthorg-backend, matching the naming convention documented indocs/guides/deployment.mdlines 29-30 where both backend and web images use the-backendand-websuffixes.README.md (6)
1-13: LGTM! Security badges appropriately promoted.The updated badge set correctly highlights security posture (OpenSSF Scorecard and SLSA 3) while maintaining quality indicators. The new tagline effectively communicates the value proposition.
92-112: LGTM! Architecture diagram updated per PR objectives.The Mermaid diagram correctly adds React Dashboard and Go CLI nodes, both connecting to the REST & WebSocket API. This aligns with the PR objective to "expand architecture diagram to include Dashboard and CLI nodes."
114-133: LGTM! Documentation navigation structure is clear and comprehensive.The new "Compare" and "Documentation" sections provide effective navigation. The contributor note correctly emphasizes reading the Design Specification before implementation, aligning with retrieved learnings.
Minor note: Line 116 claims "44 agent frameworks" — this specific count may become stale if the comparison page is updated.
63-63: No issues found. Thedocsdependency group is properly defined inpyproject.tomland theuv sync --group docscommand is valid.
21-21: Update test count in early access note — current metric is inaccurate.The README claims "13,000+ unit tests" but the actual test function count is approximately 8,023 (from 744 test files). The coverage metric of "80%+" is accurate and matches the CI-enforced minimum, but the test count should be corrected to reflect the current state of the codebase.
27-33: The template and preset counts in README.md are accurate. The codebase contains exactly 9 company templates (solo_founder, startup, dev_shop, product_team, agency, full_company, research_lab, consultancy, data_team) and 23 personality presets as claimed. No documentation drift detected.docs/architecture/decisions.md (1)
65-65: LGTM - Clear improvement over previous wording.The updated D17 wording precisely describes the pinning strategy: exact
==pins managed via Dependabot. This addresses the ambiguity flagged in the previous review.docs/roadmap/future-vision.md (1)
1-54: Roadmap refresh looks well-structured.The updated roadmap clearly distinguishes planned features (with version targets and status) from recently shipped features, and provides a concrete scaling path with phase-specific details. The structure is clear and maintainable.
docs/roadmap/open-questions.md (1)
22-28: Risk mitigation updates are clear and specific.The updated technical risk mitigations provide concrete references (issue numbers, specific capabilities) and distinguish current vs. planned approaches. The distinction between Phase 1 in-process implementations and Phase 2 distributed backends is particularly helpful for understanding the scaling path.
.slopconfig.yaml
Outdated
Comment on lines
+1
to
+4
| weights: | ||
| ldr: 0.25 | ||
| inflation: 0.65 | ||
| ddc: 0.1 |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Search for references to .slopconfig.yaml or the config fields
echo "=== Searching for .slopconfig references ==="
rg -n '\.slopconfig' --type yaml --type py --type md --type js --type ts
echo ""
echo "=== Searching for 'ldr', 'inflation', 'ddc' field references ==="
rg -nP '\b(ldr|inflation|ddc)\b' --type yaml --type py --type md -C2
echo ""
echo "=== Searching for 'slop' keyword ==="
rg -n 'slop' --type yaml --type py --type md --type js --type tsRepository: Aureliolo/synthorg
Length of output: 4801
🏁 Script executed:
# Check if .slopconfig.yaml is mentioned in documentation, setup files, or config patterns
echo "=== Searching for .slopconfig in all file types ==="
rg '\.slopconfig' -C3
echo ""
echo "=== Searching for config file references (setup.py, pyproject.toml, etc) ==="
find . -maxdepth 2 -type f \( -name "*.toml" -o -name "*.cfg" -o -name "setup.py" -o -name "*.md" \) -exec grep -l "slopconfig\|config" {} \;
echo ""
echo "=== Check if file exists and its size ==="
ls -lah .slopconfig.yaml 2>/dev/null || echo "File not found in repo root"
echo ""
echo "=== Search for YAML files with weight configurations ==="
find . -name "*.yaml" -o -name "*.yml" | head -20
echo ""
echo "=== Check README for any configuration references ==="
find . -maxdepth 2 -name "README*" -type f -exec head -50 {} +Repository: Aureliolo/synthorg
Length of output: 4932
🏁 Script executed:
# Search for any config loading or parsing code that might reference this file
echo "=== Search for config loading patterns ==="
rg 'slopconfig|load.*config|ConfigParser|yaml\.load' --type py -A 2 | head -30
echo ""
echo "=== Search for field definitions matching ldr, inflation, ddc ==="
rg '(ldr|inflation|ddc)\s*[:=]|Field.*name.*=.*["\''](ldr|inflation|ddc)' --type py
echo ""
echo "=== Check for any __init__.py or config.py files that might define defaults ==="
find . -name "config.py" -o -name "configuration.py" | xargs ls -lah 2>/dev/null
echo ""
echo "=== Check pyproject.toml for any config tool references ==="
grep -A 10 -B 2 '\[tool\|config' ./pyproject.toml | head -40Repository: Aureliolo/synthorg
Length of output: 6069
🏁 Script executed:
# Final targeted search - check if this might be a testing/example file
echo "=== Check if .slopconfig appears in any comments or docstrings ==="
rg 'slopconfig' --type py
echo ""
echo "=== Check for any recent git history or TODO comments about this config ==="
rg 'TODO|FIXME|XXX|BUG.*config|ldr|inflation|ddc' --type py --type md | grep -i 'config\|weight\|slop'
echo ""
echo "=== Verify file content one more time ==="
cat .slopconfig.yamlRepository: Aureliolo/synthorg
Length of output: 580
Remove undocumented configuration file that is not integrated into the project.
The .slopconfig.yaml file defines weights (ldr: 0.25, inflation: 0.65, ddc: 0.1) with no corresponding code integration, documentation, or references anywhere in the codebase. These field names are not used or explained in any Python module, config schema, or documentation.
This contradicts the PR's stated goal of a "comprehensive documentation refresh" and appears to be an accidental inclusion or incomplete work-in-progress. If this configuration is necessary, it should include:
- Inline comments explaining each field
- Documentation in the relevant guide
- Code that actually loads and uses these values
Otherwise, remove it from this PR.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.slopconfig.yaml around lines 1 - 4, Remove the undocumented configuration
file or document and integrate its keys: either delete the .slopconfig.yaml file
entirely from the PR if it's unused, or alternatively add inline comments
explaining the top-level "weights" object and its fields "ldr", "inflation", and
"ddc", add documentation in the relevant guide describing their purpose and
valid ranges, and implement loading/usage in the codebase (e.g., read the
"weights" config and wire it into the appropriate initializer/module) so the
fields are actually referenced; choose one of these two paths and update the PR
accordingly.
README: - Lead with tagline instead of CAUTION box - Add 'Why SynthOrg?' section with 6 differentiators - Security badges (OpenSSF, SLSA) promoted to top, CI badge removed - Capabilities as linked list with docs links - Add Dashboard, CLI, Compare sections - Split bash/powershell install blocks (PR #1049 feedback) - Architecture diagram includes Dashboard and CLI nodes Roadmap (fully rewritten -- was severely stale): - index.md: accurate 'What works today' list, honest 'What's not there yet' - future-vision.md: add 'Recently Shipped' section for features that were listed as future but are now done (workflow editor, network hosting, etc.) - open-questions.md: remove resolved questions, update mitigations Guides: - quickstart.md: fix 'Solo Builder' -> 'Solo Founder' template name - deployment.md: fix backend image name (synthorg -> synthorg-backend) Architecture: - decisions.md: remove pinned MCP version, update fine-tuning pipeline status, remove pinned Pydantic patch version Design: - memory.md: keep future backend options, remove stale 'see Decision Log' ref
- Revert quickstart.md 'Solo Founder' back to 'Solo Builder' (actual template display name) - decisions.md: 'exact-pinned, updated via Dependabot' replaces contradictory 'pinned to latest stable' - open-questions.md: 'Partially mitigated' for context window (LLM summarization still missing) - open-questions.md: clarify Python exact-pinned vs JS range-based with lockfiles - future-vision.md: remove in-progress/planned items from 'Recently Shipped' section - user_guide.md: fix backend image name (synthorg -> synthorg-backend) - README.md: all doc links now point to synthorg.io/docs/ (website URLs)
- Remove .slopconfig.yaml (accidentally committed, not a project file) - README + roadmap: fix autonomy tiers 5 -> 4 (enum has FULL, SEMI, SUPERVISED, LOCKED) - decisions.md: clarify fine-tuning pipeline raises NotImplementedError (not just 'tracked') - open-questions.md: align fine-tuning status with code reality (not 'in progress')
ec22f5b to
5d55083
Compare
Aureliolo
added a commit
that referenced
this pull request
Apr 4, 2026
🤖 I have created a release *beep* *boop* --- ## [0.6.1](v0.6.0...v0.6.1) (2026-04-04) ### Features * capability-aware prompt profiles for model tier adaptation ([#1047](#1047)) ([67650c5](67650c5)), closes [#805](#805) * implement procedural memory auto-generation from agent failures ([#1048](#1048)) ([55f5206](55f5206)), closes [#420](#420) * implement quality scoring Layers 2+3 -- LLM judge and human override ([#1057](#1057)) ([4a8adfe](4a8adfe)), closes [#230](#230) * token-based personality trimming via PromptProfile.max_personality_tokens ([#1059](#1059)) ([75afd52](75afd52)), closes [#1045](#1045) * workflow execution lifecycle + editor improvements ([#1058](#1058)) ([7b54262](7b54262)), closes [#1029](#1029) [#1042](#1042) ### Refactoring * **web:** address complexity and logging issues in dashboard ([#1056](#1056)) ([ada997b](ada997b)), closes [#1055](#1055) ### Documentation * comprehensive documentation refresh ([#1050](#1050)) ([c7a4259](c7a4259)) ### Tests * fix Hypothesis fuzzing infra and speed up slow unit tests ([#1044](#1044)) ([1111602](1111602)) ### Maintenance * add text=auto catch-all to .gitattributes ([#1051](#1051)) ([fc65d72](fc65d72)) * bump defu from 6.1.4 to 6.1.6 in /site ([#1062](#1062)) ([f0cc439](f0cc439)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
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
Full audit and refresh of all documentation. Fixes stale content found by 3 parallel audit agents across guides/, design/, architecture/, roadmap/, and reference/.
README (rewrite)
Roadmap (fully rewritten -- was severely stale)
Guides
synthorg->synthorg-backendArchitecture
Design