@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.
- package/assets/worker-kits/growthub-geo-seo-v1/.env.example +12 -0
- package/assets/worker-kits/growthub-geo-seo-v1/QUICKSTART.md +138 -0
- package/assets/worker-kits/growthub-geo-seo-v1/brands/NEW-CLIENT.md +104 -0
- package/assets/worker-kits/growthub-geo-seo-v1/brands/_template/brand-kit.md +116 -0
- package/assets/worker-kits/growthub-geo-seo-v1/brands/growthub/brand-kit.md +117 -0
- package/assets/worker-kits/growthub-geo-seo-v1/bundles/growthub-geo-seo-v1.json +54 -0
- package/assets/worker-kits/growthub-geo-seo-v1/docs/geo-seo-fork-integration.md +244 -0
- package/assets/worker-kits/growthub-geo-seo-v1/docs/pdf-report-layer.md +139 -0
- package/assets/worker-kits/growthub-geo-seo-v1/docs/scoring-methodology.md +230 -0
- package/assets/worker-kits/growthub-geo-seo-v1/docs/subagent-dispatch.md +273 -0
- package/assets/worker-kits/growthub-geo-seo-v1/examples/citability-sample.md +155 -0
- package/assets/worker-kits/growthub-geo-seo-v1/examples/geo-audit-sample.md +126 -0
- package/assets/worker-kits/growthub-geo-seo-v1/examples/pdf-report-sample.md +207 -0
- package/assets/worker-kits/growthub-geo-seo-v1/examples/prospect-proposal-sample.md +184 -0
- package/assets/worker-kits/growthub-geo-seo-v1/growthub-meta/README.md +124 -0
- package/assets/worker-kits/growthub-geo-seo-v1/growthub-meta/kit-standard.md +116 -0
- package/assets/worker-kits/growthub-geo-seo-v1/kit.json +102 -0
- package/assets/worker-kits/growthub-geo-seo-v1/output/README.md +114 -0
- package/assets/worker-kits/growthub-geo-seo-v1/output-standards.md +143 -0
- package/assets/worker-kits/growthub-geo-seo-v1/runtime-assumptions.md +175 -0
- package/assets/worker-kits/growthub-geo-seo-v1/setup/check-deps.sh +80 -0
- package/assets/worker-kits/growthub-geo-seo-v1/setup/clone-fork.sh +56 -0
- package/assets/worker-kits/growthub-geo-seo-v1/setup/verify-env.mjs +152 -0
- package/assets/worker-kits/growthub-geo-seo-v1/skills.md +359 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/brand-visibility-report.md +101 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/citability-analysis.md +131 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/client-proposal.md +172 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/content-analysis.md +136 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/crawler-access-report.md +115 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/geo-audit-brief.md +114 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/geo-score-summary.md +113 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/llmstxt-plan.md +173 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/remediation-roadmap.md +150 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/schema-validation.md +177 -0
- package/assets/worker-kits/growthub-geo-seo-v1/templates/technical-foundations.md +108 -0
- package/assets/worker-kits/growthub-geo-seo-v1/validation-checklist.md +139 -0
- package/assets/worker-kits/growthub-geo-seo-v1/workers/geo-seo-operator/CLAUDE.md +320 -0
- 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)
|