# Specyfikacja i Konfiguracja Systemu OpenClaw (Reference)

Ten dokument zawiera skonsolidowane wytyczne, szablony i konfiguracje dla systemu agentowego OpenClaw, w tym mechanizmy Heartbeat, definicje zadań Cron, Watchdog oraz procedury synchronizacji pamięci.

---

## 1. Mechanizm Heartbeat (HEARTBEAT.md)

Plik `HEARTBEAT.md` jest odczytywany przez agenta przy każdym pulsie (heartbeat) w celu synchronizacji kontekstu.

### 1.1 Szablon Uniwersalny
```markdown
# HEARTBEAT.md — <AGENT_NAME> <ROLE/ICON>

Cel:
- Ustalenie aktualnego kontekstu.
- Synchronizacja pamięci ze źródłem prawdy (Source of Truth).
- Wykrywanie blokad i zadań oczekujących.

## Procedura (Każdy Puls)

1. **Read Shared Context**: `~/clawd/team/shared/TEAM-MEMORY.md` (Mózg zespołu).
2. **Read Personal State**: `MEMORY.md`, `BACKLOG.md` (Zobowiązania agenta).
3. **Check Notes**: `NOTES.md` (Luźne wątki, przypomnienia).
4. **Scan Task Source of Truth**:
   ```bash
   curl -s http://localhost:7100/api/pm-board
   ```
   - Filtruj po: `assignee = <AGENT_NAME>`
   - Skup się na: active, blocked, recently changed.

## ⚠️ Zasada Source of Truth
PM Board jest ostatecznym źródłem prawdy o statusie zadań.
- Jeśli PM Board = **DONE**, a MEMORY.md = **ACTIVE** -> Ufaj tablicy, zaktualizuj pamięć.
- Nigdy nie aktualizuj statusu na tablicy PM wyłącznie na podstawie pamięci agenta.

## Eskalacja
Zgłoś do warstwy koordynacji (np. Muddy) przez `sessions_send`, gdy:
- Zadanie jest zablokowane.
- Brakuje kontekstu.
- Wykryto konflikt Board vs Memory.

Jeśli wszystko OK: `HEARTBEAT_OK`
```

### 1.2 Wzorzec dla Roli CTO
```markdown
# HEARTBEAT.md — <CTO_NAME> 🛠 CTO

Focus: Kierunek techniczny, spójność architektury, ryzyka, odblokowywanie dostaw.

## Procedura Specyficzna
1. **Scan PM Board**: Szukaj nie tylko swoich zadań, ale blokad (blockers), wysokich priorytetów i zależności międzyzespołowych.
2. **Checks**:
   - Zdrowie dostaw (Top 3 deliverables).
   - Architektura (czy wymagane ADR? naruszenia standardów?).
   - Niezawodność (incydenty, błędy w budżecie SLO).
   - Bezpieczeństwo (wycieki sekretów, podatności).
   - Koszty (FinOps - nagłe piki zużycia).

## Triggery Uwagi (Escalate Immediately)
- Brak właściciela dla krytycznej blokady.
- Decyzja oczekująca > X godzin.
- Ryzyko bezpieczeństwa lub utraty danych.
- Rozbieżność rzeczywistości z tablicą PM ("phantom done").
```

---

## 2. Konfiguracja Agenta (agent.json)

Przykład definicji instancji agenta:

```json
{
  "id": "elon",
  "workspace": "~/clawd/team/elon",
  "heartbeat": {
    "every": "173m",
    "activeHours": {
      "start": "08:00",
      "end": "23:00"
    },
    "model": "google-gemini-cli/gemini-3-flash-preview",
    "target": "telegram"
  },
  "subagents": {
    "allowAgents": ["main"]
  }
}
```

---

## 3. Zadania Zaplanowane i Monitorowanie (Cron & Watchdog)

### 3.1 Definicje Zadań Cron
Wzorzec: Cron powinien być krótki, wskazywać na konkretny `SKILL.md`.

