oh-my-customcode

Your AI Agent Stack. Compiled, Not Configured.

한국어 문서 (Korean)

50 agents. 115 skills. 23 rules. One command.

npm install -g oh-my-customcode && cd your-project && omcustom init

Philosophy

oh-my-customcode is built on two ideas:

1. Agent systems are compiled, not configured.

| Compile Concept | oh-my-customcode | |----------------|-----------------| | Source code | .claude/skills/ — reusable knowledge and workflows | | Build artifacts | .claude/agents/ — executable specialists assembled from skills | | Compiler | mgr-sauron (R017) — structural verification and integrity | | Spec | .claude/rules/ — constraints and build rules | | Linker | Routing skills — connect agents to tasks | | Standard library | guides/ — shared reference documentation |

Skills are source. Agents are compiled output. Sauron verifies the build. This separation means skills evolve independently of agents, and agents can be recompiled from updated skills at any time.

2. If it can't be done, make it work.

When no specialist exists for a task, oh-my-customcode does not fail. It creates one.

User: "Review this Terraform module"
  → Routing: no terraform expert found
  → mgr-creator discovers: infra-aws-expert skills + docker-best-practices guide
  → Creates: infra-terraform-expert.md
  → Executes the review immediately
  → Agent persists for future use

This is not a fallback. It is the design. The system treats missing expertise as a build problem — find the right skills, compile a new agent, execute.

How It Works

Orchestration

The main conversation acts as a singleton orchestrator (R010). It never writes files directly. Every action is delegated through routing skills to specialized agents.

User (natural language)
  → Routing skill (intent detection, confidence scoring)
    → Specialized agent (isolated execution)
      → Result returned to orchestrator
        → Response to user

Four routing skills cover the full domain:

| Routing Skill | Routes To | |--------------|-----------| | secretary-routing | Manager agents (mgr-), system agents (sys-) | | dev-lead-routing | Language, backend, frontend, tooling, DB, infra, arch agents | | de-lead-routing | Data engineering agents (de-*) | | qa-lead-routing | QA team (qa-planner, qa-writer, qa-engineer) |

Model Selection

Each agent runs on the model optimized for its task:

| Model | When | Examples | |-------|------|---------| | opus | Complex reasoning, architecture | Design review, research synthesis | | sonnet | Implementation, general tasks | Code generation, agent creation | | haiku | Fast validation, search | File search, count verification |

The reasoning-sandwich pattern formalizes this: opus for pre-analysis, sonnet for implementation, haiku for post-verification.

Parallel Execution

Independent tasks run in parallel (R009). Up to 4 concurrent agents per message:

Agent(lang-golang-expert):sonnet  ┐
Agent(lang-python-expert):sonnet  ├─ All spawned in one message
Agent(qa-engineer):sonnet         │
Agent(arch-documenter):haiku      ┘

Soft default is 4 concurrent agents, hard cap 5. Agent Teams (shared task list, peer messaging) is used instead of plain parallel agents when it's available — but it requires Claude Code to expose a TeamCreate tool, which is not present on a stock install today. Until then, oh-my-customcode's standard Agent-tool parallel model above is what actually runs.

Agents (50)

| Category | Count | Agents | |----------|-------|--------| | Languages | 6 | lang-golang, lang-python, lang-rust, lang-kotlin, lang-typescript, lang-java21 | | Backend | 6 | be-fastapi, be-springboot, be-go-backend, be-express, be-nestjs, be-django | | Frontend | 5 | fe-vercel, fe-vuejs, fe-svelte, fe-flutter, fe-design | | Data Engineering | 6 | de-airflow, de-dbt, de-spark, de-kafka, de-snowflake, de-pipeline | | Database | 4 | db-supabase, db-postgres, db-redis, db-alembic | | Tooling | 4 | tool-npm, tool-optimizer, tool-bun, slack-cli | | Architecture | 3 | arch-documenter, arch-speckit, agora-runner | | Infrastructure | 2 | infra-docker, infra-aws | | QA | 3 | qa-planner, qa-writer, qa-engineer | | Security | 1 | sec-codeql | | Managers | 6 | mgr-creator, mgr-updater, mgr-supplier, mgr-gitnerd, mgr-sauron, mgr-claude-code-bible | | System | 4 | sys-memory-keeper, sys-naggy, tracker-checkpoint, wiki-curator |

Each agent declares its tools, model, memory scope, and limitations in YAML frontmatter. Tool budgets are enforced per agent type for accuracy.

Skills (115)

