What is Vise?

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.

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.

While the agent works, Vise:

• 🧠 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.
• 🛡️ Enforces 400+ platform-specific checks — the mistakes that pass a demo and break in production.
• ✅ Gates feature completeness — the whole outcome (pagination, empty/error states, the capabilities you asked for), not just the happy path.
• 🎨 Reviews generated UI against your design system — advisory, because brand fit still needs human judgment.
• 🔧 Runs your project's own build / lint / typecheck sensors.

It 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".

🔒 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.

Vise can also run ahead of that loop: an advisory Engagement Intelligence layer turns a product goal into multiple candidate engagement strategies — what you might build, not only whether you built it right.

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.

It ships as three layers:

| Layer | Purpose | |---|---| | Skill (SKILL.md) | Teaches 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 hosts (Claude Code, Cursor, Codex, VS Code, Copilot) |

Quick Start

New to social.plus? Vise integrates the social.plus SDK. To adopt social.plus, talk to our team. Existing customers get their API key + region from the social.plus Console and can follow the SDK getting-started guide. You can install Vise and explore vise inspect/vise plan before you have credentials.

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.

# 1. Install the CLI
npm install -g @amityco/social-plus-vise
vise doctor                                # verify install

# 2. Install the AI skill into your coding tool
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. Open your AI coding tool in your project and ask:
#    "Add a social feed to this app using the social.plus SDK."

The 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.

All skill targets:

| 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 into the host's project instructions) |

Prefer 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.

How it works

1. Inspect — vise inspect detects the platform, app surfaces, available sensors, and design signals from the local repo.
2. 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 or names a capability the SDK doesn't support, it returns a structured clarify block instead of guessing; 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.
3. Initialize — vise init writes the sp-vise/ compliance contract. For a multi-surface build (a journey spanning more than one surface), it first makes you sign off the blueprint: the what — the solution path (sdk / uikit / hybrid) and the experience/surfaces to build. 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=<digest>). The sign-off can't be bypassed, and it re-arms if the path, journey, or design source later changes.
4. Build — the agent edits your code, grounded by vise search-docs and vise get-doc-page.
5. Check & repair — vise check reports deterministic findings, completeness gaps, and attestation needs. The agent fixes findings or records attestations with evidence, looping until green.
6. Sense — vise run-sensors runs your project's own typecheck/build/lint/SDK smokes. Done means the contract and evidence are committed, not just that the agent stopped.
7. Launch and verify — for any user-visible handoff, ask before spending browser/simulator/emulator/device resources. If approved, open the actual target, check the selected journey, and record what data was discovered or created. Discover targets naturally from host app state, SDK queries, user selection, or SDK create-flow return values; if the tenant has no data, prepare Console data or seed safe sample data before calling the surface populated. When a sp-vise/smoke.json contract exists, run vise smoke against captured logs; expect: "populated" requires loaded count=N with N > 0. If runtime proof genuinely can't be produced — the user declines to spend device/emulator resources, or the environment is deviceless — record an honest waiver with vise smoke waive (rather than leaving a live surface red-forever or faking evidence); vise check then reports runtime-proof-waived as an explicit under-claim. If launch verification is skipped, say what remains unverified.

Solution path & UIKit routing (advisory)

Some requests are better served by social.plus UIKit (prebuilt social surfaces) than by hand-rolling standard UI directly from SDK primitives. vise plan emits an advisory solutionPath — sdk, uikit, hybrid, or needs-decision — so an agent can pause for --answer solution_path=uikit|sdk|hybrid before it builds the wrong layer. This separates the two integrator postures cleanly: an SDK / custom-UI build (differentiated, direct-SDK) stays SDK-first, a UIKit / prebuilt-UI adoption (standard surfaces, fast launch) routes to UIKit, and a genuinely mixed request resolves to needs-decision rather than silently picking one. A request that rejects UIKit ("don't use UIKit", "we can't use UIKit") routes SDK-first, and a request that names a backend feature capability (e.g. livestreaming) is surfaced as a decision rather than a UIKit-customization default.

