Code Generations Manager

Appearance

Tryb PLAN - Transformacja zadania w szczegółowy plan implementacji ​

Przegląd ​

Tryb PLAN przekształca proste, jednoliniowe zadanie w szczegółowy plan implementacji poprzez:

  • READ-ONLY eksplorację codebase
  • Analizę wzorców i technologii
  • Identyfikację komponentów do modyfikacji
  • Utworzenie priorytetowych subtasków
  • Określenie kryteriów sukcesu
INPUT:  task.md (prosta wersja)
          ↓
      /plan command
          ↓
     Claude eksploruje:
     - Codebase (READ-ONLY)
     - Wzorce (Design Tokens, etc.)
     - Komponenty (Angular, SCSS, etc.)
          ↓
OUTPUT: task_plan.md (szczegółowa wersja)

Kiedy używać PLAN? ​

Używaj PLAN gdy:

  • Masz prostą specyfikację zadania (1-3 zdania)
  • Potrzebujesz szczegółowego planu implementacji
  • Chcesz poznać pełny zakres zmian
  • Musisz oszacować złożoność zadania
  • Chcesz uniknąć niekompletnej implementacji

NIE używaj PLAN gdy:

  • Masz już szczegółowy plan (używaj TEAM)
  • Zadanie jest trywialne (1-2 linie kodu)
  • Potrzebujesz natychmiastowej implementacji bez analizy

Przepływ PLAN mode ​

1. Przygotowanie (backup_task_md.sh) ​

bash
bash /workspace/files/helpers/backup_task_md.sh

Co robi:

  • Kopiuje /task/task.md → /task/task_original.md
  • Zabezpiecza oryginalną prostą wersję zadania
  • Pozwala na przywrócenie po zakończeniu planowania

Przykład task.md (INPUT):

markdown
# Zmiana koloru paska navbar

Zmień kolor paska pod navbar który jest widoczny jako super administrator.
Zmieniamy kolor z czerwonego na niebieski ciemny.

2. Eksploracja i planowanie (/plugin-codegen:plan) ​

bash
/plugin-codegen:plan

Przepływ Claude:

markdown
1. READ task.md (prosta wersja)
2. EKSPLORUJ codebase (READ-ONLY):
   - Znajdź komponenty związane z navbar
   - Zidentyfikuj technologie (Angular, SCSS, Material, etc.)
   - Przeanalizuj istniejące wzorce (Design Tokens, services, etc.)
   - Znajdź podobne implementacje

3. ANALIZA:
   - Jak to jest obecnie zaimplementowane?
   - Jakie komponenty trzeba zmodyfikować?
   - Jakie wzorce można wykorzystać?
   - Jakie są edge cases?

4. GENERUJ task_plan.md:
   - Cel główny (rozszerzony)
   - Kontekst z codebase
   - Lista plików do modyfikacji
   - Wzorce do wykorzystania
   - Plan implementacji (priorytetowe subtaski)
   - Kryteria sukcesu
   - Potencjalne problemy

Przykład task_plan.md (OUTPUT):

markdown
# Zmiana Koloru Paska Super Administratora

## 🎯 Cel Główny

