Builder Flow v1 — Od pomysłu do prototypu: superpowers + opencode + mockup-to-HTML

Builder Flow to proces przekształcania luźnego pomysłu w działający prototyp strony/aplikacji, zanim powstanie jakikolwiek backend. Proces dzieli się na 4 fazy:

1. Specyfikacja — superpowers SDD generuje specyfikację biznesową, techniczną i wizualną
2. Mockup wizualny — automatycznie generowane obrazy każdej strony pod jej docelowym adresem URL
3. HTML + mock data — obrazy zamieniane na działające strony HTML pod tymi samymi URL-ami, z mockowanymi danymi
4. Prototyp do klikania — człowiek przegląda i zatwierdza, zanim zacznie się backend

Kluczowa zasada: najpierw wygląd i UX, potem backend. Unikasz sytuacji, gdzie kodzisz backend przez tydzień, a potem okazuje się że frontend wymaga redesignu.

Faza 0: Od pomysłu do backlogu

Zanim cokolwiek powstanie, pomysł musi być uchwycony w formie, którą superpowers może przetworzyć.

Krok 0.1: Opisz pomysł w jednym zdaniu

Każdy pomysł zaczyna się od jednego zdania, które odpowiada na 3 pytania:

• Dla kogo? — kto jest użytkownikiem końcowym
• Co robi? — główna funkcjonalność
• Czego chce? — jaki problem rozwiązuje

Przykład: "Aplikacja dla pacjentów normobarii, która pokazuje harmonogram sesji i postępy w terapii."

Krok 0.2: Stwórz kanban task

hermes kanban --board convertere create \
  --body 'IDEA: Aplikacja harmonogramu normobarii dla pacjentów
UŻYTKOWNIK: pacjenci centrum normobarii
FUNKCJONALNOŚĆ: harmonogram, postępy, powiadomienia
PROBLEM: pacjenci nie wiedzą kiedy mają sesje i jak postępują' \
  'Builder Flow: [Nazwa projektu] - Faza 0: Idea'

Faza 1: Specyfikacja przez superpowers SDD

Superpowers SDD (Superpowers Driven Development) generuje task briefy z precyzyjnymi specyfikacjami. To jest rdzeń procesu — tu powstaje trzywarstwowa specyfikacja.

Struktura katalogu SDD

<projekt>/.superpowers/sdd/
├── progress.md                    # Postęp: które taski skończone
├── phase-1-brief.md               # Specyfikacja biznesowa
├── phase-1-report.md              # Raport z fazy 1
├── phase-2-brief.md               # Specyfikacja techniczna
├── phase-2-report.md              # Raport z fazy 2
├── phase-3-brief.md               # Specyfikacja wizualna (lista stron)
├── phase-3-report.md              # Raport z fazy 3
├── task-1-brief.md                # Strona: Dashboard
├── task-1-report.md               # Raport: Dashboard HTML
├── task-2-brief.md                # Strona: Harmonogram
├── task-2-report.md               # Raport: Harmonogram HTML
└── ...

Krok 1.1: Specyfikacja biznesowa (phase-1)

CEO pisze brief fazy 1, który superpowers rozszerza:

cd /root/projects/<projekt>

# Zapisz brief do .superpowers/sdd/phase-1-brief.md
cat > .superpowers/sdd/phase-1-brief.md << 'EOF'
# Faza 1: Specyfikacja biznesowa

## Cel
Zdefiniuj model biznesowy aplikacji harmonogramu normobarii.

## Wymagane sekcje
1. **Persona** — kto jest użytkownikiem (pacjent, recepcja, admin)
2. **User stories** — 5-10 historyjek użytkownika w formacie "Jako [persona], chcę [funkcja], żeby [korzyść]"
3. **Przepływ biznesowy** — jak użytkownik przechodzi przez aplikację krok po kroku
4. **Metryki sukcesu** — po czym poznamy że aplikacja działa (retencja, czas sesji, NPS)

## Output
Plik phase-1-report.md z pełną specyfikacją biznesową.
EOF

Uruchom opencode z superpowers:

opencode run --prompt 'Przeczytaj .superpowers/sdd/phase-1-brief.md i wygeneruj phase-1-report.md z pełną specyfikacją biznesową. Użyj superpowers SDD workflow.' --auto