When UIKit is in play, vise plan can also emit uikitCustomization, recommending the lowest-effort customization tier that meets the goal — Dynamic UI → Component Styling → Localization → Behavior Overrides → Fork and Extend → SDK Custom UI. Both signals are advisory only: they never change outcome classification, compliance rules, the sidecar schema, or vise check exit codes.

Three validation layers

The layer is set by the kind of claim, which is how Vise avoids treating "looks plausible" as "ready to ship." The current package covers all three layers across supported platforms: compliance and completeness are enforced by vise check, while design conformance is available as an advisory review loop.

| Layer | Claim | How | Enforcement | |---|---|---|---| | SDK compliance | "this is wrong" | 400+ deterministic checks (session renewal, live-collection vs one-shot, secret hygiene, parent-child rendering, ban-state gating…) | Hard gate — vise check blocks until green or attested; a small advisory subset never blocks | | Feature completeness | "this is missing" | A narrow mandatory baseline per outcome (pagination for feeds, a composer for comments, send + read state for chat, SDK-backed counts for profiles); richer capabilities are explicit opt-ins from vise plan | Decision gate — vise check exits completeness-gap until each baseline item is built or opted out with // vise: scope-omit <id> — <reason> | | Design conformance | "this looks off" | Extract your design system into a contract, confirm a preview, then check token usage | Advisory — vise design check/preview; never fails a build |

Correctness is gated by deterministic rules or attestations; completeness is gated by explicit scope decisions; conformance stays advisory because "matches the brand" is legitimately subjective. vise explain <ruleId> prints any rule's rationale, evidence requirements, and remediation.

App launch verification is the final acceptance step outside these three layers. vise check and vise run-sensors can prove structure, completeness, and local build commands; a browser or native launch confirms the selected user journey is actually visible.

Supported outcomes: feed · comments · chat · moderation · community · social graph (follow) · in-app notifications · plus setup (SDK, push, live data). vise plan/init classify the request and tailor the plan, rules, and feature checklist.

Engagement Intelligence

Advisory, in preview. The three layers above answer whether you built it right. Ahead of the build, Vise can also help reason about what to build: an Engagement Intelligence layer turns a product goal into multiple candidate engagement strategies — archetypes, UX patterns, and solution variants drawn from a social.plus experience catalog — with rationale, tradeoffs, no-fit guidance, availability limits, and review gaps. The driving agent presents the EI choice as a visible decision — recommended experience, concrete fit signals, credible alternatives, tradeoffs, expected blueprint surfaces, and no-fit option — before it accepts a variant. The human or driving agent still chooses the direction, then Vise compiles that selected variant into an implementation plan (vise creative → vise creative accept → vise experience compile), optionally bridging to installable social.plus blocks, plus advisory UX expectations and a multi-dimension experience review.

It is local-only, never uploads, carries no calibrated score, and never changes vise check's exit codes. The opt-in ranking preview is review context, not a top-1 confidence claim or autonomous product-strategy selector. Use it to shape the work; the validation layers still decide when it's done.

Design contracts

Vise can ingest your aesthetic from an HTML/CSS prototype (vise design extract) or from the host app's own design system across web, Android, Flutter, and iOS (vise design extract --from-project). The contract is advisory input for generation, never an enforcement gate, and it feeds forward into plans only after you confirm the generated preview with --answer design_contract_confirmation=yes — and on a multi-surface blueprint that confirmation is folded into the single blueprint sign-off, so you approve the design once for the whole journey rather than per surface. For social.plus-specific styling, vise design init-tokens scaffolds a dedicated, customer-editable token file (src/styles/social-plus-tokens.css) — edit it, re-extract, and future builds inherit the palette with no agent in the loop.

Evidence

