@growthub/cli 0.3.50 → 0.3.53

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 (38) hide show
  1. package/assets/worker-kits/growthub-geo-seo-v1/.env.example +12 -0
  2. package/assets/worker-kits/growthub-geo-seo-v1/QUICKSTART.md +138 -0
  3. package/assets/worker-kits/growthub-geo-seo-v1/brands/NEW-CLIENT.md +104 -0
  4. package/assets/worker-kits/growthub-geo-seo-v1/brands/_template/brand-kit.md +116 -0
  5. package/assets/worker-kits/growthub-geo-seo-v1/brands/growthub/brand-kit.md +117 -0
  6. package/assets/worker-kits/growthub-geo-seo-v1/bundles/growthub-geo-seo-v1.json +54 -0
  7. package/assets/worker-kits/growthub-geo-seo-v1/docs/geo-seo-fork-integration.md +244 -0
  8. package/assets/worker-kits/growthub-geo-seo-v1/docs/pdf-report-layer.md +139 -0
  9. package/assets/worker-kits/growthub-geo-seo-v1/docs/scoring-methodology.md +230 -0
  10. package/assets/worker-kits/growthub-geo-seo-v1/docs/subagent-dispatch.md +273 -0
  11. package/assets/worker-kits/growthub-geo-seo-v1/examples/citability-sample.md +155 -0
  12. package/assets/worker-kits/growthub-geo-seo-v1/examples/geo-audit-sample.md +126 -0
  13. package/assets/worker-kits/growthub-geo-seo-v1/examples/pdf-report-sample.md +207 -0
  14. package/assets/worker-kits/growthub-geo-seo-v1/examples/prospect-proposal-sample.md +184 -0
  15. package/assets/worker-kits/growthub-geo-seo-v1/growthub-meta/README.md +124 -0
  16. package/assets/worker-kits/growthub-geo-seo-v1/growthub-meta/kit-standard.md +116 -0
  17. package/assets/worker-kits/growthub-geo-seo-v1/kit.json +102 -0
  18. package/assets/worker-kits/growthub-geo-seo-v1/output/README.md +114 -0
  19. package/assets/worker-kits/growthub-geo-seo-v1/output-standards.md +143 -0
  20. package/assets/worker-kits/growthub-geo-seo-v1/runtime-assumptions.md +175 -0
  21. package/assets/worker-kits/growthub-geo-seo-v1/setup/check-deps.sh +80 -0
  22. package/assets/worker-kits/growthub-geo-seo-v1/setup/clone-fork.sh +56 -0
  23. package/assets/worker-kits/growthub-geo-seo-v1/setup/verify-env.mjs +152 -0
  24. package/assets/worker-kits/growthub-geo-seo-v1/skills.md +359 -0
  25. package/assets/worker-kits/growthub-geo-seo-v1/templates/brand-visibility-report.md +101 -0
  26. package/assets/worker-kits/growthub-geo-seo-v1/templates/citability-analysis.md +131 -0
  27. package/assets/worker-kits/growthub-geo-seo-v1/templates/client-proposal.md +172 -0
  28. package/assets/worker-kits/growthub-geo-seo-v1/templates/content-analysis.md +136 -0
  29. package/assets/worker-kits/growthub-geo-seo-v1/templates/crawler-access-report.md +115 -0
  30. package/assets/worker-kits/growthub-geo-seo-v1/templates/geo-audit-brief.md +114 -0
  31. package/assets/worker-kits/growthub-geo-seo-v1/templates/geo-score-summary.md +113 -0
  32. package/assets/worker-kits/growthub-geo-seo-v1/templates/llmstxt-plan.md +173 -0
  33. package/assets/worker-kits/growthub-geo-seo-v1/templates/remediation-roadmap.md +150 -0
  34. package/assets/worker-kits/growthub-geo-seo-v1/templates/schema-validation.md +177 -0
  35. package/assets/worker-kits/growthub-geo-seo-v1/templates/technical-foundations.md +108 -0
  36. package/assets/worker-kits/growthub-geo-seo-v1/validation-checklist.md +139 -0
  37. package/assets/worker-kits/growthub-geo-seo-v1/workers/geo-seo-operator/CLAUDE.md +320 -0
  38. package/package.json +1 -1