Efekt: phase-1-report.md zawiera:

• Persony (3-5 typów użytkowników)
• User stories (10-15, priorytetyzowane)
• Mapa przepływu (która strona prowadzi do której)
• Metryki sukcesu

Krok 1.2: Specyfikacja techniczna (phase-2)

Na podstawie biznesowej, CEO tworzy brief techniczny:

cat > .superpowers/sdd/phase-2-brief.md << 'EOF'
# Faza 2: Specyfikacja techniczna

## Cel
Na podstawie phase-1-report.md, zdefiniuj architekturę techniczną.

## Wymagane sekcje
1. **Struktura URL-i** — lista wszystkich ścieżek URL (np. /dashboard, /sessions, /profile)
2. **Model danych** — encje, relacje, kluczowe pola
3. **API endpoints** — REST lub GraphQL, metody, request/response
4. **Frontend stack** — framework, biblioteki, routing
5. **Backend stack** — język, baza danych, hosting

## Output
Plik phase-2-report.md z pełną specyfikacją techniczną.
EOF

Uruchom opencode:

opencode run --prompt 'Przeczytaj phase-1-report.md i phase-2-brief.md. Wygeneruj phase-2-report.md z architekturą techniczną.' --auto

Efekt: phase-2-report.md zawiera:

• Lista wszystkich URL-i aplikacji
• Schemat bazy danych
• Lista endpointów API
• Stack technologiczny

Krok 1.3: Specyfikacja wizualna — lista stron (phase-3)

To kluczowa faza. CEO tworzy brief, który definiuje każdą stronę z adresem URL, zawartością i elementami:

cat > .superpowers/sdd/phase-3-brief.md << 'EOF'
# Faza 3: Specyfikacja wizualna

## Cel
Na podstawie phase-1-report.md i phase-2-report.md, stwórz listę wszystkich stron.

## Wymagane sekcje
Dla KAŻDEJ strony:
1. **URL** — ścieżka (np. /dashboard, /sessions/123)
2. **Cel strony** — co użytkownik tu robi
3. **Elementy UI** — lista komponentów (nawigacja, tabela, formularz, wykres)
4. **Dane mockowe** — przykładowe dane do wyświetlenia
5. **Widok** — układ: co jest na górze, na środku, na dole
6. **Akcje użytkownika** — co może kliknąć, wpisać, przeciągnąć

## Przykład
### URL: /dashboard
- Cel: Podgląd postępów pacjenta
- Elementy: navbar (logo, linki), karta "Postęp", tabela "Ostatnie sesje", przycisk "Dodaj sesję"
- Dane mock: 4 sesje w tabeli, wykres postępu 60%
- Akcje: kliknięcie sesji → /sessions/{id}, kliknięcie "Dodaj" → /sessions/new

## Output
Plik phase-3-report.md — lista wszystkich stron z komponentami i danymi mockowymi.
EOF

Uruchom opencode:

opencode run --prompt 'Przeczytaj phase-1-report.md, phase-2-report.md i phase-3-brief.md. Wygeneruj phase-3-report.md z listą stron.' --auto

Efekt: phase-3-report.md zawiera kompletną listę stron z:

• URL-e
• Opis UI
• Dane mockowe
• Akcje użytkownika

Faza 2: Mockup wizualny — obrazy stron

Po specyfikacji, każda strona musi zostać zwizualizowana jako obrazek. To jest najtrudniejszy krok, bo opencode (kimi-k2-7-code) to model kodowania, nie generowania obrazów.

Opcja A: HTML/CSS mockup (zalecana)

Najprostsza i najszybsza metoda. Opencode generuje HTML z inline CSS, który wygląda jak docelowa strona:

# Dla KAŻDEJ strony z phase-3-report.md, wygeneruj HTML mockup
opencode run --prompt '
Stwórz plik /var/www/projects/<projekt>/dashboard/index.html z pełnym HTML/CSS mockupem strony dashboard.