We put Vise through the same brownfield social.plus integration twice per platform — once through the governed Vise workflow, once from a structured checklist with Vise switched off (the control) — across five platform families, on a live tenant with no mocking. The precise, uniform benchmark is Claude Sonnet 5; we cross-checked the direction with a second agent, OpenAI Codex GPT-5.4. Read the direction, not the decimals.

Anchor: Claude Sonnet 5, per platform

Composite score, 0–100 shared scale; every control built and launched.

| Platform | Fixture | Vise | no-Vise | Δ | |---|---|--:|--:|--:| | Web | PULSE / pulse-studio | 88.3 | 56.8 | +31.5 | | React Native | Arena Fit | 89.7 | 62.1 | +27.6 | | iOS | Luminary Club | 77.5 | 48.0 | +29.5 | | Android | MarketPulse | 77.5 | 50.1 | +27.4 | | Flutter | Fieldhouse | 78.0 | 48.5 | +29.5 | | Average | 5 fixtures | 82.2 | 53.1 | +29.1 |

That +29.1 full composite still carries the +90 definitional capability axis (the control scores 0 there by construction). Drop it and re-weight the four fair dimensions to 100%:

| | Vise | no-Vise | Δ | |---|--:|--:|--:| | Full weighted composite (incl. capability axis) | 82.2 | 53.1 | +29.1 | | Credible-only (capability axis removed) | 83.0 | 70.8 | +12.1 |

+12.1 is the number to stand behind. It comes from Product outcome +17.6 and Design integration +15.8 (the credible wins); Runtime hygiene is a near-tie (+1.9 — build/launch cleanliness, which a capable agent clears either way; on Android the checklist control actually built cleaner — this is not SDK-rule compliance, see below); Efficiency +11.7 is a scorer budget metric (the governed arm is slower in real time, ~2.7× on web); Capability activation +90 is definitional, kept out of the headline. (Deltas use unrounded composites, so hand-subtracting rounded cells can differ by 0.1.)

