Tryb PLAN-TO-TEAM-WEBHOOK - Dwufazowy przepływ z integracją n8n

Przegląd

Tryb PLAN-TO-TEAM-WEBHOOK to dwufazowy proces, który:

Faza PLAN - Generuje szczegółowy plan implementacji w pierwszej sesji AI
Webhook n8n - Wysyła dane planu do zewnętrznego systemu orkiestracji
Faza TEAM - n8n automatycznie tworzy nowy task z pełnym Team workflow

Ten tryb pozwala na:

Separację planowania od implementacji
Integrację z zewnętrznymi systemami (n8n)
Zatwierdzanie planu przed implementacją
Dodanie własnej logiki między fazami (approval, preprocessing)
Tracking sesji AI między fazami

┌─────────────────────────────────────┐
│  TASK 1: Plan Phase                 │
│  ┌────────┐  ┌──────┐  ┌─────────┐ │
│  │ START  │─▶│ PLAN │─▶│   END   │ │
│  │ init   │  │/plan │  │ webhook │ │
│  └────────┘  └──────┘  └─────────┘ │
└───────────────────────┬─────────────┘
                        │
                        ▼
              ┌──────────────────┐
              │   N8N Webhook    │
              │ • Receives plan  │
              │ • Creates task   │
              │ • Triggers Team  │
              └──────────────────┘
                        │
                        ▼
┌─────────────────────────────────────┐
│  TASK 2: Team Phase (auto-created) │
│  ┌────────┐  ┌──────┐  ┌─────────┐ │
│  │ START  │─▶│ P0-P3│─▶│   END   │ │
│  │ setup  │  │subtasks│ │finalize│ │
│  └────────┘  └──────┘  └─────────┘ │
└─────────────────────────────────────┘

Kiedy używać PLAN-TO-TEAM-WEBHOOK?

Używaj PLAN-TO-TEAM-WEBHOOK gdy:

Potrzebujesz zewnętrznego approval przed implementacją
Chcesz integrować z systemami zarządzania (n8n, Jenkins, etc.)
Plan wymaga preprocessing (wzbogacenie danymi, walidacja)
Musisz trackować metryki między fazami
Implementacja ma być zainicjowana przez zewnętrzny system
Chcesz rozdzielić budżet AI między Plan i Team

NIE używaj PLAN-TO-TEAM-WEBHOOK gdy:

Potrzebujesz natychmiastowej implementacji bez oczekiwania
Nie masz infrastruktury n8n/webhook
Zadanie jest trywialne (użyj zwykłego TEAM)
Nie potrzebujesz separacji faz

Przepływ PLAN-TO-TEAM-WEBHOOK

FAZA 1: PLAN (Pierwsza Sesja AI)

1.1. Inicjalizacja workspace (init_workspace.sh)

bash

bash /workspace/files/helpers/init_workspace.sh

Co robi:

Klonuje repositories z task.json
Checkout na working_branch
Konfiguruje git credentials
Tworzy workspace volume

Dependencies:

Brak (pierwszy krok)

1.2. Generowanie planu (/plugin-codegen:plan)

bash

/plugin-codegen:plan $TASK_DIR/task.md

Co robi:

READ task.md (prosta wersja zadania)
Eksploruje codebase (READ-ONLY)
Analizuje wzorce i technologie
Generuje task_plan.md z:
- Cel główny
- Kontekst z codebase
- Lista plików do modyfikacji
- Plan implementacji (P0-P3)
- Success criteria
- Potential issues

Output:

/task/task_plan.md - szczegółowy plan implementacji

Dependencies:

init_workspace

1.3. Ekstrakcja Session ID (extract_session_claude.sh)

bash

bash /workspace/files/helpers/extract_session_claude.sh plan_task /task

Co robi:

Wyciąga Session ID z docker output logs subtaska plan_task
Zapisuje Session ID w /task/task.json (ai.sessions.claude)
Pozwala na kontynuację sesji AI w Fazie TEAM

Dependencies:

plan_task

1.4. Kopiowanie planu (copy_file.sh)

bash

bash /workspace/files/helpers/copy_file.sh plan_task /task task_plan.md

Co robi:

Sprawdza czy task_plan.md istnieje w /task/ (bezpośrednio zapisany przez plugin)
Jeśli nie, kopiuje z subtask directory do /task/task_plan.md
Zapewnia dostępność planu dla kolejnych kroków

