Quick Start

# 1. Install
npm install -g @amityco/social-plus-vise

# 2. Install the AI skill into your coding tool (pick your host)
vise install-skill --target claude        # Claude Code (personal)
vise install-skill --target cursor .      # Cursor (project-local)
vise install-skill --target copilot .     # GitHub Copilot / VS Code

# 3. Inside your project, let your AI agent run the Vise loop
cd your-app
vise inspect                              # detect platform, surface, design signals
vise plan --request "Add a social feed"   # produce a grounded implementation plan
vise init --request "Add a social feed"   # write the sp-vise/ compliance contract

# 4. After the agent makes edits
vise check                                # verify the integration against the contract
vise run-sensors                          # run your project's own build/typecheck/lint

That's it. The skill at skills/social-plus-vise/SKILL.md (installed in step 2) teaches your AI agent when to run each command. Skip to Usage Flow for the full picture.

What Vise Does

Vise is a local CLI + AI skill that wraps coding agents in deterministic compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 250+ platform-specific compliance rules, and runs your project's own build/lint/typecheck sensors — all locally. Your source code never leaves your machine.

| Layer | Purpose | |---|---| | Skill (SKILL.md) | Tells your AI agent when to inspect, plan, fetch docs, edit, validate, and attest | | CLI (vise) | Deterministic engine: inspects repos, searches docs, validates setup, runs sensors, manages attestations | | MCP adapter | Optional stdio server for MCP-capable tools (Claude Code, Cursor, Codex, VS Code, Copilot) |

Why "Vise"

A bench vise holds the workpiece steady so the craftsman's hands are free to shape it. Without one, the workpiece drifts and cuts wander. Vise does the same for AI agents integrating SDKs: it clamps the integration to a known-good position (the real docs, the real project structure, the real compliance rules) so the agent can focus on creative work instead of guessing.

Supported Platforms

| Platform | Coverage | Sensors | |---|---|---| | TypeScript / Next.js / React | ✅ Full | tsc, npm build, npm lint, SDK import smoke | | React Native | ✅ Full | tsc, npm lint, SDK import smoke | | Flutter / Dart | ✅ Full | flutter analyze, flutter test | | Android (Kotlin) | ✅ Full | Gradle assemble, unit tests | | iOS (Swift) | ✅ Full | (static rule checks; runtime sensors WIP) |

Each platform has 50–55 rules across 10 compliance domains (feed, comments, moderation, chat, secrets, session & auth, notifications, live objects, logging hygiene, design tokens).

Installation

Install the CLI

npm install -g @amityco/social-plus-vise
vise doctor                                # verify install

Or install per-project:

npm install -D @amityco/social-plus-vise
npx vise --help

Install the Skill Into Your Coding Tool

The skill is what teaches your AI agent how to use Vise. Pick the matching host:

