System Zarządzania Zadaniami AI

Kompletna dokumentacja implementacji systemu automatycznego zarządzania zadaniami programistycznymi przy użyciu AI

📋 Spis Treści

1. Przegląd Systemu
2. Architektura
3. Przepływ Zadania
4. Konfiguracja
5. Pluginy i Komendy
6. Monitoring i Weryfikacja

---

Przegląd Systemu

System zarządzania zadaniami AI to zaawansowana platforma automatyzująca proces development wykorzystując orkiestrę AI agents. System symuluje działanie realnego zespołu produktowego - od discovery, przez implementację, testy, aż po weryfikację i deploy.

Główne Komponenty

┌─────────────────────────────────────────────────────────┐
│                    UŻYTKOWNIK                           │
│              (dodaje zadanie do todo/)                  │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                  WATCHDOG (DAGU)                        │
│    • Monitoring katalogów todo/                         │
│    • Load balancing między kolejkami                    │
│    • Przekazywanie zadań do orchestratora              │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              ORCHESTRATOR TEAM                          │
│    • Uruchamia Docker workers                           │
│    • Zarządza fazami: START → P0-P3 → END              │
│    • Dependency resolution                              │
│    • Session management                                 │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                 AI WORKERS                              │
│    • Frontend (Angular)                                 │
│    • Backend (Laravel)                                  │
│    • QA/Test (Playwright)                              │
│    • Reviewer (Product/Tech)                           │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│           WERYFIKACJA I FINALIZACJA                     │
│    • Visual Verification (screenshots)                  │
│    • Build verification                                 │
│    • Final task verification                            │
│    • GitHub PR/MR creation                              │
└─────────────────────────────────────────────────────────┘

Kluczowe Cechy

• 🔄 Orkiestra Team: Symulacja realnego zespołu (PO, Frontend, Backend, QA, Reviewer)
• 📊 Priorytety: Zarządzanie zadaniami według poziomów START → P0 → P1 → P2 → P3 → END
• 🔁 Dependency Graph: Automatyczne rozwiązywanie zależności między subtaskami
• 🔄 Retry Mechanism: Automatyczne ponowne próby dla nieudanych subtasków
• ⚖️ Load Balancing: Inteligentny podział zadań między dostępne kolejki
• 📸 Visual Verification: Automatyczne screenshoty i weryfikacja wizualna
• 💬 Integracja Mattermost: Dwukierunkowa komunikacja z zespołem
• 🔍 Monitoring: Okresowe statusy i health checks

---

Architektura

Struktura Katalogów

/manager/
├── tasks/                          # Główny katalog zadań
│   ├── todo/                       # Zadania oczekujące
│   │   └── {TASK_ID}/
│   │       ├── task.json           # Konfiguracja zadania
│   │       └── task.md             # Instrukcje dla AI
│   ├── in_progress/                # Zadania w trakcie
│   │   └── {TASK_ID}/
│   │       ├── task.json
│   │       ├── task.md
│   │       ├── subtasks/           # Podzadania
│   │       │   ├── START/
│   │       │   ├── P0/, P1/, P2/, P3/
│   │       │   └── END/
│   │       ├── artifacts/          # Artefakty
│   │       │   └── logs/
│   │       ├── verification/       # Wyniki weryfikacji
│   │       └── interrupts/         # Przerwania użytkownika
│   ├── done/                       # Zadania ukończone
│   ├── failed/                     # Zadania nieudane
│   └── control_commands/           # Komendy kontrolne (reopen/interrupt)
│
├── dags/                           # DAGU workflows
│   ├── watchdog.yaml               # Główny watchdog
│   ├── orchestrator_team.yaml      # Orkiestracja zadań
│   ├── task_status_monitor.yaml   # Monitoring statusów
│   └── scripts/                    # Skrypty pomocnicze
│
├── docker/                         # Konfiguracje Docker
│   └── docker/
│       ├── sembot_frontend/        # Worker Frontend
│       ├── sembot_backend/         # Worker Backend
│       └── sembot_qa/              # Worker QA
│
├── plugins/                        # Pluginy Claude Code
│   ├── plugin-default/             # Główny plugin Sembota
│   ├── plugin-team/                # Komendy ról zespołu
│   └── plugin-orkiestrator/        # Komendy orkiestratora
│
└── workspace/                      # Workspace dla repozytoriów
    └── {REPO_NAME}/                # Sklonowane repo

Technologie

