# KAOS — AI-Supervised Development System

**Verzija:** 0.1.0
**Status:** Pokretanje
**Autor:** DAL d.o.o.
**Poslednje ažuriranje:** 2026-02-20

---

## Š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/
│
└── TASKS/                     ← taskovi, specifikacije, izveštaji
    ├── MASTER-STATUS.md
    ├── Architecture.md
    ├── Workflow-Spec.md
    ├── Supervisor-Spec.md
    ├── Multi-Agent-Spec.md
    ├── Implementation-Tasks.md
    └── reports/
```

---

## Verzije

### v0.1 — Osnova (TRENUTNO)
- Mastermind + agenti definisani u CLAUDE.md fajlovima
- Supervisor: ručno pokretanje (`kaos-supervisor run T01`)
- Checker: build + test + vet (deterministički)
- Izveštaji: markdown u TASKS/reports/
- Git: direktno na main
- Nema baze, nema frontend-a, nema AI trijaže

### v0.2 — Automatizacija (planirano)
- Supervisor daemon ili watch folder
- AI trijaža prijava
- AI compliance provere (modul, pravila, konvencije)
- Staging → main branch strategija
- Auto-retry za flaky testove
- Notifikacije (konfigurabilan kanal)

### v0.3 — Kompletni ekosistem (planirano)
- Frontend dashboard
- WebSocket real-time praćenje
- Help sistem
- Embed SDK
- Cost tracking dashboard
- Metrike i analitika
- Distribucija prema licencama

---

## 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 | React + TypeScript + Vite + Tailwind + shadcn/ui | 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.