intent-gate

English | 简体中文

Stop AI coding agents from guessing.

Complex business requirements. A thin or sloppy PRD. No legacy code to reference. That is exactly where coding agents start inventing: "happy path only, no failure flow", "idempotency with no server-side design" — gaps get silently filled with plausible-looking guesses, and you find out far too late.

intent-gate moves intent alignment before coding, into the requirement-analysis stage: a PRD goes through an intent-confidence gate → gaps are resolved through a three-level funnel → the output is technically annotated Mermaid contracts (state machines / sequence diagrams / decision tables) → a mechanical lint gate must reach zero CRITICAL → only then is coding allowed to begin.

It runs as an MCP server (stdio subprocess) — plug-and-play with Claude Code and other MCP clients. No daemon, no credentials, zero config — full workflow out of the box.

Where it sits in a vibe-coding workflow

intent-gate owns exactly one stage of the pipeline, the requirement-analysis stage:

PRD ──▶ [ intent-gate: confidence gate → intent alignment → Mermaid contracts ]
          ──▶ summary.md (every edge technically annotated, lint CRITICAL = 0)
          ──▶ coding agent (Claude Code / Cursor / any agent) ──▶ tests ──▶ ship

The leverage is asymmetric: if the contracts land well, the coding stage is a free win — every edge, step and rule already has a home, so any competent agent can implement the spec. That is why intent-gate deliberately does NOT touch coding, review or deployment: downstream agents are interchangeable; the input contract is not.

Dual-layer intent alignment

The diagram is the instrument, not a deliverable. Layer 1 (reading): sweep the PRD text for explicit ambiguities. Layer 2 (drawing): hard-draw draft diagrams in the FIRST turn — every node/edge that can't be drawn yet becomes a TBDn placeholder, never a guess (every edge is a forced decision). Placeholders route by kind: technical gaps go to code evidence, business gaps go to a structured human question — and may only be cleared by code evidence or a human ruling. A placeholder left in a delivered diagram is a lint CRITICAL (L13).

A real run: the smart-locker drop-off page

What one real requirement looks like after a full intent-gate pass.

The requirement, in one sentence:

"A smart-locker drop-off page — show the shipment details, allow changing the locker size, scan and drop the parcel. Must be duplicate-proof, expiry-proof, and masked."

That's it. Exactly where a coding agent starts guessing.

What happened along the way:

1. Reading layer: the text sweep flagged the explicit gaps (expiry? slot-size rules?) straight from the PRD.
2. Drawing layer: the analyzer hard-drew the state machine in the first turn — and stalled at "submit": what about failure? Should duplicate protection live on the server or the frontend? Each un-drawable edge became a TBDn placeholder instead of a guess.
3. 🔴 Red-light questions were asked one at a time (≥3 mutually exclusive options): "How do you guard against double-submit on rapid clicks / re-scan?"
4. You ruled: "Server-side Redisson lock, wait 10s / lease 300s" → your words were logged verbatim → injected into the state-machine edge and decision-table BR-01.
5. A mechanical lint gate ran before delivery: CRITICAL = 0 or it does not ship — and any leftover placeholder would itself be a CRITICAL.

The output: a technically annotated Mermaid contract (full state machine):