| Host | Install command | |---|---| | Claude Code (personal scope) | vise install-skill --target claude | | Claude Code (project scope) | vise install-skill --target claude-project . | | OpenAI Codex | vise install-skill --target codex | | Cursor (native skills) | vise install-skill --target cursor . | | Cursor (legacy rules) | vise install-skill --target cursor-rules . | | GitHub Copilot / VS Code | vise install-skill --target vscode . | | Copilot CLI / project | vise install-skill --target copilot . | | Generic agent project | vise install-skill --target agents . | | Other coding agents | vise print-skill (paste output into the host's project instructions) |

The skill is plain Markdown; you can read it any time with vise print-skill.

Usage Flow

flowchart LR
    A[User asks AI agent<br/>'Add a social feed'] --> B[Agent runs<br/>vise inspect]
    B --> C[Agent runs<br/>vise plan --request &quot;...&quot;]
    C --> D{Intake<br/>questions?}
    D -->|Yes| E[Agent asks user<br/>for feed target,<br/>design source, etc.]
    D -->|No| F
    E --> F[Agent runs<br/>vise init]
    F --> G[Agent runs<br/>vise search-docs<br/>vise get-doc-page]
    G --> H[Agent edits<br/>your code]
    H --> I[Agent runs<br/>vise check]
    I --> J{Green?}
    J -->|No, fixable| K[Agent fixes<br/>findings]
    K --> I
    J -->|No, attest| L[Agent calls<br/>vise attest with<br/>evidence]
    L --> I
    J -->|Yes| M[Agent runs<br/>vise run-sensors]
    M --> N[Done.<br/>sp-vise/ contract<br/>committed]

The flow above is what the skill teaches your AI agent. You — the human — drive intent and approve edits; the agent runs Vise commands deterministically; Vise grounds the agent in real docs and real compliance rules.

CLI Reference

Project inspection and planning

| Command | Purpose | |---|---| | vise doctor | Verify install; print version, install path, docs source | | vise inspect [path] | Detect platform, monorepo surfaces, design signals, available sensors | | vise plan [path] --request "..." | Produce a grounded implementation plan with intake questions and docs citations | | vise plan-harness [path] --request "..." | (Pre-planning step) Build the harness around the request | | vise init [path] --request "..." | Write the sp-vise/ compliance contract for this project |

Documentation grounding

| Command | Purpose | |---|---| | vise search-docs "<query>" | Search social.plus docs for relevant pages | | vise get-doc-page <path> | Fetch a specific doc page by path |

Compliance verification

| Command | Purpose | |---|---| | vise check [path] | Re-validate against the recorded contract; reports green, needs-attestation, deterministic-failures, blocked, or contract-drift | | vise check [path] --ci | Same as check, but read-only and exits non-zero unless green (for CI pipelines) | | vise validate [path] | Run the deterministic validators (subset of check that doesn't compare against attestations) | | vise sync [path] | Persist deterministic-pass evidence to sp-vise/attestations/ | | vise attest [path] --rule <id> --signer host-agent --confidence high --evidence-file evidence.json --rationale "..." | Record an attestation when a rule passes through customer-specific architecture that the deterministic check can't see | | vise explain <ruleId> | Print the rule's rationale, evidence requirements, and remediation guidance | | vise status [path] | Summarize the current compliance state |

Sensors

| Command | Purpose | |---|---| | vise run-sensors [path] | Run detected project commands (npm scripts, Gradle, Flutter, lint, typecheck, SDK import smokes); never executes arbitrary shell | | vise run-sensors [path] --dry-run | List what would run without executing |

Skill management

| Command | Purpose | |---|---| | vise install-skill --target <host> | Install the bundled skill into a coding host (see Installation) | | vise print-skill | Print the skill markdown to stdout |

Engagement scope (optional contractual metadata)

| Command | Purpose | |---|---| | vise engagement init [path] [--tier ...] [--customer-id ...] [--scope ...] | Record the contractual scope for this integration | | vise engagement show [path] | Print the recorded engagement metadata |

MCP server

| Command | Purpose | |---|---| | vise mcp | Start the stdio MCP compatibility adapter |

MCP Integration

MCP-capable hosts can call Vise as structured tool calls instead of shell commands.

Config

{
  "mcpServers": {
    "social-plus": {
      "command": "vise",
      "args": ["mcp"]
    }
  }
}

Tool names (snake_case per MCP convention)

inspect_project, plan_harness, plan_integration, init_compliance, check_compliance, sync_compliance, attest_rule, explain_rule, init_engagement, show_engagement, search_docs, get_doc_page, validate_setup, run_sensors.

These are the same operations as the CLI commands above, exposed as MCP tools.

CI Compliance

Add vise check --ci to your CI pipeline after committing sp-vise/compliance.json to your repository:

name: Vise Compliance

on:
  pull_request:
  push:
    branches: [main]

jobs:
  vise-compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @amityco/social-plus-vise
      - run: vise check . --ci

Exit codes:

| Code | Meaning | |---|---| | 0 | All rules pass (deterministic or attested) | | 1 | One or more rules need attestation | | 2 | One or more rules have deterministic failures | | 3 | One or more blockers fired (missing prerequisite, e.g. google-services.json) | | 4 | Contract drift — rules in sp-vise/compliance.json no longer match the current ruleset |

vise check --ci is read-only. It never updates sp-vise/. The JSON output includes a ci block with structured details for pipeline logs.

Compliance Contract

After vise init, your project gets a sp-vise/ directory. These files become part of your repo and travel through code review:

| File | Created by | What it contains | |---|---|---| | sp-vise/compliance.json | vise init | The rules selected for this integration, the Vise version, the ruleset digest, the target app surface, and an optional engagement link. | | sp-vise/attestations/*.json | vise sync (deterministic) or vise attest (host-agent / human) | Per-rule evidence: signer, confidence, rationale, cited files (with source fingerprints for drift detection). | | sp-vise/inspection.json | vise init | The platform, monorepo surface, and design-token signals detected at init time. | | sp-vise/engagement.json | vise engagement init (optional) | Contractual scope: tier, customer ID, contracted outcomes, reviewer assignment. |

Commit sp-vise/ to your repo. vise check re-validates against the recorded contract on every run, comparing current code against the recorded attestations. If code changes and breaks a rule, the next check reports deterministic-fail, attestation-needed, or blocked — never a silent regression.

If a rule passes through customer-specific architecture the validator can't see (a DI wrapper, an unconventional file layout, etc.), record an attestation:

vise attest . \
  --rule typescript.client.region \
  --signer host-agent \
  --confidence high \
  --evidence-file evidence.json \
  --rationale "Region is read from NEXT_PUBLIC_AMITY_REGION env var in lib/amity.ts:6"

Attestation files record source fingerprints (SHA-256 of cited files) so subsequent edits invalidate stale attestations.

Benchmark Headline

| Platform | Pure MCP findings | Vise findings | Pure MCP CI | Vise CI | |---|---|---|---|---| | React / Next.js | 7 (3 errors) | 2 (warnings) | ❌ FAIL | ✅ PASS | | React Native | 6 | 2 | ❌ FAIL | ✅ PASS | | Flutter | 9 | 2 | ❌ FAIL | ✅ PASS | | Android (Kotlin) | 9 | 0 | ❌ FAIL | ✅ PASS | | iOS (Swift) | 8 | 0 | ❌ FAIL | ✅ PASS |

Measured runs of the same AI agent (Claude Sonnet 4.6) implementing "add a global feed" on each platform, with and without Vise. Without Vise: every run ships a hardcoded API key (a deterministic failure that cannot be attested). With Vise: every run passes CI with zero deterministic failures.

For full methodology, per-cell scorecards, and the v0.7 multi-outcome cross-tool validation (chat / comments / push on React + Flutter, plus Antigravity/Gemini cross-tool), see benchmarks/RESULTS.md in the installed npm package.

Changelog

See CHANGELOG.md for the full version history.

Support

• Bugs / feature requests: contact your social.plus account team or file an issue with your integration partner.
• Documentation: https://learn.social.plus
• Skill installation issues: vise doctor prints diagnostic info; share the output with support.

License

Proprietary. See LICENSE for terms. social.plus Vise is provided to social.plus customers and integration partners under the same agreement as the social.plus SDK.