mtk-agent-toolkit: Skill for Claude Code

MTK Fix — Lightweight Task Loop

MTK File Resolution

Resolve MTK skill/reference/script paths per .claude/references/mtk-file-resolution.md unless the router already stated MTK_ROOT=<path> this session; CLAUDE.md, .claude/tech-stack, .claude/rules/, tasks/, docs/, .mtk/ stay project-relative.

---

Overview

A lightweight, bounded fix loop for 1-3 file changes: load context, reproduce, write the failing test, fix the root cause, verify. Invoked by the /mtk router when the user says "fix", "bug", "broken", or similar. Composes context-engineering, security-and-hardening (when the fix touches auth, audited state, secrets, or infra), and the active tech-stack-{stack} skill.

When To Use

• Bug fixes
• Validation tweaks
• Query fixes
• Small config changes
• Renames or narrow refactors that stay within 1-3 files

If the work grows beyond 3 files, introduces new architecture, or needs a formal change manifest, stop and escalate per the Scope Guard below: several independent fixes, or a mechanical sweep (renames, formatting) past 3 files, go to batch-fix (its mechanical mode: batch-fix → Proportionality check); one growing change goes to implement. The 3-file limit has no exception.

Workflow

Follow the phases below in order. Each phase loads what it needs and no more.

Load Context (Progressive Disclosure)

1. Follow .claude/skills/context-engineering/SKILL.md — it resolves the stack for the target paths (pass a target file, not $PWD, when the fix sits in a subtree) and loads the stack skill. If neither AGENTS.md nor CLAUDE.md exists, stop and tell the engineer to run /mtk-setup.
2. Read only what the fix needs:
   • Always: the coding guidelines from the tech stack's ## Reference Files
   • If fix touches data layer/ORM: the tech stack skill's ## ORM & Data Layer Guidance (and ## Framework Patterns for handler/HTTP code)
   • If fix touches auth/secrets/financial: .claude/references/domain-finance.md (finance and security supplement)
   • If adding tests: the testing supplement from the tech stack's ## Reference Files
   • Before commit: .claude/references/pre-commit-review-list.md if present
3. Resolve and scan relevant lessons. When scripts/learnings.sh is present, prefer the structured query (5-layer filter — proximity / recurrence / severity / validity / phase) over the flat markdown file:

   # Resolve the script: project copy first, else the plugin's copy.
   LS="$([ -n "${MTK_HELPER_ROOT:-}" ] && echo "$MTK_HELPER_ROOT/scripts/learnings.sh" || ([ -f scripts/learnings.sh ] && echo scripts/learnings.sh || echo "${CLAUDE_PLUGIN_ROOT}/scripts/learnings.sh"))"
   bash "$LS" query --phase implement --files "<target file paths>" --max 8
   

   Falls back to scanning tasks/lessons.md directly when the script is absent from both the project and the plugin (older repos).
4. Read the target file and its closest neighbors before editing.