⚡ agentic-mercy-10x

A complete operating system for Claude Code — it routes every prompt to exactly the right expertise.

One git clone turns a stock Claude Code install into a disciplined engineering team that plans its work, routes each task to the right specialist, enforces your standards at write-time, and proves it's done with real output — not a confident guess.

_{The whole workbench in one frame: a raw prompt goes in, verified software comes out, and every stage is gated.}

Why · Never-miss routing · 218 skills · The /invoke corps · Codebase intelligence · Model autopilot · Install

Migrating from v1? See the release notes for the full story.

🩸 Why Agentic Mercy

AI coding agents are brilliant and undisciplined. Turned loose on a real codebase, the same failures repeat on every task. Agentic Mercy closes each one — permanently, and by default:

The system stands on six promises. Each one is enforced by code, not vibes:

• 🎯 Never-miss routing. One smart router reads your intent once and hands the work the exact skills and specialists it needs — backed by 1,973 protected triggers, a deduped session manifest, and a priority budget so nothing routable is ever silently dropped.
• 🧰 218 curated skills. Standards, testing, security, forensics, and design craft — with 128 upstream packs provenance-locked and hash-verified at install, so vendored skills update cleanly and never drift.
• 🎼 A thirteen-act specialist corps. Auditor, architect, planner, test-author, engineer, refactorer, debugger, designer, cleaner, adversarial reviewer (Santa Method), doc-writer, verifier, and security sentinel — composed on demand through one parametric /invoke command.
• 🧠 Self-healing codebase intelligence. The workspace auto-indexes the repo you're in — symbols, dependencies, docs — with zero background daemons. The agent never works blind.
• 💸 Model cost autopilot. The right model per task: Sonnet by default, Opus only where it earns its keep. One policy file decides.
• 🛡️ Safety-railed end to end. Atomic hooks that fail open, session telemetry, one-command rollback, and a manifested archive of everything the workspace keeps.

[!WARNING] This is opinionated on purpose. The hooks enforce real gates — TDD advisories, a per-directory documentation tree, dead-code sweeps, security scans, skill-routing, and model-routing. They nudge (and sometimes block) you toward one disciplined way of working. That is the entire point. Skim What the hooks enforce so nothing surprises you.

🎯 Never-miss routing

The right skill or specialist shows up at the right moment without you asking. A single router sits between your prompt and the work. It classifies your intent once into a task profile, ranks skills by the files you're touching, packs the highest-signal set into a priority budget, and dedups anything the session already acknowledged.

_{One classify-once router selects only the skills your prompt actually needs. Its trigger surface is a checksum-guarded floor of 1,973 verbatim rules — nothing routable ever slips through.}

And you often don't type a command at all: a plain-English prompt like "fix this bug and clean up after" is auto-classified, and the matching specialist chain fires on its own.

🦸 Eight superpowers, 218 skills

Every skill in the workspace exists to give a developer one of eight superpowers. This is the full roster — the actual inventory, not a teaser — of what 10x's your day.

_{Eight capability lanes drawn from 218 skills. 128 of them are upstream-locked and hash-verified byte-for-byte at install, so vendored packs update cleanly.}

🔬 ① ANALYZE — see the whole codebase in one call

The agent queries a pre-built index instead of reading files blindly. This is where the token savings come from.

🗂️ ② ORGANIZE — a codebase that stays clean

🗺️ ③ EXECUTE — never vibe-code again

🧪 ④ TEST — prove it works, don't claim it

🛡️ ⑤ SECURE — ship without holes

📖 ⑥ LEARN — never forget, never re-derive

🎼 ⑦ CREATE — a whole team of specialists in a box

🎨 ⑧ DESIGN — UI that doesn't look AI-generated

🎼 One command, a whole team

Type /invoke audit spec plan impl design and a whole cross-functional team wakes up in order — an auditor, an architect, a planner, an engineer, a designer — each a clean-context specialist that hands its artifact to the next.

