![\"npm](\"https://img.shields.io/npm/v/@amityco/social-plus-vise.svg\")
\n ![\"Preview](\"https://img.shields.io/badge/Status-Preview-orange.svg\"){kind=icon}
\n ![\"License\"](\"https://img.shields.io/badge/License-Proprietary-blue.svg\"){kind=icon}
\n ![\"Docs\"](\"https://img.shields.io/badge/Docs-learn.social.plus-informational\"){kind=icon}
\n\n The standards harness that keeps AI coding agents on the rails when integrating social.plus SDKs.\n
\n\n\n \n \n \n
\n npm install -g @amityco/social-plus-vise\n
\n What is Vise? ·\n Quick start ·\n How it works ·\n Evidence ·\n Platforms ·\n CLI reference ·\n MCP ·\n CI ·\n Contract ·\n Support\n
\n\n---\n\n## What is Vise?\n\n> **Preview release.** Vise is usable for guided social.plus SDK integrations, but the CLI surface, evidence format, benchmark methodology, and advisory intelligence may still change as the product hardens through more real projects. Treat it as governed AI assistance with strong validation gates, not a substitute for code review, product QA, or runtime verification.\n\n**Vise wraps your AI coding agent in compliance guardrails while it integrates social.plus SDKs.** The agent still writes the code — Vise grounds that work in real SDK APIs, checks correctness and completeness, helps align generated UI with your design system, and asks you the calls only a human should make. It does not make AI agents perfect; it gives them a governed loop, explicit gates, and evidence when something is green, intentionally scoped out, or still unverified.\n\nWhile the agent works, Vise:\n\n- 🧠 **Grounds it in the real SDK** — extracted, source-anchored facts (real types and field names), so it won't invent a symbol or field the SDK doesn't expose, and pins the version published on npm.\n- 🛡️ **Enforces 400+ platform-specific checks** — the mistakes that pass a demo and break in production.\n- ✅ **Gates feature completeness** — the whole outcome (pagination, empty/error states, the capabilities you asked for), not just the happy path.\n- 🎨 **Reviews generated UI against your design system** — advisory, because brand fit still needs human judgment.\n- 🔧 **Runs your project's own build / lint / typecheck sensors.**\n\nIt turns the request into a grounded plan, records a local contract under `sp-vise/`, and keeps checking until the integration is **green, attested, intentionally scoped, or explicitly blocked on your input** — so the handoff distinguishes finished work from unverified work instead of treating *\"the agent stopped\"* as *\"done\"*.\n\n> 🔒 **Vise itself does not upload your source code.** Your AI coding host follows its own data policy; Vise fetches only the public social.plus docs and the SDK's published version on npm — never your code, file contents, or search queries. `VISE_DOCS_OFFLINE=1` runs fully offline.\n\nVise can also run **ahead** of that loop: an advisory [Engagement Intelligence](#engagement-intelligence) layer turns a product goal into multiple candidate engagement strategies — *what you might build*, not only *whether you built it right*.\n\n> **Why \"Vise\"?** A bench vise holds the workpiece steady so the craftsman's hands are free to shape it. Vise clamps the integration to the real docs, the real project structure, and the real compliance rules so the agent can focus on building instead of guessing.\n\nIt ships as three layers:\n\n| Layer | Purpose |\n|---|---|\n| **Skill** (`SKILL.md`) | Teaches your AI agent when to inspect, plan, fetch docs, edit, validate, and attest |\n| **CLI** (`vise`) | Deterministic engine: inspects repos, searches docs, validates setup, runs sensors, manages attestations |\n| **MCP adapter** | Optional stdio server for MCP-capable hosts (Claude Code, Cursor, Codex, VS Code, Copilot) |\n\n## Quick Start\n\n> **New to social.plus?** Vise integrates the social.plus SDK. To adopt social.plus, [talk to our team](https://www.social.plus/contact/contact-sales?utm_source=vise&utm_medium=npm-readme&utm_campaign=ga). Existing customers get their **API key + region** from the [social.plus Console](https://console.socialplus.com) and can follow the [SDK getting-started guide](https://learn.social.plus/social-plus-sdk/getting-started/overview). You can install Vise and explore `vise inspect`/`vise plan` before you have credentials.\n\n> **Runtime requirement:** Vise requires Node.js 20 or newer. Run `node --version` before installing if you are unsure which runtime your terminal or CI environment uses.\n\n```sh\n# 1. Install the CLI\nnpm install -g @amityco/social-plus-vise\nvise doctor # verify install\n\n# 2. Install the AI skill into your coding tool\nvise install-skill --target claude # Claude Code (personal)\nvise install-skill --target cursor . # Cursor (project-local)\nvise install-skill --target copilot . # GitHub Copilot / VS Code\n\n# 3. Open your AI coding tool in your project and ask:\n# \"Add a social feed to this app using the social.plus SDK.\"\n```\n\nThe skill drives the loop automatically — `vise inspect` → `vise plan` → `vise init` → edit code → `vise check` → `vise run-sensors`. You drive intent, answer scope questions, and **sign off the blueprint** (what gets built) before the agent writes a line; Vise keeps the agent honest. For high-confidence handoff, also launch the app in its real browser, simulator, emulator, or device target and verify the selected social surface with real data. See [How it works](#how-it-works).\n\nAll skill targets:\n\n| Host | Install command |\n|---|---|\n| Claude Code (personal scope) | `vise install-skill --target claude` |\n| Claude Code (project scope) | `vise install-skill --target claude-project .` |\n| OpenAI Codex | `vise install-skill --target codex` |\n| Cursor (native skills) | `vise install-skill --target cursor .` |\n| Cursor (legacy rules) | `vise install-skill --target cursor-rules .` |\n| GitHub Copilot / VS Code | `vise install-skill --target vscode .` |\n| Copilot CLI / project | `vise install-skill --target copilot .` |\n| Generic agent project | `vise install-skill --target agents .` |\n| Other coding agents | `vise print-skill` (paste into the host's project instructions) |\n\nPrefer a per-project install? `npm install -D @amityco/social-plus-vise`, then call `npx vise`. The skill is plain Markdown — read it any time with `vise print-skill`.\n\n**Updating:** the installed skill is a copy — updating the npm package does not update it. After `npm update`, re-run the same `vise install-skill` command: each install records a provenance manifest (package version + file hashes), so an outdated-but-unmodified copy updates in place, while a locally edited copy is never overwritten without `--force`. `vise doctor` lists every discovered skill copy with its freshness (`skillInstalls`) and the exact repair command, and `vise status` carries the same signal as a `skillFreshness` advisory whenever a copy needs attention — so a stale copy can't hide even from an agent that never runs doctor.\n\n## How it works\n\n1. **Inspect** — `vise inspect` detects the platform, app surfaces, available sensors, and design signals from the local repo.\n2. **Plan** — `vise plan --request \"...\"` classifies the outcome, cites docs, and raises blocking intake and design-preview questions. If the request is too vague to classify, it returns a structured **clarify** block. If it explicitly names a capability unavailable on the detected platform, it returns `supportLevel: \"unsupported\"`, a grounded `platformAvailability` explanation, and stop/alternative steps instead of implementation guidance. For a broad goal it expands the outcome into a **blueprint** — the surfaces and experience it proposes to build. Use `--summary` when you only need the route/intake readout before implementation. The agent surfaces questions; you answer.\n3. **Initialize** — `vise init` writes the `sp-vise/` compliance contract. It accepts a reviewed organization Policy Pack directly (`--policy-pack`, plus `--trust-policy` for a signed envelope) or a human-reviewed pre-registered Outcome Measurement Plan (`--measurement-plan`); an initialized repository may later adopt controlled Policy Operations with `vise policy accept`. For a **multi-surface build** (a journey spanning more than one surface), `init` first makes you **sign off the blueprint**: the *what* — the solution path (`sdk` / `uikit` / `hybrid` / `managed-placement`), the experience/surfaces to build, and their cross-surface placement/read/write relationships. A community + feed blueprint, for example, binds the feed and composer to the selected community-detail route instead of accepting two disconnected tabs. This is the **alignment gate** — *\"are we building the right thing?\"* — the human-judgment counterpart to the deterministic compliance gate (*\"did we build it the right way?\"*) in step 5. `init` refuses and exits 7 until the request is resolved: `status: \"needs-clarification\"` when intake is unanswered or the request can't be classified, and `status: \"needs-blueprint-confirmation\"` until the blueprint is signed (`--answer blueprint_confirmation=