Why MeowKit

Standing on the shoulders of giants

MeowKit didn't emerge from a vacuum. It was inspired by and builds upon ideas from several pioneering AI agent toolkits:

• ClaudeKit — the original structured skill system for Claude Code, with orchestration protocols, development rules, and the cook workflow that MeowKit's phase-gated pipeline descends from. Best kit so far!
• Gstack — a comprehensive skill collection featuring headless browser automation, QA testing, and the ethos of "search before building" that shaped MeowKit's research-first approach.
• Aura-frog — an autonomous agent framework whose multi-agent coordination patterns and self-healing concepts influenced MeowKit's agent architecture and escalation protocols.

MeowKit takes these foundations and adds enforced discipline — hard gates that block, TDD that's mandatory not optional, and security scanning baked into every workflow. The goal isn't to replace these projects but to push the idea further: what happens when best practices aren't suggestions but requirements?

The problem with unstructured AI coding

When you give an AI coding agent an unstructured prompt like "fix the auth bug," here's what typically happens:

1. The agent guesses at the root cause without investigation
2. It writes a fix without understanding the full impact
3. No tests are written for the fix
4. Security implications aren't checked
5. The change ships without review

This works for toy projects. For production code, it creates a whack-a-mole cycle of fixes that introduce new bugs.

MeowKit's thesis

AI agents need enforced discipline — hard gates, TDD, security scanning, and human approval — to ship production-quality code.

The key word is enforced. Not "recommended." Not "best practice." Enforced through hooks that block, gates that require approval, and rules that cannot be overridden.

Before and after

Before: unstructured

You: "Fix the auth bug"
AI:  *immediately edits auth.ts*
AI:  "I fixed the authentication issue by adding a null check."

No investigation. No tests. No review. Does the fix actually work? Nobody knows.

After: with MeowKit

You: "/meow:fix auth login fails after session expiry"

Phase 1 — Investigate:
  Root cause: session token refresh not called before expiry check

Phase 2 — Test:
  ✓ Wrote failing test: test_session_refresh_before_expiry_check

Phase 3 — Fix:
  ✓ Added refresh call in auth middleware
  ✓ Test passes

Phase 4 — Review:
  Architecture: PASS | Types: PASS | Security: PASS
  Verdict: PASS

Phase 5 — Ship:
  feat(auth): add token refresh before expiry check
  PR: https://github.com/org/repo/pull/42

Every step is visible. Every claim is verified. The fix is tested, reviewed, and shipped with a proper commit message.

Design decisions

Decision	Why
Two hard gates	The cost of a bad ship > the cost of a 30-second approval
TDD enforced	Failing tests before implementation prevents "tests that test nothing"
Zero external deps	No API keys, no services, no runtime installs — works offline
Exclusive file ownership	Each agent owns specific files — no merge conflicts
Security as architecture	4-layer defense runs on every task, not just audits
Context-engineered agents	Every agent declares what context it needs and what to do when blocked

What MeowKit does NOT do

• No proprietary formats — standard Markdown, readable by any tool
• No telemetry — all data stays project-local
• No experimental features — everything shipped is production-ready
• No external services — zero dependencies on third-party APIs

A note on usage

MeowKit is an open-source, community-driven project — not intended for commercial use. It exists to push the boundaries of what disciplined AI coding agents can do, and to share those learnings freely.

All contributions are welcome. Whether it's a new skill, a bug fix, a documentation improvement, or a wild idea for a new agent workflow — open a PR and let's build together.

Next steps

• Installation — get started in 2 minutes
• Philosophy — deeper dive into MeowKit's principles