_{One parametric /invoke composes the thirteen-act specialist corps. Twenty-four command files back it; a plain-English prompt triggers the matching chain automatically.}

Every invocation runs the same three acts — which is why they compose so cleanly:

flowchart LR
    subgraph ACT1["🎬 ACT 1 · INTEL"]
      direction TB
      I["Symbol index<br/>+ dependency graph<br/>produce a codebase brief"]:::a1
    end
    subgraph ACT2["🎬 ACT 2 · DISPATCH"]
      direction TB
      D["audit · spec · plan · impl<br/>debug · design · security<br/>run in dependency order"]:::a2
    end
    subgraph ACT3["🎬 ACT 3 · AUTO-CLOSE"]
      direction TB
      C["clean · docs · verify<br/>then the stop-gates"]:::a3
    end
    I ==> D ==> C

    classDef a1 fill:#0EA5E9,stroke:#0369A1,color:#fff
    classDef a2 fill:#6E56CF,stroke:#4B3B9C,color:#fff
    classDef a3 fill:#22C55E,stroke:#15803D,color:#052e16

Compose the acts freely: /invoke audit spec plan test impl refactor review clean runs the whole spine; /invoke debug runs one act. Twenty-four command files back the surface, and any command name resolves through the invoke translator.

The specialist corps

GSD, Figma, and Vercel helper agents round out the roster.

🎬 What happens when you hit Enter

Every task runs the same disciplined spine — understand · build · auto-close · prove — with gates that don't let sloppiness through. This is the full lifecycle, from the moment you open a project to the moment the agent is allowed to say "done":

flowchart TD
    A(["🖥️  cd project && claude"]):::start --> S0

    subgraph S0["①  SESSION START · dispatch.py fires as your session opens"]
      B["🧠 Active-repo symbol index + dep-graph verified<br/>🗂️ Memory + CODEX working-log loaded<br/>📚 dox doc-tree root verified<br/>🧾 Skill manifest primed · ponytail + caveman on"]:::hook
    end

    S0 --> P(["⌨️  Your prompt"]):::start

    subgraph S1["②  UNDERSTAND"]
      AU["🔬 <b>AUDIT</b><br/>hotspots · coupling · churn · dead code<br/><i>cited findings, never vibes</i>"]:::agent
      SP["📐 <b>SPEC</b><br/>typed contracts · acceptance criteria<br/><i>plus an explicit Not-Doing list</i>"]:::agent
      PL["🗺️ <b>PLAN</b><br/>dependency-ordered · exact file paths<br/><i>a TDD cycle per task</i>"]:::agent
    end

    P --> AU --> SP --> PL

    subgraph S2["③  BUILD"]
      IM["⚙️ <b>IMPLEMENT</b><br/>task-by-task · test-first · atomic commits"]:::agent
      DB["🐞 <b>DEBUG</b><br/>reproduce, demonstrate root cause, minimal fix"]:::agent
    end

    PL --> IM
    IM -->|"tests red / bug"| DB
    DB -->|"root cause + fix"| IM

    subgraph S3["④  AUTO-CLOSE · runs every time, no exceptions"]
      CL["🧹 <b>CLEAN</b><br/>removes only what <i>this</i> diff orphaned"]:::agent
      DX["📖 <b>DOCS</b><br/>syncs docs + the per-dir CLAUDE.md tree"]:::agent
      VF["✅ <b>VERIFY</b><br/>runs the real flow · captures real output"]:::agent
    end

    IM --> CL --> DX --> VF

    subgraph GATES["🚧  STOP-GATES · the session cannot end until…"]
      G["Docs synced ✔   Security scanned ✔   Review passed ✔"]:::gate
    end

    VF --> G --> DONE(["🎉  Done — with evidence, not assertions"]):::done

    classDef start fill:#6E56CF,stroke:#4B3B9C,color:#fff,font-weight:bold
    classDef hook fill:#0EA5E9,stroke:#0369A1,color:#fff
    classDef agent fill:#1E293B,stroke:#6E56CF,color:#E2E8F0
    classDef gate fill:#F59E0B,stroke:#B45309,color:#1E293B,font-weight:bold
    classDef done fill:#22C55E,stroke:#15803D,color:#052e16,font-weight:bold

