Metadata-Version: 2.4
Name: ifuri-skills-agent
Version: 0.16.2
Summary: Executable skill registry for deterministic runtimes and LLM-backed doctor, repair and validator agents.
Author: skills-agent maintainers
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema<5,>=4.26.0
Requires-Dist: PyYAML<7,>=6.0.3
Provides-Extra: dev
Requires-Dist: pytest<10,>=9.1.1; extra == "dev"
Requires-Dist: pytest-cov<8,>=6; extra == "dev"
Requires-Dist: ruff<1,>=0.15.21; extra == "dev"
Provides-Extra: planfile
Requires-Dist: planfile>=0.1.117; extra == "planfile"
Provides-Extra: urirun
Requires-Dist: urirun>=0.4.200; extra == "urirun"
Dynamic: license-file

# skills-agent

`skills-agent` jest centralnym rejestrem wykonywalnych umiejętności. Skill opisuje
nie tylko *co* trzeba osiągnąć, lecz także *jak* runtime lub LLM ma wykonać
Doctor, Repair i Validator, jakie ma granice oraz jak udowodnić rezultat.

- **doctor-agent** — diagnoza i dowody, bez naprawiania systemu,
- **repair-agent** — plan lub kontrolowana zmiana przez pull request,
- **validator-agent** — niezależna walidacja diagnozy, planu i rezultatów.

Repozytorium nie zastępuje tych agentów. Stanowi **skill control plane**:
przechowuje kontrakty, procedury i instrukcje, wybiera gotowe skille, uruchamia
etapy w stałej kolejności i waliduje hand-offy JSON. Agenci pozostają osobnymi
**execution planes** z własną logiką domenową.

Zasady budowania kontekstu dla LLM, priorytet źródeł instrukcji i granica między
deterministycznym runtime a modelem są opisane w
[`docs/skills-and-llm.md`](docs/skills-and-llm.md). Polecenie
`skills-agent context . <skill-id> --agent repair-agent` materializuje dokładny,
audytowalny kontekst przekazywany wykonawcy.

## Najważniejsze właściwości

- jedna, walidowana definicja `task.yaml`,
- katalog per zadanie i per agent: `SKILLS/<id>/<agent>/...`,
- sekwencja `doctor → repair → validator`,
- jeden wymagany `correlation_id` zachowany w manifeście i kontraktach wszystkich trzech etapów,
- zapis wyłącznie do jednego jawnego repozytorium produktowego; wildcardy i repozytoria sterujące są odrzucane,
- jeden wersjonowany kontrakt możliwości backendu dla lokalnego `github-com` i GitHub.com,
- izolowany katalog każdego uruchomienia,
- ścisłe kontrakty JSON Schema dla wyników agentów,
- planowanie harmonogramu z timezone zapisanym w zadaniu,
- domyślny tryb bez zapisu; mutacje wyłącznie jako pull request po zatwierdzeniu środowiska,
- uwierzytelnianie między repozytoriami krótkotrwałym tokenem GitHub App,
- deterministyczne generowanie scaffoldów oraz opcjonalne wejście NL przez GitHub Models,
- brak obowiązkowej zależności od płatnego GitHub Copilot/Codex,
- opcjonalny rejestr zadań na `planfile` (`skills-agent tickets`),
- opcjonalne monitorowanie procesów na `urirun` (`skills-agent process`).

## Struktura repozytorium

```text
.
├── SKILLS/
│   └── 0001_org-repo-audit/
│       ├── task.yaml
│       ├── README.md
│       ├── doctor-agent/{README.md,run.py,input/,output/,logs/}
│       ├── repair-agent/{README.md,run.py,input/,output/,logs/}
│       └── validator-agent/{README.md,run.py,input/,output/,logs/}
├── schemas/                 # kontrakty zadań, agentów i repo docelowych
├── src/skills_agent/          # zgodny wstecz rdzeń implementacji
├── src/skills_agent/        # kanoniczna fasada importu
├── scripts/                 # cienkie entrypointy do CI
├── templates/               # czytelne szablony dla ludzi
├── docs/                    # architektura, bezpieczeństwo i plan wdrożenia
└── .github/workflows/       # CI, orkiestrator, ręczne uruchomienie i generator NL
```

## Pakiet zadania

`task.yaml` jest źródłem prawdy dla automatu. `README.md` zawiera kontekst dla człowieka. Każdy agent ma własny entrypoint i katalogi runtime.

