How MTK works,
feature by feature.

Forces the spec to be written before code. It classifies scope, surfaces assumptions, runs an ambiguity gate, drafts the spec sections (including EARS requirements), and persists both a markdown spec and a machine-parseable JSON sidecar under docs/specs/. Implementation never begins inside this skill — it hard-stops at the approval gate. The skill is phase-locked (a written Tool discipline note) to write only spec artifacts, never source or test code.

Runs a decision graph (trivial? multi-file? longer than a short session?) then a workflow: (1) load standards; (4b) dirty-worktree scan via git status --porcelain — unlisted modified/untracked paths are recorded as dirty-worktree risks and added to out_of_scope; (6) ambiguity gate via AskUserQuestion, batched for 1-2 ambiguities (cap 4 questions) or Socratic interview mode for ≥3 ambiguities (one question per round, cap 5 rounds); (7) draft Summary/Success criteria/Architecture/Security impact/Change manifest/Test manifest/Batches/Risks/Open questions/Requirements; (8) elegance check; (8b) Claude-Ready (INVEST+C) check against .claude/references/claude-ready-checklist.md (specs scoring ≤13/16 sent back to draft); Constitution Check via bash scripts/constitution-digest.sh; (8c) prior-work-check; (9) persist with version-suffix detection (-v2, -v3); (9.5) bash scripts/lint-ears.sh; (10) hand to Phase 2.5 approval gate. On approval the implement gate records a SHA-256 approval seal via scripts/workflow-artifact.sh seal. (9.6) After the spec is on disk, it additively publishes the spec as a capability-gated Claude Artifact — the first section of one browsable per-workflow URL (keyed to workflow_uuid) that later phases update in place. Disk stays the source of truth; the step is a silent no-op when the Artifact tool is unavailable or MTK_ARTIFACT_PUBLISH=0.

Converts the approved change manifest into batches of 2-4 related files, each with acceptance criteria, a verification step, a Boundary (what it must not leak into), a Depends list, and cited governing-constraint ids. Writes tasks/todo.md and appends a plan section to the JSON handoff. Runs a fresh prior-work-check if the spec is stale, and dispatches plan-gap-reviewer before the approval gate. Like spec-driven, it is phase-locked to write only plan/todo artifacts.

Starts from the approved change/test manifests; (1a) prior-work freshness check re-runs prior-work-check if the spec's ## Prior Work Check section is missing or was generated more than one session ago (different branch HEAD, different day); (4b) package-legitimacy gate for any new third-party dependency — runs the stack's registry-verification (dependency-intake-checklist.md criterion 0), tags the package [ASSUMED], and inserts a checkpoint:human-verify step that blocks MTK_AUTO_PROCEED; (8) appends the plan section to the JSON handoff (every batch files entry must already exist in the top-level change_manifest, else re-plan); (10) records plan/todo paths on the workflow artifact and leaves plan_trust_gate at pending — only the engineer's Phase 2.5 approval flips it to pass; (11) dispatches plan-gap-reviewer with the request + plan path + spec md + sidecar + todo for the cross-artifact consistency check. After recording plan/todo paths it updates the same workflow Artifact in place (adding the Plan section, reusing the recorded results.artifact_url rather than minting a new link) per .claude/references/artifact-publishing.md — additive, capability-gated, silent no-op when unavailable or MTK_ARTIFACT_PUBLISH=0.

Explores the design space before committing to one approach. The default light path explores context, asks clarifying questions one at a time, proposes 2-3 approaches with pros/cons/effort/fits-when, recommends one, gets approval, and persists the decision. For architecture-shaping decisions it switches to divergence mode, generating approaches in isolated parallel subagents followed by a critic pass. No implementation happens during brainstorming — not even a quick prototype.

Default single-context workflow is 6 steps ending in explicit approval + persistence. Divergence mode (entered for architecture-shaping decisions — new bounded context, persistence target, cross-slice contract, irreversible migration — or on explicit wide-exploration request; self-declares its ~6-10 agent-call cost and confirms first): Phase 1 Diverge picks 3-5 frames from .claude/references/divergence-frames.md (always ≥1 adversarial fintech frame — F-REG/F-FRD/F-AUD — when money/auth/audited state is touched), spawns one isolated subagent per frame in a single parallel message, each banning the first three obvious answers and returning JSON only. Phase 2 Focus is an orchestrator-side critic pass that scores novelty/viability/fit, clusters by angle, flags traps, deepens the top 2-3 survivors, and produces a mandatory Trap Register that carries forward into the spec's "Rejected alternatives".

Before code is written, three deterministic queries run against the repo: search_prior_work (find an existing implementation under any name), get_constraints (surface the rules and lessons that govern the area), and get_risk_profile (map the change to a risk surface). It reports findings with severity and emits a verdict; a BLOCK finding holds the approval gate. It only reports — it never edits files.

Query 1 extracts 2-4 capability keywords from the spec summary/success_criteria and runs parallel grep -rn -i across the active stack's source roots plus bash scripts/query-code-index.sh find (when CODE_INDEX.md exists) or an MCP code-index tool such as mcp__gitnexus__query / mcp__ast-index__* when available. Query 2 greps tasks/lessons.md, .claude/lessons/personal.md, architecture-principles.md, CLAUDE.md, and matching .claude/rules/*.md, grading each hit block/flag/note. Query 3 classifies every change_manifest[].path as regulated/boundary/shared/isolated and compares against the declared security_impact. Verdict: any BLOCK → BLOCKED, any FLAG → PROCEED_WITH_CHANGES, only NOTE (or none) → PASS. Output is appended under a ## Prior Work Check section in the spec.

Reviews a saved plan as if it has never seen it before, deliberately refusing to read lessons, prior reviewer output, planner rationale, or the workflow artifact so it is not anchored by the planner's confidence. It verifies the plan against the real repo and cross-checks the spec sidecar and todo for consistency. It returns findings only — it never approves, edits, or rewrites the plan.

sonnet / read-only. Mandatory anti-anchoring rules forbid reading tasks/lessons.md, .claude/lessons/personal.md, .mtk/workflows/{uuid}.json, or prior reviewer/planner notes. Verifies every named path exists (or the plan says 'create'), every assumed import is in the manifest, integration points are addressed, and execution order never imports a later phase's output. Cross-artifact check maps spec change_manifest ↔ plan batches ↔ tasks/todo.md ↔ success_criteria/test_manifest. Dirty-worktree rejection: a batch touching an out_of_scope dirty-worktree path is always BLOCKING. Uses exactly the fixed finding categories (repo_mismatches, missing_surfaces, execution_order_issues, hidden_assumptions, under_scoped_integrations, open_decisions_presented_as_settled, cross_artifact_inconsistencies, dirty_worktree_overlap) with BLOCKING/ADVISORY severity; verdict PASS | FINDINGS.

Provides distinct frames, each an entire vantage a divergence subagent must reason from and nothing else. It includes fintech-specific adversarial frames — F-REG (Regulator), F-AUD (Auditor), F-FRD (Fraudster), F-BOQ (Back Office at Quarter End) — and general ones: F-3AM (3 AM On-Call), F-INV (Inversion), F-Z0B ($0 Budget), F-RLA (Remove the Load-Bearing Assumption), F-HCP (Hostile Competitor), and F-10Y (10-Year Maintenance). Each frame states what it optimises for and a trap to register.

Brainstorming picks 3-5 maximally-distinct frames (always ≥1 adversarial fintech frame when money/auth/audited state is touched) and spawns one isolated subagent per frame with only the problem statement plus its frame prompt. The orchestrator critic then scores each proposal 1-5 on Novelty and Viability with Fit binary, clusters by angle, deepens the top 2-3, and must register a trap for any framing where two selected frames collapse to the same analysis.

Every requirement-bearing bullet in a spec uses one of five EARS templates — Ubiquitous, Event-driven, State-driven, Optional, Unwanted — so each requirement has a testable trigger-and-response shape. The ANT (Anti-Null-Tautology) check then rejects any requirement that cannot be falsified. lint-ears.sh enforces both, scoped only to the ## Requirements section.

spec-driven step 7 requires EARS bullets in ## Requirements; step 9.5 runs lint-ears.sh with zero violations required before handing to the gate. The lint's ANT phrase list (case-insensitive substring match) flags tautologies including "be reliable / be performant / be scalable / be secure / be robust / be clean / be maintainable / be efficient", "follow best practices", "be production-ready", and vague "where appropriate / as needed / if necessary". It scopes only to the ## Requirements subsections; narrative sections (Summary, Risks, Goals) are not checked.

Instead of a binary 'small vs big change', MTK computes a numeric rigor score from the approved plan and maps it to one of four levels. The level dials three things: whether Phase 3 runs inline or via subagents, which Stage-2 reviewers run, and whether MTK_AUTO_PROCEED is even eligible.

Points: +1 per batch, +1 per 3 non-mechanical files (rounded up), +3 if security_impact != none, +1 per public contract added/modified (cap +4), +3 if scope == breaking-change. Bands: <=3 LIGHT, 4-7 STANDARD, 8-11 HIGH, >=12 MAX. A hard-trigger floor forces at least HIGH whenever plan.batches.length >= 3, >= 6 non-mechanical change_manifest entries, or security_impact != none — the score scales ceremony continuously between those long-standing triggers but never relaxes them. HIGH/MAX force the subagent path, add reviewers (MAX adds silent-failure-hunter), and make MTK_AUTO_PROCEED ineligible.

The single hard stop that separates planning from building. It renders the plan and todo inline in the terminal (not just file paths), shows the rigor level and the full downstream gate sequence, and then asks the engineer how to proceed via AskUserQuestion. Until they answer, only read-only Bash is allowed — no Edit/Write on source, no Phase 3.

On approval it records scripts/workflow-artifact.sh gate "$MTK_WF_UUID" plan_trust_gate pass and then seals the approved artifacts via scripts/workflow-artifact.sh seal "$MTK_WF_UUID" — binding the exact approved bytes of the recorded spec/plan (the mutable todo is not sealed) so a later edit can't silently keep the approval (verification-before-completion re-checks with verify-seal, and hooks/spec-approval-trigger.sh re-queues this gate on any post-approval edit to a sealed artifact); Revise/Edit first leave the gate pending and do not seal. Approve & run until done sets autonomous mode — Phases 3-7 never call AskUserQuestion again (the loop stops and reports instead), except the structural Phase 2.5 re-open forced by non-auto-fixable drift. If AskUserQuestion is deferred it's loaded via ToolSearch select:AskUserQuestion; if the harness (Cursor/Copilot CLI/Gemini CLI) can't expose it, the loop prints one line and waits rather than proceeding. Full gate semantics live in .claude/references/orchestration-gates.md.

A spec-quality gate that extends Bill Wake's INVEST with a Claude-Ready ('+C') dimension: a spec must be self-sufficient enough for an LLM to execute without asking clarifying questions. spec-driven-development applies it during Phase 1, and a spec failing 4+ items is revised before approval. It is effectively a diagnostic scorecard for specs — the plan-time sibling of the repo-health scorecard.

The reference defines two parts. Classic INVEST is six story-level checks (Independent, Negotiable, Valuable, Estimable, Small, Testable), each with pass criteria. The +C dimension is 16 numbered Claude-Ready items: concrete file paths, named pattern references, runnable verification commands, explicit out-of-scope, a security_impact enum value, dependency pins, data-model deltas, enumerated public_contracts, boundary preserved, local pattern verified, no 'obvious' steps, lessons consulted, prior-work checked, risks named, rollback plan, and test-manifest matching change-manifest. Scoring bands: 14–16 = approved-ready (hand to planning), 11–13 = needs tightening, ≤10 = back to draft. plan-gap-reviewer and compliance-reviewer cite items by their stable numbers.

Bars any completion claim that isn't backed by fresh output from an actual command run. 'Should work', 'probably fixed', and 'looks correct' are explicitly not verification. It verifies the spec's frozen success_criteria one at a time — each carrying an evidence_channel and a pre-declared observable — and states results as a criterion | verdict | evidence table where every verdict is binary.

Enforces a verification contract: each criterion has an evidence_channel from a fixed taxonomy (test-run, build-output, http-probe, cli-stdout, db-state-diff, browser, smoke-boot, log-capture, script-output) and an observable declared before execution. Criteria are frozen at Phase 2.5; a tamper check (git diff <approval-ref>..HEAD on the criteria block) is fail-closed and re-opens Phase 2.5 if a goalpost moved (invariant F15). When the workflow carries an approval_seal, scripts/workflow-artifact.sh verify-seal "$MTK_WF_UUID" is the authoritative pre-completion check — stronger than the criteria diff because it binds the exact approved bytes of spec+plan+todo — and a STALE seal (exit 1) is fail-closed and re-opens Phase 2.5. The re-arm rule resets criteria to re-armed after any post-verification edit. A Claim Extraction procedure reconciles every upstream-agent claim to VERIFIED/CONTRADICTED/UNVERIFIABLE; hand-checked criteria persist a golden baseline under docs/specs/<slug>.baselines/<SCn>.txt. A wiring check runs scripts/validate-toolkit.sh --task-scoped <paths>. The browser channel follows .claude/references/evidence-capture.md; repeated failures drive the scripts/workflow-artifact.sh remediation circuit-breaker.

Verifies the implementation delivered exactly what the spec promised: nothing more, nothing less. It compares the real diff against the JSON sidecar's change_manifest, public_contracts, security_impact, and out_of_scope, emitting structured findings. In regulated environments drift means the Phase 2.5 approval didn't actually cover the shipped code, so it's caught before review, not after.

Loads the sidecar (scope, change_manifest, public_contracts, success_criteria, out_of_scope, security_impact), prefers the deterministic scripts/validate-handoff.sh for file/security drift (falls back to git diff --name-status), runs scripts/lint-ears.sh on the spec markdown (EARS/ANT lint), and checks the drift-axis table — file-list, public contract, security impact, out-of-scope, success criteria, ownership/cross-slice creep, dependency shift (lockfile diff), and usage drift (grepping call-sites of renamed contracts). It also runs scripts/monorepo-ripple.sh and compares against tagged principles in .claude/references/architecture-principles.md (S1.15: [EXTRACTED] blocks, [INFERRED:>=0.7] flags). Findings follow .claude/references/review-finding-schema.md with source: "drift"; any critical → NEEDS_CHANGES and flips phase_exit_gate fail.

Treats stubs, placeholders, and unwired components as incomplete implementation, not 'almost done.' It catalogs grep patterns for comment markers (TODO/FIXME/PLACEHOLDER), empty function bodies (NotImplementedException / NotImplementedError), suspect return values (null/[]/{}/""/0 on contracts that should produce data), mock/placeholder data in production code, empty React/JSX components, and — the silent class — handlers/routes/subscribers added but never registered where the system would call them.

Per-language grep patterns plus an unwired-component table mapping each surface (HTTP route, MediatR/CQRS handler, background job, React route, CLI subcommand, migration, feature flag) to the registry file where wiring must be verified. Severity guidance: empty body / NotImplementedException on an exposed public contract or mockData reachable from production routes → Critical (block); TODO added by this diff → High; pre-existing TODOs touched but not introduced → Low advisory. Explicit carve-outs (Python except: pass → route to silent-failure-hunter; @abstractmethod / interface declarations; nullable return types; test-directory fixtures) are not flagged.

Defines how a browser-based completion check produces real evidence instead of an unbacked assertion. When Playwright MCP is available it captures three artifacts around the observed behavior and persists them next to the spec; when MCP is unavailable it mandates an explicit textual fallback note — never a silent claim.

With Playwright MCP: browser_navigate to the state, then browser_take_screenshot, browser_console_messages, and browser_network_requests, persisted under docs/specs/<slug>.evidence/<criterion-id>/. Sensitive content is scrubbed before persisting (strip Authorization/Cookie/Set-Cookie headers and tokens from network.json, mask real account data in screenshots, scan console.log for leaked secrets); unscrubbable artifacts stay untracked and gitignored. The rule is absolute: a browser criterion cites either its artifact directory or an explicit no-MCP fallback note — there is no third option.

Reviews the changed diff as an adversary, not a collaborator, across correctness, readability, architectural fit, security, performance, and test quality. It fans work out to specialized reviewer agents, merges and dedupes their findings, then scores five dimensions 1-10 and issues a PASS or NEEDS_CHANGES verdict. It is read-only except for recording scores to the workflow artifact.

Optionally checks CI first via hooks/ci-status.sh and cached .mtk/analyzer-output.json. Loads CLAUDE.md, the active .claude/tech-stack skill's ## Reference Files, security-checklist.md, testing-patterns.md, performance-checklist.md, and the F1-F16 catalog in ai-failure-modes.md. Reviews 6 axes including stub detection (stub-detection.md). Routes agents: compliance-reviewer, test-reviewer, architecture-reviewer, silent-failure-hunter (when the diff matches an error-handling regex such as \b(catch|except|finally)\b, \.catch\(, \?\?, \|\|, @ts-ignore, it\.skip), and context-miner at HIGH/MAX rigor — run in parallel, findings merged and deduped by (file, line, rule). Categorizes findings per review-finding-schema.md after applying its False-Positive Exclusion List, then scores 5 dimensions with a file:line evidence quote each. Circuit-breaker: scripts/workflow-artifact.sh remediation "$MTK_WF_UUID" review_<dimension> --score <n> returns ESCALATE at MTK_MAX_REMEDIATION_ITERS (default 3) or on score plateau → stop and escalate to a human (orchestration-gates.md failure_stop_gate). Writes results.review_scores.<dimension> when MTK_WF_UUID is set.

Runs a fast, security-focused review on the staged diff only, checking a short list of critical rules. It runs a deterministic linter pass first, then a narrow AI pass for context-sensitive issues, and merges both into one schema-conformant verdict. It is built to run in seconds so engineers can run it before every commit.

Resolves MTK files via $CLAUDE_PLUGIN_ROOT or a plugin-cache find. Steps: git diff --cached; run hooks/pre-commit-linters.sh (source: "linter", confidence 100); merge cached .mtk/analyzer-output.json filtered to staged files (only if modified in the last 10 minutes — never runs the build itself); optional Roslyn DetectAntiPatterns via dotnet-claude-kit on .NET; dependency-introduction gate against dependency-intake-checklist.md (two Poor ratings block, one requires override); monorepo ripple via scripts/monorepo-ripple.sh; then the AI pass (source: "ai"). Checks 8 named rules (secrets, SQL injection, PII in logs, missing auth, missing audit, env secrets, IAM blast radius, dependency intake). Any critical at threshold → NEEDS_CHANGES.

Treats security and compliance as design constraints, not final-review polish. It identifies trust boundaries and checks that a change preserves confidentiality, integrity, auditability, and least privilege. It stops and asks rather than guessing when a requirement is unclear.

Reads CLAUDE.md and security-checklist.md first, then a domain supplement (e.g. domain-finance.md) if present. Identifies trust boundaries (user input, external service input, internal privileged ops); checks auth/authz, PII/secrets/logging, audit requirements for state changes, query safety / transaction boundaries / error exposure, and infra least-privilege / blast-radius / secret scope. Supply-chain step walks any new third-party dep through dependency-intake-checklist.md (two Poor block, one requires written override).

Simplifies only after behavior is proven: removes debug artifacts and dead code, collapses premature abstractions, and improves clarity without broadening scope or changing behavior. It walks a YAGNI 'less-code ladder' and stops at the first rung that satisfies the requirement. It has hard safety carve-outs it must never simplify away.

Starts from verified working code; finds the smallest simplifications; walks the less-code ladder (does it need to exist → stdlib/built-in → existing codebase capability → existing dependency → one line → minimum readable block). Never removes the safety carve-outs (auth/authz checks, secret handling, input validation, migrations, delete-guards, audit logging — all presumed load-bearing). Asks before deleting ambiguous dead code; re-runs build and tests. Directly counters F5 (defensive-guard bloat) and F10 (dead-code accretion).

Scans the repo's CODE_INDEX.md for near-duplicate capabilities and groups them by stem so they can be consolidated before they multiply. For each cluster of 2+ entries it emits the capability name, all entry points (path:symbol), and a consolidate / keep-separate recommendation. Output is a findings list only, never edits.

Reads CODE_INDEX.md (template code-index-template.md), extracts all capability rows, and normalizes stems (lowercase, drop suffixes like Async / _v2 / Impl) to group near-duplicates. Uses bash scripts/query-code-index.sh find "<keyword>" for targeted follow-up lookups (falls back to grep on older repos). Cross-checks the active stack's coding guidelines to pick the canonical implementation.

An adversarial reviewer persona ('hostile senior code reviewer at an investment bank') that gets no credit for approvals. It reviews the diff against CLAUDE.md, the coding guidelines, architecture principles, and neighboring files, enumerates untested public methods, and scores the five dimensions with file:line evidence. It emits the canonical schema output plus an untested-paths list and a short 'what's good' note.

opus / effort high / read-only. Step 1 loads the full standards stack: CLAUDE.md, the tech-stack skill + its ## Reference Files, all .claude/rules/*.md, the coding guidelines, architecture-principles.md, conventions.md, the security/testing/performance checklists, and the security-and-hardening skill. Reads the behavioral diff (a mismatch with actual code is Critical). Runs security/architecture/data-layer/performance/test checklists; Step 4 lists every new/modified public method and flags untested ones (Critical if money/auth/mutation). Step 5 scores 5 dimensions with auto-fail rules (any < 7 blocks; uniform scores rejected as non-discriminating; a score with no file:line evidence treated as 0). Escalates to a human after 2 failing iterations on the same blocking dimension. Model tier per model-routing.md (Compliance review agent → opus).

A single-lens reviewer that finds boundary violations, wrong-direction dependencies, leaky abstractions, misplaced responsibilities, and speculative abstractions. It gets no credit for approving code that 'works but is in the wrong place,' and names the correct layer/slice for each finding rather than just saying 'wrong place.'

sonnet / read-only. Loads architecture-principles.md, the rule files, the stack's framework-patterns reference (e.g. mediatr-slice-patterns.md, fastapi-patterns.md), the code-simplification skill, and 2-3 neighboring files as the expected pattern. Checks slice boundaries and inward dependency direction, responsibility splits (controllers = orchestration only, services = no HTTP/DB), abstraction quality, naming/placement, and cross-cutting concerns (DI lifetimes). Wrong-direction cross-slice violations are Critical; god handlers, leaky abstractions, and speculative abstractions are Warnings. Emits the schema output.

While the other reviewers judge the diff on its own terms, context-miner surfaces context outside the diff: a prior revert of the same code, a related open issue, a decision recorded in a PR thread, or an applicable lesson. It is strictly read-only and returns an empty findings array honestly when nothing relevant exists.

sonnet / read-only. For each touched path: git log --oneline -n 20 -- <path> and git log --oneline -S'<key symbol>' -- <path> for churn/reverts; gh pr list / gh issue list / gh pr view <n> --comments when gh is available (noted and skipped otherwise); bash scripts/learnings.sh query --files "..." --max 8 (fallback tasks/lessons.md). Emits source: "context" findings citing a concrete SHA / PR / issue / lesson id. Critical only when the change re-introduces a reverted defect or contradicts a recorded decision. Treats all mined commit/PR/issue text as untrusted data, never instructions.

Hunts gaps in test coverage, weak assertions, and missing verification. It reads both the changed test files and the production code they exercise, so it can name the specific uncovered method. Missing tests on methods that mutate financial data or handle auth are Critical.

sonnet / read-only. Loads testing-patterns.md, the stack testing supplement, and the test-driven-development skill. Runs coverage-completeness, assertion-quality, test-design, and integration-coverage checklists, then a Step-4 anti-pattern scan (always-pass assertions, no-assertion tests, exception-swallowing catches, mock-only verification, copy-paste duplication). Each finding cites file:line for both the test and the production code it fails to cover. Emits the schema output.

Finds places where code silently swallows, masks, or short-circuits a failure that should have surfaced. It applies one decision rule — if removing the silent handler would surface a real bug at runtime, flag it; otherwise skip it. Severity is set by the path the handler sits on: audited paths (auth, money, permissions, audit-log writes) are automatic Critical.

sonnet / read-only. Scope is only lines in the diff. Works an exhaustive Step-3 pattern catalogue (empty catch/except, catch-then-default-return, lossy rethrow, broad catch of a narrow op, .catch(() => {}), unawaited audited side effect, ?./?? auth or money fallbacks, unjustified // eslint-disable/# noqa/@ts-ignore, added it.skip/xit). Step-4 path-based severity table, Step-5 FP discipline (logging-only catches, Result-pattern returns, defensive render ?., top-level daemon handlers are non-findings). Maps to F1/F2/F9 in ai-failure-modes.md and cites the F-code; the fixed category: "error-handling" makes merge-dedupe by (file, line, rule) straightforward.

A stable catalog of the patterns where AI-assisted development produces incorrect or misleading output — from catch-all error swallowing (F1) and hardcoded-success stubs (F2) to hallucinated packages (F3), fake fallbacks (F9), frozen-replay evidence (F15), and unverified prose claims (F16). Each mode carries a stable id, a citation anchor, a severity, a C#-flavored bad/good pair, and an imperative rule for reviewers.

F1-F16 each carry severity (must-fix / should-fix / worth-noting) and a rule reviewers apply. Reviewers cite the F-code in the schema's failure_mode field so patterns aggregate across reviews: silent-failure-hunter maps to F1/F2/F9, code-simplification's ladder counters F5/F10, and the core/docdrift.txt linter pack mechanically catches a subset of F12. Citations anchor modes in external research (e.g. GitClear's 'Coding on Copilot' copy-paste analysis for F4).

A short, curatable checklist of the critical rules to verify before committing. In this repo the items are toolkit-specific (manifest entry per file, CSO single-sentence descriptions, version sync, skill anatomy, executable bash with set -euo pipefail, no hardcoded secrets, validate-toolkit passes, AGENTS.md routing). Teams add checks they care about and remove irrelevant ones.

Consumed inline by the implement/incremental and fix loops after each batch and by pre-commit-review before each commit. The generated version is augmented with the active stack's ## Pre-Commit Review Items (S2.13) so the list is repo-specific rather than generic.

A gate that runs whenever a dependency manifest changes. Criterion 0 (Existence & Legitimacy) runs first — a package must be verified against its live registry, and a Poor there is an immediate block (typosquat / dead repo / not found). Then criteria 1-5 (scope, maintenance, size, security, license) are each scored Good / Acceptable / Poor with an evidence-backed one-line rationale. Two Poors across criteria 1-5 block; any single Poor requires explicit engineer override.

Per-stack registry verification commands: dotnet package search <id> --exact-match, pip index versions <pkg>, npm view <pkg>, go list -m <module>@latest, cargo search <crate> --limit 5. Each Poor must cite concrete evidence (CVE/GHSA id for security, last-release/commit date for maintenance, du -sh or unpacked size for size, SPDX identifier for license) — a Poor without evidence is downgraded to Acceptable. Emits a dep_gate object into the workflow artifact results. Skips version bumps within the same major (vuln scan only) and internal/monorepo workspace deps; test/dev-only deps auto-pass a single size or license-acceptable Poor.

Every full review scores five named dimensions 1-10, each with a file:line evidence quote, and the scores — not the finding count — are the gate. Any dimension below 7 forces NEEDS_CHANGES; uniform scores across all five are rejected as 'non-discriminating'; a score with no evidence is treated as 0.

Dimensions are correctness, security, test_coverage, architecture_fit, simplicity; rubric 9-10 exemplary / 7-8 acceptable / 4-6 blocks / 1-3 severe. Auto-fail rules are enforced by the reviewers, not the schema. The remediation loop runs through scripts/workflow-artifact.sh remediation "$MTK_WF_UUID" review_<dimension> --score <n>, which returns ESCALATE at MTK_MAX_REMEDIATION_ITERS (default 3) or when a dimension's score plateaus (the compliance-reviewer and schema cap the same-dimension loop at 2 failing iterations, escalating a third). On ESCALATE, the workflow stops and escalates to a human per orchestration-gates.md failure_stop_gate. Scores persist to results.review_scores.<dimension> and results.review_iteration.

A small, dependency-tolerant helper that reports the CI status of the current branch as JSON, for the review workflow to fold into its assessment. If the gh CLI is missing or not authenticated, it exits cleanly with an 'available:false' result so review can proceed without CI context.

Checks command -v gh and gh auth status; resolves the branch (arg 1 or git branch --show-current). If a PR exists for the branch (gh pr view <branch> --json number --jq '.number'), it returns gh pr checks <pr> --json name,status,conclusion; otherwise it falls back to gh run list --branch <branch> --limit 1 --json status,conclusion,name,headSha. Output is a single JSON object. Every failure path degrades to a clean 'available:false' object rather than erroring.

A deterministic backward-compatibility linter. It reads the diff between the current branch and a base branch and looks only at removed lines to flag things that would break external consumers: deleted HTTP routes, removed public properties/fields on contract types, removed public methods, and touched OpenAPI/Swagger specs. Findings come out in the same schema the review workflow consumes.

Takes the diff via git diff <base>...HEAD, isolates removed lines, and branches on the active stack from .claude/tech-stack. For dotnet it regex-matches removed [HttpGet/Post/Put/Patch/Delete("...")] routes (critical), removed public properties on dto/request/response/model/contract/event files and removed public methods on controller/endpoint/handler/service files (warning). Python matches @app/@router decorators and dataclass/pydantic fields; TypeScript matches route handlers and exported interface/type properties. Any modified openapi/swagger file adds an API-SPEC-CHANGED warning. Findings carry source:"linter", confidence:100, and ids BC001, BC002, … escaped without jq per S3.3.

Converts raw compiler/linter output into structured, machine-checkable findings the review layer can trust at 100% confidence. It auto-detects the tool format, maps rule codes to severities, and normalizes everything into the shared finding schema — so a build error becomes a first-class review finding rather than a wall of text.

Accepts --format (msbuild|ruff|tsc|biome), --stack, --file, else reads stdin and auto-detects: JSON with "code" → ruff, other JSON → biome, (line,col): warning|error → msbuild, .tsx?(line,col) → tsc. Severity comes from hooks/analyzer-severity/<stack>.txt (tab-separated rule→severity, default warning); msbuild 'error' level is forced to critical. Each match is emitted with source:"analyzer", confidence:100, sequential ids A001, A002, …, escaped without jq per S3.3.

A tiny advisory guard for spec quality. It finds the most recently modified spec and checks that it declares a behavioral_diff — the field reviewers rely on to verify implementation intent. If the field is missing or empty, it prints a one-line nudge; it never blocks.

Scans docs/specs for *.json modified in the last day (most recent first). If the file lacks a "behavioral_diff" key it prints the 'no behavioral_diff' advisory; if the key exists but is empty ('""') it prints the 'empty behavioral_diff' advisory. Uses grep only, always exits 0 — non-blocking per the team's advisory-not-gate adoption strategy.

Re-runs setup's generators on an already-bootstrapped repo, but only for artifacts a deterministic plan marked stale/missing. It never re-audits blind and never silently overwrites a hand-edited file — engineer-edited files go through the diff-proposal contract. Refresh brings the docs back in line with the code (the inverse of converge).

STEP 0 preconditions (.claude/tech-stack + .claude/mtk-version.json must exist, else hard stop). STEP 1 scripts/setup-refresh-plan.sh --json is the sole staleness source. STEP 2 dry-run gate. STEP 3 scoped regeneration to temp paths: docs re-derive only claim lines whose anchors point into the git diff <stamp>..HEAD changed set (full re-audit only if the stamp is missing or >~30% of tracked source files changed); detected-tools.json re-run of audit STEP 2.6; reference re-pruning (ship-time only, never deletes); deterministic AGENTS.md/tool-config/index regen via generate-agents-md.sh, generate-tool-configs.sh --all, refresh-derived.sh (marker-refusal guards, never --force). STEP 4 applies regen-diff-contract.md per file; STEP 5 re-stamps + runs verify-claims.sh with the retry loop; STEP 6 four-count report. Writes to architecture-principles.md go through the shrink guard (S3.16).

The inverse of refresh: it treats architecture-principles.md/conventions.md as normative and reports where the codebase has drifted from what the team already agreed to. It produces graded (blocking/flag/note) work items, each traceable to a failing claim. Read-only outside .claude/.mtk-cache/.

STEP 0 preconditions (tech-stack + mtk-version + at least one <!-- mtk-stamp doc, else stop). STEP 1 runs verify-claims.sh against temp copies under /tmp/mtk-converge/ (never the tracked doc, since the engine rewrites in place), checking each exit code. STEP 2 pairs weak claims with changed paths via audit-drift-check.sh <doc> --json. STEP 3 grades from the ORIGINAL tag captured in each weak entry: [EXTRACTED]/[ENFORCED]→blocking, [INFERRED:N≥0.7]→flag, [INFERRED:N<0.7]/[AMBIGUOUS]→note. STEP 4 writes the report; STEP 5 optional todo append behind a non-skippable interactive gate. It never grades anything not traceable to a weak-claims entry.

A fast, read-only gate that answers "are the generated docs still accurate?" It runs the staleness plan and translates the exit code into a pass/fail verdict. Suitable for CI or a quick manual check; it never writes anything.

mtk-setup's inline --check workflow runs bash scripts/setup-refresh-plan.sh --check, prints its output verbatim, and propagates exit codes 0/1/2 into the three report lines. The plan script (read-only) evaluates seven artifact rows and fails (exit 1) if any non-informational row is stale or missing; the .claude/setup-answers.json row is informational only and never affects the gate.

Advances the pinned moberghr/coding-guidelines revision recorded in the manifest/version file to the remote HEAD and refreshes each file's sha256. It's an all-or-nothing pin update — it never applies the new guidelines itself; the engineer decides when to re-run setup.

Inline workflow. Validates the resolved SHA is 40-char hex (stops on network failure). Reads the pin from ${CLAUDE_PLUGIN_ROOT:-.}/.claude/manifest.json (fallback .claude/mtk-version.json). Fetches each file at the new SHA via curl -fsSL … | sha256sum, checks ${PIPESTATUS[0]} per file, and computes ALL hashes before any write (no partial pin updates). Write rule: never write into the plugin cache — a plugin-prefixed pin writes to the repo-local .claude/mtk-version.json coding-guidelines block, leaving other top-level keys untouched. Does not auto-invoke bootstrap.

An opt-in that skips the AskUserQuestion round-trip at Phase 2.5 by defaulting to Approve & run until done — but only when a strict set of preconditions all hold. If any condition fails, it MUST fall back to AskUserQuestion; it never overrides open decisions, unresolved assumptions, or the failure-stop gate.

Applied only when ALL hold: spec open_decisions empty; zero unresolved [ASSUMED] claims ([VERIFIED:path]/[CITED:url] don't block); no plan-gap-reviewer BLOCKING findings; no open checkpoint:human-verify for an externally-recommended package; skill_precedence_gate is pass; scope is not breaking-change or high security_impact; and rigor level is LIGHT or STANDARD (HIGH/MAX always get a human).

mtk-doctor is the holistic health check for an MTK installation. Where validate-toolkit.sh checks structural integrity, the doctor catches runtime rot: deprecated model IDs in agents, an oversized CLAUDE.md, missing gitignore entries, stale analytics, and dangling hook registrations. It reports PASS/WARN/FAIL and attaches a detail field to each check pointing at the fix.

The skill (allowed-tools: Read, Bash; argument-hint [--json] [--fix] [--strict]) runs scripts/mtk-doctor.sh, which records checks in six categories: CORE (required files, manifest resolution with a CLAUDE_PLUGIN_ROOT fallback, CLAUDE.md 200-line budget), COMPONENTS (manifest==plugin version sync, skill count, skill-name/directory match, a DEPRECATED_MODELS scan of agent frontmatter), HOOKS (registered hooks in .claude/settings.json exist and are executable, valid event names, every hooks/ script has set -euo pipefail), INTEGRITY (manifest paths exist, .gitignore coverage, analytics freshness >30 days, release-checksum verification via scripts/generate-checksums.sh, optional Ed25519 signature check when MTK_RELEASE_PUBLIC_KEY is set, and a composite run of validate-toolkit.sh), LESSONS (lints executable lesson contracts in .mtk/learnings.jsonl), and CONTEXT (always-on token baseline = CLAUDE.md + rules/INDEX.md + alwaysApply references, MCP schema count from .mcp.json, ENABLE_TOOL_SEARCH state — all report-only). Flags: --json (CI dashboards), --strict (WARN also exits 1), --fix (only gitignore additions + chmod, never FAILs, never source). Exit 1 on any FAIL.

A single periodic command that reports how ready a repo is as an AI work surface. It combines the 12-asset readiness scorecard (with a medal), PR-review mining of recurring reviewer feedback from recent merged PRs, and a derived top-3 actionable-changes list. It writes the combined report to disk and echoes the medal plus top-3 in chat.

Parses --prs N (1..50, default 10), --json, --no-mining. It always runs bash scripts/repo-health-score.sh (the scorecard). It runs a best-effort audit-drift check (scripts/audit-drift-check.sh) on CLAUDE.md, architecture-principles.md, and conventions.md — reading each doc's audited-against: SHA stamp and annotating the AI Context bucket with '🟨 audit drift: N citations' if cited files changed (a warning, never flipping pass to fail). Unless --no-mining, it runs bash scripts/pr-review-mine.sh --prs N, which is fail-soft (emits a Skipped: block when gh is missing or unauthenticated). It derives the top-3 by ranking ⬜ fails AI Context > Dev Workflow > Onboarding > mined phrases with ≥3 PR citations. It writes .claude/repo-health-latest.md always and .claude/repo-health-latest.json with --json (both gitignored). Mining is always suggest-only. After writing .claude/repo-health-latest.md it publishes the report as a Claude Artifact (standalone when run outside a workflow, else updating the active REVIEW workflow's artifact) per .claude/references/artifact-publishing.md — additive, capability-gated, silent no-op when unavailable or MTK_ARTIFACT_PUBLISH=0.

Reports how the team is actually using MTK — distinct from repo-health, which reports readiness of the repo itself. It reads the session analytics file plus on-disk artifacts, computes usage ratios, flags anomalies against tunable thresholds, and prints one concrete next action per flag. It is strictly read-only and refuses to draw conclusions from too little data.

It loads data sources in parallel: .claude/analytics.json (persisted by hooks/session-analytics.sh — sessions, total_operations, total_modifications, specs_created, lessons_captured, scope_guard_warnings, benchmarks_run, benchmark_last_score), the tasks/lessons.md '## ' count, docs/specs and docs/plans listings, and an MTK-scoped git log. It computes ops/session, specs/session, lessons/spec, and scope-guard rate, then flags anomalies against a threshold table (e.g. scope_guard_warnings/sessions < 0.3 is healthy; a mod/op ratio of 0.1–0.6 is healthy). It also runs bash scripts/learnings.sh metrics to surface decision_origin totals (user-directed, claude-recommended-approved/modified/rejected, system-inferred) and the π sycophancy index (warn only when the approved+modified+rejected denominator is ≥10), and bash scripts/skill-eval/coverage.sh --json for behavioral eval coverage_pct and overlap_candidates. It degrades gracefully on missing/corrupt/small samples and never writes analytics/lessons/specs.

A diagnostic snapshot of the MTK toolkit's currently-active configuration — what's loaded, what's not, and why. It shows the pinned tech stack, active domains, enabled linter packs with rule counts, rule files, hook registrations, review agents, reference coverage and footprint, and active specs. It's the tool to reach for when a review missed something or a linter pattern fired unexpectedly.

STEP 1 gathers state via dynamic !… bash blocks: tech stack (.claude/tech-stack, .claude/tech-stack-pm), domains (.claude/domains), linter packs under hooks/linter-patterns/{core, stack-<stack>, domain-<domain>, project} with non-comment rule counts, rules (.claude/rules/*.md line counts), hooks (events grepped from .claude/settings.json and hooks/hooks.json, plus git pre-commit executability), review agents (name + model from .claude/agents/*.md), references (shared + stack) and a footprint estimate at ~13 tokens/line, and active specs grouped by slug/version from docs/specs. STEP 2 presents a clean summary and warns on misconfiguration. It points to bash scripts/mtk-savings.sh for the full always-on/deferred/compression breakdown.

A visual, read-only view over the workflow artifacts. It reads the same {uuid}.json and {uuid}.events.jsonl files the workflow-artifacts skill writes and renders them as an HTML page showing status, current phase, gate decisions, results, and the event timeline. In --watch mode it serves a self-refreshing page so a tech lead can watch a multi-batch run live.

It only reads the artifact files — it never mutates them, so it is safe to run during an active workflow. A plain run renders once to .mtk/workflows/dashboard/index.html and opens it. --watch regenerates on an interval (default 5s) and serves a static page over http://127.0.0.1:8787/ by default (meta-refresh, no WebSocket); --watch 10 --port 9000 overrides interval and port. Requires python3 (the same dependency the helper already uses). The script intentionally stays a self-contained static renderer and embeds no tunnel.

The single natural-language entry point for everything except setup. You describe what you want in plain English and it classifies the intent, then loads the matching workflow skill and follows it end to end. It is explicitly a router: it does NOT do the work itself and it does NOT summarize your request — it delegates by reading the target skill and following every step.

The Routing Decision Graph is walked top to bottom, first match wins; the Route Table is the keyword/intent lookup that maps patterns to target skill files (fix, implement, pre-commit-review, repo-health, pr-review-mining, mtk-doctor, toolkit-health, research-context, context-report, claude-md-audit, claude-md-capture, promote-lesson, lesson-mining, handoff). Routing Rules: (1) strip and pass through flags --terse/--verbose/--staged-only/--preview/--merge/--non-interactive; (2) unambiguous -> route silently; (3) literal escalated from fix -> implement; (4) genuinely ambiguous (two rows, similar specificity) -> ask ONE question; (5) no input -> help; (6) pass the user's description through verbatim; (7) setup asks -> redirect to /mtk-setup, never absorb. Route Disambiguation (negative boundaries) encodes contested pairs (fix vs implement, research-context vs implement/fix, pre-commit-review vs code-review-and-quality, context-report vs toolkit-health, claude-md-capture vs handoff, promote-lesson vs lesson-mining, /mtk-setup vs implement/fix) to cut misroutes. A Red flags while routing table pre-empts common mis-route rationalizations (e.g. "user said 'fix' so just route to fix"). Before dispatch it applies Toolset Expansion (S2.19). Execution: read the target SKILL.md and follow every step including verification — the target skill owns its acceptance criteria.

A change that looked like a small fix sometimes turns out to be feature-sized once you're in it. Instead of doing multi-file work under the lightweight fix skill, the fix skill's Scope Guard emits the literal marker escalated from fix. The router detects the marker and routes straight to the full implement workflow.

In the Routing Decision Graph the first diamond after 'empty/help?' is the esc node ('contains escalated from fix?'), which on yes goes directly to implement — ahead of every keyword row. The Route Table lists escalated from fix as its top row, flagged 'internal self-escalation only'. Routing Rule 3 hardcodes: input literally containing escalated from fix routes straight to implement, and it is 'produced only by the fix Scope Guard'.

Workflow skills can declare which tool groups they need or must never touch. Before loading a target skill, the router reads its frontmatter and expands those declarations into a concrete tool scope, so (for example) a read-only review skill can't quietly start editing source code.

Read the target's frontmatter: required-toolsets: [<name>, ...] resolves via scripts/resolve-toolsets.sh into an advisory scope (don't invoke tools outside it without a written escalation note). forbidden-toolsets: [<name>, ...] makes those tools off-limits for the dispatch and wins on overlap. An explicit allowed-tools: in the skill takes precedence (no surprise widening) — toolset expansion is only for skills that leave tool scope to the dispatcher. When a skill declares toolsets, the resolved scope is logged to analytics via the existing hooks/session-analytics.sh pipeline so adoption is visible.

The source of truth for which model tier each workflow phase and review agent should run on. The expensive tier is spent only where capability changes the outcome — code that writes real logic and the adversarial reviews that protect serious software — while everything mechanical (discovery, structured comparison, bounded judgment) runs cheaper. This keeps a typical feature in the low-single-digit-dollars range without losing capability where it counts.

Two enforcement surfaces: review agents pin model: in frontmatter (enforced); workflow skills run on the user's session model (advisory recommendation only — skills can't self-select a model). The policy table maps each phase/role to a tier (e.g. setup discovery -> haiku; spec-driven-development/planning-and-task-breakdown/incremental-implementation/research-context/pre-commit review -> sonnet; compliance review/security-and-hardening/brainstorming/novel batch -> opus). Provider tier slots fast/default/strong abstract over the concrete Claude bindings (haiku/sonnet/opus) so a model rename is a one-line re-bind. subagent-implementation defaults per-batch implementers to sonnet, choosing opus only for a batch the plan flags novel/tricky. Overrides are allowed — the policy exists to stop the reflex of running everything on the top tier.

The rulebook every generator follows when emitting CLAUDE.md, architecture-principles.md, and conventions.md so the output is factually defensible. Each rule maps to a real failure mode from a client run that produced ~20 factual errors a single grep would have caught.

Eight numbered rule areas. (1) Rule tags [ENFORCED] (every sampled file), [CONVENTION] (≥80%), [ASPIRATIONAL] (stated intent), each requiring an evidence anchor; untagged rules quarantined to ## Untagged (review). (2) Transient-state ban with regex for branches/PRs/dates/emails/sprints. (3) No partial lists — enumerate fully or see <path>. (4) Terminology + LLM-prose-tic denylist (flag, don't rewrite). (5) Weak-claims surfacing ranked zero-hit anchor > terminology > partial list > no anchor. (6) audited-against: <sha> stamp read by audit-drift-check.sh. (7) Eat-our-own-dogfood (verify-claims.sh must run). (8) Live references over restated facts.

Defines exactly what happens when a generator re-runs over an existing file. It classifies each file against a cached ancestor and either overwrites (only when byte-identical to the last stock template), proposes the MTK delta hunk-by-hunk for engineer-edited files, or defers unresolvable hunks to Needs review. It guarantees the engineer's on-disk content is never destroyed.

Terms: ancestor (cached stock template at .claude/.mtk-cache/v<prev>/<file>) / current (on-disk) / fresh (this run's output). §2 classification: protected→SKIP; no current→write fresh (Created); current==ancestor→OVERWRITTEN (stock); current!=ancestor→engineer-edited (§3); ancestor missing→no-ancestor (§3a, additive-only, migration question). §3 proposes diff ancestor fresh hunks each with a reason; unclean hunks → Needs review (never force-applied, no conflict markers). §4 cache-update rule (only fully-resolved files re-seed the cache). §6 invariants: git merge-file --union banned, the AskUserQuestion gate is not skippable, non-interactive defers engineer-edited files, deletion is never an outcome.

The non-destructive contract governing all setup writes. Only MTK-owned files (provenance-stamped or on a known-generated-paths list) may be overwritten in place; everything else — nested CLAUDE.md, custom rules/references, lockfiles, source — is preserved untouched. There is no "replace mode," regardless of how the skill was invoked.

MTK-owned = carries the <!-- mtk-setup provenance stamp OR is a known generated path (root CLAUDE.md, standard .claude/rules/*, .claude/references/*, .claude/tech-stack, .claude/settings.json, .claude/detected-tools.json, .claude/mtk-version.json, CODE_INDEX.md, pre-commit-review-list.md). product.md/decisions.md and architecture-principles.md are never overwritten once present (changes route through regen-diff-contract.md). Superseding an MTK file must be explicit and listed under "Retired prior MTK files." Nested/per-package CLAUDE.md is never overwritten or deleted, monorepo or not. setup-refresh inherits this policy and must not weaken it.

Before any prose, the audit builds a deterministic ranked symbol graph so principles are grounded in the codebase's structural backbone rather than vibes. Every principle must cite at least one symbol from the ranked list, and a mandatory Provenance section discloses the graph's quality tier — or admits it fell back.

STEP 0.5 runs scripts/repomap.sh <stack>; the JSON fit field (full/ranked/defer-to-mcp/fallback) sets audit behavior. When fit != fallback the prompt flips to "cite at least one ranked symbol per principle; don't claim what you can't evidence." .NET defer-to-mcp attempts csharp-lsp enrichment per file. STEP 3.5 requires the ## Provenance section (symbol-evidence table, or the fallback disclaimer when no graph is available). Tree walks honor .mtkignore via scripts/repomap-tree-sitter.py.

Bootstrap and audit can run long enough to hit a session compaction or crash. Both record progress to a durable workflow artifact after each numbered STEP, so a re-run resumes from where it stopped and reloads recorded outputs instead of re-scanning from zero. On large repos the ledger, not the conversation, is the working memory.

bash scripts/workflow-artifact.sh init <type> --goal ... returns a UUID; after each STEP an event <uuid> step_completed --data '{"step":...,"outputs":...,"summary":...}' plus set <uuid> current_step=... record progress; completion sets status=completed. A resume check runs before init: an incomplete <24h artifact prompts; ≥24h auto-abandons (--reason stale-24h). Context economy: repos >1000 tracked source files process scan categories one at a time, writing each to the ledger and keeping only a 1–2 sentence summary in context. Summaries must be concrete, never vague.

Defines three artifacts: the per-feature delta spec, a canonical per-area baseline at docs/specs/baseline/<area>.{json,md}, and an audit trail at docs/specs/baseline/<area>.audit.jsonl. Each spec declares a baseline_area. On archive — only after a clean drift PASS — the delta is merged into the baseline and one audit line is appended, producing a durable specified-vs-built trail.

The sidecar's baseline_area makes a spec archivable; optional delta.adds/modifies/removes declare changes relative to the current baseline (removals must be explicit — archiving never infers deletion). spec-archive.sh merges the change_manifest/public_contracts (or the explicit delta) into the baseline JSON, applies delta.removes, appends the audit record, and regenerates the human-readable .md. The baseline is derived, never hand-edited, and is never archived on drift NEEDS_CHANGES.

Every spec ships a structured JSON sidecar carrying change_manifest, public_contracts, success_criteria (each with evidence_channel + observable), test_manifest, out_of_scope, security_impact, baseline_area, delta, assumptions, and risks. It is the source of truth for drift detection and the typed handoff that downstream skills append their plan and implement sections to — one artifact in two shapes (markdown for humans, JSON for machines).

Validated against .claude/schemas/handoff.schema.json (required keys: slug, date, scope, change_manifest, success_criteria, security_impact). Every change_manifest entry must be intended (no speculative files); security_impact must NOT be none if the diff touches auth/payments/audit/secrets/PII/IAM (spec-drift-detection blocks understated impact). assumptions/risks carry provenance tags [VERIFIED:path] / [ASSUMED] / [CITED:url] — an [ASSUMED] claim counts as an open decision that blocks MTK_AUTO_PROCEED. Every plan files entry must already exist in the top-level change_manifest, or planning must re-plan rather than widen scope.

The structured backbone the entire implementation loop reads and writes. It carries the fields that let each phase be deterministic instead of judgment-based — scope, change_manifest, public_contracts, success_criteria, out_of_scope, security_impact, and an implement block appended during the build. It's what makes drift detection and criterion-by-criterion verification possible.

Structure is governed by .claude/schemas/handoff.schema.json. The implement section is required to include actual_files (from git diff --name-only <base>...HEAD), completed_batches, honest deviations, and behavioral_diff. success_criteria carry id/description/evidence_channel/observable, frozen at Phase 2.5. On the subagent path each batch result is appended to sidecar.implement.completed_batches[]; scripts/validate-handoff.sh validates the shape and computes file/security drift before review.

The single format every review emits: a human-readable markdown findings table plus a trailing fenced JSON block, where the JSON is the source of truth. It defines the finding fields (severity, confidence, rule, source, failure_mode, decision_origin), the scores object, the confidence rubric, the default 80 threshold, the empty-findings anti-sandbagging rule, the False-Positive Exclusion List, and the verdict mapping.

JSON envelope carries findings[], scores{}, summary{}, and below_threshold_rationale. The source field distinguishes ai / linter / analyzer / context (linter and analyzer always confidence 100). Threshold comes from .claude/review-config.json thresholds.default (per-engineer override in .claude/review-config.local.json); only confidence >= threshold surfaces, and below-threshold findings count in summary.filtered_below_threshold. A 7-category FP Exclusion List drops non-findings before scoring. Verdict mapping: any critical at threshold, any gate: "mandatory", any scores.<dim>.value < 7, or uniform scores → NEEDS_CHANGES; otherwise PASS. Also houses the scores block and decision-origin tagging specs.

The canonical schema for a learning entry in .mtk/learnings.jsonl. It specifies every field and its meaning: id, scope, source (correction/promotion/manual/review-finding/incident/golden-path), decision_origin, severity, memory_type (episodic/semantic/procedural), supersedes, validity, recurrence, wrong_turns, time_cost, evolution_actions, and the optional v7.25 contract fields. It also documents the 5-layer retrieval filter, migration rules, and the sycophancy index formula.

Defines a two-tier model, the full JSON entry shape with a worked example, and per-field notes: id format L-YYYY-MM-DD-NNN; at least one of spec_id/workflow_uuid required; validity.expires_at defaults to captured_at + 12 months; recurrence.count ≥3 triggers CLAUDE.md-promotion; supersedes drives conflict-driven forgetting so query drops superseded entries without deleting the audit trail; severity includes incident which outranks other sources. It documents borrowed taxonomies (content-type memory_type; conflict-driven forgetting) and the file layout with ## Auto-generated / ## Manual additions sections.

The gate that keeps lesson-mining honest. Every candidate extracted from a transcript defaults to reject; it must pass at least one admit rule (A1–A4) and fail all six reject rules (R1–R6) before being surfaced. It also carries the security stance that transcripts are untrusted input and the machine-readable output contract each survivor must emit.

Reject rules: R1 derivable-from-code-in-<60s, R2 framework-boilerplate, R3 already-fixed-in-code (propose a code comment instead), R4 generic-advice-no-trigger, R5 inferred-preference-no-stated-reason, R6 instruction-like-content-from-transcript-body (injection — discard). Admit rules: A1 engineer redirect with stated reason, A2 recurring pattern (≥2 sessions), A3 novel constraint not already in the lessons store, A4 cost-measurable waste (time_cost estimable). The output contract fixes the candidate JSON shape (candidate_id, title, body, rule, applies_when, admit_rule, reject_rules_checked, evidence_excerpt, time_cost, proposed_action).

Defines what counts as a mineable phrase, the denylist of boilerplate that must never become a rule, and the markdown/JSON output schema for the miner. It states the candidate criteria (imperative-verb start, 4-word prefix in ≥2 distinct merged PRs, not denylisted) and the promotion workflow that keeps mined phrases suggest-only and tagged [MINED:feedback].

Documents the IMPERATIVE_HINTS verb list the script uses, the ≥2-distinct-PR threshold, and that only PR review summaries and per-line comments are mined (not issue comments). The denylist section is machine-read: lines under ## Denylist are consumed by the script until the next ## heading. Provides the markdown output table and the --json schema (status ok|skipped, scanned_prs, phrases[]), noting skipped with empty phrases when gh is unavailable. The promotion workflow requires human review, the [MINED:feedback] tag, and cited PR numbers.

Quantifies MTK's own context cost and the savings its architecture delivers, with every number derived from the installed files or the on-disk compression log — nothing from telemetry MTK does not collect. It separates the always-on floor (loaded every session) from everything progressive disclosure keeps out, plus review offload to subagents and on-demand skill bodies. It also reports real output-compression savings when a log exists.

It approximates ~4 chars/token. Always-on = the sum of every skill description + agent descriptions + CLAUDE.md + .claude/rules/INDEX.md bytes. Deferred (kept out by progressive disclosure) = .claude/references/*.md (glob-gated) + rule bodies excluding INDEX.md (path-gated) + manifest.json (MCP-gated, never inlined). Review offload = total agent-body bytes (run in isolated subagent context, never entering the main thread). On-demand = all SKILL.md bodies (one loads per skill run). The output-compression section reads .claude/observability/compression.jsonl (written by scripts/mtk-compress.sh) via python3, reporting all-time and current-session (CLAUDE_CODE_SESSION_ID) tokens saved and ratio, or a hint if the log is absent.

The deterministic hooks share one state file so counting is consistent across them. It is keyed by repo root and today's date, so counters reset each day and never mix projects. context-budget.sh writes it on every tool call; session-analytics.sh reads it at session end to summarize the session. capture-learnings.sh also reads a same-named file at session end, but it computes the path from pwd rather than through this helper, so the two agree only when the working directory is the repo root.

mtk_session_file builds the path as ${TMPDIR:-/tmp}/mtk-context-budget-<repo-root-cksum>-<YYYYMMDD> (repo root via git rev-parse --show-toplevel, falling back to pwd). mtk_load_session_state / mtk_save_session_state round-trip the fields (reads, files, mods, ops, bytes_read, warned_* flags, event_seq, last_edit_*, last_verification_*, scope_guard_warnings, benchmarks_run, benchmark_last_score) using escaped single-quoted values plus atomic temp-file rename. mtk_session_lock_acquire/release use an mkdir-based advisory lock (no flock dependency) so concurrent PreToolUse/PostToolUse firings don't lose updates to last-writer-wins races. mtk_command_is_verification classifies build/test commands as verification evidence.

Treats context — the full information payload the model sees at generation time — as something to engineer, not accumulate. It loads only what the current step needs, tracks how much has been loaded, watches for degradation, and forces a clean reset before compaction fires mid-edit. It gives MTK a shared vocabulary (Write / Select / Compress / Isolate) for the moves the toolkit already makes.

Four operations map to concrete MTK mechanisms: Write (auto-memory + tasks/lessons.md, workflow-artifacts, handoff), Select (rules INDEX.md wake-up layer + path-scoped applyTo reference loading), Compress (output-compression.md / mtk-compress.sh), Isolate (subagent-implementation one implementer per batch, review agents via context: fork). Loading workflow: CLAUDE.md first, then only task-relevant references, then read the target file plus 2-3 neighbors. It tracks four weighted context-fatigue signals — token utilization (40%), scope scatter (25%), re-read ratio (20%), error density (15%) — and when 2+ are elevated it prunes, re-summarizes, or escalates to handoff. Budget guidance: CLAUDE.md 60-80 lines (cap 120), each skill 60-120 lines, no more than 3 skills loaded at once. The context-budget hook nudges when estimated consumption passes MTK_CONTEXT_BUDGET_PCT% (default 60) of MTK_CONTEXT_WINDOW_TOKENS (default 200000); that 60% is the hard floor, the ~40% proactive reset is the target. A rot-symptom override (re-reading, re-asking, contradicting a prior decision, reintroducing rejected code) forces a reset regardless of the token count. Model routing reserves opus for real logic and adversarial reviews, running discovery/planning/comparison on sonnet/haiku (full policy in model-routing.md). Reference reads are issued as parallel Read calls in a single message.

Reference entries in .claude/manifest.json can declare an applyTo glob array. When the current task has a known set of files in scope, this mechanism loads only the references whose globs actually match one of those files and skips the rest. References without an applyTo (like coding-guidelines) stay always-on, loaded on demand per phase.

When file scope is known, the skill prefers the mtk_resolve_references MCP tool, which returns deterministic matches against the manifest's applyTo arrays. If the MCP tool is unavailable it falls back to testing each touched file against the globs with bash case / fnmatch semantics. git diff --name-only HEAD is the authoritative touched-file list when in doubt. A reference whose globs match nothing is explicitly NOT loaded 'just in case' — that would defeat the budget.

Instead of loading every rule file eagerly, MTK keeps a compact index — one line per rule file — that is cheap enough to always read. Each line carries three axes plus a path-glob list, so the agent can decide which full rule files are worth their tokens before spending them.

INDEX.md lists each rule file with axes — decision (structure|process|authoring|security), topic (manifest|skills|hooks|git|…), scope (global|project) — plus a paths glob list, rule count, and line count, targeting under 60 lines total. A rule whose paths glob matches a touched file is always relevant (machine-scoped auto-attach); the axes let you additionally pull rules by intent. The file is generated by scripts/build-rule-index.sh and must never be hand-edited; CI runs --check and fails on a stale index.

Writes a small markdown artifact that records the branch, in-progress work, decisions, blockers, and key files so the next session — yours after compaction, a new conversation tomorrow, or a teammate — can pick up cleanly. The artifact is a pointer, not a transcript: it says where to look, not what every step was.

Gathers state (current branch, recent commits, uncommitted changes, tasks/todo.md, the active spec/plan from docs/specs/ and docs/plans/ recorded as the full path incl. version suffix into spec_path, today's tasks/lessons.md entries), then reads the four context-engineering fatigue signals to decide whether the handoff is a 'clean snapshot' or a 'salvage' — leading with elevated signals so the next session knows what to mistrust. Writes docs/handoffs/YYYY-MM-DD-<slug>.md (today's real date via date +%Y-%m-%d) with fixed sections and an optional Fatigue Signals block, keeps it under 100 lines with no code blocks over 5 lines, and ensures docs/handoffs/ is gitignored. The post-compact hook (SessionStart matcher "compact") re-injects handoff artifacts after auto-compaction (per rule S3.11). After writing the handoff it records results.handoff_path and publishes/updates the workflow Artifact in place so a teammate opening the one URL sees current state (standalone publish if no workflow is active); disk-first, capability-gated, silent no-op when unavailable or MTK_ARTIFACT_PUBLISH=0.

Stores the state of a running workflow — phase cursor, gate decisions, spec/plan/todo paths, per-criterion verification status — on disk instead of in chat. Other workflow skills (implement, fix, planning-and-task-breakdown, spec-drift-detection) call it at phase boundaries and gate decisions so the orchestration can resume after a crash or compaction.

Each workflow is two files under .mtk/workflows/: {uuid}.json (current state, overwritten in place) and {uuid}.events.jsonl (append-only event log), with workflow_uuid in the form wf-YYYYMMDDTHHMMSSZ-{6 hex}. ALL reads/writes go through scripts/workflow-artifact.sh (init / set / event / gate / criteria / abandon / list / read) — never Edit/Write the JSON directly, or the event log desyncs. Five named gates are persisted (plan_trust_gate, phase_exit_gate, failure_stop_gate, memory_sync_gate, skill_precedence_gate); a failure_stop_gate: fail terminates the workflow. criteria_status tracks each success criterion (SC1, SC2, …) as pending | verified | re-armed, and the re-arm rule flips every verified criterion back to re-armed after any Edit/Write, so verification-before-completion rejects a completion claim unless all criteria are verified. Event types cover the full lifecycle (workflow_started, phase_started/completed, gate_decided, agent_dispatched/returned, remediation_*, workflow_completed/failed). .mtk/ is gitignored by setup-bootstrap; only the orchestrator writes artifacts — subagents return structured output and the orchestrator persists it via an agent_returned event.

The single source of the artifact-publishing procedure so each skill stays a thin navigation layer. Workflow skills persist their human-facing outputs to disk (the machine pipeline — drift, approval seal, EARS lint, plan-gap review, recovery, baseline — reads local files). This reference tells them how to ALSO publish those outputs as one browsable Claude Artifact per workflow run, keyed to workflow_uuid and updated in place across phases, so the engineer gets one stable URL rendered for review outside the terminal.

Gate (both required, else silent no-op): the Artifact tool is present in the harness (Claude Code / claude.ai; cursor/codex are disk-only) AND MTK_ARTIFACT_PUBLISH != 0. Procedure: resolve the workflow uuid ($MTK_WF_UUID, else the single active workflow, else publish standalone); record the output path on the workflow artifact; assemble the rollup via scripts/workflow-artifact-md.sh; publish the rollup, passing the recorded results.artifact_url as url to update in place when one exists; persist the returned URL with workflow-artifact.sh set. Disk is written first and unconditionally — publishing never gates or replaces it. Nothing beyond the named on-disk workflow outputs is ever published (no secrets, no settings.local.json, no transcript).

The deterministic assembler behind artifact publishing. It reads a workflow's JSON, then concatenates — with section headers and a title from intent.goal — whichever recorded source docs currently exist on disk (results.spec_path / plan_path / todo_path / handoff_path / health_report_path). Missing paths are skipped, not errors, so the rollup always reflects exactly what exists at assembly time. Output overwrites .mtk/workflows/<uuid>.artifact.md in place.

bash + python3 (within the S3.3 baseline), set -euo pipefail, executable (S3.2). It resolves paths relative to the repo root, skips any recorded path that isn't a file on disk, and emits a placeholder section when nothing exists yet. It never writes anything except the derived rollup under gitignored .mtk/, and never mutates the workflow JSON or the source docs.

Answers the forward-looking question 'given what this repo already does, what is the current best way to do X?' by pulling fresh external information (release notes, current best-practices, migration paths, security advisories) and grounding it against named files in this repo. It is MTK's research-mode primitive: research is a first-class workflow step, not an ad-hoc web search. It produces a brief and stops — another skill acts on it.

Step 1 frames the question against the repo — naming the active tech stack (.claude/tech-stack), the installed library version read from the lockfile/project file, and 1-3 grounding files (an ungrounded brief is marked as such). Step 2 chooses depth from a table: the light path uses WebSearch + WebFetch directly (2-4 fetches) or the context7 MCP for library docs; the deep path delegates to the built-in /deep-research workflow (via the Skill tool) for multi-angle/high-stakes questions rather than hand-rolling a fan-out. Step 3 classifies each finding (verified-from-source / applies-to-this-repo / conflicts-with-repo / still-uncertain). Step 4 emits a compact Markdown brief where every claim carries exactly one mandatory provenance tag — [CITED:<url>], [VERIFIED:<file:line>], or [ASSUMED] — the [ASSUMED] tag being load-bearing because it blocks MTK_AUTO_PROCEED downstream. Step 5 persists a research_brief event when $MTK_WF_UUID is set. A written phase-locked tool-discipline note pins it to Read/Grep/Glob + web tools — never Edit/Write of source or test code, the only artifact it may write is its own brief (it is deliberately NOT locked to the read-only toolset because it needs WebSearch/WebFetch) — and it runs on sonnet. Its brief is consumed by spec-driven-development (version-sensitive ambiguity gate, step 6) and implement (Phase 3).

Sets up an isolated workspace for feature work or experiments without the overhead of a full clone, and does it safely: it verifies the worktree location is gitignored, installs the right dependencies for the stack, and proves the baseline tests pass before any new code is written.

Determines the location by checking for .worktrees/, worktrees/, or .claude/worktrees/ (Claude Code's native location) and CLAUDE.md preferences, defaulting to .worktrees/. Verifies gitignore safety and commits the .gitignore change before creating anything. Creates via git worktree add <path> -b <branch-name> with feat/<slug> or fix/<slug> naming (S4.1). Auto-detects and installs dependencies by project file (*.csproj/*.sln → dotnet restore, package.json → npm install, requirements.txt/pyproject.toml → pip/poetry install, go.mod → go mod download, Cargo.toml → cargo fetch), then runs baseline tests. Finishing offers four options — merge locally, push and create PR, keep as-is, or discard (requires typed 'discard') — cleaning up only options 1 and 4 via git worktree remove <path> and git branch -d. Resolves the lessons path (tasks/lessons.md) against the main worktree using git rev-parse --git-common-dir.

A skill is a reusable behavior contract that shapes how the agent approaches a category of work. writing-skills is the process you follow to add or rewrite one: watch the agent fail at the task without the skill first, write only enough documentation to close those specific gaps, then prove the skill resists pressure before it ships. It also enforces the shared skill anatomy and the CSO (Condition-based Skill Descriptions) principle that every MTK skill must follow.

Five phases: Phase 1 Observe Baseline Failures (document skipped steps + rationalizations = the RED baseline); Phase 2 Write The Minimum Skill (anatomy from docs/skill-anatomy.md — frontmatter + ## Overview/## When To Use/## Workflow/## Verification; apply the CSO principle so the description triggers on conditions, not a workflow summary; reference the shared rationalization table in context-engineering rather than duplicating it; keep it under 500 lines using progressive disclosure — S2.26 'navigation layer, not a payload'); Phase 3 Test Under Pressure (3-5 adversarial scenarios — time/simplicity/authority/precedent — saved to tests/pressure-tests/<skill-name>-pressure.md); Phase 3b Add Evals if the skill gates shipping (evals/<skill-name>/ with positive/negative/adversarial scenarios + grader.md, run via bash scripts/run-evals.sh); Phase 4 Register (add to .claude/manifest.json, update AGENTS.md routing, rebuild the triggers index with bash scripts/build-triggers-index.sh if it declares triggers:, run bash scripts/validate-toolkit.sh). A dedicated 'Cache-Stable Prefixes' section tells reviewer/entry-point authors to put invariants first and inject volatile state (branch, diff) last so prompt caching hits.

MTK's workflow skills (spec-driven-development, incremental-implementation, test-driven-development) and review agents are language-agnostic. All the stack-specific knowledge — build/test commands, ORM rules, framework patterns, coding-style path, detection markers, and pre-commit items — lives in one tech-stack skill loaded on demand. Which one loads is decided by the .claude/tech-stack file. This is the seam where you add support for a new language.

Tech-stack skills carry type: tech-stack frontmatter and follow the declarative S2.13 anatomy (Build & Test Commands, File Extensions & Markers, ORM & Data Layer Guidance, Framework Patterns, Test Level Guidance, Coding Style Reference, Reference Files, Settings Additions, Format Command, Scan Recipes) — the ## Workflow section is omitted because they are declarative, not procedural. Each declares its detection markers (used by setup-bootstrap), its .claude/references/{stack}/ reference list, allowedTools/deny merges for .claude/settings.json, and a PostToolUse formatting hook (hooks/format-on-edit.sh). To add a stack you author a new tech-stack-{name}/SKILL.md and its .claude/references/{name}/ files; setup-bootstrap detects it and writes the marker into .claude/tech-stack.

Provides .NET-specific build and test commands, EF Core and MediatR/CQRS guidance, coding-style conventions, detection markers, and reference paths to the generic workflow skills and review agents. It is the first-class stack in MTK and includes analyzer-capture wiring and an optional Roslyn MCP companion plugin.

Declares markers (*.sln/*.slnx/*.csproj High, global.json/Directory.Build.props Medium) for setup-bootstrap detection; ships EF Core rules (AsNoTracking() on reads, .Select() over Include(), async query methods, one SaveChanges per handler) and MediatR slice conventions; points to references under .claude/references/dotnet/ (coding-guidelines, ef-core-checklist, mediatr-slice-patterns, testing-supplement, performance-supplement, analyzer-config). Formatting is wired via hooks/format-on-edit.sh (matcher Edit|Write, dispatch by tool_input.file_path from stdin JSON — NOT $CLAUDE_FILE). Analyzer output is captured with dotnet build 2>&1 | tee /dev/tty | hooks/parse-build-diagnostics.sh > .mtk/analyzer-output.json. Before installing any un-referenced NuGet package it runs dotnet package search <id> --exact-match --source https://api.nuget.org/v3/index.json (criterion 0 of the dependency-intake-checklist); planning-and-task-breakdown tags unverified AI-recommended packages [ASSUMED] and inserts a checkpoint:human-verify step. Scan Recipes supply the grep/find commands setup-audit runs on a .NET repo.

Provides Python-specific verification commands (there is no compile step, so type checking and tests are the gates), SQLAlchemy and Django ORM guidance, FastAPI/Django framework patterns, and reference paths. It adapts to the project's toolchain (tox, Poetry, Makefile/justfile targets) rather than assuming one.

Detection markers: pyproject.toml/setup.py(or setup.cfg)/Pipfile/poetry.lock High, requirements.txt Medium, .python-version supplemental (Low). Verification: mypy ./pyright as the compile-equivalent, pytest (or tox, poetry run pytest, make test) for tests, ruff check for lint. Analyzer capture: ruff check --output-format json . | hooks/parse-build-diagnostics.sh --format ruff > .mtk/analyzer-output.json. References live under .claude/references/python/ (coding-guidelines placeholder, sqlalchemy-checklist, fastapi-patterns, testing-supplement, performance-supplement, analyzer-config). Dependency intake verifies un-listed PyPI packages with pip index versions <pkg>. Scan Recipes drive setup-audit on a Python repo. The coding-guidelines file is an explicit placeholder to be authored when the team starts its first Python project.

Provides TypeScript/JavaScript build, type-check, and test commands, ORM guidance (Prisma, Drizzle, TanStack Query), and framework patterns for React SPAs, React Native/Expo, Next.js, Tauri desktop apps (with Rust sidecar commands), and Node backends. JavaScript-only projects use the same skill with the TS-specific rules relaxed to recommendations.

Package-manager auto-detection by lockfile priority (bun.lock/bun.lockb → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm, else npm) writes the choice to .claude/tech-stack-pm, and all commands substitute <pm>. Markers include package.json/tsconfig.json (High), src-tauri/Cargo.toml (Tauri sidecar), next.config.*, react-native/expo deps, metro.config.*. Formatting via hooks/format-on-edit.sh dispatches biome → prettier by extension. Analyzer capture: npx tsc --noEmit 2>&1 | hooks/parse-build-diagnostics.sh --format tsc > .mtk/analyzer-output.json. References under .claude/references/typescript/ (coding-guidelines placeholder, data-layer-checklist, framework-patterns, testing-supplement, performance-supplement, analyzer-config). Dependency intake verifies un-listed npm packages with npm view <pkg> name version time.modified. Extensive Scan Recipes cover monorepo, framework, ORM, and RN/Expo config detection for setup-audit.

A toolset is a named bundle of Claude Code tools that a skill can require or explicitly forbid. Instead of every skill getting the full tool surface, a skill declares which bundle it needs; the router expands that into allowed-tools when it dispatches the skill. This narrows a review or audit run to read-only tools and keeps destructive tools (push, run) out of scope.

Each toolset is a .claude/toolsets/<name>.yaml file (name must match the filename) with description, optional extends: <parent> (inheritance forms a DAG; the validator rejects cycles), and a tools: list of Claude Code tool specs (e.g. Read, Edit, Bash(git diff:*)). Three built-ins ship: read-only (review/audit/drift), git-safe (stage/unstage/read stash, extends read-only), code-edit (edit + build/test, extends git-safe). Skills reference them with required-toolsets/forbidden-toolsets (S2.19-S2.21); forbidden-toolsets wins on overlap, and an explicit allowed-tools already in the skill takes precedence over expansion (no surprise widening). Static agents under .claude/agents/*.md declare allowed-tools directly — toolsets exist for dynamic dispatch where scope varies by invocation.

References are the detail docs that skills link to rather than inline. They split into shared references (any stack) and per-stack references under .claude/references/{stack}/. A skill's frontmatter and body cite the reference for a given phase; the reference is read only when that phase runs, keeping the always-loaded skill body small (the S2.26 'navigation layer, not a payload' rule).

Reference files carry YAML frontmatter with description, globs, and alwaysApply. The set of per-stack references is declared canonically in each tech-stack skill's ## Reference Files section (S2.14). Shared references include security-checklist, testing-patterns, performance-checklist, domain-finance, and dependency-intake-checklist. Two generators consume references frontmatter to fan out into other tools (AGENTS.md and native tool configs), and scripts/build-references-index.sh compiles all frontmatter into a machine-readable .claude/references.index. Progressive disclosure (S2.10/S2.11) means orchestrating skills specify which references each phase needs.

Scans every reference doc under .claude/references/ for its frontmatter and emits a tab-separated .claude/references.index listing each file's path, alwaysApply flag, description, and globs. This index is the fast lookup layer for which reference applies to which files, without reading every reference body.

Finds .claude/references/**/*.md (null-delimited, LC_ALL=C sorted for stable ordering), pulls description, globs, and alwaysApply from each file's frontmatter block via awk, normalizes empties (globs → ["*"], alwaysApply → false, description → (no description)), strips brackets/quotes from the globs array into a comma-separated form, and writes a header row plus one row per file. It operates on the caller's CWD (the project repo), not the script's own directory, so a plugin-root invocation still indexes the project's references. The real write goes through mtk_guarded_write from hooks/lib/shrink-guard.sh (S3.16), which refuses a write that shrinks the index by >50% bytes or >20% lines unless MTK_SHRINK_GUARD_OVERRIDE=1 is set. --check rebuilds in memory and exits 1 on any difference from the on-disk index.

Generates an AGENTS.md that summarizes the project's reference and rules files into one file other AI coding tools read. Every source is summarized (its own headings, a 1-2 line distillation, and a See <path> pointer) rather than concatenated in full, so the output stays inside a 60-120 line budget. It refuses to clobber a hand-curated AGENTS.md.

Composition strategy DF-6: the only verbatim copy is CLAUDE.md's ## Critical Rules body (extracted with a prefix match so ## Critical Rules (Always Apply) also matches); every reference (architecture-principles, per-stack coding-guidelines, security/testing/performance checklists, stack supplements, domain-finance) is run through build_summary_section (H1/H2 headings + frontmatter description or first paragraph + See <path>). A SOFT_BUDGET of 120 lines drops the lowest-priority sections first (stack supplements at priority 10, then shared checklists 20-23), and a HARD_CEILING of 140 truncates as a last resort, leaving a <!-- sections summarized to fit... --> note. Detects the active stack from .claude/tech-stack, preserves any ## Custom: sections across regeneration, and gates overwrites on the Auto-generated by MTK marker in the first 10 lines.

Generates project-guideline files in each non-Claude tool's native format from the shared reference set, so Cursor rules, Copilot instructions, Windsurf rules, GEMINI.md, and Cline rules all carry the same conventions. Output is read-only — you regenerate rather than hand-edit — and hand-curated files are protected.

Formats: cursor-rules (one .cursor/rules/mtk-<topic>.mdc per reference, with frontmatter description/globs/alwaysApply; globs resolved from the manifest via extract_apply_to), copilot, windsurf, gemini, cline (single-file generators). Content is assembled by assemble_all_content: CLAUDE.md ## Critical Rules verbatim first, then architecture-principles, a coding-guidelines pointer (not the full body — it can be 800+ lines), security/testing/performance checklists, stack supplements (skipping coding-guidelines and analyzer-config), and domain-*.md files. Every write carries the Auto-generated by MTK marker and check_overwrite_allowed refuses to clobber a file without it (skip-and-continue, never abort) unless --force. --all honors an optional .claude/tool-configs.conf allowlist of formats, else generates all five. Stale mtk-*.mdc files are removed only if they still carry the marker (or under --force).

tech-stack-dotnet can lean on an optional external plugin, dotnet-claude-kit, whose 15 Roslyn MCP tools load the actual MSBuild workspace and provide semantic code intelligence. MTK skills call specific tools during pre-commit, batch review, and architecture review for deterministic findings, and fall back cleanly to build-output parsing when the plugin isn't installed.

Key tools MTK invokes: DetectAntiPatterns (pre-commit/batch review, treated as analyzer-sourced, confidence 100); GetProjectGraph/GetDependencyGraph (scope builds/tests to affected projects on big solutions); FindDeadCode/DetectCircularDependencies (architecture review); GetDiagnostics (targeted compiler/analyzer warnings per file); GetTestCoverageMap (verify coverage claims during test review). Graceful degradation: if the plugin is not installed, all MTK skills fall back to build-output parsing via hooks/parse-build-diagnostics.sh plus AI-based review — the workflow is unchanged, only the deterministic layer is thinner. Per S3.12, the MCP layer is optional and dependency-carrying, and every skill must have a bash fallback path.