nvim-stride: Instructions file for Codex

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

• Mentions planning or proposals (words like proposal, spec, change, plan)
• Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
• Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

• How to create and apply change proposals
• Spec format and conventions
• Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

AGENTS.md

Guide for AI agents working on this Neovim plugin. Based on patterns from flash.nvim.

Architecture

Directory Structure

lua/
  plugin_name/        # Internal modules
    module.lua        # Feature modules
  plugin_name.lua     # Main entry point, public API, setup()
plugin/
  plugin_name.lua     # Vim commands, autocommands
tests/
  plugin_name/        # Test files per module
  minimal_init.lua    # Test harness
doc/                  # Help documentation

Layered Design

┌─────────────────────────────────┐
│  Public API (plugin_name.lua)   │  User-facing: setup(), commands
├─────────────────────────────────┤
│  Plugins/Modes                  │  Feature implementations
├─────────────────────────────────┤
│  Core Modules                   │  Business logic
├─────────────────────────────────┤
│  Utilities                      │  Helpers, low-level
└─────────────────────────────────┘

Module Pattern

-- Every module follows this structure
local M = {}
M.__index = M  -- If class-like

-- Private state
local state = {}

-- Private functions (local)
local function helper() end

-- Public methods
function M.new() end
function M:method() end

return M

Style Guide

Naming

Type	Convention	Example
Functions	snake_case	get_matches, update_state
Private funcs	underscore prefix	M:_update(), M:_call()
Variables	snake_case	match_count, win_id
Constants	UPPER_CASE	M.ESC, M.CR
Module table	M	local M = {}
Requires	PascalCase	local Config = require(...)