Wymagania:
- URL: https://10s.pl/<projekt>/dashboard/
- Design: nowoczesny, czysty, z paddingiem 2rem, font systemowy
- Elementy z phase-3-report.md: navbar, karta postępu, tabela sesji, przycisk dodawania
- Dane mockowe: wypełnij realistycznymi danymi (imiona, daty, wartości)
- Żadnych backendowych zależności — czysty HTML + CSS
- Wszystkie linki prowadzą do innych stron mockupu (np. /projekt/sessions/123)
- Na dole stopka: "Mockup v1 — dane testowe"
' --auto

Proces dla każdej strony:

# 1. Lista stron z phase-3-report.md
# 2. Dla każdej: opencode run --prompt 'Stwórz HTML mockup dla URL: ...'
# 3. Sprawdź czy wszystkie linki wewnętrzne działają

Zalety: Błyskawicznie, każda strona pod swoim URL-em, gotowe do klikania.

Wady: To nie są obrazy, tylko HTML z CSS — ale wyglądają identycznie jak finalna strona.

Opcja B: Screenshot z przeglądarki

Po wygenerowaniu HTML/CSS mockupów, możesz zrobić screenshota każdej strony:

# Użyj browser_navigate + browser_vision lub narzędzia do screenshotów
# Przykład: otwórz w headless Chrome i zrób zrzut
google-chrome --headless --screenshot=/var/www/projects/<projekt>/dashboard/screenshot.png \
  https://10s.pl/<projekt>/dashboard/

Opcja C: AI Image Generation (zaawansowane)

Dla bardziej zaawansowanych wizualizacji, możesz użyć modelu generowania obrazów (np. Flux, DALL-E, Midjourney) do wygenerowania screenshotów na podstawie opisu z phase-3-report.md:

Prompt: "Create a modern web dashboard UI for a normobaric therapy patient app.
Show a navbar with logo, a progress card showing 60% completion, a table of recent sessions,
and a blue 'Add Session' button. Clean design, light theme, professional medical app style."

Następnie: zapisz obrazek jako /var/www/projects/<projekt>/dashboard/mockup.png i wyświetl go na stronie pod URL-em /dashboard/.

Faza 3: HTML z mockowanymi danymi

Obrazy/szkice → działające HTML strony pod tymi samymi URL-ami. To jest miejsce, gdzie opencode (kimi-k2-7-code) brilliuje — generuje pełny, responsywny HTML z mockowanymi danymi.

Krok 3.1: Struktura katalogów

/var/www/projects/<projekt>/
├── index.html               # Strona główna (lista wszystkich stron)
├── dashboard/
│   └── index.html           # Dashboard z mock danych
├── sessions/
│   ├── index.html           # Lista sesji
│   └── 123/
│       └── index.html       # Szczegóły sesji (mock ID)
├── profile/
│   └── index.html           # Profil użytkownika
├── settings/
│   └── index.html           # Ustawienia
└── assets/
    ├── style.css            # Wspólny CSS (opcjonalnie)
    └── mock-data.js         # Wspólne dane mockowe (opcjonalnie)

Krok 3.2: Generuj każdą stronę przez opencode

# Strona główna
opencode run --prompt '
Stwórz /var/www/projects/<projekt>/index.html — strona główna prototypu.
Lista wszystkich stron z linkami:
- /dashboard — Dashboard pacjenta
- /sessions — Lista sesji
- /sessions/123 — Szczegóły sesji
- /profile — Profil użytkownika
- /settings — Ustawienia

Każdy link z krótkim opisem (1 zdanie). Nowoczesny design, karta dla każdej strony.
URL docelowy: https://10s.pl/<projekt>/
' --auto

# Dashboard
opencode run --prompt '
Stwórz /var/www/projects/<projekt>/dashboard/index.html — Dashboard pacjenta normobarii.

Z phase-3-report.md:
- Cel: Podgląd postępów
- Navbar u góry z linkami do /dashboard, /sessions, /profile, /settings
- Karta "Postęp terapii" z paskiem postępu 60% i tekstem "12 z 20 sesji"
- Karta "Statystyki" z 3 liczbami: ukończone sesje (12), czas (24h), compliance (85%)
- Tabela "Ostatnie sesje" z kolumnami: Data, Czas, Ciśnienie, Wynik
- Przycisk "Dodaj sesję" → link do /sessions/new
- Stopka "Mockup v1 — dane testowe"

