Using MeowKit Productively

MeowKit's 7-phase workflow is a loop: gather context, act, verify, repeat. Productivity is not about typing prompts faster — it is about handing off pieces of that loop so you stop being the bottleneck. This guide shows which piece to hand off, which MeowKit primitive to reach for, and how to keep the memory and wiki subsystems fresh so every future session starts smarter than the last.

You hand off	Use it when	Reach for
The check	You're exploring or deciding	mk:verify, mk:evaluate, mk:review
The stop condition	You know what done looks like	/goal + mk:verify, /mk:loop
The trigger	Work happens outside your session on its own schedule	/loop, /schedule (host runtime)
The knowledge	A learning should outlive the session	## capture, mewkit wiki, mewkit trace

Host runtime primitives

/goal, /loop, and /schedule are loop primitives of the host runtime (recent Claude Code releases). MeowKit supplies the deterministic checks and recurring jobs that make them effective.

Right-size every task first

The cheapest productivity win is not running the full pipeline when you don't need it. MeowKit already routes for you — use the escape hatches it codifies instead of fighting the gates:

• Trivial edits (rename, typo, format) are classified TRIVIAL and routed to the cheapest model. Don't invoke /mk:cook for a one-line change.
• Simple bug fixes: /mk:fix with complexity=simple bypasses Gate 1 by design — the fix is the plan.
• One-shot domains: when scale-routing returns workflow=one-shot with zero blast radius, Gate 1 may be bypassed. Extend domain-complexity.csv with your project's safe fast-path domains so routing keeps matching reality.
• Everything else goes through the plan gate. Fighting it costs more than a 30-second plan.

Hand off the stop condition with /goal

Phase 3.6 (mk:verify) is a deterministic check — build, lint, typecheck, tests, coverage all pass or they don't. Deterministic criteria are exactly what goal-based loops need: an evaluator can check the condition without judgment calls, so the agent keeps iterating instead of declaring "good enough" early.

/goal run /mk:cook for the approved plan; do not stop until mk:verify
passes with zero failures. Stop after 5 tries.

Always set an explicit try cap. MeowKit's own autobuild pipeline caps its generator ⇄ evaluator loop at 3 rounds before escalating to a human — copy that discipline.

For scalar metrics (coverage percentage, bundle size, lint count), use /mk:loop instead: it runs bounded, git-tracked iterations and keeps or reverts each change based on the measured delta.

Hand off the trigger with /loop

The workflow ends at Phase 5 with a PR pushed — but CI results and review comments arrive on the external system's schedule, not yours. Instead of polling GitHub yourself:

/loop 15m check the open PR: address review comments with mk:respond-pr,
fix failing CI. Stop when the PR is merged.

mk:respond-pr triages each reviewer comment with verify-before-agree discipline, so the loop responds carefully instead of blindly accepting every suggestion.

Schedule the maintenance you keep forgetting

Several MeowKit maintenance jobs are documented as "quarterly" or "calendar reminder" — which in practice means never. They are mechanical, measurable, and perfect for /schedule:

Job	Command	Cadence
Memory prune (archive entries >90 days)	/mk:memory --prune	Monthly
Friction backlog review	mewkit trace propose	Weekly
SKILL.md length audit (>500 lines)	check from skill-authoring rules	Quarterly
Dead-weight audit	/mk:benchmark run --full + compare	Quarterly, and on every model upgrade
Wiki candidate review	mewkit wiki list → approve/reject	Weekly

Cloud environments

Scheduled routines run in a cloud environment that does not inherit your local shell. Verify required credentials (Jira tokens, MEOWKIT_* variables) are configured there before moving a routine off your machine.

Keep memory fresh — capture while you work

Memory only compounds if entries actually land. MeowKit has two write paths (full architecture); the productive habit is using the keyboard shortcut path the moment a learning appears, not at session end:

##decision: chose advisory lock over row lock — row lock deadlocked under concurrent reassign
##pattern: bug-class N+1 in team roster query — always eager-load memberships
##note: staging DB resets every Monday 03:00 UTC

These route to the canonical .json stores via the capture hook, with injection validation and secret scrubbing built in. Phase 6 (Reflect) also captures at session end, but it can only capture what the session still remembers — mid-work capture beats end-of-session recall.

Two rules keep the stores healthy:

• JSON is canonical. The .md files are generated views. Never hand-edit them; regenerate with mewkit memory render-views after JSON changes.
• Prune on a schedule. /mk:memory --prune archives entries older than 90 days to lessons-archive.md (nothing is deleted). A store full of stale patterns is worse than an empty one — agents read it as current truth.

Keep the wiki current — a weekly gate, not a someday task

The wiki is MeowKit's long-term, provenance-bearing knowledge store. Its safety model is also why it goes stale: agents can only propose; only a human approve writes a canonical page. If you never review candidates, knowledge accumulates in the proposal queue and the wiki stops reflecting reality.

The maintenance loop that keeps it current:

1. Agents propose during work. Decision-heavy flows end by handing off their terminal artifact as a scanned candidate:

npx mewkit wiki propose            # propose a candidate (scanner-gated)
npx mewkit wiki handoff propose    # hand off a skill's terminal artifact

2. External knowledge enters as candidates too. Use mk:wiki-research (mewkit wiki enqueue / research) to fetch external sources — every fetched byte is scanned, size-capped, and secret-scrubbed before it can even become a candidate. Nothing external writes directly to canonical pages.

3. You review weekly. This is the step to protect with a recurring slot (or a /schedule reminder):

npx mewkit wiki list               # see pending candidates
npx mewkit wiki approve <id>       # re-runs the scanner, writes canonical page
npx mewkit wiki reject <id>

A weekly 10-minute review keeps the queue near zero. Approving in batches months later means re-verifying stale claims — the cost grows with the delay.

4. Recall closes the loop. Approved knowledge pays off at Phase 0, when agents probe the wiki before non-trivial work:

npx mewkit wiki context "payment retry idempotency" --max-pages 3 --json

If the probe keeps returning nothing for topics you know were decided, that is your signal the approval queue is backed up.

Turn friction into system improvements

When a loop stalls or you correct the agent by hand, don't stop at fixing the instance — record it:

npx mewkit trace --friction "evaluator passed a build with broken auth flow"

mewkit trace propose groups repeated friction (2+ occurrences) into advisory backlog items. When a friction item traces back to one skill, the natural place to encode the fix is that skill's Gotchas section — it exists to grow one bullet per observed failure. One recorded friction note is worth more than three silent workarounds.

The compounding cadence

When	Do	Why
During every task	##decision: / ##pattern: the moment you learn something	Mid-work capture beats end-of-session recall
After every intervention	mewkit trace --friction "<note>"	Repeated friction becomes a backlog item automatically
Weekly	Review wiki candidates; run mewkit trace propose	Keeps the wiki canonical and the harness improving
Monthly	/mk:memory --prune	Stale memory misleads agents
Quarterly / model upgrade	Dead-weight audit via /mk:benchmark	Scaffolding that helped last model may slow this one

None of these steps is large. The point is that each one feeds the next session: captured decisions become recalled context, recorded friction becomes harness fixes, approved candidates become Phase 0 answers. That is what "productive" means with an agent toolkit — not faster typing, but a system that gets smarter every week you use it.

Related

• Memory System — capture paths, JSON-first stores, pruning
• Workflow Phases (0–6) — where gates and verification sit
• Trace & Benchmark — friction recall and measured audits
• Model Routing — tier classification and escalation