nvsinner-architecture-contract

Document architectural decisions and invariants for the NvSinner Neovim distribution.

1|Updated Jul 1, 2026

Search Tags:#architecture #debugging #configuration #ai workflow #lua #lazy.nvim #neovim

Ready to run

npx skills add https://github.com/anderssonq/nvsinner --skill nvsinner-architecture-contract

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: nvsinner-architecture-contract
Source: https://github.com/anderssonq/nvsinner/tree/main/.claude/skills/nvsinner-architecture-contract
Command: npx skills add https://github.com/anderssonq/nvsinner --skill nvsinner-architecture-contract

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a reliable architectural map for understanding NvSinner's design decisions, invariants, and trade-offs before modifying the Neovim distribution, reducing the risk of breaking core workflows.

Core Features & Use Cases

Architecture Understanding: Explains the boot sequence, native Lua core layer, plugin organization, NVIM_APPNAME isolation, and distro engineering model.
Change Safety Guidance: Documents load-bearing decisions such as CLI-based AI integration, lazy.nvim restore behavior, autoreload choices, terminal UX patterns, and palette management.
Use Case: When extending NvSinner with new features or debugging regressions, use this Skill to determine which components can change safely and which invariants must remain intact.

Quick Start

Use the nvsinner architecture contract skill to explain why a proposed change to the NvSinner configuration will or will not break existing design guarantees.

Frequently Asked Questions about nvsinner-architecture-contract

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How does the NvSinner Neovim distribution boot sequence and module layering work?▼

The NvSinner boot sequence initializes a native Lua core layer, organizes plugin loading via lazy.nvim, and isolates environments using NVIM_APPNAME. Understanding this module layering prevents regressions when modifying the Neovim distribution.

How do I safely change Neovim plugin loading rules without breaking lazy.nvim restore behavior?▼

To safely change Neovim plugin loading rules, review the architectural invariants governing lazy.nvim restore behavior and autoreload choices. Modifying these load-bearing decisions risks breaking core workflows if the original design guarantees are not maintained.

Why does my terminal AI workflow integration break after modifying Neovim configuration boundaries?▼

Terminal AI workflow integration breaks because it relies on strict CLI-based architectural decisions and Lua module boundaries. Changing these configuration boundaries violates the design invariants that prevent regressions in the NvSinner distribution.

Can I use NVIM_APPNAME isolation to test new Neovim configurations without affecting my main setup?▼

Yes, NVIM_APPNAME isolation is a core architectural feature allowing you to test Neovim configurations safely. It separates the NvSinner distribution environment, ensuring experimental changes do not impact your primary setup.

What are the limitations when extending NvSinner with new features and debugging design issues?▼

When extending NvSinner, limitations center on preserving load-bearing decisions like palette management and terminal UX patterns. Debugging design issues requires respecting these operational constraints to avoid breaking existing architectural guarantees.

What is the best way to debug regressions in a complex Lua-based Neovim distribution?▼

The best way to debug regressions is analyzing the architectural contract to identify violated invariants. Checking boot ordering, Lua module boundaries, and plugin loading rules reveals which design guarantees were broken during configuration changes.