agency-skills-suite/agency-orchestrator/SKILL.md

name

description

agency-orchestrator

Coordinare agenti, gestire decisioni e qualità per i 5 workflow della suite. Usare quando: (1) avviare nuovo progetto/cliente, (2) attivare uno dei workflow (Analisi, Posizionamento Strategico, Sito Web Aziendale, Landing Page di Prodotto, Strategia Social), (3) coordinare output di più agenti, (4) gestire decisioni, (5) eseguire QA trasversale, (6) gestire upload risorse (immagini, video, asset) tramite agency-archivist. Accetta in input sia questionario di onboarding sia documento company profile (estrazione automatica). Output: Decision log, QA notes, stato progetto.

Agency Orchestrator — Coordinamento Multi-Agente

Coordina agenti e mantiene stato (decisioni/QA) per eseguire i workflow della suite in modo efficiente.

Quando Usare

• Nuovo progetto: Avviare onboarding cliente e definire workflow
• Coordinamento: Consolidare output di più agenti (strategy, design, content)
• Gestione progetto: Monitorare avanzamento workflow
• QA trasversale: Verificare qualità deliverable prima di publish

---

I 5 Workflow della Suite

Questa skill coordina 5 workflow principali:

Workflow	Descrizione	Skills Coinvolte
Analisi	Research competitivo e audit completo	agency-research, agency-analytics
Posizionamento Strategico	Positioning, messaging, content pillars	agency-strategy, agency-creative-director
Sito Web Aziendale	Sito completo da sitemap a publish	agency-ux-copy, agency-design-system, agency-web-developer, agency-seo
Landing Page di Prodotto	Landing page conversion-focused	agency-ux-copy, agency-design-system, agency-web-developer
Strategia Social	Piano editoriale e content calendar	agency-social, agency-youtube, agency-visual-generator

---

Input — Due Modalità di Onboarding

Questa skill accetta due modalità di input per avviare il workflow:

Modalità A: Questionario di Onboarding (Tradizionale)

Raccogliere queste informazioni tramite domande dirette al cliente:

1. Informazioni Base Cliente

Campo	Tipo	Esempio	Note
Nome cliente/azienda	string	"Demo Co SRL"	Ragione sociale o nome progetto
Settore/Industry	string	"E-commerce fashion B2B"	Categoria principale
Sito web attuale	URL	https://democo.it	Se esiste, per analisi
Social esistenti	array	Instagram, LinkedIn	Piattaforme attive
Contatto principale	string	marco@democo.it	Email o telefono

2. Obiettivi e Aspettative

Campo	Tipo	Esempio	Note
Obiettivo primario	string	"Aumentare lead qualificati"	Cosa vuole ottenere
Obiettivi secondari	array	Brand awareness, SEO	Altri goal
Timeline attesa	string	"V1 entro 4 settimane"	Deadline o milestone
Budget indicativo	string	"€5-10K"	Range budget (opzionale)

3. Audience e Mercato

Campo	Tipo	Esempio	Note
Target primario	string	"Founder PMI 35-55 anni"	ICP principale
Target secondario	string	"PM B2B tech"	Audience secondaria
Competitor diretti	array	Competitor A, Competitor B	2-5 competitor
Differentiatori	array	"Servizio 24/7, prezzi chiari"	Punti di forza unici

4. Offerta e Servizi

Campo	Tipo	Esempio	Note
Servizi principali	array	Consulenza, Formazione, Supporto	Core offerings
Prodotti flagships	array	"Corso X, Tool Y"	Prodotti principali
Pricing model	string	"Subscription €99/mese"	Come monetizza

5. Preferenze e Vincoli

Campo	Tipo	Esempio	Note
Tone of voice	string	"Professionale ma amichevole"	Stile comunicazione
Brand colors	array	"#FF5733, #003366"	Colori brand (se noti)
Vincoli/Note	string	"No stock photo, solo foto reali"	Restrizioni o preferenze

