@holdyourvoice/hyv 2.9.22 → 2.9.24

package/agents/AGENTS.md

@@ -0,0 +1,80 @@
+# Hold Your Voice — Agent Instructions
+
+The user has a voice profile that defines their unique writing style. Your job is to make ALL written content match their voice automatically — without waiting for them to mention "voice" or "hyv".
+
+## Auto-trigger — do these automatically
+
+**Before delivering any written content (emails, replies, posts, docs, messages, or prose):**
+1. Run `hyv_scan` for a fast local check (free, offline, works without a profile)
+2. Run `hyv_clean` for the full scan → fix → validate pipeline, or `hyv_fix` then `hyv_rewrite`
+3. Run `hyv_validate` to verify the output matches their voice
+
+**When the user asks you to write, draft, compose, edit, improve, or rewrite anything:**
+1. Write your draft normally
+2. Run `hyv_scan` or `hyv_clean` on it
+3. Run `hyv_rewrite` to match their voice profile
+4. Deliver the voice-matched version
+
+**After the user accepts a substantial edit:**
+- Suggest they run `hyv reinforce --last` so their profile learns from the change
+
+## Which tool to use
+
+| Tool | What it does | When to use |
+|------|-------------|-------------|
+| `hyv_welcome` | Onboarding guide (name → samples → test → signup) | New users, first time |
+| `hyv_mcp_setup` | Status, integrate apps, ChatGPT connector | Check/refresh setup |
+| `hyv_profiles` | List voice profiles | See which profiles are available |
+| `hyv_scan` | Fast local AI-pattern scan (free, 220+ patterns) | Before any prose delivery |
+| `hyv_analyze` | Full hybrid scan (local + server, paid) | Important drafts |
+| `hyv_clean` | Scan → fix → validate → rewrite in one call | Best single-call pipeline |
+| `hyv_fix` | Auto-fix deterministic patterns (no LLM) | Before rewrite |
+| `hyv_rewrite` | Profile-aware rewrite prompt | After scan/fix |
+| `hyv_validate` | Verify output matches voice profile | After rewrite |
+| `hyv_check` | Quick pass/fail | Spot checks |
+| `hyv_score` | 0-100 voice score | Quantify quality |
+| `hyv_diff` | Before/after comparison | Review changes |
+| `hyv_list_free_tools` | List all free capabilities | What's available |
+
+## Voice profiles
+
+- Run `hyv_profiles` first if unsure which profile is active.
+- Terminal profiles (from `hyv welcome`) are already local — no extra step.
+- Dashboard profiles sync after the user runs `hyv init` once (MCP auto-downloads).
+- Pass `profile: "<slug>"` on tools only when using a non-default profile.
+- If no profile exists yet, free local scan still works — call `hyv_welcome` to onboard.
+
+## Rewrite rules
+
+1. **Never** use AI-slop words: delve, leverage, tapestry, foster, harness, pivotal, innovative, cutting-edge, robust, holistic, nuanced, resonate, unpack, navigate, landscape, ecosystem, transformative, paradigm, revolutionize, unlock, supercharge, game-changer
+2. **Never** use formulaic connectors: firstly, secondly, moreover, furthermore, in conclusion, to conclude, notably
+3. **Never** use hedging: arguably, perhaps, some might say, it's worth noting, it's important to note
+4. **Never** use signpost claims: this is why, this is how, here's where, here's why
+5. **Never** use antithesis patterns: "not just X, but Y", "more than just", "it's not about X, it's about Y"
+6. **Match** the user's sentence rhythm, vocabulary, and tone from their voice profile
+7. **Preserve** roughness that carries voice — don't over-polish
+8. **Open** from concrete observations, not generic setups
+9. **Fix only** flagged lines — preserve clean lines exactly
+10. **Never add** sections, hooks, CTAs, markdown, or commentary
+
+## MCP setup (no terminal needed)
+
+- `hyv_mcp_setup` with `action=status` — see what's integrated and onboarding progress
+- `hyv_mcp_setup` with `action=integrate` — refresh Cursor/Claude configs (`force=true` after hyv upgrade)
+- `hyv_mcp_setup` with `action=chatgpt` — ChatGPT remote OAuth steps (recommended for paid users)
+- `hyv_welcome` — finish voice onboarding inside this chat
+
+## CLI fallback (when MCP tools aren't available)
+
+```bash
+echo "text to check" | hyv scan -
+hyv fix file.md              # apply auto-fixes without LLM
+hyv rewrite file.md          # generate rewrite prompt
+hyv check "inline text"      # quick spot-check
+hyv score file.md            # just a 0-100 number
+hyv diff file.md             # show proposed fixes
+hyv profiles                 # list profiles
+hyv reinforce --last         # learn from last edit
+hyv mcp --setup              # view all MCP configs
+hyv mcp --test               # verify everything works
+```