Code Generations Manager

Appearance

Konfiguracja Zadania (task.json) ​

Przegląd ​

Plik task.json to główny plik konfiguracyjny każdego zadania. Zawiera wszystkie informacje niezbędne do wykonania zadania przez system.

Pełna Struktura ​

json
{
  "task_id": "example_task_2_team_mode",
  "title": "Add User Authentication System",
  "issue": {
    "id": "DEV-789",
    "author_id": "product.owner",
    "assignee_id": "tech.lead",
    "assignee_github_id": "techleadgithub",
    "url": "https://jira.example.com/browse/DEV-789"
  },
  "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/example_task_2_team_mode",
      "merge_request_id": null,
      "merge_request_url": null,
      "merge_request_create_as_draft": false
    }
  ],
  "ai": {
    "provider": "claude",
    "model": "claude-sonnet-4",
    "mode": "read_only",
    "start_commands": [
      {
        "id": "init_workspace",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/init_workspace.sh",
        "dependencies": []
      },
      {
        "id": "backup_task",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/backup_task_md.sh",
        "dependencies": ["init_workspace"]
      },
      {
        "id": "plan_task",
        "catalog": "START",
        "executor": "claude",
        "command": "/plugin-codegen:plan",
        "dependencies": ["backup_task"]
      },
      {
        "id": "move_task_spec",
        "catalog": "END",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/move_task_md.sh",
        "dependencies": ["plan_task"]
      },
      {
        "id": "persist_git",
        "catalog": "END",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/persist_git_changes.sh",
        "dependencies": ["move_task_spec"]
      },
      {
        "id": "github_push_mr",
        "catalog": "END",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/github_push_mr.sh",
        "dependencies": ["persist_git"]
      }
    ],
    "approval_request_wait_minutes": 10,
    "sessions": {
      "claude": null,
      "codex": null,
      "gemini": null
    }
  },
  "monitoring": {
    "status_update_interval_minutes": 5,
    "status_ai_provider": "claude",
    "status_ai_model": "haiku",
    "last_status_update": null
  },
  "worker_tag": null,
  "parent_task_id": null,
  "reopened_count": 0,
  "reopened_at": null,
  "created_at": "2025-12-18T10:00:00Z",
  "updated_at": "2025-12-18T10:00:00Z",
  "started_at": null,
  "completed_at": null,
  "status": "todo"
}

Szczegółowy Opis Pól ​

Podstawowe Informacje ​

task_id (string, required) ​

Unikalny identyfikator zadania.

Format: Dowolny string (zazwyczaj ID z systemu ticketów) Przykłady: "DEV-7315", "FEAT-123", "BUG-456"

json
{
  "task_id": "DEV-7315"
}

title (string, required) ​

Krótki, opisowy tytuł zadania.

Długość: 5-100 znaków Przykład: "Add User Authentication System"

json
{
  "title": "Settings UI Unification"
}

Sekcja: issue ​

Informacje o tickecie/issue z systemu zarządzania projektami.

issue.id (string, required) ​

ID ticketu w systemie zewnętrznym (Jira, Linear, etc.)

json
{
  "issue": {
    "id": "DEV-789"
  }
}

issue.author_id (string, required) ​

ID autora zadania (osoby która stworzyła ticket).

Format: Zazwyczaj email lub username Przykład: "product.owner", "[email protected]"

json
{
  "issue": {
    "author_id": "product.owner"
  }
}

issue.assignee_id (string, required) ​

ID osoby przypisanej do wykonania zadania.

json
{
  "issue": {
    "assignee_id": "tech.lead"
  }
}

issue.assignee_github_id (string, required) ​

GitHub username osoby która ma być przypisana do PR/MR.

Ważne: Musi być poprawnym GitHub username (bez @)

json
{
  "issue": {
    "assignee_github_id": "techleadgithub"
  }
}

issue.url (string, optional) ​

