VexJoy Agent

Essays and writing behind this toolkit live at vexjoy.com.

VexJoy Agent connects plain-English requests to specialist agents, skills, and workflows. /do selects the knowledge and tools needed for your task. Hooks enforce specific checks, and scripts handle repeatable work.

The aim is to give capable models useful domain knowledge without making you learn the toolkit's catalog.

43 domain agents, 59 workflow skills, 78 hooks, 153 scripts. Agents carry knowledge, skills enforce methodology, hooks block incomplete work, scripts handle determinism.

Works across Claude Code (/do), Codex ($do), Factory (/do), Reasonix (/do).

What It Looks Like

$ claude

> /do debug this Go test

  Routing: go-engineer + systematic-debugging
  Phase 1/4: Reproduce: running test, capturing failure...
  Phase 2/4: Hypothesize: 3 candidates from stack trace...
  Phase 3/4: Verify: isolated root cause in connection pool timeout
  Phase 4/4: Fix: patch applied, test passing, PR opened

  ✓ Delivered: PR #847, fix connection pool timeout in health check

The router pairs a Go agent with a debugging skill, then follows the task through verification and delivery.

The Pipeline

  ROUTE        PLAN         EXECUTE      VERIFY       DELIVER      RECORD
 ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐    ┌──────┐
 │ /do  │───▶│ Task │───▶│Agent │───▶│Tests │───▶│  PR  │───▶│Route │
 │Router│    │ Plan │    │+Skill│    │Gates │    │Branch│    │Result│
 └──────┘    └──────┘    └──────┘    └──────┘    └──────┘    └──────┘

/d — Jev-Powered Router

/d routes requests through TypeSafe's Jev classifier. One API call picks the agent, skill, and pipeline — no manifest read into context. Requires Jev; use /do if TypeSafe is not configured.

Setup: install the typesafe MCP plugin and set TYPESAFE_API_KEY in your environment.

> /d fix the flaky test in the payments module

  ROUTING (/d): testing-automation-engineer + testing-preferred-patterns
  Source: jev (confidence: medium)
  Invoking...

Anti-Rationalization

Checks require evidence rather than confidence.

Hooks run at configured events. Skills state what to verify; blocking78 hooks enforce the checks they cover. Coverage depends on the runtime and tool path.

Knowledge Work Is First-Class

The content engine researches, drafts in a calibrated voice, checks 397 writing patterns, and adapts finished pieces for each platform. /html produces a self-contained report, slide deck, prototype, chart, or diagram. It needs no coding or setup beyond installation.

It Proves Its Own Changes

Toolkit changes use direct review and relevant checks. Model comparisons can settle specific uncertainties; they are not required for every edit. PHILOSOPHY.md explains the validation policy. what-didnt-work.md records failed experiments, routing reversals, unvalidated A/B citations, disabled lint rules, and program refutations.

The automated nightly evolution loop (/evolve, writes to evolution-reports/) ran regularly through mid-May 2026. It is currently dormant; recent evidence has come from manual PRs instead.

Installation

git clone https://github.com/notque/vexjoy-agent.git ~/vexjoy-agent
cd ~/vexjoy-agent
./install.sh

Installs into ~/.claude/ and mirrors into ~/.codex/, ~/.factory/, and ~/.reasonix/ when the runtime command is on PATH or its home directory exists. Choose symlinks for live updates through git pull, or copies for a stable snapshot.

Want only part of the toolkit? Run ./install.sh --configure to pick which skills, agents, and78 hooks install, or copy .local.example/profile.yaml to .local/profile.yaml and edit. No profile file = full install, unchanged behavior. Credit: @thomasvan. Details: .local.example/README.md.

Jev Auto-Compact plugin (optional, requires TYPESAFE_API_KEY):

claude plugin marketplace add ./plugins/jev-auto-compact
claude plugin install jev-auto-compact@jev-auto-compact -y

Replaces LLM-generated compaction summaries with Jev-judged verbatim pruning. Once context reaches 60%, Jev evaluates each old tool call (keep, truncate result, or drop) and returns the pruned transcript with zero rewriting, in about a second instead of one to three minutes. The threshold matters: every compaction is a cold KV-cache rewrite of the prefix, so compacting every turn multiplies cost. Evidence lives in learning.db (python153 scripts/jev-compact-evidence.py).

Proof it works: python153 scripts/jev-compact-evidence.py prints every compaction from two sources side by side — the plugin's claim and the engine's own compact_boundary record (tokens before/after, duration). A Jev compaction shows as a sub-second engine record next to a matching plugin claim; a built-in LLM compaction shows as a 30–150s record. Rows live in ~/.claude/learning/learning.db (compaction_events, session_usage).

Full setup: docs/start-here.md

rm -rf ~/.gemini/skills ~/.gemini/agents ~/.gemini/hooks ~/.gemini/scripts ~/.gemini/antigravity/plugins/vexjoy-agent

claude --system-prompt "."

Four Layers

Full skill catalog: docs/skills.md.

┌─────────────────────────────────────────────────┐
│  SKILL.md                                       │
│  ┌─ Frontmatter ─────────────────────────────┐  │
│  │ triggers, pairs_with, success-criteria     │  │
│  └────────────────────────────────────────────┘  │
│  Reference Loading Table (conditional imports)   │
│  Phased Instructions (numbered, with gates)      │
│  Verification (evidence requirements)            │
└─────────────────────────────────────────────────┘

Built with the Toolkit

A game built entirely by Claude Code using these agents, skills, and pipelines:

Choose Your Path

I just want to use it Install, learn /do, done.

I do knowledge work Writing, research, data analysis, moderation, HTML artifacts. No code.

I'm a developer Architecture, extension points, adding agents and skills.

I'm an AI power user Routing tables, pipelines,78 hooks, telemetry DB.

I'm an AI agent Machine-dense inventory. Tables, paths, schemas.

I'm on LinkedIn 🚀 Thought leadership. Agree? 👇

Philosophy

• Zero-expertise operation. Say what you want. The system classifies, dispatches, enforces, delivers.
• LLMs orchestrate, programs execute. Deterministic work belongs to153 scripts. LLM judgment handles design decisions, diagnosis, review.
• Density. Every word carries instruction, rule, or decision. Cut everything else.
• Breadth over depth. Right context ensures correctness. Unfocused context adds cost.
• Structural enforcement. Exit codes enforce what instructions can't. Quality gates are automated, not advisory.
• Everything pipelines. Complex work decomposes into phases. Phases have gates. Gates prevent cascading failures.

Full design philosophy: PHILOSOPHY.md

Maintenance

One report-only script surfaces upkeep work; it prints a digest and never edits, deletes, or blocks.

• python153 scripts/stale-skill-scan.py --top 20 ranks stale skills and agents as pruning candidates. Run it quarterly; see docs/deprecation-template.md.

Scheduled work follows the same boundary as everything else: judgment uses agents; repeatable plumbing uses153 scripts.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.