Codex Loops

Kickoff preview

Take this branch to a green pull request. Implement the requested change, run local verification, open or update the PR, run `gh pr checks`, inspect failures, fix root causes, and repeat until every required check passes or you hit the iteration cap.
Goal: Open or update a pull request and stop only when all required PR checks are green.
Check command: gh pr checks
Exit condition: All required pull request checks are successful and the PR is ready for review or merge.
Max iterations: 10
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not disable required checks, edit loops to skip jobs, or remove tests to make CI green.
- Do not merge the PR unless the user explicitly asked for merge authority.

Kickoff preview

Act as an independent verifier. Restate the requirements, inspect the diff, run relevant checks, and return a pass/fail/blocker verdict with evidence.
Goal: Prove the implementation satisfies the request without relying on the implementer’s claim.
Check command: git diff --stat && git diff --check
Exit condition: The verifier can map each requirement to code and verification evidence.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not rubber-stamp. Find at least one plausible failure mode and check it.

Kickoff preview

Audit SEO metadata from server-rendered HTML for the target pages. Verify title, description, canonical, H1, Open Graph, and indexability, then fix and re-check.
Goal: Ensure SEO-critical pages have unique, server-rendered metadata and indexable content.
Check command: curl -sL $URL | head -80
Exit condition: Each target page has unique title, description, canonical, visible H1, and no accidental noindex.
Max iterations: 5
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not rely only on client-rendered metadata for SEO-critical pages. Verify server HTML.

Kickoff preview

Run a launch readiness checklist: build, deployed critical pages, SEO metadata, sitemap, robots, policy pages, analytics/ads, and final blockers.
Goal: Avoid launching with broken routes, missing policy pages, bad metadata, or unverifiable deployment.
Check command: pnpm build
Exit condition: Build, deployment, SEO basics, policy pages, and critical user paths pass review.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not mark launch-ready with missing policy pages or broken critical routes.

Kickoff preview

Audit a sample of generated SEO pages for uniqueness, helpfulness, metadata, internal links, and schema. Fix template/data issues before publishing at scale.
Goal: Ensure template-generated pages provide distinct value and are safe to index.
Check command: curl -sL $URL
Exit condition: Sampled generated pages have unique metadata, useful body content, and valid internal links.
Max iterations: 5
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not create large numbers of thin pages solely to manipulate search ranking.

Kickoff preview

Run the project tests, inspect failures, fix the smallest root cause, and repeat until the test command passes. Do not weaken the tests or change the check command.
Goal: Make the selected test command pass without weakening coverage.
Check command: pnpm test
Exit condition: The test command exits successfully with no failing tests.
Max iterations: 8
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not delete, skip, or mark tests as todo unless explicitly requested.

Kickoff preview

Verify the deployed URL, critical pages, sitemap, robots, and metadata. Fix or report exact failures before declaring the release successful.
Goal: Confirm the deployed site responds correctly and key pages are usable.
Check command: curl -I $DEPLOY_URL
Exit condition: Critical deployed pages return expected status and visible content/metadata.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not claim deployment success based only on build success. Verify the deployed URL.

Kickoff preview

Debug indexing for the target URL: status, robots, canonical, noindex, sitemap, internal links, and content usefulness. Return exact fixes and uncertainty.
Goal: Find technical or content reasons a page may not be indexed.
Check command: curl -I $URL
Exit condition: The page is technically indexable and remaining indexing uncertainty is clearly documented.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not promise indexing. Only verify technical readiness and recommend fixes.

Kickoff preview

Before committing, inspect the staged diff, scan for secrets/debug flags, run relevant validation, and only commit if the guard passes.
Goal: Block commits that contain secrets, debug switches, or unverified broken code.
Check command: git diff --cached --check
Exit condition: Staged diff is clean, no obvious secrets/debug flags are present, and relevant validation passes or is explained.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not commit secrets, local env files, debug flags, or generated private artifacts.

Kickoff preview

Scan changed and staged files for secrets, local env files, and debug leaks. Remove or redact unsafe values and repeat until clean.
Goal: Prevent secrets and local credentials from leaving the working tree.
Check command: git diff --cached | rg -n "(API_KEY|SECRET|TOKEN|PASSWORD|PRIVATE_KEY|BEGIN RSA|BEGIN OPENSSH)"
Exit condition: No unapproved secrets or local credentials are present in staged or changed files.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Never print raw secrets in the final answer. Redact values if they appear in output.

Kickoff preview

Audit the site for AdSense readiness: content depth, policy pages, navigation, mobile UX, and ad-safe layout. Return blockers and fixes.
Goal: Make the site credible, useful, navigable, and ad-safe before AdSense review.
Check command: curl -I $SITE_URL
Exit condition: Core content, policy pages, navigation, and ad placement are ready for review.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not place ads next to copy/download/source buttons where users may click accidentally.