Dependencies:

extract_session

1.5. Wysłanie webhooka (send_plan_webhook.sh) - END PHASE

bash

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

Co robi:

Zbiera dane z /task/task.json, /task/task_plan.md, /task/task.md
Tworzy JSON payload z:
- Task metadata (task_id, title, issue_url, worker_type)
- AI info (provider, model, session_id)
- Plan content (task_plan.md)
- Task description (task.md)
- Repositories config
- Actions requested (create_team_task)
Wysyła POST request do n8n webhook
Zapisuje artefakty w /task/.spec/webhooks/:
- plan_webhook_payload_{timestamp}.json
- plan_webhook_response_{timestamp}.json

Parametry:

<WEBHOOK_URL> - Pełny URL webhooka n8n (POST)

HTTP Status Codes:

200, 201, 204 → Sukces (exit 0)
Inne → Błąd (exit 1)

Dependencies:

copy_plan

Example webhook URL:

bash

https://n8n.example.com/webhook/plan-to-team
https://n8n.production.company.com/webhook/code-gen/plan-completed

FAZA 2: N8N WEBHOOK PROCESSING

N8N workflow otrzymuje payload i:

2.1. Validation

Weryfikuje completeness planu
Sprawdza czy session_id istnieje
Waliduje repositories config

2.2. Optional Preprocessing

Approval gate - wysyła notyfikację do PM/Tech Lead
Data enrichment - dodaje dodatkowe dane (Jira info, metrics)
Priority routing - routuje do odpowiedniej kolejki
Budget check - weryfikuje budżet AI credits

2.3. Task Creation

Tworzy nowy task w tasks/in_queue/{TASK_ID}-TEAM/
Kopiuje task.json z payload (z session_id!)
Zapisuje task.md
Zapisuje task_plan.md (jako główny task.md dla TEAM)
Dodaje metadata (source: plan-to-team-webhook)

2.4. Trigger Team Orchestrator

Wywołuje Dagu API lub webhook do triggerowania orchestrator_team.yaml
Przekazuje TASK_ID-TEAM

FAZA 3: TEAM (Druga Sesja AI - Auto-created)

Ta faza działa identycznie jak standardowy TEAM mode:

bash

/plugin-codegen:team

START Phase
- setup_team
- create_subtasks (z task_plan.md)
- resolve_dependencies
- approval_subtask_breakdown
WORK Phase (P0-P3)
- Wykonanie subtasków z dependency management
- Równoległe wykonanie w ramach priorytetu
- Retry mechanic (2 attempts)
END Phase
- persist_git (commit changes)
- github_push_mr (create pull request)
- visual_verification (jeśli frontend)
- task_verification
- run_verification

start_commands dla PLAN-TO-TEAM-WEBHOOK

json

{
  "ai": {
    "provider": "claude",
    "model": "claude-sonnet-4-5-20250929",
    "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"]
      }
    ]
  }
}

UWAGA: URL webhooka musi być pełnym adresem HTTP/HTTPS jako pierwszy parametr skryptu.

Webhook Payload Structure

Request (sent by send_plan_webhook.sh)

json

{
  "event": "plan_completed",
  "timestamp": "2026-01-14T12:00:00Z",
  "task": {
    "task_id": "DEV-123",
    "title": "Feature title",
    "description": "Feature 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## 🎯 Cel Główny\n..."
  },
  "task_md": {
    "content": "# Task Description\n\nSimple one-liner task..."
  },
  "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"
  }
}

Response (expected from n8n)

json

{
  "success": true,
  "task_id": "DEV-123-TEAM",
  "message": "Team task created successfully",
  "metadata": {
    "created_at": "2026-01-14T12:01:00Z",
    "queue": "in_queue",
    "status": "pending"
  }
}

N8N Workflow Example

Basic Node Setup

javascript

// Node 1: Webhook Trigger
// URL: /webhook/plan-to-team
// Method: POST
// Authentication: None (lub API Key)

// Node 2: Validation
if (!$json.plan.exists || !$json.task.task_id) {
  throw new Error('Invalid payload');
}

// Node 3: Create Task Directory
const taskId = `${$json.task.task_id}-TEAM`;
const taskDir = `/path/to/tasks/in_queue/${taskId}`;

// Node 4: Write Files
// task.json (with session_id!)
// task.md (task_plan.md content as main task description)
// Original task.md as task_original.md