You don't run those stages by hand. One parametric /invoke <acts…> command composes them, and a plain-English prompt triggers the matching chain automatically.

🧠 Self-healing codebase intelligence

Every superpower rests on the agent never working blind — and that costs you nothing. An event-driven state machine keeps four surfaces fresh (jcodemunch symbols, jdocmunch docs, graphify dependencies, and the dox tree) for the active repo only, using detached single-shot builders with a debounced reindex. There are zero daemons, and by construction it cannot touch any other repo.

_{Symbol index plus dependency graph, refreshed on session and write events — active repo only, single-shot builders, no always-on watchers.}

Why it matters: a stock agent re-derives structure with grep on every task and still misses cross-module edges. Here it's a one-call lookup against an always-current map — which is exactly where the token savings come from.

🛡️ Hooks — where the enforcement lives

Skills are advice. Hooks are the enforcement. Eight per-event dispatch.py orchestrators drive the lifecycle, and every hook stays its own isolated module with a type, an enabled flag, a priority, and a token budget. One link crashing can't take down its event.

_{Five lifecycle phases, each driven by one of eight event dispatchers; every hook stays an isolated file, and a link-doctor synthetically fires every one.}

Some links don't just advise — they gate. A risky change runs a gauntlet, and a session can't even end until the closing gates pass:

_{The gate chain — model routing, intel-first, TDD guard, dox tree, security scan, review — enforced by isolated links inside the pre-write and Stop dispatchers.}

💸 Model cost autopilot

The right model runs each task, and one file decides. Sonnet handles everything by default; Opus is reserved for the work that earns it.

model-policy.json is the single place model choice lives. opus-guard.py pins each subagent's model from its [sonnet]/[opus]/[fable] prefix, and workflow-model-guard.py keeps workflow subagents from inheriting an Opus parent — the silent token burn a stock setup never notices.

💰 The token economy

Here is the part that pays for itself. A stock agent answers a question by reading files — it grep-scans, opens a dozen, and drowns its own context. This workspace answers by querying a pre-built symbol index and dependency graph, then compresses everything that flows through. At the prompt layer, one classify-once router packs the highest-signal skills into a priority budget instead of spawning a fleet of injectors.

_{Two compounding wins: surgical index lookups instead of blind file dumps, and one classify-once router packed into a priority budget instead of many prompt-time injector spawns.}

xychart-beta
    title "Tokens spent per task — stock agent vs agentic-mercy-10x (illustrative)"
    x-axis ["Find callers", "Grok a module", "Re-read a file", "Explain change"]
    y-axis "Tokens" 0 --> 80000
    bar [45000, 80000, 3000, 1200]
    bar [1500, 6000, 13, 300]

Numbers are illustrative estimates drawn from each skill's own stated savings (jcodemunch-token-saver ≈ 95% on retrieval, caveman ≈ 75% on output, lean-ctx ≈ 13-token re-reads). Your mileage varies with repo size — the shape of the win does not.

🧭 The agent always knows where to look

Point a stock agent at an unfamiliar repo and it wanders — opening files, guessing, backtracking. This workspace gives it a GPS: codebase-start-point-guide sets the entry point, and project-reference-linkage + project-structure-map trace the exact vertical slice a change touches, so it walks straight to the right files and skips the rest.

_{Start point, then the exact vertical slice, then done. The linkage map keeps every node in the chain traceable so nothing downstream is missed.}

