jovaltus 0.5.1__tar.gz

jovaltus-0.5.1/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build-and-publish:
+    name: Build, check, and publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Run tests
+        run: uv run pytest --ignore=tests/integration/
+
+      - name: Type check (mypy)
+        run: uv run mypy src/jovaltus
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify pyproject version matches tag
+        run: |
+          PYPROJECT_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          if [ "$PYPROJECT_VERSION" != "$TAG_VERSION" ]; then
+            echo "❌ pyproject.toml version ($PYPROJECT_VERSION) != tag version ($TAG_VERSION)"
+            exit 1
+          fi
+          echo "✅ Version $PYPROJECT_VERSION matches tag v$TAG_VERSION"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "v${{ steps.version.outputs.version }}"
+          files: dist/*
+          draft: false
+          prerelease: false
+          generate_release_notes: true

jovaltus-0.5.1/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+
+# Virtual environment
+.venv/
+.uv/
+
+# OS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/
+
+# Eval results
+eval_results/

jovaltus-0.5.1/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+# Pre-commit hooks for Jovaltus
+# Order: ruff lint → mypy strict → ruff format
+#
+# ruff check   — lint verification (must pass)
+# mypy --strict — type checking (must pass)
+# ruff format  — auto-format (runs after all checks pass)
+#
+# Install: pre-commit install
+# Run all: pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      # ── Stage 1: Lint check (must pass) ──────────────────────────
+      - id: ruff
+        name: ruff check (lint)
+        args: [--fix]
+        types_or: [python, pyi]
+        description: "ruff check — lint validation (commit blocked on failure)"
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.16.1
+    hooks:
+      # ── Stage 2: Type check (must pass) ──────────────────────────
+      - id: mypy
+        name: mypy strict check
+        args: [--strict, --no-site-packages]
+        exclude: ^tests/
+        types_or: [python, pyi]
+        additional_dependencies: []
+        description: "mypy --strict — type checking (commit blocked on failure)"
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      # ── Stage 3: Auto-format (runs after all checks pass) ────────
+      - id: ruff-format
+        name: ruff format (auto-format)
+        types_or: [python, pyi]
+        description: "ruff format — auto-format staged files"

jovaltus-0.5.1/AGENTS.md

@@ -0,0 +1,86 @@
+# Jovaltus — Hermes Plugin Agent Mode
+
+## Build & Test
+
+- `uv run pytest -v` — Run full test suite (68 tests, ~3.6s)
+- `uv run ruff check .` — Lint (zero warnings)
+- `uv run ruff format --check .` — Format check (auto-format with `ruff format .`)
+- `uv run mypy --strict --no-site-packages *.py` — Type check (zero errors)
+- All tests pass before commit. No lint, format, or type warnings.
+
+## Pre-commit Hooks (v0.5.0)
+
+Three hooks run on every `git commit` in this order:
+
+1. **ruff check — lint** (must pass, blocks commit on failure)
+2. **mypy --strict — type check** (must pass, blocks commit on failure)
+3. **ruff format — auto-format** (reformats staged files after checks pass)
+
+Install: `pre-commit install` (already done)
+Run manually: `pre-commit run --all-files`
+
+## Project Structure
+
+- `plugin.yaml` + `__init__.py` — Hermes plugin entry (root dir IS the package)
+- `tools.py` — Three tool handler factories (implement, verify, simplify)
+  - Dual-mode: task_id for stateful pipeline, before/after for stateless commit mode
+- `schemas.py` — Tool JSON schemas (what the LLM sees)
+  - verify/simplify schemas include optional before/after params
+- `state.py` — Thread-safe in-memory task state
+- `git_utils.py` — Git subprocess wrappers (list args, no shell=True)
+  - New in v0.2.0: remote update utilities (fetch, pull, ahead/behind check)
+- `SOUL.md` — Bundled agent identity file; applied to profile via `setup`
+- `prompts/*.md` — Subagent system prompts (editable without touching Python)
+- `skills/jovaltus-agent/SKILL.md` — Agent Mode workflow definition
+- `tests/` — 68 pytest tests across 7 test files + conftest.py
+
+## Key Constraints
+
+- All handler functions must accept `(args: dict, **kwargs)` and return JSON string
+- All git commands use list args (no `shell=True`)
+- State uses `threading.Lock` for thread safety
+- Handler factories capture `ctx` in `register()` — closures, not class instances
+- Prompt files loaded at factory creation time, not at handler invocation
+- Plugin skills are namespaced (`jovaltus:jovaltus-agent`), loaded via `skill_view()`
+
+## Documentation
+
+- `docs/features/` — User-visible behaviour in BDD format (Given/When/Then)
+- `docs/architecture/` — Module boundaries and design principles
+- `docs/principles/` — Code conventions with source evidence
+- Every doc claim traces to source file + line range. `[INFERRED]` marks unverifiable claims.
+
+## CLI Commands (v0.3.0)
+
+- `hermes jovaltus setup` — Create profile, install bundled skills, apply SOUL.md
+  - Interactive prompts with TTY detection (falls back to safe defaults)
+  - Creates `jovaltus-agent` profile if missing
+  - Installs bundled skills to global skills directory
+  - Optionally writes `SOUL.md` to profile directory
+  - Persists installation state to `~/.hermes/jovaltus_state.json`
+- `hermes jovaltus status` — Show installation state per profile
+  - Displays profile name, installation mode, and last updated timestamp
+- `hermes jovaltus update --check` — Check for remote updates against origin
+- `hermes jovaltus update` — Pull latest changes
+  - Detects and removes stale bundled skills (interactive)
+  - Refreshes all bundled skills
+  - Re-applies SOUL.md where previously installed
+  - Refreshes timestamps
+
+## Workflow
+
+### Stateful Pipeline (task_id mode)
+
+1. User confirms requirements (Phase 0)
+2. Main agent calls `jovaltus_implement` → handler spawns implement subagent
+3. Main agent calls `jovaltus_verify(task_id)` → handler spawns verification subagent
+4. Main agent calls `jovaltus_simplify(task_id)` → handler spawns simplifier subagent
+
+### Stateless Commit Mode
+
+For verify and simplify tools, pass `before` (and optionally `after`) commit hashes
+instead of `task_id` to skip pipeline state and operate on any commit range:
+- `jovaltus_verify(before=<hash>)` → verifies before..HEAD
+- `jovaltus_verify(before=<hash>, after=<hash>)` → verifies exact range
+- `jovaltus_simplify(before=<hash>)` → simplifies before..HEAD
+- `task_id` and `before` are mutually exclusive

jovaltus-0.5.1/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to the **Jovaltus** Hermes plugin are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## v0.3.2 — 2026-07-11
+
+### Changed
+
+- **Architecture**: plugin CLI commands registered from the default profile (like caelterra) instead of requiring a dedicated profile — `hermes jovaltus setup/status/update` work from any terminal after `hermes plugins install`
+- **`setup` flow simplified**: removed `_link_plugin_to_profile()` — plugin stays in default profile, no profile-plugin linking needed
+
+---
+
+## v0.3.1 — 2026-07-11
+
+### Added
+
+- **Auto-link plugin to profile on `setup`** (`_link_plugin_to_profile()`) — detects the installed plugin in either global `~/.hermes/plugins/` or profile plugins dir and ensures it's accessible from `jovaltus-agent` profile
+- **Better error message on `setup`** — suggests installing from outside the repo if plugin isn't found
+
+---
+
+## v0.3.0 — 2026-07-11
+
+### Added
+
+- **State management** (`~/.hermes/jovaltus_state.json`) — JSON file tracking installation mode (Skills only vs Skills + SOUL.md) and last updated timestamp per profile
+- **CLI: `status`** — shows Jovaltus installation status for the jovaltus-agent profile
+- **Interactive prompts** (`_prompt_yes_no()`) with TTY detection — falls back to defaults in non-interactive environments
+- **Profile sync on `update`** — after pulling latest code, refreshes SOUL.md and timestamps for tracked profiles, even when already up to date (handles state drift)
+- **Stale skill detection** — compares `~/.hermes/skills/` against bundled skills after update, interactively removes orphaned skills
+- **TypedDict return types** in `git_utils.py` — `FetchResult`, `AheadBehind`, `PullResult`, `CommitResult`
+- **`_is_skill_dir()` helper** — factorised directory check pattern
+- **`_get_bundled_skill_names()`** — scan bundled skills
+- **`_remove_installed_skill()` / `_remove_stale_skills()`** — stale skill cleanup workflow
+
+### Changed
+
+- `setup` now uses interactive prompts for skill and SOUL.md installation (defaults: skills=yes, SOUL.md=yes, overwrite=no)
+- `setup` persists installation state to `~/.hermes/jovaltus_state.json`
+- `update` now re-applies SOUL.md for tracked profiles, removes stale skills, and refreshes all bundled skills
+- `update` refreshes skills and SOUL.md even when already up to date (fixes state drift)
+- `_install_bundled_skill()` renamed to `_install_bundled_skills()` — handles multiple bundled skills
+- `git_utils.py` return types migrated to TypedDict for better type safety
+
+### Added (tests)
+
+- 8 new tests covering state management (load/save/set), profile sync (SOUL.md, skills-only, missing profiles), and stale skill detection
+
+---
+
+## v0.2.0 — 2026-07-09
+
+### Added
+
+- Profile + SOUL.md setup via `hermes jovaltus setup`
+- Update checking via `hermes jovaltus update --check`/`hermes jovaltus update`
+- Git utilities for remote operations (fetch, pull, ahead/behind check)
+- Bundled skill registration
+
+---
+
+## v0.1.0 — 2026-07-09
+
+Initial release. Jovaltus Agent Mode — automated development pipeline (Plan → Implement → Verify → Simplify) as a Hermes plugin.

jovaltus-0.5.1/CLAUDE.md

@@ -0,0 +1,41 @@
+# Jovaltus — Hermes Plugin Agent Mode
+
+## Build & Test
+
+- `uv run pytest -v` — Run full test suite (25 tests, ~1.2s)
+- `uv run python3 -m py_compile *.py tests/*.py` — Type/syntax check
+- All tests pass before commit. No lint warnings.
+
+## Project Structure
+
+- `plugin.yaml` + `__init__.py` — Hermes plugin entry (root dir IS the package)
+- `tools.py` — Three tool handler factories (implement, verify, simplify)
+- `schemas.py` — Tool JSON schemas (what the LLM sees)
+- `state.py` — Thread-safe in-memory task state
+- `git_utils.py` — Git subprocess wrappers (list args, no shell=True)
+- `prompts/*.md` — Subagent system prompts (editable without touching Python)
+- `skills/jovaltus-agent/SKILL.md` — Agent Mode workflow definition
+- `tests/` — 25 pytest tests across 4 test files + conftest.py
+
+## Key Constraints
+
+- All handler functions must accept `(args: dict, **kwargs)` and return JSON string
+- All git commands use list args (no `shell=True`)
+- State uses `threading.Lock` for thread safety
+- Handler factories capture `ctx` in `register()` — closures, not class instances
+- Prompt files loaded at factory creation time, not at handler invocation
+- Plugin skills are namespaced (`jovaltus:jovaltus-agent`), loaded via `skill_view()`
+
+## Documentation
+
+- `docs/features/` — User-visible behaviour in BDD format (Given/When/Then)
+- `docs/architecture/` — Module boundaries and design principles
+- `docs/principles/` — Code conventions with source evidence
+- Every doc claim traces to source file + line range. `[INFERRED]` marks unverifiable claims.
+
+## Workflow
+
+1. User confirms requirements (Phase 0)
+2. Main agent calls `jovaltus_implement` → handler spawns implement subagent
+3. Main agent calls `jovaltus_verify(task_id)` → handler spawns verification subagent
+4. Main agent calls `jovaltus_simplify(task_id)` → handler spawns simplifier subagent

jovaltus-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin (Sunny Lai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jovaltus-0.5.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: jovaltus
+Version: 0.5.1
+Summary: Jovaltus Agent Mode — Hermes plugin for automated development pipeline
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fabricium>=0.1.1

jovaltus-0.5.1/README.md

@@ -0,0 +1,295 @@
+# Jovaltus — Hermes Plugin for Agent Mode
+
+> **Jovaltus** is a Hermes Agent plugin that transforms the main agent into an intelligent development orchestrator. Designed for quick bug fixes and small-to-medium features, it provides a structured four-phase pipeline — Plan → Implement → Verify & Fix → Simplify — while keeping the workflow invisible to the user.
+
+---
+
+## Overview
+
+Jovaltus takes a single user request and runs it through an automated quality pipeline. The user only participates in Phase 0 (requirement clarification). Everything else — implementation, adversarial verification, code simplification — is handled autonomously by subagents.
+
+```
+User Request
+    │
+    ├── Phase 0: Planning (Main Agent)
+    │   Round-based clarification → Checklist → User confirmation
+    │
+    ├── Phase 1: Implement (Subagent)
+    │   Writes code. Reports BLOCKED if stuck.
+    │
+    ├── Phase 2: Verify & Fix (Subagent)
+    │   Adversarial testing. Finds problems, fixes them, repeats until clean.
+    │
+    └── Phase 3: Simplify (Subagent)
+        Structural cleanup. No behaviour changes.
+```
+
+---
+
+## Architecture
+
+### Three-Layer Design
+
+| Layer | What It Does | Why |
+|-------|-------------|-----|
+| **Skill** (documents) | Describes what each phase should do. No tool names. | LLM reads this + tool schemas, figures out the flow itself. |
+| **Tool Handler** (thin Python) | Records state, reads system prompt from file, spawns subagent via `ctx.dispatch_tool("delegate_task", ...)`. Returns immediately. | One tool call per phase. No manual `delegate_task` from the main agent. Prompt lives in its own file. |
+| **Subagent prompt** (markdown) | The system prompt injected into each subagent. Lives in `prompts/*.md`. | Editable without touching Python. Each subagent reads its own prompt. |
+
+### One Tool Call Per Phase
+
+The main agent calls ONE tool per phase. That tool handler:
+
+1. Records state (git hash, task_id)
+2. Reads the system prompt from `prompts/<phase>.md`
+3. Spawns a subagent via `ctx.dispatch_tool("delegate_task", ...)` with the prompt as goal
+4. Returns immediately — the subagent runs in the background
+
+The subagent self-commits when done. Its result arrives as a message
+the main agent reads to decide the next phase.
+
+---
+
+## The Four Phases
+
+### Phase 0: Planning (Main Agent)
+
+The only phase the user interacts with.
+
+```
+User: "Build a login page"
+    │
+    ├── Step 1: Round-based clarification (1-3 questions per round, multiple choice)
+    │   Scope → Business flow → Constraints → Business value
+    │
+    ├── Step 2: Decompose into a business requirement checklist
+    │
+    ├── Step 3: Web search for latest information (avoids knowledge cut-off)
+    │
+    └── Step 4: User confirms the plan
+        "Don't start implementing until the user says yes."
+```
+
+### Phase 1: Implement
+
+```
+Main agent calls jovaltus_implement
+    └─ Handler:
+        1. Records start_hash, creates task
+        2. Reads prompts/implement.md
+        3. ctx.dispatch_tool("delegate_task", {
+               goal: implement prompt,
+               toolsets: [terminal, file]
+           })
+        4. Returns {task_id, start_hash}
+
+Subagent works in background:
+    • Reads context from handler
+    • Writes code (full read/write access)
+    • Does NOT verify, does NOT simplify
+    • Reports BLOCKED if genuinely stuck
+    • git add -A && git commit when done
+```
+
+**Tool permissions**: `terminal`, `file` (full read/write).  
+**Red lines**: ❌ No touching irrelevant files. ❌ No self-verification. ❌ No self-simplification.
+
+### Phase 2: Verify & Fix
+
+```
+Main agent calls jovaltus_verify(task_id)
+    └─ Handler:
+        1. Looks up task, computes diff (start_hash → HEAD)
+        2. Reads prompts/verify.md
+        3. ctx.dispatch_tool("delegate_task", {
+               goal: verify prompt,
+               context: diff output,
+               toolsets: [terminal, file]
+           })
+        4. Returns {task_id, diff_summary}
+
+Subagent works in background (with write access):
+    • Runs the code
+    • Tries to break it (adversarial mindset)
+    • Finds bugs → fixes them directly → re-verifies
+    • Loops until all tests pass
+    • git add -A && git commit when done
+```
+
+**Mindset**: Adversarial. Not "does it work?" but "how can I break this?"  
+**Write access**: The subagent can fix what it finds — no read-only reporting. This is the Fable 5 closed-loop model.
+
+### Phase 3: Simplify
+
+```
+Main agent calls jovaltus_simplify(task_id)
+    └─ Handler:
+        1. Looks up task, computes clean diff
+        2. Reads prompts/simplify.md
+        3. ctx.dispatch_tool("delegate_task", {
+               goal: simplify prompt,
+               context: clean diff,
+               toolsets: [terminal, file]
+           })
+        4. Returns {task_id, diff_summary}
+
+Subagent works in background:
+    • No behaviour changes
+    • Structural priorities: extract duplicates > delete dead code > flatten nesting > improve naming
+    • Mandatory grep evidence before deleting anything
+    • git add -A && git commit when done
+```
+
+**Value hierarchy**: Extract duplicates → Delete dead code → Flatten nesting → Improve naming.  
+**Safety**: Every deletion requires grep evidence. Behaviour must be strictly preserved.
+
+---
+
+## Installation and Usage
+
+### Step 1: Install the Plugin
+
+```bash
+pip install jovaltus && hermes plugins enable jovaltus
+```
+
+> `fabricium` 會作為依賴自動安裝。
+
+### Step 2: Setup
+
+```bash
+# 一鍵安裝 — 互動式 prompts (TTY detection, 非互動環境用預設值)
+hermes jovaltus setup
+```
+
+Setup 會：
+
+1. 建立 `jovaltus-agent` profile（如不存在）
+2. 安裝 bundled skills 到 global skills 目錄
+3. 寫入 SOUL.md（可選，預設 yes）
+4. 記錄安裝狀態至 `~/.hermes/jovaltus_state.json`
+
+### Step 3: 啟用 Plugin
+
+```bash
+hermes plugins enable jovaltus
+```
+
+### Step 4: 建立 Profile
+
+```bash
+# 一鍵建立 jovaltus-agent profile
+hermes jovaltus setup
+```
+
+> Profile 建立後，編輯 `~/.hermes/profiles/jovaltus-agent/config.yaml`，
+> 確認 model 設定與 root config 一致（若無則複製貼上）：
+> ```yaml
+> model:
+>   default: deepseek-v4-flash
+>   provider: deepseek
+> ```
+> 若不確定 root 設定，執行：`grep -A2 "^model:" ~/.hermes/config.yaml`
+
+### Step 4: 連結 Plugin 到 Profile
+
+```bash
+# 將 plugin 原始碼連結到 profile 的 plugins 目錄
+ln -s /Users/tszkinlai/uniterra/jovaltus ~/.hermes/profiles/jovaltus-agent/plugins/jovaltus
+```
+
+> **為什麼需要這步？** 當使用 `hermes -p <profile>` 啟動 session 時，
+> Hermes 只掃描 profile 目錄底下的 plugins，不會掃描全域 `~/.hermes/plugins/`。
+> 因此 plugin 必須存在於 profile 的 plugins 子目錄中才會被載入。
+
+### Step 5: 確認安裝
+
+```bash
+# 啟動 session 並測試工具是否可用
+hermes -p jovaltus-agent
+
+# 在 session 中輸入：
+# 「list all tools whose name starts with jovaltus」
+#
+# 應該看到：
+# - jovaltus_implement
+# - jovaltus_verify
+# - jovaltus_simplify
+```
+
+### 日常使用
+
+```bash
+# 查詢安裝狀態
+hermes jovaltus status
+
+# 檢查更新
+hermes jovaltus update --check
+
+# 套用更新（自動清理過時 skill、同步 SOUL.md）
+hermes jovaltus update
+
+# 在任何專案目錄下啟動
+cd /projects/app-alpha
+hermes -p jovaltus-agent
+
+# Profile 不綁定目錄 — 同一 profile 可在不同 project 使用
+cd /projects/app-beta
+hermes -p jovaltus-agent
+```
+
+### 疑難排解
+
+| 問題 | 解法 |
+|------|------|
+| `Unknown toolset 'jovaltus'` | Plugin 未正確載入。檢查 Step 4 的 symlink 是否存在 |
+| 工具列表沒有 `jovaltus_*` | 確認 profile config 有 `plugins.enabled: [jovaltus]` |
+| `No inference provider configured` | Profile config 缺少 model 設定。參考 Step 3 補上 |
+| 401 Authentication Error | 確認 profile 的 `.env` 有 API key。複製 root 的：`grep DEEPSEEK ~/.hermes/.env >> ~/.hermes/profiles/jovaltus-agent/.env` |
+
+---
+
+## Project Structure
+
+```
+jovaltus/
+├── README.md              # Proposal + usage
+├── plugin.yaml            # Hermes plugin manifest
+├── __init__.py            # register() — creates handler closures, mounts everything
+├── schemas.py             # Tool JSON schemas (what the LLM sees)
+├── tools.py               # Tool handler factories (capture ctx, spawn subagents)
+├── state.py               # In-memory task state
+├── git_utils.py           # Git subprocess wrappers
+├── skills/
+│   └── jovaltus-agent/
+│       └── SKILL.md       # Agent Mode workflow (no tool names)
+└── prompts/
+    ├── implement.md       # Implement subagent system prompt
+    ├── verify.md          # Verification subagent system prompt
+    └── simplify.md        # Simplifier subagent system prompt
+```
+
+---
+
+## Technical Decisions
+
+| Aspect | Decision |
+|--------|----------|
+| **Profile** | `jovaltus-agent`, separate from any other mode |
+| **Plugin sharing** | GitHub repo + `hermes plugins install` |
+| **Profile init** | Plugin provides `hermes jovaltus setup` CLI command (`ctx.register_cli_command`) |
+| **Profile binding** | Not directory-bound — same profile works across projects |
+| **Pipeline control** | Skill document guides main agent. Each phase = one tool call. |
+| **Git tracking** | Tool handler records start_hash. Subagent self-commits when done. |
+| **Subagent spawning** | Tool handler calls `ctx.dispatch_tool("delegate_task", ...)` with prompt from file |
+| **System prompts** | Stored in `prompts/*.md`, read by handler at call time |
+| **Verify loop** | Verification subagent has write access and runs a self-contained loop |
+| **Simplify input** | Handler computes clean diff (start vs HEAD, no intermediate commits) |
+| **Skill style** | Describes *what* to do, never names tools other than the three plugin tools |
+| **Plugin skills** | Read-only, namespaced (`"jovaltus:jovaltus-agent"`), loaded via `skill_view()` |
+
+---
+
+## License
+
+MIT