Kickoff preview

Review database schema and migration changes for D1 compatibility, destructive operations, indexes, and rollback risk. Generate but do not apply production migrations without approval.
Goal: Ensure database changes are safe for development and production migration paths.
Check command: pnpm db:generate
Exit condition: Migration SQL is reviewed and no unexpected destructive operations remain.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not apply production migrations without human review. Do not run destructive SQL automatically.

Kickoff preview

Run the TypeScript check, group errors by root cause, fix them with strict types, and repeat until the command exits cleanly.
Goal: Make TypeScript validation pass without lowering type safety.
Check command: pnpm tsc --noEmit
Exit condition: TypeScript check exits with code 0.
Max iterations: 8
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not add `any`, `// @ts-ignore`, or disable strict compiler options unless explicitly approved.

Kickoff preview

Audit repository agent instructions against actual project files, then improve them with accurate commands, architecture rules, and verification expectations.
Goal: Make repository instructions accurate, actionable, and verification-oriented.
Check command: ls -la && rg -n "build|test|lint|deploy" README.md package.json AGENTS.md CLAUDE.md
Exit condition: Agent instructions state stack, commands, architecture rules, and verification expectations accurately.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not invent commands, tools, or architecture claims that are not present in the repository.

Kickoff preview

Run the production build, fix root causes while preserving project architecture, and repeat until the build passes.
Goal: Make the production build succeed for the target runtime.
Check command: pnpm build
Exit condition: The production build command exits successfully.
Max iterations: 6
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not hide build failures with dynamic imports or environment checks unless that is the correct runtime boundary.

Kickoff preview

Run the Cloudflare build, verify the deployed Worker URL, D1-dependent pages, sitemap, robots, and static assets. Report exact failures.
Goal: Prove the Cloudflare Worker deployment is serving critical routes with correct bindings.
Check command: pnpm cf:build
Exit condition: Cloudflare build and deployed smoke checks pass.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not expose Cloudflare tokens or account IDs in public output.

Kickoff preview

Audit all environment variable references, classify public vs secret scope, compare env templates and deployment config, and report missing or unsafe variables.
Goal: Ensure required env vars exist in the right place and secrets are not exposed client-side.
Check command: rg -n "process.env|import.meta.env|VITE_" src .env.example wrangler.example.jsonc
Exit condition: All referenced env vars are documented and correctly scoped.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Never move server-only secrets into public `VITE_` variables.

Kickoff preview

Find weak or orphan pages, choose relevant source pages, add natural internal links, and verify the rendered pages expose those links.
Goal: Improve crawlability and user navigation through relevant internal links.
Check command: curl -sL $SITEMAP_URL
Exit condition: Priority pages are linked from relevant hub/detail pages with natural anchors.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not add irrelevant keyword-stuffed links. User usefulness comes first.

Kickoff preview

Run audit, review safe remediation paths, update targeted dependencies, verify build/tests, and report remaining vulnerability risk.
Goal: Remediate actionable vulnerabilities without unsafe forced upgrades.
Check command: npm audit --audit-level=high
Exit condition: No high/critical audit findings remain, or remaining findings are documented with blockers.
Max iterations: 5
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not run force upgrades without explaining breaking-change risk and receiving approval.

Kickoff preview

After every code edit, list changed files, choose the closest meaningful validation, run it, and report evidence before claiming completion.
Goal: Run the closest meaningful verification after edits and report evidence.
Check command: git diff --name-only HEAD
Exit condition: Relevant validation has been run and either passes or failures are reported with evidence.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not say “not run” without explaining why no meaningful check exists.

Kickoff preview

Fetch sitemap.xml, compare it against expected public URLs, check exclusions, patch the generator, and re-fetch until coverage is correct.
Goal: Ensure sitemap.xml includes canonical public pages and excludes private/admin/API routes.
Check command: curl -sL $SITE_URL/sitemap.xml
Exit condition: Sitemap contains important public URLs and excludes private/API/admin pages.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not include private, admin, API, or duplicate query URLs in sitemap.

Kickoff preview

Upgrade dependencies in small safe batches, review install-time scripts, run build/tests after each batch, and document remaining breaking changes.
Goal: Upgrade dependencies without breaking the app or ignoring supply-chain risk.
Check command: pnpm build
Exit condition: Selected dependency batch is upgraded and validation passes.
Max iterations: 5
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not blindly install packages without reviewing install/postinstall/prepare scripts.

Kickoff preview

