v2: thin, docs-backed redesign - #20
Merged
Merged
Conversation
Replace the v1 baked-API-snapshot agents (stale at a 2-major-versions-old Android API surface, generating non-compiling code) with a design that stores no product facts at all: - Facts (versions, coordinates, APIs, adapter matrices) are fetched live from docs.cloudx.io (llms.txt index + raw-markdown pages) at run time. - The repo ships only workflow and field knowledge: a phased cloudx-integrate skill (Detect -> Plan -> Integrate -> Build-verify -> Audit -> Report), a cloudx-audit skill, and scenario playbooks (MAX/LevelPlay/Google coexistence, mediation migration, consent/CMP, per-platform build quirks) dispatched by project detection signals. - Agent-agnostic: AGENTS.md + .agents/skills/ canonical (Cursor/Codex), .claude/skills symlink and a Claude Code plugin + self-hosted marketplace (.claude-plugin/) exposing the same files. - CI (verify.sh, PR + weekly cron): docs-link liveness against llms.txt, a hardcoded-version lint that fails closed, playbook staleness warnings, and manifest/schema checks. Nothing version-shaped to sync. - v1 agents removed; curl install.sh replaced by a deprecation stub; scripts/uninstall-legacy.sh removes previously installed v1 files. v1 tree preserved at the v1-legacy tag. Verified: claude plugin validate passes; plugin loads with both skills via --plugin-dir; dry-run integration on a toy Android app fetched live docs and produced current-API code (context-parameter factory signatures, current sdk coordinate); version lint and link check fail closed on planted violations; uninstall and stub tested in a sandbox. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…c playbook The coexistence pattern (first-look vs parallel, init independence, load-failure-only fallback, duplicate partner-SDK resolution, consent to both stacks) is invariant across mediators; per-mediator files invited baking competitor SDK facts that rot with their releases — the same failure mode this redesign exists to prevent. Mediator identity stays a detection signal in playbook-index; the playbook instructs looking up the detected mediator's own current APIs live. Google's unique bit (first-look vs googlewaterfall-adapter choice) moves to a mediator note. Also correct the README claim that playbooks are seeded from real cases: current content is general guidance pending field verification. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The adapter set is defined by the networks enabled in the publisher's CloudX dashboard config (server-provisioned at runtime), so the skill now establishes it by asking or reading config/show — never guessing, never defaulting to all. Integrate and audit phases now require applying each adapter's docs page in full (extra Maven repositories, manifest/Info.plist entries, SDK-track choices, native asset requirements), and the audit flags adapter-set mismatches in both directions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Interstitial first-look end-to-end test caught the integration agent recreating the CloudX interstitial per show/hide cycle where the docs page reuses one instance and calls load() — leaking the prior instance. Make the Integrate phase match the page's object lifecycle exactly and the Audit phase flag per-cycle object creation the page doesn't show. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Observed during the iOS parallel-setup end-to-end test: AppLovin MAX's ad-view delegate and CloudX's banner delegate declare colliding Objective-C selectors, so one class conforming to both breaks — each SDK needs its own delegate object. First field-verified playbook entry. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Rebuilds the repository into a “thin, docs-backed” agent/skill package that avoids in-repo SDK facts by shifting product truth (versions/APIs/coordinates) to live docs, and adds CI checks + migration tooling for the legacy v1 curl-installed agents.
Changes:
- Introduces docs-driven skills (
cloudx-integrate,cloudx-audit) plus scenario/playbook content for real-world integration situations. - Adds repository verification automation (
scripts/verify.sh+ GitHub Action) to enforce link freshness, doc-map validity, and “no hardcoded versions”. - Deprecates the v1 installer and adds a legacy uninstaller; removes the legacy Android agent markdown files.
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/verify.sh |
Adds CI/local verification checks for docs liveness, doc-map stems, hardcoded-version lint, playbook staleness, and basic schema validation. |
scripts/uninstall-legacy.sh |
Removes previously installed v1 agent files from common Claude agent locations. |
scripts/install.sh |
Replaces v1 installer with a deprecation stub that prints new install guidance and exits non-zero. |
README.md |
Updates repo positioning, installation flow, and migration guidance for v2 skills/playbooks. |
playbooks/unity-export.md |
Adds Unity-specific (stub) playbook with signals/frontmatter. |
playbooks/react-native.md |
Adds React Native-specific (stub) playbook with signals/frontmatter. |
playbooks/flutter.md |
Adds Flutter-specific (stub) playbook with signals/frontmatter. |
playbooks/ios-dependency-managers.md |
Adds iOS dependency manager playbook (CocoaPods vs SPM, linkage pitfalls). |
playbooks/android-build-variants.md |
Adds Android build-variant playbook (Gradle dialects, catalogs, repos, R8). |
playbooks/consent-and-cmp.md |
Adds CMP/consent ordering and coexistence guidance playbook. |
playbooks/coexist-mediation.md |
Adds mediator-agnostic coexistence playbook (first-look/parallel, collision points). |
playbooks/migrate-from-mediation.md |
Adds migration-off-mediation playbook (staged approach, removal checklist, verification). |
AGENTS.md |
Adds repo entry point describing the “no product facts” rule and repository layout. |
CLAUDE.md |
Replaces prior long-form v1 guidance with a pointer to AGENTS.md. |
.github/workflows/verify.yml |
Adds PR/push/cron workflow to run scripts/verify.sh. |
.claude-plugin/plugin.json |
Defines Claude Code plugin metadata and skill entry points. |
.claude-plugin/marketplace.json |
Adds marketplace manifest pointing at the plugin. |
.agents/skills/cloudx-integrate/SKILL.md |
Adds the phased integration workflow skill (Detect→Plan→Integrate→Build-verify→Audit→Report). |
.agents/skills/cloudx-audit/SKILL.md |
Adds the audit workflow skill for existing integrations. |
.agents/skills/cloudx-integrate/references/doc-map.md |
Adds stable docs page stems mapping. |
.agents/skills/cloudx-integrate/references/playbook-index.md |
Adds signal-based playbook dispatch table. |
.claude/agents/android/cloudx-android-integrator.md |
Deletes legacy v1 Android integrator agent that embedded SDK facts. |
.claude/agents/android/cloudx-android-auditor.md |
Deletes legacy v1 Android auditor agent that embedded SDK facts. |
.claude/agents/android/cloudx-android-build-verifier.md |
Deletes legacy v1 Android build-verifier agent that embedded SDK facts. |
.claude/agents/android/cloudx-android-privacy-checker.md |
Deletes legacy v1 Android privacy-checker agent that embedded SDK facts. |
Suppressed comments (2)
scripts/verify.sh:59
- The hardcoded-version lint uses
grep --include, which is not supported by BSD grep (macOS). For a script meant to run locally, switching tofind ... | xargs grepavoids platform-specific failures.
HITS=$(grep -rInE "$pat" --include='*.md' --include='*.json' --include='*.sh' . \
| grep -v '^\./scripts/verify.sh:' || true)
scripts/verify.sh:24
- The per-link liveness checks should also use a retry policy to avoid failing PRs/cron runs due to transient network errors.
if ! curl -sf -o /dev/null --max-time 30 "$url"; then
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+67
to
+71
| note "== playbook staleness (last_verified > 180 days -> warning)" | ||
| NOW=$(date +%s) | ||
| for f in playbooks/*.md; do | ||
| LV=$(sed -n 's/^last_verified: *//p' "$f" | head -1) | ||
| if [ -z "$LV" ]; then |
Comment on lines
+21
to
+22
| URLS=$(grep -rhoE 'https://docs\.cloudx\.io[^) `"'"'"'<>]*' \ | ||
| --include='*.md' --include='*.json' . | sed 's/[.,;]$//' | sort -u) |
Comment on lines
+17
to
+18
| LLMS_TXT="$(curl -sf --max-time 30 https://docs.cloudx.io/llms.txt)" \ | ||
| || { fail "could not fetch https://docs.cloudx.io/llms.txt"; LLMS_TXT=""; } |
Review feedback: curl now retries twice on transient failures so the weekly cron and PR runs don't flake on DNS hiccups or brief 5xx, and the playbook staleness loop fails clearly when the glob matches no files instead of sed-ing a literal pattern. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
Author
|
Addressed the review:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rebuilds this repo from scratch on a design that cannot go stale the way v1 did.
v1 problem: the four Android subagents hand-baked the full SDK API reference into their prompts. That snapshot froze while the SDK moved two major versions; every factory signature is now wrong (generated code doesn't compile), the dependency list names a module that doesn't exist, and six manual sync PRs each missed spots. The validation CI was deleted in anticipation of a generator that was never built.
v2 design: the repo stores no product facts at all.
llms.txtpage index, every page raw markdown via.mdsuffix — which is already updated with every SDK release. Versions, coordinates, APIs, adapter matrices never appear in this repo (CI enforces it).cloudx-integrateskill (Detect → Plan → Integrate → Build-verify → Audit → Report), acloudx-auditskill for existing integrations, andplaybooks/holding field knowledge docs can't: mediator coexistence, mediation migration, consent/CMP handling, per-platform build quirks. Playbooks are selected by detection signals (references/playbook-index.md) and are version-free by rule.coexist-mediation.mdcovers the invariant pattern (first-look vs parallel, init independence, load-failure-only fallback, duplicate partner-SDK resolution, consent to both stacks); mediator identity is a detection signal, and the playbook instructs looking up the detected mediator's own current APIs live — baking competitor SDK facts would rot exactly like baked CloudX facts.AGENTS.md+.agents/skills/canonical (Cursor/Codex);.claude/skillssymlink plus a Claude Code plugin with self-hosted marketplace (.claude-plugin/) expose the same files. Install:/plugin marketplace add cloudx-io/cloudx-sdk-agents→/plugin install cloudx@cloudx.verify.sh, PR + weekly cron): docs-link liveness + doc-map stems checked against livellms.txt, hardcoded-version lint fails closed, playbooklast_verifiedstaleness warnings, manifest/schema checks. SDK releases require zero work here.v1-legacytag; curlinstall.shis now a deprecation stub (exits 1);scripts/uninstall-legacy.shremoves previously installed v1 agent files.Playbook content status: seeded playbooks contain general mobile-ads engineering guidance plus the version-agnostic salvage from v1 — not yet field-verified CloudX support cases. They harden as real cases surface; wrapper-platform playbooks (Unity, RN, Flutter) start as stubs.
Verification
claude plugin validatepasses; plugin loads via--plugin-dirand exposescloudx:cloudx-integrate+cloudx:cloudx-audit.en/android/integration.md+ the banner docs page live, added the current sdk coordinate, and wrote current-API code including the context-parameter factory signature v1 got wrong.verify.shgreen on the repo; fails closed on a planted hardcoded version and on a planted dead docs link.uninstall-legacy.shremoves v1 files in a sandbox$HOME; deprecation stub prints new instructions and exits non-zero.Closes #16 (superseded: adapter docs now fetched live, never listed in-repo).
Design doc: see the "CloudX SDK Agents v2 — Thin, Docs-Backed Redesign" proposal in Notion (Product Docs).
🤖 Generated with Claude Code