igny8/part2-dev/planning/04-roadmap.md

IGNY8 Phase 2 Roadmap & Implementation Plan

Consolidates Igny8-part-2-plan.md and IGNY8-IMPLEMENTATION-PLAN.md into a single execution roadmap.

---

1. Roadmap Overview

Strategic Themes

1. Planner Modernization – richer clustering, taxonomy seeding, keyword governance.
2. Site Builder Evolution – guided wizard, taxonomy-aware sitemap generation, blueprint ↔ planner sync.
3. Writer & Optimization Depth – metadata propagation, product/service support, auto-linking improvements.
4. Publishing & Sync – IGNY8 deployments + full WordPress parity (taxonomies, products, attributes).

Stage Rollout

Stage	Focus	Target Outcome
Stage 1	Data & services foundation	New schema, clustering upgrades, workflow state APIs.
Stage 2	Planner + Wizard UX	State-aware wizard, taxonomy builder, planner UI refresh.
Stage 3	Writer / Linker / Optimizer	Metadata-aware tasks/content, improved linking & scoring.
Stage 4	Publishing & Sync	WordPress taxonomy sync, deployment polish, QA.

---

2. Detailed Workstream Breakdown

Workstream A – Data & Services

• Apply migrations for blueprint clusters/taxonomies, writer mapping tables.
• Implement WorkflowStateService, validation endpoints, TaxonomyService.
• Upgrade clustering prompt/service for multi-dimensional outputs.
• Update API serializers to expose entity metadata.

Workstream B – Planner & Wizard UX

• New planner views for clusters/taxonomies with matrix visualization.
• Wizard steps (business, clusters, taxonomy, sitemap, validation, hand-off) with gating logic.
• Toasts/tooltips/inline helpers to keep users oriented.
• Resume capability (persisted step state).

Workstream C – Writer, Linker, Optimizer

• Extend ideas/tasks/content editors with cluster/taxonomy context panels.
• Enforce validation (no publish without assigned taxonomy/attributes).
• Linker suggestions grouped by cluster role; optimizer scoring for coverage.
• Progress dashboards per site/cluster.

Workstream D – Publishing & Sync

• Finish WordPress taxonomy + product attribute sync (bi-directional).
• Update deployment adapters to honor new metadata; ensure renderer reads cluster/taxonomy info.
• Provide sync dashboards with health indicators, last sync timestamps.
• Final regression + staging sign-off.

---

3. Milestones & Deliverables

Milestone	Key Deliverables	Dependencies
M1 – Schema Ready	Migrations merged, services deployed, API docs updated.	None.
M2 – Guided Planner & Wizard	New UI flows live behind feature flag, analytics instrumented.	M1.
M3 – Metadata-Driven Writer	Writer/linker/optimizer using new relations, validation in place.	M2.
M4 – Publish & Sync Alpha	WordPress sync parity, deployment QA, release notes.	M3.

Each milestone includes QA checklist, documentation update (master-docs + in-app help), and telemetry validation.

---

4. Dependencies & Risks

• Redis/Celery availability – AI flows block if infra not running; ensure monitoring.
• Migration coordination – new tables touched by multiple services; schedule maintenance window.
• WordPress API variance – taxonomy/product endpoints vary by site; need robust error handling + manual override UI.
• User learning curve – wizard adds structure; include onboarding tips and inline docs.

Mitigations described in 02-workflows.md (UX guardrails) and 03-phase-reports.md (lessons learned).

---

5. Communication & Tracking

• Maintain status in part2-dev/README.md with links to this roadmap.
• Sprint boards map tasks back to stage/milestone.
• Release notes reference doc IDs here for posterity.

---

References

• Strategy context: 01-strategy.md
• Detailed workflows: 02-workflows.md
• Historical reports: 03-phase-reports.md

---

6. Stage Implementation Details

Stage 1 – Data & Services Foundation

Goal: Ship all schema + backend building blocks so later stages can focus on UX.

Backend