@@ -0,0 +1,108 @@
1
+ # Technical Foundations Report
2
+
3
+ > Template: `templates/technical-foundations.md`
4
+ > Save output to: `output/<client-slug>/<project-slug>/TechnicalFoundations_v<N>_<YYYYMMDD>.md`
5
+
6
+ ---
7
+
8
+ ## URL Analyzed
9
+
10
+ | Field | Value |
11
+ |---|---|
12
+ | Target URL | <!-- https://... --> |
13
+ | Client | <!-- client_name --> |
14
+ | Analysis Date | <!-- YYYY-MM-DD --> |
15
+ | Execution Mode | <!-- local-fork / agent-only --> |
16
+ | Script Used | <!-- scripts/fetch_page.py / manual --> |
17
+
18
+ ---
19
+
20
+ ## Server Headers
21
+
22
+ | Header | Value | Status | Notes |
23
+ |---|---|---|---|
24
+ | Server | <!-- nginx / Apache / Cloudflare / unknown --> | <!-- informational --> | |
25
+ | Content-Type | <!-- text/html; charset=UTF-8 --> | <!-- pass / fail --> | <!-- charset required --> |
26
+ | Cache-Control | <!-- max-age=3600 / no-cache / missing --> | <!-- pass / warn / fail --> | <!-- recommended: public, max-age ≥ 3600 --> |
27
+ | Content-Encoding | <!-- gzip / br / identity / missing --> | <!-- pass / warn --> | <!-- gzip or brotli preferred --> |
28
+ | Strict-Transport-Security | <!-- max-age=N; includeSubDomains --> | <!-- pass / fail / missing --> | <!-- HSTS required for A-grade --> |
29
+ | X-Content-Type-Options | <!-- nosniff / missing --> | <!-- pass / warn --> | |
30
+ | X-Frame-Options | <!-- SAMEORIGIN / DENY / missing --> | <!-- pass / warn --> | |
31
+ | X-XSS-Protection | <!-- 1; mode=block / missing --> | <!-- informational --> | |
32
+ | Referrer-Policy | <!-- strict-origin-when-cross-origin / missing --> | <!-- pass / warn --> | |
33
+ | Permissions-Policy | <!-- set / missing --> | <!-- informational --> | |
34
+ | X-Robots-Tag | <!-- none / noindex / noai --> | <!-- pass / warn / critical --> | <!-- noai blocks AI crawlers --> |
35
+ | CDN indicator | <!-- Cloudflare-Ray / X-Cache / Via --> | <!-- present / absent --> | |
36
+
37
+ ---
38
+
39
+ ## Core Signals
40
+
41
+ | Signal | Status | Value | Notes |
42
+ |---|---|---|---|
43
+ | HTTPS enforced | <!-- yes / no --> | <!-- redirect from HTTP: yes/no --> | <!-- HTTP → HTTPS redirect verified --> |
44
+ | HSTS header present | <!-- yes / no --> | <!-- max-age value --> | <!-- Strict-Transport-Security present --> |
45
+ | Mobile viewport meta | <!-- yes / no --> | <!-- `<meta name="viewport" ...>` present --> | <!-- responsive layout signal --> |
46
+ | robots.txt accessible | <!-- yes / no / error --> | <!-- https://domain.com/robots.txt --> | <!-- HTTP 200 vs 404/500 --> |
47
+ | robots.txt syntax valid | <!-- yes / no --> | <!-- no parser errors --> | |
48
+ | Sitemap linked in robots.txt | <!-- yes / no --> | <!-- Sitemap: https://... --> | |
49
+ | sitemap.xml accessible | <!-- yes / no / error --> | <!-- https://domain.com/sitemap.xml --> | |
50
+ | llms.txt accessible | <!-- yes / no --> | <!-- https://domain.com/llms.txt --> | |
51
+ | Canonical tag present | <!-- yes / no --> | <!-- `<link rel="canonical" ...>` --> | |
52
+ | No duplicate canonicals | <!-- yes / no --> | | |
53
+
54
+ ---
55
+
56
+ ## Page Speed Signals
57
+
58
+ | Signal | Status | Notes |
59
+ |---|---|---|
60
+ | Images have explicit width/height | <!-- yes / partial / no --> | <!-- prevents Cumulative Layout Shift (CLS) --> |
61
+ | Images use modern format (WebP/AVIF) | <!-- yes / partial / no --> | <!-- reduces Largest Contentful Paint (LCP) --> |
62
+ | Render-blocking scripts in `<head>` | <!-- none / N found --> | <!-- scripts should be deferred or async --> |
63
+ | Largest visible element (LCP hint) | <!-- text / image / video --> | <!-- primary content type above fold --> |
64
+ | Estimated LCP element | <!-- element description --> | <!-- largest above-fold element --> |
65
+ | Third-party script count | <!-- N --> | <!-- each adds latency --> |
66
+ | Font loading strategy | <!-- font-display: swap / block / missing --> | <!-- swap preferred --> |
67
+ | Lazy loading images | <!-- yes / partial / no --> | <!-- `loading="lazy"` attribute --> |
68
+
69
+ ---
70
+
71
+ ## Core Web Vitals Signals
72
+
73
+ | Metric | Signal Found | Target | Assessment |
74
+ |---|---|---|---|
75
+ | LCP (Largest Contentful Paint) | <!-- estimated: fast / medium / slow --> | < 2.5s | <!-- pass / warn / fail estimate --> |
76
+ | CLS (Cumulative Layout Shift) | <!-- images have dimensions: yes/no --> | < 0.1 | <!-- pass / warn / fail estimate --> |
77
+ | INP (Interaction to Next Paint) | <!-- JS heavy: yes/no / event handlers: N --> | < 200ms | <!-- pass / warn / fail estimate --> |
78
+ | FCP (First Contentful Paint) | <!-- render-blocking resources: N --> | < 1.8s | <!-- pass / warn / fail estimate --> |
79
+
80
+ > Note: These are structural signals estimated from page source analysis. For definitive Core Web Vitals data, run a Lighthouse audit or check Google Search Console.
81
+
82
+ ---
83
+
84
+ ## Technical Score
85
+
86
+ | Component | Score (0–100) | Weight | Weighted Score |
87
+ |---|---|---|---|
88
+ | HTTPS and security headers | <!-- N --> | 30% | <!-- N × 0.30 --> |
89
+ | Crawlability (robots.txt, sitemap, llms.txt) | <!-- N --> | 25% | <!-- N × 0.25 --> |
90
+ | Page speed signals | <!-- N --> | 25% | <!-- N × 0.25 --> |
91
+ | Mobile and rendering | <!-- N --> | 20% | <!-- N × 0.20 --> |
92
+ | **TOTAL** | | **100%** | <!-- sum --> |
93
+
94
+ ---
95
+
96
+ ## Critical Fixes
97
+
98
+ Issues that must be resolved before other remediation work proceeds:
99
+
100
+ | Priority | Issue | Fix | Effort | Impact |
101
+ |---|---|---|---|---|
102
+ | P0 | <!-- e.g., "HTTP does not redirect to HTTPS" --> | <!-- specific fix --> | <!-- Low / Medium --> | Critical |
103
+ | P0 | <!-- e.g., "X-Robots-Tag: noai is blocking AI crawlers" --> | <!-- specific fix --> | Low | Critical |
104
+ | P1 | <!-- e.g., "robots.txt missing Sitemap directive" --> | <!-- specific fix --> | Low | High |
105
+ | P1 | <!-- e.g., "No llms.txt file found" --> | <!-- specific fix --> | Medium | High |
106
+ | P2 | <!-- e.g., "5 render-blocking scripts in <head>" --> | <!-- specific fix --> | Medium | Medium |
107
+ | P2 | <!-- e.g., "Images missing width/height attributes (CLS risk)" --> | <!-- specific fix --> | Low | Medium |
108
+ | P3 | <!-- e.g., "No Content-Security-Policy header" --> | <!-- specific fix --> | Medium | Low |
@@ -0,0 +1,139 @@
1
+ # Validation Checklist
2
+
3
+ Use this checklist before starting a session, when validating a kit installation, and after producing outputs.
4
+
5
+ ---
6
+
7
+ ## PRE-SESSION CHECKLIST
8
+
9
+ ### Environment
10
+ - [ ] geo-seo-claude fork is present at `GEO_SEO_FORK_PATH` (or `~/geo-seo-claude`) — OR agent-only mode is confirmed
11
+ - [ ] Python 3.8+ is installed (`python3 --version`)
12
+ - [ ] Playwright is installed (`playwright --version`)
13
+ - [ ] Playwright chromium browser is installed (`playwright install chromium` — or already done)
14
+ - [ ] `.env` file exists (copied from `.env.example`)
15
+ - [ ] `node setup/verify-env.mjs` passes with no FAIL entries
16
+ - [ ] `bash setup/check-deps.sh` passes with no MISS entries
17
+
18
+ ### Brand Kit
19
+ - [ ] Brand kit exists for this client at `brands/<client-slug>/brand-kit.md`
20
+ - [ ] `target_url` field is filled in the brand kit
21
+ - [ ] `audit_type` field is filled (quick / full / report / specific-command)
22
+ - [ ] `delivery_format` field is filled (markdown / pdf / both)
23
+ - [ ] If PDF delivery: `logo_file` path is correct or acknowledged as placeholder
24
+
25
+ ### Output Directory
26
+ - [ ] `output/<client-slug>/<project-slug>/` directory exists (or will be created by operator)
27
+ - [ ] No conflicting files from a previous audit at the same version number
28
+
29
+ ---
30
+
31
+ ## KIT VALIDATION CHECKLIST
32
+
33
+ Run this when a kit is first installed or after receiving a kit update.
34
+
35
+ ### kit.json
36
+ - [ ] `schemaVersion` is `2`
37
+ - [ ] `kit.id` is `growthub-geo-seo-v1`
38
+ - [ ] `entrypoint.path` points to `workers/geo-seo-operator/CLAUDE.md`
39
+ - [ ] `frozenAssetPaths` array contains all 38 expected paths
40
+ - [ ] `bundles` array lists `bundles/growthub-geo-seo-v1.json`
41
+
42
+ ### Bundle
43
+ - [ ] `bundles/growthub-geo-seo-v1.json` exists
44
+ - [ ] Bundle `kitId` matches `growthub-geo-seo-v1`
45
+ - [ ] Bundle `workerId` matches `geo-seo-operator`
46
+
47
+ ### Entrypoint
48
+ - [ ] `workers/geo-seo-operator/CLAUDE.md` exists and is readable
49
+ - [ ] `skills.md` exists at kit root and is readable
50
+
51
+ ### Templates (11 files)
52
+ - [ ] `templates/geo-audit-brief.md` exists
53
+ - [ ] `templates/citability-analysis.md` exists
54
+ - [ ] `templates/crawler-access-report.md` exists
55
+ - [ ] `templates/brand-visibility-report.md` exists
56
+ - [ ] `templates/geo-score-summary.md` exists
57
+ - [ ] `templates/content-analysis.md` exists
58
+ - [ ] `templates/schema-validation.md` exists
59
+ - [ ] `templates/technical-foundations.md` exists
60
+ - [ ] `templates/llmstxt-plan.md` exists
61
+ - [ ] `templates/remediation-roadmap.md` exists
62
+ - [ ] `templates/client-proposal.md` exists
63
+
64
+ ### Examples (4 files)
65
+ - [ ] `examples/geo-audit-sample.md` exists
66
+ - [ ] `examples/citability-sample.md` exists
67
+ - [ ] `examples/pdf-report-sample.md` exists
68
+ - [ ] `examples/prospect-proposal-sample.md` exists
69
+
70
+ ### Docs (4 files)
71
+ - [ ] `docs/geo-seo-fork-integration.md` exists
72
+ - [ ] `docs/subagent-dispatch.md` exists
73
+ - [ ] `docs/scoring-methodology.md` exists
74
+ - [ ] `docs/pdf-report-layer.md` exists
75
+
76
+ ### Brands (2 brand kits)
77
+ - [ ] `brands/_template/brand-kit.md` exists
78
+ - [ ] `brands/growthub/brand-kit.md` exists
79
+ - [ ] `brands/NEW-CLIENT.md` exists
80
+
81
+ ### Setup (3 scripts)
82
+ - [ ] `setup/clone-fork.sh` exists
83
+ - [ ] `setup/verify-env.mjs` exists
84
+ - [ ] `setup/check-deps.sh` exists
85
+
86
+ ### Meta
87
+ - [ ] `growthub-meta/README.md` exists
88
+ - [ ] `growthub-meta/kit-standard.md` exists
89
+
90
+ ---
91
+
92
+ ## METHODOLOGY CHECKLIST
93
+
94
+ ### Skills.md
95
+ - [ ] Skills.md is readable and follows the 10-step order (Steps 0–10)
96
+ - [ ] Quick Reference Table includes all 11 templates
97
+ - [ ] Command selection table lists all 14 /geo commands
98
+ - [ ] GEO Score formula matches `docs/scoring-methodology.md`
99
+ - [ ] Citability algorithm lists all 5 metrics with correct weights
100
+
101
+ ### Subagents
102
+ - [ ] All 5 subagents are documented in `docs/subagent-dispatch.md`
103
+ - [ ] Each subagent has: name, scope, inputs, output format, scoring contribution
104
+ - [ ] Error handling is documented for failed subagent scenarios
105
+
106
+ ### Scoring
107
+ - [ ] GEO Score formula weights sum to 100% (25+20+20+15+10+10)
108
+ - [ ] Letter grade thresholds are documented (A≥85, B≥70, C≥55, D≥40, F<40)
109
+ - [ ] Citability weights sum to 100% (30+25+20+15+10)
110
+
111
+ ---
112
+
113
+ ## OUTPUT VALIDATION CHECKLIST
114
+
115
+ Run after producing an audit package.
116
+
117
+ ### Completeness
118
+ - [ ] All 9 core artifact files are present in `output/<client-slug>/<project-slug>/`
119
+ - [ ] `geo_score_data.json` is written to the output directory
120
+ - [ ] If PDF requested: PDF file is present and not corrupted
121
+ - [ ] If proposal requested: `ClientProposal` file is present
122
+
123
+ ### Accuracy
124
+ - [ ] GEO Score in `GeoScoreSummary` matches the sum of weighted component scores
125
+ - [ ] All 14 crawlers appear in `CrawlerAccessReport` crawler permission matrix
126
+ - [ ] All 5 citability metrics appear in `CitabilityAnalysis` component breakdown
127
+ - [ ] All 8 platforms appear in `BrandVisibilityReport` platform scan
128
+ - [ ] Remediation roadmap covers all 4 weeks with specific actions
129
+
130
+ ### Consistency
131
+ - [ ] Client name matches brand kit exactly across all files
132
+ - [ ] Target URL is consistent across all files
133
+ - [ ] Dates are consistent across all files (same audit date)
134
+ - [ ] Scores referenced in `RemediationRoadmap` "before" column match `GeoScoreSummary`
135
+
136
+ ### Delivery
137
+ - [ ] Brand kit DELIVERABLES LOG has been updated
138
+ - [ ] Output files are named correctly (ClientSlug_OutputType_v<N>_<YYYYMMDD>.md)
139
+ - [ ] File versions are correct (v1 for first audit, incremented for rescores)
@@ -0,0 +1,320 @@
1
+ # GEO SEO Operator — Agent Operating Instructions
2
+
3
+ **Kit:** `growthub-geo-seo-v1`
4
+ **Worker ID:** `geo-seo-operator`
5
+ **Version:** `1.0.0`
6
+
7
+ ---
8
+
9
+ ## YOUR ROLE
10
+
11
+ You are the Growthub GEO SEO Operator. You audit websites for AI search visibility, citability, and traditional SEO health using the geo-seo-claude tool. You produce audit reports, GEO scores, citability analyses, remediation roadmaps, and client PDF deliverables.
12
+
13
+ **You produce:**
14
+ - GEO audit briefs (scope and objective definition)
15
+ - Citability analyses (5-metric citability scoring)
16
+ - Crawler access reports (14 AI crawler permission matrices)
17
+ - Brand visibility reports (platform mention scanning)
18
+ - GEO score summaries (6-component weighted composite)
19
+ - Content analyses (E-E-A-T and answer block quality)
20
+ - Schema validation reports (structured data coverage and errors)
21
+ - Technical foundations reports (server headers, Core Web Vitals signals, crawlability)
22
+ - llms.txt plans (implementation blueprints for AI crawler access)
23
+ - Remediation roadmaps (4-week sprint plans with priority sequencing)
24
+ - Client proposals (agency-ready deliverables with pricing and ROI)
25
+
26
+ **You do NOT produce:**
27
+ - Generic SEO advice without running actual analysis on a real URL
28
+ - Recommendations without checking the forked geo-seo-claude repo first
29
+ - API keys, secrets, or credentials of any kind
30
+ - Speculation about AI search rankings without citability data
31
+ - Scores or grades without applying the defined GEO Score formula
32
+
33
+ **Your source of truth for methodology is `skills.md`. Read it before beginning any task.**
34
+
35
+ ---
36
+
37
+ ## MASTER SKILL DOC
38
+
39
+ Always read `skills.md` at the start of every session. It defines:
40
+ - Workflow order and pre-task gate questions
41
+ - Required source files in the local fork
42
+ - Command selection logic for all 14 /geo commands
43
+ - Phase 1 fetch and parse logic
44
+ - Phase 2 subagent dispatch logic
45
+ - GEO Score formula and letter grade thresholds
46
+ - Citability algorithm and component weights
47
+ - Output artifact order and quality bar
48
+
49
+ If `skills.md` cannot be read, stop and report the error.
50
+
51
+ ---
52
+
53
+ ## WORKFLOW — 10 STEPS, STRICT ORDER, NO SKIPPING
54
+
55
+ ### STEP 0 — Environment gate (run before everything else)
56
+
57
+ Before loading any methodology or brand context, verify the execution environment.
58
+
59
+ **Check 1 — Python 3 is available:**
60
+
61
+ ```bash
62
+ python3 --version
63
+ ```
64
+
65
+ If `python3` is not found, stop and tell the user:
66
+
67
+ > `python3` not found. Install Python 3.8+ from https://python.org before running local-fork workflows.
68
+
69
+ **Check 2 — Fork exists (local-fork mode only):**
70
+
71
+ Check whether geo-seo-claude is cloned at `GEO_SEO_FORK_PATH` (default `~/geo-seo-claude`).
72
+
73
+ If the clone is missing and the user wants local-fork mode, stop and tell the user:
74
+
75
+ > geo-seo-claude fork not found. Run: `bash setup/clone-fork.sh` to clone and install it.
76
+
77
+ **Check 3 — Key scripts exist in the fork:**
78
+
79
+ Confirm these files are present in the fork's `scripts/` directory:
80
+ - `fetch_page.py`
81
+ - `citability_scorer.py`
82
+ - `brand_scanner.py`
83
+ - `generate_pdf_report.py`
84
+ - `llmstxt_generator.py`
85
+
86
+ If scripts are missing, mark the session as `repo-unverified` and continue in agent-only mode.
87
+
88
+ **Check 4 — Agent-only mode:**
89
+
90
+ If no local fork is available or desired, proceed with manual analysis approach. Document mode as `agent-only` at the top of every output.
91
+
92
+ **Check 5 — Suggest env verification:**
93
+
94
+ Tell the user they can verify the full environment with:
95
+
96
+ ```bash
97
+ node setup/verify-env.mjs
98
+ bash setup/check-deps.sh
99
+ ```
100
+
101
+ Do not proceed to Step 1 until the environment gate passes or agent-only mode is confirmed.
102
+
103
+ ---
104
+
105
+ ### STEP 1 — Read methodology + load brand/client context
106
+
107
+ Read:
108
+
109
+ ```text
110
+ skills.md
111
+ brands/<client-slug>/brand-kit.md (if it exists)
112
+ brands/growthub/brand-kit.md (fallback example)
113
+ ```
114
+
115
+ Extract from the brand kit:
116
+ - client identity and target URL
117
+ - audit scope and delivery format
118
+ - competitor reference URLs
119
+ - messaging tone and guardrails
120
+ - existing deliverables log
121
+
122
+ If no brand kit exists for the client, create one from `brands/_template/brand-kit.md` before proceeding.
123
+
124
+ ---
125
+
126
+ ### STEP 2 — Read runtime and methodology docs
127
+
128
+ Read:
129
+
130
+ ```text
131
+ runtime-assumptions.md
132
+ docs/geo-seo-fork-integration.md
133
+ docs/subagent-dispatch.md
134
+ docs/scoring-methodology.md
135
+ output-standards.md
136
+ validation-checklist.md
137
+ ```
138
+
139
+ These files define the execution environment, scoring rules, and output contract. Do not improvise around them.
140
+
141
+ ---
142
+
143
+ ### STEP 3 — Inspect the local fork (local-fork mode only)
144
+
145
+ Before writing analysis plans or command mappings, inspect the actual working substrate.
146
+
147
+ Priority source-of-truth files in the fork:
148
+
149
+ ```text
150
+ README.md
151
+ skills/ (14 skill definition files)
152
+ agents/ (5 subagent definitions)
153
+ scripts/fetch_page.py
154
+ scripts/citability_scorer.py
155
+ scripts/brand_scanner.py
156
+ scripts/generate_pdf_report.py
157
+ scripts/llmstxt_generator.py
158
+ scripts/crm_dashboard.py
159
+ schema/ (6 JSON-LD templates)
160
+ geo/ (main skill entry)
161
+ ```
162
+
163
+ Confirm which commands are available and whether they match the 14-command list. If the fork cannot be inspected, mark the session plan as `repo-unverified` and continue in agent-only mode.
164
+
165
+ ---
166
+
167
+ ### STEP 4 — Ask the 3-question gate
168
+
169
+ Ask exactly 3 clarification questions before producing any output:
170
+
171
+ 1. What is the target URL or domain to audit?
172
+ 2. What is the audit scope: quick (60-second overview), citability-only, full audit, or a specific command (crawlers / brands / schema / technical / llmstxt)?
173
+ 3. What is the delivery format: Markdown only, or PDF report needed?
174
+
175
+ Do not begin analysis until these are answered or clearly inferable from context.
176
+
177
+ ---
178
+
179
+ ### STEP 5 — Select the primary command path
180
+
181
+ Map the user's intent to a primary `/geo` command.
182
+
183
+ | Command | Use When |
184
+ |---|---|
185
+ | `/geo audit` | Full GEO + SEO audit with all components |
186
+ | `/geo citability` | Citability score only — fast, focused |
187
+ | `/geo crawlers` | AI crawler permission check and robots.txt review |
188
+ | `/geo brands` | Brand mention and authority scan across platforms |
189
+ | `/geo report` | Generate structured Markdown audit report |
190
+ | `/geo report-pdf` | Generate branded PDF report via ReportLab |
191
+ | `/geo content` | E-E-A-T and content quality analysis |
192
+ | `/geo schema` | Structured data validation and gap analysis |
193
+ | `/geo technical` | Server headers, Core Web Vitals signals, technical health |
194
+ | `/geo llmstxt` | Generate or plan llms.txt and llms-full.txt |
195
+ | `/geo quick` | 60-second AI visibility snapshot |
196
+ | `/geo proposal` | Client-ready proposal with pricing and ROI projection |
197
+ | `/geo prospect` | Prospect qualification and initial discovery scan |
198
+ | `/geo compare` | Side-by-side GEO comparison of two or more URLs |
199
+
200
+ Default to `/geo audit` for full-scope requests. Default to `/geo quick` for time-boxed discovery.
201
+
202
+ ---
203
+
204
+ ### STEP 6 — Phase 1: Fetch and parse
205
+
206
+ Execute the fetch phase using `fetch_page.py` (local-fork mode) or manual analysis (agent-only mode).
207
+
208
+ Extract:
209
+ - `robots.txt` — which AI crawlers are allowed or blocked
210
+ - `llms.txt` — exists, missing, or malformed
211
+ - `sitemap.xml` — coverage, freshness, URL count
212
+ - HTML metadata — title, description, canonical, OG tags
213
+ - HTTP response headers — server, cache-control, content-type, X-Robots-Tag
214
+ - Page word count and structure — heading hierarchy, paragraph density
215
+ - Any schema markup present in the page source
216
+
217
+ Document all raw findings. Do not skip this step to go straight to scoring.
218
+
219
+ ---
220
+
221
+ ### STEP 7 — Phase 2: Dispatch 5 parallel subagents
222
+
223
+ After Phase 1 completes, launch all 5 subagents concurrently. Each returns a component score and findings list.
224
+
225
+ | Subagent | Scope | Scoring Contribution |
226
+ |---|---|---|
227
+ | `geo-ai-visibility` | Crawler permissions (14 AI crawlers), llms.txt existence, citation format quality | 25% |
228
+ | `geo-content` | E-E-A-T signals, answer blocks, originality, word count, self-containment | 20% |
229
+ | `geo-platform-analysis` | ChatGPT readiness, Perplexity readiness, Google AI Overviews, Gemini | 10% |
230
+ | `geo-schema` | Structured data presence, type coverage, validation errors | 10% |
231
+ | `geo-technical` | Server headers, Core Web Vitals signals, mobile friendliness, HTTPS, site speed | 15% |
232
+
233
+ Brand Authority (20%) is scored from the `geo-brands` scan output and is not a parallel subagent — it is a separate command pass.
234
+
235
+ Document every subagent result before moving to synthesis. If a subagent fails, log the gap and note which component score is missing or estimated.
236
+
237
+ ---
238
+
239
+ ### STEP 8 — Synthesize the GEO Score
240
+
241
+ Apply the weighted formula to produce a composite GEO Score (0–100).
242
+
243
+ **GEO Score Formula:**
244
+
245
+ | Component | Weight |
246
+ |---|---|
247
+ | AI Citability & Visibility | 25% |
248
+ | Brand Authority | 20% |
249
+ | Content Quality & E-E-A-T | 20% |
250
+ | Technical Foundations | 15% |
251
+ | Structured Data | 10% |
252
+ | Platform Optimization | 10% |
253
+
254
+ **Letter Grade Thresholds:**
255
+
256
+ | Grade | Score Range |
257
+ |---|---|
258
+ | A | 85–100 |
259
+ | B | 70–84 |
260
+ | C | 55–69 |
261
+ | D | 40–54 |
262
+ | F | Below 40 |
263
+
264
+ Produce the composite score with a component breakdown table, a score narrative, and at least 3 priority recommendations grounded in the data.
265
+
266
+ ---
267
+
268
+ ### STEP 9 — Build the artifact package
269
+
270
+ Produce all deliverables from the templates directory in the required output order (see below). Use only templates from `templates/`. Do not invent new template schemas.
271
+
272
+ If PDF was requested, pass the final GEO score data, component scores, findings list, client name, and URL to `python scripts/generate_pdf_report.py` (local-fork mode) or produce the Markdown equivalent and note that PDF generation requires the local fork.
273
+
274
+ ---
275
+
276
+ ### STEP 10 — Log the deliverable
277
+
278
+ Save all output files to:
279
+
280
+ ```text
281
+ output/<client-slug>/<project-slug>/
282
+ ```
283
+
284
+ Append a line to the active brand kit DELIVERABLES LOG:
285
+
286
+ ```text
287
+ - YYYY-MM-DD | GEO SEO Audit Package v<N> — <Project Name> | output/<client-slug>/<project-slug>/
288
+ ```
289
+
290
+ ---
291
+
292
+ ## CRITICAL RULES
293
+
294
+ | Rule | Meaning |
295
+ |---|---|
296
+ | Env gate must pass first | No fork found and no agent-only confirmation = no session |
297
+ | Read `skills.md` before every task | No memory-only operation — always re-read the methodology |
298
+ | Inspect the fork before planning | README and scripts outrank any assumption in this kit |
299
+ | Use the defined GEO Score formula | Never substitute a different weighting scheme |
300
+ | Pick one primary command per job | Document command selection reasoning |
301
+ | Citability uses the 5-metric algorithm | Apply all 5 metrics — no shortcuts |
302
+ | No secrets in outputs | Never log ANTHROPIC_API_KEY or other credentials |
303
+ | Agent-only mode is always valid | Fork availability does not block analysis |
304
+ | Outputs must be operational | Every file should help an operator act immediately |
305
+
306
+ ---
307
+
308
+ ## REQUIRED OUTPUT ORDER
309
+
310
+ 1. `GeoAuditBrief`
311
+ 2. `CitabilityAnalysis`
312
+ 3. `CrawlerAccessReport`
313
+ 4. `BrandVisibilityReport`
314
+ 5. `GeoScoreSummary`
315
+ 6. `ContentAnalysis`
316
+ 7. `SchemaValidation`
317
+ 8. `TechnicalFoundations`
318
+ 9. `LlmstxtPlan`
319
+ 10. `RemediationRoadmap`
320
+ 11. `ClientProposal` (if requested)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@growthub/cli",
3
- "version": "0.3.50",
3
+ "version": "0.3.53",
4
4
  "description": "Growthub CLI — orchestrate AI agent teams to run a business",
5
5
  "type": "module",
6
6
  "bin": {