Search Intent Automation

Deterministic search-intent automation for coding agents with validated JSON contracts, manifest-relative artifact handling, and resumable CLI subcommands.

This project turns a seed topic into a repeatable research pipeline using:

• Ubersuggest
• AnswerThePublic
• Playwright MCP
• Python CLI orchestration

The original source workflow used Make.com as the automation layer. This repo preserves the research sequence but replaces the implementation layer with Playwright MCP capture plus a Python package that handles normalization, checkpoints, and resumable flows.

Install

pip install search-intent-automation

For local development:

python -m pip install -e .[dev]

More setup options live in docs/installation.md.

Primary commands

• search-intent-automation init --workdir ...
• search-intent-automation validate --kind capture-status ...
• search-intent-automation run --seed ... --goal ... --workdir ...
• search-intent-automation resume --resume-from-checkpoint ... --direction ...

Public package mode

Run the installed CLI:

search-intent-automation init --workdir /tmp/search-intent-run
search-intent-automation validate \
  --kind capture-status \
  /tmp/search-intent-run/capture-status.json
search-intent-automation run \
  --seed "local seo" \
  --goal "rank service pages" \
  --workdir /tmp/search-intent-run \
  --capture-status-json /tmp/search-intent-run/capture-status.json

Artifact paths inside capture-status.json resolve relative to the manifest file when they are not absolute paths.

Module invocation is also supported:

python -m search_intent_automation run --help

Skill mode

If you want to use this repo as a skill source, keep the public package docs as the source of truth and use SKILL.md plus Workflows/ as the adaptation layer for your local skill runtime.

Compatibility path

If you are running from a source checkout or installed skill bundle, existing automation can continue using:

python Tools/OpportunityPipeline.py run --help

That file is a compatibility shim and is not part of the PyPI wheel.

Blocked-state contract

When the pipeline is blocked, it stops and emits:

• taxonomy
• recommended option 1
• recommended option 2
• custom direction

Only recommended-2 or custom:... may continue as a partial run.

Repo structure

• src/search_intent_automation/: packaged CLI and pipeline logic
• Tools/OpportunityPipeline.py: compatibility shim for prior script-based callers
• Tools/CaptureStatusContract.md: Playwright-to-Python handoff contract
• Workflows/: skill-oriented workflow docs
• docs/: public package documentation
• examples/: runnable manifests and fixture artifacts

Documentation

• Installation
• Quickstart
• Development
• Release
• Architecture
• Contracts
• FAQ

Source trace

The reel-derived source evidence remains available in ReelEvidence.md. It is treated as provenance, not as the package usage guide.