mk-spec-master · AI 規格大師 — specs in, scenarios out

Scope

What this is not

mk-spec-master sits between your spec source and your test runner. It's not the editor, runner, or LLM.

A spec editor

→ Linear / JIRA / Notion / Markdown — keep writing specs where you already do

A test runner

→ mk-qa-master (pytest / Jest / Cypress / Go test / Maestro)

An issue tracker UI

→ Linear / JIRA / Notion's native interface

A spec → code generator

→ GitHub Spec Kit, AWS Kiro

An LLM

→ Leverages your AI client (Claude / Cursor / Codex / Gemini) for reasoning

Tool surface

18 tools across 7 roles

Grouped by role. Each group is one layer in the spec → test → coverage → coach loop.

Meta — orientation

get_spec_source_info — Active adapter + all available. Call this first.

Discovery — find + load specs

list_specs — Filter by status / label / limit.
fetch_spec — Pull a single spec by id.
parse_spec — Heuristic AC extraction (en + zh-TW + zh-CN headings). Returns ac_hash.

Generation — specs → testable artifacts

extract_scenarios — AC → scenarios with happy / edge / error classification.
generate_test_plan — One-shot markdown plan ready to hand to mk-qa-master.

Coverage & drift

link_test_to_spec — Record that a test verifies a spec; stores title / source / ac_hash.
auto_link_tests — Scan test files for @spec: tags. Python / JS / TS / Go.
get_coverage_matrix — "Which specs have no tests" in one call.
get_drift_report — fresh / drifted / unknown / stranded buckets.

Coach — quality + prioritization

analyze_spec_quality — Vague language, implementation-leak AC, unclear role refs.
propose_spec_improvements — PM-facing markdown with concrete rewrites.
get_optimization_plan — Three-layer prioritized plan: coverage + quality + drift.

Knowledge — domain methodology

init_spec_knowledge — Starter spec-knowledge.md (EARS, INVEST, AC quality rules).
get_spec_context — Read the methodology file; optional section filter.

Self-reinforcement — longitudinal view (v0.4)

get_spec_history — Trend deltas current vs ~7d / ~30d across coverage / quality / drift.
get_drift_signature — Chronic-spec detection: unstable / chronic_low_quality / chronic_unhashed.
get_telemetry — Tool-usage log: top tools, error rate, p50/p95, dead surface. No argument values logged.

Source adapters

6 sources, one tool surface

Switch via the SPEC_SOURCE env var. Same tools, six different backends.

markdown_local

auth: none
since 0.1.0

github_issues

auth: gh auth login or GITHUB_TOKEN
since 0.1.0

linear

auth: LINEAR_API_KEY + SPEC_PROJECT_KEY
since 0.2.2

jira

auth: JIRA_BASE_URL + JIRA_EMAIL + JIRA_API_TOKEN
since 0.2.3

notion

auth: NOTION_TOKEN + database id as SPEC_PROJECT_KEY
since 0.3.0

figma

auth: FIGMA_TOKEN + file key as SPEC_PROJECT_KEY
since 0.3.1

Workflows

Four prompts cover ~90% of real use

One sentence to the AI client; the tools chain automatically.

1.

"Fetch LIN-123, extract scenarios, generate Playwright tests with mk-qa-master, run them, and update the coverage matrix."

fetch_spec → parse_spec → extract_scenarios → mk-qa-master.generate_test (×N) → link_test_to_spec (×N) → mk-qa-master.run_tests → get_coverage_matrix

2.

"Review every in-progress spec for quality issues and give me a prioritized improvement plan."

list_specs(status='in-progress') → analyze_spec_quality → propose_spec_improvements → get_optimization_plan

3.

"Sync the spec ↔ test index from the test source — I just renamed a bunch of files."

auto_link_tests → get_coverage_matrix

4.

"Load the spec-knowledge methodology and tell me which source is active before we start."

get_spec_source_info → get_spec_context

Sample output

What you actually get

Two of the most-shown outputs — both ready to paste into Slack, JIRA, or a sprint planning doc.

get_optimization_plan

# Optimization plan

_Coverage matrix: 23 spec(s) tracked, 4 untested._
_Spec quality: 23 spec(s) analyzed, 17 finding(s)._
_Drift: 2 drifted, 0 stranded, 5 without ac_hash._

## 🔴 Layer 1 — Coverage gaps

**Specs with zero tests** (ranked first — every business risk lives here):
- `LIN-204` — Apply promo code at checkout
- `LIN-211` — Refund flow

## 🟡 Layer 2 — Spec quality

### `LIN-098` — Checkout latency  (score: 80/100, findings: 4)
- 🟡 `ac-1`: Quantify (e.g., 'response within 200 ms')  (evidence: `fast`)
- 🔴 `ac-3`: Rewrite to describe what the user observes  (evidence: `redis`)

## 🔵 Layer 3 — Process drift

**Drifted** (spec changed since link — review affected tests):
- `LIN-123` — Apply discount at checkout · 4 test(s) potentially stale

get_coverage_matrix

# Coverage matrix

- Specs tracked: 23
- Specs shown (min_tests=0): 23
- Specs with zero tests: 4

| Spec      | Title                          | Tests | Last status |
|-----------|--------------------------------|------:|-------------|
| `LIN-204` | Apply promo code at checkout   |     0 | —           |
| `LIN-123` | Apply discount at checkout     |     4 | passed      |

Add to your MCP client config

Restart your client, then talk to the AI like you always do.

{
  "mcpServers": {
    "mk-spec-master": {
      "command": "uvx",
      "args": ["mk-spec-master"],
      "env": {
        "SPEC_SOURCE": "markdown_local",
        "SPEC_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Read the docs → Sibling → mk-qa-master

Specs in.Scenarios out.