Workflows con Cascade

In questa lezione, esploreremo approfonditamente il concetto di Workflows all’interno di Cascade di Windsurf, come li definiamo, come li creiamo e come li sfruttiamo per automatizzare compiti ripetitivi e complessi. Procederemo in modo pratico, condividendo esempi, casi d’uso reali, consigli e alcune best practice che ci aiuteranno a integrare i workflows nelle nostre attività quotidiane di sviluppo e collaborazione.

Cascade: cos’è un Workflow

Quando lavoriamo con Cascade, spesso ci troviamo a ripetere una serie di azioni o task. Ad esempio, il deploy di un servizio, la risposta a commenti su una Pull Request, o una serie di comandi per la gestione di dipendenze. In modo semplice, un Workflow è una definizione strutturata. Una serie sequenziale di passi che guida Cascade nel compimento di queste attività.

Questa definizione non è un semplice elenco di operazioni, ma un flusso di istruzioni riutilizzabile e ripetibile. I workflows ci permettono di codificare processi ripetitivi come file Markdown che poi possiamo richiamare facilmente con un comando prefixato da slash (ad esempio: /nome-workflow).

I Workflows estendono quindi il concetto di regole che forniamo a grandi modelli linguistici: mentre le regole danno un contesto persistente e riutilizzabile sul livello del prompt, i workflows forniscono una sequenza strutturata di prompt e step a livello di traiettoria guidando il modello passo dopo passo attraverso un processo complesso.

Come i Workflows si integrano con Cascade

Come già annunciato precedentemente, quando eseguiamo un workflow in Cascade, non stiamo solo chiedendo a un modello di rispondere a un prompt: stiamo istruendo Cascade a seguire una serie di passi prestabiliti.

Ecco come funziona:

1. Invocazione: chiamiamo il workflow con un comando slash: /nome-workflow.

2. Elaborazione: Cascade legge l’elenco di passi definiti nel workflow e li elabora in sequenza.
3. Azione: per ogni passo, Cascade svolge l’azione richiesta o genera la risposta desiderata.
4. Output: al termine, otteniamo il risultato complessivo dell’intera sequenza.

Una caratteristica potente è la possibilità di chiamare altri workflows all’interno di un workflow stesso. In pratica, possiamo costruire flussi di lavoro modulari e annidarli tra loro: un workflow principale può invocare sotto-workflows che risolvono parti specifiche del processo, rendendo l’intera struttura più leggibile e manutenibile.

Per essere utilizzabili da Cascade, i workflows devono essere salvati in file Markdown con estensione .md e devono trovarsi in specifiche directory che Cascade riconosce automaticamente.

Ecco i percorsi di ricerca:

• Cartella .windsurf/workflows/ nel workspace attuale.
• Sottodirectory .windsurf/workflows/ ovunque all’interno del nostro workspace.
• Cartelle .windsurf/workflows/ verso l’alto fino alla radice di un repository Git (quando si lavora con Git).

Cascade esplora questi percorsi per trovare tutti i workflows disponibili, li deduplica (se necessario) e li mette a disposizione per l’esecuzione tramite slash command.

Nota importante: ogni file workflow ha un limite di circa 12.000 caratteri, quindi dobbiamo essere consapevoli della dimensione dei nostri script MD.

Come creare un Workflow in Cascade

 Creare un workflow in Cascade è un’attività relativamente semplice, ma richiede attenzione, metodo e una buona organizzazione per essere davvero efficace nel tempo. Nel nostro flusso di lavoro iniziamo accedendo all’interfaccia di Cascade e aprendo il pannello Workflows, che troviamo all’interno della sezione Customizations, solitamente posizionata nell’angolo in alto a destra dell’ambiente di lavoro.

Da qui possiamo gestire tutti i flussi esistenti oppure crearne di nuovi. Per avviare la creazione di un workflow, utilizziamo il pulsante + Workflow, che ci guida nella definizione degli elementi fondamentali: il nome del workflow, una descrizione chiara del suo scopo e, soprattutto, la struttura dei passi che lo compongono. Questi passi vengono generalmente definiti in un file Markdown (.md), che rappresenta il cuore del workflow.

All’interno del file specifichiamo un titolo esplicativo, una descrizione che chiarisca cosa fa il workflow e una sequenza ordinata di istruzioni pensate per essere comprensibili, ripetibili e facilmente mantenibili nel tempo.

Una volta completata la definizione del contenuto i workflows di Cascade ci permettono di scegliere tra due modalità di esecuzione, la Safe Mode e la Turbo Mode. Queste, sono due modalità di esecuzione opposte che controllano quanto Cascade deve essere prudente oppure aggressivo/autonomo mentre segue i passi del workflow. Possiamo vederle come due estremi dello spettro dell’execution mode.

Il Safe Mode è la modalità più conservativa e controllata. Quando un workflow viene eseguito in safe mode, Cascade privilegia la sicurezza, la chiarezza e il controllo umano rispetto alla velocità.

Il Turbo Mode è l’esatto opposto e infatti Cascade interpreta il workflow come una sequenza di istruzioni da eseguire nel modo più diretto possibile, riducendo al minimo le interruzioni.

Una volta completato il contenuto del Workflow, salviamo il file nella directory corretta (se il workflow si trova in una delle cartelle riconosciute da Windsurf, Cascade lo individua automaticamente senza bisogno di ulteriori configurazioni). A questo punto possiamo testarlo immediatamente invocandolo con un semplice comando slash, come /nome-workflow, verificando che ogni passaggio venga eseguito correttamente e apportando eventuali correzioni prima di adottarlo stabilmente nel nostro processo di lavoro.

Un esempio molto semplice e concreto di definizione di un workflow in Cascade, pensato per essere facile da capire anche al primo utilizzo, potrebbe essere un workflow chiamato che controlla e formatta il codice prima di fare un commit. Per esempio:

# format-code
Questo workflow formatta il codice del progetto e segnala eventuali problemi
prima di effettuare un commit.
## Steps
1. Analizza i file modificati nel repository.
2. Identifica il linguaggio principale del progetto.
3. Applica il formatter appropriato (es. Prettier, Black, o equivalente).
4. Esegue un controllo di linting sui file formattati.
5. Se ci sono errori non risolvibili automaticamente, fermati e segnalali.
6. Riassumi le modifiche effettuate e indica se il codice è pronto per il commit.

Una volta salvato il file nella cartella corretta, possiamo eseguire il workflow semplicemente scrivendo in Cascade:

/format-code

Cascade leggerà il file Markdown e seguirà i passi uno dopo l’altro, rispettando l’execution mode attivo (safe mode o turbo mode).

Conclusioni

In questa lezione abbiamo imparato che i Workflows con Cascade sono strumenti potenti per automatizzare compiti ripetitivi, standardizzare processi e aumentare l’efficienza del team. Attraverso Markdown strutturati e invocazioni con il comando slash /nome-workflow, possiamo trasformare una serie di step manuali in una procedura ripetibile e condivisibile.