aphrodite-development-lessons

name	aphrodite-development-lessons
description	Critical development pitfalls for Aphrodite - auto-expand, env_passthrough, plugin symlink, dual-store pattern, release notes, and session setup checklist.
version	1.1.0
related_skills	["aphrodite-dev-workflow","aphrodite-release-workflow","aphrodite-hook-reference","aphrodite-tool-guide"]

Aphrodite Development Lessons

Critical pitfalls and fixes learned across 100+ releases.

Auto-Expand: The Critical Switch

When auto-expand is OFF, every file read gets compressed into <<<CCR:hash>>> markers. The LLM sees markers instead of content, creating a cascading failure loop where no debugging is possible.

Fix: enable auto-expand in aphrodite.toml:

[compression]
auto_expand = true
auto_expand_limit = 51200

Or per-session: APHRODITE_AUTO_EXPAND=1 hermes --profile dev-aphrodite

When you see a CCR marker: use aphrodite_retrieve(hash) - DO NOT try alternative tools. They'll also produce CCR markers.

Plugin Symlink → Repo

The plugin must symlink directly to the repo for instant code updates:

~/.hermes/profiles/dev-aphrodite/plugins/aphrodite → /path/to/Aphrodite/plugins/aphrodite

Without this, code changes in the repo don't reach the running plugin. Background workers get stale code.

env_passthrough - API Key Blocking

Empty env_passthrough: [] blocks APHRODITE_API_KEY from reaching proxy subprocesses. Proxies silently fail to start.

Fix: hermes config set terminal.env_passthrough '["APHRODITE_API_KEY","PATH","HOME"]' --profile dev-aphrodite

Release Notes - Use the Template

See .hermes/RELEASE-TEMPLATE.md for the canonical template. Every release MUST include: Summary, Changes, Infrastructure, What Ships, and Links.

Anti-pattern (DO NOT): bare compare link with zero description. 30+ releases (v0.8.13-v0.8.43) ship with only a compare link.

NEVER use inline backtick-quoted text with gh release create --notes. The shell interprets backticks as command substitution. Use --notes-file with a heredoc:

cat > /tmp/notes.md << 'EOF'
**[Compare vX.Y.Z...vX.Y.Z](https://github.com/PlayForm/Aphrodite/compare/vX.Y.Z...vX.Y.Z)**

## Aphrodite vX.Y.Z 💋 Plugin vA.B.C

### Summary
...

### Changes
- ...

### Infrastructure
- Build: ✅ | Tests: ✅ | Lint: ✅

### What Ships
| Artifact | Platform |
|----------|----------|
| aphrodite-aarch64-apple-darwin | macOS ARM64 |
| aphrodite-x86_64-unknown-linux-gnu | Linux x86_64 |

### Links
- **Full Changelog**: https://github.com/PlayForm/Aphrodite/compare/...
EOF
gh release create Aphrodite/vX.Y.Z --notes-file /tmp/notes.md \
  target/release/aphrodite-aarch64-apple-darwin \
  target/release/aphrodite-x86_64-unknown-linux-gnu

Dual-Store Guarantee (CCR_UNRESOLVED Fix)

Every proxy compress/fetch MUST also store in inline store. This prevents [CCR_UNRESOLVED] from race conditions or proxy eviction.

Pattern: after _compress_via_proxy(content, ...) succeeds with hash h, call _inline_store_put(h, content) before returning the marker.

After _resolve_one fetches from proxy, call _inline_store_put(hash_val, result) before returning.

Version Bump - 5 Locations (v0.7.0+)

Atomization moved _core.py → _core/config.py. Auto-release now bumps:

1. Cargo.toml (binary)
2. _core/config.py (BIN_VERSION + PLUGIN_VERSION)
3. pyproject.toml
4. __init__.py docstring
5. plugin.yaml

Use --minor for feature releases, default patch for fixes.

Session Setup Checklist

Before development:

1. Auto-expand ON: aphrodite_catalog(mode='toc') shows inline content
2. Proxies running: aphrodite_stats shows token: on, cache: on
3. Plugin symlinked to repo
4. env_passthrough set
5. Context engine ON: [compression].context_engine = true in aphrodite.toml