Link do ticketu w systemie zewnętrznym.

json
{
  "issue": {
    "url": "https://jira.example.com/browse/DEV-789"
  }
}

Sekcja: worker ​

Konfiguracja workera (Docker environment).

worker.type (string, required) ​

Typ kolejki/workera.

Wartości: "sembot_frontend", "sembot_backend", "sembot_qa"

Ważne: Określa który Docker worker zostanie użyty i do której kolejki trafi zadanie.

json
{
  "worker": {
    "type": "sembot_frontend"
  }
}

worker.docker_path (string, required) ​

Ścieżka do katalogu z docker-compose.yml.

Format: Relatywna ścieżka od PROJECT_ROOT

json
{
  "worker": {
    "docker_path": "docker/docker/sembot_frontend"
  }
}

worker.docker_finish_stop (boolean, optional, default: false) ​

Czy zatrzymać i usunąć Docker po zakończeniu zadania.

Wartości:

  • true - Zatrzymaj i usuń kontenery po zakończeniu
  • false - Zostaw kontenery uruchomione (szybsze kolejne uruchomienia)
json
{
  "worker": {
    "docker_finish_stop": false
  }
}

Sekcja: repositories ​

Lista repozytoriów Git do sklonowania i pracy.

Typ: Array of objects Może być wiele repozytoriów: Tak

repositories[].folder (string, required) ​

Nazwa folderu w workspace gdzie zostanie sklonowane repo.

Ścieżka: workspace/{folder}

json
{
  "repositories": [
    {
      "folder": "sembot-angular"
    }
  ]
}

repositories[].git_url (string, required) ​

URL Git do klonowania (SSH lub HTTPS).

Preferowane: SSH (wymaga SSH_PRIVATE_KEY secret)

json
{
  "repositories": [
    {
      "git_url": "[email protected]:sembot-io/sembot-angular.git"
    }
  ]
}

repositories[].target_branch (string, required) ​

Główny branch (base branch dla PR/MR).

Przykłady: "master", "main", "develop"

json
{
  "repositories": [
    {
      "target_branch": "master"
    }
  ]
}

repositories[].working_branch (string, required) ​

Branch na którym wykonywane są zmiany.

Format: Zazwyczaj feature/{task_id} lub fix/{task_id}

Ważne: Branch zostanie utworzony jeśli nie istnieje

json
{
  "repositories": [
    {
      "working_branch": "feature/DEV-7315"
    }
  ]
}

repositories[].merge_request_id (string|null, auto-filled) ​

ID utworzonego PR/MR.

Auto-filled: Wypełniane automatycznie przez github_push_mr.sh

json
{
  "repositories": [
    {
      "merge_request_id": "123"
    }
  ]
}

repositories[].merge_request_url (string|null, auto-filled) ​

URL do utworzonego PR/MR.

Auto-filled: Wypełniane automatycznie przez github_push_mr.sh

json
{
  "repositories": [
    {
      "merge_request_url": "https://github.com/sembot-io/sembot-angular/pull/123"
    }
  ]
}

repositories[].merge_request_create_as_draft (boolean, optional, default: false) ​

Czy utworzyć PR/MR jako draft.

Wartości:

  • true - Draft PR (wymaga ręcznej zmiany na "Ready for review")
  • false - Normalny PR (od razu ready for review)
json
{
  "repositories": [
    {
      "merge_request_create_as_draft": true
    }
  ]
}

Sekcja: ai ​

Konfiguracja AI providera i komend.

ai.provider (string, required) ​

Domyślny provider AI dla zadania.

Wartości: "claude", "codex", "gemini", "mock"

json
{
  "ai": {
    "provider": "claude"
  }
}

ai.model (string, required) ​

Domyślny model AI.

Przykłady:

  • Claude: "claude-sonnet-4", "claude-opus-4"
  • Codex: "gpt-4", "gpt-5.1-codex-max"
  • Gemini: "gemini-pro"
