Code Generations Manager

Appearance

Plan-to-Team Webhook Flow ​

Przegląd ​

Ten dokument opisuje przepływ, w którym:

  1. Faza Plan - Pierwsza sesja AI wykonuje /plugin-codegen:plan i generuje task_plan.md
  2. Webhook - Helper send_plan_webhook.sh wysyła dane planu do n8n
  3. Faza Team - n8n automatycznie tworzy nowego taska z pełnym Team workflow

Architektura ​

┌─────────────────────────────────────────────────────────────┐
│  TASK 1: Plan Phase                                         │
│  ┌────────────┐   ┌────────────┐   ┌──────────────────┐    │
│  │   START    │──▶│    Plan    │──▶│  END: Webhook    │    │
│  │ init_workspace│  │/plugin-codegen:│  │send_plan_webhook │
│  │             │   │    plan    │   │                  │    │
│  └────────────┘   └────────────┘   └──────────────────┘    │
│                                              │               │
└──────────────────────────────────────────────│───────────────┘
                                               │
                                               ▼
                                    ┌─────────────────────┐
                                    │     N8N Webhook     │
                                    │                     │
                                    │ • Receives plan data│
                                    │ • Creates new task  │
                                    │ • Triggers Team     │
                                    └─────────────────────┘
                                               │
                                               ▼
┌─────────────────────────────────────────────│───────────────┐
│  TASK 2: Team Phase (automatically created) │               │
│  ┌────────────┐   ┌────────────┐   ┌──────────────────┐    │
│  │   START    │──▶│ P0-P3 Work │──▶│  END: Finalize   │    │
│  │ setup_team │   │  Subtasks  │   │  persist_git     │    │
│  │            │   │            │   │  github_push_mr  │    │
│  └────────────┘   └────────────┘   └──────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Konfiguracja ​

1. Helper Script ​

Helper send_plan_webhook.sh znajduje się w:

  • /docker/sembot_frontend/files/helpers/send_plan_webhook.sh
  • /docker/sembot_backend/files/helpers/send_plan_webhook.sh
  • /docker/sembot_qa/files/helpers/send_plan_webhook.sh
  • /docker/sembot_go/files/helpers/send_plan_webhook.sh

2. Usage ​

bash
bash /workspace/files/helpers/send_plan_webhook.sh <WEBHOOK_URL>

Parametry:

  • WEBHOOK_URL - Pełny URL webhooka n8n (POST)

Przykład:

bash
bash /workspace/files/helpers/send_plan_webhook.sh "https://n8n.example.com/webhook/plan-to-team"

3. task.json Configuration ​

Przykładowa konfiguracja task.json znajduje się w:

.doc/examples/task.json.plan-webhook-example.json

Struktura start_commands:

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 $TASK_DIR/task.md",
        "dependencies": ["init_workspace"]
      },
      {
        "id": "extract_session",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/extract_session_claude.sh plan_task /task",
        "dependencies": ["plan_task"]
      },
      {
        "id": "copy_plan",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/copy_file.sh plan_task /task task_plan.md",
        "dependencies": ["extract_session"]
      },
      {
        "id": "send_webhook",
        "catalog": "END",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/send_plan_webhook.sh https://n8n.example.com/webhook/plan-to-team",
        "dependencies": ["copy_plan"]
      }
    ]
  }
}

Webhook Payload ​

Helper wysyła następujący JSON payload do n8n:

json
{
  "event": "plan_completed",
  "timestamp": "2026-01-14T12:00:00Z",
  "task": {
    "task_id": "DEV-123",
    "title": "Task title",
    "description": "Task description",
    "issue_url": "https://github.com/org/repo/issues/123",
    "worker_type": "sembot_frontend"
  },
  "ai": {
    "provider": "claude",
    "model": "claude-sonnet-4-5-20250929",
    "session_id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "plan": {
    "exists": true,
    "content": "# Task Plan\n\n..."
  },
  "task_md": {
    "content": "# Task Description\n\n..."
  },
  "repositories": [
    {
      "folder": "repo-name",
      "git_url": "git@github.com:org/repo.git",
      "target_branch": "master",
      "working_branch": "claude/DEV-123"
    }
  ],
  "actions_requested": {
    "create_team_task": true,
    "use_existing_session": true
  },
  "metadata": {
    "source": "code-generations_manager",
    "workflow": "plan-to-team",
    "phase": "plan_completed"
  }
}

N8N Workflow ​

