# Project Skill — plán a diskuze

Založeno: 2026-06-08 (session `websocket_12f851b1`)
Poslední aktualizace: 2026-06-09

---

## Původní požadavek

Oddělit část z notes do `projects/` — projekty, na kterých chci pracovat, ale na které neustále zapomínám. Každý projekt vlastní soubor s poznámkami, náhodné připomínky v rozumném intervalu.

---

## Rozhodnutí: Nový skill `/project`, čistě soubory, frontmatter

### Proč nový skill (ne rozšířit `/note` nebo `/remind`)

- `/note` je pro rychlé poznámky — přidat status, prioritu, next-step by ho překutilo
- `/remind` je pro konkrétní opakující se úkoly — projekty mají jinou životnost
- Samostatný skill = čistší interface, nezávislá evoluce

### Proč soubory místo SQLite

- Volné poznámky, editace částí textu, mazání odstavců — **soubor je přirozenější** než DB řádky
- DB je dobrá pro rychlé filtrování, ale špatná pro: "smaž druhý odstavec", "přidej poznámku mezi dvě existující"
- Frontmatter na začátku souboru = metadata se načtou bez procházení celého souboru
- Git-friendly, jeden commit = jedna změna, jeden diff
- Jedno místo pravdy — žádná desynchronizace mezi DB a souborem

### Proč frontmatter místo indexu + souborů

| Kritérium | Index + soubory | Frontmatter |
|-----------|----------------|-------------|
| Jedno místo pravdy | ❌ Dvě místa, riziko desynchronizace | ✅ Vše v jednom souboru |
| Rychlost listu | ✅ Index okamžitě | ⚡ Parse 10–20 souborů = zanedbatelné |
| Editace metadat | Edit index + edit soubor | Edit jednoho souboru |
| Git/historie | Dva commity, dva diffy | Jeden commit, jeden diff |
| "Přepni se do projektu" | Najdi v indexu, otevři soubor | Otevři soubor, máš vše |

Index přináší jen rychlost listu, ale projektů bude max desítky — parse zanedbatelný. Frontmatter vyhrává na všem ostatním.

---

## Struktura

```
projects/
├── nuget-cache.md
├── grill-me-plugin.md
└── ...
```

### Šablona projektového souboru

```markdown
---
status: active
priority: high
created: 2026-06-09
slug: nuget-cache
---

# NuGet cache

Hostovat vlastní NuGet cache na Linuxu.

## Poznámky

- 2026-06-09: BaGetter podporuje S3
- 2026-06-09: Originální BaGet je mrtvý, BaGetter je fork

## Další krok

zkusit BaGetter v LXC
```

**Frontmatter obsahuje pouze metadata:** `status`, `priority`, `created`, `slug`. Žádný `next_step` — ten je v těle jako sekce `## Další krok`.

---

## Rozdělení odpovědnosti: skript vs. agent

### Skript `project.py` — metadata + základní operace

| Subcommand | Co dělá | Proč ve skriptu |
|------------|---------|-----------------|
| `add <název>` | Vytvoří `.md` s frontmatter a základní strukturou | Deterministické, žádná volba struktury |
| `list` | Parse frontmatter ze všech `.md`, vypíše active | Rychlé, žádný kontext potřeba |
| `show <slug>` | Vypíše celý soubor | Triviální |
| `status <slug> <active|paused|done>` | Změní `status:` v frontmatteru | Jednoduchý regex, deterministické |

### Agent — textové úpravy souboru

| Operace | Jak | Proč na agentovi |
|---------|-----|------------------|
| `project next <slug> "text"` | Agent `edit_file` na sekci `## Další krok` | Struktura může být libovolná, skript by to nezvládl robustně |
| `project note <slug> "text"` | Agent `edit_file` přidá řádek pod `## Poznámky` | Stejný důvod |
| Editace existující poznámky | Agent `edit_file` | Skript by musel parsovat přirozený jazyk |
| Mazání poznámky | Agent `edit_file` | Skript by musel identifikovat "tu poznámku o S3" |
| Změna struktury souboru | Agent `apply_patch` | Skript nemůže předvídat všechny struktury |

**Pravidlo:** Kdykoliv jde o volný text v těle souboru, použije agent `edit_file`/`apply_patch`. Skript řeší jen frontmatter a celkovou strukturu.

---

## Příkazy skillu `/project`

