notex.nvim/specs/001-create-a-neovim/plan.md

Implementation Plan: Relational Document System in Neovim

Branch: 001-create-a-neovim | Date: 2025-10-01 | Spec: [link to spec.md] Input: Feature specification from /specs/001-create-a-neovim/spec.md

Execution Flow (/plan command scope)

1. Load feature spec from Input path
   → If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
   → Detect Project Type from file system structure or context (web=frontend+backend, mobile=app+api)
   → Set Structure Decision based on project type
3. Fill the Constitution Check section based on the content of the constitution document.
4. Evaluate Constitution Check section below
   → If violations exist: Document in Complexity Tracking
   → If no justification possible: ERROR "Simplify approach first"
   → Update Progress Tracking: Initial Constitution Check
5. Execute Phase 0 → research.md
   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode).
7. Re-evaluate Constitution Check section
   → If new violations: Refactor design, return to Phase 1
   → Update Progress Tracking: Post-Design Constitution Check
8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
9. STOP - Ready for /tasks command

IMPORTANT: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:

• Phase 2: /tasks command creates tasks.md
• Phase 3-4: Implementation execution (manual or via tools)

Summary

The project is a Neovim plugin that provides a relational document system. It uses markdown files with YAML frontmatter as documents and supports typed schemas, linking, and query-based views. The queries are defined using a custom block syntax and rendered in virtual buffers. The implementation will be in Lua, leveraging an SQLite database for performance.

Technical Context

Language/Version: Lua (Neovim compatible) Primary Dependencies: lsqlite3 (or similar, to be confirmed by research) Storage: SQLite Testing: busted (or similar, to be confirmed by research) Target Platform: Neovim Project Type: Single project (Neovim plugin) Performance Goals: Query execution should be non-blocking and feel instantaneous for typical workloads. Constraints: Must be implemented in Lua for seamless integration with Neovim. Scale/Scope: The system should be able to handle a library of several thousand documents without significant performance degradation.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• I. Clean Code: Is the proposed code structure and design clean and maintainable?
• II. Functional Style: Does the design favor a functional approach where appropriate?
• III. Descriptive Coding: Is the naming of components and files descriptive and self-documenting?

Project Structure

Documentation (this feature)

specs/001-create-a-neovim/
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command)
├── data-model.md        # Phase 1 output (/plan command)
├── quickstart.md        # Phase 1 output (/plan command)
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)

Source Code (repository root)

lua/
└── notex/
    ├── init.lua
    ├── schema.lua
    ├── document.lua
    ├── query.lua
    └── view.lua
tests/
├── spec/
│   ├── schema_spec.lua
│   └── query_spec.lua
└── integration/
    └── main_spec.lua

Structure Decision: A single project structure is chosen, which is standard for Neovim plugins. The core logic will reside in the lua/notex directory.

Phase 0: Outline & Research

1. Extract unknowns from Technical Context above:
   • Research Lua SQLite libraries (e.g., lsqlite3).
   • Research Lua testing frameworks (e.g., busted).
   • Research best practices for Neovim plugin development in Lua.
2. Consolidate findings in research.md.

Output: research.md with all NEEDS CLARIFICATION resolved.

Phase 1: Design & Contracts

Prerequisites: research.md complete

1. Extract entities from feature spec → data-model.md.
2. Extract test scenarios from user stories → quickstart.md.
3. Update agent file incrementally.

Output: data-model.md, quickstart.md, and updated agent file.

Phase 2: Task Planning Approach

This section describes what the /tasks command will do - DO NOT execute during /plan

Task Generation Strategy:

• Load .specify/templates/tasks-template.md as base.
• Generate tasks from Phase 1 design docs (data-model.md, quickstart.md).
• Each entity in the data model will have corresponding implementation tasks.
• Each scenario in the quickstart guide will have a corresponding integration test task.

Ordering Strategy:

• TDD order: Tests before implementation.
• Dependency order: Core data structures and parsing before query and view logic.
• Mark [P] for parallel execution (independent files).

Estimated Output: A list of ordered tasks in tasks.md.

Phase 3+: Future Implementation

These phases are beyond the scope of the /plan command

Phase 3: Task execution (/tasks command creates tasks.md) Phase 4: Implementation (execute tasks.md) Phase 5: Validation (run tests, execute quickstart.md)

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because

Progress Tracking

This checklist is updated during execution flow

Phase Status:

• Phase 0: Research complete (/plan command)
• Phase 1: Design complete (/plan command)
• Phase 2: Task planning complete (/plan command - describe approach only)
• Phase 3: Tasks generated (/tasks command)
• Phase 4: Implementation complete
• Phase 5: Validation passed

Gate Status:

• Initial Constitution Check: PASS
• Post-Design Constitution Check: PASS
• All NEEDS CLARIFICATION resolved
• Complexity deviations documented

---

Based on Constitution v1.0.0 - See /memory/constitution.md