Komponent	Technologia
Orkiestracja	DAGU (DAG scheduler)
AI Providers	Claude Code, Codex, Gemini CLI
Containerization	Docker, Docker Compose
Version Control	Git, GitHub CLI
Testing	Playwright
Monitoring	n8n, Mattermost webhooks
Frontend	Angular + Storybook
Backend	Laravel

---

Przepływ Zadania

1. Dodawanie Zadania

Użytkownik tworzy katalog w tasks/todo/{TASK_ID}/ z dwoma plikami:

task.json - Konfiguracja zadania

{
  "task_id": "DEV-7315",
  "title": "Settings UI Unification",
  "issue": {
    "id": "DEV-7315",
    "author_id": "product.owner",
    "assignee_id": "tech.lead",
    "assignee_github_id": "techleadgithub",
    "url": "https://jira.example.com/browse/DEV-7315"
  },
  "worker": {
    "type": "sembot_frontend",
    "docker_path": "docker/docker/sembot_frontend",
    "docker_finish_stop": false
  },
  "repositories": [
    {
      "folder": "sembot-angular",
      "git_url": "[email protected]:sembot-io/sembot-angular.git",
      "target_branch": "master",
      "working_branch": "feature/DEV-7315"
    }
  ],
  "ai": {
    "provider": "claude",
    "model": "claude-sonnet-4",
    "start_commands": [
      {
        "id": "init_workspace",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/init_workspace.sh",
        "dependencies": []
      },
      {
        "id": "plan_task",
        "catalog": "START",
        "executor": "claude",
        "command": "/plugin-codegen:plan",
        "dependencies": ["init_workspace"]
      }
    ]
  },
  "monitoring": {
    "status_update_interval_minutes": 5,
    "status_ai_provider": "claude",
    "status_ai_model": "haiku"
  }
}

task.md - Instrukcje dla AI

# Settings UI Unification

## Cel
Zunifikować UI menu ustawień - wszystkie ikony mają być widoczne.

## Wymagania
1. Wszystkie ikony w menu ustawień muszą być widoczne
2. Zachować istniejący design system
3. Responsive design (desktop + mobile)
4. Dodać testy Playwright

## Acceptance Criteria
- [ ] Ikony widoczne na desktop
- [ ] Ikony widoczne na mobile
- [ ] Testy przechodzą
- [ ] Build bez błędów

2. Watchdog - Routing i Load Balancing

# Watchdog (DAGU) skanuje tasks/todo/ co 30 sekund

1. Pobiera najstarsze zadanie
2. Odczytuje worker.type (np. "sembot_frontend")
3. Sprawdza dostępne kolejki:
   - sembot_frontend_1 (obciążenie: 2 taski)
   - sembot_frontend_2 (obciążenie: 1 task)
4. Wybiera kolejkę z najmniejszym obciążeniem → sembot_frontend_2
5. Zapisuje worker_tag do task.json
6. Przenosi todo/DEV-7315/ → in_progress/DEV-7315/
7. Przekazuje zadanie do orchestrator_team

3. Orchestrator Team - Wykonanie

PHASE START
├─ init_workspace (bash)
│  └─ Klonuje repo sembot-angular
│  └─ Checkout feature/DEV-7315
│
└─ plan_task (claude)
   └─ Analizuje task.md
   └─ Tworzy subtaski w P0-P3

PHASE P0 (Critic - wykonuje się pierwszy)
└─ critic_a1b2c3 (claude)
   └─ Weryfikuje plan
   └─ Może zablokować lub zaaprobować

PHASE P1 (High Priority)
├─ frontend_d4e5f6 (claude)
│  └─ Implementuje zmiany w komponencie
│
└─ test_g7h8i9 (claude)
   └─ Pisze testy Playwright
   └─ Jeśli failuje → retry (attempt 2/2)

PHASE P2 (Medium Priority)
└─ reviewer_product_j0k1l2 (claude)
   └─ Weryfikuje zgodność z wymaganiami
   └─ Może utworzyć follow-up taski jeśli błędy

PHASE P3 (Low Priority)
└─ reviewer_tech_m3n4o5 (claude)
   └─ Code review
   └─ Weryfikacja standardów

PHASE END
├─ move_task_spec (bash)
│  └─ Przenosi artefakty
│
├─ persist_git (bash)
│  └─ Commit zmian
│  └─ Git diff
│
└─ github_push_mr (bash)
   └─ Push na remote
   └─ Utworzenie PR/MR
   └─ Przypisanie assignee