```yaml
# Główny Sync (Executive)
name: daily-executive-sync
schedule: "30 8 * * 1,2,3,4,5"
model: anthropic/claude-opus-4-6

# Watchdog (Weryfikacja sukcesu)
name: watchdog-daily-sync
schedule: "0 9 * * 1,2,3,4,5"
model: haiku
sessionTarget: isolated
message: |
  Verify daily-executive-sync success.
  1. Run `bash ~/clawd/scripts/sync-watchdog.sh daily`
  2. If exit 1 (FAIL): Send Telegram alert to Muddy + re-trigger sync.
```

### 3.2 Skrypt Watchdog (`sync-watchdog.sh`)
```bash
#!/bin/bash
# Usage: ./sync-watchdog.sh <daily|weekly|saturday>

TYPE=$1
TODAY=$(date +%Y-%m-%d)
MONTH=$(date +%Y-%m)
DIR="$HOME/clawd/team/meetings/$MONTH"

if [ "$TYPE" = "daily" ]; then
  EXPECTED_FILE="$DIR/$TODAY-daily-sync.md"
elif [ "$TYPE" = "weekly" ]; then
  EXPECTED_FILE="$DIR/$TODAY-weekly-sync.md"
elif [ "$TYPE" = "saturday" ]; then
  EXPECTED_FILE="$HOME/clawd/team/meetings/saturday-vision.md"
fi

if [ -f "$EXPECTED_FILE" ]; then
  SIZE=$(stat -c%s "$EXPECTED_FILE")
  [ "$SIZE" -gt 1000 ] && exit 0 # OK
fi

exit 1 # FAIL
```

---

## 4. Umiejętności Systemowe (Skills)

### 4.1 Executive Sync (Daily Ops)
Przebieg spotkania zarządczego (COO + Chiefs):
1. **Gather State**: PM Board, C-suite chat (notatki Human), poprzednie transkrypcje (tylko diff).
2. **Spawn Chiefs**: Uruchomienie sub-agentów (CTO, CMO, CRO) równolegle przez `sessions_spawn`.
3. **Compile Transcript**: 
   - Runda 1: Raporty (dialog naturalny).
   - Runda 2: Konflikty i zależności.
   - Runda 3+: Rozwiązania i zobowiązania.
4. **Finalize**: Zapis transkrypcji, generowanie Audio (TTS), aktualizacja PM Board, raport na Telegram.

### 4.2 Chief Workspace Sync
Synchronizacja decyzji z poziomu COO do poszczególnych agentów.
- **Krok 1**: Porównaj `MEMORY.md` każdego Chiefa z PM Board (usuwanie "Zombie Items").
- **Krok 2**: Zbuduj blok `SYNC FROM COO` (aktywne reguły, martwe zadania, aktualizacje per-chief).
- **Krok 3**: Podmień sekcję w workspace agenta (REPLACE, never append).

### 4.3 Weekly Memory Reconciliation (Niedziela)
1. **Audit**: Przegląd plików dziennych z 7 dni.
2. **Extract**: Wyciągnięcie kluczowych decyzji, lekcji i kamieni milowych.
3. **Update MEMORY.md**: Destylacja wiedzy, usuwanie duplikatów (limit 500 linii).
4. **Cron Audit**: Sprawdzenie czy prompty w Cron nie "odpłynęły" od definicji w Skills.

---

## 5. Kanoniczna Architektura (Zasady Ogólne)

1. **Struktura Plików**:
   - `~/clawd/MEMORY.md`: Zasady permanentne.
   - `~/clawd/memory/YYYY-MM-DD.md`: Zmiany dzienne.
   - `~/clawd/skills/`: Cała logika procedur (SKILL.md).
   - `~/clawd/team/shared/TEAM-MEMORY.md`: Wspólna wiedza zespołu.

2. **Single Source of Truth**:
   - Zadania -> **PM Board**.
   - Decyzje/Ryzyka -> **MEMORY.md**.

3. **Determinizm**:
   - Krytyczne crony uruchamiane jako `isolated`.
   - Watchdog to tani model (Haiku), tylko weryfikuje obecność artefaktów.

4. **Komunikacja**:
   - Raporty tylko gdy wymagana akcja lub wykryto błąd.
   - `HEARTBEAT_OK` jako domyślny status ciszy.