json
{
  "ai": {
    "model": "claude-sonnet-4"
  }
}

ai.mode (string, optional) ​

Tryb działania AI - określa czy AI może modyfikować kod.

Wartości:

  • Brak (default) - Normalny tryb, AI może modyfikować kod i tworzyć commity
  • "read_only" - Tryb read-only, AI może tylko analizować kod bez wprowadzania zmian

Zachowanie w trybie read_only:

  • AI nie tworzy commitów
  • AI nie pushuje zmian
  • AI nie tworzy Pull Requestów
  • Pomija wszystkie operacje git w execute_subtask.sh
  • Używane głównie dla worker type "qa" (Q&A system)

Użycie: Idealny dla zadań typu Q&A, gdzie AI ma odpowiadać na pytania o kod bez wprowadzania zmian.

json
{
  "ai": {
    "provider": "codex",
    "model": "gpt-5.1-codex-max",
    "mode": "read_only"
  }
}

Przykład - Worker Q&A:

json
{
  "worker": {
    "type": "qa",
    "docker_path": "qa"
  },
  "ai": {
    "provider": "codex",
    "model": "gpt-5.1-codex-max",
    "mode": "read_only",
    "start_commands": [
      {
        "id": "init_workspace",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/init_workspace.sh",
        "dependencies": []
      },
      {
        "id": "qa_answer",
        "catalog": "START",
        "executor": "codex",
        "command": "/qa_answer",
        "dependencies": ["init_workspace"]
      }
    ]
  }
}

ai.start_commands (array, required) ​

Tablica komend do wykonania w fazach START i END.

Struktura komendy:

json
{
  "id": "unique_command_id",
  "catalog": "START" | "END",
  "executor": "bash" | "claude" | "codex" | "gemini",
  "command": "command to execute",
  "dependencies": ["array", "of", "command_ids"]
}

Przykład pełnej konfiguracji:

json
{
  "ai": {
    "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"]
      },
      {
        "id": "finalize",
        "catalog": "END",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/move_task_md.sh",
        "dependencies": []
      }
    ]
  }
}

Pola obiektu komendy:

  • id (string, required) - Unikalny identyfikator dla dependencies
  • catalog (string, required) - "START" lub "END"
  • executor (string, required) - Który executor użyć
    • "bash" - Bezpośrednia komenda bash
    • "claude" - Claude Code slash command
    • "codex" - Codex command
    • "gemini" - Gemini CLI command
  • command (string, required) - Komenda do wykonania
  • dependencies (array, required) - Lista ID komend które muszą się wykonać wcześniej

ai.approval_request_wait_minutes (number, optional, default: 10) ​

Czas oczekiwania na odpowiedź użytkownika (w minutach) przy approval requestach.

Zachowanie po timeout:

  • Jeśli możliwe kontynuowanie → kontynuuje + notyfikacja
  • Jeśli nie → task failed
json
{
  "ai": {
    "approval_request_wait_minutes": 10
  }
}

ai.sessions (object, auto-managed) ​

Session IDs dla różnych AI providerów.

Auto-managed: System automatycznie zarządza sesjami Wartości: null lub string (session ID)

json
{
  "ai": {
    "sessions": {
      "claude": "session_abc123def456",
      "codex": null,
      "gemini": null
    }
  }
}

Sekcja: monitoring ​

Konfiguracja monitoringu i statusów.

monitoring.status_update_interval_minutes (number, optional, default: 5) ​

Interwał między automatycznymi statusami (w minutach).

Zakres: 1-60 minut Domyślnie: 5 minut (z .env)

json
{
  "monitoring": {
    "status_update_interval_minutes": 5
  }
}

monitoring.status_ai_provider (string, optional, default: ai.provider) ​

Provider AI do generowania statusów.

Zazwyczaj: Lekki model (Haiku) dla oszczędności

