albertshiney/websitegenerator/local-business-revamp-parallel

Parallel business website batches

Use one main agent for dispatch, progress and routine authorization; one active scout researches cities; fresh builder/sender agents generate, deploy, verify and contact each qualified business. This is the default batch workflow for Albert's WebsiteGenerator application. Creating or editing this skill does not launch a batch.

Shared application and setup

Resolve this file's real path (including installation symlinks); the application root is two directories above this skill folder. Work from that root. Read Firecrawl scouting for the default candidate-screening path. Read settings.json and ledger commands, production, and fixed outreach. Reuse tools/control.py, tools/quick_site.py, data/revamp.sqlite3, runs/ and the existing prepared templates. Do not create a second application or temporary production ledger.

This skill's role split and fresh-agent lifecycle take precedence over the shared reference's reusable-worker assignment text. Shared command syntax, stage transitions, deduplication, recovery and completion rules still apply. The coordinator registers and claims jobs on behalf of the assigned builder; that builder owns subsequent updates and contact commands.

Get industry, location (state or city) and completed-outreach count from the request or explicitly selected dashboard batch; default count is five. A state is sufficient: the main agent finds its cities without asking Albert to supply them. Use the selected batch’s industry when a follow-up supplies only a state. Clarify the country only when the state name is ambiguous in context. Resume selected unfinished work before creating duplicates. Start the dashboard on port 4310 if this application's /api/state is not already responding. Inspect python3 tools/control.py state. Preflight the selected prepared template and configured Vercel account/scope once per run; do not repeat for every candidate. Ask only for missing run inputs or a concrete dependency that prevents progress.

State and city queue

For a state request, create one batch with one completed-outreach target across the entire state, not a full target per city. The existing CLI/API location field is named city; store the supplied state label there (for example --city 'Delaware, USA'). This is a compatibility field name, not a requirement to choose a single city. Save explicit scope in runs/scouting/BATCH_ID/scope.json: scope type, state, country, requested target, city-list source URLs, and a city queue with stable city IDs, names, status, assigned scout ID and coverage paths. Only the main agent writes this file.

Find and verify the state's city/municipality list using an authoritative public source during the run. Start with larger cities, then work through smaller municipalities if needed; record any population/order source rather than inventing rankings. Keep the remaining cities queued. Do not declare the state exhausted merely because its largest cities or one query produced no candidates. For a city-only request, create a single city queue entry and preserve that geographic scope.

Run only one active scout at a time, assigned one exclusive city for its entire initial assignment. Mark it assigned in the scope file before dispatch. Give it the city, state, industry, search instructions, unique evidence directory and known identities. Never split the same city between simultaneous scouts or send every scout to the same state-wide query. Scouts may use query variants within their assigned city, but must not independently expand into neighboring cities. The main agent reassigns a city only after confirming the previous scout has stopped working it.

When a scout finishes a city's searches, it sends CITY_DONE with coverage and candidate paths; the main agent spawns a fresh scout for the next queued city while builders continue; do not resume the finished scout for browser work. Record exhausted, paused and browser-unavailable cities distinctly. Lost browser access does not exhaust a city. Preserve the cursor and evidence for recovery or coordinator takeover. Pause dispatch when completed plus in-progress jobs cover the statewide target; resume pending cities when unsuccessful outcomes free slots. A city-only run has one scout; use spare child slots for build work rather than duplicating its city.

City boundaries do not guarantee unique businesses: contractors often advertise in multiple cities. Keep one cross-city/cross-batch identity check before every build. Verify the prospect serves the assigned city; deduplicate canonical and alternate domains, phones, emails, name and address. Register/build/contact a multi-city company once, retaining verified service-area evidence. Never remove an identity to fill a city's queue.

For qualified businesses whose automatic outreach is unavailable, follow Manual outreach: build and verify first, then provide the prepared message and verified contact details to Albert. This takes precedence over form-only rejection. Opt-outs, duplicates and failed business qualification remain skipped.

Roles and capacity

Use collaboration subagents, never user-facing tasks. Only the main agent spawns agents. Read worker_model and worker_reasoning_effort from settings; pass those exact values with fork_turns: "none". Include the absolute skill path and resolved application root, role, batch, assignment, evidence directory and the standing outreach authorization below. Do not silently substitute an unavailable configured model.

Default active layout: main agent + one scout + one builder/sender. Keep the fourth slot available for a replacement or another ready build when useful. Never run more than one scout concurrently. With only one child slot, alternate fresh scout and fresh builder assignments; save candidate packets before ending the scout. Respect actual available slots and report limitations instead of claiming nonexistent parallel work.

