docs: add hierarchical AGENTS.md knowledge base#375
Open
OS-Lihua wants to merge 4 commits intospacedriveapp:mainfrom
Open
docs: add hierarchical AGENTS.md knowledge base#375OS-Lihua wants to merge 4 commits intospacedriveapp:mainfrom
OS-Lihua wants to merge 4 commits intospacedriveapp:mainfrom
Conversation
Add module-level knowledge base files for the core Rust subsystems: - src/AGENTS.md: WHERE TO LOOK table, module sizes, shared types, complexity hotspots - src/agent/AGENTS.md: process lifecycle, state machines, non-blocking patterns - src/tools/AGENTS.md: ToolServer topology, trait pattern, factory functions - src/memory/AGENTS.md: search flow, dual-DB architecture, maintenance ops Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Add knowledge base files for infrastructure subsystems: - src/api/AGENTS.md: Axum routes, middleware stack, SSE streaming, state management - src/llm/AGENTS.md: SpacebotModel, 4-level routing, 15+ providers, anthropic/ subdir - src/config/AGENTS.md: hot-reload via ArcSwap, resolution order, config types Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Add knowledge base files for cross-cutting concerns: - src/hooks/AGENTS.md: tool nudging, loop guard, leak detection - src/secrets/AGENTS.md: AES-256-GCM encryption, OS keyring, output scrubbing - src/messaging/AGENTS.md: Messaging trait, 7 adapters, fan-in, coalescing Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Add knowledge base files for non-Rust subsystems: - interface/AGENTS.md: React 19 + TanStack stack, bun-only, SSE state, design system - prompts/AGENTS.md: 73 Jinja2 templates, tool/fragment/adapter structure, rendering rules Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Contributor
WalkthroughThis PR introduces comprehensive architectural documentation across 12 AGENTS.md files, covering the web UI stack, prompt templates, Rust modules, subsystems (agent process, HTTP API, configuration, hooks, LLM routing, memory, messaging, secrets, and tools), and their design patterns and responsibilities. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![tembo[bot]](https://avatars.githubusercontent.com/in/1223475?s=60&v=4){kind=small}
| @@ -0,0 +1,53 @@ | |||
| # prompts/ | |||
|
|
|||
| Jinja2 prompt templates for all LLM process types. | |||
Contributor
There was a problem hiding this comment.
Minor nit: this is implemented with MiniJinja (Jinja2-compatible), so calling that out avoids confusion with Python Jinja2.
Suggested change
| Jinja2 prompt templates for all LLM process types. | |
| MiniJinja (Jinja2-compatible) prompt templates for all LLM process types. |
|
|
||
| ## Rendering | ||
|
|
||
| `PromptEngine` in `src/prompts/engine.rs` renders templates with context variables via Jinja2. Templates receive typed context structs, not raw strings. |
Contributor
There was a problem hiding this comment.
Same note here — PromptEngine uses MiniJinja.
Suggested change
| `PromptEngine` in `src/prompts/engine.rs` renders templates with context variables via Jinja2. Templates receive typed context structs, not raw strings. | |
| `PromptEngine` in `src/prompts/engine.rs` renders templates with context variables via MiniJinja. Templates receive typed context structs, not raw strings. |
| - **Merge**: finds near-duplicate pairs (high cosine similarity + same type), collapses into one, rewires edges. | ||
| - **Reindex**: drops and rebuilds LanceDB HNSW + Tantivy indices. Needed after bulk deletes or schema changes. | ||
|
|
||
| Maintenance ops are fallible but non-fatal. Errors are logged, not propagated to callers. |
Contributor
There was a problem hiding this comment.
This line reads like errors are swallowed, but run_maintenance() currently returns Result and propagates failures with ?.
Suggested change
| Maintenance ops are fallible but non-fatal. Errors are logged, not propagated to callers. | |
| Maintenance ops are fallible; `run_maintenance()` returns errors to callers, which should be treated as non-fatal (log + continue). |
| | `email.rs` | IMAP/SMTP | Largest adapter (1919 lines). Email search, thread tracking | | ||
| | `twitch.rs` | twitch-irc | Chat only, trigger prefix required | | ||
| | `webchat.rs` | SSE | Embeddable portal, per-agent session isolation, streaming | | ||
| | `webhook.rs` | axum | Programmatic access, HTTP receiver, no auth by default | |
Contributor
There was a problem hiding this comment.
Worth spelling out the header name here since auth is optional.
Suggested change
| | `webhook.rs` | axum | Programmatic access, HTTP receiver, no auth by default | | |
| | `webhook.rs` | axum | Programmatic access, HTTP receiver; auth via `x-webhook-token` when configured (disabled when unset) | |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (7)
prompts/AGENTS.md (1)
7-24: Add language specifier to directory structure code block.The code block showing the prompts directory structure should have a language identifier for proper rendering.
📝 Proposed fix
-``` +```text prompts/en/ ├── channel.md.j2🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/AGENTS.md` around lines 7 - 24, Update the code block in prompts/AGENTS.md that shows the prompts directory tree to include a language specifier (e.g., "text") after the opening triple backticks so the block renders correctly; locate the directory structure code fence in the file and change the opening fence from ``` to ```text (keeping the existing tree content unchanged).src/api/AGENTS.md (1)
18-20: Add language specifier to middleware stack diagram.The code block showing the middleware flow should have a language identifier for consistent formatting.
📝 Proposed fix
-``` +```text CORS → Auth (bearer token) → Body limit (10 MB) → Metrics (optional)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/api/AGENTS.md` around lines 18 - 20, The fenced code block showing the middleware flow lacks a language specifier; update the block that currently contains "CORS → Auth (bearer token) → Body limit (10 MB) → Metrics (optional)" to use a language identifier (e.g., change ``` to ```text) so the snippet is consistently formatted and rendered as plain text.src/tools/AGENTS.md (1)
22-29: Add language specifier to factory functions code block.The code block listing factory functions is missing a language identifier. Consider adding
textorrustfor better rendering.📝 Proposed fix
-``` +```text add_channel_tools() — adds/removes per-turn channel tools create_branch_tool_server() — memory + recall + task board🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/tools/AGENTS.md` around lines 22 - 29, The fenced code block listing factory functions (add_channel_tools, create_branch_tool_server, create_worker_tool_server, create_cortex_tool_server, create_cortex_chat_tool_server, create_factory_tool_server) is missing a language specifier; update the block delimiter to include a language (for example ```text or ```rust) so the snippet renders correctly, e.g., change the opening ``` to ```text and keep the inner lines unchanged.src/AGENTS.md (1)
72-82: Add language specifier to shared types code block.The code block showing key shared types should have a language identifier for proper syntax highlighting.
📝 Proposed fix
-``` +```rust AgentDeps — dependency injection bundle passed to all processes ProcessEvent — 30+ variants for inter-process communication🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/AGENTS.md` around lines 72 - 82, The markdown code block listing shared types (e.g., AgentDeps, ProcessEvent, ProcessId, ProcessType, ChannelId, WorkerId, BranchId, InboundMessage, OutboundResponse) lacks a language specifier; update the surrounding fenced code block to include a language identifier (suggest "rust") so the block starts with ```rust to enable proper syntax highlighting and leave the content unchanged.src/config/AGENTS.md (1)
21-23: Add language specifiers to code blocks.Two code blocks are missing language identifiers:
- Lines 21-23: Resolution order should use
text- Lines 46-48: TOML example should use
toml📝 Proposed fixes
-``` +```text env vars > config.toml > compiled defaults```diff -```toml +```toml api_key = "secret:OPENAI_KEY"Note: The TOML block already appears to have proper syntax but ensure it renders correctly.
Also applies to: 46-48
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/config/AGENTS.md` around lines 21 - 23, Update the two fenced code blocks so they include language specifiers: change the block containing the resolution order text "env vars > config.toml > compiled defaults" to start with ```text and change the TOML example containing api_key = "secret:OPENAI_KEY" to start with ```toml so both blocks render with proper highlighting; locate the blocks by their contents and add the respective language identifiers to the opening triple-backtick lines.src/messaging/AGENTS.md (1)
29-36: Add language specifier to messaging flow diagram.The code block showing the message routing architecture should have a language identifier for consistent formatting.
📝 Proposed fix
-``` +```text [discord] ──┐ [slack] ──┤ mpsc::Sender<InboundMessage> → channel router🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/messaging/AGENTS.md` around lines 29 - 36, The fenced code block in AGENTS.md that contains the messaging flow diagram lacks a language specifier; update the block by adding a language identifier (e.g., ```text) before the diagram so the diagram containing symbols like mpsc::Sender<InboundMessage>, channel router, mpsc::Sender<OutboundResponse>, and adapter.respond() is consistently formatted/rendered; ensure you only add the language tag and do not alter the diagram content.interface/AGENTS.md (1)
16-21: Add language specifiers to code blocks for better rendering.The markdown linter flags missing language specifiers for the code blocks. Consider adding appropriate identifiers:
- Lines 16-21: Add
bashorshellfor the command examples- Lines 25-41: Add
textor leave as-is (plain route list is acceptable)- Lines 74-76: Add
textfor the build pipeline diagram📝 Proposed fixes
-``` +```bash bun install bun run dev-``` +```text / /settings-``` +```text bun run build → Vite → dist/ → rust_embed → single Rust binaryAlso applies to: 25-41, 74-76
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@interface/AGENTS.md` around lines 16 - 21, The markdown code fences in the AGENTS.md content are missing language specifiers; update the three affected fenced blocks by adding appropriate language identifiers: add "bash" (or "shell") to the command block containing "bun install / bun run dev / bun run build / bunx <tool>", add "text" for the plain route list block (lines showing "/" and "/settings"), and add "text" for the build pipeline diagram block ("bun run build → Vite → dist/ → rust_embed → single Rust binary"); locate the fences by matching those exact snippets and prepend the language token after the opening ``` to satisfy the markdown linter.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/secrets/AGENTS.md`:
- Around line 37-39: Update the SystemSecrets docs to remove the "marker trait"
claim and instead state that SystemSecrets requires implementing section() and
secret_fields(), and that scrubbing is enforced via the runtime registry
returned by system_secret_registry() rather than the trait itself; explicitly
document that types must be manually registered with system_secret_registry()
(or equivalent) to be protected, and note that auto_categorize() will default
unknown secrets to the Tool category if not registered. Reference the
SystemSecrets trait, its section() and secret_fields() methods, the
system_secret_registry() usage, and auto_categorize() behaviour so readers know
the manual registration requirement and default fallback.
- Around line 31-35: Update the AGENTS.md description to describe the scrubber
as two-layered: mention that src/secrets/scrub.rs performs exact-match stream
scrubbing for known secrets (and preserves the secret name in replacements as
`[REDACTED:<name>]`) plus a regex-based leak detection layer for unknown
formats; also note it works across chunk boundaries via a rolling buffer and is
applied to all worker stdout/stderr streams.
---
Nitpick comments:
In `@interface/AGENTS.md`:
- Around line 16-21: The markdown code fences in the AGENTS.md content are
missing language specifiers; update the three affected fenced blocks by adding
appropriate language identifiers: add "bash" (or "shell") to the command block
containing "bun install / bun run dev / bun run build / bunx <tool>", add "text"
for the plain route list block (lines showing "/" and "/settings"), and add
"text" for the build pipeline diagram block ("bun run build → Vite → dist/ →
rust_embed → single Rust binary"); locate the fences by matching those exact
snippets and prepend the language token after the opening ``` to satisfy the
markdown linter.
In `@prompts/AGENTS.md`:
- Around line 7-24: Update the code block in prompts/AGENTS.md that shows the
prompts directory tree to include a language specifier (e.g., "text") after the
opening triple backticks so the block renders correctly; locate the directory
structure code fence in the file and change the opening fence from ``` to
```text (keeping the existing tree content unchanged).
In `@src/AGENTS.md`:
- Around line 72-82: The markdown code block listing shared types (e.g.,
AgentDeps, ProcessEvent, ProcessId, ProcessType, ChannelId, WorkerId, BranchId,
InboundMessage, OutboundResponse) lacks a language specifier; update the
surrounding fenced code block to include a language identifier (suggest "rust")
so the block starts with ```rust to enable proper syntax highlighting and leave
the content unchanged.
In `@src/api/AGENTS.md`:
- Around line 18-20: The fenced code block showing the middleware flow lacks a
language specifier; update the block that currently contains "CORS → Auth
(bearer token) → Body limit (10 MB) → Metrics (optional)" to use a language
identifier (e.g., change ``` to ```text) so the snippet is consistently
formatted and rendered as plain text.
In `@src/config/AGENTS.md`:
- Around line 21-23: Update the two fenced code blocks so they include language
specifiers: change the block containing the resolution order text "env vars >
config.toml > compiled defaults" to start with ```text and change the TOML
example containing api_key = "secret:OPENAI_KEY" to start with ```toml so both
blocks render with proper highlighting; locate the blocks by their contents and
add the respective language identifiers to the opening triple-backtick lines.
In `@src/messaging/AGENTS.md`:
- Around line 29-36: The fenced code block in AGENTS.md that contains the
messaging flow diagram lacks a language specifier; update the block by adding a
language identifier (e.g., ```text) before the diagram so the diagram containing
symbols like mpsc::Sender<InboundMessage>, channel router,
mpsc::Sender<OutboundResponse>, and adapter.respond() is consistently
formatted/rendered; ensure you only add the language tag and do not alter the
diagram content.
In `@src/tools/AGENTS.md`:
- Around line 22-29: The fenced code block listing factory functions
(add_channel_tools, create_branch_tool_server, create_worker_tool_server,
create_cortex_tool_server, create_cortex_chat_tool_server,
create_factory_tool_server) is missing a language specifier; update the block
delimiter to include a language (for example ```text or ```rust) so the snippet
renders correctly, e.g., change the opening ``` to ```text and keep the inner
lines unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 417ac0c7-fbdf-4b11-abe8-12b3cdccca74
📒 Files selected for processing (12)
interface/AGENTS.mdprompts/AGENTS.mdsrc/AGENTS.mdsrc/agent/AGENTS.mdsrc/api/AGENTS.mdsrc/config/AGENTS.mdsrc/hooks/AGENTS.mdsrc/llm/AGENTS.mdsrc/memory/AGENTS.mdsrc/messaging/AGENTS.mdsrc/secrets/AGENTS.mdsrc/tools/AGENTS.md
Comment on lines
+31
to
+35
| Redacts secret values from worker output before it reaches channels or LLM context. | ||
|
|
||
| - Rolling buffer handles secrets split across stream chunk boundaries | ||
| - Applied to all worker stdout/stderr streams | ||
| - Replacement: `[REDACTED]` |
Contributor
There was a problem hiding this comment.
Describe the scrubber as two-layered, not just [REDACTED] replacement.
src/secrets/scrub.rs implements exact-match stream scrubbing for known secrets and regex leak detection for unknown formats. It also preserves the secret name in exact-match replacements ([REDACTED:<name>]). This summary is too narrow as written.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/secrets/AGENTS.md` around lines 31 - 35, Update the AGENTS.md description
to describe the scrubber as two-layered: mention that src/secrets/scrub.rs
performs exact-match stream scrubbing for known secrets (and preserves the
secret name in replacements as `[REDACTED:<name>]`) plus a regex-based leak
detection layer for unknown formats; also note it works across chunk boundaries
via a rolling buffer and is applied to all worker stdout/stderr streams.
Comment on lines
+37
to
+39
| ## SystemSecrets Trait | ||
|
|
||
| Marker trait for config sections that contain credentials: `LlmConfig`, `DiscordConfig`, `TelegramConfig`, etc. Used to enforce scrubbing at config load time. |
Contributor
There was a problem hiding this comment.
The SystemSecrets docs overstate the guarantee.
SystemSecrets is not a marker trait here—it requires section() and secret_fields()—and it does not by itself “enforce scrubbing at config load time.” The protection is registry-based in system_secret_registry(), and auto_categorize() defaults unknown secrets to Tool. Please document the manual registration requirement, otherwise this reads like a compile-time safety guarantee that the code does not provide.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/secrets/AGENTS.md` around lines 37 - 39, Update the SystemSecrets docs to
remove the "marker trait" claim and instead state that SystemSecrets requires
implementing section() and secret_fields(), and that scrubbing is enforced via
the runtime registry returned by system_secret_registry() rather than the trait
itself; explicitly document that types must be manually registered with
system_secret_registry() (or equivalent) to be protected, and note that
auto_categorize() will default unknown secrets to the Tool category if not
registered. Reference the SystemSecrets trait, its section() and secret_fields()
methods, the system_secret_registry() usage, and auto_categorize() behaviour so
readers know the manual registration requirement and default fallback.
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
1 participant
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
AGENTS.mdfiles creating a hierarchical knowledge base below the existing rootAGENTS.mdFiles Created
src/AGENTS.mdsrc/agent/AGENTS.mdsrc/tools/AGENTS.mdsrc/api/AGENTS.mdsrc/messaging/AGENTS.mdsrc/memory/AGENTS.mdsrc/llm/AGENTS.mdsrc/config/AGENTS.mdsrc/hooks/AGENTS.mdsrc/secrets/AGENTS.mdinterface/AGENTS.mdprompts/AGENTS.mdHierarchy
Design Decisions
conversation/,cron/,presets/,settings/,identity/scored below threshold — parent coverage is sufficientNote
This PR establishes a hierarchical documentation layer for complex subsystems. The 12 new files add navigation guides (WHERE TO LOOK tables), module structure, complexity hotspots, and design patterns unique to each domain—complementing the root AGENTS.md without duplication. Key additions:
src/AGENTS.mdwith a 46-entry task lookup table, agent process files documenting non-blocking patterns and state machines, tools topology mapping process-type tool access, and subsystem-specific details for memory search (RRF + graph traversal), LLM routing (4-level fallback chains), config hot-reload (ArcSwap), and more.Written by Tembo for commit 63da745. This will update automatically on new commits.