Why the hygiene dimension is near-parity — and why that isn't the whole story. The scorer's correctness dimension measures runtime hygiene (build, launch, no crashes/secrets/hardcoded IDs), which strong agents clear with or without Vise. It is not SDK-rule compliance — the thing the 400+ deterministic rules govern. That is measured directly by a separate compliance-findings metric (vise validate on both arms' produced source): an ungoverned control carries real rule violations a smoke test never surfaces, and its runtime symptoms already show up as the product-outcome gap above.

Cross-check: OpenAI Codex GPT-5.4 (directional)

The same A/B run with Codex points the same way — Vise ahead on every platform. Codex's exact figures are directional, not precise: its no-Vise controls are high-variance — on Android a single control has read anywhere from +63 (an unlucky, instrument-affected run on the earlier harness) down to +27 (clean). Run cleanly on the hardened harness (Android and iOS N=3; Flutter one clean launch, the rest watchdog-blocked), Codex's controls land ~65 and its lift settles around +25–30, converging with Sonnet's. Honest cross-model read: both agents show Vise winning by ~+25–30 once controls are run cleanly. We anchor on Sonnet because it is the uniform, current-harness run; Codex is cross-model confirmation of direction.

Methodology & caveats

• Vise is the deterministic CLI under test, not an AI model. Each arm runs the same coding agent on the same brownfield fixture, live tenant, no mocking.
• Scoring weights: capability activation 25% (definitional), product outcome 25%, design integration 20%, runtime hygiene 20% (the scorer's correctness key — build/launch cleanliness, not SDK-rule compliance), efficiency 10%. A separate compliance-findings metric (vise validate on both arms) measures SDK-rule adherence directly. The credible-only composite drops the capability axis and re-weights the other four to 100%.
• Small-N, directional. Controls are n = 1–3 per arm, so neither model is a precise second measurement, and the two are not directly comparable (Codex ran on an earlier harness). The runtime-signal scorer that could over-credit a rendered-but-broken shell is now gated. July 2026 product-evidence runs on representative fixtures — not a third-party audit. For a formal comparison, keep each Vise / no-Vise pair on the same model and reasoning setting.

Cursor, Claude, Codex, GitHub Copilot, VS Code, and other product names are trademarks of their respective owners; social.plus is not affiliated with or endorsed by them.

Supported Platforms

| Platform | Status | Sensors | |---|---|---| | TypeScript / Next.js / React | Supported | tsc, npm build, npm lint, SDK import smoke | | React Native | Supported | tsc, npm lint, SDK import smoke | | Flutter / Dart | Supported | flutter analyze, flutter test | | Android (Kotlin) | Supported | Gradle assemble, unit tests | | iOS (Swift) | Supported | Static rules fully operational (tree-sitter AST for highest-risk rules); Package.swift enables a SwiftPM manifest sensor, and .xcodeproj/.xcworkspace enables a guarded xcodebuild sensor when available |

Each platform is checked by the shipped rule suite across feed, comments, chat, moderation, communities, social graph, secrets, session & auth, notifications, live data, security, design, and more.

CLI Reference

Run vise <command> --help for full flags. JSON output is the default for agent-facing commands; the read commands (check, status, plan, doctor, explain, explore) also accept --format human for a readable summary.

Inspect, plan, initialize

| Command | Purpose | |---|---| | vise explore "<request>" | Pre-credentials discovery: map a request to what social.plus offers (candidate outcome, capabilities, docs, next command). No project or API key needed | | vise doctor | Verify install; print version, install path, docs source | | vise inspect [path] | Detect platform, monorepo surfaces, design signals, available sensors, and bounded scan coverage. An incomplete scan cannot initialize or produce a green check; select a concrete app surface in a large monorepo | | vise plan [path] --request "..." [--summary] | Grounded implementation plan with intake questions and docs citations; --summary prints a compact route/intake view | | vise plan --summary "..." | Shortcut for quick routing or discovery when the current directory is the repo | | vise plan-harness [path] --request "..." | Pre-planning step: build the harness around the request | | vise init [path] --request "..." [--answer key=value] | Write the sp-vise/ compliance contract once blocking intake is answered; exits 7 (needs-clarification) otherwise. Refuses to initialize the Vise / social.plus blocks development workspace itself (status: "internal-workspace", exit 10 — use vise sdk-facts there, or --allow-internal-workspace for an intentional harness run). Replacing a green engagement with a different outcome requires --supersede-engagement (exit 7 otherwise); the outgoing engagement's final state is recorded to sp-vise/engagements/ either way | | vise workplan next [path] --request "..." | For broad social requests: print the next uncompleted surface and its focused commands | | vise workplan status [path] --request "..." | Show the workplan sequence and completed surfaces; ignores unverifiable or drifted snapshot evidence. If the in-scope surface's live vise check is already green, auto-records that one surface (same evidence bar as workplan complete) so a working, check-green surface isn't left uncounted | | vise workplan complete [path] --request "..." --surface <id> | Record a green-checked surface; snapshots evidence plus an integrity manifest under sp-vise/workplan-snapshots/<surface>/ | | vise workplan trim [path] --request "..." --surface <id> --reason "..." | Deliberately omit a companion surface (surface-level scope-omit). --reason required; re-arms the blueprint sign-off gate (re-sign the trimmed blueprint before proceeding) |

Creative pre-planning (advisory)

| Command | Purpose | |---|---| | vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview] | Write an advisory Engagement Intelligence brief with multiple candidate solution variants, rationale, tradeoffs, and review gaps; --ranking-preview adds opt-in, local-only review context that never reorders the default candidates | | vise creative accept [path] --variant <id> --rationale "..." --confidence high\|medium\|low | Record the grounded selected variant so plan/init/workplan carry it forward; --variant none --rationale "..." --confidence high\|medium\|low records a catalog-gap signal instead | | vise ux-harness [path] | Generate advisory UX expectations from the accepted selection | | vise experience compile [path] | Compile the accepted variant into an implementation artifact plan | | vise experience sensors [path] | Write an advisory multi-dimension sensor framework (no calibrated score) | | vise experience-report [path] | Write an advisory dimensioned review report (no calibrated score) | | vise learning record [path] | Append a local-only learning event; refreshes the learning summary | | vise learning show [path] | Read the local learning summary (never changes recommendations) |

Everything in this group is local and advisory: no uploads, no vise check exit-code changes, no auto-accepted variants, no top-1 confidence claim, and no calibrated score.

Design contract

| Command | Purpose | |---|---| | vise design extract <prototypePath> [--repo .] [--no-write] | Extract a graded design contract + visual preview from an HTML/CSS prototype | | vise design extract --from-project [path] [--no-write] | Derive the contract from the project's own design system: CSS custom properties (incl. shadcn/Tailwind v4 @theme), TS/JS token modules, Android colors.xml/dimens.xml, Flutter Color(0x…), iOS .colorset/Swift colors | | vise design check [path] | Advisory token-conformance report (incl. computed WCAG for the brand palette's role pairs when a profile exists); never fails a build | | vise design contrast <foreground> <background> | Compute the WCAG 2.x contrast ratio between two colours (advisory) — check any text/icon colour that isn't a palette role instead of eyeballing it | | vise design preview [path] [--reference <prototype>] | Write a self-contained visual review (sp-vise/design-preview.html) for human/VLM judgment | | vise design reference [path] [--title <name>] | Write a self-contained design-system spec: swatches, type samples, component demos | | vise design init-tokens [path] [--force] | Scaffold src/styles/social-plus-tokens.css (greenfield defaults or seeded from existing tokens); idempotent |