N8N workflow powinien:

  1. Otrzymać webhook z danymi planu
  2. Stworzyć nowy task w tasks/in_queue/{TASK_ID}/:
    • Skopiować task.json z payload
    • Skopiować task.md z payload
    • Dodać task_plan.md z payload
    • Opcjonalnie: wykorzystać session_id do kontynuacji sesji
  3. Wyzwolić orchestrator_team.yaml dla nowego taska

Przykładowy N8N Node (JSON) ​

json
{
  "name": "Create Team Task",
  "type": "n8n-nodes-base.executeCommand",
  "parameters": {
    "command": "=mkdir -p /path/to/tasks/in_queue/{{ $json.task.task_id }} && echo '{{ $json }}' > /path/to/tasks/in_queue/{{ $json.task.task_id }}/webhook_data.json"
  }
}

Artefakty ​

Helper tworzy następujące artefakty w /task/.spec/webhooks/:

  • plan_webhook_payload_{timestamp}.json - Wysłany payload
  • plan_webhook_response_{timestamp}.json - Odpowiedź z n8n

Error Handling ​

Helper zwraca:

  • Exit code 0 - sukces (HTTP 200, 201, 204)
  • Exit code 1 - błąd (brak parametrów, błąd HTTP, itp.)

Przykładowy Output ​

📤 Wysyłanie danych planu do webhooka...
   Webhook URL: https://n8n.example.com/webhook/plan-to-team
   Task plan exists: true

📋 Task ID: DEV-123
📝 Title: Example Task
🔗 Issue: https://github.com/org/repo/issues/123
🤖 AI: claude (claude-sonnet-4-5-20250929)
🔐 Session ID: 01234567-89ab-cdef-0123-456789abcdef

💾 Payload zapisany: /task/.spec/webhooks/plan_webhook_payload_1705233600.json

📡 Wysyłanie do: https://n8n.example.com/webhook/plan-to-team
✅ Webhook wykonany pomyślnie!

═══════════════════════════════════════════════════════════
    ✅ PLAN COMPLETED - SENT TO WEBHOOK
═══════════════════════════════════════════════════════════

📋 Task ID: DEV-123
📝 Title: Example Task
📊 Plan exists: true
✅ Status: WEBHOOK SENT

📤 AKCJE WYKONANE:
   • Wysłano plan do n8n webhook
   • n8n utworzy nowego taska z Team workflow
   • Session ID przekazany: 01234567-89ab-cdef-0123-456789abcdef

📁 ARTEFAKTY:
   • /task/.spec/webhooks/plan_webhook_payload_1705233600.json
   • /task/.spec/webhooks/plan_webhook_response_1705233600.json

📡 RESPONSE:
{
  "success": true,
  "task_id": "DEV-123-TEAM",
  "message": "Team task created successfully"
}

═══════════════════════════════════════════════════════════

Zalety tego rozwiązania ​

  1. Separacja faz - Plan i Team są osobnymi taskami
  2. Elastyczność - n8n może dodać własną logikę przed utworzeniem Team taska
  3. Session tracking - Session ID jest przekazywany do drugiej fazy
  4. Audyt - Wszystkie dane są zapisywane w artefaktach
  5. Error handling - Retry logic i HTTP status checking

Use Cases ​

1. Podstawowy Plan-to-Team ​

Plan → Webhook → Team

2. Plan z approval ​

Plan → Webhook → N8N Approval → Team

3. Multi-stage workflow ​

Plan → Webhook → N8N Pre-process → Team → Webhook → N8N Post-process

4. Conditional routing ​

Plan → Webhook → N8N Decision Logic → [Team A | Team B | Skip]

Troubleshooting ​

Webhook nie działa ​

  1. Sprawdź URL webhooka
  2. Sprawdź HTTP status w artefaktach
  3. Sprawdź logi n8n
  4. Sprawdź czy payload jest poprawny JSON

Task plan nie istnieje ​

  1. Sprawdź czy plan_task się wykonał
  2. Sprawdź czy copy_plan skopiował task_plan.md
  3. Sprawdź logi subtaska plan_task

N8N nie tworzy taska ​

  1. Sprawdź response z webhooka
  2. Sprawdź workflow w n8n
  3. Sprawdź czy ścieżki są poprawne

See Also ​

  • Task Configuration
  • Orchestrator Team DAG: dags/orchestrator_team.yaml
  • Send Webhook Helper: dags/scripts/send_webhook.sh