# KAOS — AI-Supervised Development System

**Verzija:** 0.3.0
**Status:** Aktivan razvoj
**Autor:** DAL d.o.o.
**Poslednje azuriranje:** 2026-02-21

---

## Šta je KAOS

Sistem gde AI agenti razvijaju softver pod ljudskim nadzorom.
Jedan mastermind orkestrira, specijalizovani agenti izvršavaju,
čovek odobrava. Svaki agent zna samo svoj deo posla.

---

## Kako radi

```
Klijent prijavi (šta hoće ili šta ne radi)
        │
        ▼
Operater proveri (da li ima smisla, doradiš opis)
        │
        ▼
Mastermind se uključi (čita kontekst, razume problem)
        │
        ▼
Task se zapiše (markdown, u listu taskova)
        │
        ▼
Operater odobri (ok, kreni)
        │
        ▼
Mastermind pokrene agenta (pravi model, minimalan kontekst)
        │
        ▼
Agent izvrši (kodira, testira, commituje)
        │
        ▼
Checker verifikuje (build, test, vet — nezavisno)
        │
        ▼
Reporter napiše izveštaj (šta, koliko, koliko koštalo)
        │
        ▼
Operater pregleda (kod, testovi, izveštaj)
        │
        ▼
Deploy ili dorada
```

---

## Arhitektura — Multi-Agent

```
                    ┌─────────────────┐
                    │   MASTERMIND    │
                    │  (root CLAUDE)  │
                    │  ne kodira,     │
                    │  orkestrira     │
                    └───────┬─────────┘
                            │
        ┌───────┬───────┬───┴───┬───────┬───────┬───────┬───────┐
        ▼       ▼       ▼       ▼       ▼       ▼       ▼       ▼
    ┌───────┐┌──────┐┌──────┐┌──────┐┌───────┐┌────────┐┌────┐┌───────┐
    │Triage ││Task  ││Coder ││Front ││Checker││Reporter││Docs││Deploy │
    │       ││Mgr   ││      ││end   ││       ││        ││    ││er     │
    │Haiku  ││Sonnet││Sonnet││Sonnet││Haiku/ ││Haiku   ││Haiku││Haiku │
    │       ││      ││/Opus ││      ││Opus   ││        ││    ││      │
    └───────┘└──────┘└──────┘└──────┘└───────┘└────────┘└────┘└───────┘
```

**Princip:** Agenti ne komuniciraju međusobno. Samo sa mastermindom.
**Cena:** Uvek najjeftiniji model koji može da uradi posao.

---

## Struktura projekta

```
/root/projects/KAOS/
│
├── CLAUDE.md                  ← mastermind (v0.1.0)
├── README.md                  ← ovo
│
├── agents/                    ← specijalizovani agenti
│   ├── triage/CLAUDE.md       ← klasifikacija prijava
│   ├── task-manager/CLAUDE.md ← kreiranje taskova, status
│   ├── coder/CLAUDE.md        ← backend kodiranje
│   ├── frontend/CLAUDE.md     ← React kodiranje
│   ├── checker/CLAUDE.md      ← verifikacija
│   ├── reporter/CLAUDE.md     ← izveštaji
│   ├── docs/CLAUDE.md         ← eksterna dokumentacija
│   └── deployer/CLAUDE.md     ← git merge, verzije, deploy
│
├── documentation/             ← eksterna dokumentacija (tuđe)
│   ├── api-specs/
│   ├── regulations/
│   └── third-party/
│
├── docs/                      ← dokumentacija
│   ├── SPEC.md
│   ├── ARCHITECTURE.md
│   └── SETUP.md
│
├── code/                      ← Go kod (server, testovi)
│   ├── cmd/kaos-server/
│   ├── internal/server/
│   ├── internal/supervisor/
│   └── web/templates/
│
└── TASKS/                     ← taskovi po stanju
    ├── backlog/
    ├── ready/
    ├── active/
    ├── review/
    ├── done/
    └── reports/
```

---

## Verzije

### v0.1 — Osnova
- Mastermind + agenti definisani u CLAUDE.md fajlovima
- Supervisor: rucno pokretanje (`kaos-supervisor run T01`)
- Checker: build + test + vet
- Izvestaji: markdown u TASKS/reports/

### v0.2 — Dashboard
- Web dashboard sa Kanban board-om
- Drag & drop premestanje taskova
- SSE real-time update
- Pretraga, dokumenti, prijava taskova

### v0.3 — Konzola i PTY (TRENUTNO)
- xterm.js terminali u browseru
- Svaki task dobija sopstvenu claude PTY sesiju
- "Pusti" automatski pokrece rad
- "Proveri" pokrece review sesiju
- WebSocket za real-time terminal I/O
- Replay buffer za reconnect
- 125+ testova u 12 fajlova

---

## Donesene odluke

| Odluka | Izbor | Datum |
|--------|-------|-------|
| Arhitektura | Multi-agent (mastermind + specijalizovani) | Feb 2026 |
| Komunikacija | Agenti → samo sa mastermindom, nikad međusobno | Feb 2026 |
| Model selekcija | Po zadatku: Haiku/Sonnet/Opus | Feb 2026 |
| Format taskova | Markdown (nema JSON-a, jedno mesto istine) | Feb 2026 |
| Triger | Ručno v0.1, automatizacija v0.2 | Feb 2026 |
| Verifikacija | Dupla (agent + supervisor nezavisno) | Feb 2026 |
| Retry | Čekaj operatera (v0.1), auto-retry (v0.2) | Feb 2026 |
| Verzionisanje | Semver (Major.Minor.Patch) | Feb 2026 |
| Izveštaji | Markdown u TASKS/reports/, idu u git | Feb 2026 |
| Dorada | Novi task sa MD referencom na stari | Feb 2026 |
| Rollback | Git revert (v0.1) | Feb 2026 |
| Branch | Direktno main (v0.1), staging (v0.2) | Feb 2026 |
| Timeout | Ručno podešavanje, operater odlučuje | Feb 2026 |
| Troškovi | Praćenje po tasku (tokeni, cena, vreme) | Feb 2026 |
| Backend | Go | Feb 2026 |
| Frontend | Go templates + HTMX + Sortable.js (nula npm) | Feb 2026 |
| Baza | PostgreSQL (v0.2+) | Feb 2026 |
| HTTP framework | Gin (v0.2+) | Feb 2026 |
| Engine | `pkg/engine/` javni paket, nula HTTP (v0.2+) | Feb 2026 |

---

## Poreklo

KAOS je nastao iz ARV (Advanced Resource & Venue Management) projekta
gde smo dokazali da AI agent može da razvija softver pod nadzorom.
ARV ima 43+48 završenih taskova ovim pristupom.
KAOS formalizuje taj proces u alat koji može da se koristi za bilo koji projekat.