Docs grounding & troubleshooting

| 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 | | vise sdk-facts --platform <platform> [--capability <capability>] [--format json] | Read bundled SDK surface facts without a project; useful for agents and block packaging when they need field-level facts before editing | | vise debug [path] --error "..." [--brief] | Diagnose an SDK-specific runtime failure; --brief returns the likely rule, minimal patch shape, and verification commands |

Compliance verification

| Command | Purpose | |---|---| | vise check [path] | Re-validate against the recorded contract: green, needs-attestation, deterministic-failures, blocked, contract-drift, completeness-gap, selected-capability-failures, no-platform (no SDK platform detected — reported as a failure, not a vacuous green), or runtime-proof-waived | | vise check [path] --ci | Read-only release gate for the active contract and every recorded engagement. Active non-green keeps its normal exit code; active green with completed-work drift exits 11 | | vise check [path] --allow-proof-waiver | Accept an honest runtime-proof-waived result (from vise smoke waive) as passing (exit 0) instead of blocking; without it a waiver blocks CI by default | | vise check [path] --new-only | Brownfield gate. With a recorded baseline, gate only on rule findings introduced since the baseline (pre-existing ones are reported but excluded). The outcome's completeness checklist and selected optional capabilities are never excluded — they are the engagement's deliverables and gate like a default check. Default check always gates on everything | | vise check [path] --engagement <outcome> | Re-verdict one recorded engagement (from sp-vise/engagements/) against the current ruleset and code. Exit 11 on drift, 0 when it still holds; never the active engagement's codes. ruleset_upgraded discloses when the installed ruleset moved since it was recorded | | vise check [path] --all-engagements | Run the normal active gate plus re-verdicts of every recorded engagement. Active gate non-green → its normal exit code; active green but a recorded engagement drifted → exit 11 (engagement-drift). Findings already gating the active engagement are counted once there (shared_with_active) | | vise baseline [path] | Snapshot the current pre-existing rule findings to sp-vise/baseline.json so check --new-only can separate legacy debt from new gaps. Deliverables (completeness/selected capabilities) are never baselined. Record it right after vise init, before writing code — a mid-build baseline would swallow your own findings. vise init --baseline records it at init time | | vise validate [path] | Run the deterministic validators only (no attestation comparison) | | 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 architecture the deterministic check can't see. Attestations are bound to the engagement outcome they were reviewed under: after vise init switches the sidecar to a different outcome, a rule-global attestation re-gates (stale_engagement_attestation) until re-attested — file-scoped attestations survive the switch because new files re-gate them anyway | | vise explain <ruleId> | Print a rule's rationale, evidence requirements, and remediation | | vise status [path] | Summarize the current compliance state |