FINALIZATION
├─ visual_verification (claude)
│  └─ Screenshoty (desktop/mobile/tablet)
│  └─ Build verification
│  └─ Startup verification
│
└─ final_task_verification (bash)
   └─ Weryfikacja wymagań
   └─ Raport końcowy
   └─ Decision: READY FOR REVIEW / REQUIRES FIXES

4. Weryfikacja i Follow-up

Jeśli final_task_verification = REQUIRES FIXES:

1. analyze_verification_results (claude)
   └─ Analizuje raporty
   └─ Tworzy listę problemów

2. create_followup_task.sh
   └─ Tworzy: DEV-7315-FIX-1 w tasks/todo/
   └─ Ten sam branch i repo
   └─ task.md z listą błędów + link do evidence

3. Watchdog automatycznie podejmuje follow-up task

Maksymalnie 10 follow-upów (infinite loop prevention)

---

Konfiguracja

DAGU Config (dagu_config.yaml)

queues:
  enabled: true
  config:
    - name: "sembot_frontend_1"
      maxConcurrency: 1
    - name: "sembot_frontend_2"
      maxConcurrency: 1
    - name: "sembot_backend_1"
      maxConcurrency: 1
    - name: "sembot_qa_1"
      maxConcurrency: 1

Environment Variables (.env)

# Paths
TASKS_DIR=$PROJECT_ROOT/tasks
DAGS_DIR=$PROJECT_ROOT/dags
DOCKER_DIR=$PROJECT_ROOT/docker
PLUGINS_DIR=$PROJECT_ROOT/plugins
WORKSPACE_DIR=$PROJECT_ROOT/workspace

# AI Configuration
AI_PROVIDER=claude
AI_MODEL=claude-sonnet-4

# Monitoring
STATUS_UPDATE_INTERVAL_MINUTES=5
STATUS_AI_PROVIDER=claude
STATUS_AI_MODEL=haiku

# Webhooks
N8N_WEBHOOK_URL=https://n8n.sembot.ovh/webhook/

# GitHub
GH_TOKEN=${secrets.GH_TOKEN}

Docker Compose (example: sembot_frontend)

version: '3.8'

services:
  worker:
    build:
      context: ./build
      dockerfile: Dockerfile
    volumes:
      - ${WORKSPACE_DIR}:/workspace
      - ${PLUGINS_DIR}:/workspace/plugins:ro
      - task_spec:/task
    environment:
      - AI_PROVIDER=${AI_PROVIDER}
      - AI_MODEL=${AI_MODEL}
      - CHROME_HOST=chrome
      - CHROME_PORT=9222
    depends_on:
      - chrome

  chrome:
    image: browserless/chrome:latest
    platform: linux/amd64
    environment:
      - MAX_CONCURRENT_SESSIONS=5
      - CONNECTION_TIMEOUT=600000
    ports:
      - "9222:3000"
    shm_size: '2gb'

---

Pluginy i Komendy

Plugin-Team (Workers)

Komendy używane przez AI workers podczas wykonywania subtasków:

Komenda	Rola	Opis
/frontend	Frontend Developer	Implementacja UI (Angular)
/backend	Backend Developer	Implementacja API (Laravel)
/test	QA Engineer	Testy Playwright + API
/reviewer_product	Product Owner	Weryfikacja wymagań biznesowych
/reviewer_tech	Tech Lead	Code review i architektura
/qa	QA Specialist	Kompleksowe testy jakości

Plugin-Orkiestrator (DAGU)

Komendy używane przez orkiestratora do zarządzania workflow:

Komenda	Opis
/status_update	Generowanie statusów zadań
/visual_verification	Weryfikacja wizualna aplikacji
/analyze_verification_results	Analiza raportów weryfikacji

Plugin-Default (Sembot)

Główny plugin z komendami pomocniczymi:

Komenda	Opis
/plugin-codegen:plan	Planowanie zadania
/plugin-codegen:analyze	Analiza codebase

---

Monitoring i Weryfikacja

Okresowe Statusy (Task Status Monitor)

task_status_monitor.yaml (DAGU, co 5 minut)
  ↓
Dla każdego taska w in_progress/:
  1. Sprawdza czy minęło 5 min od ostatniego statusu
  2. Czyta recent logs + current subtask
  3. Generuje status przez AI (Claude Haiku)
  4. Wysyła webhook do n8n → Mattermost
  5. Aktualizuje task.json (last_status_update)

