@growthub/cli 0.3.53 → 0.3.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/assets/worker-kits/growthub-ai-website-cloner-v1/.env.example +7 -0
  2. package/assets/worker-kits/growthub-ai-website-cloner-v1/QUICKSTART.md +116 -0
  3. package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/NEW-CLIENT.md +22 -0
  4. package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/_template/brand-kit.md +27 -0
  5. package/assets/worker-kits/growthub-ai-website-cloner-v1/brands/growthub/brand-kit.md +26 -0
  6. package/assets/worker-kits/growthub-ai-website-cloner-v1/bundles/growthub-ai-website-cloner-v1.json +53 -0
  7. package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/ai-website-cloner-fork-integration.md +118 -0
  8. package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/design-token-system.md +135 -0
  9. package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/multi-phase-pipeline.md +129 -0
  10. package/assets/worker-kits/growthub-ai-website-cloner-v1/docs/parallel-builder-dispatch.md +103 -0
  11. package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/clone-brief-sample.md +54 -0
  12. package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/component-spec-sample.md +123 -0
  13. package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/platform-handoff-sample.md +102 -0
  14. package/assets/worker-kits/growthub-ai-website-cloner-v1/examples/visual-qa-sample.md +119 -0
  15. package/assets/worker-kits/growthub-ai-website-cloner-v1/growthub-meta/README.md +71 -0
  16. package/assets/worker-kits/growthub-ai-website-cloner-v1/growthub-meta/kit-standard.md +47 -0
  17. package/assets/worker-kits/growthub-ai-website-cloner-v1/kit.json +105 -0
  18. package/assets/worker-kits/growthub-ai-website-cloner-v1/output/README.md +26 -0
  19. package/assets/worker-kits/growthub-ai-website-cloner-v1/output-standards.md +75 -0
  20. package/assets/worker-kits/growthub-ai-website-cloner-v1/runtime-assumptions.md +70 -0
  21. package/assets/worker-kits/growthub-ai-website-cloner-v1/setup/check-deps.sh +50 -0
  22. package/assets/worker-kits/growthub-ai-website-cloner-v1/setup/clone-fork.sh +66 -0
  23. package/assets/worker-kits/growthub-ai-website-cloner-v1/setup/verify-env.mjs +78 -0
  24. package/assets/worker-kits/growthub-ai-website-cloner-v1/skills.md +186 -0
  25. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/asset-manifest.md +57 -0
  26. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/builder-dispatch-plan.md +92 -0
  27. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/clone-brief.md +59 -0
  28. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/component-spec.md +124 -0
  29. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/design-token-extraction.md +89 -0
  30. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/platform-handoff.md +114 -0
  31. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/reconnaissance-report.md +77 -0
  32. package/assets/worker-kits/growthub-ai-website-cloner-v1/templates/visual-qa-checklist.md +107 -0
  33. package/assets/worker-kits/growthub-ai-website-cloner-v1/validation-checklist.md +76 -0
  34. package/assets/worker-kits/growthub-ai-website-cloner-v1/workers/ai-website-cloner-operator/CLAUDE.md +256 -0
  35. package/assets/worker-kits/growthub-open-montage-studio-v1/.env.example +40 -0
  36. package/assets/worker-kits/growthub-open-montage-studio-v1/QUICKSTART.md +114 -0
  37. package/assets/worker-kits/growthub-open-montage-studio-v1/brands/NEW-CLIENT.md +42 -0
  38. package/assets/worker-kits/growthub-open-montage-studio-v1/brands/_template/brand-kit.md +49 -0
  39. package/assets/worker-kits/growthub-open-montage-studio-v1/brands/growthub/brand-kit.md +50 -0
  40. package/assets/worker-kits/growthub-open-montage-studio-v1/bundles/growthub-open-montage-studio-v1.json +55 -0
  41. package/assets/worker-kits/growthub-open-montage-studio-v1/docs/cms-node-bridge.md +152 -0
  42. package/assets/worker-kits/growthub-open-montage-studio-v1/docs/open-montage-fork-integration.md +120 -0
  43. package/assets/worker-kits/growthub-open-montage-studio-v1/docs/pipeline-reference.md +147 -0
  44. package/assets/worker-kits/growthub-open-montage-studio-v1/docs/provider-adapter-layer.md +105 -0
  45. package/assets/worker-kits/growthub-open-montage-studio-v1/examples/cms-node-video-gen-sample.md +109 -0
  46. package/assets/worker-kits/growthub-open-montage-studio-v1/examples/pipeline-selection-sample.md +67 -0
  47. package/assets/worker-kits/growthub-open-montage-studio-v1/examples/platform-ready-handoff-sample.md +101 -0
  48. package/assets/worker-kits/growthub-open-montage-studio-v1/examples/video-production-brief-sample.md +68 -0
  49. package/assets/worker-kits/growthub-open-montage-studio-v1/growthub-meta/README.md +7 -0
  50. package/assets/worker-kits/growthub-open-montage-studio-v1/growthub-meta/kit-standard.md +45 -0
  51. package/assets/worker-kits/growthub-open-montage-studio-v1/kit.json +107 -0
  52. package/assets/worker-kits/growthub-open-montage-studio-v1/output/README.md +34 -0
  53. package/assets/worker-kits/growthub-open-montage-studio-v1/output-standards.md +79 -0
  54. package/assets/worker-kits/growthub-open-montage-studio-v1/runtime-assumptions.md +86 -0
  55. package/assets/worker-kits/growthub-open-montage-studio-v1/setup/check-deps.sh +43 -0
  56. package/assets/worker-kits/growthub-open-montage-studio-v1/setup/clone-fork.sh +53 -0
  57. package/assets/worker-kits/growthub-open-montage-studio-v1/setup/verify-env.mjs +102 -0
  58. package/assets/worker-kits/growthub-open-montage-studio-v1/skills.md +254 -0
  59. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/asset-tracking.md +46 -0
  60. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/cms-node-pipeline-mapping.md +64 -0
  61. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/generation-batch-plan.md +70 -0
  62. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/pipeline-selection-brief.md +67 -0
  63. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/platform-ready-execution-handoff.md +103 -0
  64. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/prompt-matrix.md +48 -0
  65. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/provider-selection-brief.md +86 -0
  66. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/review-qa-checklist.md +59 -0
  67. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/scene-plan.md +65 -0
  68. package/assets/worker-kits/growthub-open-montage-studio-v1/templates/video-production-brief.md +58 -0
  69. package/assets/worker-kits/growthub-open-montage-studio-v1/validation-checklist.md +46 -0
  70. package/assets/worker-kits/growthub-open-montage-studio-v1/workers/open-montage-studio-operator/CLAUDE.md +304 -0
  71. package/assets/worker-kits/growthub-postiz-social-v1/.env.example +18 -0
  72. package/assets/worker-kits/growthub-postiz-social-v1/QUICKSTART.md +136 -0
  73. package/assets/worker-kits/growthub-postiz-social-v1/brands/NEW-CLIENT.md +67 -0
  74. package/assets/worker-kits/growthub-postiz-social-v1/brands/_template/brand-kit.md +120 -0
  75. package/assets/worker-kits/growthub-postiz-social-v1/brands/growthub/brand-kit.md +117 -0
  76. package/assets/worker-kits/growthub-postiz-social-v1/bundles/growthub-postiz-social-v1.json +52 -0
  77. package/assets/worker-kits/growthub-postiz-social-v1/docs/ai-caption-layer.md +118 -0
  78. package/assets/worker-kits/growthub-postiz-social-v1/docs/bullmq-queue-layer.md +157 -0
  79. package/assets/worker-kits/growthub-postiz-social-v1/docs/platform-coverage.md +97 -0
  80. package/assets/worker-kits/growthub-postiz-social-v1/docs/postiz-fork-integration.md +143 -0
  81. package/assets/worker-kits/growthub-postiz-social-v1/examples/analytics-brief-sample.md +125 -0
  82. package/assets/worker-kits/growthub-postiz-social-v1/examples/client-proposal-sample.md +127 -0
  83. package/assets/worker-kits/growthub-postiz-social-v1/examples/content-calendar-sample.md +75 -0
  84. package/assets/worker-kits/growthub-postiz-social-v1/examples/social-campaign-sample.md +104 -0
  85. package/assets/worker-kits/growthub-postiz-social-v1/growthub-meta/README.md +128 -0
  86. package/assets/worker-kits/growthub-postiz-social-v1/growthub-meta/kit-standard.md +113 -0
  87. package/assets/worker-kits/growthub-postiz-social-v1/kit.json +104 -0
  88. package/assets/worker-kits/growthub-postiz-social-v1/output/README.md +56 -0
  89. package/assets/worker-kits/growthub-postiz-social-v1/output-standards.md +127 -0
  90. package/assets/worker-kits/growthub-postiz-social-v1/runtime-assumptions.md +159 -0
  91. package/assets/worker-kits/growthub-postiz-social-v1/setup/check-deps.sh +117 -0
  92. package/assets/worker-kits/growthub-postiz-social-v1/setup/clone-fork.sh +83 -0
  93. package/assets/worker-kits/growthub-postiz-social-v1/setup/verify-env.mjs +99 -0
  94. package/assets/worker-kits/growthub-postiz-social-v1/skills.md +277 -0
  95. package/assets/worker-kits/growthub-postiz-social-v1/templates/analytics-brief.md +123 -0
  96. package/assets/worker-kits/growthub-postiz-social-v1/templates/caption-copy-deck.md +127 -0
  97. package/assets/worker-kits/growthub-postiz-social-v1/templates/client-proposal.md +139 -0
  98. package/assets/worker-kits/growthub-postiz-social-v1/templates/content-calendar.md +65 -0
  99. package/assets/worker-kits/growthub-postiz-social-v1/templates/platform-publishing-plan.md +112 -0
  100. package/assets/worker-kits/growthub-postiz-social-v1/templates/scheduling-manifest.md +83 -0
  101. package/assets/worker-kits/growthub-postiz-social-v1/templates/social-campaign-brief.md +111 -0
  102. package/assets/worker-kits/growthub-postiz-social-v1/validation-checklist.md +79 -0
  103. package/assets/worker-kits/growthub-postiz-social-v1/workers/postiz-social-operator/CLAUDE.md +287 -0
  104. package/assets/worker-kits/growthub-twenty-crm-v1/.env.example +15 -0
  105. package/assets/worker-kits/growthub-twenty-crm-v1/QUICKSTART.md +90 -0
  106. package/assets/worker-kits/growthub-twenty-crm-v1/brands/NEW-CLIENT.md +57 -0
  107. package/assets/worker-kits/growthub-twenty-crm-v1/brands/_template/brand-kit.md +88 -0
  108. package/assets/worker-kits/growthub-twenty-crm-v1/brands/growthub/brand-kit.md +92 -0
  109. package/assets/worker-kits/growthub-twenty-crm-v1/bundles/growthub-twenty-crm-v1.json +56 -0
  110. package/assets/worker-kits/growthub-twenty-crm-v1/docs/api-and-webhooks.md +296 -0
  111. package/assets/worker-kits/growthub-twenty-crm-v1/docs/data-model-layer.md +172 -0
  112. package/assets/worker-kits/growthub-twenty-crm-v1/docs/twenty-fork-integration.md +213 -0
  113. package/assets/worker-kits/growthub-twenty-crm-v1/examples/crm-playbook-sample.md +172 -0
  114. package/assets/worker-kits/growthub-twenty-crm-v1/examples/crm-setup-sample.md +100 -0
  115. package/assets/worker-kits/growthub-twenty-crm-v1/examples/lead-enrichment-sample.md +117 -0
  116. package/assets/worker-kits/growthub-twenty-crm-v1/examples/pipeline-automation-sample.md +132 -0
  117. package/assets/worker-kits/growthub-twenty-crm-v1/growthub-meta/README.md +114 -0
  118. package/assets/worker-kits/growthub-twenty-crm-v1/growthub-meta/kit-standard.md +61 -0
  119. package/assets/worker-kits/growthub-twenty-crm-v1/kit.json +108 -0
  120. package/assets/worker-kits/growthub-twenty-crm-v1/output/README.md +46 -0
  121. package/assets/worker-kits/growthub-twenty-crm-v1/output-standards.md +175 -0
  122. package/assets/worker-kits/growthub-twenty-crm-v1/runtime-assumptions.md +150 -0
  123. package/assets/worker-kits/growthub-twenty-crm-v1/setup/check-deps.sh +56 -0
  124. package/assets/worker-kits/growthub-twenty-crm-v1/setup/clone-fork.sh +77 -0
  125. package/assets/worker-kits/growthub-twenty-crm-v1/setup/verify-env.mjs +105 -0
  126. package/assets/worker-kits/growthub-twenty-crm-v1/skills.md +401 -0
  127. package/assets/worker-kits/growthub-twenty-crm-v1/templates/api-query-plan.md +179 -0
  128. package/assets/worker-kits/growthub-twenty-crm-v1/templates/crm-playbook.md +155 -0
  129. package/assets/worker-kits/growthub-twenty-crm-v1/templates/crm-setup-brief.md +94 -0
  130. package/assets/worker-kits/growthub-twenty-crm-v1/templates/custom-object-design.md +115 -0
  131. package/assets/worker-kits/growthub-twenty-crm-v1/templates/data-model-design.md +112 -0
  132. package/assets/worker-kits/growthub-twenty-crm-v1/templates/enrichment-field-map.md +100 -0
  133. package/assets/worker-kits/growthub-twenty-crm-v1/templates/import-mapping.md +139 -0
  134. package/assets/worker-kits/growthub-twenty-crm-v1/templates/integration-handoff.md +190 -0
  135. package/assets/worker-kits/growthub-twenty-crm-v1/templates/lead-enrichment-pipeline.md +128 -0
  136. package/assets/worker-kits/growthub-twenty-crm-v1/templates/pipeline-automation-brief.md +88 -0
  137. package/assets/worker-kits/growthub-twenty-crm-v1/templates/webhook-integration-spec.md +129 -0
  138. package/assets/worker-kits/growthub-twenty-crm-v1/templates/workspace-config-checklist.md +129 -0
  139. package/assets/worker-kits/growthub-twenty-crm-v1/validation-checklist.md +115 -0
  140. package/assets/worker-kits/growthub-twenty-crm-v1/workers/twenty-crm-operator/CLAUDE.md +310 -0
  141. package/package.json +1 -1