Sensors, skill, engagement, server

| Command | Purpose | |---|---| | vise run-sensors [path] [--dry-run] [--include "<sensor name>"] | Run detected project scripts (npm, Gradle, Flutter, lint, typecheck, SDK smokes); --dry-run lists without executing. Every explicit include must match a detected sensor or the command fails; output is bounded and timed-out descendants are terminated | | vise smoke [path] --log <file> | Assess a captured mount-smoke log into a pass/fail verdict + record evidence. expect: "populated" requires loaded count=N with N > 0; this catches session-establish and empty-data gaps that static checks cannot see | | vise smoke waive [path] --reason "..." [--mode declined\|deviceless] | Record an auditable runtime-proof waiver when proof is declined or no device/emulator is available, instead of faking evidence. vise check then reports runtime-proof-waived (exit 9; accept with --allow-proof-waiver) rather than a red-forever live surface | | vise install-skill --target <host> | Install the bundled skill into a coding host (see Quick Start) | | vise print-skill | Print the skill markdown to stdout | | vise engagement init [path] [--tier ...] [--customer-id ...] [--scope ...] | Record optional contractual scope metadata | | vise engagement show [path] | Print the recorded engagement metadata | | vise mcp | Start the stdio MCP compatibility adapter |

MCP Integration

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

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

Tool names (snake_case per MCP convention): search_docs, get_doc_page, inspect_project, creative_brief, creative_accept, ux_harness, compile_experience, experience_sensors, plan_harness, plan_integration, init_compliance, check_compliance, experience_report, record_learning, show_learning, sync_compliance, attest_rule, explain_rule, init_engagement, show_engagement, resolve_request, run_sensors, smoke, validate_setup, suggest_patch, debug_issue, design_extract, design_check, design_contrast, design_preview, design_reference, design_init_tokens, get_sdk_facts.

Most tools mirror the CLI commands above. The adapter still answers the legacy resolve_request and suggest_patch names for compatibility, but they are deprecated in favour of plan_integration plus host-tool edits.

CI Compliance

Commit sp-vise/ to your repository, then add vise check --ci to your pipeline:

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

vise check --ci is read-only — it never updates sp-vise/ — and its JSON output includes a structured ci block for pipeline logs. It automatically re-verdicts every recorded engagement, so CI holds previously completed surfaces green without a second --all-engagements command.