json
{
  "monitoring": {
    "status_ai_provider": "claude"
  }
}

monitoring.status_ai_model (string, optional, default: "haiku") ​

Model AI do generowania statusów.

Rekomendacja: Użyj szybkiego, lekkiego modelu

json
{
  "monitoring": {
    "status_ai_model": "haiku"
  }
}

monitoring.last_status_update (string|null, auto-filled) ​

Timestamp ostatniego wysłanego statusu.

Auto-filled: Aktualizowane przez task_status_monitor.sh Format: ISO 8601

json
{
  "monitoring": {
    "last_status_update": "2025-12-31T10:30:00Z"
  }
}

Metadata i Status ​

worker_tag (string|null, auto-filled) ​

Tag kolejki przypisanej przez watchdog.

Auto-filled: Ustawiane przez watchdog podczas load balancingu Przykłady: "sembot_frontend_1", "sembot_backend_1"

json
{
  "worker_tag": "sembot_frontend_2"
}

parent_task_id (string|null, optional) ​

ID parent taska (dla follow-up tasków).

Użycie: Follow-up taski (DEV-7315-FIX-1 → parent: DEV-7315)

json
{
  "parent_task_id": "DEV-7315"
}

reopened_count (number, auto-managed, default: 0) ​

Liczba reopenów taska.

Auto-managed: Inkrementowane przez reopen_task.sh

json
{
  "reopened_count": 2
}

reopened_at (string|null, auto-filled) ​

Timestamp ostatniego reopena.

Auto-filled: Ustawiane przez reopen_task.sh Format: ISO 8601

json
{
  "reopened_at": "2025-12-31T14:30:00Z"
}

created_at (string, required) ​

Timestamp utworzenia zadania.

Format: ISO 8601

json
{
  "created_at": "2025-12-18T10:00:00Z"
}

updated_at (string, auto-managed) ​

Timestamp ostatniej aktualizacji.

Auto-managed: Aktualizowane przy każdej zmianie task.json

json
{
  "updated_at": "2025-12-18T10:30:00Z"
}

started_at (string|null, auto-filled) ​

Timestamp rozpoczęcia wykonywania zadania.

Auto-filled: Ustawiane przez orchestrator przy pierwszym subtasku

json
{
  "started_at": "2025-12-18T10:15:00Z"
}

completed_at (string|null, auto-filled) ​

Timestamp zakończenia zadania.

Auto-filled: Ustawiane przy przeniesieniu do done/failed

json
{
  "completed_at": "2025-12-18T12:45:00Z"
}

status (string, auto-managed) ​

Aktualny status zadania.

Wartości:

  • "todo" - Zadanie oczekuje
  • "in_progress" - Zadanie w trakcie wykonywania
  • "done" - Zadanie ukończone pomyślnie
  • "failed" - Zadanie zakończone niepowodzeniem
json
{
  "status": "in_progress"
}

Subtask task.json ​

Subtaski mają uproszczoną strukturę:

json
{
  "task_id": "frontend_abc123",
  "priority": "P1",
  "title": "Implement Settings Menu Component",
  "why": "User needs to access settings through a visible menu with icons",
  "ai": {
    "provider": "claude",
    "model": "claude-sonnet-4",
    "start_command": "/frontend /task",
    "sessions": {
      "claude": null,
      "codex": null,
      "gemini": null
    }
  },
  "dependencies": ["init_workspace", "plan_task"],
  "created_at": "2025-12-18T10:20:00Z",
  "updated_at": "2025-12-18T10:20:00Z",
  "started_at": null,
  "completed_at": null
}

Pola specyficzne dla subtasków ​

priority (string, required) ​

Poziom priorytetu subtaska.

Wartości: "START", "P0", "P1", "P2", "P3", "END"

json
{
  "priority": "P1"
}

why (string, required) ​

Wyjaśnienie dlaczego subtask został utworzony.

Cel: Pomaga AI zrozumieć kontekst i cel zadania

