From 84785967c31faee82fe445f5dd7778a7c325804d Mon Sep 17 00:00:00 2001 From: curo1305 Date: Mon, 18 May 2026 15:02:58 +0200 Subject: [PATCH] docs: restructure roadmap and add plugin branch workflow rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stages now reflect architectural milestones only (Memory DB → Vault → Skills → Daemon → Audit → Web UI). Plugins move to a perpetual catalog with per-plugin git branches. Always-push rule replaces the old no-push default. Adds Plugin Branches workflow section. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 106 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 61 insertions(+), 45 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7ea3aa2..1dcd267 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,8 +7,8 @@ a plugin/integration system (Stage 2+) and an encrypted vault (Stage 3+). ## Current Status -**Stage 2.1 — Plugin Framework: complete** (2026-05-17) -Next: Stage 2.2 (Nextcloud plugin) + Stage 2.3 (Email plugin) +**Stage 2 — Plugin Framework: complete** (2026-05-18) +Next: Stage 3 — Memory Database ## Project Roadmap @@ -16,15 +16,7 @@ Next: Stage 2.2 (Nextcloud plugin) + Stage 2.3 (Email plugin) Working `pyra` executable with provider setup wizard, streaming chat REPL, .md-based memory in `~/.pyra/memory/`, and hard security boundaries around the vault. -### Stage 2 — Plugin System & Integrations (IN PROGRESS) - -Pyra runs as a system daemon so messaging bots are always-on. All integrations are -standalone Python plugin scripts in `~/.pyra/plugins/` — not hardcoded in `src/pyra/`. -The AI uses tool-use (function calling) to invoke plugins; every execution requires -explicit user approval (y/N prompt). Plugin credentials are stored in the vault under -namespaced keys (`plugin:{name}:{key}`). - -#### Stage 2.1 — Plugin Framework ✅ COMPLETE +### Stage 2 — Plugin Framework ✅ COMPLETE - `src/pyra/plugins/` package: `base.py`, `loader.py`, `registry.py`, `executor.py`, `install.py` - `src/pyra/bundled_plugins/` — ships bundled plugin scripts with pyra - `src/pyra/daemon/` stub (CLI surface only) @@ -33,47 +25,60 @@ namespaced keys (`plugin:{name}:{key}`). - Chat session: AI tool-use loop (up to 10 iterations), approval gate, plugin slash commands - CLI: `pyra plugin list/install/enable/disable/setup`, `pyra daemon *` stubs -#### Stage 2.2 — Nextcloud Plugin (next) -Bundled plugin: `src/pyra/bundled_plugins/nextcloud/plugin.py` -CalDAV calendar, CardDAV contacts, WebDAV files. -Install deps: `uv pip install -e ".[nextcloud]"` +### Stage 3 — Memory Database (next) +Replace the flat `.md` file scanner with SQLite + FTS5 for fast full-text search. +Schema designed to add a vector column later for semantic (embedding-based) search. +Backwards-compatible: existing `.md` memory files are migrated on first run. -#### Stage 2.3 — Email Plugin (next, parallel with 2.2) -Bundled plugin: `src/pyra/bundled_plugins/email/plugin.py` -IMAP (Hotmail.de/Outlook), folder browsing, smart event extraction to calendar. -No new deps (uses stdlib imaplib). - -#### Stage 2.4 — Daemon + Messaging Bots -- `src/pyra/daemon/server.py` — asyncio event loop, plugin tasks, IPC socket -- `src/pyra/daemon/ipc.py` — Unix socket (chmod 600), line-delimited JSON protocol -- `src/pyra/daemon/service.py` — launchd plist (macOS) / systemd unit (Linux) -- Bundled plugins: `matrix_bot`, `telegram_bot`, `signal_bot` -- Security: sender allowlist, bcrypt passphrase challenge, rate limiting (20 msg/hr), - injection scanning on all incoming messages, tool approval over messaging (2-min timeout) - -#### Stage 2.5 — Infrastructure Plugins -Bundled plugins: `ssh_tool` (paramiko), `docker_tool` (docker SDK), -`kubernetes_tool` (kubectl subprocess), `service_manager` (systemctl/launchctl), -`smb_mount` (mount subprocess) - -#### Stage 2.6 — Cloud Storage Plugins -Bundled plugins: `gdrive` (Google OAuth2), `onedrive` (MSAL device flow), `dropbox_tool` - -### Stage 3 — Vault Encryption +### Stage 4 — Vault Encryption Encrypt `~/.pyra/vault/secrets/` using `age` (or GPG fallback). Pyra decrypts in memory at call time only — no plaintext ever written to disk after initial setup. Secret rotation support. Per-key passphrases optional. -### Stage 4 — Security Audit Sub-agent -A separate `pyra security audit` command that spins up a sandboxed AI agent whose sole -job is scanning for vulnerabilities: prompt injection in memory files, unexpected vault -access attempts in `security.log`, outdated dependency CVEs, permission drift on `~/.pyra/`. +### Stage 5 — Skills System +YAML-defined multi-plugin workflows with event triggers and AI-driven selection. +Skills compose existing plugin tools into automated pipelines with conditional branching +and human-in-the-loop decision points. + +### Stage 6 — Daemon + Messaging Bots +Always-on asyncio daemon, IPC socket, launchd/systemd service. Bundled bots: +`matrix_bot`, `telegram_bot`, `signal_bot`. Sender allowlist, bcrypt passphrase +challenge, rate limiting (20 msg/hr), injection scanning on all incoming messages, +tool approval over messaging (2-min timeout). + +### Stage 7 — Security Audit Sub-agent +`pyra security audit` — sandboxed agent scanning for prompt injection in memory files, +unexpected vault access in `security.log`, outdated CVEs, permission drift on `~/.pyra/`. Report written to `~/.pyra/security_audit.md` (not AI-readable during normal chat). -### Stage 5 — Web UI / Advanced Features +### Stage 8 — Web UI / Advanced Features Optional local web interface (FastAPI + HTMX or similar). Embedding-based memory search -(ChromaDB or sqlite-vec). Scheduled automations via cron-style plugin scheduling. -Multi-profile support (work vs personal). +via `sqlite-vec`. Multi-profile support (work vs personal). + +--- + +### Plugin Catalog (not stage-gated — ships when ready) + +Plugins are developed independently on `plugin/` branches and merged to `main` +only when complete. All integrations are standalone Python plugin scripts in +`~/.pyra/plugins/` — not hardcoded in `src/pyra/`. Plugin credentials are stored in +the vault under namespaced keys (`plugin:{name}:{key}`). + +| Plugin | Branch | Status | +|--------|--------|--------| +| `nextcloud` | `plugin/nextcloud` | planned | +| `email` | `plugin/email` | planned | +| `websearch` | `plugin/websearch` | planned | +| `headless_browser` | `plugin/headless_browser` | planned | +| `server_manager` | `plugin/server_manager` | planned | +| `matrix_bot` | `plugin/matrix_bot` | planned | +| `telegram_bot` | `plugin/telegram_bot` | planned | +| `signal_bot` | `plugin/signal_bot` | planned | +| `ssh_tool` | `plugin/ssh_tool` | planned | +| `docker_tool` | `plugin/docker_tool` | planned | +| `gdrive` | `plugin/gdrive` | planned | +| `onedrive` | `plugin/onedrive` | planned | +| `dropbox_tool` | `plugin/dropbox_tool` | planned | --- @@ -250,7 +255,18 @@ chore: description - **One commit per concern.** If a session touches a file for two different reasons (e.g. a bugfix and a cleanup), those are two separate commits — staged and committed independently, even if the file is the same. - Use the project commit convention: `feat(module):`, `fix(module):`, `test:`, `docs:`, `chore:` followed by a short description. - Always `git add` only the files relevant to that commit — never `git add .` blindly. -- Do **not** push unless explicitly asked to. +- **Always push after committing** — every commit goes to the remote Gitea repository immediately. + +### Plugin Branches + +- Every plugin is developed on its own branch: `plugin/` (e.g. `plugin/nextcloud`). +- A plugin branch is **never merged to `main` until the plugin is complete and tested**. +- `main` always contains only production-ready core source code (`src/pyra/` framework). +- If plugin work uncovers a bug in core Pyra code, fix it on a dedicated `fix/...` branch + off `main`, commit it to `main`, push, then rebase the plugin branch onto the updated `main`. +- Plugin branches may be pushed to remote for backup/review at any time. +- Do **not** merge plugin branches to `main` prematurely — a half-working plugin on `main` + is worse than one that isn't there yet. ### Avoid Duplication — Check the Inventory First