feat: Skills Architecture - First Principles Design

[gloomcheng]

Summary

Kaido = Thinking Model Display + Command Executor + Knowledge Trigger

Not an answer machine. An expert thinking coach.

---

First Principles

1. Purpose

Teach users to think like experts, not give answers.

2. Essence

• Ops problem = Information asymmetry + Knowledge gap
• AI role = Thinking model (not answer database)

3. Minimum Viable

┌─────────────────────────────────────┐
│           Kaido MVP                 │
├─────────────────────────────────────┤
│  1. Understand (NLP → Command)      │
│  2. Execute (Shell Execution)      │
│  3. Show Thinking (ReAct Display)  │
│  4. Explain (Command Explanation)  │
└─────────────────────────────────────┘

---

Architecture: Thin Core + Skills + Context + LLM

┌─────────────────────────────────────────────────────┐
│                    Kaido Core                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐│
│  │   NLP →    │  │   Shell     │  │   ReAct     ││
│  │  Command   │→ │  Executor   │→ │   Display   ││
│  └─────────────┘  └─────────────┘  └─────────────┘│
└─────────────────────────────────────────────────────┘
           ↑                    ↑                    ↑
           │                    │                    │
           └────────────────────┴────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
   ┌──────────┐         ┌──────────┐         ┌──────────┐
   │  Skills   │         │ Context  │         │   LLM    │
   │ (YAML)    │         │ Target   │         │ (Brain)  │
   │ trigger   │         │ collect  │         │ thinking │
   │ structure │         │ snapshot │         │          │
   └──────────┘         └──────────┘         └──────────┘

Core Interface

pub trait KaidoCore {
    fn understand(&self, input: &str) -> Command;
    async fn execute(&self, cmd: &Command, target: &Target) -> Result<Output>;
    fn display_reasoning(&self, steps: &[ReasoningStep]) -> String;
    fn explain(&self, cmd: &str) -> String;
}

Skills = Trigger + Structure

skill:
  trigger: [pod, k8s, kubernetes]
  
  diagnosis_prompt: |
    Diagnosis flow:
    1. Get pod status
    2. Get events  
    3. Check logs
    4. Analyze root cause
    
  explanations:
    kubectl: \"K8s CLI for cluster management\"
    pod: \"K8s smallest deployable unit\"

Context = Target Agnostic

enum Target {
    Local,
    Remote { host: String, user: String },
}

trait ContextCollector {
    async fn collect(&self, target: &Target) -> SystemSnapshot;
}

---

CLI Usage

# Local
kaido \"nginx 502\"

# Remote SSH
kaido \"postgres down\" --target user@prod-db.example.com

# JSON output
kaido \"pod crash\" --json | jq '.thinking'

---

Implementation

Phase 1: Core + JSON

• --json flag
• --target flag (local/SSH)

Phase 2: Skills Architecture

• Skill YAML schema
• Skill loader
• ReAct integration

Phase 3: Domains

• K8s (existing → YAML)
• Network
• Security
• Database

---

Principles

Principle	Meaning
Thin Core	Minimum code, maximum value
Skills = Data	Knowledge in YAML, not code
Target Agnostic	Local/SSH/K8s all work
Thinking First	Show thinking, not answers