Zmiana koloru paska administracyjnego wyświetlanego pod głównym paskiem
nawigacyjnym dla użytkowników z rolą super administratora z czerwonego
na ciemnoniebieski (#1a3a5c).

## 📋 Kontekst z Codebase

### Technologia
- Angular 18.2
- Angular Material
- SCSS (Sass preprocessor)
- Design Tokens (Figma integration)

### Obecna Implementacja
```typescript
// src/app/shared/components/container/container.component.ts
export class ContainerComponent {
  isSuperAdmin$ = this.authService.isSuperAdmin();
}
scss
// src/app/shared/components/container/container.component.scss
.admin-bar {
  background-color: #ff0000; // Czerwony
  height: 4px;
  width: 100%;
}

Istniejące Komponenty ​

  • ContainerComponent - główny layout (ma już logikę super admin)
  • AuthService - weryfikacja roli (isSuperAdmin())
  • Design Tokens - zmienne kolorów w _colors.scss

📂 Pliki do Modyfikacji ​

Priority P0 (Krytyczne): ​

  1. src/app/shared/components/container/container.component.scss
    • Zmiana background-color: #ff0000 → #1a3a5c

Priority P1 (Weryfikacja): ​

  1. src/styles/_colors.scss (opcjonalnie)
    • Dodanie tokena: $admin-bar-color: #1a3a5c;
    • Używanie tokena zamiast hardcoded color

🎨 Wzorce do Wykorzystania ​

Design Tokens Pattern ​

System wykorzystuje Figma Design Tokens w src/styles/_colors.scss:

scss
// Istniejące tokeny
$primary-blue: #1a3a5c;
$warning-red: #ff0000;
$success-green: #28a745;

// Nowy token (opcjonalnie)
$admin-bar-super-admin: $primary-blue;

Zaleta: Spójność kolorów w całej aplikacji + łatwość zmiany w przyszłości.

📝 Plan Implementacji ​

Priority P0: Zmiana Koloru Paska ​

Subtask 1: Zmień kolor w SCSS

scss
// src/app/shared/components/container/container.component.scss
.admin-bar {
  background-color: #1a3a5c; // Zmiana: #ff0000 → #1a3a5c
  height: 4px;
  width: 100%;
}

Weryfikacja:

  • [ ] Pasek jest ciemnoniebieskim (#1a3a5c)
  • [ ] Zmiana dotyczy TYLKO super administratora
  • [ ] Brak regresji dla innych ról

Priority P1: Wykorzystanie Design Tokens (Opcjonalnie) ​

Subtask 2: Dodaj token do _colors.scss

scss
// src/styles/_colors.scss
$admin-bar-super-admin: #1a3a5c;

Subtask 3: Użyj tokena w komponencie

scss
// src/app/shared/components/container/container.component.scss
@import 'src/styles/colors';

.admin-bar {
  background-color: $admin-bar-super-admin; // Token zamiast hardcoded
  height: 4px;
  width: 100%;
}

Weryfikacja:

  • [ ] Kolor działa identycznie
  • [ ] Build przechodzi bez błędów SCSS

Priority P2: Build & Deployment Verification ​

Subtask 4: Uruchom build

bash
npm run build

Weryfikacja:

  • [ ] Build przechodzi bez błędów
  • [ ] Brak ostrzeżeń SCSS compilation
  • [ ] Bundle size nie zwiększył się znacząco

Priority P3: Documentation & Code Quality ​

Subtask 5: Dodaj komentarz

scss
// Admin bar for super administrators
// Color: Dark blue (#1a3a5c) per design system
.admin-bar {
  background-color: $admin-bar-super-admin;
  height: 4px;
  width: 100%;
}

Weryfikacja:

  • [ ] Kod jest zrozumiały dla innych developerów

✅ Success Criteria ​

Funkcjonalne: ​

  • [x] Pasek ma kolor ciemnoniebieskim (#1a3a5c)
  • [x] Zmiana dotyczy TYLKO super administratora
  • [x] Brak wpływu na innych użytkowników

Techniczne: ​

  • [x] Build przechodzi bez błędów
  • [x] SCSS kompiluje się poprawnie
  • [x] Wykorzystuje Design Tokens (jeśli P1 zaimplementowane)

Wizualne: ​

  • [x] Kolor wizualnie zgodny z mockupem/wymaganiami
  • [x] Brak artefaktów wizualnych (flickering, etc.)

⚠️ Potential Issues & Solutions ​

Issue 1: Hardcoded Color vs Design Token ​

Problem: Hardcoded #1a3a5c utrudnia przyszłe zmiany Solution: Użyć Design Token $admin-bar-super-admin (Priority P1)

Issue 2: Cache przeglądarki ​

Problem: Użytkownicy mogą widzieć stary kolor (cached CSS) Solution: Hard refresh (Ctrl+Shift+R) lub cache busting w deployment

Issue 3: Accessibility ​

Problem: Ciemnoniebieski może mieć niski kontrast Solution: Sprawdzić WCAG contrast ratio (powinno być OK dla paska dekoracyjnego)

📊 Metryki ​

  • Złożoność: Niska (1-2 pliki)
  • Ryzyko: Bardzo niskie
  • Czas estymowany: 5-10 minut
  • Priorytet P0: 1 subtask (MUST)
  • Priorytet P1: 2 subtaski (SHOULD)
  • Priorytet P2: 1 subtask (VERIFICATION)
  • Priorytet P3: 1 subtask (NICE-TO-HAVE)

### 3. Finalizacja (move_task_md.sh)

```bash
bash /workspace/files/helpers/move_task_md.sh

Co robi:

  • Kopiuje /task/task_plan.md → /task/.spec/{TASK_ID}/task.md
  • Przywraca /task/task_original.md → /task/task.md
  • Zadanie wraca do prostej wersji
  • Plan jest dostępny w .spec/ do użycia przez TEAM mode

Struktura po PLAN:

/task/
  task.md              # Oryginalna prosta wersja (przywrócona)
  task_original.md     # Backup
  task_plan.md         # Wygenerowany plan
  .spec/
    DEV-1_2/
      task.md          # Kopia task_plan.md (dla TEAM mode)

start_commands dla PLAN mode ​

json
{
  "ai": {
    "start_commands": [
      {
        "id": "backup_task",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/backup_task_md.sh",
        "dependencies": []
      },
      {
        "id": "plan_task",
        "catalog": "START",
        "executor": "claude",
        "command": "/plugin-codegen:plan",
        "dependencies": ["backup_task"]
      },
      {
        "id": "move_task_spec",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/move_task_md.sh",
        "dependencies": ["plan_task"]
      }
    ]
  }
}

Struktura task_plan.md ​

Sekcje standardowe: ​

  1. 🎯 Cel Główny

    • Rozszerzony opis zadania
    • Pełen kontekst biznesowy/techniczny

  2. 📋 Kontekst z Codebase

    • Technologia: Stack technologiczny (Angular, React, Go, etc.)
    • Obecna Implementacja: Jak to działa teraz (fragmenty kodu)
    • Istniejące Komponenty: Co można wykorzystać

  3. 📂 Pliki do Modyfikacji

    • Lista konkretnych plików z ścieżkami
    • Grupowanie po priorytetach (P0, P1, P2, P3)

  4. 🎨 Wzorce do Wykorzystania

    • Identyfikowane wzorce (Design Tokens, Services, etc.)
    • Przykłady istniejących implementacji
    • Rekomendacje best practices

  5. 📝 Plan Implementacji

    • Priority P0: Krytyczne (MUST) - minimalna działająca funkcjonalność
    • Priority P1: Ważne (SHOULD) - best practices, refactoring
    • Priority P2: Weryfikacja (VERIFICATION) - build, testy
    • Priority P3: Nice-to-have (OPTIONAL) - dokumentacja, komentarze

  6. ✅ Success Criteria

    • Kryteria funkcjonalne
    • Kryteria techniczne
    • Kryteria wizualne (jeśli UI)

  7. ⚠️ Potential Issues & Solutions

    • Przewidywane problemy
    • Rozwiązania/workaroundy

  8. 📊 Metryki (opcjonalnie)

    • Złożoność (Niska/Średnia/Wysoka)
    • Ryzyko (Niskie/Średnie/Wysokie)
    • Liczba subtasków na priorytet

Priorytety Subtasków ​

P0 - MUST (Krytyczne) ​

  • Minimalna działająca funkcjonalność
  • Bez tego feature nie działa
  • Zawsze implementowane

Przykład:

  • Zmiana koloru paska
  • Dodanie przycisku
  • Podstawowa logika biznesowa

P1 - SHOULD (Ważne) ​

  • Best practices
  • Refactoring dla maintainability
  • Wykorzystanie wzorców (Design Tokens, services, etc.)

Przykład:

  • Użycie Design Token zamiast hardcoded color
  • Wydzielenie logiki do serwisu
  • DRY principle

P2 - VERIFICATION (Weryfikacja) ​

  • Build & compilation
  • Testy (unit, integration, e2e)
  • Linting & code quality

Przykład:

  • npm run build
  • npm test
  • npm run lint

P3 - OPTIONAL (Nice-to-have) ​

  • Dokumentacja
  • Komentarze w kodzie
  • Accessibility improvements
  • Performance optimizations (jeśli nie krytyczne)

Przykład:

  • Dodanie JSDoc
  • README update
  • A11y dla screen readers

Eksploracja codebase (READ-ONLY) ​

Claude w trybie PLAN eksploruje codebase BEZ MODYFIKACJI:

Techniki eksploracji: ​

  1. Grep/Ripgrep - szukanie kluczowych słów
bash
rg "navbar" --type ts
rg "isSuperAdmin" --type ts
rg "admin-bar" --type scss
  1. Glob - znajdowanie plików po wzorcach
bash
**/*navbar*.component.ts
**/*auth*.service.ts
src/styles/**/*.scss
  1. Read - czytanie znalezionych plików
typescript
// Analiza istniejącego kodu
// Identyfikacja wzorców
// Zrozumienie architektury
  1. Analiza zależności
typescript
// imports, exports
// services injection
// component hierarchy

Czego Claude szuka: ​

  • Istniejące komponenty do wykorzystania/modyfikacji
  • Wzorce architektoniczne (serwisy, tokeny, utilities)
  • Podobne implementacje (analogiczne features)
  • Technologie (framework, libraries, preprocessory)
  • Edge cases (role-based access, permissions, etc.)

Przykład: Od prostego zadania do planu ​

INPUT (task.md): ​

markdown
Dodaj przycisk "Eksportuj CSV" w tabeli użytkowników.

PLAN eksploruje: ​

  • Gdzie jest tabela użytkowników? → users-table.component.ts
  • Czy jest już export? → export.service.ts (TAK!)
  • Jakiego formatu używają? → CSV przez Papa.parse
  • Jak wyglądają inne przyciski? → Material <button mat-raised-button>

OUTPUT (task_plan.md): ​

markdown
# Eksport CSV w Tabeli Użytkowników

## 🎯 Cel
Dodanie funkcjonalności eksportu danych użytkowników do pliku CSV
z tabeli na stronie zarządzania użytkownikami.

## 📋 Kontekst z Codebase

### Technologia
- Angular 18.2 + Material
- Istniejący `ExportService` (Papa.parse library)
- `UsersTableComponent` - główny komponent

### Obecna Implementacja
```typescript
// src/app/features/users/users-table.component.ts
export class UsersTableComponent {
  users$ = this.usersService.getUsers();
}

Komponent NIE ma obecnie żadnej funkcji exportu, ale:

  • ExportService już istnieje w src/app/core/services/export.service.ts
  • Używa Papa.parse do generowania CSV
  • Przykład użycia w ReportsComponent

📂 Pliki do Modyfikacji ​

P0: ​

  1. users-table.component.ts - dodanie metody exportToCSV()
  2. users-table.component.html - dodanie przycisku

P1: ​

  1. export.service.ts - rozszerzenie o exportUsers() metoda

📝 Plan Implementacji ​

Priority P0: Dodanie Przycisku i Logiki ​

Subtask 1: Dodaj przycisk w template

html
<button mat-raised-button color="primary" (click)="exportToCSV()">
  <mat-icon>download</mat-icon>
  Eksportuj CSV
</button>

Subtask 2: Dodaj metodę w komponencie

typescript
export class UsersTableComponent {
  constructor(private exportService: ExportService) {}

  exportToCSV(): void {
    this.users$.subscribe(users => {
      this.exportService.exportUsers(users);
    });
  }
}

Priority P1: Wydzielenie logiki do serwisu ​

Subtask 3: Rozszerz ExportService

typescript
// export.service.ts
exportUsers(users: User[]): void {
  const data = users.map(u => ({
    ID: u.id,
    Email: u.email,
    Name: u.name,
    Role: u.role
  }));
  this.exportToCSV(data, 'users_export.csv');
}

Priority P2: Weryfikacja ​

Subtask 4: Testy

  • Unit test dla exportToCSV() metody
  • Weryfikacja poprawności formatu CSV

Priority P3: UX Improvements ​

Subtask 5: Loading state

typescript
isExporting = false;

exportToCSV(): void {
  this.isExporting = true;
  // ... export logic
  this.isExporting = false;
}

✅ Success Criteria ​

  • [x] Przycisk widoczny w tabeli
  • [x] Kliknięcie pobiera plik CSV
  • [x] CSV zawiera wszystkie kolumny
  • [x] Nazwa pliku: users_export.csv

⚠️ Potential Issues ​

Issue: Duża liczba użytkowników (performance) Solution: Paginacja lub streaming export (P3)


## Artefakty PLAN mode

Po zakończeniu PLAN tworzy:

/task/ task.md # Oryginalna wersja (przywrócona) task_original.md # Backup task_plan.md # Szczegółowy plan

.spec/ {TASK_ID}/ task.md # Kopia task_plan.md (dla TEAM)


## Kiedy używać PLAN → TEAM sequence?

Proste zadanie (task.md) ↓ /plan mode ↓ Szczegółowy plan (task_plan.md) ↓ /team mode ↓ Implementacja z subtaskami


**Zalety:**
- Plan jest przejrzysty PRZED implementacją
- User może zaakceptować/odrzucić plan
- TEAM ma pełen kontekst do implementacji
- Łatwiej estymować czas i złożoność

## FAQ

**Q: Czy PLAN modyfikuje kod?**
A: NIE. PLAN jest READ-ONLY. Tylko eksploruje i tworzy dokumentację (task_plan.md).

**Q: Czy muszę używać PLAN przed TEAM?**
A: Nie. Jeśli masz już szczegółowy plan, użyj bezpośrednio TEAM.

**Q: Co jeśli PLAN nie znalazł wszystkich plików?**
A: Możesz ręcznie edytować task_plan.md przed uruchomieniem TEAM.

**Q: Czy mogę pominąć priority P1-P3?**
A: Tak. TEAM może zaimplementować tylko P0 jeśli potrzebujesz MVP.

**Q: Jak długo trwa PLAN?**
A: Zależy od złożoności codebase. Zwykle 1-3 minuty eksploracji.

**Q: Gdzie są skrypty pomocnicze?**
A: `docker/{worker}/files/helpers/`
- `backup_task_md.sh` - backup task.md
- `move_task_md.sh` - kopiowanie do .spec/