```text
SKILLS/0042_customer-mail-triage/
├── task.yaml
├── README.md
├── doctor-agent/
│   ├── README.md
│   ├── run.py
│   ├── input/
│   ├── output/
│   └── logs/
├── repair-agent/
└── validator-agent/
```

Status `ready` oznacza, że kod zadania, kontrakty i kryteria akceptacji są gotowe do uruchomienia. Generator zawsze tworzy task ze statusem `todo`, aby wygenerowana treść nie została wykonana bez przeglądu.

## Rejestr zadań (planfile) i procesy (urirun)

skills-agent działa w oparciu o **listę zadań** i **monitorowanie procesów**, ale
oba filary są od siebie oddzielone i obie zależności są opcjonalne:

- **Lista zadań — `planfile`.** Kontraktem wykonania pozostaje
  `SKILLS/<id>/task.yaml`, natomiast rejestrem/backlogiem jest store `planfile`.
  Każde zadanie jest rzutowane na bilet planfile (dopasowanie po etykiecie
  `task:<id>`, idempotentnie), więc wybór następnego zadania korzysta z
  kontraktu runnability planfile, a backlog jest wspólny z resztą toolchainu.
  Ten sam moduł udostępnia wstrzykiwalny backend PM; pętla Subactor reużywa
  `planfile.sync.OneDevBackend`, mapuje ticket po `todo-task:<task_id>` i zapisuje
  w OneDev rezultat receipt bez bezpośredniej synchronizacji z GitHub Issues.
- **Procesy — `urirun`.** Uruchomienie zadania może działać jako proces
  adresowany URI `agent://todo/<task>/run` z trwałym rekordem (pid, log, kod
  wyjścia) i podglądem stanu running/exit przez `urirun.host.work_runs`.
  Domyślny izolowany runner (`skills-agent run`) pozostaje synchroniczny; warstwa
  `skills-agent process` dokłada uruchamianie w tle z monitoringiem.

Instalacja z warstwami opcjonalnymi:

```bash
python -m pip install -e '.[dev,planfile,urirun]'
```

Rejestr zadań (planfile):

```bash
skills-agent tickets sync .           # rzutuj SKILLS/*/task.yaml na bilety planfile
skills-agent tickets list . --status open
skills-agent tickets next .           # następny bilet zgodny z kontraktem runnability
skills-agent tickets status . PLF-001 in_progress
```

Monitorowanie procesów (urirun):

```bash
skills-agent process launch . 0001_org-repo-audit --wait   # uruchom jako proces URI
skills-agent process list .                                # stan running/exit + tail logów
```

Bez zainstalowanych warstw polecenia zwracają czytelny błąd z podpowiedzią
instalacji; rdzeń (`validate`, `discover`, `run`, `scaffold`) nie wymaga żadnej
z nich. Szczegóły: `docs/integrations/planfile.md`, `docs/integrations/urirun.md`.

## Uruchomienie lokalne

Wymagany jest Python 3.11+.

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
make check
```

Walidacja i discovery:

```bash
skills-agent validate .
skills-agent discover . --event manual
skills-agent discover . --event schedule --now 2026-07-15T00:15:00Z
```

Test zadania audytowego bez połączenia z GitHubem:

```bash
GITHUB_ORG=example-org \
TODO_AGENT_AUDIT_FIXTURE="$PWD/SKILLS/0001_org-repo-audit/doctor-agent/input/sample-organization.json" \
skills-agent run . 0001_org-repo-audit
```

Wynik pojawi się w `.skills-agent-runs/<task-id>/<run-id>/` i zawiera manifest, raport zbiorczy oraz artefakty każdego agenta.

## Generowanie kompletnego zadania

Generator deterministyczny nie używa modelu:

```bash
skills-agent scaffold . \
  --title "Analiza nieodebranych wiadomości klientów" \
  --description "Zidentyfikuj wiadomości bez odpowiedzi, przygotuj szkice i zweryfikuj politykę komunikacji." \
  --type customer-support \
  --priority high \
  --scope-level external