stateDiagram-v2
    direction LR
    [*] --> DROP_CONFIRM: 进入寄件确认页 (DB_QUERY_SHIPMENT, LOCKER_ROUTING_QUERY)
    DROP_CONFIRM --> SLOT_OPTIONS_LOADING: 请求可用柜格 (IOT_GET_FREE_SLOTS)
    SLOT_OPTIONS_LOADING --> DROP_CONFIRM: 获取成功 (RETURN_SLOT_LIST)
    SLOT_OPTIONS_LOADING --> DROP_CONFIRM: 获取失败 (RETURN_ERROR, SIZE_EDIT_DISABLED)
    DROP_CONFIRM --> SLOT_ROUTING: 修改柜型或站点 (DB_INSERT_SHIPMENT_SLOT, DB_UPDATE_SHIPMENT)
    SLOT_ROUTING --> DROP_CONFIRM: 路由成功 (DB_UPDATE_SHIPMENT_SLOT, RETURN_NEW_FEE)
    SLOT_ROUTING --> DROP_CONFIRM: 路由失败 (RETURN_ERROR, ROLLBACK_OR_KEEP_ORIGIN)
    DROP_CONFIRM --> EXPIRED: 扫码时效超时 (RETURN_ERROR_CODE, GUIDE_RESCAN)
    EXPIRED --> [*]: 引导回首页 (FRONTEND_NAVIGATE)
    DROP_CONFIRM --> SUBMITTING: 点击确认投递 (REDIS_LOCK_SUBMIT, IOT_UNLOCK_COMMAND)
    SUBMITTING --> STEP_QUERY: 提交成功 (DB_UPDATE_SHIPMENT, QUERY_CURRENT_STEP)
    SUBMITTING --> DROP_CONFIRM: 提交失败 (RELEASE_LOCK, RETURN_ERROR)
    SUBMITTING --> TERMINATE: 开柜指令失败 (DB_UPDATE_DROP_STATUS_TERMINATE)
    STEP_QUERY --> LOADING: DropStep=awaitingDrop (RETURN_NEXT_STEP)
    STEP_QUERY --> IDENTITY_CHECK: DropStep=identityCheck (RETURN_NEXT_STEP)
    STEP_QUERY --> PAY_CHANNEL: DropStep=payChannel (RETURN_NEXT_STEP)
    STEP_QUERY --> QUERY_PROGRESS: DropStep=queryProgress (RETURN_NEXT_STEP)
    STEP_QUERY --> DROP_CONFIRM: DropStep=dropConfirm (STAY_ON_PAGE)
    LOADING --> SUCCESS: 跳转下一步 (FRONTEND_NAVIGATE)
    IDENTITY_CHECK --> SUCCESS: 跳转下一步 (FRONTEND_NAVIGATE)
    PAY_CHANNEL --> SUCCESS: 跳转下一步 (FRONTEND_NAVIGATE)
    QUERY_PROGRESS --> SUCCESS: 跳转下一步 (FRONTEND_NAVIGATE)
    SUCCESS --> [*]: 投递流程结束 (END)
    TERMINATE --> [*]: 运单终止 (END)

Every edge carries a mandatory technical-action annotation — the edge DROP_CONFIRM --> SUBMITTING reads (REDIS_LOCK_SUBMIT, IOT_UNLOCK_COMMAND). What the coding agent receives is a spec, not an illustration.

Decision table (rule logic forced into a matrix — no "happy path only" survival):

| Rule | Condition | Action | Failure branch | |---|---|---|---| | BR-01 | Submit: lock LOCK:dropoff:submit:{shipmentId} conflict | Redisson lock serializes, concurrent submits rejected | Lock conflict → error code DUPLICATE_SUBMIT | | BR-07 | Scan deadline scanExpireTime | 5-minute double check: page countdown + server-side fallback on submit | Expired → SCAN_EXPIRED, guide re-scan |

The full contract: 10 business rules (BR-01..BR-10) + 3 sequence diagrams + an intent-injection mapping table (15 Q&A rounds, every answer on record).

The mechanical lint gate (pre-delivery self-check report):

summary_lint: CRITICAL 0 / 2 findings total (all MINOR, human-review class)

• [MINOR][L3] state STEP_QUERY has 5 outgoing edges — confirm triggers are distinguishable
• [MINOR][L3] state SUBMITTING has 3 outgoing edges — confirm triggers are distinguishable

With CRITICAL > 0 the contract refuses to ship and coding refuses to start — this is checked by code, not self-reported by the model.

Same requirement without intent-gate (observed in our control run): the agent would front-end-disable the submit button instead of designing a server-side distributed lock, hardcode a success page instead of routing by queryCurrentStep, and never model the EXPIRED state at all. The guessing space is structurally compressed, not politely discouraged.

Where to put your PRD

intent-gate accepts UTF-8 text files or .docx (the dominant format for business requirements). Three ways to hand one over:

| Way | Example | Notes | |---|---|---| | Absolute path | analyze D:\docs\locker-dropoff.docx | Most reliable; readable from anywhere | | Relative path | analyze docs/locker-dropoff.md | Resolved against the project root (HG_WORKSPACE_ROOT, defaults to the startup directory) | | Conversation attachment | Drag the file into the chat; have the agent persist it first | Attachments are conversation content to the host, not a path — the agent must write them to disk before handing over a path |

Supported formats:

• ✅ UTF-8 text: .md / .txt / .csv / .json and similar
• ✅ .docx: native support — mammoth is a core dependency (installed automatically; tables become Markdown tables); if markitdown already exists in your environment (e.g. for another document MCP), it is reused for enhanced extraction
• ❌ Legacy .doc / .pdf / .xlsx and other binaries: convert first — Word「Save As → .docx or Plain Text (.txt)」, PDF export/save-as text

Errors carry the next step: missing file, binary format, and encoding failures each return a distinct message telling you what to do.

Using it: what to say

Once installed, you drive it with plain language. This table is the whole manual:

| You say | Who picks it up | What happens | |---|---|---| | "分析这个需求 / analyze this PRD"（贴文档或指文件） | 🔴 Red team（requirement-alignment） | Reads the playbook first, runs the Step 0 confidence check, then asks you structured questions (≥3 options + "other"), one gap at a time | | "画个状态机 / 生成 DDL" | 🔴 Red team | Same entry — pattern routing decides which diagrams your requirement actually needs | | "继续"（中断后/新会话） | 🔴 Red team | Resumes from the on-disk ledger (.harness/requests/{feature}/_review/) — no session memory needed | | 回答它的提问："1"，或 "4 余额不足一律拒绝" | the funnel | Answer logged verbatim → injected into the diagrams → settled with a precise landing point | | "红蓝对抗 / blue-team review" —— 另开新会话说 | 🔵 Blue team（red-blue-review） | Independent adversarial review of the delivered summary: R1–R9 checks → findings with verdict PASS / FAIL-可整改 / FAIL-重做 | | "按 findings 整改"（回到红军的会话里说） | 🔴 Red team revision discipline | Each finding settled into revision-log.md with a real landing point, lint re-runs to zero CRITICAL; anything conflicting with your earlier rulings comes back to you for a decision | | 什么都不说，直接让它写代码 | SessionStart hook | The agent reads the landed summary.md contract before coding; blocked or lint-CRITICAL contracts refuse to be coded against |

Two rules worth remembering:

• Answer its questions seriously — every answer becomes part of the contract your coding agent will execute against.
• The blue team needs a fresh session — reviewing in the same session degrades adversarial review into self-check. Deliver with the red team, then open a new conversation and say "红蓝对抗".

Core mechanisms

Intent-confidence gate (Step 0): assess the light status before analyzing any requirement. Until 🔴 core-logic gaps are eliminated, the report status must be blocked, the first task in any breakdown is forced to be [BLOCKER], and downstream coding is forbidden from starting.

Three-level alignment funnel (Step 0.5) — cost decreases level by level, fully non-blocking throughout:

① Code-grounded verification: technical gaps are checked against the code first;
  a unique ground truth is recorded directly, zero interpersonal cost
② AI-disclosed inference: registered with an explicit evidence chain, batch-confirmed
  by a human at session end (pure inference is forbidden on money-critical main flows)
③ Human ruling: structured-option questions (≥3 mutually exclusive options + "other"),
  one question at a time

Mechanical enforcement (enforced by MCP tools, not by prompt self-discipline):

• Once a gap is registered it is physically persisted to pending-questions.md; until every box is ticked you don't get intent_aligned_ready;
• resolve_question mechanically rejects an empty landing point — every injected intent must be precise down to a state-machine edge, a sequence-diagram step, or a decision-table rule number; if no landing point is found, closing the question is forbidden and it must be asked again;
• Landing-point anchors may not be handwritten — the draft_mapping script locates real section/rule/step numbers;
• Pre-delivery lint_summary mechanical self-check (L0–L8: unparseable state machine (blind-guard) / missing terminal state / dead states / mispl