| Category | Count | Includes | |----------|-------|----------| | Best Practices | 24 | Go, Python, TypeScript, Kotlin, Rust, React, FastAPI, Spring Boot, Django, Flutter, Docker, AWS, Postgres, Redis, Kafka, dbt, Spark, Snowflake, Airflow, pipeline-architecture-patterns, alembic, and more | | Routing | 4 | secretary, dev-lead, de-lead, qa-lead | | Workflow | 14 | structured-dev-cycle, deep-plan, research, evaluator-optimizer, dag-orchestration, worker-reviewer-pipeline, reasoning-sandwich, pipeline, fsd, and more | | Development | 8 | dev-review, dev-refactor, analysis, create-agent, intent-detection, web-design-guidelines, omcustom-takeover, skill-extractor | | Operations | 9 | update-docs, audit-agents, sauron-watch, monitoring-setup, fix-refs, release-notes, and more | | Memory | 3 | memory-save, memory-recall, memory-management | | Package | 3 | npm-publish, npm-version, npm-audit | | Optimization | 3 | optimize-analyze, optimize-bundle, optimize-report | | Security | 2 | adversarial-review, cve-triage | | Consensus | 1 | agora — anonymous multi-round multi-vendor consensus review | | Other | 44 | claude-native, vercel-deploy, skills-sh-search, result-aggregation, and ~40 more |

Skills use a 3-tier scope system: core (universal), harness (agent/skill maintenance), package (project-specific).

Commands

All commands are invoked inside the Claude Code conversation.

Development

| Command | What it does | |---------|-------------| | /dev-review | Code review against best practices | | /dev-refactor | Refactor for structure and patterns | | /structured-dev-cycle | 6-stage development: plan → verify → implement → verify → compound → done | | /deep-plan | Research-validated planning | | /research | 10-team parallel analysis with cross-verification | | /sdd-dev | Spec-Driven Development workflow | | /ambiguity-gate | Pre-routing ambiguity analysis | | /adversarial-review | Attacker-mindset security code review | | /pipeline | Execute YAML-defined pipelines | | /pipeline resume | Resume a halted pipeline from last failure point | | /omcustom:fsd | Full Self Driving — autonomous release loop: repeats /pipeline auto-dev (issue → implement → verify → release) then /homework (retrospective audit) until no eligible issues remain | | /homework | Retrospective audit of the current session, surfacing process gaps as feedback/issues | | /agora | Anonymized multi-round, multi-vendor consensus review (independent CLI reviewers + rotating judge) for decisions that need adversarial scrutiny |

Agent Management

| Command | What it does | |---------|-------------| | /omcustom:analysis | Analyze project, auto-configure agents and skills | | /omcustom:create-agent | Create a new agent | | /omcustom-takeover | Extract canonical spec from existing agent or skill | | /omcustom:audit-agents | Audit agent dependencies | | /omcustom:update-docs | Sync project structure and documentation | | /omcustom:sauron-watch | Full structural verification (5+3 rounds) | | /omcustom-feedback | Submit feedback as GitHub issue |

Web UI

| Command | What it does | |---------|-------------| | /omcustom:web | Control built-in Web UI (start, stop, status, open) |

Package & Release

| Command | What it does | |---------|-------------| | /omcustom:npm-publish | Publish to npm | | /omcustom:npm-version | Semantic versioning | | /omcustom:npm-audit | Dependency security audit | | /omcustom-release-notes | Generate release notes from git history |

Memory & System

| Command | What it does | |---------|-------------| | /omcustom:monitoring-setup | OTel monitoring toggle | | /omcustom-loop | Auto-continue background agent workflows (3-continue safety limit) | | /omcustom:lists | Show all commands | | /omcustom:status | System health check |

Rules (23)

| Priority | Count | Purpose | |----------|-------|---------| | MUST | 14 | Safety, permissions, agent design, identification, orchestration, verification, completion, enforcement | | SHOULD | 8 | Interaction, error handling, memory, HUD, ecomode, ontology routing, wiki sync, verification ladder | | MAY | 1 | Optimization |

Key rules: R010 (orchestrator never writes files), R009 (parallel execution mandatory), R017 (sauron verification before push), R020 (completion verification before declaring done), R021 (advisory-first enforcement — most rules are prompt-based, not hard-blocked), R016 (continuous improvement — violations update the rule, and stale clauses are retired into HTML comments rather than accumulating forever), R023 (verification ladder — cheapest check first: deterministic hooks/linters, then cheap-model review, then expensive-model review, then human).

R018 (Agent Teams) is conditional: it only takes effect when both CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set AND the TeamCreate tool is present in the tool list. On a stock Claude Code install today, TeamCreate is not registered, so R018 is dormant and R009/R010 (the standard Agent-tool parallel-execution model) govern instead.

Guides (56)

Reference documentation covering best practices, architecture decisions, and integration patterns. Located in guides/ at project root, covering topics from agent design to CI/CD to observability.