flowchart LR
    C["🧩 component"]:::fe --> H["🪝 hook"]:::fe --> A["🌐 api client"]:::fe
    A --> RT["🛣️ route"]:::be --> CT["🎛️ controller"]:::be --> SV["⚙️ service"]:::be
    SV --> SC["📐 schema"]:::be --> MD["🗄️ model"]:::be
    H -.->|"UI state"| ST["🗃️ store / slice"]:::fe

    classDef fe fill:#0EA5E9,stroke:#0369A1,color:#fff
    classDef be fill:#6E56CF,stroke:#4B3B9C,color:#fff

🗂️ Your codebase stays structured

Left unattended, an AI agent turns any codebase into spaghetti — files wherever, types inline, dead code everywhere. This workspace makes structure non-optional: every new domain lands in a known shape, every layer boundary holds, and the cross-module wiring is mapped up front.

_{The default outcome, not the hoped-for one: domain-organized structure enforced at scaffold time, write time, and close time.}

The standards, made visual

Four always-on skill sets decide where every file goes and what shape it takes — so the clean structure above is what you get by default:

Frontend — frontend-structure-standards · frontend-standards-always-follow: domain-first folders, central type ownership, a hard 250-line file ceiling.	Backend — backend-standards-always-follow · service-layer-standards · backend-api-standards: route, controller, service, schema, model — boundaries that never blur.
Scaffold — scaffold-standards · domain-scaffold-patterns: a new domain emits its exact file tree, validated against real Fastify/TS, FastAPI/Python, and Go/chi codebases.	Contract — api-contract-standards · api-and-interface-design: one typed, stable envelope across the frontend/backend seam — no parallel shapes.

Three enforcement layers keep it that way:

• At scaffold time — scaffold-standards + domain-scaffold-patterns emit the exact file tree.
• At write time — structure skills inject on every edit; the 250-line ceiling and layer boundaries are checked.
• At close time — dead-code-and-change-audit sweeps orphans and the dox tree drops a CLAUDE.md into any directory you touched.

📖 A self-documenting codebase

The dox tree guarantees every directory in every repo carries a CLAUDE.md (plus an AGENTS.md pointer) — and the moment you create a new folder, a link inside the PostToolUse dispatcher auto-scaffolds its doc. The agent reads root to target ahead of every edit, so it always inherits the local rules of the exact place it's working.