• Migrations for SiteBlueprintCluster, SiteBlueprintTaxonomy, WorkflowState, writer mapping tables.
• WorkflowStateService with REST endpoints for fetching/updating step status.
• TaxonomyService (CRUD/import/export) and ClusteringService prompt upgrade for multi-dimensional clusters.
• API validation hooks (validate_clusters_attached, validate_taxonomies_ready, etc.) consumed by wizard gating.
• Serializer updates exposing entity metadata to frontend.

Frontend

• Minimal work (feature flags + API clients) to prepare for new endpoints; no user-facing change yet.

Testing/Acceptance

• Migration dry run, rollback verified.
• Unit/integration tests for services and validators.
• API documentation updated; Postman suite green.

Stage 2 – Planner + Wizard UX

Goal: Deliver the guided, state-aware planning experience.

Backend

• Ensure planner endpoints return cluster metrics, taxonomy suggestions, validation errors.
• Audit logging for workflow transitions.

Frontend

• Implement builderWorkflowStore (Zustand) with resume capability, blocking logic, telemetry.
• Build wizard steps:
  1. Business details + hosting detection.
  2. Cluster assignment (coverage metrics, filters).
  3. Taxonomy builder (create/import/match clusters).
  4. AI sitemap review with checklist + edits.
  5. Coverage validation summary.
  6. Ideas hand-off with secondary prompt.
• Update planner cluster/taxonomy management screens (matrix view, inline warnings).

UX Guardrails

• Progress indicator with completion badges.
• Disabled buttons explain “what’s missing”.
• CTAs back to Planner when prerequisites unmet.

Testing/Acceptance

• Manual script for full wizard flow (new IGNY8 site + WP-linked site).
• Cypress/e2e coverage for gating + resume behavior.
• Telemetry events for step completion firing.

Stage 3 – Writer / Linker / Optimizer Enhancements

Goal: Propagate metadata end-to-end and enforce validation.

Backend

• Ensure ideas/tasks/content writer pipeline populates entity_type, taxonomy_id, cluster_role, product_data.
• Linker/optimizer services consume mapping tables and expose coverage metrics via APIs.
• Progress dashboard endpoints (per site/cluster) for frontend widgets.

Frontend

• Planner Ideas + Writer Tasks lists show entity/taxonomy chips and warnings.
• Writer editor sidebar summarizing target cluster, taxonomy, attribute requirements; validation prompts before publish.
• Linker UI grouped by cluster role; Optimizer dashboards show dimension scorecards and “next actions”.
• Sites module progress bars summarizing blueprint completion.

Testing/Acceptance

• Regression on task/content creation flows.
• QA verifies publish blocked when metadata missing.
• Performance profiling on linker/optimizer queries with new joins.

Stage 4 – Publishing & Sync Integration

Goal: Achieve parity between IGNY8-hosted and WordPress-hosted sites.

Backend

• Complete WordPress taxonomy/product attribute import/export in ContentSyncService.
• Enhance SitesRendererAdapter to include cluster/taxonomy metadata for navigation + internal linking.
• Sync health endpoints (last sync, mismatched taxonomies, errors) and deployment logs/rollback hooks.

Frontend

• Sync dashboard showing taxonomy parity, cluster coverage, last sync status, manual retry/reconcile actions.
• Deployment panel summarizing readiness (clusters covered, content publish state) before enabling deploy.
• Notifications/toasts for sync success/failure and deployments.

Testing/Acceptance

• End-to-end tests: IGNY8 deployment, WP publish for posts/products/services (blog/ecom/company templates).
• Fallback behavior validated (auto-creating missing taxonomies).
• Final QA checklist signed off; release notes + training updates distributed.

---

7. Stage Exit Criteria

Stage	Exit Criteria
1	Migrations live, services stable, existing Planner/Writer flows unaffected, docs updated.
2	Wizard fully usable with telemetry + QA sign-off; planner UIs reflect new taxonomy data.
3	Writer/linker/optimizer using metadata, publishing blocked without required info, dashboards live.
4	WordPress parity achieved, deployments verified, sync dashboards green, release announced.