json
{
  "why": "User needs to access settings through a visible menu with icons"
}

ai.start_command (string, required) ​

Pierwsza komenda do uruchomienia w subtasku.

Format: Slash command z path do subtaska

json
{
  "ai": {
    "start_command": "/frontend /task"
  }
}

dependencies (array, optional) ​

Lista dependency IDs (wspiera wildcards).

json
{
  "dependencies": ["init_workspace", "frontend_*", "test_unit_*"]
}

Przykłady Konfiguracji ​

Przykład 1: Prosty Frontend Task ​

json
{
  "task_id": "DEV-7315",
  "title": "Settings UI Unification",
  "issue": {
    "id": "DEV-7315",
    "author_id": "product.owner",
    "assignee_id": "frontend.dev",
    "assignee_github_id": "frontenddev"
  },
  "worker": {
    "type": "sembot_frontend",
    "docker_path": "docker/docker/sembot_frontend"
  },
  "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",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/init_workspace.sh",
        "dependencies": []
      },
      {
        "id": "plan",
        "catalog": "START",
        "executor": "claude",
        "command": "/plugin-codegen:plan",
        "dependencies": ["init"]
      }
    ]
  }
}

Przykład 2: Multi-Repo Backend Task ​

json
{
  "task_id": "API-456",
  "title": "New Payment Gateway Integration",
  "issue": {
    "id": "API-456",
    "assignee_github_id": "backenddev"
  },
  "worker": {
    "type": "sembot_backend",
    "docker_path": "docker/docker/sembot_backend"
  },
  "repositories": [
    {
      "folder": "backend-api",
      "git_url": "[email protected]:sembot-io/backend.git",
      "target_branch": "develop",
      "working_branch": "feature/API-456-payment"
    },
    {
      "folder": "shared-models",
      "git_url": "[email protected]:sembot-io/models.git",
      "target_branch": "main",
      "working_branch": "feature/API-456-payment-models"
    }
  ],
  "ai": {
    "provider": "claude",
    "model": "claude-sonnet-4"
  }
}

Przykład 3: Follow-up Task ​

json
{
  "task_id": "DEV-7315-FIX-1",
  "title": "Fix issues from DEV-7315 verification",
  "parent_task_id": "DEV-7315",
  "issue": {
    "id": "DEV-7315-FIX-1",
    "author_id": "orchestrator",
    "assignee_id": "frontend.dev",
    "assignee_github_id": "frontenddev"
  },
  "worker": {
    "type": "sembot_frontend",
    "docker_path": "docker/docker/sembot_frontend"
  },
  "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"
  }
}

Walidacja ​

Wymagane Pola (Minimum) ​

json
{
  "task_id": "required",
  "title": "required",
  "issue": {
    "id": "required",
    "assignee_github_id": "required"
  },
  "worker": {
    "type": "required",
    "docker_path": "required"
  },
  "repositories": [
    {
      "folder": "required",
      "git_url": "required",
      "target_branch": "required",
      "working_branch": "required"
    }
  ],
  "ai": {
    "provider": "required",
    "model": "required"
  }
}

Common Mistakes ​

❌ Błąd: worker.type nie pasuje do żadnej kolejki

json
{
  "worker": {
    "type": "invalid_worker"
  }
}

❌ Błąd: Brak start_commands dla orkiestry team

json
{
  "ai": {
    "provider": "claude",
    "model": "claude-sonnet-4"
    // Brakuje start_commands!
  }
}

❌ Błąd: Circular dependency w start_commands

json
{
  "ai": {
    "start_commands": [
      {"id": "a", "dependencies": ["b"]},
      {"id": "b", "dependencies": ["a"]}
    ]
  }
}

Template ​

Użyj tego template do tworzenia nowych zadań:

bash
cp templates/task.json tasks/todo/YOUR-TASK-ID/task.json

Template path: templates/task.json