Safety

oh-my-customcode ships 42 lifecycle hook scripts covering security, drift detection, and rule reinforcement. A few examples:

| Hook | Trigger | Action | |------|---------|--------| | secret-filter | Bash, Read output | Detects AWS keys, API tokens, private keys, bearer tokens | | audit-log | Edit, Write, Bash, Agent | Append-only JSONL at ~/.claude/audit.jsonl | | schema-validator | Write, Edit, Bash input | Validates tool inputs, flags dangerous patterns | | claude-md-reinject | SessionStart (fresh session, resume, or compact) | Reinjects CLAUDE.md and the enforced rule set — prevents rule amnesia after context compaction | | stuck-detector | PostToolUse, repeated edits | Flags an agent looping on the same file/edit without progress | | r007-r008-drift-advisor | UserPromptSubmit, SubagentStop, PostToolUse | Advisory check that the last turn carried the required agent/tool identification headers |

Most hooks are advisory (exit 0) — they warn but never block. A small number of hard-block hooks (e.g. stage-blocker, rule-deletion-guard) reject the tool call outright (exit 2). oh-my-customcode's own governance rules (.claude/rules/) follow an advisory-first enforcement model: prompt-based guidance is the default, and a rule is only promoted to a blocking hook after repeated, observed violations. Rules also retire — clauses tied to since-fixed platform bugs or that go unused for two minor releases are wrapped in HTML comments (still readable via the source file, invisible to the agent's context) rather than left to accumulate indefinitely.

The hook source of truth is .claude/hooks/hooks.json; omcustom init compiles it into the hooks block of .claude/settings.json (via src/core/hooks-settings.ts), which is the file Claude Code actually loads.

CLI

omcustom init                  # Interactive setup wizard (language, framework, team mode)
omcustom init --lang ko        # Initialize with Korean
omcustom init --from-snapshot  # Install from pre-configured team snapshot
omcustom sync                  # Detect drift between .claude/ state and lockfile
omcustom sync --check          # Check for drift without applying changes
omcustom sync --export         # Export current state as team snapshot
omcustom update                # Update to latest
omcustom list                  # List components
omcustom doctor                # Verify installation
omcustom doctor --fix          # Auto-fix issues
omcustom security              # Scan for security issues
omcustom projects              # List managed projects with version status
omcustom update --all          # Batch update all outdated projects
omcustom serve                 # Start built-in Web UI
omcustom serve-stop            # Stop Web UI

Project Structure

your-project/
├── CLAUDE.md                   # Entry point
├── .claude/
│   ├── agents/                 # 50 agent definitions
│   ├── skills/                 # 115 skill modules
│   ├── rules/                  # 23 governance rules (R000-R023)
│   ├── hooks/                  # 42 lifecycle hook scripts (hooks.json source; compiled into settings.json)
│   ├── schemas/                # Tool input validation schemas
│   ├── specs/                  # Extracted canonical specs
│   ├── contexts/               # 4 shared context files
│   └── ontology/               # Knowledge graph for RAG
└── guides/                     # 56 reference documents

External Tool Integrations

RTK is automatically installed during omcustom init for 60-90% token savings. Other tools are optional:

| Tool | Purpose | Install | Status | |------|---------|---------|--------| | RTK | 60-90% token savings on CLI output | Auto-installed via omcustom init | Recommended | | Codex CLI | OpenAI Codex hybrid workflows | npm i -g @openai/codex | Optional | | Gemini CLI | Google Gemini hybrid workflows | npm i -g @google/gemini-cli | Optional |

When installed, each tool is auto-detected at session start and its features become available. When not installed, all commands gracefully fall back to Claude-native alternatives.

Development

bun install          # Install dependencies
bun run dev          # Development mode
bun test             # Run tests
bun run build        # Production build

Requirements: Node.js >= 18.0.0, Claude Code CLI (developed and tested against Claude Code v2.1.277).

Releases are two-stage automation: a merged release/vX.Y.Z PR triggers auto-tag.yml, which creates the git tag; the tag push then triggers release.yml, which builds, verifies, and publishes to npm. The project's own contributor knowledge base — the in-repo wiki at wiki/ (278 pages covering agents, skills, rules, and workflows) — is CI-verified on every PR against a source-hash manifest, so wiki pages cannot silently drift from the code they document.

Support

If oh-my-customcode saves you time or you like where it's heading, consider supporting development:

Every contribution keeps the compiler running. ☕

License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

You are free to use, modify, and distribute oh-my-customcode for any noncommercial purpose — personal projects, research, education, and nonprofit/government use. Commercial use is not permitted under this license.

Need a commercial license? Open an issue or reach out to the author.