| Příkaz | Kdo provádí | Co dělá |
|--------|-------------|---------|
| `project add <název>` | Skript | Založí projekt, vygeneruje slug, vytvoří soubor |
| `project list` | Skript | Vypíše aktivní projekty (parse frontmatter) |
| `project show <slug>` | Skript | Zobrazí celý soubor |
| `project status <slug> <status>` | Skript | Změní `status` v frontmatteru |
| `project next <slug> <text>` | Agent | Nahradí obsah pod `## Další krok` |
| `project note <slug> <text>` | Agent | Přidá poznámku pod `## Poznámky` |
| `project switch <slug>` | Agent | Uloží slug do `my` scratchpadu pro aktuální session |

---

## Klíčová feature: "Přepni se do projektu"

- **Explicitní slug** — default, `project note nuget-cache "..."`
- **Session context** — `project switch nuget-cache` → `my set project_context=nuget-cache` → další příkazy bez slugu použijí kontext
- **Scope:** Jen aktuální session. Po restartu se kontext ztratí — musí se znovu `project switch`.

---

## Připomínky — odloženo na další kolo

Posílání upomínek je feature pro další iteraci. Nejsou součástí POC.

Navržený mechanismus (pro budoucí implementaci):
- Jeden cron job denně (náhodný čas 8–21h)
- Skript načte `active` projekty, váženě vybere podle priority
- Vypíše `"{name}: {next_step}"`
- Agent přepošle do Telegram

---

## Definitivní rozhodnutí (zodpovězeno 2026-06-09)

### 1. Slug generování
→ Jednoduchý kebab-case lowercase z prvních pár slov názvu. Např. "NuGet package caching" → `nuget-package-caching`. Max pár slov, zbytek se ořízne.

### 2. `next_step` — frontmatter vs. tělo
→ `next_step` je **pouze v těle** jako sekce `## Další krok`. Frontmatter obsahuje jen `status`, `priority`, `created`, `slug`. Důvod: jedno místo pravdy, frontmatter je jen metadata.

### 3. Editace poznámek — skript vs. agent
→ **Na agentovi.** Skript nedokáže robustně pracovat s libovolnou strukturou markdown souboru. Agent použije `edit_file`/`apply_patch`.

### 4. `project switch` — přežití mezi sessiony
→ **Nepřežije.** Kontext je jen v `my` scratchpadu aktuální session. Po restartu se ztratí — explicitní `project switch` znovu.

### 5. Formát priority
→ Slovní: `high`, `medium`, `low`. Čísla jsou nejednoznačná (1 může být nejvyšší i nejnižší).

### 6. Rozdělení skript/agent
→ Skript: `add`, `list`, `show`, `status`. Agent: `next`, `note`, `switch`, veškerá editace/smazání textu.

### 7. Formát data v poznámkách
→ **Nedefinováno.** Struktura souboru je volná. Agent přidává poznámky pod `## Poznámky` jako bullety, ale uživatel může mít libovolnou strukturu.

---

## Otevřené otázky — VŠECHNY ZODPOVĚZENY

### Identifikace projektů — název vs. slug
→ Slug je souborové jméno (`nuget-cache.md`). Uživatel používá slug v příkazech. Jednoznačné, lidsky přívětivé (kebab-case).

### Vztah k `/note` skillu
→ Oddělené. Explicitní `project note <slug>` jde do projektového souboru, obecný `/note` zůstává v SQLite.

### Vztah k `/remind` skillu
→ Oddělené. Projekty mají vlastní připomínkový mechanismus (až v další iteraci).

### Databáze vs. soubory
→ Čistě soubory s YAML frontmatter. Žádná DB.

### Co je "projekt" vs. "úkol"
→ Projekt = dlouhodobá věc s next-step a poznámkami. Úkol = jednorázová připomínka v `/remind`. Hranice je na uživateli.

### Je to nový systém, nebo rozšířit existující?
→ **Nový skill.** Méně systémů = méně údržby je obecně pravda, ale `/note` a `/remind` mají jiný charakter. Projektový skill potřebuje frontmatter, editaci souborů, session context — to by existující skilly překutilo.

---

## Implementační plán POC

| Krok | Co |
|------|-----|
| 1 | `project.py` — `add`, `list`, `show`, `status` |
| 2 | `SKILL.md` — protokol pro agenta (co dělá skript, co agent) |
| 3 | Test — vytvoř 2-3 projekty, ověř editaci přes agenta |

---

## Další kroky

- [ ] Implementovat `project.py` (krok 1)
- [ ] Napsat `SKILL.md`
- [ ] Otestovat základní CRUD
- [ ] Připomínky — další kolo