Add VISION.md and AGENTS.md
VISION.md: Project goals, design principles, architecture, milestones AGENTS.md: AI agent guidelines for working on the codebase
This commit is contained in:
Levi Neely
parent
14fc3233e9
commit
6f3cc0578d
|
|
@ -0,0 +1,127 @@
|
|||
# Agent Guidelines
|
||||
|
||||
Instructions for AI agents working on orkmode.
|
||||
|
||||
## Project Context
|
||||
|
||||
Orkmode is a native org-mode implementation: Rust parser/core + Qt/QML UI.
|
||||
|
||||
Current state: **v0.1** — parser and CLI complete, no UI yet.
|
||||
|
||||
## Codebase Structure
|
||||
|
||||
```
|
||||
crates/
|
||||
├── org-ast/ # AST types (Document, Section, Element, etc.)
|
||||
├── org-parser/ # Tree-sitter parser, AST conversion
|
||||
├── orkmode-core/ # High-level API, C FFI
|
||||
└── ork-cli/ # CLI tool (bin name: ork)
|
||||
```
|
||||
|
||||
## Working with the Code
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
Requires: Rust 1.70+, C compiler (for tree-sitter grammar).
|
||||
|
||||
### Test
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
```
|
||||
|
||||
### CLI
|
||||
|
||||
The `ork` CLI operates on directories by default:
|
||||
|
||||
```bash
|
||||
ork info . # Aggregate info for all .org files
|
||||
ork sections --todos-only # List TODOs across files
|
||||
ork query "tag:work" -R # Recursive search
|
||||
ork get "section-id" -j # JSON output
|
||||
ork toggle "task-id" -n # Dry run
|
||||
ork add "New Task" file.org --todo TODO
|
||||
```
|
||||
|
||||
Use `-j/--json` for machine-readable output. Use `-n/--dry-run` for mutations.
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
### Parser
|
||||
|
||||
- Uses [tree-sitter-org](https://github.com/nvim-orgmode/tree-sitter-org) grammar (git submodule)
|
||||
- Pinned to tree-sitter 0.22 (0.23+ requires rustc 1.90+)
|
||||
- Conversion in `org-parser/src/convert.rs` maps tree-sitter nodes to AST
|
||||
|
||||
### AST
|
||||
|
||||
- Follows [org-element spec](https://orgmode.org/worg/dev/org-syntax.html)
|
||||
- All nodes have `Span` for source locations
|
||||
- `Document` → `Section`* → `Element`* / `Section`*
|
||||
- Inline objects (bold, links) are partially implemented
|
||||
|
||||
### FFI
|
||||
|
||||
- C-compatible FFI in `orkmode-core/src/ffi.rs`
|
||||
- Functions prefixed `ork_*`
|
||||
- Caller owns returned strings (free with `ork_string_free`)
|
||||
|
||||
## Conventions
|
||||
|
||||
### Rust
|
||||
|
||||
- Edition 2021
|
||||
- Use `thiserror` for error types
|
||||
- Use `serde` for serialization
|
||||
- Prefer `&str` over `String` in function signatures
|
||||
- Match existing code style
|
||||
|
||||
### Commits
|
||||
|
||||
- Imperative mood: "Add feature" not "Added feature"
|
||||
- Reference issue/context in body if relevant
|
||||
|
||||
### CLI
|
||||
|
||||
- Commands operate on paths (file or directory)
|
||||
- Default to current directory
|
||||
- `-R` for recursive
|
||||
- `-j` for JSON output
|
||||
- `-n` for dry run
|
||||
|
||||
## Current Limitations
|
||||
|
||||
1. **Inline objects incomplete** — tree-sitter-org doesn't fully parse bold/italic/links
|
||||
2. **Property/tag write commands** — stubs only, not implemented
|
||||
3. **Timestamp text** — displays "set" placeholder, not actual date
|
||||
4. **No incremental parsing** — full reparse on every call
|
||||
|
||||
## Next Steps (v0.2)
|
||||
|
||||
Priority: Qt/QML read-only document viewer.
|
||||
|
||||
Tasks:
|
||||
1. Set up Qt6/QML project in `ui/`
|
||||
2. Link orkmode-core via C FFI
|
||||
3. Implement document model (QAbstractItemModel)
|
||||
4. Basic headline rendering with folding
|
||||
5. Syntax highlighting
|
||||
|
||||
## Testing Changes
|
||||
|
||||
Before committing:
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
cargo test
|
||||
./target/release/ork check .
|
||||
./target/release/ork info test.org -j
|
||||
```
|
||||
|
||||
## Questions?
|
||||
|
||||
Check VISION.md for project goals and design principles.
|
||||
|
|
@ -0,0 +1,130 @@
|
|||
# Orkmode Vision
|
||||
|
||||
## The Problem
|
||||
|
||||
Org-mode is exceptional for structured thinking, task management, and knowledge work. But it's trapped in Emacs.
|
||||
|
||||
Existing alternatives fall short:
|
||||
- **Organice** (web): Clunky, slow, limited offline
|
||||
- **Orgzly** (Android): Mobile-only, sync issues
|
||||
- **VS Code extensions**: No proper AST, just syntax highlighting
|
||||
- **Logseq/Obsidian**: Different formats, not org-mode
|
||||
|
||||
None of these integrate with the Linux desktop. None feel native.
|
||||
|
||||
## The Goal
|
||||
|
||||
A native KDE application for org-mode that:
|
||||
- Parses org files correctly (tree-sitter AST, not regex)
|
||||
- Renders beautifully (Qt/QML, not web views)
|
||||
- Edits efficiently (keyboard-driven, Emacs-inspired bindings)
|
||||
- Syncs reliably (file-based, works with Syncthing/git)
|
||||
- Integrates with KDE (notifications, calendar, search)
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Replace Emacs for power users
|
||||
- Support every org-mode feature on day one
|
||||
- Build a "second brain" or "PKM" system
|
||||
- Cloud/SaaS anything
|
||||
|
||||
## Design Principles
|
||||
|
||||
**1. Files are truth**
|
||||
Org files on disk are the source of truth. No database. No proprietary format. Edit with Emacs, vim, or orkmode interchangeably.
|
||||
|
||||
**2. Parse properly**
|
||||
Use tree-sitter for a real AST. No regex hacks. Handle malformed files gracefully with error recovery.
|
||||
|
||||
**3. Keyboard-first**
|
||||
Every action reachable by keyboard. Mouse optional. Emacs-inspired bindings where sensible.
|
||||
|
||||
**4. Desktop-native**
|
||||
Use Qt/QML. Respect system themes. Integrate with KDE services (KRunner, Akonadi calendar, notifications).
|
||||
|
||||
**5. CLI for automation**
|
||||
The `ork` CLI enables scripting, agent integration, and headless workflows.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Qt/QML UI │
|
||||
│ (document view, agenda, capture, search) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ orkmode-core (Rust) │
|
||||
│ (document ops, queries, mutations, sync) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ org-parser (Rust) │
|
||||
│ (tree-sitter AST, incremental parsing) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ org-ast (Rust) │
|
||||
│ (type definitions, spans, serialization) │
|
||||
└─────────────────────────────────────────────────┘
|
||||
↑ ↑
|
||||
C FFI for Qt CLI (ork)
|
||||
```
|
||||
|
||||
## Milestones
|
||||
|
||||
### v0.1 — Parser & CLI (current)
|
||||
- [x] Tree-sitter parser integration
|
||||
- [x] Core AST types
|
||||
- [x] CLI for querying and basic mutations
|
||||
- [x] JSON output for tooling
|
||||
|
||||
### v0.2 — Read-only UI
|
||||
- [ ] Qt/QML document viewer
|
||||
- [ ] Headline folding/cycling
|
||||
- [ ] Syntax highlighting
|
||||
- [ ] Basic navigation
|
||||
|
||||
### v0.3 — Editing
|
||||
- [ ] Inline text editing
|
||||
- [ ] TODO state cycling
|
||||
- [ ] Tag editing
|
||||
- [ ] Property editing
|
||||
- [ ] Undo/redo
|
||||
|
||||
### v0.4 — Agenda
|
||||
- [ ] Agenda view (day/week)
|
||||
- [ ] TODO list view
|
||||
- [ ] Tag/property filtering
|
||||
- [ ] Scheduled/deadline display
|
||||
|
||||
### v0.5 — KDE Integration
|
||||
- [ ] KRunner plugin (search headlines)
|
||||
- [ ] System notifications for deadlines
|
||||
- [ ] Akonadi calendar integration
|
||||
- [ ] Global capture hotkey
|
||||
|
||||
### Future
|
||||
- Code block execution
|
||||
- Diagram rendering (mermaid, plantuml)
|
||||
- Table formula evaluation
|
||||
- Capture templates
|
||||
- Clock/time tracking
|
||||
- Mobile companion (Kirigami)
|
||||
|
||||
## Why Rust + Qt?
|
||||
|
||||
**Rust** for the parser/core:
|
||||
- Memory safety without GC
|
||||
- Excellent tree-sitter bindings
|
||||
- Easy C FFI for Qt integration
|
||||
- Fast incremental parsing
|
||||
|
||||
**Qt/QML** for the UI:
|
||||
- Native KDE integration
|
||||
- Powerful text rendering (QTextDocument)
|
||||
- Declarative UI with QML
|
||||
- Cross-platform if needed later
|
||||
|
||||
## Contributing
|
||||
|
||||
See AGENTS.md for AI-assisted development workflow.
|
||||
|
||||
The codebase is designed for agent collaboration:
|
||||
- CLI with JSON output for programmatic access
|
||||
- Clear module boundaries
|
||||
- Comprehensive type definitions
|
||||
Loading…
Reference in New Issue