From 2d70b9fe0d80252eb920db27bf03712add787509 Mon Sep 17 00:00:00 2001 From: slhx agent Date: Sun, 21 Jun 2026 01:25:30 +0200 Subject: [PATCH] Set product and agent authority --- .gitignore | 9 +++++++++ AGENTS.md | 40 ++++++++++++++++++++++++++++++++++++++++ PRODUCT.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ REQUIREMENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 139 insertions(+) create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 PRODUCT.md create mode 100644 REQUIREMENTS.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5c03b1a --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +.zig-cache/ +zig-out/ +*.o +*.a +*.so +*.dylib +*.dll +*.exe +.DS_Store diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4a80176 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,40 @@ +# AGENTS.md + +## Authority + +- `PRODUCT.md` is the durable product orientation and product boundary for `mim`. +- `REQUIREMENTS.md` is the checkable requirement authority. Cite rows as `req: component/id` in future code, tests, and design notes when a change implements or protects that requirement. +- User instructions for the current task override these files when they conflict. + +## Product constraints + +`mim` is a protocol-first, mobile-first terminal code editor for iPhone SSH sessions. Preserve these constraints unless the user explicitly changes direction: + +- Server-side editor binary; no native iOS client by default. +- Terminal UI is the first thin client over the local session socket. See req: session/002 and req: session/003. +- No runtime config files, plugin system, package manager, hidden tool installers, or public feature-flag matrix. See req: governance/001, req: governance/002, and req: governance/004. +- Optimize for narrow viewports, QWERTZ/thumb input, and source patching. +- Treat keyboard layouts as explicit source-patched data backed by terminal traces, not ad-hoc conditionals. See req: input/004 and req: input/005. +- Common actions must avoid required Esc/Ctrl/Alt/function-key chords. See req: input/001. + +## Verification + +Before handing off requirement-affecting work, run the cheapest relevant checks: + +```sh +redgate list +redgate lint +redgate health +``` + +No implementation build/test command exists yet. When the Zig project is created, record the canonical build/test command here. + +## Work tracking + +Work is tracked in Gitea Issues at `git.tmk241.com/tmk241/mim`. + +- Parent outcome issues are labeled `northstar`. +- Executable child issues are labeled `slice` and link to their parent in the issue body. +- `ready-for-agent` means a child issue has enough scope, acceptance, and verification to start. +- Do not mirror issues into local files. +- Do not mutate tracker items unless the user or active goal grants exact issue/parent authority. diff --git a/PRODUCT.md b/PRODUCT.md new file mode 100644 index 0000000..00e9c57 --- /dev/null +++ b/PRODUCT.md @@ -0,0 +1,48 @@ +# PRODUCT.md + +## Product thesis + +`mim` is a mobile-first terminal code editor for SSH sessions from an iPhone. It runs as one server-side binary and is designed around narrow viewports, QWERTZ/thumb input, source patching, and real coding workflows rather than desktop Vim compatibility. + +## User job + +A capable developer SSHing into a machine from an iPhone needs to inspect a repo, edit code, navigate files, run builds/tests, read diagnostics, use LSP, check git state, and recover from mistakes without fighting full-keyboard assumptions. + +## Current alternative + +The user opens Vim or Neovim over SSH and tolerates bindings, ex commands, splits, plugin/config systems, and punctuation-heavy workflows designed for a desktop keyboard and wider screen. + +## Mechanism + +`mim` is protocol-first: the editor core owns buffers, selections, panels, jobs, diagnostics, and session state behind a local socket, while the terminal UI is the first thin client over that protocol. The UI provides a thumb-native leader-key command grammar, transient panels instead of desktop splits, UTF-8-aware editing, Tree-sitter highlighting, built-in LSP, git, file search/tree, project text search, build output, terminal, and optional Pi assistant integration. The socket path is exported in the session environment so trusted local tools like `pi` can inspect editor state or send explicit commands through the same small protocol. Defaults live in source and are changed by patching and rebuilding, not runtime config files. + +## Feature-complete boundary + +Feature-complete means good enough to be the default tool for real small-to-medium code changes over SSH from an iPhone. It includes: protocol/socket + `mimctl`, deterministic replay, UTF-8/cell-width-correct editing, mobile leader/symbol input, narrow transient panels, file tree/search, read-only git workbench, build/test output, terminal escape hatch, Tree-sitter, LSP diagnostics/navigation/actions, and local Pi/tool context through the socket. + +## Build shape + +Use layered source plus a few named build targets, not runtime config and not a public feature-flag matrix: + +- `mim-min`: core editor, socket, replay, TUI, mobile input, open/edit/save/quit. +- `mim-code`: `mim-min` plus files/search/git/build, Tree-sitter, and LSP. +- `mim-full`: `mim-code` plus Pi/local tool bridge. + +If the cuts are wrong, patch the source profile table and rebuild. + +## Refusals + +- No runtime config files, plugin system, package manager, or hidden installers. +- No obligation to preserve Vim default hotkeys or ex-command workflows. +- No desktop split-first UI on narrow terminals. +- No remote network control plane; the session socket is local and scoped. +- No native iOS/Android app, custom mobile keyboard, cloud sync, telemetry, collaborative editing, or tmux replacement until the SSH terminal editor proves it needs them. +- No public matrix of per-feature compile-time flags. + +## First useful slice + +Build the smallest replayable vertical slice: `zig build` produces `mim-min`; it opens a file, edits, saves, renders correctly in a narrow terminal, exposes a local socket, and can replay the session deterministically. + +## Proof / learning boundary + +The thesis is validated when the user chooses `mim` over their normal Neovim setup for small real fixes from an iPhone over SSH. diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md new file mode 100644 index 0000000..0917bc9 --- /dev/null +++ b/REQUIREMENTS.md @@ -0,0 +1,42 @@ +# REQUIREMENTS.md + +Rows are redgate TSV requirements: `ringidsummary [tag]`. + +## session + +0 001 `mim` SHALL run as a server-side terminal editor binary for SSH use. [core] +0 002 Each editor session SHALL expose a local socket path to trusted child/tool environments. [protocol] +0 003 The terminal UI SHALL act as a client of the session protocol, even when hosted in the same process. [protocol] +1 004 The session protocol SHALL support deterministic record/replay of input and state-changing commands. [test] + +## input + +0 001 Common editing and navigation commands SHALL be reachable without required Esc, Ctrl, Alt, or function keys. [mobile] +0 002 The Space leader SHALL expose a visible command rail when the user pauses after pressing it. [mobile] +1 003 Frequent coding punctuation SHALL have editor-native insertion paths for mobile keyboards. [mobile] +1 004 Input handling SHALL separate terminal key events, keyboard layout profiles, and editor command intents. [mobile] +2 005 Keyboard layout profiles SHALL be source-patched tables backed by recorded terminal traces, starting with iOS QWERTZ. [mobile] + +## ui + +0 001 Narrow terminals SHALL use transient panels instead of permanent desktop splits. [mobile] +1 002 Files, git, diagnostics, LSP, build, terminal, and Pi surfaces SHALL share one panel navigation model. [panels] + +## coding + +0 001 Buffer and rendering code SHALL preserve UTF-8 boundaries and terminal cell width semantics. [core] +1 002 Tree-sitter syntax highlighting SHALL be built in with source-patched language tables. [syntax] +1 003 LSP support SHALL be built in and spawn existing language servers without installing them. [lsp] + +## repo + +1 001 File search SHALL respect gitignore rules by default and provide an include-ignored path. [files] +1 002 Git support SHALL use explicit local git commands and avoid hidden mutating operations. [git] + +## governance + +0 001 Defaults SHALL be changed by patching source and rebuilding, not by runtime config files. [suckless] +0 002 `mim` SHALL not provide a plugin system or package manager. [suckless] +0 003 The session socket SHALL remain local and scoped to the running editor session. [protocol] +1 004 Build variants SHALL be named profiles over source layers, not a public matrix of per-feature flags. [suckless] +1 005 Capabilities excluded from a build profile SHALL fail with clear `not built in this profile` diagnostics. [suckless]