KOR SDK Context & Architecture

You are working on the KOR SDK, an Enterprise Developer Platform built on a Vertical Architecture.

1. Core Philosophy: The "KOR Way"

• •Vertical Architecture: Code is organized by domain (mcp, lsp, skills, plugin), not by technical layer (models, views). Each domain is self-contained.
• •Consolidated Modules: We prefer single-file modules (e.g., events.py, search.py, commands.py) over scattered __init__.py files when the complexity is low (< 5 files).
• •Facade First: The public API is the Kor class in kor_core.api. Always design for the user accessing functionality via kor = Kor().
• •Pythonic & Explicit: We use explicit typing, dataclasses, and standard Python patterns. We avoid "magic" where possible (e.g., rigid frameworks).

2. Directory Map (Deep Dive)

packages/kor-core/src/kor_core/:

Core Infrastructure

• •api.py (The Facade): The ONLY intended public entry point.
  • •Rule: Never import Kernel in user code. Use from kor_core import Kor.
• •kernel.py (The Engine): Orchestrates lifecycle.
  • •Key: It is a Singleton. Access via get_kernel() internally if needed, but prefer passing dependencies.
• •config.py: Pydantic-based configuration.
  • •Pattern: Start with ConfigManager().load(). Supports ~/.kor/config.toml.
• •events.py: Unified Event Bus and Telemetry.
  • •Key: Use HookEvent enum for lifecycle events. Contains TelemetrySubscriber and LoggingTelemetrySink.

Vertical Domains

• •mcp/: Model Context Protocol.
  • •Structure: client.py (connects to servers), server.py (hosts resources).
• •lsp/: Language Server Protocol.
  • •Feature: Provides Code Intelligence (Hover, Definition) to Agents.
• •skills.py: Skills System.
  • •Pattern: SkillLoader inherits BaseLoader. SkillRegistry inherits SearchableRegistry.

Plugin System

• •plugin.py: Plugin System.
  • •Consolidated: Contains manifest, loader, context.
  • •Workflow: Plugins are loaded by kernel.py at boot.

Utilities

• •search.py: Unified Search Infrastructure.
  • •Provides: Searchable protocol, SearchableRegistry[T], RegexBackend, BM25Backend.
  • •Pattern: All registries (Tools, Skills, Commands, Agents) inherit from SearchableRegistry.
• •commands.py: Slash Commands System.
  • •Pattern: CommandLoader inherits BaseLoader. CommandRegistry extends SearchableRegistry.

Agent System

• •agent/: Multi-Agent Orchestration.
  • •state.py: AgentState, PlanTask TypedDicts.
  • •planning.py: Planner class with file sync, events.
  • •archiver.py: PlanArchiver for long-term memory.
  • •graph.py: LangGraph workflow builder.
  • •nodes/: Worker nodes (Supervisor, Architect, Coder, etc.).

2.5 Native Planning Architecture

The SDK includes a Plan-and-Execute system for autonomous agents:

• •Entry Flow: AutoPlanner → EnsurePlan → Supervisor → Workers
• •File Sync: Agent state syncs with PLAN.md (GFM checklist).
• •Events: TASK_STARTED, TASK_COMPLETED, PLAN_FINISHED.
• •Memory: Completed plans archived to ~/.kor/memory/plans.jsonl.
• •Tool: ManagePlanTool with actions: add_task, add_subtask, update_status, finish_task.

3. Implementation Recipes

How to add a new Tool

1. •Create Class: In kor_core/tools/<category>.py (or generic tools.py).
2. •Inherit: From BaseTool (pydantic BaseModel).
3. •Register: In kor_core.kernel.Kernel._register_core_tools().
4. •Tag: Add tags/keywords for semantic search discovery.

How to Add a New LLM Provider

1. •Do NOT create a new file: Modify kor_core/llm/provider.py.
2. •Update UnifiedProvider: Ensure _create_client handles the new base_url or signature.
3. •Config: Map it in kor_core/config.py under LLMConfig.

How to Create a Declarative Plugin

1. •Folder: plugins/kor-plugin-<name>/.
2. •Manifest: plugin.json (defines commands, tools).
3. •Scripts: scripts/my_script.py (executable logic).
4. •No Init: Do NOT verify __init__.py for declarative plugins.

4. Coding Standards & Best Practices

• •Typing: Strict mypy compatibility. Use typing.List, typing.Optional.
• •Imports:
  • •Vertical: from . import models (relative within module).
  • •Horizontal: from kor_core.other import thing (absolute across modules).
  • •Avoid circular imports: Use if TYPE_CHECKING: for type-only dependencies.
• •Async/Sync:
  • •The Kernel is primarily Async.
  • •boot_sync() is a wrapper for CLI convenience.
  • •Always await I/O operations (LLM, File, Network).
• •Error Handling:
  • •Use specific exceptions from kor_core.exceptions.
  • •Never swallow exceptions silently in the Kernel.

5. Architecture Decision Records (ADR) - Simplified

• •ADR-001 Vertical Arch: We moved from Layered (loaders/, registries/) to Vertical (mcp/, lsp/) to localize complexity.
• •ADR-002 Facade: We hid the Kernel complexity behind Kor to make the library approachable for beginners.
• •ADR-003 Resources: We moved prompts/markdown OUT of src/ to resources/ to separate code from data.
• •ADR-004 Single File Modules: We merged small folders into single .py files to reduce "tab fatigue".
• •ADR-005 CLI Decoupling: The CLI (chat) is Agent-Agnostic. It renders generic events (messages, next_step) rather than hardcoding agent names.
• •ADR-006 Native Planning: Agents use file-backed PLAN.md for transparent, human-editable planning.

Use this skill to simulate "Senior Engineer" context when editing the codebase.