todo-agent

todo-agent jest centralnym rejestrem pakietów zadań i deterministyczną warstwą orkiestracji dla trzech istniejących wykonawców:

• 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 control plane: przechowuje kontrakty zadań, wybiera zadania gotowe do wykonania, uruchamia etapy w stałej kolejności i waliduje hand-offy JSON. Agenci pozostają osobnymi execution planes z własną logiką domenową.

Najważniejsze właściwości

• jedna, walidowana definicja task.yaml,
• katalog per zadanie i per agent: TODO/<id>/<agent>/...,
• sekwencja doctor → repair → validator,
• 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 (todo-agent tickets),
• opcjonalne monitorowanie procesów na urirun (todo-agent process).

Struktura repozytorium

.
├── TODO/
│   └── 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/todo_agent/          # discovery, walidacja, runner, scaffold i bootstrap
├── 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.

TODO/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)

todo-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 TODO/<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.
• 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 (todo-agent run) pozostaje synchroniczny; warstwa todo-agent process dokłada uruchamianie w tle z monitoringiem.

Instalacja z warstwami opcjonalnymi:

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

Rejestr zadań (planfile):

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

Monitorowanie procesów (urirun):

todo-agent process launch . 0001_org-repo-audit --wait   # uruchom jako proces URI
todo-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+.

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

Walidacja i discovery:

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

Test zadania audytowego bez połączenia z GitHubem:

GITHUB_ORG=example-org \
TODO_AGENT_AUDIT_FIXTURE="$PWD/TODO/0001_org-repo-audit/doctor-agent/input/sample-organization.json" \
todo-agent run . 0001_org-repo-audit

Wynik pojawi się w .todo-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:

todo-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:

todo-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 todo-agent-apply z wymaganymi reviewerami dla tasków pull-request.

Wbudowany GITHUB_TOKEN pozostaje wystarczający dla samego repo todo-agent. Odczyt lub zapis w innych repozytoriach wykorzystuje token instalacyjny GitHub App. Minimalne uprawnienia są opisane w docs/github-app.md.

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/todo-agent.yml — maszynowa konfiguracja build/test/release.

Plan bezpiecznego utworzenia brakujących plików:

todo-agent bootstrap-target /path/to/repository

Zapis, bez nadpisywania istniejących plików:

todo-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.