Wszystkie linki wewnętrzne prowadzą do innych stron prototypu.
URL: https://10s.pl/<projekt>/dashboard/
' --auto

Krok 3.3: Automatyzacja przez opencode batch

Dla projektu z 5-10 stronami, CEO może stworzyć jeden task dla opencode, który wygeneruje wszystkie strony naraz:

opencode run --prompt '
Stwórz kompletny prototyp HTML aplikacji do harmonogramu normobarii.

Na podstawie pliku .superpowers/sdd/phase-3-report.md, wygeneruj
WSZYSTKIE strony jako osobne pliki HTML w /var/www/projects/<projekt>/.

Wymagania:
1. Każda strona ma swój katalog i index.html
2. Wszystkie linki wewnętrzne prowadzą do innych stron prototypu
3. Spójny design (ten sam navbar, footer, kolory, font)
4. Realistyczne dane mockowe (imiona, daty, wartości)
5. Responsywny layout (działa na mobile i desktop)
6. Zero zależności zewnętrznych (brak CDN, backendu, JS frameworks)
7. Każda strona ma nagłówek "Prototyp v1 — dane testowe do zatwierdzenia"

Po wygenerowaniu wszystkich stron, stwórz plik /var/www/projects/<projekt>/index.html
z listą wszystkich stron i linkami.

Zweryfikuj że każda strona ma HTTP 200 przed zakończeniem.
' --auto

Faza 4: Prototyp do klikania

Po wygenerowaniu wszystkich stron, CEO weryfikuje że prototyp jest w pełni klikalny.

Krok 4.1: Weryfikacja struktury