6. Workflow e Agenti Richiesti

Campo	Tipo	Esempio	Note
Workflow da eseguire	string	Sito Web Aziendale, Strategia Social	Uno dei 5 workflow (vedi tabella sopra)
Agenti necessari	array	strategy, design, ux-copy, web-developer	Skills da attivare
Priorità	string	"Veloce" o "Dettagliato"	Approccio preferito

Modalità B: Documento Company Profile (Estrazione Automatica)

In alternativa al questionario, l'orchestratore può accettare un documento esistente che descrive il company profile del cliente.

Formati supportati:

• Markdown (.md)
• PDF (.pdf)
• Documenti Word (.docx)
• Presentazioni (.pptx)
• Testo strutturato (.txt)

Informazioni da estrarre automaticamente:

L'orchestratore deve leggere il documento ed estrarre tutte le informazioni rilevanti mappandole ai campi del questionario:

Campo da Estrazione	Cosa Cercare nel Documento
Nome cliente/azienda	Ragione sociale, nome progetto, intestazioni
Settore/Industry	Descrizioni business, categorie merceologiche
Sito web attuale	URL, link, riferimenti web
Social esistenti	Menzioni di piattaforme social, handle, link
Contatto principale	Email, telefono, persone di riferimento
Obiettivi	Goal strategici, KPI, target di business
Timeline/Budget	Deadline, budget, vincoli temporali
Target/Audience	ICP, buyer personas, segmenti di mercato
Competitor	Nomi competitor, analisi competitive
Differentiatori	USP, punti di forza, vantaggi competitivi
Servizi/Prodotti	Catalogo offerte, prodotti flagship, pricing
Tone of Voice	Linee guida comunicazione, stile brand
Brand Colors/Assets	Palette colori, linee guida visive
Vincoli/Note	Restrizioni, preferenze, requisiti speciali

Procedura di Estrazione:

1. Ricevi documento: L'utente fornisce path o carica il file
2. Leggi documento: Usa read o strumenti appropriati per il formato
3. Estrai informazioni: Mappa contenuti ai campi del questionario
4. Valida estrazione: Verifica che tutti i campi critici siano presenti
5. Proponi riepilogo: Mostra all'utente i dati estratti in formato strutturato
6. Chiedi conferma: "Ho estratto questi dati dal documento. Procedo o vuoi correggere qualcosa?"
7. Dopo conferma: Prosegui con Fase 1 (Setup Progetto)

Gestione campi mancanti:

• Se un campo non è trovabile nel documento, fai un'assunzione ragionevole basata sul contesto
• Documenta tutte le assunzioni in {project}/ops/decisions.md
• Segnala all'utente i campi con assunzioni e chiedi conferma o correzione prima di procedere

Vantaggi Modalità B:

• ✅ Risparmia tempo al cliente (nessun questionario da compilare)
• ✅ Sfrutta documentazione esistente (business plan, pitch deck, website copy)
• ✅ Maggiore accuratezza (dati già validati e strutturati)
• ✅ Professionalità (lavora con materiali ufficiali del cliente)

---

Processo

Fase 1: Setup Progetto e Avvio Workflow

Obiettivo: Creare struttura cartelle cliente e avviare workflow.

Azioni:

1. Ricevi input (Modalità A o B):

   • Modalità A (Questionario): Usa dati compilati dal cliente
   • Modalità B (Documento): Estrai informazioni automaticamente (vedi sezione sopra)

2. Proposta path progetto:

   • Proponi: {project}/ (es. {nome_cliente_lowercase}/ o nome progetto)
   • Esempio: demo_co_srl/ oppure campagna_prodotto_x/
   • Chiedi conferma esplicita prima di procedere