Przykład statusu na Mattermost:

📊 Task DEV-7315: Settings UI Unification
Status: in_progress
Current: P1: frontend_abc123 - Implement Settings Menu

Currently implementing the settings menu component with new
icon visibility logic. Build completed successfully, working
on component integration.

Visual Verification

System automatycznie weryfikuje aplikację po ukończeniu subtasków:

1. Detekcja środowiska (beta vs local backend)
2. npm install + npm run build
3. npm start (dev server)
4. Uruchomienie testów Playwright
5. Screenshoty dla różnych viewportów:
   - Desktop (1920x1080)
   - Mobile (375x812)
   - Tablet (768x1024)
6. Generowanie raportu wizualnego

Struktura dowodów:

verification/
├── screenshots/
│   ├── 01-desktop-dashboard-settings.png
│   ├── 23-mobile-dashboard-settings.png
│   └── 35-tablet-dashboard-settings.png
├── visual_verification_report.md
└── final_verification_report.md

Manual Task Control

System umożliwia programistom ręczną kontrolę zadań przez Mattermost:

Reopen (DONE → TODO)

# User na Mattermost:
"DEV-7315 dodaj dark mode do settings"

# System:
1. Przenosi done/DEV-7315/ → todo/DEV-7315/
2. Appends instrukcje do task.md
3. Zachowuje context (branch, repos)
4. Watchdog automatycznie podejmuje task

Interrupt (IN_PROGRESS)

# User na Mattermost:
"DEV-7315 PILNE: najpierw zweryfikuj czy build działa"

# System:
1. Tworzy interrupts/interrupt_xyz.json
2. Orchestrator wykrywa interrupt
3. Wykonuje według priority:
   - urgent → stop natychmiast
   - high → dokończ current subtask
   - normal → dokończ current priority
4. Kontynuuje normalną pracę

---

Szczegółowe Dokumenty

• Task Configuration - Szczegóły konfiguracji task.json
• Dependency System - System zależności i wildcards
• Sessions and Retry - Session management i automatyczne retry
• Verification System - Visual i final verification
• Monitoring Integration - Integracja z n8n i Mattermost
• Roles and Commands - Wszystkie role i komendy AI
• Manual Control - Reopen, Interrupt i User Commands
• Docker Helpers - Helper scripts i utilities

---

Quick Start

1. Utworzenie zadania

# Utwórz katalog zadania
mkdir -p tasks/todo/DEV-7315

# Skopiuj template
cp templates/task.json tasks/todo/DEV-7315/
cp templates/task.md tasks/todo/DEV-7315/

# Edytuj task.json i task.md zgodnie z wymaganiami

2. Watchdog automatycznie podejmie zadanie

# Sprawdź status
dagu status

# Zobacz logi
tail -f ~/.dagu/logs/watchdog/<date>/watchdog.log

3. Monitoruj wykonanie

# Sprawdź status zadania
cat tasks/in_progress/DEV-7315/task.json | jq '.status'

# Zobacz subtaski
ls -la tasks/in_progress/DEV-7315/subtasks/P1/in_progress/

# Sprawdź logi
tail -f tasks/in_progress/DEV-7315/artifacts/logs/task.log

4. Weryfikacja wyników

# Po zakończeniu sprawdź raporty
cat tasks/done/DEV-7315/verification/final_verification_report.md

# Zobacz screenshoty
open tasks/done/DEV-7315/verification/screenshots/

---

Troubleshooting

Zadanie stuck w in_progress

# Sprawdź logi orchestratora
cat ~/.dagu/logs/orchestrator_team/<date>/orchestrator_team.log

# Sprawdź logi Dockera
docker logs <worker_container>

# Ręcznie przenieś do failed (jeśli konieczne)
mv tasks/in_progress/DEV-7315 tasks/failed/

Follow-up loop (więcej niż 10)

# System automatycznie zatrzyma po 10 follow-upach
# Sprawdź ostatni follow-up
cat tasks/done/DEV-7315-FIX-10/verification/final_verification_report.md

# Manual intervention required - przeanalizuj problemy

Webhook nie działa

# Sprawdź konfigurację
echo $N8N_WEBHOOK_URL

# Test webhooka
curl -X POST $N8N_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"event_type":"test","message":"test webhook"}'

---

Licencja i Kontakt

© 2025 Sembot - System Zarządzania Zadaniami AI

Dla pytań technicznych: [email protected]