OnePlan (Context-Driven Engineering)

Questa skill implementa l’equivalente del workflow “Conductor” (file-based) ma con GitHub come backend e un’identità propria: OnePlan.

Idea guida: Measure twice, ship once.

Quick Reference

Struttura consigliata

• Track = GitHub Milestone
• Spec = Issue con label oneplan/spec
• Plan = Issue con label oneplan/plan (parent)
• Phase = Sub-issue del Plan con label oneplan/phase
• Task = Sub-issue (o sub-issue della Phase) con label oneplan/task

Fallback (se le Sub-issues non sono abilitate nel repo):

• Phase = Issue normale nella milestone (titolo [PHASE] ...) + linkata dal PLAN tramite task list
• Task = Issue normale nella milestone (titolo [TASK] ...) + linkata dalla PHASE tramite task list

Stati (label)

• status/pending, status/in-progress, status/blocked, status/done

Regola d’oro

• Prima SPEC, poi PLAN, poi IMPLEMENT.

Cosa risolve rispetto al file-based

• Persistenza e collaborazione: tutto vive su GitHub.
• Gerarchia e parallelismo: sub-issues + dipendenze.
• Tracciamento: milestone progress, labels, assignees, review.
• Audit trail: commenti e PR collegate.

Workflow operativo

1) Setup (una volta per repo)

Obiettivo: standardizzare convenzioni e ridurre ambiguità.

1. Crea labels OnePlan (vedi references/LABELS_AND_STATES.md).
2. Aggiungi issue templates (vedi references/ISSUE_TEMPLATES.md).
3. Crea (opzionale) una issue “contesto” sempre aperta:
   • titolo: [CONTEXT] Project context
   • label: oneplan/context
   • contenuto: product goals, tech stack, workflow.

Output desiderato:

• Labels pronte
• Templates pronte
• Contesto centralizzato e condiviso

2) Creare un Track (Milestone)

Obiettivo: un contenitore unico per spec/plan/tasks.

1. Crea milestone: Track: <nome>.
2. Crea issue SPEC associata alla milestone:
   • titolo: [SPEC] <nome>
   • label: oneplan/spec
3. Crea issue PLAN associata alla milestone:
   • titolo: [PLAN] <nome>
   • label: oneplan/plan

Nota: la SPEC deve essere “approvata” (anche solo via commento “LGTM / approved”) prima di creare task dettagliate.

3) Planning (gerarchico + parallelo)

Obiettivo: trasformare SPEC → fasi e task eseguibili.

Regole:

• Le Phase sono sequenziali salvo dichiarazione esplicita.
• Le Task dentro una phase possono essere parallele.
• Ogni task deve avere:
  • “Definition of Done” verificabile
  • dipendenze esplicite (se esistono)
  • owner/assignee (se in team)

Algoritmo pratico di scomposizione:

1. Estrarre requisiti/AC dalla SPEC.
2. Raggruppare per aree (UI, API, DB, tests, deploy).
3. Definire 3–6 phases:
   • Setup/Scaffold
   • Core implementation
   • Edge cases
   • Testing
   • Docs/Release
4. Per ogni phase, creare 2–6 task piccole, con verifica.

Parallelismo:

• Metti nella stessa phase task indipendenti.
• Usa dipendenze solo dove necessario.

Gerarchia senza Sub-issues (task lists)

Se non puoi creare sub-issues, usa le task list nel body del PLAN/PHASE:

• #123 [PHASE] Setup
• #124 [PHASE] Implementazione

E dentro una PHASE:

• #130 [TASK] Aggiungere toggle UI
• #131 [TASK] Persistenza preferenza
• #132 [TASK] Test e2e

4) Implement (resumable)

Obiettivo: eseguire una task per volta, mantenendo stato su GitHub.

Selezione “next task” (deterministica):

1. Se esiste una task status/in-progress assegnata a te → continua quella.
2. Altrimenti scegli la più piccola task status/pending:
   • nella prima phase non completata
   • non status/blocked
   • con dipendenze soddisfatte

Ciclo di esecuzione per task:

1. Metti status/in-progress.
2. Esegui la modifica in repo (branch/commit/PR se necessario).
3. Aggiorna la issue task:
   • checklist di verifica spuntata
   • link a PR/commit
4. Metti status/done e chiudi la issue task.

5) Status / Reporting

Obiettivo: visione rapida a milestone/phase/task.

Heuristics:

• Track progress = (issues chiuse nella milestone) / (issues totali nella milestone)
• Phase progress = (tasks chiuse nella phase) / (tasks totali)

6) Post-track Tech Debt pass (consigliato)

Obiettivo: dopo aver consegnato una milestone, ridurre il debito tecnico “fresco”.

Workflow consigliato:

1. Quando una track è completa (0 issue aperte nella milestone), crea una issue di review tech-debt.
2. Esegui la modalità @techdebt e trasforma i findings in issue piccole e prioritizzate.

Suggerimenti pratici:

• @techdebt assess (panoramica)
• @techdebt smells, @techdebt complexity, @techdebt unused (se pertinente)

Nota: l’estensione può proporre automaticamente la creazione della issue di review quando la milestone è completa.

7) Sync opzionale (GitHub ⇄ repo)

Se vuoi “contesto locale” per far lavorare meglio l’agente (e facilitare review), puoi mantenere:

• .conductor/product.md
• .conductor/tech-stack.md
• .conductor/workflow.md

Questi file sono derivati dal contesto GitHub (o viceversa). La fonte di verità resta GitHub.

Convenzioni di naming

• Milestone: Track: <Titolo umano>
• Issue type prefix: [SPEC], [PLAN], [PHASE], [TASK]
• Slug: kebab-case per file/branch (se usati)

Dipendenze (come rappresentarle)

Usa un blocco standard nel body:

• Depends on: #123, #124
• Blocks: #200

E quando blocchi una task:

• label status/blocked
• commento: motivo + cosa serve per sbloccare

Integrazione con Agent Planning

Quando serve progettazione “larga”:

1. Usa un agente planner (es. “Plan”) per ricavare la scomposizione.
2. Trascrivi il risultato nel PLAN issue creando phases/tasks come sub-issues.

Guardrail

• Non creare task “giganti”: target 0.5–2 ore ciascuna.
• Evita dipendenze cicliche.
• Non chiudere una task senza verifica scritta.
• Una sola task in-progress per persona.

Reference

• references/GITHUB_MAPPING.md
• references/LABELS_AND_STATES.md
• references/ISSUE_TEMPLATES.md
• references/DEPENDENCIES.md