oh-my-kiro

oh-my-kiro

Your AI agent forgets everything. Mine doesn't.

oh-my-kiro is a framework that gives your AI coding agent persistent memory, deterministic workflows, and self-evolving intelligence. Like oh-my-zsh for Zsh — but for AI agents.

Day 1: generic agent. Day 30: knows your codebase, your style, your decision patterns.

Works with: Kiro CLI

Quick Start • Why OMK • Commands • Architecture

---

Quick Start

New project:

git clone https://github.com/KaimingWan/oh-my-kiro.git my-project
cd my-project
python3 scripts/generate_configs.py

Existing project:

git submodule add https://github.com/KaimingWan/oh-my-kiro.git oh-my-kiro
bash oh-my-kiro/tools/init-project.sh . "My Project"

Start building:

@auto build a REST API for user management

That's it. The agent understands requirements, writes a plan, reviews it, and executes — all autonomously.

---

Why oh-my-kiro?

The Core Problem: AI Agents Hallucinate and Drift

You tell the agent "always run tests before committing." It does — for 3 turns. Then it forgets. Or it "runs" tests by printing "tests passed" without actually executing anything. Or it skips the step because "the change is trivial."

Natural language instructions are unreliable. The agent interprets them probabilistically. It might follow them. It might not. You can't build a reliable workflow on "might."

The Solution: As-Code, Hook-Based Enforcement

OMK's design philosophy: if it can be enforced by code, don't enforce it with words.

• ❌ Prompt: "Never commit secrets" → agent might still do it

• ✅ Hook: block-secrets.sh scans every git push → exit 2 = blocked. Zero exceptions.

• ❌ Prompt: "Always run tests after editing" → agent skips when context is tight

• ✅ Hook: post-write.sh auto-triggers lint + test on every file save. Agent doesn't choose.

• ❌ Prompt: "Follow the plan step by step" → agent jumps ahead or skips steps

• ✅ Hook: enforce-ralph-loop.sh blocks direct source edits when a plan exists. Must go through Ralph Loop.

This is not about restricting the agent. It's about raising the success rate of every operation by removing the possibility of hallucinated shortcuts.

What You Get

• Agent never forgets — Corrections persist across sessions. Mistakes become rules. Knowledge compounds.
• 19 hooks enforce, not suggest — The agent literally cannot rm -rf /, commit secrets, skip tests, or edit files outside its workspace.
• Agent crashes don't matter — Ralph Loop keeps spawning fresh agents until every checklist item passes.
• Plan → Review → Ship, one command — @auto goes from vague idea to merged code.
• Skill supply chain security — 8-category threat scan on every skill install. Based on Snyk's ToxicSkills research.
• Zero config, full power — Works out of the box.

---

The Innovation: 3-Layer Determinism

┌─────────────────────────────────────────────────────┐
│  L1: Commands — 15 workflows, 100% deterministic     │
│  @plan @auto @execute @review @evaluate @debug ...   │
│  Each hardcodes the full step chain. No shortcuts.   │
├─────────────────────────────────────────────────────┤
│  L2: Gates — 11 hooks, hard block (exit 2 = denied)  │
│  Agent CANNOT bypass. Secrets blocked. rm -rf blocked.│
│  Writes outside workspace blocked. No exceptions.    │
├─────────────────────────────────────────────────────┤
│  L3: Feedback — 8 hooks, advisory enrichment         │
│  Auto-lint on save. Correction detection. Semantic   │
│  knowledge injection on every prompt.                │
└─────────────────────────────────────────────────────┘

Why 3 layers, not just "add more hooks"?

Not everything should be a hard block. Blocking rm -rf is obvious (L2). But "you should run tests" is better as auto-triggered feedback (L3) — the agent sees test results and self-corrects. And "follow this 5-step workflow" is best as a deterministic command (L1) — the agent doesn't interpret, it executes.