3. Dopo conferma, crea struttura cartelle:

   {project}/
   ├── knowledge/        (company profile, audience, brand)
   ├── research/         (competitor, market insights)
   ├── strategy/         (positioning, messaging, pillars)
   ├── design/           (design system, assets)
   ├── content/          (copy, social, video scripts)
   ├── ops/              (decisions, QA, run log)
   ├── published/        (content pubblicato, versionato)
   └── assets/           (immagini, video, documenti — gestito da agency-archivist)
   

4. Leggi ../agency-shared-references/references/quality_bar.md per standard di qualità

5. Registra assunzioni in {project}/ops/decisions.md

6. (Opzionale) Upload risorse:

   • Chiedi: "Hai un archivio di risorse (immagini, logo, brand assets) da caricare?"
   • Se SI: Ricevi zip/URL e triggera agency-archivist
   • Workflow:

     a. agency-archivist estrae archivio in {project}/assets/
     b. Scansiona risorse e genera metadata
     c. Crea catalog.md con descrizione e tag
     d. Notifica orchestrator: "✅ Risorse pronte"
     

   • Se NO: Prosegui senza assets (altre skill useranno placeholder)
   • Include dati estratti (se Modalità B) o compilati (se Modalità A)
   • Documenta eventuali assunzioni su campi mancanti

7. Avvia workflow selezionato coordinando gli agenti necessari

Regole:

• ✅ Non bloccare per input mancanti: fai assunzioni ragionevoli e documentale
• ✅ Tracciabilità: ogni decisione va nel decision log
• ✅ Modalità B: Se estrazione da documento, valida che i dati siano coerenti prima di procedere

---

Fase 2: Coordinamento Agenti

Obiettivo: Assegnare task e monitorare progresso.

Azioni:

1. Per ogni agente necessario:
   • Verifica input disponibili
   • Assegna task con definizione degli obbiettivi chiara
   • Imposta deadline interna
2. Monitora stato avanzamento
3. Risolvi conflitti o dipendenze bloccanti

Agenti tipici:

• agency-strategy → positioning, messaging
• agency-research → competitor, reference
• agency-creative-director → direzione visiva
• agency-ux-copy → sitemap, page copy
• agency-design-system → design system
• agency-archivist → upload, estrazione, catalogazione risorse
• agency-visual-generator → asset (usa risorse da archivist)
• agency-social / agency-youtube → content

---

Fase 3: Consolidamento e QA

Obiettivo: Verificare coerenza output e qualità.

Azioni:

1. Raccogli output da tutti gli agenti
2. Verifica coerenza cross-deliverable
3. Esegui QA checklist (vedi ../agency-shared-references/references/quality_bar.md)
4. Crea {project}/ops/qa_notes.md con issue + fix proposti

QA Checklist:

• Output in path corretto
• Frontmatter presente e valido
• Fonti loggate (se richiesto)
• QA specifico compilato (es. qa_website.md)

---

Fase 4: Publish Gate

Obiettivo: Gestire approvazione pre-publish e publish manuale.

Azioni:

1. Verifica che i file content abbiano APPROVED: YES nel frontmatter
2. Verifica che esista PUBLISH_APPROVED.md con valore YES
3. Verifica che QA sia compilato e passato
4. Publish manuale: Aggiorna {project}/ops/publish_log.md dopo publish
5. Aggiorna frontmatter dei content file con status: published e published_at

Regola: Mai publish senza APPROVED: YES esplicito.

Template publish_log.md:

# Publish Log — {Client}

| Data | Platform | Content ID | Status | URL | Note |
|------|----------|------------|--------|-----|------|
| 2026-03-11 | LinkedIn | post_001 | Published | https://... | Engagement buono |

---

Gestione Risorse — Integrazione agency-archivist

Quando Chiamare agency-archivist

• Cliente fornisce brand assets: Logo, foto prodotto, team, ufficio
• Serve materiale visivo per agency-visual-generator: Immagini per social post, ads
• Serve documentazione per agency-research: Brand guidelines, schede prodotto
• Mancano risorse per completare un task: Una skill segnala risorse mancanti