| Exit code | Meaning | |---|---| | 0 | All rules pass; baseline capabilities present or opted-out; selected optional capabilities pass | | 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 — recorded rules no longer match the current ruleset | | 5 | Baseline capability neither implemented nor opted-out (add it or place // vise: scope-omit <id> — <reason>) | | 6 | An explicitly selected optional capability failed its source sensors | | 8 | No SDK platform detected (no-platform) — reported as a failure, never a vacuous green | | 9 | Runtime proof waived (runtime-proof-waived) — accept explicitly with --allow-proof-waiver | | 11 | Engagement drift (--ci, --engagement, or --all-engagements): the active gate is green but a recorded engagement re-verdicts non-green — a previously finished surface no longer holds |

Compliance Contract

Vise writes local planning, compliance, design, and evidence artifacts under sp-vise/. These files become part of your repo and travel through code review — commit them. vise check re-validates against the recorded contract on every run, so a code change that breaks a rule surfaces as deterministic-fail, attestation-needed, or blocked — never a silent regression.

| File | Created by | What it contains | |---|---|---| | sp-vise/compliance.json | vise init | Selected rules, ruleset digest, app surface, selected optional capabilities, accepted design digest | | sp-vise/intake.json | vise init | Request, outcome, intake answers, design-review status | | sp-vise/inspection.json | vise init | Platform, surface, and design signals detected at init | | sp-vise/attestations/*.json | vise sync / vise attest | Per-rule evidence: signer, confidence, rationale, source fingerprints for drift detection | | sp-vise/engagements/<outcome>/*.json | vise init (on an outcome switch) | Engagement ledger: the superseded engagement's final check, contract, and intake (latest per outcome) — surfaced by vise status as previousEngagements | | sp-vise/creative-brief.json + creative-brief.md | vise creative | Advisory brief: goals, archetypes, candidate variants (JSON + human-readable) | | sp-vise/candidate-ranking-preview.json | vise creative --ranking-preview | Opt-in local ranking preview for review context; experience_score: null, no uploads, no default-order change, no top-1 confidence claim | | sp-vise/creative-selection.json | vise creative accept | Accepted variant and plan/workplan feed-forward context | | sp-vise/catalog-gap.json | vise creative accept --variant none --rationale "..." --confidence high\|medium\|low | Local-only no-fit signal for human catalog review | | sp-vise/ux-harness.json | vise creative accept or vise ux-harness | Advisory UX pattern expectations and anti-patterns | | sp-vise/experience-compiler.json | vise experience compile | Advisory implementation plan: install guidance, surfaces, validation commands | | sp-vise/experience-sensors.json | vise experience sensors | Advisory sensor framework; score: null until calibrated | | sp-vise/experience-report.json | vise experience-report | Advisory dimensioned review; score: null until calibrated | | sp-vise/learning-events.jsonl | vise learning record | Append-only, local-only learning event log | | sp-vise/learning-summary.json | vise learning record | Derived summary; recommendationOptimization.status: "not-active" | | sp-vise/flow.json | vise workplan next / trim | Entry-state, selected solution path, active blueprint digest, sign-off state, and omitted companion surfaces | | sp-vise/flow-blueprint.html | vise workplan next | Human-readable blueprint preview for the alignment gate; review before passing blueprint_confirmation=<digest> | | sp-vise/workplan.json | vise workplan complete | Broad-request progress: completed surfaces, green-check evidence, snapshot integrity digest | | sp-vise/workplan-snapshots/<surface>/ | vise workplan complete | Per-surface snapshots plus snapshot-manifest.json so later focused surfaces don't erase earlier proof | | sp-vise/smoke.json | project/runtime harness | Declared runtime-smoke surfaces and expected resolution states | | sp-vise/evidence/runtime-smoke.json | vise smoke | Captured runtime-smoke verdicts used by evidence-citing runtime rules | | sp-vise/design-contract.json | vise design extract | Extracted tokens, breakpoints, source digests, stable design digest | | sp-vise/design-preview.html | vise design extract / preview | Self-contained visual review; open before answering design_contract_confirmation | | sp-vise/design-reference.html | vise design reference | Self-contained design-system spec (swatches, type, components) | | sp-vise/engagement.json | vise engagement init (optional) | Contractual scope: tier, customer ID, outcomes, reviewer |

If a rule passes through customer-specific architecture the validator can't see (a DI wrapper, an unconventional layout), 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"

Attestations record SHA-256 source fingerprints of cited files, so later edits to those files invalidate the attestation automatically.

Support

• Documentation: https://learn.social.plus — the same corpus vise search-docs grounds agents in.
• Questions, bugs & feature requests: email [email protected]. Existing customers can also reach their social.plus account team or integration partner.
• Skill installation issues: run vise doctor and include its output.
• Version history: CHANGELOG.md ships inside the installed package.

License

Proprietary — see the LICENSE file included with the package. Free to install and evaluate for integrating the social.plus SDK, including by teams assessing whether to adopt social.plus. Production use alongside the social.plus platform is covered by your social.plus agreement; integration partners are licensed under their partner agreement.

Installing globally (npm install -g) or running via npx keeps Vise out of your application's dependency tree — and its proprietary license out of your SBOM / dependency-license scanner reports.