The layers map to certainty levels: L1 = 100% (user-triggered workflow), L2 = 100% (hard block), L3 = ~50% (advisory, agent may ignore but usually doesn't because the feedback is useful).

L1 is deterministic. When you say @plan, the agent follows: deep understanding → write plan with TDD checklist → dispatch parallel reviewers → fix until APPROVE → execute via Ralph Loop. It cannot skip steps.

L2 is a hard wall. exit 2 from any gate hook = operation blocked. The agent sees the block, gets a suggested alternative, and retries safely. No amount of prompt engineering bypasses this.

L3 is compound interest. Every correction you make is detected, persisted to episodes.md, and auto-injected into future sessions by keyword match. After 3 similar corrections, it promotes to a permanent rule.

---

The Innovation: Ralph Loop

Your agent crashes mid-task? Context window fills up? No problem.

Ralph Loop (Python outer loop)
  │
  ├─ Spawn fresh Kiro CLI instance
  │    └─ Agent reads plan, works on next unchecked item
  │    └─ Marks item [x] when verify command passes
  │    └─ Agent exits (crash, context full, or done)
  │
  ├─ Re-verify: run all inline verify commands
  │    └─ Revert any [x] items whose verify fails
  │
  ├─ Progress check
  │    └─ Items completed? → spawn next iteration
  │    └─ 3 stalls? → circuit breaker, stop
  │
  └─ All items [x]? → ✅ Done. Print summary.

Each iteration gets clean context. No stale state accumulation. The bash loop is the reliability layer — agent intelligence is the execution layer.

---

Commands

Commands come in two flavors:

• MCP Prompt (@o/plan "build a REST API") — accepts natural language input inline. The agent receives your description as context.
• Command-only (@execute, @cpu) — triggered by keyword, no inline arguments. Reads state from files (active plan, git diff, etc.)

🚀 The Autonomy Spectrum

@auto "build a user auth system" (MCP prompt)

Full autopilot. One command → understand requirements → write plan with TDD checklist → dispatch parallel reviewers → auto-fix until APPROVE → Ralph Loop execution → done.

What makes it special: Readiness Check — a 4-dimension checklist (Goal / Constraints / Success Criteria / Context) that validates understanding before any code is written. If anything is unclear, it asks exactly ONE question with Socratic challenge modes.

@plan "migrate from PostgreSQL to DynamoDB" (MCP prompt)

Controlled execution. Same pipeline as @auto, but pauses for your confirmation after Phase 0 (deep understanding) and after review. You stay in the loop.

What makes it special: Every checklist item requires an inline verify command (- [ ] API returns 200 | \curl -sf localhost:8000/health`). Ralph Loop re-runs these commands and reverts any [x]` that fails. No false completions.

@execute (command-only)

Resume and finish. Loads an approved plan, launches Ralph Loop. Agent crashes don't matter — the bash loop keeps spawning fresh instances until every checklist item passes.

What makes it special: Work Dir isolation — if the plan declares **Work Dir:** worktrees/omk-foo, execution is sandboxed there. The gate hook blocks writes outside that directory.

@do "add a health check endpoint" (MCP prompt)

Quick task (< 1 hour). No plan file, no review dispatch. Scratchpad → implement → verify → commit. For when @plan is overkill.

---

🔍 Analysis Commands

@review (MCP prompt)

Dispatches a reviewer subagent with the full git diff. Multi-angle review (correctness, security, performance). Every finding has P0-P3 severity and file:line citation. Auto-detects worktree context from .active-submodule.

@evaluate "scripts/ralph_loop.py look for simplifications" (MCP prompt)

Independent code quality assessment. 4 parallel evaluator subagents — each with a distinct persona (Refactoring Expert, Product Manager, Breaker, CSO) — assess code across 6 dimensions: Simplicity, Alignment, Correctness, Security, Robustness, Maintainability. Mandatory fill-table format prevents walk-through reviews. Also runs automatically after @execute completes (GAN-inspired adversarial loop, up to 3 rounds).

@debug "tests fail with timeout on CI" (MCP prompt)

Systematic debugging pipeline. Not guess-and-check — structured root cause analysis:

1. Session resume — checks docs/investigations/ for prior work on this bug (cross-session continuity)
2. Triage — reads episodes.md for known patterns, builds architectural context via LSP
3. Hypothesis tree — generates ranked hypotheses, tests each with evidence
4. Fix — only after root cause is confirmed

What makes it special: Investigation documents persist across sessions. If you hit a bug on Monday and resume Wednesday, the agent picks up exactly where it left off.

@research "how does Kafka handle rebalancing" (MCP prompt)

3-level research: L0 built-in knowledge → L1 web search → L2 deep dive with source cross-verification. Findings auto-persisted to file.

---

🔧 Git & PR Commands

@fixpr (command-only)

Automated PR fixer. Fetches ALL unresolved review threads via GraphQL, triages each comment (fix / pushback / clarify), implements fixes, replies + resolves every thread. Goal: zero unresolved threads.

What makes it special: PR Blueprint — reads the full diff first to understand intent, then fixes individual comments without drifting from the PR's purpose. Protected Code list prevents reviewers from requesting changes to intentional design decisions.

@cpr (MCP prompt) · @cpu (command-only)

@cpr: Commit → push → create PR → worktree cleanup. @cpu: Commit → push → merge directly.

@ck "feature/auth" (MCP prompt) · @wt (command-only)

@ck: Checkout branch into submodule worktree with fuzzy search. @wt: List all worktrees, clean up merged branches.

---

🧠 Knowledge Commands

@dream (command-only)

Automated knowledge hygiene. Scans the entire knowledge base for rot:

• Deterministic (bash): dead links, stale episodes, orphan files, TODO markers, content staleness by type
• Semantic (LLM): content redundancy, contradictions across files, consolidation recommendations

@agent (MCP prompt) · @know (MCP prompt)

@agent: Distill a principle into rules.md. @know: Capture a knowledge insight into episodes.md.

@lint (command-only) · @skill (command-only)

@lint: Framework health check. @skill: List skills, match user need to closest one.

---

The Innovation: Self-Evolving Knowledge System

This is not "save notes to a file." It's a closed-loop intelligence pipeline that automatically detects mistakes, extracts patterns, and rewires the agent's behavior — permanently.

How It Works

You say "别用 sed 改 JSON，用 jq"
  │
  ├─ correction-detect.sh fires (中英文 30+ 纠正模式匹配)
  │
  ├─ auto-capture.sh pipeline:
  │    ├─ Gate 1: 过滤低价值 (问句丢弃, 无动作丢弃)
  │    ├─ Gate 2: 提取关键词 (英文技术术语优先, 中文动作词 fallback)
  │    ├─ Gate 3: 去重 (已在 rules.md → 跳过)
  │    └─ 写入 episodes.md: "2026-03-30 | active | sed,json,jq | 别用 sed 改 JSON"
  │
  ├─ distill.sh (background):
  │    └─ 同一关键词出现 ≥3 次 → 自动提升为 rules.md 永久规则
  │    └─ 标记源 episodes 为 "promoted"，下次 session-init 清理
  │
  └─ context-enrichment.sh (every prompt):
       └─ 用户消息包含 "sed" 或 "json" → 自动注入对应规则
       └─ 🔴 CRITICAL 规则: 每条消息都注入
       └─ 🟡 RELEVANT 规则: 关键词匹配时注入

What Makes This Different