// Node 5: Trigger Dagu
// POST to Dagu API: /dags/orchestrator_team/start
// Body: { "params": { "TASK_ID": taskId } }

// Node 6: Response
return {
  success: true,
  task_id: taskId,
  message: 'Team task created successfully'
};

Artefakty

Po FAZA 1 (Plan):

/task/
  task.json                 # Z session_id!
  task.md                   # Oryginalna prosta wersja
  task_plan.md              # Szczegółowy plan

  .spec/
    webhooks/
      plan_webhook_payload_{timestamp}.json    # Wysłany payload
      plan_webhook_response_{timestamp}.json   # Odpowiedź z n8n

  subtasks/
    START/
      done/
        init_workspace_xxxxx/
        plan_task_xxxxx/
        extract_session_xxxxx/
        copy_plan_xxxxx/
    END/
      done/
        send_webhook_xxxxx/

Po FAZA 3 (Team):

tasks/done/{TASK_ID}-TEAM/
  task.json
  task.md                   # task_plan.md z Fazy 1
  task_original.md          # Prosta wersja

  subtasks/
    START/ (team setup)
    P0/ (krytyczne)
    P1/ (ważne)
    P2/ (weryfikacja)
    P3/ (opcjonalne)
    END/ (finalizacja)

  .spec/
    diffs/                  # Git diffs
    dependency_graph.mmd    # Mermaid graph
    logs/                   # Subtask logs

Session Tracking

KLUCZOWA ZALETA: Session ID jest przekazywany między fazami!

Faza PLAN:

json

