Make install a two-line cheat: Claude Code plugin marketplace + installer v2

[cgallic]

Install UX overhaul

Research-driven rebuild of the install experience. A 5-agent research pass (current-install audit, ICP profile, best-in-class installer research, technical-constraints audit, adversarial gap critic) is summarized in docs/install-ux-research.md; this PR ships the design it converged on.

The cheat code

The repo is now a Claude Code plugin marketplace. Install is two lines typed inside Claude Code — no terminal, no clone, no config, auto-updating on every push:

/plugin marketplace add cgallic/kai-cmo-harness
/plugin install kai@kai-marketing-os

plugins/kai-marketing-os/ is a curated directory of symlinks (skills, knowledge/, harness/references, harness/skill-contracts, scripts/quality_gates). Claude Code dereferences symlinks when copying a plugin into its cache, so users get the ~7 MB payload the skills actually need — and none of the repo's other ~106 MB (workspace/, .git, site/, mp3s). Empirically verified with claude CLI v2.1.201: local marketplace add + install → 0 symlinks in cache, full payload materialized, no junk leaked, all 49 skills registered, ~7.7k always-on tokens.

What was broken

1. Hollow installs — install.sh v1 copied only harness/skills/ (848K). 34 of 49 skills reference knowledge//harness/ files and 14 invoke scripts/ Python that were never installed; the installer verified green anyway.
2. Dead-end first command — /kai-start and the installer both recommended /kai-audit, which hard-requires python -m scripts.audit.collect → guaranteed ModuleNotFoundError outside the repo.
3. Hard-fail on optional assets — the installer aborted if kaicalls-design files were missing.
4. No executable bits — every installer script was mode 644, so the documented ./install.sh failed on every fresh clone.
5. Broken frontmatter — kai-growth-hacker/SKILL.md had an unquoted : in its description; YAML parse failure silently dropped all its metadata at runtime (caught by claude plugin validate).

Changes

• .claude-plugin/marketplace.json + plugins/kai-marketing-os/ — plugin packaging as above. version intentionally omitted from plugin.json → SHA-based auto-updates (docs-recommended for actively developed plugins).
• install.sh v2 — installs the knowledge base to ~/.claude/kai/ alongside the skills, uses a local checkout when run from one, verifies knowledge + gates + skills, kaicalls-design is warn-not-fail, exit message lands on /kai-start with time promises. Tested end-to-end.
• "Kai root note" in 34 skills — resolves knowledge//harness//scripts/ paths against the Kai install root in all three modes (repo checkout, plugin cache, ~/.claude/kai); missing scripts/ commands are skipped-and-declared, never fabricated.
• /kai-start — goal-loop step auto-skips when scripts/harness_cli.py is absent (goal goes into MARKETING.md); first recommendation is /kai-growth-plan (works anywhere), /kai-audit only when collectors exist.
• /kai-audit — explicit qualitative mode without collectors: cite-what-you-browse, unmeasured numbers go to _data-gaps.md.
• Executable bits on install.sh, setup.sh, deploy.sh, setup, bin/*.
• README + docs/QUICK_START.md — lead with the plugin path; manual install now includes the knowledge payload; stale skill count and broken seo_lint example fixed.
• docs/install-ux-research.md — full research findings, rejected alternatives, and open items (Windows symlink caveat, Four U's Gemini dependency, claude-plugins-community submission, npx skills add path, legacy-path retirement).

Verification

• python scripts/doctor.py --ci — clean (45/45 files, instruction chain intact, golden corpus 4/4)
• python scripts/quality_gates/golden_check.py — 4/4
• claude plugin validate ./plugins/kai-marketing-os — passes (only the intentional missing-version warning)
• bash install.sh — end-to-end green from a local checkout; installed skills registered in a live Claude Code session
• Local /plugin install → cache inspected: dereferenced payload, no junk, 49 skills

🤖 Generated with Claude Code

https://claude.ai/code/session_01XyDQLHJEfMzefM85qfaCEg

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app-meetkai	Ready	Preview, Comment	Jul 5, 2026 4:45am