# Sprawdź czy wszystkie strony istnieją
ls -la /var/www/projects/<projekt>/*/index.html

# Sprawdź HTTP 200 dla każdej strony
for path in /dashboard /sessions /sessions/123 /profile /settings; do
  curl -s -o /dev/null -w "HTTP %{http_code}\n" --max-time 5 "https://10s.pl/<projekt>$path/"
done

Krok 4.2: Weryfikacja linków wewnętrznych

# Sprawdź czy wszystkie linki wewnętrzne prowadzą do istniejących stron
for url in $(grep -roP 'href="/<projekt>/[^"]*"' /var/www/projects/<projekt>/ | grep -oP '/<projekt>/[^"]*' | sort -u); do
  echo -n "$url → "
  curl -s -o /dev/null -w "%{http_code}\n" --max-time 5 "https://10s.pl$url"
done

Krok 4.3: Raport do zatwierdzenia

Po weryfikacji, CEO tworzy raport dla użytkownika:

hermes kanban --board convertere comment <card-id> \
  "[CEO] ✅ Prototyp gotowy do klikania:
- Strona główna: https://10s.pl/<projekt>/
- Dashboard: https://10s.pl/<projekt>/dashboard/
- Sesje: https://10s.pl/<projekt>/sessions/
- Profil: https://10s.pl/<projekt>/profile/
- Ustawienia: https://10s.pl/<projekt>/settings/

Status: ✅ Wszystkie strony HTTP 200
Status: ✅ Wszystkie linki wewnętrzne działają
Status: ⏳ Czekam na zatwierdzenie wizualne przed backendem"

Faza 5: Implementacja backendu

Po zatwierdzeniu prototypu przez użytkownika, zaczyna się właściwa implementacja.

Krok 5.1: Konfiguracja projektu

# Inicjalizacja projektu z superpowers SDD
mkdir -p /root/projects/<projekt>
cd /root/projects/<projekt>
git init

# Uruchom opencode z superpowers w projekcie
opencode run --prompt "
Zainicjalizuj projekt z superpowers SDD:
1. Utwórz .superpowers/sdd/ z katalogiem
2. Skopiuj phase-1/2/3-report.md do .superpowers/sdd/
3. Utwórz task-1-brief.md dla backendu (API endpoints z phase-2-report.md)
4. Utwórz task-2-brief.md dla bazy danych (schema z phase-2-report.md)
5. Utwórz task-3-brief.md dla integracji frontend-backend (HTML z phase-3)
" --auto

Krok 5.2: Implementacja przez SDD taski

Każdy task z SDD to osobne zadanie dla opencode:

# Task 1: Backend API
opencode run --prompt '
Zaimplementuj backend API dla projektu <projekt>.

Na podstawie .superpowers/sdd/task-1-brief.md:
- Framework: [np. FastAPI, Express, Django]
- Endpoints z phase-2-report.md
- Walidacja danych
- Error handling
- Testy (pytest lub jest)

Po implementacji: uruchom testy i zweryfikuj że wszystkie przechodzą.
' --auto

# Task 2: Baza danych
opencode run --prompt '
Zaimplementuj warstwę bazy danych dla projektu <projekt>.

Na podstawie .superpowers/sdd/task-2-brief.md:
- Schema z phase-2-report.md
- Migracje
- Seed data (mockowe dane)
- Query helpers

Po implementacji: sprawdź czy migracje działają i dane seedują się poprawnie.
' --auto

# Task 3: Integracja frontend-backend
opencode run --prompt '
Zintegruj frontend HTML z backendem API.

Na podstawie .superpowers/sdd/task-3-brief.md:
- Zastąp mock data w HTML rzeczywistymi danymi z API
- Dodaj fetch/axios calls
- Obsługa błędów (loading, error, empty states)
- Zachowaj design z prototypu

Po implementacji: sprawdź czy wszystkie strony ładują dane z API.
' --auto

Pełny pipeline — komendy skrócone

Dla szybkiego startu, CEO może uruchomić cały pipeline jednym taskiem opencode:

# 1. Przygotuj katalog projektu
mkdir -p /root/projects/<projekt>
cd /root/projects/<projekt>
git init

# 2. Zapisz specyfikację pomysłu
echo '# <Nazwa projektu>
## Dla kogo: <persona>
## Co robi: <funkcja>
## Czego chce: <problem>' > IDEA.md

# 3. Uruchom opencode z superpowers — wygeneruje wszystkie specyfikacje
opencode run --prompt '
Przeczytaj IDEA.md. Wykonaj pełny Builder Flow:

Faza 1: Specyfikacja
- phase-1-brief.md → phase-1-report.md (biznesowa)
- phase-2-brief.md → phase-2-report.md (techniczna: lista URL-i, schema, API)
- phase-3-brief.md → phase-3-report.md (wizualna: każda strona z URL-em i komponentami)

Faza 2-3: HTML mockupy
- Wygeneruj HTML dla każdej strony z phase-3 w /var/www/projects/<projekt>/
- Każda strona pod swoim URL-em
- Realistyczne mock dane
- Spójny design, wszystkie linki wewnętrzne działają

Faza 4: Weryfikacja
- Sprawdź HTTP 200 dla każdej strony
- Sprawdź wszystkie linki wewnętrzne
- Stwórz plik VERIFICATION.md z wynikami

Po zakończeniu: wypisz wszystkie URL-e prototypu.
' --auto

Case study: Aplikacja harmonogramu normobarii

Pomysł: Aplikacja dla pacjentów centrum normobarii, która pokazuje harmonogram sesji i postępy terapii.

Przebieg:

Łączny czas od pomysłu do działającego prototypu: ~20 minut.

Łączny czas do pełnej implementacji: ~1 godzina.

Ryzyka i wyzwania

Ryzyko 1: Opencode nie generuje obrazów

kimi-k2-7-code to model kodowania, nie generowania obrazów. HTML/CSS mockup wygląda jak strona, ale nie jest screenshotem.

Rozwiązanie: Użyj HTML/CSS zamiast obrazów — to szybsze i dokładniejsze. Dla rzeczywistych screenshotów: otwórz w headless Chrome i zrób zrzut.

Ryzyko 2: SDD taski mogą być zbyt ogólne

Superpowers SDD generuje briefy, ale ich jakość zależy od jakości prompta.

Rozwiązanie: Im bardziej szczegółowy brief, tym lepszy raport. CEO powinien spędzić 5 minut na doprecyzowaniu briefu przed uruchomieniem opencode.

Ryzyko 3: Dużo stron = dużo czasu

Projekt z 20+ stronami to 20+ osobnych plików HTML. Opencode może generować 1-2 strony na minutę.

Rozwiązanie: Uruchom opencode z jednym promptem, który wygeneruje wszystkie strony naraz. To zużywa więcej tokenów ale jest szybsze.

Ryzyko 4: Brak konsystencji między stronami

Każda strona generowana osobno może mieć inny design (inne kolory, marginesy, fonty).

Rozwiązanie: Zdefiniuj wspólny CSS na początku. Użyj prompta: "Użyj tych samych kolorów: primary #2563eb, secondary #f8fafc, font system-ui. Wszystkie strony mają ten sam navbar i footer."

Ryzyko 5: Użytkownik nie klika prototypu

Największe ryzyko — robisz prototyp, a użytkownik mówi "ok, zrób backend" bez klikania.

Rozwiązanie: Nie zaczynaj backendu, dopóki nie dostaniesz wyraźnego zatwierdzenia każdej strony. Postaw warunek: "Kliknij wszystkie strony i powiedz czy coś zmienić. Po zatwierdzeniu zaczynam backend."

Playbook: 30-minutowy Builder Flow

Cel: Od pomysłu do klikalnego prototypu w 30 minut

Przygotowanie (5 min):

• [ ] Opisz pomysł w 1 zdaniu
• [ ] Stwórz katalog projektu: mkdir -p /root/projects/<projekt> && cd $_ && git init
• [ ] Zapisz IDEA.md
• [ ] Stwórz kanban task

Specyfikacja (10 min):

• [ ] Uruchom opencode z superpowers (Faza 1: 3 specyfikacje naraz)
• [ ] Czekaj na zakończenie (3-5 min)
• [ ] Przeczytaj phase-1/2/3-report.md — czy wszystko ma sens?
• [ ] Jeśli nie → popraw brief i uruchom ponownie

HTML mockupy (10 min):

• [ ] Uruchom opencode z promptem "wygeneruj wszystkie strony HTML"
• [ ] Czekaj na zakończenie (5-8 min)
• [ ] Ustaw uprawnienia: chmod -R 755 /var/www/projects/<projekt>/

Weryfikacja (5 min):

• [ ] Sprawdź HTTP 200 dla każdej strony
• [ ] Sprawdź linki wewnętrzne
• [ ] Sprawdź design (czy spójny, czy ładny)
• [ ] Zgłoś użytkownikowi URL-e
• [ ] Czekaj na zatwierdzenie przed backendem

Mierzenie sukcesu

Czy Builder Flow jest dla każdego?

Przyszłość / Rozwój

v1 → v2: Co można dodać

• Automatyczne screenshoty — headless Chrome po wygenerowaniu HTML robi screenshoty każdej strony
• Design system — superpowers SDD generuje wspólny CSS zamiast inline w każdej stronie
• Interaktywne mockupy — dodanie JS do mockupów (kliknięcia, hover, podstawowe animacje)
• Feedback loop — użytkownik klika prototyp, CEO widzi które strony są nieklikane (analytics)
• Automatyczne testy wizualne — porównanie screenshotów prototypu z finalną implementacją
• Multi-wariant — superpowers generuje 3 warianty designu, użytkownik wybiera

Integracja z istniejącymi narzędziami

• Figma → superpowers — export Figma do JSON → superpowers SDD jako brief wizualny
• superpowers → opencode — SDD taski automatycznie uruchamiają opencode z promptem
• opencode → 10s.pl — automatyczny deploy na r.10s.pl po wygenerowaniu mockupów

Źródła (Linki URL)

• superpowers — obra/superpowers GitHub
• opencode — kimi-k27/code
• Hermes Agent — Nous Research
• 10s.pl — platforma hostingowa
• r.10s.pl — raporty i dokumentacja
• Builder Flow v1 — ten raport

Źródła (Pliki)

• /root/.config/opencode/opencode.json — konfiguracja opencode (model kimi-k2-7-code, superpowers plugin)
• /root/.hermes/profiles/ceo/skills/devops/opencode-delegation/SKILL.md — skill delegacji do opencode
• /root/.hermes/profiles/ceo/skills/devops/delegation-todo-workflow/SKILL.md — Kanban workflow
• /root/.hermes/profiles/ceo/skills/devops/10s-pl-deploy/SKILL.md — deploy na 10s.pl
• /root/.local/share/opencode/log/opencode.log — log opencode