{
  "ai": {
    "sessions": {
      "claude": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}

Webhook Payload:

json

{
  "ai": {
    "session_id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

Faza TEAM (nowy task.json):

json

{
  "ai": {
    "sessions": {
      "claude": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}

Rezultat: Claude w Fazie TEAM ma pełen kontekst z Fazy PLAN!

Use Cases

1. Basic Plan-to-Team (Auto)

Plan → Webhook → Team (auto-trigger)

Najszybszy flow
Brak manual intervention

2. Plan with Approval Gate

Plan → Webhook → N8N Approval → Manual Trigger → Team

PM/Tech Lead approval required
Button in Slack/Mattermost
Team starts po zatwierdzeniu

3. Multi-Repository Coordination

Plan → Webhook → N8N Split → [Team Frontend, Team Backend] (parallel)

N8N tworzy 2 taski
Równoległe wykonanie
Synchronizacja na końcu

4. Budget-Aware Routing

Plan → Webhook → N8N Budget Check → [High Priority Queue, Low Priority Queue, Reject]

Sprawdzenie budżetu AI credits
Priorytetyzacja tasków
Odrzucenie jeśli brak budżetu

5. Staging Environment Testing

Plan → Webhook → N8N → Team (Staging) → Manual Approval → Team (Production)

Testowanie na stagingu
Weryfikacja przez QA
Deployment na production po approval

Example Output Logs

send_plan_webhook.sh 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: Feature: Add export CSV button
🔗 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: Feature: Add export CSV button
📊 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",
  "metadata": {
    "created_at": "2026-01-14T12:01:00Z",
    "queue": "in_queue",
    "status": "pending"
  }
}

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

Error Handling

Webhook Failed (HTTP ≠ 200/201/204)

bash

❌ BŁĄD: Webhook zwrócił status 500
Response: {"error": "Internal server error"}

# Task pozostaje w Plan Phase
# Możliwe akcje:
# 1. Sprawdź logi n8n
# 2. Ponów wysłanie webhooka ręcznie
# 3. Ręcznie utwórz Team task

Missing task_plan.md

bash

❌ BŁĄD: Plik task_plan.md nie istnieje

# Możliwe przyczyny:
# 1. plan_task nie wykonał się
# 2. copy_plan nie skopiował pliku
# 3. Plugin nie utworzył pliku

# Rozwiązanie:
# Sprawdź logi subtaska plan_task

Invalid Session ID

bash

⚠️  Session ID jest pusty - Team zacznie nową sesję

# Nie jest to błąd krytyczny
# Team utworzy nową sesję AI
# Ale utraci kontekst z Plan Phase

Monitorowanie

Metryki do trackowania:

Plan Phase Duration
- Czas wykonania Fazy PLAN
- Benchmark: 2-5 minut
Webhook Latency
- Czas między wysłaniem a response
- Benchmark: < 2 sekundy
N8N Processing Time
- Czas między webhook a utworzeniem Team task
- Benchmark: < 10 sekund
Total Time Plan-to-Team
- Całkowity czas od startu PLAN do startu TEAM
- Benchmark: 5-10 minut
Session Persistence Rate
- % tasków gdzie session_id był przekazany
- Target: > 95%

Troubleshooting

Problem: Webhook nie działa

Symptom:

❌ BŁĄD: Webhook zwrócił status 0 (connection refused)

Rozwiązania:

Sprawdź czy n8n jest uruchomiony
Sprawdź URL webhooka (http vs https)
Sprawdź firewall/network connectivity
Sprawdź logi n8n

Problem: Team task nie jest tworzony

Symptom:

✅ Webhook executed successfully
(ale task nie pojawia się w in_queue/)

Rozwiązania:

Sprawdź response z webhooka - czy sukces?
Sprawdź logi n8n workflow
Sprawdź czy n8n ma uprawnienia do zapisu w tasks/
Sprawdź czy payload zawiera wszystkie wymagane pola

Problem: Session ID nie jest przekazywany

Symptom:

⚠️  Session ID jest pusty

Rozwiązania:

Sprawdź czy extract_session wykonał się
Sprawdź logi subtaska plan_task
Sprawdź task.json - czy session_id jest zapisany?
Sprawdź czy docker output logs zawierają session_id

Problem: task_plan.md jest pusty

Symptom:

"plan": {
  "exists": true,
  "content": ""
}

Rozwiązania:

Sprawdź czy /plugin-codegen:plan zapisał plik
Sprawdź uprawnienia do /task/task_plan.md
Sprawdź logi subtaska plan_task
Sprawdź czy copy_plan wykonał się

Zalety tego rozwiązania

1. Separacja faz

Plan i Team są osobnymi taskami
Można zatrzymać po Plan i przeanalizować
Łatwiejsze debugging

2. Integracja z zewnętrznymi systemami

n8n może dodać własną logikę
Approval gates
Routing based on content
Budget management

3. Session tracking

Kontekst AI jest zachowany
Claude w TEAM wie co robił w PLAN
Lepsza jakość implementacji

4. Audyt i monitoring

Wszystkie dane zapisane w artefaktach
Payload i response do analizy
Metryki między fazami

5. Flexibility

Można dodać preprocessing
Można dodać approval
Można routować do różnych queues
Można integrować z innymi systemami (Jira, Slack, etc.)

FAQ

Q: Czy PLAN-TO-TEAM-WEBHOOK jest wolniejszy niż zwykły TEAM? A: Tak, o ~10-30 sekund (webhook latency + n8n processing). Ale daje dużo więcej kontroli.

Q: Czy muszę używać n8n? A: Nie. Możesz użyć dowolnego systemu HTTP webhook (Zapier, Make, własny API).

Q: Co jeśli webhook nie działa? A: Task pozostaje w Plan Phase. Możesz ręcznie utworzyć Team task lub ponowić webhook.

Q: Czy session_id jest obowiązkowy? A: Nie. Jeśli brak session_id, TEAM zacznie nową sesję (ale utraci kontekst z PLAN).

Q: Czy mogę edytować plan przed Team Phase? A: Tak! Po otrzymaniu webhooka w n8n możesz:

Pokazać plan userowi do approval
Edytować task_plan.md
Wzbogacić o dodatkowe dane
Dopiero potem utworzyć Team task

Q: Czy mogę użyć tego do multi-repo tasków? A: Tak! n8n może utworzyć wiele Team tasków (jeden na repo).

Q: Gdzie są skrypty? A: docker/{worker}/files/helpers/send_plan_webhook.sh

Q: Jak testować webhook lokalnie? A: Użyj ngrok lub webhook.site do testowania bez n8n.

PLAN Mode - Szczegóły Fazy PLAN
TEAM Mode - Szczegóły Fazy TEAM
Implementation Guide - Szczegóły techniczne
Task Configuration - Konfiguracja task.json
Example task.json - Gotowy przykład

Tryb PLAN-TO-TEAM-WEBHOOK - Dwufazowy przepływ z integracją n8n ​

Przegląd ​

Kiedy używać PLAN-TO-TEAM-WEBHOOK? ​

Przepływ PLAN-TO-TEAM-WEBHOOK ​

FAZA 1: PLAN (Pierwsza Sesja AI) ​

1.1. Inicjalizacja workspace (init_workspace.sh) ​

1.2. Generowanie planu (/plugin-codegen:plan) ​

1.3. Ekstrakcja Session ID (extract_session_claude.sh) ​

1.4. Kopiowanie planu (copy_file.sh) ​

1.5. Wysłanie webhooka (send_plan_webhook.sh) - END PHASE ​

FAZA 2: N8N WEBHOOK PROCESSING ​

2.1. Validation ​

2.2. Optional Preprocessing ​

2.3. Task Creation ​

2.4. Trigger Team Orchestrator ​

FAZA 3: TEAM (Druga Sesja AI - Auto-created) ​

start_commands dla PLAN-TO-TEAM-WEBHOOK ​

Webhook Payload Structure ​

Request (sent by send_plan_webhook.sh) ​

Response (expected from n8n) ​

N8N Workflow Example ​

Basic Node Setup ​

Artefakty ​

Po FAZA 1 (Plan): ​

Po FAZA 3 (Team): ​

Session Tracking ​

Faza PLAN: ​

Webhook Payload: ​

Faza TEAM (nowy task.json): ​

Use Cases ​

1. Basic Plan-to-Team (Auto) ​

2. Plan with Approval Gate ​

3. Multi-Repository Coordination ​

4. Budget-Aware Routing ​

5. Staging Environment Testing ​

Example Output Logs ​

send_plan_webhook.sh output: ​

Error Handling ​

Webhook Failed (HTTP ≠ 200/201/204) ​

Missing task_plan.md ​

Invalid Session ID ​

Monitorowanie ​

Metryki do trackowania: ​

Troubleshooting ​

Problem: Webhook nie działa ​

Problem: Team task nie jest tworzony ​

Problem: Session ID nie jest przekazywany ​

Problem: task_plan.md jest pusty ​

Zalety tego rozwiązania ​

1. Separacja faz ​

2. Integracja z zewnętrznymi systemami ​

3. Session tracking ​

4. Audyt i monitoring ​

5. Flexibility ​

FAQ ​

Related Documentation ​

Tryb PLAN-TO-TEAM-WEBHOOK - Dwufazowy przepływ z integracją n8n

Przegląd

Kiedy używać PLAN-TO-TEAM-WEBHOOK?

Przepływ PLAN-TO-TEAM-WEBHOOK

FAZA 1: PLAN (Pierwsza Sesja AI)

1.1. Inicjalizacja workspace (init_workspace.sh)

1.2. Generowanie planu (/plugin-codegen:plan)

1.3. Ekstrakcja Session ID (extract_session_claude.sh)

1.4. Kopiowanie planu (copy_file.sh)

1.5. Wysłanie webhooka (send_plan_webhook.sh) - END PHASE

FAZA 2: N8N WEBHOOK PROCESSING

2.1. Validation

2.2. Optional Preprocessing

2.3. Task Creation

2.4. Trigger Team Orchestrator

FAZA 3: TEAM (Druga Sesja AI - Auto-created)

start_commands dla PLAN-TO-TEAM-WEBHOOK

Webhook Payload Structure

Request (sent by send_plan_webhook.sh)

Response (expected from n8n)

N8N Workflow Example

Basic Node Setup

Artefakty

Po FAZA 1 (Plan):

Po FAZA 3 (Team):

Session Tracking

Faza PLAN:

Webhook Payload:

Faza TEAM (nowy task.json):

Use Cases

1. Basic Plan-to-Team (Auto)

2. Plan with Approval Gate

3. Multi-Repository Coordination

4. Budget-Aware Routing

5. Staging Environment Testing

Example Output Logs

send_plan_webhook.sh output:

Error Handling

Webhook Failed (HTTP ≠ 200/201/204)

Missing task_plan.md

Invalid Session ID

Monitorowanie

Metryki do trackowania:

Troubleshooting

Problem: Webhook nie działa

Problem: Team task nie jest tworzony

Problem: Session ID nie jest przekazywany

Problem: task_plan.md jest pusty

Zalety tego rozwiązania

1. Separacja faz

2. Integracja z zewnętrznymi systemami

3. Session tracking

4. Audyt i monitoring

5. Flexibility

FAQ

Related Documentation