docs(arch): evolve agentic and microkernel architectures

architectures/agentic-architecture/data-flow.md

@@ -0,0 +1,43 @@
+---
+technology: Agentic Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [ai-agents, orchestration, multi-agent-systems, vibe-coding, best-practices]
+ai_role: Senior Software Architect
+last_updated: 2026-05-02
+---
+
+# 🔄 Agentic Architecture Data Flow Best Practices
+
+<div align="center">
+  **Execution paths and communication between Orchestrator and Workers.**
+</div>
+
+---
+
+## 🔁 The Sequence of Execution
+
+In Agentic Architecture, tasks are delegated by the Orchestrator to specialized Workers, followed by validation.
+
+```mermaid
+sequenceDiagram
+    participant User as User
+    participant Orch as Orchestrator Agent
+    participant Plan as Planner Agent
+    participant Code as Coder Agent
+    participant Rev as Reviewer Agent
+
+    User->>Orch: Submit Task
+    Orch->>Plan: Decompose Task
+    Plan-->>Orch: Return Execution Plan
+    Orch->>Code: Execute Coding Sub-task
+    Code-->>Rev: Pass output for review
+    Rev-->>Orch: Validate & Return Result
+    Orch-->>User: Final Response
+```
+
+## ⛔ Boundary Constraints (Data Flow Rules)
+
+1. **Orchestrator Centralization:** All communication between agents MUST route through the Orchestrator. Agents MUST NOT communicate with each other directly to prevent context leakage.
+2. **Deterministic Schemas:** Workers MUST return data in a strict, validated schema (e.g., JSON).

architectures/agentic-architecture/folder-structure.md

@@ -0,0 +1,48 @@
+---
+technology: Agentic Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [ai-agents, orchestration, multi-agent-systems, vibe-coding, best-practices]
+ai_role: Senior Software Architect
+last_updated: 2026-05-02
+---
+
+# 📁 Agentic Architecture Folder Structure Best Practices
+
+<div align="center">
+  **Strict directory blueprints for Multi-Agent Systems.**
+</div>
+
+---
+
+## 🏗️ Structure Rules
+
+```mermaid
+classDiagram
+    class src:::component
+    class orchestrator:::component
+    class workers:::component
+    class memory:::component
+    class prompts:::component
+    class schemas:::component
+
+    src --> orchestrator
+    src --> workers
+    src --> memory
+    src --> prompts
+    src --> schemas
+
+    note for orchestrator "Main coordinator agent"
+    note for workers "Specialized worker agents (Planner, Coder, Reviewer)"
+    note for memory "Shared context and state management"
+    note for prompts "System prompts and persona definitions"
+    note for schemas "Zod/JSON validation schemas"
+
+    %% Design Tokens
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+```
+
+## 📌 Core Constraints
+1. **Isolated Prompts:** System prompts MUST be stored in `prompts/` and loaded dynamically.
+2. **Validation Layer:** Schemas for agent I/O MUST reside in `schemas/`.

architectures/agentic-architecture/implementation-guide.md

@@ -0,0 +1,38 @@
+---
+technology: Agentic Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [ai-agents, orchestration, multi-agent-systems, vibe-coding, best-practices]
+ai_role: Senior Software Architect
+last_updated: 2026-05-02
+---
+
+# 🛠️ Agentic Architecture Implementation Guide
+
+<div align="center">
+  **Step-by-step rules and code constraints for Vibe Coding.**
+</div>
+
+---
+
+## 1. Context Window Pollution
+
+### ❌ Bad Practice
+```typescript
+const agent = new SingleAgent();
+const response = await agent.run("Do everything: plan, code, and test this feature. Context: " + entireCodebase);
+```
+
+### ⚠️ Problem
+Passing the entire codebase to a single agent causes context window overflow, high token costs, and severe hallucination risks. The agent loses focus and generates non-deterministic output.
+
+### ✅ Best Practice
+```typescript
+const orchestrator = new Orchestrator();
+const plan = await orchestrator.delegateTo('Planner', "Plan the feature");
+const code = await orchestrator.delegateTo('Coder', plan.steps[0], { context: sliceOfCodebase });
+```
+
+### 🚀 Solution
+Decompose tasks into granular sub-tasks. Only pass the strictly necessary context (O(1) relevant context) to specialized worker agents, ensuring deterministic, high-fidelity code generation.

architectures/agentic-architecture/readme.md