Verify visible FAQ content and JSON-LD structured data match exactly. Fix mismatches and avoid marking up hidden content.
Goal: Keep FAQ structured data accurate and visible.
Check command: curl -sL $URL | rg "application/ld\+json|FAQPage"
Exit condition: FAQ JSON-LD matches visible questions and answers on the page.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not mark up hidden, misleading, or unrelated FAQ content.

Kickoff preview

Review your own PR against the original task, changed files, tests, and risk categories. Fix must-fix issues and report evidence.
Goal: Identify problems in the agent’s own PR before human review.
Check command: git diff --stat main...HEAD && git diff --check main...HEAD
Exit condition: No must-fix review issues remain, or unresolved issues are clearly documented.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not hide unresolved issues; label them as risks or blockers.

Kickoff preview

Monitor the PR checks, inspect failing logs, fix the smallest root cause, push, and continue until CI passes or a real blocker is reported.
Goal: Turn failing CI logs into a verified fix or clear blocker report.
Check command: gh pr checks --watch
Exit condition: The failing CI check is fixed, or a blocker is documented with log evidence.
Max iterations: 6
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not paste secret-bearing logs into public output. Redact tokens and credentials.

Kickoff preview

Inspect the project context and write a strict, audit-friendly implementation objective with scope, constraints, done criteria, verification, and stop-if rules.
Goal: Create an audit-friendly agent objective before implementation.
Check command: find . -maxdepth 2 -type f | sort | head -100
Exit condition: The goal is concrete enough for an agent to execute and for a reviewer to audit.
Max iterations: 2
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not write a goal that allows vague completion or unverified claims.

Kickoff preview

Audit D1-backed public queries for indexes, pagination, N+1 patterns, and SSR safety. Propose or implement targeted fixes.
Goal: Keep public D1 queries indexed, bounded, and SSR-safe.
Check command: rg -n "select(|where(|limit(" src/modules src/routes
Exit condition: Hot list/detail queries have matching indexes and bounded result sizes.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not add broad unbounded queries to SEO pages. Keep public pages SSR-friendly.

Kickoff preview

Review code changes for documentation impact, update relevant docs/examples/instructions, and report evidence or why no docs update is needed.
Goal: Keep documentation aligned with code changes.
Check command: git diff --name-only HEAD
Exit condition: Docs are updated for relevant changes or the no-docs-needed decision is justified.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not update docs with behavior that the code does not actually implement.

Kickoff preview

Review the landing page for positioning, CTA focus, trust, mobile UX, and SEO alignment. Return prioritized fixes and avoid fake proof.
Goal: Improve landing page clarity and conversion without harming SEO.
Check command: curl -sL $URL | head -120
Exit condition: The page has clear positioning, primary CTA, trust signals, and SEO metadata.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not add fake testimonials, fake metrics, or misleading claims.

Kickoff preview

Map the changed files to affected call chains, list likely regressions, verify the top risks, and report remaining uncertainty.
Goal: Identify likely regressions and verify the highest-risk paths.
Check command: git diff --name-only main...HEAD
Exit condition: Top regression risks are either tested, ruled out, or documented as unresolved.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not overstate confidence when a risk was not actually verified.

Kickoff preview

Improve a thin page by adding specific examples, operational guidance, source context, FAQs, and related links. Avoid filler and duplicate boilerplate.
Goal: Turn a thin page into a useful page with distinct user value.
Check command: curl -sL $URL | wc -c
Exit condition: The page clearly answers user intent with distinct examples, guidance, and internal links.
Max iterations: 4
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not expand pages with filler text. Add specific, actionable value or remove/noindex the page.

Kickoff preview

Triage the flaky test: re-run narrowly, estimate reproduction, inspect nondeterminism sources, patch or document quarantine, and verify repeatedly.
Goal: Diagnose flaky behavior without hiding it.
Check command: pnpm test -- --runInBand
Exit condition: The flake has a likely cause, a verified fix, or a documented quarantine recommendation.
Max iterations: 6
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not delete or skip flaky tests just to make CI pass without documenting risk.

Kickoff preview

Audit release rollback readiness: risky files, migrations, previous deployment path, data safety, and feature flags. Do not execute destructive commands.
Goal: Know how to safely revert the release before shipping it.
Check command: git diff --name-only main...HEAD
Exit condition: Rollback path is documented and destructive/irreversible changes are explicitly acknowledged.
Max iterations: 3
Guardrails:
- Do not weaken, skip, delete, or rewrite the validation command to force success.
- Do not claim completion until the stated exit condition is actually satisfied.
- If blocked, report the blocker, evidence, and next safest action instead of gaming the metric.
- Do not run destructive migrations or rollback commands without explicit user confirmation.