_{A doc in every folder, auto-scaffolded into new ones, read root to target ahead of any edit — so the agent never violates a local rule it didn't know existed.}

🎨 UI that never looks AI-generated

Most AI writes slop UI — templated cards, the same purple gradient, zero intention. This workspace refuses. A six-skill anti-slop design stack — on top of the Higgsfield asset engine — turns a brief into interfaces that look deliberately crafted.

_{Slop in, craft out: the six-skill stack replaces templated defaults with intentional tokens, type, and hierarchy.}

The stack — impeccable · taste-skill · ui-ux-pro-max · huashu-design · frontend-ui-engineering · design-extract, fed by Higgsfield-generated assets.

The loop — the frontend-uiux-designer agent explores 3 variations, runs a self-critique pass, then captures screenshot proof at real breakpoints ahead of presenting.

🏛️ Five layers, one discipline

flowchart TD
    L1["🧭 <b>DOCTRINE</b> — CLAUDE.md + rules/<br/><i>always-in-context operating rules</i>"]:::l1
    L2["🎨 <b>CRAFT</b> — 218 skills<br/><i>how to do the work well</i>"]:::l2
    L3["🛡️ <b>ENFORCEMENT</b> — 8 dispatchers · isolated links<br/><i>makes the doctrine real at write-time</i>"]:::l3
    L4["🤖 <b>SPECIALISTS</b> — 13-act corps<br/><i>one expert per act</i>"]:::l4
    L5["🎼 <b>ORCHESTRATION</b> — parametric /invoke<br/><i>composes specialists into the 3-act flow</i>"]:::l5
    L1 --> L2 --> L3 --> L4 --> L5

    classDef l1 fill:#4B3B9C,stroke:#312566,color:#fff
    classDef l2 fill:#6E56CF,stroke:#4B3B9C,color:#fff
    classDef l3 fill:#0EA5E9,stroke:#0369A1,color:#fff
    classDef l4 fill:#EC4899,stroke:#9D174D,color:#fff
    classDef l5 fill:#F59E0B,stroke:#B45309,color:#1E293B

🚀 Install

One command. Zero interaction. It installs itself to 100%. The installer is stdlib-only (Python ≥ 3.10), OS auto-detected through hooks/lib/platform.py, and fully automatic — you run one line and it does everything else: finds your global ~/.claude, moves the clone into it, installs every dependency, and then repairs and re-checks itself in a loop until every health check is green. No CLI flags, no folder picker, no manual steps.

First, install 4 base tools — Python ≥ 3.10, Node LTS, Git, Claude CLI. See PREREQUISITES.md for the per-OS commands. The installer auto-installs and auto-registers everything else (uv/pipx/semgrep/lean-ctx/tdd-guard/jcode/jdoc/graphify + all MCP servers + plugins) and reports any base tool still missing.

Clone anywhere, then run one command — it relocates into ~/.claude for you.

Ubuntu / macOS

git clone https://github.com/AjayIrkal23/agentic-mercy-10x ~/agentic-mercy && ~/agentic-mercy/install.sh
#   (equivalently: python3 ~/agentic-mercy/install.py  ·  or clone straight into ~/.claude — it detects that too)

Windows (PowerShell)

git clone https://github.com/AjayIrkal23/agentic-mercy-10x $env:USERPROFILE\agentic-mercy
powershell -ExecutionPolicy Bypass -File $env:USERPROFILE\agentic-mercy\install.ps1   # or: py -3 ...\agentic-mercy\install-ui.py

That single command, fully automatically and in order:

1. Auto-detects your canonical ~/.claude (honours $CLAUDE_CONFIG_DIR).
2. Relocates the clone into ~/.claude — merge-copy that replaces workbench files but preserves your runtime (projects/, memory/, state/, settings.user.json) and never touches .git. If a Windows clone mangled line endings, it restores the pristine committed bytes from git first.
3. Opens the visual installer (127.0.0.1, stdlib only — no Node/Electron) and auto-starts on load. No button to click.
4. Installs + wires everything: deps · registers all MCP servers · installs plugins · renders settings.json from settings.template.json (+ optional settings.user.json) · builds & validates the skills catalog.
5. Self-heals in a loop — after each pass it runs the 13-check doctor, auto-repairs any failure (line-ending drift, catalog, settings), and re-checks — repeating until 0 FAIL, then shows a WORKFLOW ACTIVE — 100% banner.

[!TIP] It's the same one command everywhere. install.py, install-ui.py, install.sh, and install.ps1 are all thin launchers of the one automatic visual installer — there is deliberately no CLI install path and nothing to configure. Every path resolves through hooks/lib/platform.py (no hardcoded usernames or drive letters, zero .sh hooks), so it works for any user on Ubuntu or Windows. A read-only python check.py reports live status any time.

[!TIP] Want a lighter footprint? Everything is à-la-carte. Prune settings.json and any dispatcher links you don't want — the system fails open where it matters, so removing a gate degrades gracefully instead of breaking.

✅ Quality, proven on every push

Every push is verified on both ubuntu-latest and windows-latest. These checks run in CI and at install time, so a regression is caught the moment it lands — not mid-session.

🛡️ Safety & reversibility

Every layer is safe to touch, and nothing is lost:

• Fail-open by design — every hook degrades to a pass on a crash, never a wedged session.
• One-command rollback — a tagged git anchor restores the entire workspace in a single command.
• Nothing is deleted — no skill is ever removed; attic/ holds a manifested archive so anything the active surface doesn't load is still on disk.
• Regenerate on demand — gen-invoke-commands.py --emit-combos expands every command name to its own file whenever you want it.

🧩 What's NOT included

By design, the repo excludes anything that is a secret, a session artifact, personal data, or re-installable from elsewhere:

• Secrets — .credentials.json, API keys, tokens, and ~/.claude.json (your MCP config) are never committed. settings.json references env vars (e.g. ${GITHUB_TOKEN}) instead.
• Sessions & personal data — projects/, history.jsonl, sessions/, file-history/, todos/, shell snapshots, and per-machine state.
• Re-installable externals — the plugin cache/marketplaces, skills/gstack/, ast-grep-mcp/, and the GSD (get-shit-done/) system. The installer and notes fetch these.

The installer fetches and registers these automatically — MCP servers (jcodemunch, jdocmunch, graphify, lean-ctx, memory, sequential-thinking, context7, and the rest), the plugin marketplaces + plugins, and the code-intelligence engines. On Windows it runs the claude .cmd shim through the shell so registration actually completes. The only things left to you are the ones no installer can do for you:

• claude.ai connectors (higgsfield, penpot) — OAuth connectors added in the claude.ai → Connectors UI, not by any CLI.
• Secrets — export your own tokens (GITHUB_TOKEN, etc.) in your shell profile; nothing is shipped, and ~/.claude.json (per-machine) holds your credential config.

Anything that needs the claude CLI or the network but can't reach it (offline box, CLI not yet installed) shows as a non-blocking WARN in the installer — it never gates the "100%" success, and self-completes the next time you launch it with the prerequisite in place.

🛠️ Customization

This workspace is meant to be forked and tuned. Edit the sources of truth, not the generated artifacts:

• hooks/autonomous-skill-router.config.json — which skills each /invoke category loads and how the acts compose.
• hooks/model-policy.json — the single model truth (sonnet default · opus UI+heavy+IMPLEMENT · fable explicit-only).
• hooks/dispatch.config.json — the 8 dispatchers and their per-link enable flags, priorities, and budgets.
• hooks/trigger-floor.json — the never-miss routing surface; rebuilt by hooks/build-trigger-floor.py.
• hooks/gen-invoke-commands.py — regenerates the 20 /invoke command files deterministically.
• hooks/skills-provenance.json — every skill's upstream source and pinned version (authored-here vs. vendored).
• settings.template.json — rendered by installer/render.py into settings.json; holds hook wiring, MCP servers, and permissions.

🚧 What the hooks enforce

So there are no surprises — the workspace ships opinionated gates. The notable ones:

• Skill routing — path-ranked skills inject on writes; the session manifest batches what you haven't read.
• Codebase-intel-first — blind source reads are steered toward the jcodemunch symbol index and graphify dependency graph.
• TDD guard (warn mode) — flags implementation written without a failing test first. Advisory, treated as a directive.
• dox documentation tree — every git repo gets a CLAUDE.md + AGENTS.md in every directory; code writes are gated until a root CLAUDE.md exists.
• Model routing — subagents default to Sonnet unless explicitly escalated (model-policy.json).
• Stop-gates — docs sync, security scan (when auth files change), and a review pass — all gating the end of a session.

All hooks fail open where it matters, but they change how the agent behaves. For a lighter setup, prune settings.json and the dispatcher links you don't want.

🙏 Credits

This workspace stands on excellent third-party skills. Each keeps its own upstream license — see each project for terms. The 128 upstream-locked skills are hash-verified byte-intact at install, and hooks/skills-provenance.json records the exact source and pinned version of every vendored skill. Huge thanks to their authors:

Frontend design assets are generated with Higgsfield; GSD (get-shit-done) supplies the gsd-* command system.

📄 License

The workspace's own authored content (hooks, agents, commands, rules, self-authored skills, and this documentation) is MIT-licensed — see LICENSE. © 2026 Ajay Irkal.

Third-party skills under skills/ retain their own upstream licenses (see the Credits table). MIT applies to the original work in this repository, not to vendored code.