```

Można również przekazać JSON zgodny z `schemas/task-spec.schema.json`:

```bash
skills-agent scaffold . --spec-file task-spec.json
```

Workflow `generate-task-from-nl.yml` jest opcjonalnym front-endem: GitHub Models zamienia opis na mały JSON, a ten sam deterministyczny generator tworzy pliki i otwiera draft pull request. Odpowiedź modelu nigdy nie jest wykonywana bezpośrednio.

## GitHub Actions i dostęp do organizacji

Do audytu wielu repozytoriów skonfiguruj:

- variable `GITHUB_ORG`,
- variable `TODO_AGENT_APP_CLIENT_ID`,
- secret `TODO_AGENT_APP_PRIVATE_KEY`,
- środowisko `skills-agent-apply` z wymaganymi reviewerami dla tasków `pull-request`.

Wbudowany `GITHUB_TOKEN` pozostaje wystarczający dla samego repo `skills-agent`. Odczyt lub zapis w innych repozytoriach wykorzystuje token instalacyjny GitHub App. Minimalne uprawnienia są opisane w `docs/github-app.md`, a kompletna instalacja i przejście na produkcję w `docs/LIVE_SYSTEM_SETUP.md`.

Utworzenie kolejnej rozdzielonej tożsamości Repair/Validator przez oficjalny GitHub App Manifest flow uruchamia `make github-app-install`.

## Standard repozytorium docelowego

Każdy projekt powinien zawierać co najmniej:

- `README.md` — cel, instalacja, użycie i utrzymanie,
- `TODO.md` — wyłącznie aktywne zadania,
- `CHANGELOG.md` — `[Unreleased]` oraz wpis bieżącej wersji,
- `VERSION` — pojedyncza wartość SemVer,
- `AGENTS.md` — wskazówki dla agentów i LLM,
- `PROJECT_NOTES.md` — robocze przemyślenia człowieka,
- `DECISIONS.md` lub ADR — trwałe decyzje,
- `.github/skills-agent.yml` — maszynowa konfiguracja build/test/release.

Plan bezpiecznego utworzenia brakujących plików:

```bash
skills-agent bootstrap-target /path/to/repository
```

Zapis, bez nadpisywania istniejących plików:

```bash
skills-agent bootstrap-target /path/to/repository --apply
```

Szczegółowa kolejność prac dla `doctor-agent`, `repair-agent`, `validator-agent` i pozostałych repozytoriów znajduje się w `docs/rollout.md`.

## Model bezpieczeństwa

1. Workflow z pull requesta tylko waliduje — nie uruchamia tasków ani nie otrzymuje tokenu organizacyjnego.
2. Harmonogram działa z domyślnej gałęzi i wykonuje tylko taski `ready`.
3. Kod taska jest kopiowany do izolowanego workspace; ścieżki wychodzące poza pakiet i symlinkowane entrypointy są odrzucane.
4. Repair-agent nie może pisać, dopóki task nie ma `mutation_mode: pull-request`, workflow nie otrzyma `apply_changes: true`, a chronione środowisko nie zostanie zatwierdzone.
5. Validator-agent nie współdzieli implementacji naprawy i nie poprawia wyników poprzednich agentów.
6. Sekrety są filtrowane przez allowlistę zmiennych środowiskowych i nie trafiają do artefaktów.

Więcej: `docs/security.md`.

## Cykl TODO / CHANGELOG / VERSION

- `TODO.md` pokazuje tylko aktualne działania.
- Po wykonaniu pozycja jest usuwana z aktywnego TODO i opisywana pod `[Unreleased]` w `CHANGELOG.md`.
- Przy wydaniu `[Unreleased]` staje się sekcją wersji, następnie aktualizowany jest `VERSION` i tworzona jest nowa pusta sekcja `[Unreleased]`.
- Nie zwiększaj wersji tylko dlatego, że LLM zmienił dokumentację; decyzja wersjonowania należy do właściciela wydania.

## Canonical agent Project

Agent orchestration targets organization Project #2 `Agents`. The verified field and option IDs exported from GitHub are versioned in `config/project-2-fields.json`; Project #1 IDs are rejected by tests. Runtime configuration may override `PROJECT_NUMBER`, but its safe default is `2`.

### Cross-branch live E2E

`run-task.yml` accepts `doctor_ref`, `repair_ref`, `validator_ref`, `target_repository`, and `validator_merge_enabled`. All refs default to `main`. `AUTO_MERGE=false` is invariant; the separate merge input permits one explicit Validator merge only after final validation. Write runs require different Repair and Validator App/PAT tokens and reject missing or identical mock/live credentials before agent execution.

## Versioned agent processes

Skills-agent is the source of truth for the registered contracts in `SKILLS/processes/v1`. Repair and Validator consume data-only process definitions for checklist rendering, branch lifecycle, release metadata, and rejection retry. Operational references: `docs/GITHUB_PERMISSIONS.md`, `docs/DELIVERY_STRATEGIES.md`, `docs/BRANCH_LIFECYCLE.md`, `docs/REPAIR_TODO_CONTRACT.md`, and `docs/VALIDATOR_RUNBOOK.md`.
