angular-signal-forms-migration-mcp: Instructions file for Claude Code

CLAUDE.md — signal-forms-migration-mcp

You are building an MCP server that helps migrate Angular Reactive Forms to Angular Signal Forms. Signal Forms landed in v21; recipes are verified against v22, the current release. Full scope and tool specs live in SPEC.md — read it first, every session. This file is the rules you must never break.

Non-negotiable rules

1. THIS SERVER NEVER EDITS USER CODE. It only DETECTS and ADVISES. Never add a tool that writes to the user's source files. The calling agent does all edits.

2. GROUND EVERY SIGNAL FORMS RECIPE IN OFFICIAL DOCS. Signal Forms is new and is NOT reliable from memory. Before writing any recipe or "after" snippet: use the official Angular CLI MCP server (npx @angular/cli mcp) search_documentation / find_examples, and cross-check angular.dev. Encode only verified syntax; mark anything unverified as caveats: ["UNVERIFIED — confirm on angular.dev"]. Docs beat memory when they conflict. Always pass an explicit version: and check the searchedVersion in the reply — the tool silently falls back to older docs. Behaviour has already changed across releases (disabled(path, cb) in v21 became disabled(path, { when: cb }) in v22), so a recipe verified against the wrong version is worse than no recipe. Recipes must name the version they were verified against and flag anything version-sensitive.

   A DOC GAP IS NOT A BEHAVIOUR. This rule previously cited "v22 made required() reject false; v21 accepted it". That was wrong, and it survived two audits because every check compared documentation across versions. isEmpty is byte-identical in @angular/forms 21.0.0 and 22.0.7 — both contain value === false — so v21 rejected false exactly as v22 does. Only the docs changed: v22 added the sentence v21 omitted. When claiming a version difference, diff the shipped source (npm pack @angular/forms@N), not the two doc pages. Absence of a statement is not evidence of different behaviour.