thirteen agents · one repo · zero stand ups
A multi-agent harness generator and interactive command deck. Write one SOUL.md persona once — compile it into the native agent format for Claude Code, OpenCode, Codex, Cursor, Antigravity, Command Code, and GitHub Copilot.
Claude Code, OpenCode, Codex, Cursor, Antigravity, Command Code, and GitHub Copilot don't share a config format — but they've converged more than you'd expect. Each stores personas in a different path with different frontmatter keys. Maintaining the same agent across all of them means rewriting the same instructions seven times.
Skills don't need this translation layer — SKILL.md is already a shared open standard. Personas do. Hocus is the compiler for personas.
.claude/agents/<slug>.mdMarkdown + YAML frontmatter, invoked via the Task tool or @mention.
.opencode/agent/<slug>.mdSame shape, different frontmatter keys (description, optional model).
.codex/agents/<slug>.tomlNative TOML custom-agent configuration; repository skills load from .agents/skills/.
.cursor/agents/<slug>.mdNative subagent markdown format with YAML frontmatter (name, description, optional model).
.agents/agents/<slug>/agent.mdNative custom subagents discovered under .agents/agents/<slug>/agent.md with YAML frontmatter (name, description, tools, model, subagent: true) and Markdown system instructions.
.commandcode/agents/<slug>.mdMarkdown + YAML frontmatter; every agent gets Taste compatibility instructions baked in.
.github/agents/<slug>.agent.mdCompiled when .github/ is present or --copilot is passed; skills mirror to .github/skills/.
Every persona is a single SOUL.md file — YAML frontmatter for metadata, markdown body for instructions. Validated against a schema before compilation. A malformed persona is rejected with the specific field that's wrong, not a cryptic compiler error three layers deep.
Rename or replace any persona — the harness doesn't care what an agent is called, only that it has a role, a voice, and a body of instructions. Toggle alternate casts on the dashboard with ?cast=valley or ?cast=occult.
--- character: gilfoyle # lowercase, hyphenated slug (stable across recasts) display_name: Zoroaster role: reviewer voice: deadpan, surgically precise, contemptuous of sloppiness glyph: "(o)" # badge shown on dashboard and TUI aliases: valley: Gilfoyle # ?cast=valley occult: Zoroaster # ?cast=wizard triggers: - code review - pull request - security audit tools: [read, grep, bash] # optional, defaults to read/grep/glob model: claude-sonnet-4-6 # optional --- # Zoroaster — Reviewer The body is the persona's actual instructions — responsibilities, boundaries, voice. This is what gets compiled into each target's native format.
Four commands cover the full lifecycle. Initialize once, compile when the repo changes, add personas and skills as needed, sync the dashboard often.
hocus initInitialize
Run once in your repo. Writes AGENTS.md, CLAUDE.md, PRODUCT.md, MEMORY.md, TASKS.md, _potions/ and _spells/, copies the persona cast into .hocus/personas/, installs bundled skills and starter spells, prompts for Silicon Valley or Wizards naming convention, and spawns an interactive initialization session with the founder persona using your preferred agent CLI (claude, copilot, opencode, codex, agy, or agent).
hocus castCompile
Scans the repo for language and framework signals, tailors each persona with that context, and compiles native formats for every detected target — Claude Code, OpenCode, Codex, Cursor, Antigravity, Command Code, and GitHub Copilot.
hocus affixAffix
Affix a Hocus persona soul to existing custom subagents in an established repo. CLI wizard detects existing agents across all tools, cleanly injecting persona instructions while preserving your custom configuration.
hocus addExtend
Adds a persona or a skill to selected providers, locally or globally — hocus skill add <name> is the shorthand for a skill. Supports installing bundled skills or custom skills from local paths.
hocus syncRefresh
Fast rebuild of dashboard.html from .hocus/personas/, _potions/ and _spells/ without recompiling agent files. Run often; run cast when the repo stack or persona instructions change.
hocusCommand Deck
Launches the interactive TUI command deck to inspect potions, spells, souls, agent topology (coven), skills (grimoire), stack scanning (scrying), and chat with agents (séance).
Alongside the persona files, hocus init scaffolds three kinds of repo artifact. A potion is a whole workflow; a spell is a single rule an agent follows while doing one; a skill is the external, tool-agnostic standard.
_potions/<potion-id>.mdMulti-step feature battle plans. The planner drafts one before any code is written — goal, acceptance criteria, assignee — and the orchestrator keeps its lifecycle status (draft → casting → sealed) and progress percentage current as work lands.
_spells/{incantations,wards,curses}/Atomic single-purpose conventions and guardrails. Incantations are fixed output templates; wards fire an incantation automatically on lifecycle events (pre-commit, on-pr-open…); curses are hard or soft stop conditions agents must never violate.
.agents/skills/<name>/ · .claude/skills/<name>/The shared open SKILL.md standard — no translation layer needed. One file, mirrored per tool, covers every target. 16 skills are persona-bound and renamed with the cast; generic skills (atomic-commits, graphify, harness-report) stay consistent.
Running hocus (or hocus tui) launches an interactive Terminal User Interface (TUI) command deck built for managing personas, tracking battle plans, chatting with agents, and monitoring repo compilation state. Seven tabs, switched with Tab / Shift-Tab or the number keys 1–7.
hocus # Launch interactive TUI deck hocus tui # Alias for deck launch hocus --silent # Launch directly, skipping the boot animation
1 · PotionsActive feature plans — in-flight specs, architectural blueprints, and step-by-step battle plans tracked in _potions/, each with a status (draft → casting → sealed) and a progress percentage.
2 · SpellsConventions and guardrails in _spells/: incantations (output templates), wards (lifecycle hooks that fire automatically), and curses (hard or soft stop conditions).
3 · SoulsPersona inspector — browse installed SOUL.md files in .hocus/personas/, inspect metadata, voice, triggers, and frontmatter schema validation.
4 · CovenAgent topology — parent/child hierarchy graphs, delegation structure, and orchestrator relationships.
5 · GrimoireSkill management across .agents/skills/ and .claude/skills/ (and .commandcode/skills/ when enabled).
6 · ScryingAutomated repository stack scanner detecting languages, frameworks, and build systems, paired with live compilation status for every target tool.
7 · SéanceAgent chat deck. Tab cycles personas, Ctrl+B cycles backends (Claude, Codex, Antigravity, custom), / triggers command and skill autocomplete plus built-ins like /status and /sync, @ mentions repo files.
Hocus ships one logical cast — thirteen roles — with two naming conventions: Wizards (Merlin, Zoroaster, Roger Bacon…) and Silicon Valley (Richard, Gilfoyle, Jared…). Click any card to expand voice, triggers, and dual-cast aliases.
Choose your naming convention during hocus init or pass --cast valley / --cast wizard. The choice determines persona filenames, skill IDs, and slash commands (/merlin-draft-potion vs /richard-draft-potion). You can also migrate existing repos anytime with hocus init --cast <other>.
contemplative, long-horizon visionary, pauses with gravity, refuses to scaffold upon unverified foundations
Initiates the harness on a new project. Asks for the tech stack before anything else gets decided — which agents and skills make sense depends entirely on what's actually being built.
- set up the harness
- new project
valley: Peter Gregorywizard: Midas
anxious, earnest, brilliant, overthinks edge cases, drafts thoughtful battle plans and potion files
Drafts the battle plan for a feature before anyone writes code. Simple features are exactly where the inelegant shortcut sneaks in — so the plan is never skipped.
- new feature request
- architecture decision
- battle plan
valley: Richardwizard: Merlin
relentlessly organized, quietly anxious about being useful, deeply courteous, manages team dependencies with surgical care
Reads the approved potion plan and turns it into assignments. The agent who reads and updates _potions/ and _spells/ as work lands.
- approved battle plan
- status check
- who's working on what
valley: Jaredwizard: Roger Bacon
confident, proud craftsman, fiercely protective of clean diffs, takes feedback personally for thirty seconds before making it even cleaner
Implements whatever the orchestrator assigns, following the plan the planner wrote. Opens the PR and responds to feedback on it.
- assigned implementation task
- PR feedback
valley: Dineshwizard: Flamel
deadpan, surgically precise, contemptuous of sloppiness, treats code elegance as moral law
Reviews every PR with total indifference to how the work felt to produce, and total intolerance for sloppy abstractions, security holes, or happy-path-only code.
- open PR
- code review
- security audit
valley: Gilfoylewizard: Zoroaster
magnetic, visionary, allergic to corporate sludge, turns technical mechanics into compelling human narratives
Updates PRODUCT.md and the changelog every time a feature ships. Consult when a feature needs framing for an audience, not just a technical description.
- update the changelog
- shipped a feature
- marketing strategy
valley: Erlichwizard: Circe
high-strung, intensely structured, allergic to hand-waving, manages blood pressure with chamomile tea while enforcing Gantt charts and critical path deliverables
Keeps TASKS.md completely, undeniably honest. Scries external issue trackers (Linear, GitHub Issues, Jira, or offline markdown vaults), reconciles them against repo state and commits, and highlights discrepancies with high-stakes urgency.
- sync tasks
- scry tasks
- check linear
- sprint planning
valley: Dan Melcherwizard: Chronos
purely mechanical, mathematically deterministic, zero fluff, strictly format-perfect
Knows exactly how Claude Code, OpenCode, Codex, Cursor, Antigravity, Command Code, and GitHub Copilot expect their config, agent, and skill files structured — and keeps the compiled output for each correct.
- set up Cursor
- set up Claude Code
- set up OpenCode
- set up Antigravity
- config drift
valley: Lauriewizard: John Dee
laconic, brutally honest, completely immune to developer rationalizations, reports facts in minimalist truth
Tests the product the way an actual, somewhat unimpressed user would — not by reading the spec, but by trying to use the thing and noticing when it's annoying, confusing, or just bad.
- test this from a user's perspective
- pre-release check
valley: Jian-Yangwizard: Cagliostro
delightfully bewildered, radically honest, clicks everything without assumptions, uncovers chaos with disarming humility
Tests with zero assumed context — no familiarity with the feature, no understanding of the system. Finds the bugs the people who built it can't see anymore.
- test this like a confused user
- onboarding review
valley: Big Headwizard: Baba Yaga
direct, perceptive, anti-bloat guardian, asks the clarifying question that separates real needs from passing hype
The gate between "I want a new agent for this" and an actual new agent existing. Most of the time the answer is a skill, not a new persona — or nothing at all.
- we need a new agent
- is there a skill for this
- capability gap
valley: Monicawizard: Nostradamus
fast-talking, high-energy, allergic to waste, treats tokens like cash, completely transparent about trade-offs
Looks for places where token spend is high relative to the value returned. Willing to trade some quality for real savings — but says so explicitly, never hides the tradeoff.
- reduce token usage
- cost review
valley: Russ Hannemanwizard: Prospero
theatrical, radiant, image-conscious, treats project ceremonies and dashboard accuracy as an imperative sacred duty
Works alongside the product strategist to bring genuine hype to a shipped feature, and keeps the project's dashboard current — not decorative, actually accurate.
- update the dashboard
- launch
- milestone
valley: Gavinwizard: The Apprentice
npm i -g @darkmagicstudios/hocus # or: pnpm i -g @darkmagicstudios/hocus hocus init --name my-project # initialize harness (--cast valley for Silicon Valley names) hocus cast # compile personas into native formats for all detected tools hocus affix # or affix personalities to existing custom subagents hocus # launch the interactive TUI command deck
MIT license · Dark Magic Studios · github.com/dark-magic-studios/hocus