Browser access failed in both reused-agent tests, even after markHandoff and a REPL reset. Create a fresh scout per city and a fresh builder/sender per business. Each performs all browser work in its initial assignment. While waiting for packets or routine coordinator authorization, remain in the same turn using collaboration messages and bounded waits of at most 60 seconds; do not send a final answer and rely on a follow-up to restore browser access. Finalize only after the assigned city/job ends or a concrete access failure is reported. Tab retention is not a browser-lifetime guarantee.

Before any browser-dependent job starts, verify the fresh agent's private iab surface. If unavailable, report the exact inventory/error. The coordinator may try one fresh replacement when capacity allows, after confirming the old agent stopped. If replacement also lacks access, record the unresolved dependency and continue independent authorized work; do not repeatedly create agents or silently change the main agent into the normal scout/sender. Recovery of claimed jobs follows the shared ownership and submission rules. Never transfer an uncertain contact attempt to a replacement for retry.

Keep at most two ready candidate packets beyond active builds. Completed plus in-progress jobs reserve the target slots; only complete/sent count toward success. Replace skipped, blocked and uncertain prospects with fresh identities. At the target stop new dispatch and finish reconciliation; if search coverage is exhausted below target, report exhausted and the shortfall.

Scouts

• Verify a private iab browser surface before browser work. Use Google web search starting at page 10 (start=90), never Maps or pages 1–9 unless requested. Search the assigned city and state only, starting each query at page 10. Partition by city, not by deep-page ranges of the same query. After a confirmed empty result page, do not mechanically request ten later offsets; try a relevant trade-query variant for that city, then report its coverage and move to the next assigned city. Distinguish empty results from CAPTCHA/loading failures. Preserve the page-10 rule; do not silently switch to pages 1–9. A finished query is not statewide exhaustion.
• Screen the original homepage/contact page with cached Firecrawl HTML and saved screenshots using Firecrawl scouting. Inspect the screenshot with the image-view tool and qualify by observed visual weakness, never actual age, dates or copyright years. Collect two concrete findings and screenshots/source URLs. Desktop observations suffice if mobile inspection is unavailable; do not claim mobile defects without checking. Skip visually strong sites, directories, dead sites, certificate/browser verification barriers, and known duplicates.
• Before passing a build candidate, verify from scraped evidence an original contact form with a message field and submit control, suitable for a website proposal. Apply the shared outreach rules for CAPTCHA, opt-outs and required commitments. Email-only contact, newsletter/review-only forms, and visible CAPTCHA select manual outreach; they do not fail business qualification. Use browser inspection only for ambiguous or incomplete form evidence; missing HTML alone is not proof of no form. Skip confirmed unsuitable prospects promptly and continue.
• Collect business name, public contact details, public address if available, aliases, template and brand color (industry fallback if unclear), recording sources. Reuse the same cached Firecrawl evidence for visual qualification, contact facts and form discovery. Do not reopen each business in the browser or scrape again when evidence is sufficient. CAPTCHA integration hints alone never disqualify a form; final live challenge state remains unknown until the builder checks.
• Write each result to a unique file under runs/scouting/BATCH_ID/CITY_ID/SCOUT_ID/. Send CANDIDATE_READY immediately to the main agent for deduplication and job allocation. Once the main agent returns the assigned builder ID and job ID, send the evidence packet directly to that builder with collaboration.send_message, copying the main agent on the handoff. If the scout has already finished, the main agent forwards its saved packet without restarting it. Do not wait to finish the city before dispatching qualified candidates. Include assigned city/state, identity, URL, findings, screenshots, form fields, contact URL, facts and sources. Return skips and search coverage too. Scouts never write the ledger, deploy, contact, or reserve attempts.

Use only the private browser surface provided to that agent. Request visible tabs when supported; if the private surface explicitly rejects visible tabs, use its supported hidden tabs and report this visibility limitation. Do not switch to a shared native browser. Follow returned browser API documentation. Serialize shared viewport changes, and never treat separate tabs as isolated cookie profiles.

Main agent: register and dispatch

Check each candidate against the durable identities and current in-flight candidates using canonical/alternate domains, phone/email and name/address. Register qualified prospects and verified aliases once. Save evidence under runs/JOB_ID/. Retain skipped/opt-out identities through the existing ledger workflow so they are not rediscovered.