From c60ae310fc078431d647a4f3b2c62f0ce1ee8b56 Mon Sep 17 00:00:00 2001
From: RAIT-09 <51452399+RAIT-09@users.noreply.github.com>
Date: Fri, 3 Apr 2026 17:43:45 +0900
Subject: [PATCH] docs: update CONTRIBUTING.md architecture section and naming
 conventions

---
 CONTRIBUTING.md | 37 ++++++++++++++++++-------------------
 1 file changed, 18 insertions(+), 19 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 334b77a..791bc18 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -105,11 +105,12 @@ We use `eslint-plugin-obsidianmd` for Obsidian-specific rules and `typescript-es
 
 ### File Naming Conventions
 
-- **Ports**: `*.port.ts`
-- **Adapters**: `*.adapter.ts`
-- **Hooks**: `use*.ts`
-- **Components**: `PascalCase.tsx`
-- **Utils/Models**: `kebab-case.ts`
+- **Types**: `kebab-case.ts` in `types/`
+- **ACP**: `kebab-case.ts` in `acp/`
+- **Services**: `kebab-case.ts` in `services/`
+- **Hooks**: `use*.ts` in `hooks/`
+- **Components**: `PascalCase.tsx` in `ui/`
+- **Utilities**: `kebab-case.ts` in `utils/`
 
 ## Branch Naming
 
@@ -186,25 +187,23 @@ Please ensure these pass locally before submitting.
 
 ```
 src/
-├── domain/         # Pure domain models + ports (interfaces)
-│   ├── models/     # agent-config, chat-message, session-update, etc.
-│   └── ports/      # IAgentClient, ISettingsAccess, IVaultAccess
-├── adapters/       # Interface implementations
-│   ├── acp/        # ACP protocol implementation
-│   └── obsidian/   # Obsidian-specific implementations
-├── hooks/          # React custom hooks (state + logic)
-├── components/     # UI components
-└── shared/         # Utility functions
+├── types/          # Pure type definitions (no logic, no dependencies)
+├── acp/            # ACP protocol layer (SDK confined here)
+├── services/       # Non-React business logic + pure functions
+├── hooks/          # React custom hooks (useAgent facade + sub-hooks)
+├── ui/             # React components (ChatPanel orchestrator)
+└── utils/          # Shared utility functions
 ```
 
 ### Architecture Principles
 
-1. **Hooks for state and logic** — No ViewModel or Use Case classes
-2. **Pure functions in shared/** — Non-React business logic
-3. **Ports absorb protocol changes** — IAgentClient interface provides isolation
-4. **Domain has zero dependencies** — No `obsidian` or `@agentclientprotocol/sdk` imports
+1. **useAgent as facade** — Composes useAgentSession + useAgentMessages. Single `onSessionUpdate` subscription.
+2. **Services have zero React imports** — Pure functions and classes in `services/`
+3. **ACP isolation** — All `@agentclientprotocol/sdk` imports confined to `acp/`
+4. **Types have zero deps** — No `obsidian`, no SDK, no React in `types/`
+5. **Single event channel** — All agent events flow through `onSessionUpdate`. No special callback paths.
 
-For more details, see `CLAUDE.md`.
+For more details, see `ARCHITECTURE.md`.
 
 ## ACP Notes