CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

This repo contains no code. It is a set of AI-agent skills — Markdown documents that teach a coding agent the real API of DelphiMVCFramework, so the agent stops inventing plausible-but-wrong Delphi identifiers.

The product is prose. The failure mode is a confidently wrong API name that costs a user a compile error. Everything below exists to prevent that.

The iron rule

Every Delphi identifier written into a skill must be copied from the framework source. Never from memory.

The framework lives at C:\DEV\dmvcframework on this machine (sources/ and samples/); otherwise read sources and samples.

• A skill and a sample disagree → the sample wins, and the skill has a bug.
• Cannot verify something → say so in the skill, or leave it out. Do not guess.
• The samples document usage; sources/ documents signatures. You usually need both.

Real bugs this rule caught, all of which read as perfectly plausible: ToFree on a returned object (double free — the framework already frees it), TCORSMiddleware (it is TMVCCORSMiddleware), MVCFramework.Validators.CrossField (no such unit), [MVCFromBody(bvSkip)] (the enum is bvDoNotValidate), Context.ServiceContainer (only ServiceContainerResolver exists), an invented 422 response body.

Layout

skills/<skill-name>/SKILL.md          one skill; frontmatter + body
skills/dmvcframework/reference/*.md   heavy material the agent opens on demand
skills/*/scripts/*.bat                build/run helpers shipped with a skill
install_in_{claude,codex,cursor,gemini}.bat
tools/gen_htmx_index.py               regenerates skills/htmx-skill/SKILL.md (not shipped)
docs/logo.png

skills/htmx-skill/SKILL.md is generated, not hand-edited: clone htmx at a v2.x.y tag and run python -I tools/gen_htmx_index.py <clone>, then python check.py --urls (the one check that needs the network: every link must answer 200). Descriptions are htmx's own (0BSD); the lines htmx does not provide live in MANUAL inside the script. Nobody reruns it by hand: .github/workflows/htmx-skill.yml runs --latest weekly on main and dmvc-3.5, commits only if check.py --urls passes, and opens an issue when it cannot (a new htmx page with no description needs a MANUAL line). Keep check.py --urls on both branches: the workflow refuses to run a branch that lacks it. GitHub disables scheduled workflows after 60 days without repository activity; a banner in the Actions tab means re-enabling it.

skills/dmvcframework is the core; the others (-minimal-api, -webapp, -ui, -security, -jsonrpc, -testing, plus htmx-skill) build on it and cross-reference it by skill name.

skills/delphi, delphi-code-smells, delphi-firedac, delphi-testing, delphi-build and delphi-security are the exception: they are about the language, the RTL and the tools that ship with Delphi, not the framework, so the iron rule points at the shipped source (C:\Program Files (x86)\Embarcadero\Studio\<n>.0\source\rtl\, …\vcl\, …\data\firedac\, …\DunitX\), at what dcc32.EXE / dcc64.exe print (note the upper-case .EXE of dcc32 in bin, which a case-sensitive glob misses) and at the Embarcadero docwiki instead of C:\DEV\dmvcframework. Check a claim that may differ between releases on both the 12 Athens tree (23.0) and the 13 Florence tree (37.0), or label it "verified on 13 only". They carry no wizard-first section — they apply to any .pas file. A version claim ("available since Delphi X") is as damaging there as a wrong identifier: check it, never recall it. The two split by job: delphi explains how the language works, delphi-code-smells finds what is wrong with existing code. Ownership semantics live in the first, leak diagnosis in the second — they cross-reference rather than repeat. A warning code (W1035) is verified the only honest way: write the offending code and compile it with dcc32.exe, then copy what it printed.

Adding a skill? Also add it to: the four install_in_*.bat (three of them carry a hand-written one-line description per skill), and the four places the set is listed — the skills table in README.md, the prompts in docs/prompts.md, the AGENTS.md example in docs/installing.md, the layout tree in docs/layout.md. The public docs state the current state and the changes between public versions (docs/changelog.md), never how the work was done; process notes belong here.

The core skill's SKILL.md is deliberately thin. Bulk goes in reference/ — it is loaded only when the task needs it. When adding substantial material, ask whether it belongs in a reference file rather than in SKILL.md, and add a row to the reference index table in SKILL.md.

Hard constraints on a SKILL.md

• YAML frontmatter with name and description. Total frontmatter must stay under 1024 characters — over that, the skill silently fails to load. This has happened.
• name must exactly match the folder name; letters, numbers and hyphens only.
• description = when to use it, in third person. It is the only thing the agent reads when deciding whether to load the skill. Do not summarize the skill's workflow there: agents follow the description instead of reading the body.

check.py — run it after every edit

python check.py        # exits non-zero on any defect

Four mechanical checks, about five seconds:

• frontmatter — under 1024 chars, name == folder, description present
• links — every reference/*.md and every sibling skill named actually exists
• identifiers — every Delphi identifier in the prose exists in a source tree (C:\DEV\dmvcframework\{sources,samples,ideexpert,lib} and the Delphi source\{rtl,vcl,data,DunitX,internet}). Override with DMVC_HOME / DELPHI_SOURCE; if neither tree is present the check is skipped, not failed.
• coverage — every skill is listed in the three installers that name skills, and in README.md

When it flags an identifier you know is an example (TProductsController, TMyRecord), either declare it in the doc — TFoo = class(...) is recognised repo-wide — or add it to ALLOW in check.py, deliberately. That prompt is the point: a new identifier is either sourced or it is admittedly fictional.

What it does not prove. It checks that a name exists, not that it is used correctly. Result := ToFree(x) passes every check and double-frees. Real names with the wrong arity are caught only by a compiler; ownership bugs only by running something. So, in order of cost:

1. check.py — on every edit.
2. Compile: paste the skill's code skeletons into a wizard project and build it (scripts/build.bat). Catches wrong signatures. With ReportMemoryLeaksOnShutdown := True plus the DUnitX suite, it also catches the double-free/leak class — the one this repo exists to prevent.
3. Agent RED/GREEN (below) — before tagging a release.

Two positions the skills take, deliberately

Do not weaken these without being asked — they are decisions, not oversights.

1. Wizard-first. The skills never scaffold a project from scratch. They detect a project generated by the DMVCFramework IDE wizard (EngineConfigU.pas, RoutesU.pas, bin/.env, …) and add features inside it. If there is none, they stop and tell the user to create one.
2. Indy Direct is the default host — but only for a new project. An existing WebBroker project (ISAPI, Apache module) is legitimate: the skills detect the host, keep it, and never suggest migrating. Everything above the host is identical on every backend.

skills/exewatch-delphi documents a product SDK instead: its source of truth is the SDK source at C:\DEV\ExeWatch\SDK (EXEWATCH_HOME overrides it; check.py reads it), not the guide or the samples, which the code overrules when they disagree. It pins the SDK version it was verified against; keep that in step with the SDK when its public API changes.

Policy: skills do not advertise

No skill recommends a product, least of all one made by the authors. exewatch-delphi loads when the user's request is about remote logging, crash reports or telemetry, or when a project already uses ExeWatch; the language and security skills may point to it only for projects that already use it, and the README says plainly that ExeWatch is the authors' own service. Do not add "consider X" lines to the neutral skills.

How skills are tested

check.py covers the mechanical half (above). The half that matters — does the skill actually change what an agent writes — is verified by running an agent against it:

• Baseline (RED): dispatch a subagent to do a task without the skill, forbidding it from reading the framework source. Record the exact wrong names it invents. That list is the specification.
• Build a skill only where the baseline errs. Write verified questions first (answer each from the shipped source or by compiling), put them to an agent that has no tools, and write the skill for the details it gets wrong. A topic the model already answers correctly (the legacy-migration facts, the htmx 2 attributes) needs a procedure or a small reference, not a skill full of facts.
• With the skill (GREEN): same task, agent restricted to the skill folder only (no source, no samples). Then ask it check questions whose answers are the bugs from the baseline — e.g. "do you need ToFree on the object you return?" (correct answer: no, it would double-free).
• Audit: dispatch an agent to fact-check every identifier in a skill against sources/ and samples/, reporting only defects with file:line. Do this before publishing changes. check.py now does the name-exists part; the agent's job is the part a script cannot do — wrong arity, wrong ownership, an example that would not compile.

Keep check.py honest. A checker that never fails is decoration. After changing it, mutate a skill on purpose and confirm it fails: rename a class to something plausible that does not exist, point a reference/ link at a missing file, pad a description past 1024. Restore from a copy — never git checkout a file whose edits are not committed yet.

Installers

The four install_in_*.bat are idempotent and must stay so: re-running overwrites the skills but must not duplicate the section appended to AGENTS.md / GEMINI.md (guarded by the <!-- delphi-ai-skills --> marker). Claude Code auto-discovers skills; Codex, Cursor and Gemini do not, which is why those scripts also write the pointer file.

Test an installer against a scratch directory before shipping it — cmd.exe escaping is treacherous (! inside a <!-- --> comment is eaten by delayed expansion and needs ^^!).

Versioning

Currently 0.4.0, pre-1.0: the shape of the skill set is explicitly unsettled, and skills may be split, merged or renamed between minor versions. The skills version is independent of the framework's; the README states which DelphiMVCFramework release the content was verified against. Update both when content changes materially.

Branches follow the framework's major.minor. main is the line in development; dmvc-3.5, dmvc-3.6, … are cut from main when that framework release ships and then take corrections (an API described wrongly), cherry-picked from main; new skills or coverage go there only when the maintainer asks for them in that line (the five Delphi-level skills and exewatch-delphi were added to dmvc-3.5 that way). The DMVC IDE wizard downloads archive/refs/heads/dmvc-<major>.<minor>.zip, so a branch's head is what users of that line get: never force-push one, and never merge main into it.

• skills/VERSION holds the line (3.5); the core SKILL.md states the same line to the agent (**DelphiMVCFramework 3.5.x**). check.py fails if they disagree. When cutting a new line on main, bump both.
• On a line branch, run check.py against that release's sources, not the current checkout: DMVC_HOME=<a checkout of the 3.5 tag> python check.py. Against a newer framework it would accept names the line does not have.