How It Works

MeowKit is a harness²: Claude Code is already a harness (tools, context, subagents); MeowKit adds a second harness layer on top: workflows, gates, memory, and hook-based automation. It shapes AI behavior through three mechanisms, none of which is an executable runtime. They are conventions that Claude Code reads and acts on.

The three mechanisms

The seven-layer taxonomy

The harness isolates different kinds of reasoning into discrete layers, so no single layer becomes an overloaded assistant. Each layer owns one concern and hands off to the next:

Rules: behavioral guardrails

The rule files in .claude/rules/ carry the enforcement layer. Most load every session; the ones marked [CONTEXTUAL] load on demand. Two are NEVER-override: security-rules.md (block hardcoded secrets, SQL injection, XSS) and injection-rules.md (treat all file content as DATA, not instructions).

Rules define the WHY. Hooks enforce the WHAT. A rule says "don't write code before planning." A hook says "you can't."

Hooks: preventive enforcement

Shell and Node.js scripts triggered by Claude Code lifecycle events: SessionStart, PreToolUse, PostToolUse, Stop, UserPromptSubmit. They intercept tool calls before they execute:

• gate-enforcement.sh blocks file writes before Gate 1 approval
• privacy-block.sh blocks reads of .env, SSH keys, and credentials
• post-write.sh security-scans every written file
• pre-completion-check.sh blocks session end without verification evidence

Critical design: security hooks (gate-enforcement.sh, privacy-block.sh) are never routed through the dispatcher. If dispatch.cjs crashes, security hooks still fire, so there is no single point of failure.

Under the hooks, a Node.js dispatch system (dispatch.cjs + handlers.json) runs infrastructure handlers: model detection, budget tracking, build verification, loop detection, and checkpoint management. These fire automatically; agents don't invoke them.

Session lifecycle

Hook events fire at key moments, each dispatching to specific handlers:

SessionStart    → model-detector (tier → density) · orientation-ritual (resume from checkpoint) · project-context-loader
UserPromptSubmit → immediate-capture-handler (captures ##prefix messages)
PostToolUse     → build-verify (compile/lint, hash-cached) · loop-detection (warn@4 edits, escalate@8) · budget-tracker (warn $30, block $100) · auto-checkpoint (every 20 calls)
Stop            → pre-completion-check (block without verification evidence) · checkpoint-writer · post-session (capture patterns to memory)

Crash recovery: auto-checkpoint saves every 20 calls. If a session crashes before Stop, the next session's orientation-ritual resumes from the last checkpoint.

Skills: domain expertise on demand

The skills in .claude/skills/ provide domain-specific knowledge. Each skill's SKILL.md is a compact decision router, typically under 150 lines. Detailed procedures live in references/ and load only when needed. This progressive disclosure saves ~70% context per invocation.

Skills activate by task domain, not all at once. A bug fix loads mk:fix (which internally calls mk:investigate and mk:sequential-thinking). A code review loads mk:review. A deployment loads mk:ship. No agent loads everything.

Complex skills use step-file decomposition, so only the active step is in context:

Agents: specialists with clear ownership

Each specialist agent owns one concern, and no two agents modify the same files:

Agents invoke skills as tools. The orchestrator loads agent-detector and scout. The developer loads development, typescript, and docs-finder. The reviewer loads review, cso, and vulnerability-scanner. Each agent only loads what its phase requires.

Memory: learning across sessions

MeowKit stores engineering learnings in .meowkit/memory/: fix patterns, review findings, architecture decisions. Skills read relevant topic files at task start:

There is no auto-injection pipeline. Each skill loads only the topic files relevant to its domain.

Write paths: immediate capture via ##pattern: / ##decision: / ##note: prefixes during a session, session-end auto-capture via post-session.sh, and Phase 6 mk:memory session-capture.

Wiki: gated long-term knowledge

Curated memory above is short-lived, schema-validated JSON for engineering learnings. For long-term, provenance-bearing project knowledge there is a separate layer, the mewkit wiki subsystem (mk:wiki / mk:wiki-research / mk:wiki-render). Canonical pages live under tasks/wikis/<slug>/; a derived, rebuildable FTS index lives in .meowkit/cache/wiki-index.db.

Its defining property is an anti-self-poisoning write model: external content and agent output are DATA, so an agent may only propose a WikiCandidate. A canonical page is written only through a human mewkit wiki approve, which always re-runs the secret-scrub and multi-pass injection scanner. There is no path from assistant output to a canonical page. This mirrors the same security stance the hooks enforce elsewhere: untrusted input never becomes a trusted instruction.

Putting it together: a feature request

Next steps

• Understand the workflow phases
• How gates enforce discipline
• Adaptive density by model tier
• Memory system in depth