diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index a84747e..0cf9a00 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -94,31 +94,31 @@ Quali fasi coprono quali requirements. Aggiornato durante creazione roadmap. | Requirement | Phase | Status | |-------------|-------|--------| -| AUTH-01 | TBD | Pending | -| AUTH-02 | TBD | Pending | -| AUTH-03 | TBD | Pending | -| AUTH-04 | TBD | Pending | -| ONBR-01 | TBD | Pending | -| ONBR-02 | TBD | Pending | -| CHAT-01 | TBD | Pending | -| CHAT-02 | TBD | Pending | -| CHAT-03 | TBD | Pending | -| CHAT-04 | TBD | Pending | -| CONT-01 | TBD | Pending | -| CONT-02 | TBD | Pending | -| CONT-03 | TBD | Pending | -| SCHD-01 | TBD | Pending | -| SCHD-02 | TBD | Pending | -| SCHD-03 | TBD | Pending | -| SCHD-04 | TBD | Pending | -| MSGN-01 | TBD | Pending | -| MSGN-02 | TBD | Pending | +| AUTH-01 | Phase 1 | Pending | +| AUTH-02 | Phase 1 | Pending | +| AUTH-03 | Phase 1 | Pending | +| AUTH-04 | Phase 2 | Pending | +| ONBR-01 | Phase 3 | Pending | +| ONBR-02 | Phase 3 | Pending | +| CHAT-01 | Phase 4 | Pending | +| CHAT-02 | Phase 4 | Pending | +| CHAT-03 | Phase 4 | Pending | +| CHAT-04 | Phase 8 | Pending | +| CONT-01 | Phase 5 | Pending | +| CONT-02 | Phase 5 | Pending | +| CONT-03 | Phase 9 | Pending | +| SCHD-01 | Phase 6 | Pending | +| SCHD-02 | Phase 6 | Pending | +| SCHD-03 | Phase 7 | Pending | +| SCHD-04 | Phase 7 | Pending | +| MSGN-01 | Phase 10 | Pending | +| MSGN-02 | Phase 10 | Pending | **Coverage:** - v1 requirements: 19 total -- Mapped to phases: 0 -- Unmapped: 19 ⚠️ +- Mapped to phases: 19 +- Unmapped: 0 ✓ --- *Requirements defined: 2026-01-30* -*Last updated: 2026-01-30 after initial definition* +*Last updated: 2026-01-31 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..b8521ef --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,194 @@ +# Roadmap: Leopost + +## Overview + +Leopost viene costruito in 10 fasi incrementali che portano da zero a un micro-SaaS AI-first funzionante. Iniziamo con fondamenta solide (auth, database, multi-tenancy), aggiungiamo integrazione social e AI, implementiamo scheduling affidabile con job queue, poi concludiamo con funzionalità avanzate (AI learning, messaging bots). Ogni fase consegna capacità verificabili dall'utente, nessun lavoro speculativo. + +## Phases + +**Phase Numbering:** +- Integer phases (1, 2, 3): Planned milestone work +- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) + +Decimal phases appear between their surrounding integers in numeric order. + +- [ ] **Phase 1: Foundation & Auth** - User accounts, plans, multi-tenant database +- [ ] **Phase 2: Social Platform Integration** - Facebook OAuth, Graph API setup +- [ ] **Phase 3: Onboarding & Context** - Brand context capture, persistent memory +- [ ] **Phase 4: AI Chat Interface** - Chat UI, multi-model support, conversation management +- [ ] **Phase 5: Content Generation** - AI text and image generation +- [ ] **Phase 6: Scheduling Foundation** - Post scheduling, reliable publishing with job queue +- [ ] **Phase 7: Automation & Calendar** - Automation levels, visual calendar +- [ ] **Phase 8: AI Learning** - AI learns user preferences from feedback +- [ ] **Phase 9: Editorial Planning** - AI creates editorial calendar +- [ ] **Phase 10: Messaging Integration** - Telegram and WhatsApp bot commands + +## Phase Details + +### Phase 1: Foundation & Auth +**Goal**: Users can create accounts, log in, and subscribe to plans in a secure multi-tenant environment +**Depends on**: Nothing (first phase) +**Requirements**: AUTH-01, AUTH-02, AUTH-03 +**Success Criteria** (what must be TRUE): + 1. User can register with email/password and receive confirmation email + 2. User can log in with Google OAuth and stay authenticated across sessions + 3. User can view and switch between Free, Creator, and Pro plans + 4. System enforces plan-specific limits (configured in database, enforced in API) + 5. All data is isolated per tenant (RLS active, no cross-tenant leakage) +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 2: Social Platform Integration +**Goal**: Users can securely connect their Facebook account for publishing +**Depends on**: Phase 1 +**Requirements**: AUTH-04 +**Success Criteria** (what must be TRUE): + 1. User can click "Connect Facebook" and complete OAuth flow + 2. Facebook access token is stored securely with automatic refresh + 3. User can view connected Facebook pages and select target page + 4. System handles token expiration gracefully (refresh before publish) + 5. API rate limits are monitored and logged (dashboard shows remaining quota) +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 3: Onboarding & Context +**Goal**: New users provide brand context that AI uses for personalized content +**Depends on**: Phase 1 +**Requirements**: ONBR-01, ONBR-02 +**Success Criteria** (what must be TRUE): + 1. New user sees progressive onboarding wizard (not overwhelming) + 2. User provides business name, sector, and description in < 2 minutes + 3. Brand context persists in database and loads in future sessions + 4. User can update brand info anytime via settings page + 5. AI prompts automatically inject brand context (verified in logs) +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 4: AI Chat Interface +**Goal**: Users interact with AI assistant to create content via natural conversation +**Depends on**: Phase 3 +**Requirements**: CHAT-01, CHAT-02, CHAT-03 +**Success Criteria** (what must be TRUE): + 1. User sees chat interface as main screen (not buried in tabs) + 2. User can send message and receive AI response in < 5 seconds + 3. User can choose AI model (GPT, Claude, Gemini) in settings + 4. AI suggests 3-5 initial actions after onboarding (e.g., "Create first post") + 5. Conversation history persists (user can scroll back, AI remembers context) +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 5: Content Generation +**Goal**: AI generates quality text posts and images adapted to brand voice +**Depends on**: Phase 4 +**Requirements**: CONT-01, CONT-02 +**Success Criteria** (what must be TRUE): + 1. User asks "Create post about [topic]" and receives text draft in < 10 seconds + 2. Generated post uses brand context (tone, sector, target audience) + 3. User asks "Add image" and receives AI-generated image in < 30 seconds + 4. User can regenerate content with feedback ("Make it more casual") + 5. Generated content displays in chat with edit capability +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 6: Scheduling Foundation +**Goal**: Users reliably schedule posts and they publish automatically at specified time +**Depends on**: Phase 2, Phase 5 +**Requirements**: SCHD-01, SCHD-02 +**Success Criteria** (what must be TRUE): + 1. User can set date/time for post and it saves to queue + 2. Post publishes to Facebook automatically at scheduled time (99%+ reliability) + 3. User receives notification when post is published (or if it fails) + 4. Job queue handles retries with exponential backoff (API failures don't lose posts) + 5. Timezone is handled correctly (user sees local time, system schedules in UTC) +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 7: Automation & Calendar +**Goal**: Users configure automation level and visualize scheduled posts in calendar +**Depends on**: Phase 6 +**Requirements**: SCHD-03, SCHD-04 +**Success Criteria** (what must be TRUE): + 1. User can set automation level (Approval → Semi-Auto → Autopilot) + 2. In Approval mode, AI generates drafts and user must manually approve + 3. In Autopilot mode, AI generates and publishes without user action + 4. Calendar view shows all scheduled posts (color-coded by platform) + 5. User can drag-and-drop posts to reschedule in calendar +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 8: AI Learning +**Goal**: AI improves content quality over time by learning user's authentic voice +**Depends on**: Phase 7 +**Requirements**: CHAT-04 +**Success Criteria** (what must be TRUE): + 1. User can give thumbs up/down feedback on generated content + 2. AI analyzes approved posts to identify tone, vocabulary, structure patterns + 3. Future posts incorporate learned preferences (measurably more "on brand") + 4. User sees improvement notification ("AI learned from 10 approved posts") + 5. Learning data is per-tenant (AI doesn't leak patterns across users) +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 9: Editorial Planning +**Goal**: AI proactively creates multi-week content calendar aligned to business goals +**Depends on**: Phase 8 +**Requirements**: CONT-03 +**Success Criteria** (what must be TRUE): + 1. User asks "Create 2-week plan" and AI generates calendar with 10-14 post ideas + 2. Editorial plan includes diverse content types (educational, promotional, engagement) + 3. User can accept entire plan or edit individual posts + 4. Accepted plan populates calendar with draft posts (ready to review/publish) + 5. AI considers business context (sector trends, user's past successful posts) +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +### Phase 10: Messaging Integration +**Goal**: Users can create and schedule posts via Telegram or WhatsApp commands +**Depends on**: Phase 6 +**Requirements**: MSGN-01, MSGN-02 +**Success Criteria** (what must be TRUE): + 1. User connects Telegram bot and can send "/create [topic]" to generate post + 2. Telegram bot responds with draft post and options (edit, schedule, publish now) + 3. User connects WhatsApp bot (Business API verified) with same functionality + 4. Both bots support voice messages (transcribed to text, processed by AI) + 5. Posts created via messaging appear in web calendar (sync across channels) +**Plans**: TBD + +Plans: +- [ ] TBD during plan-phase + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Foundation & Auth | 0/TBD | Not started | - | +| 2. Social Platform Integration | 0/TBD | Not started | - | +| 3. Onboarding & Context | 0/TBD | Not started | - | +| 4. AI Chat Interface | 0/TBD | Not started | - | +| 5. Content Generation | 0/TBD | Not started | - | +| 6. Scheduling Foundation | 0/TBD | Not started | - | +| 7. Automation & Calendar | 0/TBD | Not started | - | +| 8. AI Learning | 0/TBD | Not started | - | +| 9. Editorial Planning | 0/TBD | Not started | - | +| 10. Messaging Integration | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..90f2854 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,69 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-01-30) + +**Core value:** L'AI fa il lavoro sporco del social media manager — minimo sforzo, massima resa +**Current focus:** Phase 1 - Foundation & Auth + +## Current Position + +Phase: 1 of 10 (Foundation & Auth) +Plan: 0 of TBD (planning not started) +Status: Ready to plan +Last activity: 2026-01-31 — Roadmap created with 10 phases, 100% requirement coverage + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: N/A +- Total execution time: 0.0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: N/A +- Trend: N/A + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- Initial: Chat-first con schermate di supporto (L'interazione naturale riduce l'attrito) +- Initial: Multi-model AI (Diversi utenti preferiscono modelli diversi, evita lock-in) +- Initial: Onboarding progressivo (Evita abbandono per "troppo da fare" al primo accesso) +- Initial: Automazione configurabile (Costruisce fiducia gradualmente, dall'approval all'autopilot) +- Initial: Headless architecture (Prepara per app native senza riscrivere logica) + +### Pending Todos + +None yet. + +### Blockers/Concerns + +**Research-identified risks to address early:** +- Phase 1: Implement RLS multi-tenant isolation from day 1 (no retrofitting) +- Phase 2: Facebook API rate limits (200 DM/hour) — need exponential backoff + monitoring +- Phase 5: AI cost management — implement caching, freemium limits, per-user tracking +- Phase 6: Job queue reliability critical — BullMQ on Redis, not setTimeout +- Phase 10: WhatsApp Business verification takes 2-4 weeks — start process early + +## Session Continuity + +Last session: 2026-01-31 +Stopped at: Roadmap and STATE.md created, traceability updated +Resume file: None +Next step: Execute `/gsd:plan-phase 1` to create detailed plans for Foundation & Auth