@@ -26,10 +26,10 @@ last_updated: 2026-04-17
 
 This architecture defines the operational boundaries for multi-agent workflows, specifically optimizing for context windows, token efficiency, and deterministic output.
 
-- 🌊 **Data Flow:** Orchestrator-to-Worker execution paths.
-- 📁 **Folder Structure:** Modular isolation of Prompts, Skills, and Contexts.
-- ⚖️ **Trade-offs:** Latency vs. Reasoning depth.
-- 🛠️ **Implementation Guide:** Rules for defining strict agent personas and constraints.
+- 🌊 **[Data Flow](./data-flow.md):** Orchestrator-to-Worker execution paths.
+- 📁 **[Folder Structure](./folder-structure.md):** Modular isolation of Prompts, Skills, and Contexts.
+- ⚖️ **[Trade-offs](./trade-offs.md):** Latency vs. Reasoning depth.
+- 🛠️ **[Implementation Guide](./implementation-guide.md):** Rules for defining strict agent personas and constraints.
 
 ```mermaid
 graph TD

architectures/agentic-architecture/trade-offs.md

@@ -0,0 +1,26 @@
+---
+technology: Agentic Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [ai-agents, orchestration, multi-agent-systems, vibe-coding, best-practices]
+ai_role: Senior Software Architect
+last_updated: 2026-05-02
+---
+
+# ⚖️ Agentic Architecture Trade-offs
+
+<div align="center">
+  **Pros, cons, and architectural constraints.**
+</div>
+
+---
+
+## 📊 Structural Comparisons
+
+| Architecture Aspect | Advantage | Disadvantage | Mitigation |
+| :--- | :--- | :--- | :--- |
+| **Token Usage** | High token efficiency per specialized task | Overall token usage across system is higher | Use smaller models for trivial worker tasks |
+| **Latency** | Parallel execution of independent tasks | Multiple agent handoffs increase TTFB | Stream responses or use fast inference APIs |
+| **Determinism** | Structured outputs increase reliability | Hallucination risks during delegation | Strict schema validation at every step |
+| **Complexity** | Extremely modular and scalable | Harder to debug and trace state | Centralized logging in Orchestrator |

architectures/microkernel-architecture/data-flow.md

@@ -0,0 +1,42 @@
+---
+technology: Microkernel Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [plugin-architecture, extensibility, solid-principles, core-system, best-practices]
+ai_role: Senior Software Architect
+last_updated: 2026-05-02
+---
+
+# 🔄 Microkernel Architecture Data Flow Best Practices
+
+<div align="center">
+  **Core-to-Plugin execution paths and contract enforcement.**
+</div>
+
+---
+
+## 🔁 The Sequence of Execution
+
+In Microkernel Architecture, the Core dictates the flow, while Plugins provide specialized logic.
+
+```mermaid
+sequenceDiagram
+    participant Core as Core Engine
+    participant Reg as Plugin Registry
+    participant Plugin as External Plugin
+
+    Core->>Reg: Initialize Registry
+    Plugin->>Reg: Register Self (implements Interface)
+    Core->>Core: Process Business Logic
+    Core->>Reg: Request Plugins for Task
+    Reg-->>Core: Return active Plugins
+    Core->>Plugin: Execute Plugin Interface Method
+    Plugin-->>Core: Return processed Data
+    Core->>Core: Finalize Business Logic
+```
+
+## ⛔ Boundary Constraints (Data Flow Rules)
+
+1. **One-Way Dependency:** Plugins MUST depend on Core Interfaces. The Core MUST NEVER depend on Plugin concrete implementations.
+2. **Contract Strictness:** Data passed between Core and Plugins MUST adhere to strict, validated DTOs.

architectures/microkernel-architecture/folder-structure.md

@@ -0,0 +1,42 @@
+---
+technology: Microkernel Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [plugin-architecture, extensibility, solid-principles, core-system, best-practices]
+ai_role: Senior Software Architect
+last_updated: 2026-05-02
+---
+
+# 📁 Microkernel Architecture Folder Structure Best Practices
+
+<div align="center">
+  **Absolute isolation of the Core engine from volatile Plugins.**
+</div>
+
+---
+
+## 🏗️ Structure Rules
+
+```mermaid
+classDiagram
+    class src:::component
+    class core:::component
+    class plugins:::component
+    class shared:::component
+
+    src --> core
+    src --> plugins
+    src --> shared
+
+    note for core "Core system orchestrator and registry interfaces"
+    note for plugins "Independent modules implementing core interfaces"
+    note for shared "Data types and common utilities"
+
+    %% Design Tokens
+    classDef component fill:#e8f5e9,stroke:#4caf50,stroke-width:2px,color:#000;
+```
+
+## 📌 Core Constraints
+1. **Isolated Registries:** The `core/` directory MUST contain the registry logic and interface definitions.
+2. **Independent Plugins:** Each plugin in `plugins/` MUST be self-contained and potentially extractable into a separate package.

architectures/microkernel-architecture/implementation-guide.md

@@ -0,0 +1,54 @@
+---
+technology: Microkernel Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [plugin-architecture, extensibility, solid-principles, core-system, best-practices]
+ai_role: Senior Software Architect
+last_updated: 2026-05-02
+---
+
+# 🛠️ Microkernel Architecture Implementation Guide
+
+<div align="center">
+  **Rules for defining strict interface boundaries and registry mechanisms.**
+</div>
+
+---
+
+## 1. Core-Plugin Coupling
+
+### ❌ Bad Practice
+```typescript
+class ImageProcessor {
+  process(image: Image) {
+    if (image.type === 'png') {
+        PNGProcessor.handle(image); // Hardcoded dependency
+    }
+  }
+}
+```
+
+### ⚠️ Problem
+The Core is tightly coupled to concrete implementations. Adding a new format requires modifying the Core, breaking the Open/Closed Principle and increasing regression risk.
+
+### ✅ Best Practice
+```typescript
+interface ImagePlugin {
+  supports(type: string): boolean;
+  handle(image: Image): void;
+}
+
+class ImageProcessor {
+  constructor(private readonly registry: ImagePlugin[]) {}
+
+  process(image: Image) {
+    const plugin = this.registry.find(p => p.supports(image.type));
+    if (!plugin) throw new Error("Unsupported format");
+    plugin.handle(image);
+  }
+}
+```
+
+### 🚀 Solution
+Invert dependencies using a Plugin Registry. The Core defines the `ImagePlugin` interface, and plugins register themselves. This guarantees O(1) impact on the Core when extending functionality.

architectures/microkernel-architecture/readme.md

@@ -28,10 +28,10 @@ last_updated: 2026-04-18
 
 This architecture defines strict boundaries between a minimal core system and extended functionalities implemented as standalone plugins. It guarantees O(1) impact on the core when adding or modifying auxiliary features.
 
-- 🌊 **Data Flow:** Core-to-Plugin execution paths and contract enforcement.
-- 📁 **Folder Structure:** Absolute isolation of the Core engine from volatile Plugins.
-- ⚖️ **Trade-offs:** Extensibility vs. Contract Management complexity.
-- 🛠️ **Implementation Guide:** Rules for defining strict interface boundaries and registry mechanisms.
+- 🌊 **[Data Flow](./data-flow.md):** Core-to-Plugin execution paths and contract enforcement.
+- 📁 **[Folder Structure](./folder-structure.md):** Absolute isolation of the Core engine from volatile Plugins.
+- ⚖️ **[Trade-offs](./trade-offs.md):** Extensibility vs. Contract Management complexity.
+- 🛠️ **[Implementation Guide](./implementation-guide.md):** Rules for defining strict interface boundaries and registry mechanisms.
 
 ```mermaid
 graph TD

architectures/microkernel-architecture/trade-offs.md

@@ -0,0 +1,26 @@
+---
+technology: Microkernel Architecture
+domain: Architecture
+level: Senior/Architect
+version: Agnostic
+tags: [plugin-architecture, extensibility, solid-principles, core-system, best-practices]
+ai_role: Senior Software Architect
+last_updated: 2026-05-02
+---
+
+# ⚖️ Microkernel Architecture Trade-offs
+
+<div align="center">
+  **Extensibility vs. Contract Management complexity.**
+</div>
+
+---
+
+## 📊 Structural Comparisons
+
+| Architecture Aspect | Advantage | Disadvantage | Mitigation |
+| :--- | :--- | :--- | :--- |
+| **Extensibility** | Core remains untouched when adding features | Managing multiple plugin repositories is hard | Mono-repo or strict versioning |
+| **Testing** | Core and Plugins are unit-testable independently | Integration testing is complex | Robust contract testing strategy |
+| **Performance** | Load only necessary plugins at runtime | Plugin discovery overhead | Cache registry lookups |
+| **Maintenance** | Isolated bug fixes without core regressions | API versioning for plugins is difficult | Backward compatibility layers |