From f697a4418da923781ecc65c8274254568839df2a Mon Sep 17 00:00:00 2001 From: Sylvain Gougouzian Date: Mon, 13 Jul 2026 11:05:26 +0200 Subject: [PATCH] docs: add README and AGENTS.md --- AGENTS.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 298 insertions(+) create mode 100644 AGENTS.md create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a09ee4b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,149 @@ +# Obsidian Vault + OpenSpec Workflow + +## Available Skills + +Load these when working with Obsidian or OpenSpec: +- `obsidian-markdown` — OFM, wikilinks, embeds, callouts, frontmatter +- `obsidian-cli` — Interact with vault, notes, tasks, plugins +- `obsidian-bases` — .base files, views, filters, formulas +- `json-canvas` — .canvas files, nodes, edges +- `defuddle` — Clean markdown from URLs +- `openspec-propose` — Create changes with proposal/design/tasks +- `openspec-apply-change` — Implement tasks from a change +- `openspec-archive-change` — Archive completed changes + +## Vault Structure + +| Folder | Content | +|--------|---------| +| `Context/` | Profile, Business, ICP, Goals, Projects | +| `Daily/` | `YYYY-MM-DD.md` — one note per day | +| `Intelligence/` | Research, decisions, architecture | +| `Resources/` | Templates, patterns, snippets | +| `Inbox.md` | Unsorted ideas | +| `openspec/changes/` | OpenSpec changes | +| `openspec/specs/` | OpenSpec specifications | + +## Required Frontmatter + +```yaml +--- +date: YYYY-MM-DD +tags: [] +type: note | project | context | daily | research | resource +status: draft | active | archive +--- +``` + +## Wiki Links + +- Link: `[[Note Name]]` +- Embed: `![[Note#Section]]` +- Label: `[[path|Display Text]]` + +## OpenSpec Workflow + +For each proposal, **create a dedicated branch** before implementation starts. + +1. Propose: `openspec new change ` or use `openspec-propose` skill → then `/git-propose` +2. Design: Create `proposal.md`, `design.md`, `tasks.md` +3. Implement: Use `openspec-apply-change` skill → then `/git-commit` after each task +4. Archive: Use `openspec-archive-change` skill → then `/git-archive` + +## Vault Rules + +- Update `Daily/YYYY-MM-DD.md` after every action +- Every note needs at least one wiki link +- Rejected ideas → `status: archive`, never delete + + +## Vault Growth + +- Well-reasoned technical/business decision → `Intelligence/` +- Reusable pattern/snippet → `Resources/` +- Technical project → its own `CLAUDE.md` (the vault connects them) + +## Reminders + +- Vault = thought journal, not a record of final decisions +- Rejected ideas = `status: archive`, never deleted + +## Token Optimization +- Responses: short, direct, no preamble, no summary +- No "I'll now...", no "Great!", no redundant explanations +- Code only when asked; prefer inline edits over full file rewrites +- If unsure, ask one short question — don't guess and over-generate + +## File Access — NEVER READ +- All paths matching .gitignore patterns (see below) +- node_modules/, .venv/, venv/, env/, __pycache__/, target/, dist/, build/ +- *.lock files (package-lock.json, yarn.lock, Cargo.lock, poetry.lock, uv.lock) +- *.log, *.tmp, *.cache +- .git/ internals +- coverage/, .nyc_output/, htmlcov/ +- .next/, .nuxt/, .svelte-kit/, out/ +- *.min.js, *.min.css, *.map +- __generated__/, generated/, vendor/ +- .terraform/, .pulumi/ +- *.egg-info/, .eggs/, dist-info/ + +## Common .gitignore to create if missing +If no .gitignore exists, create one with: +``` +# Dependencies +node_modules/ +.venv/ +venv/ +env/ + +# Build outputs +dist/ +build/ +target/ +out/ +*.egg-info/ + +# Cache +__pycache__/ +.cache/ +.next/ +.nuxt/ +coverage/ +htmlcov/ +.nyc_output/ + +# Locks (read-only, skip) +# package-lock.json ← keep for npm ci +# Cargo.lock ← keep for bins + +# Env & secrets +.env +.env.* +!.env.example + +# IDE +.idea/ +.vscode/ +*.swp + +# OS +.DS_Store +Thumbs.db +``` + +## Exploration Strategy +1. Read only: README, package.json / Cargo.toml / pyproject.toml / go.mod +2. Then: src/ or lib/ entry points +3. Ask before reading more than 5 files in one go + +## Response Format +- Bug fix → show only the changed lines + brief reason +- New feature → minimal working implementation, no scaffolding unless asked +- Explanation → 3 lines max unless more depth is explicitly requested + + +## Hard Rules + +1. **Daily first** — Update `Daily/YYYY-MM-DD.md` after every action (summary, decisions, links to affected notes) +2. **No orphans** — Every note has at least one wiki link `[[incoming or outgoing]]` +3. **Capture everything** — Ideas, decisions, and rejections in `Inbox.md` or a dedicated note diff --git a/README.md b/README.md new file mode 100644 index 0000000..ccc3184 --- /dev/null +++ b/README.md @@ -0,0 +1,149 @@ +# Paikal + +A full-screen TUI CLI agent powered by local LLMs via [Docker Model Runner](https://docs.docker.com/desktop/features/model-runner/). + +``` +paikea +``` + +## Features + +- **Full-screen TUI** — header, timeline, thinking pane, result pane, prompt input, status bar +- **Local LLMs** — streams via Docker Model Runner (OpenAI-compatible API at `localhost:12434`) +- **Model switching** — Tab / Shift+Tab cycles through available models, or `M` to pick from a list +- **Thinking support** — detects and renders chain-of-thought from Qwen3, DeepSeek-R1, OpenAI o-series +- **OpenSpec integration** — detects propose → plan → design → tasks → apply → archive workflow +- **Skills & rules** — loads from bundled defaults + `.paikea/` + `.claude/` project overrides +- **Session persistence** — saves conversation history to `.paikea/sessions/` +- **Project scaffolding** — `paikea init` creates a full dev environment with devcontainer, OpenSpec, vault, and Diátaxis docs +- **Diátaxis docs** — `paikea doc` generates tutorials, how-to, reference, and explanation documentation +- **Single binary** — compiles to a self-contained executable via `bun build --compile` + +## Prerequisites + +- [Bun](https://bun.sh) (v1.3+) +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) with Model Runner enabled +- At least one model pulled (e.g. `ai/qwen3`) + +## Install + +```bash +bun install +``` + +## Development + +```bash +bun run dev # run in development mode +bun run build # compile to dist/paikea +bun run check # typecheck + lint + test +bun run lint # biome check +bun run lint:fix # biome check --write +bun run format # biome format --write +bun run test # run tests +``` + +## Usage + +### Interactive TUI + +```bash +paikea +``` + +#### Keyboard shortcuts + +| Key | Action | +|-----|--------| +| `Enter` | Submit prompt | +| `Escape` | Cancel generation (while streaming) · Quit (when idle) | +| `Ctrl+C` / `Ctrl+D` | Cancel generation, or quit | +| `Tab` | Accept suggestion, or next model | +| `Shift+Tab` | Previous model | +| `↑` | Open toolbar | +| `:` | Open command palette | +| `←/→` | Move cursor in prompt | +| `Home`/`End` · `Ctrl+A`/`Ctrl+E` | Jump to start/end of prompt | +| `Ctrl+W` / `Ctrl+U` | Delete previous word / to line start | +| `PageUp`/`PageDown` · `Shift+↑`/`Shift+↓` | Scroll the response | + +### Initialize a project + +```bash +paikea init +``` + +Creates a new directory with: +- **Devcontainer** — Dockerfile + docker-compose.yml + devcontainer.json +- **OpenSpec** — changes/, specs/ directories +- **Vault** — Context/, Daily/, Intelligence/, Resources/ for Obsidian +- **Skills** — obsidian-cli, obsidian-markdown, defuddle, openspec-*, json-canvas +- **Rules** — TypeScript strict, conventional commits, devcontainer, testing, obsidian, dev practices +- **AGENTS.md** — workflow rules and vault conventions +- **Docs** — Diátaxis documentation scaffold + +### Generate documentation + +```bash +paikea doc # generate docs in ./docs +paikea doc -o ./my-docs # custom output directory +paikea doc -s src # scope to src/ only +``` + +## Architecture + +``` +src/ +├── cli/ +│ ├── index.ts # CLI entry (clipse) +│ ├── commands/ +│ │ ├── init.ts # paikea init +│ │ ├── doc.ts # paikea doc +│ │ ├── run.ts # paikea (TUI) +│ │ └── tui-main.ts # main TUI loop + keyboard handling +│ └── prompts/ +│ └── stack-questions.ts # init wizard (language, framework, db, services) +├── components/ +│ ├── header.ts # top bar +│ ├── timeline.ts # message history +│ ├── thinking-pane.ts # chain-of-thought display +│ ├── result-pane.ts # LLM response rendering +│ ├── prompt-input.ts # text input area +│ └── status-bar.ts # bottom bar (model, skills, openspec steps) +├── renderer/ +│ ├── terminal.ts # raw mode, event stream, cursor +│ ├── layout.ts # 6-zone responsive layout +│ ├── theme.ts # colors, symbols, spacing +│ └── draw.ts # box drawing, text wrapping +├── services/ +│ ├── dmr-client.ts # Docker Model Runner API (SSE streaming) +│ ├── model-registry.ts # model fetching + cycling +│ ├── thinking-parser.ts # thinking model detection +│ ├── openspec-hook.ts # OpenSpec step detection +│ ├── devcontainer.ts # Dockerfile/compose/devcontainer generation +│ ├── project-scaffold.ts # directory + file scaffolding +│ └── doc-generator.ts # Diátaxis doc generation +├── skills/ +│ └── registry.ts # loads SKILL.md from subdirectories +├── rules/ +│ └── registry.ts # loads *.md rule files +├── state/ +│ ├── store.ts # reactive state store +│ └── session.ts # session save/load +└── types.ts # shared types +``` + +## Stack + +| Layer | Library | +|-------|---------| +| CLI parser | [clipse](https://github.com/gouz/clipse) | +| Interactive prompts | [@clack/prompts](https://github.com/bombshell-dev/clack) | +| TUI rendering | [@hexie/tui](https://github.com/anomalyco/hexie) | +| LLM backend | [Docker Model Runner](https://docs.docker.com/desktop/features/model-runner/) | +| Linter/formatter | [Biome](https://biomejs.dev) | +| Runtime | [Bun](https://bun.sh) | + +## License + +MIT -- 2.51.2