v2.5.0 — The Native Fit Release

A release that makes the installed kit feel native to your project instead of bolted-on. Skills stop describing "MeowKit's workflow" and start describing the workflow. Dozens of hardcoded paths, phantom references, and ambiguous triggers are cleaned up. Three knowledge-accumulating skills (meow:evaluate, meow:benchmark, meow:party) finally persist across sessions. A CLAUDE.md arbitration rule ends the dual-orchestrator race between meow:cook and meow:workflow-orchestrator.

Highlights

• Brand leakage swept from skill bodies — ~70 user-facing phrases rewritten so installed skills refer to "the project", "this workflow", "the kit" instead of "MeowKit's X". Real infrastructure names (meowkit-* binaries, MEOWKIT_* env vars, CLI commands, frontmatter source: fields) are preserved.
• 64-skill audit, shipped — mechanical cleanup (34 hardcoded /Users/sangnguyen/... paths stripped, 6 dead /codex review rows removed), reference fixes (/meow:budget clarified, /meow:plan alias documented, ~/.claude/plans/ made project-relative), boundary disambiguation (7 collision clusters), and architecture wiring (memory writes + orchestrator arbitration).
• Memory persistence for evaluate / benchmark / party — verdicts land in .claude/memory/review-patterns.md, baselines in cost-log.json, architectural decisions in decisions.md. No more evaluation results evaporating at session end.
• Dual-orchestrator arbitration — CLAUDE.md now has an explicit rule: explicit /meow:cook wins; meow:workflow-orchestrator defers. No more duplicate Gate 1 enforcement or silent skip depending on execution order.
• Frontmatter schema documented — preamble-tier, user-invocable, phase, trust_level, injection_risk are now first-class fields with defined semantics in CLAUDE.md. Twenty-one skills were using preamble-tier: 3 without a schema — the field is now defined, not ignored.
• A6 citation hygiene — fabricated OWASP Top 10:2025 label replaced with "2021 ranking, 2025 threat context" + disclaimer; stale 57 font pairings count fixed to 73 (CSV was already ahead); invented BMAD ~10% pivot frequency statistic removed; preview model IDs in meow:multimodal now carry a staleness warning.

The Kit Reframing

The substantive shift: when a user runs npx mewkit init, the installed skills should read as your project's workflow, not as promotional copy for the kit itself.

Before

## Completeness Principle — Boil the Lake

Tell the user: "MeowKit follows the **Boil the Lake** principle..."

> Help MeowKit get better! Community mode shares usage data...
> we just learn that *someone* used MeowKit

| Task type | Human team | MeowKit | Compression |

After

## Completeness Principle — Boil the Lake

Tell the user: "This workflow follows the **Boil the Lake** principle..."

> Help improve this workflow! Community mode shares usage data...
> we just learn that *someone* used this workflow

| Task type | Human team | AI-assisted | Compression |

Same principle, same mechanism, same telemetry — presented as the project's workflow rather than as a third-party product the user is embedded in.

What stayed branded (by design)

Category	Example	Why it stayed
Real binaries	.claude/scripts/bin/meowkit-config	Actual executable name — renaming breaks things
CLI commands	npx mewkit init, npx meowkit upgrade	Real npm commands
Env vars	MEOWKIT_TDD, MEOWKIT_HARNESS_MODE	Real config keys
Frontmatter	source: meowkit, adapted_for: meowkit	Provenance metadata, not body prose
Config keys	meowkit_contributor in .claude/config	Real key
Contributor mode	Hey MeowKit team — field reports	Gated by _CONTRIB=true; never fires unless explicitly enabled
Author signature	Personal note in meow:office-hours YC encouragement	Creator voice, intentional

The 64-Skill Audit

Seven parallel red-team agents audited the 64 non-legacy skills across five dimensions. Findings were deduplicated across phases and executed in sequence from lowest to highest blast radius.

Phase 1 — Mechanical cleanup

