Benvenuto nel .agent-framework, il "motore" del nostro sistema di sviluppo guidato dall'AI. Questa cartella contiene tutta la logica, la configurazione e i template che permettono al nostro workflow di funzionare.
Creare un framework di sviluppo software che orchestra il lavoro di agenti AI dall'idea iniziale fino alla Pull Request, mantenendo il controllo strategico umano, la robustezza e la completa tracciabilità del lavoro.
Il nostro sistema supporta due scenari principali:
- FASE 0: Definizione (
/workspace:setup): L'AI guida l'utente nella creazione della documentazione di base (docs/). - FASE 1: Pianificazione (
/plan:*): L'AI analizza la documentazione e genera un backlog dettagliato (features/). - FASE 2: Esecuzione (
/run:*): L'AI scrive il codice insrc/, seguendo il backlog. - FASE 3: Revisione e Finalizzazione (
/refine:story,/complete:story): L'utente revisiona il codice, chiede modifiche e l'AI finalizza il lavoro con una Pull Request.
- FASE 0: Mappatura (
/onboard:map): L'AI analizza la struttura del codebase e crea un piano di onboarding inreports/. - FASE 1: Onboarding Autonomo (
/onboard:run): L'AI esegue il piano in una reazione a catena, analizzando il codice, generando la documentazione (docs/) e un backlog dello stato attuale (features/con statusbaseline).
La struttura del progetto non è arbitraria, ma viene generata e gestita dagli agenti AI seguendo un insieme di regole formali. Questo approccio garantisce coerenza, prevedibilità e automazione.
La fonte di verità per tutte le convenzioni di naming e di struttura è definita nel file .spec/project_structure.md.
Di seguito è riportato un esempio completo della struttura risultante:
/tuo-progetto
│
├── .spec/ # Il "motore" del sistema. Definisce le specifiche di comportamento degli agenti.
│ ├── commands/ # Logica dei comandi che l'utente può eseguire, raggruppati per dominio.
│ │ ├── onboard_generate-backlog.md
│ │ ├── onboard_generate-docs.md
│ │ ├── onboard_map.md
│ │ ├── onboard_run.md
│ │ ├── onboard_scan.md
│ │ ├── plan_epic-stories.md
│ │ ├── plan_epic.md
│ │ ├── plan_mvp.md
│ │ ├── plan_story.md
│ │ ├── run_epic.md
│ │ ├── run_story.md
│ │ ├── workspace_refactor.md
│ │ ├── workspace_setup.md
│ │ ├── workspace_status.md
│ │ ├── complete_story.md
│ │ ├── fix_bug.md
│ │ └── refine_story.md
│ │
│ ├── templates/ # Template usati dagli agenti per generare artefatti.
│ │ ├── docs/ # Template per /workspace:setup e /onboard:generate-docs.
│ │ │ ├── architecture/ # Template per i dettagli architetturali.
│ │ │ │ ├── api-contract.md
│ │ │ │ ├── c4-diagrams.md
│ │ │ │ └── schema.md
│ │ │ ├── requirements.md
│ │ │ ├── setup-dev.md
│ │ │ └── setup-prod.md
│ │ │
│ │ └── plans/ # Template per /plan:* e /onboard:generate-backlog.
│ │ ├── plan_epic_template.md
│ │ ├── plan_story_template.md
│ │ ├── plan_workplan_template.md # Template per il piano di lavoro
│ │ └── plan_task_template.md # Template per le singole descrizioni dei task (senza stato)
│ │
│ ├── glossary.md # Vocabolario condiviso per termini tecnici e agili.
│ └── project_structure.md # Le regole formali per la struttura di file e cartelle.
│
├── docs/ # OUTPUT di /workspace:setup o /onboard:run. La definizione STATICA del progetto.
│ ├── requirements.md # Requisiti (il "cosa").
│ ├── setup-dev.md # Guida all'ambiente di sviluppo locale.
│ ├── architecture/ # Dettagli dell'architettura (il "come").
│ │ ├── api-contract.md
│ │ ├── c4-diagrams.md
│ │ └── schema.sql
│ └── api/ # (DEPRECATO, ora in architecture/)
│
├── features/ # OUTPUT di /plan:* o /onboard:run. Il backlog VIVO e DINAMICO.
│ └── 001-authentication/
│ ├── plan.md # Piano dell'Epic con le story dettagliate.
│ └── stories/
│ ├── 001-user-login.md # File della User Story.
│ ├── 001_workplan.md # Piano di lavoro per la story 001 (contiene lo stato dei task).
│ └── 001_tasks/ # Cartella dei task tecnici per la story 001 (contengono solo descrizioni).
│ ├── 01_create_user_model.md
│ └── 02_setup_auth_endpoint.md
│
├── reports/ # OUTPUT di comandi di analisi, cruciale per l'onboarding.
│ ├── onboarding_plan.md # Piano di esecuzione generato da /onboard:map.
│ └── onboarding_analysis_...md # Report intermedi generati da /onboard:scan.
│
└── src/ # OUTPUT di /run:*. Il codice sorgente dell'applicazione.
└── index.js
- /workspace:setup: Avvia la creazione guidata della documentazione.
- /workspace:status: Mostra lo stato di avanzamento di tutto il lavoro.
- /onboard:map: Crea un piano per analizzare un progetto esistente.
- /onboard:run: Avvia l'esecuzione autonoma del piano di onboarding.
- /plan:mvp: Genera il backlog completo per l'MVP di un nuovo progetto.
- /run:epic: Orchestra l'esecuzione autonoma del codice per un intero Epic.
- /complete:story: Finalizza il lavoro e crea la Pull Request.
- /fix:bug: Gestisce l'intero ciclo di vita di un bug fix in autonomia.