How thecraighewitt/seomachine works
This repository is a Claude Code workspace for an SEO content operations system, not a conventional application runtime. Its architecture is centered on human-in-the-loop workflows: research, drafting, optimization, rewriting, auditing, and publishing content through structured prompts, agents, and Python analysis modules.
1. Primary orchestration layer: .claude/commands/
The main entry points are custom slash commands such as /research, /write, /rewrite, /analyze-existing, /optimize, /priorities, and the landing-page variants. These command files define the workflow steps and hand off work to agents, context files, or Python-backed analysis. In diagram terms, this is the control plane.
2. Specialized agent layer: .claude/agents/
The agents split responsibilities into narrow roles: content analysis, SEO optimization, meta creation, internal linking, keyword mapping, editing, performance analysis, headline generation, CRO analysis, and landing-page optimization. They are downstream consumers of research briefs, drafts, and context, and they produce structured recommendations rather than final application state.
3. Marketing skill library: .claude/skills/
The skills directory is a reusable knowledge base for specific marketing tasks: copywriting, CRO, paid ads, analytics tracking, A/B testing, schema markup, programmatic SEO, referral programs, and more. Architecturally, these are reference modules that inform agent behavior and command workflows, not executable business logic.
4. Content strategy inputs: context/ and examples/
The repo relies heavily on configuration-like editorial context: brand voice, writing examples, style guide, SEO guidelines, target keywords, internal links map, competitor analysis, and CRO best practices. The examples/castos/ directory shows a fully populated real-world instance of those inputs. These files are the main boundary between generic tooling and business-specific output.
5. Research and generation pipeline: topics/, research/, drafts/, rewrites/, published/
Content moves through a clear lifecycle. Topic ideas start in topics/, research briefs and analysis reports land in research/, first drafts in drafts/, updates in rewrites/, and final assets in published/. This directory structure is the repo’s artifact pipeline and is important for any architecture diagram showing state progression.
6. Analytics and scoring engine: data_sources/modules/
The Python modules under data_sources/modules/ provide the analytical backbone. They include search-intent classification, keyword analysis, content-length comparison, readability scoring, SEO quality rating, opportunity scoring, engagement analysis, competitor gap analysis, article planning, section writing, and social research aggregation. These modules transform raw inputs into scores, recommendations, and content strategy signals.
7. External data integrations: Google Analytics, Search Console, DataForSEO
The repo integrates with GA4, Google Search Console, and DataForSEO through dedicated modules and scripts. These external services supply live performance, ranking, CTR, keyword, and competitor data. The data_aggregator.py module acts as a consolidation point for these sources, which is a key boundary in the system: external telemetry in, prioritized content actions out.
8. Publishing boundary: wordpress/
Publishing is handled through WordPress REST API integration, with a custom MU-plugin (seo-machine-yoast-rest.php) exposing Yoast SEO fields and a theme snippet helper (functions-snippet.php). This is the output boundary of the system, where generated content and metadata leave the Claude workspace and become site content.
9. Operational scripts at repo root
The root Python scripts such as research_quick_wins.py, research_competitor_gaps.py, research_performance_matrix.py, research_serp_analysis.py, research_topic_clusters.py, and seo_competitor_analysis.py are batch analysis entry points. They appear to be standalone orchestration scripts that likely reuse the same modules but run outside the Claude command flow for repeated analysis tasks.
10. Configuration and environment layer: config/, data_sources/config/, .env.example
Repo-level configuration includes competitor templates, credentials templates, and environment setup for API keys and WordPress publishing. This layer defines how the system is adapted per business and how it connects to external services. It is essential to represent as a non-code dependency boundary in the architecture.
11. Caching and ephemeral state: data_sources/cache/
The cache directory indicates that analysis modules store intermediate API responses or derived results locally to reduce repeated external calls. This is an infrastructure concern that sits between analysis modules and third-party APIs, improving speed and cost.
12. Workflow outputs and review artifacts
The repo also contains output-oriented directories like output/, audits/, and landing-pages/ in addition to the main content lifecycle folders. These represent generated reports and content variants used during review, optimization, and conversion-focused work. They are useful to show as side outputs of the analysis pipeline.
13. Two major content tracks: SEO articles and landing pages
The architecture supports both informational SEO content and conversion-oriented landing pages. The article track runs through research → drafting → optimization → publishing, while the landing-page track runs through landing research → landing write → CRO audit → landing publish. They share context and analytics but use different agents and scoring models.
14. Overall system flow
In practice, the system works as: topic or performance signal in → contextual research and external data aggregation → agent-driven analysis and drafting → SEO/CRO optimization and editorial review → WordPress publishing. The key architectural characteristic is that content strategy is data-informed, but final output is generated and curated through layered prompts, templates, and scoring modules rather than a monolithic app server.
Main entry points: commands Commands · modules Scoring modules · research Research · agents Agents
Components 17
Control plane
Claude commands and agents that orchestrate human-in-the-loop workflows.
Knowledge base
Reusable marketing skills and business-specific context inputs.
- Skills · Reusable marketing and growth knowledge used to guide prompts and agent behavior.
.claude/skills - Context · Repository-specific editorial and SEO guidance such as voice, keywords, links, and style.
context - Examples · Concrete business example set used to ground the generic workflows.
examples/castos
Content pipeline
Topic, research, draft, rewrite, and published artifact flow.
- Topics · Seed ideas and content opportunities before research begins.
topics - Research · Research outputs, SERP analysis, competitor gaps, and performance investigation artifacts.
research - Drafts · Working article drafts before optimization or rewrite.
drafts - Rewrites · Updated content versions after audit, optimization, or editorial feedback.
rewrites - Published · Final content artifacts after approval and publishing.
published - Output · Standalone generated reports and content outputs outside the main lifecycle folders.
output
Analytics engine
Python modules that score, analyze, and aggregate external data.
- Data aggregator · Consolidates external telemetry and keyword/ranking data into analysis-ready inputs.
data_sources/modules/data_aggregator.py - Scoring modules · SEO, readability, opportunity, intent, engagement, and landing-page scoring modules.
data_sources/modules - External sources · Live search, traffic, CTR, and competitor data pulled from external services.
data_sources/modules/google_analytics.py
Publishing boundary
WordPress integration and final content handoff.
- WordPress · REST publishing boundary and Yoast field exposure for final site delivery.
wordpress
Other components
- Batch scripts · Root-level analysis entry points for recurring research and ranking workflows.
- Config · Repo and data-source configuration, credentials templates, and environment definitions.
config
Connections 23
- Commands → Agents: dispatches · Slash commands hand work to role-specific agents.
- Commands → Skills: consults · Workflows reference reusable marketing playbooks.
- Commands → Context: grounds in · Commands use brand, SEO, and editorial context.
- Commands → Topics: starts from · Topic and priority commands seed the pipeline.
- Commands → Research: produces · Research commands generate briefs and analysis artifacts.
- Commands → Drafts: writes · Writing commands create draft content.
- Commands → Rewrites: refines · Rewrite and optimize commands create revised assets.
- Agents → Scoring modules: uses · Agents rely on scoring and analysis helpers for recommendations.
- Agents → Context: applies · Agents incorporate repository-specific guidance.
- Examples → Context: instantiates · The example workspace shows a filled-in version of the context layer.
- Topics → Research: feeds · Ideas become research briefs and SERP investigations.
- Research → Drafts: informs · Research outputs shape first drafts.
- Drafts → Rewrites: iterates to · Drafts move into optimization and revision.
- Rewrites → Published: finalizes · Rewritten content becomes publishable output.
- Scoring modules → Data aggregator: converges in · Analytical results are combined through the aggregator.
- Data aggregator → External sources: pulls from · Aggregation depends on live telemetry and keyword services.
- Scoring modules → Research: scores · Analysis modules produce research signals and content recommendations.
- Scoring modules → Output: emits · Batch analysis often lands in generated reports.
- Batch scripts → Scoring modules: reuses · Root scripts reuse the shared Python analysis library.
- Batch scripts → Research: generates · Standalone scripts produce research artifacts.
- WordPress → Published: receives · Final content is handed to the publishing boundary.
- Config → Data aggregator: configures · API keys and source settings shape the analytics layer.
- Config → WordPress: configures · Publishing credentials and site settings control WordPress integration.