# Rozbudowa narzedzia

Ten plik opisuje, jak dodawac nowe grupy zadan, zadania i skrypty, zeby kolejny agent nie musial projektowac procesu od zera.

## Zasada architektury

Kazde zadanie powinno dzialac w tym samym modelu:

1. Pobierz aktualne dane.
2. Zbuduj plan.
3. Zapisz plan do `clients/<domena>/plans/` jako `.json` i `.md`.
4. W trybie `--plan-only` nie wdrazaj zmian.
5. Po akceptacji uzytkownika wdrazaj tylko plan zapisany w JSON.
6. Zapisz historie do:
   - `clients/<domena>/history/YYYY-MM-DD.jsonl`
   - `clients/<domena>/changes/YYYY-MM-DD.md`

Agent AI prowadzi uzytkownika, ale logika pobierania danych, analizy i wdrozenia zmian ma byc w Pythonie.

## Dodanie nowej grupy zadan

Przed dodaniem wiekszego zakresu sprawdz:

```text
OLD_COMMANDS_CHECKLIST.md
```

To jest lista rzeczy sprawdzanych przez stary system z `D:\google ads\`.

Edytuj:

```text
config/tasks.toml
```

Dodaj nowa grupe:

```toml
[[groups]]
id = "search"
name = "Kampanie Search"
```

Zadania beda numerowane automatycznie jako `2.1`, `2.2`, itd. w zaleznosci od kolejnosci grup.

## Dodanie nowego zadania do grupy

W `config/tasks.toml` dodaj zadanie pod odpowiednia grupa:

```toml
[[groups.tasks]]
id = "check_search_settings"
name = "Sprawdzenie ustawien"
description = "Sprawdza ustawienia kampanii Search wedlug regul globalnych i wyjatkow klienta."
```

`id` jest techniczne i musi byc stabilne. `name` i `description` sa dla uzytkownika.

## Plik zadania w Pythonie

Dodaj modul w:

```text
src/gads_v2/tasks/
```

Przyklad nazwy:

```text
src/gads_v2/tasks/search_settings_check.py
```

Minimalny wzorzec funkcji:

```python
def run_check_search_settings(
    client_config: ClientConfig,
    global_rules: dict,
    plan_only: bool = False,
    apply_plan_path: str | None = None,
    confirm_apply: str | None = None,
    show_navigation: bool = True,
) -> None:
    ...
```

Wymagania:

- `plan_only=True` zawsze tylko zapisuje plan.
- `apply_plan_path` wdraza tylko wskazany plan JSON.
- `confirm_apply` musi wymagac wartosci `TAK`.
- `show_navigation=False` musi ukrywac pytanie `Co dalej`, bo uzywa tego tryb sekwencji.

## Struktura planu

Plan powinien miec klase lub slownik z metodami:

```python
to_dict()
from_dict()
```

Plan JSON musi zawierac:

```json
{
  "created_at": "...",
  "client": "example.pl",
  "task": "task_id",
  "changes": []
}
```

Plan Markdown powinien zawierac:

- krotkie podsumowanie,
- tabele po kampaniach, jesli zadanie dotyczy kampanii,
- tabele planowanych dzialan,
- ostrzezenia lub pominiete reguly.

## Podpiecie zadania do CLI

Edytuj:

```text
src/gads_v2/cli.py
```

1. Zaimportuj funkcje zadania:

```python
from .tasks.search_settings_check import run_check_search_settings
```

2. Dodaj `id` do argumentu `--task`:

```python
parser.add_argument("--task", choices=["sync_pla_cl1", "check_pla_settings", "check_search_settings"], ...)
```

3. Dodaj obsluge w `run_task()`:

```python
if task_id == "check_search_settings":
    run_check_search_settings(
        client,
        global_rules,
        plan_only=plan_only,
        apply_plan_path=apply_plan_path,
        confirm_apply=confirm_apply,
        show_navigation=show_navigation,
    )
    return
```

## Reguly globalne i wyjatki klientow

Reguly trzymaj w:

```text
config/clients.toml
```

Przyklad globalny:

```toml
[global_rules.search_settings]
require_presence_only = true
require_search_partners_off = true
```

Wyjatek per klient:

```toml
[clients."example.pl".search_settings]
require_search_partners_off = false
```

W kodzie uzywaj:

```python
rules = client_config.effective_rules(global_rules, "search_settings")
```

## Numeracja i wybory

Lista zadan uzywa formatu:

```text
1.1 - pierwsze zadanie w pierwszej grupie
1.2 - drugie zadanie w pierwszej grupie
1.0 - wszystkie zadania z pierwszej grupy
ALL - wszystkie zadania ze wszystkich grup
```

Nie dodawaj recznej numeracji do `tasks.toml`. Numeracja wynika z kolejnosci grup i zadan.

## Test po dodaniu zadania

Uruchom:

```powershell
python -m compileall -q gads.py src
python gads.py analiza-klienta --client-number 1
python gads.py analiza-klienta --client-number 1 --select <nr> --plan-only
```

Jesli zadanie wdraza zmiany, przetestuj najpierw tylko `--plan-only`.

## Format komunikacji agentow

Instrukcja dla agentow jest w:

```text
AGENTS.md
```

Po dodaniu nowego typu zadania dopisz tam tylko specjalne zasady, jesli agent ma wiedziec cos ponad standardowy przeplyw.
