aphrodite-operations

name	aphrodite-operations
description	Operational patterns for working with aphrodite - engine compression handling, prefetch workflow, dual-mode rebuild, standalone repo sync.
version	1.0.0

Aphrodite Operations

Day-to-day operational patterns when working inside an aphrodite-compressed session.

Engine Compression + Prefetch Workflow

When the context engine compresses tool output into CCR markers, do NOT fight it by re-reading the same file with different offsets or tools. The engine compresses every read. Instead:

1. Plan reads ahead - use aphrodite_prefetch(paths=[...]) to read files and compress them. Markers are returned inline; use aphrodite_prefetch_status to track loading progress.
2. Retrieve, don't re-read - when you get <<<CCR:hash|type|size>>>, use aphrodite_retrieve(hash). Don't call read_file again with different offsets.
3. Write terminal output to files - command > /tmp/out.txt 2>&1 then prefetch/retrieve.
4. Do other work while waiting - dispatch prefetches, proceed with independent tasks, check aphrodite_prefetch_status for readiness.

Anti-pattern: calling read_file 3+ times on the same file with different offsets, each time getting a compressed marker. The engine compresses every read.

Dual-Mode Rebuild (_rebuild_handler)

The aphrodite_rebuild tool supports two modes:

• Dev mode: if Cargo.toml exists in a parent directory, builds from Rust source via cargo build --release.
• User mode: if no Cargo workspace found (standalone install), re-downloads the binary from GitHub Releases via _download_binary().

The _find_cargo_toml() helper walks up to 6 directories from the rebuild module to locate the workspace root.

Standalone Plugin Repo

End users install from Aphrodite-Hermes - a lightweight repo containing only Python plugin files (no binary, no monorepo). The binary is auto-downloaded from GitHub Releases on first session start.

After releasing in the monorepo, sync files to the standalone repo:

cp plugins/aphrodite/_core/config.py $STANDALONE/_core/config.py
cp plugins/aphrodite/plugin.yaml $STANDALONE/plugin.yaml
cp plugins/aphrodite/pyproject.toml $STANDALONE/pyproject.toml
cp plugins/aphrodite/__init__.py $STANDALONE/__init__.py
cp plugins/aphrodite/_hooks/rebuild.py $STANDALONE/_hooks/rebuild.py
cd $STANDALONE && git add -A && git commit -m "sync: v$NEW" && git push

--version Flag

The Rust binary's --version flag is only parsed by clap when Cli::parse() is called (no aphrodite.toml exists). Added early handling in main() to intercept --version/-V before config loading, ensuring it works regardless of config state.

Pitfalls

• _rebuild_handler repo path: from _hooks/rebuild.py, use _find_cargo_toml() which walks up, not hardcoded dirname() chains that break when directory structure changes.
• _check_binary_version() calls [BINARY, "--version"] - ensure the binary actually supports it (fixed in v0.8.6).
• Plugin-shipped skills are read-only via skill_manage - create profile-level skills for operational patterns.