Workflow di Upload

1. Orchestrator riceve input (zip allegato o URL)
   ↓
2. Triggera agency-archivist con:
   - Path file o URL
   - Nome cliente
   ↓
3. agency-archivist esegue:
   - Estrazione in {project}/assets/
   - Scansione e catalogazione
   - Generazione catalog.md
   ↓
4. Archivist notifica orchestrator: "✅ Risorse pronte"
   ↓
5. Orchestrator sblocca skill in attesa:
   - agency-visual-generator
   - agency-design-system
   - agency-web-developer
   - agency-social

Comportamento Proattivo di Archivist

Quando una skill richiede risorse mancanti:

Esempio: agency-visual-generator deve creare social post ma mancano foto prodotto

**Flusso:**
1. Visual-generator legge catalog.md
2. Non trova immagini prodotto → "🔒 Bloccato: servono foto prodotto"
3. Tagga @agency-archivist con requisiti:
   - Foto prodotto (sfondo bianco, minimo 1000x1000px)
   - Logo aziendale (PNG trasparente)
4. Archivist risponde:
   "⚠️ **Risorse Mancanti**
   
   Per eseguire [social post], servono:
   - [ ] Foto prodotto (sfondo bianco, minimo 1000x1000px)
   - [ ] Logo aziendale (PNG trasparente)
   
   **Vuoi caricare queste risorse ora?**"
5. Dopo upload: Re-scan e aggiornamento catalogo
6. Archivist sblocca: "✅ Risorse pronte, puoi procedere @agency-visual-generator"

Struttura Cartelle Assets

{project}/assets/
├── archive/          # Archivi originali (zip, tar)
├── images/           # Immagini estratte
│   ├── logo/         # Loghi aziendali
│   ├── prodotto/     # Foto prodotto
│   ├── team/         # Foto team/ufficio
│   └── stock/        # Immagini generiche
├── videos/           # Video estratti
│   ├── promo/        # Video promozionali
│   └── tutorial/     # Tutorial/dimostrazioni
├── documents/        # Documenti di riferimento
│   ├── brand/        # Linee guida brand
│   └── product/      # Schede prodotto
└── catalog.md        # Catalogo generato (indice centrale)

Pattern per Altre Skill

Prima di eseguire task che richiedono asset:

1. Leggi `{project}/assets/catalog.md`
2. Cerca risorse per tag/tipo/descrizione
3. Se trovi: Usa path completo
4. Se NON trovi: 
   - "🔒 Bloccato: servono [descrizione risorse]"
   - Tagga: @agency-archivist
   - Specifica: Requisiti tecnici (es. "minimo 1000x1000px, JPG")
   - Attendi: Sblocco da archivist

Script di Riferimento

• scripts/extract_archive.js — Estrazione zip/URL
• scripts/scan_resources.js — Scansione metadata
• scripts/generate_catalog.js — Generazione catalogo

---

Output

File	Formato	Descrizione
{project}/ops/decisions.md	Markdown	Decisioni e assunzioni
{project}/ops/qa_notes.md	Markdown	Issue QA + fix proposti
{project}/ops/run_log.md	Markdown	Log operativo (opzionale)

---

References

• quality_bar.md — Standard V1
• research_citation_rules.md — Citazione fonti
• resource_types.md — Tipologie risorse e use case

---

Note

Edge Cases:

• Input mancanti: Fai assunzioni ragionevoli, documenta in decision log, procedi
• Conflitti tra agenti: Orchestratore decide in base alle priorità del progetto
• QA fallisce: Documenta issue in qa_notes.md e prosegui con fix

Limitazioni:

• Questa skill non esegue direttamente il lavoro degli agenti specialistici
• Richiede che gli altri agenti siano disponibili/eseguibili
• Publish richiede integrazione webhook configurata

---

Agency Skills Suite v1.0