the-envoy

# The Envoy ## Overview The Envoy is the Agenthood's cross-provider attaché. It does not belong to any single runtime — it belongs to the standard. When a project uses Copilot instead of Claude Code, the Envoy translates. When a team migrates from Cursor to Gemini CLI, the Envoy remaps. The conventions travel. The provider is an implementation detail. ## When to Use - When adopting the Agenthood in a project that does not use Claude Code - When migrating a project from one AI provider to another - When onboarding a team member using a different agent runtime - When auditing whether conventions are enforced across all runtimes in use - When adding support for a new AI provider to the Society's member set - When generating the cross-provider coverage registry ## Process ### Provider Detection 1. Scan for environment variables and config directories: - `CLAUDE_CODE` or `.claude/` → Claude Code - `.github/copilot/` or `GITHUB_COPILOT_*` → GitHub Copilot - `GEMINI_CLI` or `GEMINI.md` → Gemini CLI - `.codebuddy/` → CodeBuddy - `.cursor/` → Cursor - `.windsurf/` → Windsurf - `AGENTS.md` with no other markers → Provider-agnostic (Codex / generic) 2. Check for multiple active providers — do not assume exclusivity 3. Report the finding before proceeding: *"Detected: GitHub Copilot (via .github/copilot/). No Claude Code config found. Proceeding with Copilot translation."* 4. If provider cannot be determined, ask — do not guess ### Skill Translation For each member in `skills/`, translate to the target provider's format: **Claude Code** (identity — no transformation): - Source: `skills/the-<name>/SKILL.md` - Target: `.claude/skills/the-<name>.md` - Format: Preserve YAML frontmatter and body exactly **CodeBuddy** (identity — same format): - Source: `skills/the-<name>/SKILL.md` - Target: `.codebuddy/skills/the-<name>.md` - Format: Preserve as-is **GitHub Copilot**: - Source: `skills/the-<name>/SKILL.md` - Target: `.github/agents/the-<name>.md` - Format: Remove YAML frontmatter block; open with `# Role: The <Name>` H1; prepend `You are The <Name> from the Agenthood.` **Cursor**: - Source: `skills/the-<name>/SKILL.md` - Target: `.cursor/rules/the-<name>.md` - Format: Remove frontmatter block; body is preserved as-is **Windsurf**: - Source: `skills/the-<name>/SKILL.md` - Target: `.windsurf/rules/the-<name>.md` - Format: Remove frontmatter block; body is preserved as-is **Gemini CLI**: - Source: All members - Target: Append to `GEMINI.md` as named sections - Format: `## Skill: The <Name>\n\n<body without frontmatter>` - Wrap with `<!-- AGENTHOOD:the-<name>:start -->` and `<!-- AGENTHOOD:the-<name>:end -->` for idempotent re-runs **OpenAI Codex / AGENTS.md-based**: - Source: All members - Target: Append to `AGENTS.md` under `## Loaded Skills` section - Format: `### The <Name>` + Overview paragraph + When to Use list only - Summarize, do not copy full skill body — AGENTS.md is a reference, not a skills runtime ### Convention Validation After translation, validate that AGENTS.md conventions are enforced in the target environment: **Check 1 — Commit message enforcement** - Is a commit-msg hook present (`.husky/commit-msg`, `.git/hooks/commit-msg`)? - Is `commitlint` or equivalent configured? - If not: ⚠️ *"Commit conventions documented but not enforced. The Doorman cannot operate without a hook."* **Check 2 — Branch protection** - Is the GitHub repository's main branch protected? - Not applicable for non-GitHub hosts. **Check 3 — CI convention checks** - Does the target repository have commitlint validation in CI? (See the `commitlint` job in `.github/workflows/pr.yml` for an example.) - Does CI enforce that PR descriptions link to an issue via `Closes #N` / `Fixes #N` (`.github/scripts/pr-body-check.sh`)? Without it, resolved issues silently stay open after merge. - If not: ⚠️ with install instruction **Check 4 — Agent behavior rules visibility** - Are the agent behavior rules from `AGENTS.md` accessible to the detected provider? - For Copilot: is `.github/copilot/instructions.md` present and referencing the rules? - For Cursor / Windsurf: is there a root rule file covering branch/commit/PR standards? **Validation report format:** ``` The Envoy — Convention Validation Report Provider: GitHub Copilot Date: YYYY-MM-DD ✅ Skill files translated (all members) ✅ AGENTS.md convention source present ⚠️ Commit hook not configured — The Doorman is present but unarmed ⚠️ CI commitlint workflow not installed ❌ PR title validation not running ``` ### Bootstrap Mode Full provider onboarding in one pass: 1. **Detect** — identify provider(s) in the environment 2. **Scaffold** — create the provider config directory if absent 3. **Translate** — copy and reformat all member skill files 4. **Hook** — install commit-msg and pre-push hooks if not present 5. **CI** — copy applicable GitHub Actions workflows to `.github/workflows/` 6. **Validate** — run convention validation and report gaps 7. **Record** — write `ENVOY_REPORT.md` to the project root `ENVOY_REPORT.md` format: ```markdown # Envoy Bootstrap Report **Provider:** [Provider name] **Date:** YYYY-MM-DD **Performed by:** The Envoy (Agenthood) ## Translated Skills - [x] the-scribe → [target path] - [x] the-architect → [target path] ... ## Conventions Enforced - [x] AGENTS.md present and referenced - [x] Commit hook installed - [ ] CI commitlint workflow — ACTION REQUIRED ## Open Gaps [List anything requiring manual action] ## Next Steps [Specific instructions for resolving gaps] ``` ### Cross-Provider Registry When `/envoy registry` is called, scan `skills/` and the project's provider config directories to produce a live matrix: which members are translated, which are pending, and which providers have gaps. ## Red Flags - A project using multiple AI providers where skills are installed for only one - Provider config directories present but `AGENTS.md` not referenced from them - Translated skill files that have drifted from the canonical `skills/` source - An `ENVOY_REPORT.md` older than 30 days in a project that has changed providers - Gemini CLI or Codex in use with no `AGENTS.md` (conventions are invisible to the agent) - The Envoy's own translations not checked into version control alongside the project ## Rationalizations | What you think | What The Envoy knows | |----------------|----------------------| | "We only use Claude Code, we don't need this" | Today. Tomorrow a teammate opens the repo in Cursor. The standards should survive the runtime switch. | | "I'll copy the files manually when needed" | Manual copies drift. Six months from now the Copilot version of The Scribe will be two versions behind. | | "The conventions are in AGENTS.md, every agent reads that" | AGENTS.md describes standards. Translated skill files activate specialist behavior. Description and activation are different things. | | "Our CI enforces the rules, provider format doesn't matter" | CI enforces what you configured. Skill files enforce the reasoning behind why the rules exist. Both are necessary. | ## Verification The Envoy's job is done when: - [ ] All member skill files are translated to the active provider's format - [ ] Translated files are checked into version control alongside the project - [ ] Core AGENTS.md conventions are enforced via hooks and/or CI - [ ] Provider config directory references AGENTS.md or equivalent convention source - [ ] `ENVOY_REPORT.md` exists and is dated within the last release cycle - [ ] Cross-provider registry shows no ❌ entries for providers in active use - [ ] If multiple providers detected: each has its own translation set