• 34 hardcoded /Users/sangnguyen/Desktop/compare-kit/... lines stripped from meow:angular/references/*.md (10 files, source-import metadata with zero runtime value)
• 6 dead /codex review rows removed from shared-protocol tables (browse, document-release, investigate, office-hours, plan-ceo-review, retro) — references to the OpenAI Codex CLI, not a meowkit skill
• 7 claudekit-engineer prose leaks genericized in body HTML comments, script headers, and reference attributions (frontmatter source: policy-preserved)

Phase 2 — Broken references + implementation drift

• meow:memory — /meow:budget clarified as a subcommand of meow:memory, not a standalone skill
• meow:help — /meow:plan alias confirmed via slash-command router at .claude/commands/meow/plan.md, now documented
• meow:ship — memory-read instruction added for .claude/memory/architecture-decisions.md (the lone outlier among memory-claiming skills)
• meow:review + meow:ship — plan-lookup paths made project-relative (.claude/plans/, tasks/plans/); ~/.claude/plans/ retained only as legacy fallback with explanatory comment
• meow:careful — FLUSHDB severity aligned to CRITICAL (matches script); audit-trail log now appended to .claude/memory/security-log.md on every warn/override
• meow:benchmark — run-canary.sh documented accurately as step-1-of-2 manifest emitter; compare-runs.sh now distinguishes null (PENDING, excluded) from 0 (valid zero score)
• meow:docs-finder — Node.js 18+ prerequisite documented; unbounded cache growth noted in Gotchas
• meow:investigate — freeze hook clarified as a no-op without an explicit meow:freeze <target-dir> invocation
• A6 citation fixes (5 fabrications/stale counts)

Phase 3 — Semantic boundaries

Seven collision clusters each got mutual disambiguation:

Cluster	Before	After
agent-browser vs playwright-cli	Near-identical triggers; routing rule buried in qa-manual	Both skills declare use-when/instead-when at the top
intake vs jira	Both claimed "analyze ticket"	jira description narrowed to CRUD; analysis routed to intake
cook vs harness	meow:cook "ALWAYS activate" masked harness for green-field builds	Cook's intent table now carries an explicit escalation note
simplify vs clean-code	Ambiguous scope	simplify = post-diff; clean-code = anytime quality enforcement
docs-init vs project-context	Unclear ownership of docs/project-context.md	docs-init generates the suite; project-context generates only the constitution
lint-and-validate vs verify	Which runs what	verify = full pipeline; lint-and-validate = lint-only quick check
validate-plan vs sprint-contract	Same name, different targets	validate-plan = cook flow; sprint-contract = harness sprints

Plus "NOT this skill if:" differentiators added to the reasoning cluster (elicit / brainstorming / problem-solving), scale-routing marked user-invocable: false, and meow:workflow-orchestrator's bare "implement" trigger (which fired autoInvoke:true on trivial requests) narrowed to "implement feature".

Phase 4 — Architecture wiring

Three skills that accumulate structured knowledge now persist it:

Skill	Writes to	What survives session end
meow:evaluate	.claude/memory/review-patterns.md	Per-evaluation verdict row with top-criterion + score
meow:benchmark	.claude/memory/cost-log.json	Baseline entry (tier, pass rate, avg score, cost)
meow:party	.claude/memory/decisions.md	Decision record (context + decision + rationale + dissent)

Each writer runs mkdir -p .claude/memory before the append. meow:party's write is now required, not a post-hoc manual note.

Phase 4 — Orchestrator arbitration rule (in CLAUDE.md)

Explicit /meow:cook invocation   → meow:cook owns the pipeline.
                                    meow:workflow-orchestrator does NOT activate
                                    for the remainder of the session.
Session start, complex intent    → meow:workflow-orchestrator activates via autoInvoke.
                                    Defers to meow:cook for single-task requests.
Never both in the same session.

meow:workflow-orchestrator/SKILL.md carries a pointer to this rule.

Phase 4 — Frontmatter schema

Six skills gained explicit phase anchoring (phase: on-demand): chom, clean-code, docs-finder, docs-init, lint-and-validate, multimodal. meow:jira corrected from phase: 3 → phase: on-demand. Antigravity-kit-sourced skills (clean-code, lint-and-validate) gained trust_level: third-party + injection_risk: low provenance markers.

Frontmatter Schema (now documented in CLAUDE.md)

Field	Values	Meaning
preamble-tier	1 | 2 | 3	Context-injection priority. 3 = injected before other context.
user-invocable	true | false (default true)	false = internal sub-skill; orchestrator-invoked only
phase	0-6 | on-demand	Workflow phase anchor; on-demand = invoked by need, not by phase
trust_level	kit-authored | third-party	Provenance marker
injection_risk	low | medium | high	Advisory prompt-injection exposure level

All five are advisory (not hook-enforced). Twenty-one skills were already using preamble-tier: 3 without a documented schema — the field is now defined.

A6 Citation Hygiene (Grounding Findings)

Skill	Fix
meow:ui-design-system	57 font pairings → 73 (CSV has 73 data rows)
meow:brainstorming	Removed invented BMAD ~10% pivot frequency statistic
meow:vulnerability-scanner	OWASP Top 10:2025 (no such release) → OWASP Top 10 (2021 ranking, 2025 threat context) + disclaimer
meow:multimodal	gemini-3.1-* and veo-3.1-* preview IDs now carry a verify-before-deploy warning
meow:scout / meow:docs-finder	P1-P8 / P1-P14 citation labels dropped (neither Anthropic research doc uses those labels)

Files Changed

Area	Files
Audit fixes	61 skill files + CLAUDE.md (orchestrator rule + schema section)
Brand reframing	~50 skill body files (headings, prose, table columns, cross-refs)
Docs	website/guide/whats-new/v2.5.0.md, website/guide/whats-new.md, website/changelog.md, website/.vitepress/config.ts sidebar, website/guide/memory-system.md, website/guide/agent-skill-architecture.md
Release metadata	RELEASING.md (Release History row)

Upgrade

npx mewkit upgrade

Fresh install: npx mewkit init.

Existing .claude/memory/ topic files are preserved. Skills that now write to review-patterns.md, cost-log.json, or decisions.md will mkdir -p safely if the parent directory is missing.

Migration notes

No breaking changes. Two behavior shifts worth noting:

• meow:workflow-orchestrator no longer fires on bare "implement" — use compound triggers ("implement feature", "build feature", "complex task") or invoke /meow:cook explicitly. If a session you depend on was relying on bare-word activation, update the invocation.
• meow:party memory write is now mandatory, not optional — the decision record lands in .claude/memory/decisions.md. If you have a shell that blocks writes to .claude/memory/, whitelist the directory or the party session will fail at synthesis time.