feat: add relational document system specification and plan
This commit is contained in:
parent
ef65e38bb2
commit
9152f868ce
GPG key ID:
3DDB9C3E023F1F31
6 changed files with 393 additions and 0 deletions
150
specs/001-create-a-neovim/plan.md
Normal file
150
specs/001-create-a-neovim/plan.md
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
# 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**:
|
||||
- [x] Phase 0: Research complete (/plan command)
|
||||
- [x] 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**:
|
||||
- [x] Initial Constitution Check: PASS
|
||||
- [x] Post-Design Constitution Check: PASS
|
||||
- [x] All NEEDS CLARIFICATION resolved
|
||||
- [ ] Complexity deviations documented
|
||||
|
||||
---
|
||||
*Based on Constitution v1.0.0 - See `/memory/constitution.md`*
|
||||
Loading…
Add table
Add a link
Reference in a new issue