diff --git a/.sync-state.json b/.sync-state.json new file mode 100644 index 0000000..6efe579 --- /dev/null +++ b/.sync-state.json @@ -0,0 +1,69 @@ +{ + "last_sync": "2026-05-11", + "sources_checked": 6, + "changes_applied": [ + { + "source": "garrytan/gstack", + "commit": "7b4738bca0d157c761894e548349cb85e61104ba", + "version": "v1.27.1.0", + "description": "Anti-shortcut clause for plan-* review skills", + "target": "eng-review/SKILL.md", + "why": "Prevents the May-2026 transcript bug: model dumps all findings into prose without calling AskUserQuestion. Core safety language, adapted to drop ExitPlanMode references." + }, + { + "source": "garrytan/gstack", + "commit": "7b4738bca0d157c761894e548349cb85e61104ba", + "version": "v1.27.1.0", + "description": "Anti-shortcut clause for plan-* review skills", + "target": "prod-review/SKILL.md", + "why": "Same as eng-review — prevents silent finding-batching failure mode." + }, + { + "source": "garrytan/gstack", + "commit": "443bde054c6d8a0e608ec099b841d508c2fa4be5", + "version": "v1.28.0.0", + "description": "Browse: headed mode, SOCKS5 proxy, --navigate download flag documentation", + "target": "browse/SKILL.md", + "why": "Documents new --headed and --proxy flags for anti-bot site access. The --navigate flag from this same commit was already present in claudebert's browse SKILL.md, confirming binary parity." + } + ], + "changes_deferred": [ + { + "source": "garrytan/gstack", + "commit": "19e699ab9b69de9e1bf10d4b7c2682703b56f984", + "version": "v1.26.4.0", + "description": "GSTACK REVIEW REPORT delete-then-append flow fix", + "why_deferred": "claudebert has no GSTACK REVIEW REPORT section in eng-review or prod-review — not applicable" + }, + { + "source": "garrytan/gstack", + "commit": "5d4fe7df070fefb45f300144e1181cf43836bdd1", + "version": "v1.31.0.0", + "description": "Delete AskUserQuestion 'Decisions to confirm' fallback from plan-* skills", + "why_deferred": "claudebert's eng-review and prod-review do not have the fallback language that was deleted — not applicable" + }, + { + "source": "addyosmani/agent-skills", + "commit": "0af1a5ef15c7c6e13330d881d1560c460cb12aaa", + "description": "New skill: doubt-driven-development (5-step adversarial in-flight review cycle)", + "why_deferred": "Interesting new skill concept but not in claudebert's pipeline gap categories (review, qa, design-review, browse, etc.). Would require creating a new skill directory rather than cherry-picking into an existing one." + }, + { + "source": "anthropics/skills", + "commit": "d211d437443a7b2496a3dad9575e7dddd724c585", + "description": "Claude API skill: Managed Agents outcomes, multiagent patterns, webhooks", + "why_deferred": "API feature documentation for claude-api skill, not relevant to claudebert's review pipeline" + }, + { + "source": "VoltAgent/awesome-agent-skills", + "description": "New skills added (xquik, honeydew-ai) — company-specific tool integrations", + "why_deferred": "Not filling claudebert pipeline gaps; appear to be specialized commercial tool integrations, not general review/qa/browse pipeline improvements" + }, + { + "source": "Owl-Listener/designpowers", + "commit": "e9448b316ab28c20f84f8c9589426f0164317035", + "description": "terminal-starter-guide-for-designers.md", + "why_deferred": "Designer onboarding guide, not a cognitive/a11y/motion/tokens/voice/responsive pattern applicable to design-review skill" + } + ] +} diff --git a/browse/SKILL.md b/browse/SKILL.md index 2322f8e..b02b705 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -184,6 +184,42 @@ $B snapshot -D # verify deletion happened $B diff https://staging.app.com https://prod.app.com ``` +## Headed Mode + Proxy + Anti-Bot Sites + +For sites that block headless browsers, fingerprint Playwright defaults, or require routing through an authenticated SOCKS5 proxy (residential VPN, etc.), browse exposes three coordinated flags: + +```bash +# Headed mode — visible Chromium window. Auto-spawns Xvfb on Linux +# containers without DISPLAY (no extra setup needed on Debian/Ubuntu). +browse --headed goto https://example.com + +# SOCKS5 with auth (Chromium can't prompt for SOCKS5 creds itself — +# browse runs a local 127.0.0.1 bridge that handles the auth handshake). +browse --proxy socks5://user:pass@residential.proxy.host:1080 goto https://example.com + +# HTTP/HTTPS proxy (passes through to Chromium directly): +browse --proxy http://corp-proxy:3128 goto https://example.com + +# Browser-triggered file download (Content-Disposition, redirect chain, +# anti-bot CDN — falls back from page.request.fetch() to browser native +# download handler): +browse download "https://protected.example.com/file" /tmp/file.bin --navigate + +# Combined: headed + proxy + navigate-download +browse --headed --proxy socks5://user:pass@host:1080 \ + download "https://protected.example.com/file" /tmp/file.bin --navigate +``` + +**Credential policy.** Pass creds via either the URL (`socks5://user:pass@host`) OR the env vars `BROWSE_PROXY_USER` and `BROWSE_PROXY_PASS` — never both. Browse refuses with a clear hint when both are set, because silent override creates "works on my machine" debugging traps. + +**Daemon discipline.** Browse runs as a long-lived daemon. `--proxy` and `--headed` change daemon-startup config, so they only apply on a fresh daemon. If a daemon is already running with different config, browse refuses and tells you to `browse disconnect` first. No silent restart that would drop tab state, cookies, or logged-in sessions. + +**Stealth.** When `--headed` or `--proxy` are set, browse masks `navigator.webdriver` (the obvious automation tell) via Chromium's `--disable-blink-features=AutomationControlled` plus a small init script. We do NOT fake `navigator.plugins`, `navigator.languages`, or `window.chrome` — modern fingerprinters check those for consistency, and synthesizing fixed values can flag MORE bot-like, not less. + +**Container support.** `--headed` on Linux without `DISPLAY` automatically picks a free X display (`:99`, `:100`, ...) and spawns Xvfb. Cleanup on `browse disconnect` validates the recorded PID's `/proc//cmdline` matches `Xvfb` AND start-time matches before sending any signal — no PID-reuse footguns. Standard Debian/Ubuntu containers work out of the box; minimal images (alpine, distroless) may also need fonts/dbus/gtk libs for headed Chromium to render. + +**Failure modes.** SOCKS5 upstream rejected or unreachable → fail-fast at startup with a redacted error after 3 retries (5s budget). Mid-stream upstream drop → browse kills the affected client connection only; no transport retries (which could corrupt browser traffic). Mismatched daemon config → exit 1 with a `browse disconnect` hint. + ## Snapshot Flags The snapshot is your primary tool for understanding and interacting with pages. diff --git a/eng-review/SKILL.md b/eng-review/SKILL.md index a2900cc..d0f04ef 100644 --- a/eng-review/SKILL.md +++ b/eng-review/SKILL.md @@ -177,6 +177,8 @@ Evaluate: **STOP.** For each issue found in this section, call AskUserQuestion individually. One issue per call. Present options, state your recommendation, explain WHY. Do NOT batch multiple issues into one AskUserQuestion. Only proceed to the next section after ALL issues in this section are resolved. +**Anti-shortcut clause:** Writing every finding into a single prose dump without calling AskUserQuestion is the precise failure mode this skill is designed to prevent — the model explored, found issues, and delivered a report rather than walking the user through them interactively. If you have ANY non-trivial finding in any review section, the path from finding to completion goes THROUGH AskUserQuestion. Zero findings in every section is the only path that bypasses AskUserQuestion. If you find yourself wanting to summarize all findings at once before asking, stop and call AskUserQuestion now — that's the bug, recognize it. + ## CRITICAL RULE — How to ask questions Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews: * **One issue = one AskUserQuestion call.** Never combine multiple issues into one question. diff --git a/prod-review/SKILL.md b/prod-review/SKILL.md index 2101cd3..2a4faf2 100644 --- a/prod-review/SKILL.md +++ b/prod-review/SKILL.md @@ -510,6 +510,8 @@ Evaluate: For deep design work, recommend `/design-review` after implementation. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Anti-shortcut clause:** Writing every finding into a single prose dump without calling AskUserQuestion is the precise failure mode this skill is designed to prevent — the model explored, found issues, and delivered a report rather than walking the user through them interactively. If you have ANY non-trivial finding in any review section, the path from finding to completion goes THROUGH AskUserQuestion. Zero findings in every section is the only path that bypasses AskUserQuestion. If you find yourself wanting to summarize all findings at once before asking, stop and call AskUserQuestion now — that's the bug, recognize it. + ## CRITICAL RULE — How to ask questions Follow the AskUserQuestion format from the Preamble above. Additional rules for plan reviews: * **One issue = one AskUserQuestion call.** Never combine multiple issues into one question.