@@ -0,0 +1,99 @@
1
+ #!/usr/bin/env node
2
+ // verify-env.mjs — Verify Postiz fork and kit environment configuration
3
+ // Usage: node setup/verify-env.mjs
4
+
5
+ import { existsSync } from "node:fs";
6
+ import { join } from "node:path";
7
+ import { homedir } from "node:os";
8
+
9
+ const RED = "\x1b[31m";
10
+ const GREEN = "\x1b[32m";
11
+ const YELLOW = "\x1b[33m";
12
+ const RESET = "\x1b[0m";
13
+
14
+ let allPassed = true;
15
+ const results = [];
16
+
17
+ function check(label, passed, detail = "") {
18
+ const icon = passed ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
19
+ results.push({ label, passed, detail, icon });
20
+ if (!passed) allPassed = false;
21
+ }
22
+
23
+ function warn(label, detail = "") {
24
+ results.push({ label, passed: null, detail, icon: `${YELLOW}⚠${RESET}` });
25
+ }
26
+
27
+ console.log("Growthub Postiz Social Media Studio — Environment Verification");
28
+ console.log("=".repeat(60));
29
+ console.log("");
30
+
31
+ // --- Check 1: Postiz fork path ---
32
+ const forkPath = process.env.POSTIZ_FORK_PATH ?? join(homedir(), "postiz-app");
33
+ const forkExists = existsSync(forkPath);
34
+ check("Postiz fork directory exists", forkExists, forkExists ? forkPath : `Not found at ${forkPath}`);
35
+
36
+ if (forkExists) {
37
+ const dockerCompose = existsSync(join(forkPath, "docker-compose.yml"));
38
+ check("docker-compose.yml present in fork", dockerCompose);
39
+
40
+ const envFile = existsSync(join(forkPath, ".env"));
41
+ check("Postiz .env file present", envFile, envFile ? "" : `Run: cp ${forkPath}/.env.example ${forkPath}/.env`);
42
+ }
43
+
44
+ // --- Check 2: Postiz API reachability ---
45
+ const postizApiUrl = process.env.POSTIZ_API_URL ?? "http://localhost:3000";
46
+ let apiHealthy = false;
47
+ try {
48
+ const controller = new AbortController();
49
+ const timeout = setTimeout(() => controller.abort(), 3000);
50
+ const res = await fetch(`${postizApiUrl}/api/healthcheck`, { signal: controller.signal });
51
+ clearTimeout(timeout);
52
+ apiHealthy = res.ok;
53
+ } catch {
54
+ apiHealthy = false;
55
+ }
56
+ check("Postiz API is reachable", apiHealthy, apiHealthy ? postizApiUrl : `Not reachable at ${postizApiUrl} — run: bash setup/clone-fork.sh`);
57
+
58
+ // --- Check 3: Workspace ID ---
59
+ const workspaceId = process.env.POSTIZ_WORKSPACE_ID;
60
+ if (workspaceId && workspaceId !== "your_workspace_uuid_here") {
61
+ check("POSTIZ_WORKSPACE_ID is set", true, workspaceId.slice(0, 8) + "...");
62
+ } else {
63
+ warn("POSTIZ_WORKSPACE_ID not set", "Required for scheduling manifest submission — find it in Postiz Settings > Workspace");
64
+ }
65
+
66
+ // --- Check 4: Anthropic API key ---
67
+ const anthropicKey = process.env.ANTHROPIC_API_KEY;
68
+ if (!anthropicKey || anthropicKey === "your_anthropic_key_here") {
69
+ warn("ANTHROPIC_API_KEY not set", "Optional — required for AI-enhanced caption generation in agent-only and hybrid modes");
70
+ } else if (anthropicKey.startsWith("sk-ant-")) {
71
+ check("ANTHROPIC_API_KEY format is valid", true);
72
+ } else {
73
+ check("ANTHROPIC_API_KEY format is valid", false, "Key does not start with sk-ant- — check your Anthropic console");
74
+ }
75
+
76
+ // --- Print results ---
77
+ console.log("Results:");
78
+ for (const { icon, label, detail } of results) {
79
+ const detailStr = detail ? ` → ${detail}` : "";
80
+ console.log(` ${icon} ${label}${detailStr}`);
81
+ }
82
+
83
+ console.log("");
84
+
85
+ if (allPassed) {
86
+ console.log(`${GREEN}All checks passed. Ready for local-fork or hybrid mode.${RESET}`);
87
+ } else {
88
+ const warnings = results.filter((r) => r.passed === null);
89
+ const failures = results.filter((r) => r.passed === false);
90
+ if (failures.length > 0) {
91
+ console.log(`${RED}${failures.length} check(s) failed. See details above.${RESET}`);
92
+ if (!apiHealthy) {
93
+ console.log(`\n To start Postiz: bash setup/clone-fork.sh`);
94
+ }
95
+ }
96
+ if (warnings.length > 0 && failures.length === 0) {
97
+ console.log(`${YELLOW}Checks passed with warnings. Agent-only mode is available.${RESET}`);
98
+ }
99
+ }
@@ -0,0 +1,277 @@
1
+ # Postiz Social Media Operator — Master Skill Doc
2
+
3
+ **Source of truth for methodology. Read this file completely before beginning any task.**
4
+
5
+ ---
6
+
7
+ ## QUICK REFERENCE TABLE
8
+
9
+ | Resource | Path |
10
+ |---|---|
11
+ | Agent operating law | `workers/postiz-social-operator/CLAUDE.md` |
12
+ | Brand kit template | `brands/_template/brand-kit.md` |
13
+ | Growthub example brand kit | `brands/growthub/brand-kit.md` |
14
+ | Output contract | `output-standards.md` |
15
+ | Runtime assumptions | `runtime-assumptions.md` |
16
+ | Fork integration notes | `docs/postiz-fork-integration.md` |
17
+ | Platform coverage | `docs/platform-coverage.md` |
18
+ | AI caption layer | `docs/ai-caption-layer.md` |
19
+ | BullMQ queue layer | `docs/bullmq-queue-layer.md` |
20
+ | Social campaign brief | `templates/social-campaign-brief.md` |
21
+ | Content calendar | `templates/content-calendar.md` |
22
+ | Platform publishing plan | `templates/platform-publishing-plan.md` |
23
+ | Caption copy deck | `templates/caption-copy-deck.md` |
24
+ | Analytics brief | `templates/analytics-brief.md` |
25
+ | Scheduling manifest | `templates/scheduling-manifest.md` |
26
+ | Client proposal | `templates/client-proposal.md` |
27
+ | Sample campaign | `examples/social-campaign-sample.md` |
28
+ | Sample calendar | `examples/content-calendar-sample.md` |
29
+ | Sample analytics | `examples/analytics-brief-sample.md` |
30
+ | Sample proposal | `examples/client-proposal-sample.md` |
31
+
32
+ ---
33
+
34
+ ## STEP 0 — BEFORE ANY TASK, ANSWER THESE QUESTIONS
35
+
36
+ Before producing anything, confirm:
37
+
38
+ 1. Which client or brand is this campaign for?
39
+ 2. Which platforms are in scope (select from `docs/platform-coverage.md`)?
40
+ 3. What is the campaign objective: brand awareness / lead generation / engagement / product launch / community growth?
41
+ 4. What is the campaign timeframe and posting cadence?
42
+ 5. Is the Postiz fork running locally?
43
+ 6. What execution mode: local-fork / agent-only / hybrid?
44
+
45
+ If any of these are unknown after the 4-question gate in CLAUDE.md, stop and ask.
46
+
47
+ ---
48
+
49
+ ## STEP 1 — LOAD THE BRAND KIT
50
+
51
+ Read `brands/<client-slug>/brand-kit.md` if it exists. Otherwise start from `brands/_template/brand-kit.md`.
52
+
53
+ Extract:
54
+ - client identity (name, slug, industry)
55
+ - target platforms and primary audience demographics
56
+ - content themes and messaging guardrails
57
+ - campaign objectives and KPI targets
58
+ - competitor accounts for reference
59
+ - agency context (prospect stage, retainer range)
60
+ - existing deliverables log
61
+
62
+ The brand kit drives all output naming, tone calibration, platform selection, and proposal pricing context.
63
+
64
+ ---
65
+
66
+ ## STEP 2 — CHECK THE WORKING SUBSTRATE
67
+
68
+ If the user has a local Postiz fork running, inspect it before planning anything.
69
+
70
+ ### Source-of-truth check in the Postiz workspace
71
+
72
+ 1. `docker compose ps` — confirm all services are up (postiz-app, Redis, PostgreSQL)
73
+ 2. `curl http://localhost:3000/api/healthcheck` — confirm API responds
74
+ 3. Postiz admin UI at `http://localhost:3000` — confirm workspace is initialized
75
+ 4. `libraries/nestjs-libraries/src/integrations/` — platform integrations available
76
+ 5. Postiz API → `GET /api/v1/workspace` — retrieve workspace ID for scheduling
77
+
78
+ ### What to verify in the fork
79
+
80
+ - Which platform integrations are connected and authorized in the Postiz admin UI
81
+ - Whether the BullMQ Redis queue is healthy (`GET /api/v1/queue/health`)
82
+ - Whether AI caption generation is enabled (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY` set in Postiz `.env`)
83
+ - What the current workspace posting timezone is set to
84
+
85
+ If the fork cannot be inspected, use the frozen assumptions in `runtime-assumptions.md` and label outputs `assumption-based`.
86
+
87
+ ---
88
+
89
+ ## STEP 3 — COMMAND SELECTION LOGIC
90
+
91
+ Select the narrowest command that satisfies the real job.
92
+
93
+ | Command | Primary Use | Scheduling? | AI Captions? |
94
+ |---|---|---|---|
95
+ | `/postiz campaign` | Full campaign from scratch — brief + calendar + publishing plan + captions | Optional | Yes |
96
+ | `/postiz calendar` | Content calendar for an existing brief | No | Partial |
97
+ | `/postiz captions` | Caption copy deck only — batch or single platform | No | Yes |
98
+ | `/postiz schedule` | Scheduling manifest from an existing calendar | Yes | No |
99
+ | `/postiz analytics` | Analytics briefing from API data or provided metrics | No | No |
100
+ | `/postiz proposal` | Client-ready proposal with platform mix and ROI | No | No |
101
+ | `/postiz platforms` | Platform coverage report for client context | No | No |
102
+ | `/postiz quick` | 30-second campaign snapshot for a domain or brand | No | Minimal |
103
+
104
+ Default selection rules:
105
+ - "Build a campaign" → `/postiz campaign`
106
+ - "Draft captions for my posts" → `/postiz captions`
107
+ - "Schedule my content calendar" → `/postiz schedule`
108
+ - "How did my posts perform?" → `/postiz analytics`
109
+ - "Pitch this to the client" → `/postiz proposal`
110
+ - "What platforms should I be on?" → `/postiz platforms`
111
+
112
+ ---
113
+
114
+ ## STEP 4 — PLATFORM SELECTION LOGIC
115
+
116
+ Select platforms based on: audience demographics, campaign objective, content format, and client capacity.
117
+
118
+ ### Primary platform selection rules
119
+
120
+ | Objective | Recommended Primary Platforms |
121
+ |---|---|
122
+ | Brand awareness | Instagram, TikTok, YouTube |
123
+ | Lead generation | LinkedIn, X/Twitter, Facebook |
124
+ | Community growth | Reddit, Discord, Slack |
125
+ | Product launch | Instagram, TikTok, X/Twitter, YouTube |
126
+ | Thought leadership | LinkedIn, X/Twitter, Bluesky |
127
+ | Local business | Facebook, Instagram, Google Business |
128
+
129
+ ### Platform capacity rules
130
+
131
+ - Limit active platforms to 5 per campaign unless client explicitly has team capacity for more
132
+ - Always check `docs/platform-coverage.md` for per-platform format constraints before assigning content types
133
+ - Carousel posts: available on Instagram, LinkedIn, Pinterest — not TikTok or X
134
+ - Long-form video (>10 min): YouTube only — short-form elsewhere
135
+ - Thread format: X/Twitter, Bluesky, Mastodon
136
+
137
+ ---
138
+
139
+ ## STEP 5 — CAPTION GENERATION LOGIC
140
+
141
+ Apply the AI caption layer for every content calendar entry.
142
+
143
+ ### Caption workflow
144
+
145
+ 1. Extract key message from content theme pillar
146
+ 2. Identify platform tone profile from `docs/ai-caption-layer.md`
147
+ 3. Draft 3 variants (A/B/C):
148
+ - Variant A: Direct and factual
149
+ - Variant B: Storytelling or narrative
150
+ - Variant C: Question or engagement-hook opening
151
+ 4. Apply platform character limits:
152
+ - X/Twitter: 280 characters (aim for ≤240 for re-share space)
153
+ - LinkedIn: 3,000 characters (optimal engagement at 150–300 characters for opening)
154
+ - Instagram: 2,200 characters (optimal: ≤150 characters above "more" fold)
155
+ - TikTok: 2,200 characters (most engagement in first 150 characters)
156
+ - Pinterest: 500 character description
157
+ - Reddit: Variable by subreddit — default to long-form
158
+ - Bluesky: 300 characters
159
+ - Mastodon: 500 characters (instance-configurable)
160
+ 5. Add hashtag sets (platform-appropriate quantity):
161
+ - Instagram: 3–5 primary hashtags (moved away from 30-hashtag practice)
162
+ - LinkedIn: 3–5 relevant professional hashtags
163
+ - TikTok: 3–6 hashtags mixing trending and niche
164
+ - Pinterest: 2–3 keyword-focused hashtags
165
+ - X/Twitter: 1–2 hashtags maximum
166
+ - Bluesky: None required (use in context only)
167
+ 6. Flag any captions that require visual assets with specific format requirements
168
+
169
+ ---
170
+
171
+ ## STEP 6 — CONTENT CALENDAR STRUCTURE
172
+
173
+ The content calendar template produces one row per scheduled post.
174
+
175
+ ### Required columns
176
+
177
+ | Column | Content | Rules |
178
+ |---|---|---|
179
+ | Date | YYYY-MM-DD | Must fall within campaign window |
180
+ | Day | Weekday name | Include for readability |
181
+ | Platform | Platform slug (from coverage doc) | Must be in approved platform list |
182
+ | Content Theme | Theme pillar name | Must be one of 3–5 defined pillars |
183
+ | Post Type | image / video / carousel / text / reel / story | Must be valid for that platform |
184
+ | Caption Preview | First 100 characters of selected variant | Do not paste full caption |
185
+ | CTA | Call-to-action phrase | Required — never "N/A" |
186
+ | Media Notes | Asset requirements, dimensions, duration | Required for image/video/carousel |
187
+ | Status | draft / approved / scheduled / published | Default: draft |
188
+
189
+ ### Cadence rules
190
+
191
+ - Minimum 3 posts per week per platform for meaningful growth signal
192
+ - Maximum 3 posts per day per platform to avoid feed fatigue
193
+ - Space multi-platform posts by at least 30 minutes to avoid simultaneous publishing optics
194
+ - Reserve weekends for engagement/community posts rather than promotional content unless client specifies otherwise
195
+
196
+ ---
197
+
198
+ ## STEP 7 — SCHEDULING MANIFEST FORMAT
199
+
200
+ See `docs/bullmq-queue-layer.md` for full format specification.
201
+
202
+ Quick format reference:
203
+
204
+ ```json
205
+ {
206
+ "postizSchedulingManifest": {
207
+ "version": "1.0",
208
+ "workspaceId": "<postiz-workspace-uuid>",
209
+ "generatedAt": "<ISO-8601-timestamp>",
210
+ "posts": [
211
+ {
212
+ "postId": "<client-slug>-<YYYYMMDD>-<platform>-<sequence>",
213
+ "platform": "<postiz-platform-id>",
214
+ "scheduledAt": "<ISO-8601-timestamp>",
215
+ "content": "<selected-caption-variant>",
216
+ "mediaAssets": [],
217
+ "status": "pending"
218
+ }
219
+ ]
220
+ }
221
+ }
222
+ ```
223
+
224
+ ---
225
+
226
+ ## STEP 8 — ANALYTICS BRIEFING LOGIC
227
+
228
+ When analytics data is provided (from Postiz API export or client-provided metrics):
229
+
230
+ ### Required metrics to collect per platform
231
+
232
+ | Metric | Source | Notes |
233
+ |---|---|---|
234
+ | Impressions | Postiz analytics or platform export | Total times content was displayed |
235
+ | Reach | Platform native | Unique accounts that saw the content |
236
+ | Engagement rate | Calculated: (likes + comments + shares) / impressions × 100 | Platform-normalized |
237
+ | Follower growth | Platform native | Net new followers during period |
238
+ | Link clicks | Postiz UTM tracking or platform bio links | Only for platforms with link support |
239
+ | Top posts | By engagement rate, not raw likes | Surface the 3 best-performing posts |
240
+
241
+ ### Analytics briefing structure
242
+
243
+ 1. Period summary (date range, total posts published, platforms)
244
+ 2. Per-platform performance table (all collected metrics)
245
+ 3. Top 3 performing posts (with engagement rate, format, theme pillar)
246
+ 4. Bottom 3 performing posts (with failure mode hypothesis)
247
+ 5. Recommendations (3–5 actionable items for next period)
248
+ 6. Benchmark comparison (if industry benchmarks are available from brand kit)
249
+
250
+ ---
251
+
252
+ ## STEP 9 — OUTPUT ORDER
253
+
254
+ Produce artifacts in this strict order:
255
+
256
+ 1. Social Campaign Brief (`templates/social-campaign-brief.md`)
257
+ 2. Content Calendar (`templates/content-calendar.md`)
258
+ 3. Platform Publishing Plan (`templates/platform-publishing-plan.md`)
259
+ 4. Caption Copy Deck (`templates/caption-copy-deck.md`)
260
+ 5. Scheduling Manifest (`templates/scheduling-manifest.md`) — only if scheduling requested
261
+ 6. Analytics Brief (`templates/analytics-brief.md`) — only if analytics data available
262
+ 7. Client Proposal (`templates/client-proposal.md`) — only if requested
263
+
264
+ ---
265
+
266
+ ## STEP 10 — QUALITY BAR
267
+
268
+ Good output looks like this:
269
+
270
+ - All platform IDs match the official list in `docs/platform-coverage.md` — no invented platform slugs
271
+ - All caption variants respect the character limits for their target platform
272
+ - Content calendar rows contain no empty CTAs — every post must have an explicit call to action
273
+ - Scheduling manifest timestamps are in ISO 8601 format and fall within the campaign window
274
+ - Analytics briefings derive all metrics from provided data — no invented engagement rates
275
+ - Client proposals ground ROI projections in documented platform benchmark data
276
+ - Every output file can be handed to an operator or client and acted on immediately
277
+ - No filler paragraphs — every sentence either presents data, explains a constraint, or specifies an action
@@ -0,0 +1,123 @@
1
+ # Analytics Brief
2
+
3
+ <!-- Client: [client-slug] | Project: [project-slug] | Version: v1 | Date: YYYY-MM-DD -->
4
+
5
+ ---
6
+
7
+ ## Period Summary
8
+
9
+ | Field | Value |
10
+ |---|---|
11
+ | Client | <!-- client name --> |
12
+ | Campaign | <!-- campaign name --> |
13
+ | Period | <!-- YYYY-MM-DD to YYYY-MM-DD --> |
14
+ | Platforms Analyzed | <!-- comma-separated --> |
15
+ | Total Posts Published | <!-- N --> |
16
+ | Data Source | <!-- Postiz API export / client-provided metrics / Postiz analytics dashboard --> |
17
+
18
+ ---
19
+
20
+ ## Per-Platform Performance
21
+
22
+ | Platform | Impressions | Reach | Engagement Rate | Follower Growth | Link Clicks | Posts Published |
23
+ |---|---|---|---|---|---|---|
24
+ | <!-- instagram --> | <!-- --> | <!-- --> | <!-- N% --> | <!-- +N --> | <!-- N --> | <!-- N --> |
25
+ | <!-- linkedin --> | <!-- --> | <!-- --> | <!-- N% --> | <!-- +N --> | <!-- N --> | <!-- N --> |
26
+ | <!-- tiktok --> | <!-- --> | <!-- --> | <!-- N% --> | <!-- +N --> | <!-- N/A --> | <!-- N --> |
27
+ | <!-- twitter --> | <!-- --> | <!-- --> | <!-- N% --> | <!-- +N --> | <!-- N --> | <!-- N --> |
28
+ | **Totals** | <!-- --> | <!-- --> | <!-- avg --> | <!-- net --> | <!-- --> | <!-- --> |
29
+
30
+ *Engagement Rate = (likes + comments + shares + saves) / impressions × 100*
31
+
32
+ ---
33
+
34
+ ## Top 3 Performing Posts
35
+
36
+ ### #1 Best Performing
37
+
38
+ | Attribute | Value |
39
+ |---|---|
40
+ | Post Date | <!-- YYYY-MM-DD --> |
41
+ | Platform | <!-- --> |
42
+ | Theme Pillar | <!-- --> |
43
+ | Post Type | <!-- --> |
44
+ | Impressions | <!-- --> |
45
+ | Engagement Rate | <!-- N% --> |
46
+ | Caption Preview | <!-- first 100 chars --> |
47
+ | Why It Worked | <!-- hypothesis: format, timing, topic, hook style --> |
48
+
49
+ ---
50
+
51
+ ### #2 Best Performing
52
+
53
+ | Attribute | Value |
54
+ |---|---|
55
+ | Post Date | <!-- --> |
56
+ | Platform | <!-- --> |
57
+ | Theme Pillar | <!-- --> |
58
+ | Post Type | <!-- --> |
59
+ | Impressions | <!-- --> |
60
+ | Engagement Rate | <!-- N% --> |
61
+ | Caption Preview | <!-- --> |
62
+ | Why It Worked | <!-- --> |
63
+
64
+ ---
65
+
66
+ ### #3 Best Performing
67
+
68
+ | Attribute | Value |
69
+ |---|---|
70
+ | Post Date | <!-- --> |
71
+ | Platform | <!-- --> |
72
+ | Theme Pillar | <!-- --> |
73
+ | Post Type | <!-- --> |
74
+ | Impressions | <!-- --> |
75
+ | Engagement Rate | <!-- N% --> |
76
+ | Caption Preview | <!-- --> |
77
+ | Why It Worked | <!-- --> |
78
+
79
+ ---
80
+
81
+ ## Bottom 3 Performing Posts
82
+
83
+ | Post Date | Platform | Theme | Engagement Rate | Failure Hypothesis |
84
+ |---|---|---|---|---|
85
+ | <!-- --> | <!-- --> | <!-- --> | <!-- N% --> | <!-- e.g., Posted at low-engagement time, generic topic, no visual hook --> |
86
+ | <!-- --> | <!-- --> | <!-- --> | <!-- N% --> | <!-- --> |
87
+ | <!-- --> | <!-- --> | <!-- --> | <!-- N% --> | <!-- --> |
88
+
89
+ ---
90
+
91
+ ## KPI vs. Target Comparison
92
+
93
+ | KPI | Target | Actual | Status |
94
+ |---|---|---|---|
95
+ | Impressions | <!-- --> | <!-- --> | <!-- Met / Missed / Exceeded --> |
96
+ | Avg Engagement Rate | <!-- N% --> | <!-- N% --> | <!-- --> |
97
+ | Follower Growth | <!-- +N --> | <!-- +N --> | <!-- --> |
98
+ | Link Clicks | <!-- N --> | <!-- N --> | <!-- --> |
99
+ | Conversions | <!-- N --> | <!-- N --> | <!-- --> |
100
+
101
+ ---
102
+
103
+ ## Recommendations for Next Period
104
+
105
+ <!-- 3–5 specific, actionable recommendations. Each must name the exact platform, format, or behavior to change. -->
106
+
107
+ 1. **Increase [post type] on [platform]:** [Specific recommendation with rationale from data above]
108
+ 2. **Shift [platform] posting time to [time]:** [Reason, referencing best-performing post timing]
109
+ 3. **Add [content format] to [platform]:** [Why — engagement data supports this]
110
+ 4. **Retire [underperforming theme pillar] on [platform]:** [Replace with X — engagement data shows Y]
111
+ 5. **Test [caption variant style] on [platform]:** [Based on the performance gap between variants A and C]
112
+
113
+ ---
114
+
115
+ ## Benchmark Comparison
116
+
117
+ <!-- Compare client performance to industry benchmarks if available from brand kit or third-party sources. -->
118
+
119
+ | Metric | Client Result | Industry Benchmark | Source |
120
+ |---|---|---|---|
121
+ | Instagram engagement rate | <!-- N% --> | <!-- 1.0–3.0% --> | <!-- Rival IQ 2026 Industry Report --> |
122
+ | LinkedIn engagement rate | <!-- N% --> | <!-- 0.5–2.0% --> | <!-- --> |
123
+ | TikTok engagement rate | <!-- N% --> | <!-- 4.0–6.0% --> | <!-- --> |
@@ -0,0 +1,127 @@
1
+ # Caption Copy Deck
2
+
3
+ <!-- Client: [client-slug] | Project: [project-slug] | Version: v1 | Date: YYYY-MM-DD -->
4
+
5
+ ---
6
+
7
+ ## Overview
8
+
9
+ | Field | Value |
10
+ |---|---|
11
+ | Client | <!-- client name --> |
12
+ | Campaign | <!-- campaign name --> |
13
+ | Total Posts | <!-- N --> |
14
+ | Platforms Covered | <!-- comma-separated --> |
15
+
16
+ ---
17
+
18
+ ## Caption Entries
19
+
20
+ <!-- One entry per scheduled post. Entries follow calendar order (date ascending). -->
21
+ <!-- Each entry includes 3 variants (A/B/C) and a selected variant recommendation. -->
22
+
23
+ ---
24
+
25
+ ### Post 001 — <!-- YYYY-MM-DD --> | <!-- platform --> | <!-- Theme Pillar -->
26
+
27
+ **Post Type:** <!-- image / video / carousel / text -->
28
+ **Media Notes:** <!-- asset requirements, dimensions -->
29
+ **CTA:** <!-- exact call-to-action text -->
30
+ **Hashtags:** <!-- #hashtag1 #hashtag2 #hashtag3 -->
31
+
32
+ ---
33
+
34
+ **Variant A — Direct / Factual**
35
+
36
+ > <!-- Caption text. Stays within character limit. Leads with the core fact or insight. -->
37
+
38
+ *Character count: <!-- N --> / <!-- platform limit -->*
39
+
40
+ ---
41
+
42
+ **Variant B — Storytelling / Narrative**
43
+
44
+ > <!-- Caption text. Opens with a scenario or relatable situation before delivering the insight. -->
45
+
46
+ *Character count: <!-- N --> / <!-- platform limit -->*
47
+
48
+ ---
49
+
50
+ **Variant C — Question / Engagement Hook**
51
+
52
+ > <!-- Caption text. Opens with a direct question or provocative statement to drive comments. -->
53
+
54
+ *Character count: <!-- N --> / <!-- platform limit -->*
55
+
56
+ ---
57
+
58
+ **Recommended Variant:** <!-- A / B / C -->
59
+ **Recommendation Rationale:** <!-- e.g., Variant B performs best for this audience on Instagram due to story-first format -->
60
+
61
+ ---
62
+
63
+ ### Post 002 — <!-- YYYY-MM-DD --> | <!-- platform --> | <!-- Theme Pillar -->
64
+
65
+ **Post Type:** <!-- -->
66
+ **Media Notes:** <!-- -->
67
+ **CTA:** <!-- -->
68
+ **Hashtags:** <!-- -->
69
+
70
+ ---
71
+
72
+ **Variant A — Direct / Factual**
73
+
74
+ > <!-- -->
75
+
76
+ *Character count: <!-- N --> / <!-- platform limit -->*
77
+
78
+ ---
79
+
80
+ **Variant B — Storytelling / Narrative**
81
+
82
+ > <!-- -->
83
+
84
+ *Character count: <!-- N --> / <!-- platform limit -->*
85
+
86
+ ---
87
+
88
+ **Variant C — Question / Engagement Hook**
89
+
90
+ > <!-- -->
91
+
92
+ *Character count: <!-- N --> / <!-- platform limit -->*
93
+
94
+ ---
95
+
96
+ **Recommended Variant:** <!-- -->
97
+ **Recommendation Rationale:** <!-- -->
98
+
99
+ ---
100
+
101
+ <!-- Repeat entry block for each post in the content calendar. -->
102
+
103
+ ---
104
+
105
+ ## Hashtag Library
106
+
107
+ <!-- Reusable hashtag sets for each platform and theme pillar. -->
108
+
109
+ ### <!-- Platform: Instagram -->
110
+
111
+ | Pillar | Hashtag Set |
112
+ |---|---|
113
+ | <!-- Industry Insights --> | <!-- #hashtag1 #hashtag2 #hashtag3 --> |
114
+ | <!-- Product Value --> | <!-- --> |
115
+ | <!-- Social Proof --> | <!-- --> |
116
+
117
+ ### <!-- Platform: LinkedIn -->
118
+
119
+ | Pillar | Hashtag Set |
120
+ |---|---|
121
+ | <!-- Industry Insights --> | <!-- #hashtag1 #hashtag2 #hashtag3 --> |
122
+
123
+ ---
124
+
125
+ ## Caption Quality Notes
126
+
127
+ <!-- Any platform-specific constraints, approved terminology, or client-mandated phrases to use or avoid. -->