From 1b652e1dc05d85c6e73590669c38397a76de0c05 Mon Sep 17 00:00:00 2001 From: gavrielc Date: Wed, 8 Apr 2026 23:10:15 +0300 Subject: [PATCH] docs: add code structure principles for skill customization Channels, MCP tools, and providers use registration patterns so skill branches can add capabilities without conflicting. Index stays thin. File map updated with channels/ and mcp-tools/ directories. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/v2-architecture-draft.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/v2-architecture-draft.md b/docs/v2-architecture-draft.md index 18053c768..0be41494f 100644 --- a/docs/v2-architecture-draft.md +++ b/docs/v2-architecture-draft.md @@ -506,6 +506,25 @@ Two tiers: The architecture is **flexible for code changes, not configurable for everything**. Advanced setups (like the PR Factory below) use custom routing logic and host-side hooks — not database config columns. +### Code Structure for Skill Customization + +NanoClaw is customized via skills — branches that get merged into the user's installation. Different skills add different capabilities (channels, integrations, behaviors). The code must be structured so that: + +1. **Different customizations don't conflict.** Adding Slack and adding Telegram should not produce merge conflicts. Adding a new MCP tool should not conflict with adding a channel. Each type of customization should touch its own file(s). + +2. **Core blocks of functionality are in separate files.** Channel registration, message formatting, MCP tools, routing logic, container management — each in its own file. A skill that changes how messages are formatted doesn't touch the file that handles container spawning. + +3. **The index file is thin.** It wires things together (init DB, start adapters, start poll loops) but contains no business logic. All logic lives in purpose-specific modules that skills can modify independently. + +4. **Don't over-split.** A simple change (e.g., adding a new message kind) shouldn't require edits across 5 files. Group related logic together. The goal is that each skill touches 1-2 files for its core change. + +5. **Registration patterns over switch statements.** Channels, MCP tools, and providers should use registration/plugin patterns. A skill adds a channel by adding a file and a registration call — not by editing a central switch statement alongside every other channel. + +**Practical example:** Adding a new channel via skill should require: +- One new file (the channel adapter or Chat SDK config) +- One line in index or a self-registering import +- Zero changes to routing, formatting, delivery, or container code + ### What the base architecture must support primitively These are the building blocks. None require special abstractions — they fall out of per-session DBs, host-managed routing, and messages_out with `kind: 'system'`: