# ZoneGaze Social Studio Modular Plugin Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build `ZoneGaze Social Studio` as an installable Matrix plugin whose capabilities are isolated into reusable modules for asset ingest, media understanding, research, planning, publishing/export, analytics, automation, and user-supplied provider connectors.

**Architecture:** Keep Matrix as the thin shell and keep Social Studio product logic inside `extensions/social-studio/`. Shared runtime/browser-safe schemas stay in `flow/contracts`, runtime persistence and tRPC wiring stay in `flow/runtime/src/social-studio/`, and each product capability lands in its own package so it can be reused outside the plugin later. The default product mode is local-first planning, analysis, and export-pack delivery; direct platform publishing and platform-native analytics remain optional BYO connector modules.

**Tech Stack:** TypeScript, React, Zod, existing Matrix/Flow runtime tRPC APIs, `@zonegaze/cline-sdk`, existing Matrix model-source registry (`cline-sdk`, `ollama`, `exo`, `custom-api`), existing Whispr and project-context surfaces, optional local worker adapters for vision/NLP tools, optional user-supplied platform/API connectors.

## Progress Snapshot

- [x] Tasks 1 through 7 are implemented on `codex/social-studio-complete-plugin`.
- [x] Focused root and web Social Studio validation passed locally.
- [ ] Task 8 remains: final diff hygiene, merge back into `development`, repeat focused validation, and push `origin/development`.

## Global Constraints

- Keep the feature as an installable Matrix plugin under `extensions/social-studio/`.
- Keep every major capability behind its own typed module boundary with no product logic copied into generic Matrix shell files.
- Use only commercially safe dependencies; avoid AGPL, SSPL, fair-code, Sustainable Use, mixed-license enterprise bundles, or unclear model-weight redistribution terms as defaults.
- Keep `@cline/sdk` access behind `@zonegaze/cline-sdk`.
- Use the existing Matrix model-source abstraction for Cline-backed models; user-supplied NVIDIA endpoints must flow through the existing `cline-sdk` source configuration, not a Social Studio-specific hard-coded path.
- Make the core product useful with no paid API and no required proprietary social-platform API dependency.
- Treat direct publish, analytics-import, and DM/comment actions as optional connector modules owned by the user or future adapters, not as required foundation dependencies.
- Keep Whispr, Research, Open Design, Chat, Exo, and Flow as peer products consumed through typed adapters, not deep imports into their internal feature logic.
- Use the canonical local QA route `http://127.0.0.1:4217/demo-website`.
- Land the work in small validated slices that can merge back into `development` independently.

---

## Module Ownership

- `extensions/social-studio/apps/web/`
  - Matrix-embedded Social Studio UI only.
  - May depend on `extensions/social-studio/packages/*`, `flow/contracts`, and runtime API hooks.
- `extensions/social-studio/packages/domain/`
  - Product-owned workspace defaults, module catalog, invariants, and cross-module shared types.
- `extensions/social-studio/packages/connectors/`
  - Connector descriptors, capability registries, connector metadata, and provider-facing contracts.
- `extensions/social-studio/packages/asset-ingest/`
  - Folder/file/project-context/Whispr intake, asset manifests, dedupe, and collection assembly.
- `extensions/social-studio/packages/media-analysis/`
  - Transcription, OCR, thumbnails, scenes, clip metadata, and reusable media-signal contracts.
- `extensions/social-studio/packages/research/`
  - Trend research briefs, evidence summaries, competitor/reference capture, and citation-oriented strategy objects.
- `extensions/social-studio/packages/planning/`
  - Content pillars, campaign briefs, post variants, editorial calendar rules, and export-pack preparation.
- `extensions/social-studio/packages/publishing/`
  - Normalized publish commands, export bundles, platform capability matrices, and optional direct-publish adapters.
- `extensions/social-studio/packages/analytics/`
  - Metrics normalization, CSV/manual-import parsing, strategy summaries, and feedback loops.
- `extensions/social-studio/packages/automation/`
  - Schedules, approvals, retries, queue abstractions, audit logs, and safe workflow triggers.
- `flow/contracts/src/social-studio-contracts.ts`
  - Source of truth for runtime/browser-safe Social Studio schemas shared across UI, runtime, and tests.
- `flow/runtime/src/social-studio/`
  - Social Studio runtime adapter layer only: persistence, tRPC, orchestration entrypoints, and background-job coordination.

## Existing Matrix Reuse Map

- `@zonegaze/cline-sdk`
  - Primary AI orchestration boundary for planning, drafting, summarization, and optional user-supplied model routing.
- `flow/runtime/src/trpc/projects-api.ts`
  - Reuse directory picker/list/create flows for local asset selection.
- `flow/runtime/src/context/context-documents.ts`
  - Reuse project-context documents as ingestable evidence collections.
- `flow/web/src/whispr/matrix-transcripts.ts`
  - Reuse Whispr transcript history as Social Studio ingest input.
- Existing Matrix Deep Research product boundary
  - Reuse cited research outputs through typed adapters rather than rebuilding raw research logic in Social Studio.
- Existing Matrix navigation/install state
  - Keep Social Studio plugin registration and shell composition narrow and product-agnostic.

### Task 1: Asset Ingest And Evidence Packaging

**Files:**
- Create: `extensions/social-studio/packages/asset-ingest/src/asset-types.ts`
- Create: `extensions/social-studio/packages/asset-ingest/src/file-classifier.ts`
- Create: `extensions/social-studio/packages/asset-ingest/src/asset-collection-builder.ts`
- Create: `extensions/social-studio/packages/asset-ingest/src/index.ts`
- Create: `flow/runtime/src/social-studio/social-studio-asset-ingest-service.ts`
- Create: `test/runtime/social-studio/social-studio-asset-ingest-service.test.ts`
- Create: `extensions/social-studio/apps/web/src/modules/ingest/social-studio-ingest-panel.tsx`
- Create: `extensions/social-studio/apps/web/src/modules/ingest/social-studio-ingest-panel.test.tsx`
- Create: `extensions/social-studio/apps/web/src/modules/ingest/use-social-studio-ingest.ts`
- Modify: `flow/contracts/src/social-studio-contracts.ts`
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `flow/contracts/src/index.ts`
- Modify: `flow/runtime/src/social-studio/index.ts`
- Modify: `flow/runtime/src/trpc/app-router.ts`
- Modify: `extensions/social-studio/apps/web/src/social-studio-shell.tsx`
- Modify: `extensions/social-studio/apps/web/src/use-social-studio-workspace.ts`

**Interfaces:**
- Produces: `SocialStudioAssetKind`
- Produces: `SocialStudioAssetCollectionSource`
- Produces: `type SocialStudioAssetItem`
- Produces: `buildSocialStudioAssetCollection(input: SocialStudioAssetCollectionBuildInput): SocialStudioAssetCollection`
- Produces: `runtime.ingestSocialStudioDirectory`
- Produces: `runtime.importSocialStudioProjectContext`
- Produces: `runtime.importSocialStudioWhisprTranscripts`

- [ ] Step 1: Expand `flow/contracts/src/social-studio-contracts.ts` so asset collections capture source type, source path, asset items, timestamps, dedupe fingerprints, and bounded-ingest metadata.
- [ ] Step 2: Implement `extensions/social-studio/packages/asset-ingest/` as a browser-safe reusable package that classifies files, normalizes asset manifests, and builds collections without depending on React or runtime code.
- [ ] Step 3: Add `flow/runtime/src/social-studio/social-studio-asset-ingest-service.ts` plus new tRPC endpoints that scan a folder, package project-context documents, and import Whispr transcripts into workspace asset collections.
- [ ] Step 4: Add a dedicated ingest panel under `extensions/social-studio/apps/web/src/modules/ingest/` that reuses existing directory selection flows and keeps `social-studio-shell.tsx` as composition only.
- [ ] Step 5: Verify with `./node_modules/.bin/tsc -p tsconfig.json --noEmit`, `./node_modules/.bin/vitest run test/runtime/social-studio/social-studio-asset-ingest-service.test.ts`, and `npm --prefix flow/web run typecheck`.
- [ ] Step 6: Commit with `git commit -m "feat: add social studio asset ingest module"`.

### Task 2: Media Analysis Modules

**Files:**
- Create: `extensions/social-studio/packages/media-analysis/src/media-analysis-types.ts`
- Create: `extensions/social-studio/packages/media-analysis/src/media-analysis-pipeline.ts`
- Create: `extensions/social-studio/packages/media-analysis/src/transcription-provider.ts`
- Create: `extensions/social-studio/packages/media-analysis/src/ocr-provider.ts`
- Create: `extensions/social-studio/packages/media-analysis/src/scene-provider.ts`
- Create: `extensions/social-studio/packages/media-analysis/src/index.ts`
- Create: `flow/runtime/src/social-studio/social-studio-media-analysis-service.ts`
- Create: `test/runtime/social-studio/social-studio-media-analysis-service.test.ts`
- Create: `extensions/social-studio/apps/web/src/modules/media/social-studio-media-panel.tsx`
- Create: `extensions/social-studio/apps/web/src/modules/media/social-studio-media-panel.test.tsx`
- Modify: `flow/contracts/src/social-studio-contracts.ts`
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `flow/runtime/src/social-studio/index.ts`
- Modify: `flow/runtime/src/trpc/app-router.ts`
- Modify: `extensions/social-studio/apps/web/src/social-studio-shell.tsx`

**Interfaces:**
- Consumes: `SocialStudioAssetCollection`
- Produces: `type SocialStudioMediaInsight`
- Produces: `type SocialStudioMediaAnalysisJob`
- Produces: `analyzeSocialStudioAssets(input: SocialStudioMediaAnalysisJob): SocialStudioMediaInsight[]`
- Produces: `SocialStudioTranscriptionProvider`
- Produces: `SocialStudioOcrProvider`
- Produces: `SocialStudioSceneProvider`

- [ ] Step 1: Extend the shared contracts so media analysis results, transcription records, OCR snippets, scene boundaries, and brand-safety flags have stable schemas independent of any specific tool.
- [ ] Step 2: Implement `extensions/social-studio/packages/media-analysis/` as a pure capability package with provider interfaces and pipeline orchestration that can wrap Whispr, Whisper-compatible tools, OCR engines, or future vision providers behind adapters.
- [ ] Step 3: Add runtime entrypoints that enqueue or execute bounded analysis jobs against selected asset collections without embedding engine-specific logic in the UI.
- [ ] Step 4: Add a module-specific media panel that shows transcripts, OCR text, scenes, suggested clip cuts, and analysis status while keeping provider setup separate from presentation.
- [ ] Step 5: Verify with focused runtime tests, shared contract tests, and web UI tests for the media module.
- [ ] Step 6: Commit with `git commit -m "feat: add social studio media analysis module"`.

### Task 3: Research And Strategy Modules

**Files:**
- Create: `extensions/social-studio/packages/research/src/research-types.ts`
- Create: `extensions/social-studio/packages/research/src/research-brief-builder.ts`
- Create: `extensions/social-studio/packages/research/src/evidence-summary.ts`
- Create: `extensions/social-studio/packages/research/src/index.ts`
- Create: `flow/runtime/src/social-studio/social-studio-research-service.ts`
- Create: `test/runtime/social-studio/social-studio-research-service.test.ts`
- Create: `extensions/social-studio/apps/web/src/modules/research/social-studio-research-panel.tsx`
- Create: `extensions/social-studio/apps/web/src/modules/research/social-studio-research-panel.test.tsx`
- Modify: `flow/contracts/src/social-studio-contracts.ts`
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `flow/runtime/src/social-studio/index.ts`
- Modify: `flow/runtime/src/trpc/app-router.ts`
- Modify: `extensions/social-studio/packages/connectors/src/index.ts`

**Interfaces:**
- Consumes: `SocialStudioAssetCollection`
- Produces: `type SocialStudioResearchBrief`
- Produces: `type SocialStudioEvidenceRecord`
- Produces: `type SocialStudioTrendSignal`
- Produces: `runSocialStudioResearch(input: SocialStudioResearchBrief): SocialStudioResearchResult`

- [ ] Step 1: Add research schemas for briefs, evidence items, cited findings, trend signals, and saved strategy summaries to `flow/contracts/src/social-studio-contracts.ts`.
- [ ] Step 2: Implement `extensions/social-studio/packages/research/` to convert user direction, asset collections, project context, and imported references into reusable research briefs and evidence summaries.
- [ ] Step 3: Add runtime orchestration that can invoke the existing Cline model-source boundary and future Matrix Deep Research adapters through typed tool calls rather than hard-coded UI prompts.
- [ ] Step 4: Add a research panel that captures market direction, audience goals, competitor references, and saved cited findings for downstream planning modules.
- [ ] Step 5: Verify contracts, runtime services, and UI rendering for saved research sessions.
- [ ] Step 6: Commit with `git commit -m "feat: add social studio research module"`.

### Task 4: Planning And Draft Generation Modules

**Files:**
- Create: `extensions/social-studio/packages/planning/src/planning-types.ts`
- Create: `extensions/social-studio/packages/planning/src/content-pillar-engine.ts`
- Create: `extensions/social-studio/packages/planning/src/post-variant-builder.ts`
- Create: `extensions/social-studio/packages/planning/src/calendar-builder.ts`
- Create: `extensions/social-studio/packages/planning/src/index.ts`
- Create: `flow/runtime/src/social-studio/social-studio-planning-service.ts`
- Create: `test/runtime/social-studio/social-studio-planning-service.test.ts`
- Create: `extensions/social-studio/apps/web/src/modules/planner/social-studio-planner-panel.tsx`
- Create: `extensions/social-studio/apps/web/src/modules/planner/social-studio-planner-panel.test.tsx`
- Modify: `flow/contracts/src/social-studio-contracts.ts`
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `flow/runtime/src/social-studio/index.ts`
- Modify: `flow/runtime/src/trpc/app-router.ts`

**Interfaces:**
- Consumes: `SocialStudioResearchResult`
- Consumes: `SocialStudioMediaInsight`
- Produces: `type SocialStudioCampaignBrief`
- Produces: `type SocialStudioPostVariant`
- Produces: `type SocialStudioCalendarEntry`
- Produces: `buildSocialStudioPlan(input: SocialStudioPlanningInput): SocialStudioPlan`

- [ ] Step 1: Add planning contracts for campaign briefs, platform specs, post variants, review states, and calendar entries.
- [ ] Step 2: Implement `extensions/social-studio/packages/planning/` to generate reusable content pillars, post plans, platform-specific copy variants, and editorial calendar suggestions from research plus media inputs.
- [ ] Step 3: Add runtime actions that use the existing model-source boundary for draft generation and keep scoring, ranking, and approval state separate from generation.
- [ ] Step 4: Add a planner panel that shows campaign goals, generated variants, platform-specific text, review states, and calendar placement without mixing publishing concerns into planning code.
- [ ] Step 5: Verify planning domain logic, service orchestration, and panel behavior with focused tests.
- [ ] Step 6: Commit with `git commit -m "feat: add social studio planning module"`.

### Task 5: Publishing And Export Modules

**Files:**
- Create: `extensions/social-studio/packages/publishing/src/publishing-types.ts`
- Create: `extensions/social-studio/packages/publishing/src/platform-capabilities.ts`
- Create: `extensions/social-studio/packages/publishing/src/export-pack-builder.ts`
- Create: `extensions/social-studio/packages/publishing/src/publish-command-builder.ts`
- Create: `extensions/social-studio/packages/publishing/src/index.ts`
- Create: `extensions/social-studio/packages/connectors/src/publishing-connectors.ts`
- Create: `flow/runtime/src/social-studio/social-studio-publishing-service.ts`
- Create: `test/runtime/social-studio/social-studio-publishing-service.test.ts`
- Create: `extensions/social-studio/apps/web/src/modules/publishing/social-studio-publishing-panel.tsx`
- Create: `extensions/social-studio/apps/web/src/modules/publishing/social-studio-publishing-panel.test.tsx`
- Modify: `flow/contracts/src/social-studio-contracts.ts`
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `extensions/social-studio/packages/connectors/src/index.ts`
- Modify: `flow/runtime/src/social-studio/index.ts`
- Modify: `flow/runtime/src/trpc/app-router.ts`

**Interfaces:**
- Consumes: `SocialStudioPostVariant`
- Produces: `type SocialStudioPublishTarget`
- Produces: `type SocialStudioPublishJob`
- Produces: `buildSocialStudioExportPack(input: SocialStudioExportPackInput): SocialStudioExportPack`
- Produces: `SocialStudioPublishingConnector`

- [ ] Step 1: Add shared contracts for publish targets, capability matrices, export-pack manifests, and optional direct-publish jobs.
- [ ] Step 2: Implement `extensions/social-studio/packages/publishing/` with export-pack generation as the mandatory baseline and direct-publish command building as an optional adapter path.
- [ ] Step 3: Split connector descriptors so official platform adapters live in `packages/connectors` and remain entirely optional, user-configured modules.
- [ ] Step 4: Add runtime/export endpoints and a publishing panel that can either build manual-upload packs or hand work to approved user-supplied connectors without changing planning logic.
- [ ] Step 5: Verify export-pack generation, connector registry behavior, and publish-job state transitions with focused tests.
- [ ] Step 6: Commit with `git commit -m "feat: add social studio publishing module"`.

### Task 6: Analytics And Feedback Modules

**Files:**
- Create: `extensions/social-studio/packages/analytics/src/analytics-types.ts`
- Create: `extensions/social-studio/packages/analytics/src/metrics-normalizer.ts`
- Create: `extensions/social-studio/packages/analytics/src/feedback-summary.ts`
- Create: `extensions/social-studio/packages/analytics/src/index.ts`
- Create: `extensions/social-studio/packages/connectors/src/analytics-connectors.ts`
- Create: `flow/runtime/src/social-studio/social-studio-analytics-service.ts`
- Create: `test/runtime/social-studio/social-studio-analytics-service.test.ts`
- Create: `extensions/social-studio/apps/web/src/modules/analytics/social-studio-analytics-panel.tsx`
- Create: `extensions/social-studio/apps/web/src/modules/analytics/social-studio-analytics-panel.test.tsx`
- Modify: `flow/contracts/src/social-studio-contracts.ts`
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `extensions/social-studio/packages/connectors/src/index.ts`
- Modify: `flow/runtime/src/social-studio/index.ts`
- Modify: `flow/runtime/src/trpc/app-router.ts`

**Interfaces:**
- Consumes: `SocialStudioPublishJob`
- Produces: `type SocialStudioMetricRecord`
- Produces: `type SocialStudioPerformanceSummary`
- Produces: `normalizeSocialStudioMetrics(input: SocialStudioMetricsImportInput): SocialStudioMetricRecord[]`
- Produces: `SocialStudioAnalyticsConnector`

- [ ] Step 1: Add contracts for metrics imports, normalized records, attribution notes, and strategy feedback summaries.
- [ ] Step 2: Implement `extensions/social-studio/packages/analytics/` so CSV/manual imports, optional connector-driven imports, and strategy summaries all share the same normalized metric model.
- [ ] Step 3: Add runtime services that import metrics, persist summaries, and connect performance data back to planning and research modules without direct UI coupling.
- [ ] Step 4: Add an analytics panel that starts with manual/CSV imports and later lights up optional BYO analytics connectors without changing the domain layer.
- [ ] Step 5: Verify metrics normalization, summary generation, and UI rendering with focused tests.
- [ ] Step 6: Commit with `git commit -m "feat: add social studio analytics module"`.

### Task 7: Automation, Approval, And Audit Modules

**Files:**
- Create: `extensions/social-studio/packages/automation/src/automation-types.ts`
- Create: `extensions/social-studio/packages/automation/src/automation-rule-engine.ts`
- Create: `extensions/social-studio/packages/automation/src/queue-backend.ts`
- Create: `extensions/social-studio/packages/automation/src/audit-log.ts`
- Create: `extensions/social-studio/packages/automation/src/index.ts`
- Create: `flow/runtime/src/social-studio/social-studio-automation-service.ts`
- Create: `test/runtime/social-studio/social-studio-automation-service.test.ts`
- Create: `extensions/social-studio/apps/web/src/modules/automation/social-studio-automation-panel.tsx`
- Create: `extensions/social-studio/apps/web/src/modules/automation/social-studio-automation-panel.test.tsx`
- Modify: `flow/contracts/src/social-studio-contracts.ts`
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `flow/runtime/src/social-studio/index.ts`
- Modify: `flow/runtime/src/trpc/app-router.ts`

**Interfaces:**
- Consumes: `SocialStudioPublishJob`
- Produces: `type SocialStudioAutomationRule`
- Produces: `type SocialStudioApprovalGate`
- Produces: `type SocialStudioAuditEntry`
- Produces: `executeSocialStudioAutomationTick(input: SocialStudioAutomationTickInput): SocialStudioAutomationTickResult`
- Produces: `SocialStudioQueueBackend`

- [ ] Step 1: Add contracts for schedules, approval gates, retries, rule triggers, audit entries, and automation outcomes.
- [ ] Step 2: Implement `extensions/social-studio/packages/automation/` with a queue-backend abstraction so the first runtime can stay local-first while later BullMQ or other workers can slot in without rewriting the domain logic.
- [ ] Step 3: Add runtime automation entrypoints that enforce approval gates before publish or reply actions and record every decision into an audit log.
- [ ] Step 4: Add an automation panel for schedules, approval requirements, retry rules, and recent automation events.
- [ ] Step 5: Verify local automation execution, audit log creation, and approval-gated behavior with focused tests.
- [ ] Step 6: Commit with `git commit -m "feat: add social studio automation module"`.

### Task 8: Program Hardening, Documentation, And Merge Cadence

**Files:**
- Modify: `extensions/social-studio/README.md`
- Modify: `zonegaze/memory/social-studio-plugin/00-goal-status.md`
- Create: `docs/superpowers/plans/2026-07-08-zonegaze-social-studio-asset-ingest.md`
- Create: later per-slice plan files for media, research, planning, publishing, analytics, and automation
- Modify: tests and verification commands as each slice lands

**Interfaces:**
- Consumes: all prior module contracts
- Produces: durable slice plans, updated goal tracker, and stable verification checklist for future agents

- [ ] Step 1: Keep `extensions/social-studio/README.md` and `zonegaze/memory/social-studio-plugin/00-goal-status.md` aligned with the real module map, connector posture, and next slice after each meaningful change.
- [ ] Step 2: Create a dedicated slice plan before each major subsystem so implementation stays bounded and reviewable.
- [ ] Step 3: After each validated slice, merge the task branch back into `development`, rerun the relevant verification on `development`, and push `origin/development`.
- [ ] Step 4: Before calling the plugin complete, run the full Social Studio-focused contract, runtime, and web test matrix plus a local browser verification pass at `http://127.0.0.1:4217/demo-website`.
- [ ] Step 5: Commit each slice with a narrow scope and durable docs updates instead of batching unrelated module work together.

## Scope Decision

This plan intentionally treats the product as two concentric layers:

1. **Guaranteed free/open core**
   - Local-first ingest, analysis, research, planning, scheduling, export packs, and reporting.
   - Reuse of existing Matrix and Whispr assets.
   - No paid API required.

2. **Optional BYO connector ring**
   - User-supplied Cline model endpoints, including NVIDIA-compatible endpoints routed through the existing Cline source configuration.
   - User-supplied official social-platform publishing adapters.
   - User-supplied analytics connectors.

That split keeps the core product commercially safe and closed-source-compatible while still allowing advanced users to bring their own provider access later.
