Friction
The managed-header spec (Install/managed-header.md) instructs installers to place the managed header "at the very top of the file." Cursor .mdc rule files require YAML frontmatter (--- delimited block with description and globs) at the top for Cursor to parse them. The spec has a carve-out for skill files (managed marker after YAML frontmatter) but no equivalent carve-out for .mdc rule files, causing installers to produce incorrectly ordered files.
Evidence/example
During a Cursor adapter install, the agent placed the managed header above the YAML frontmatter in all 7 .mdc rule files. The human caught the error and the files had to be corrected. The legacy install (from a prior system) had the correct ordering, which served as the reference for the fix.
Failure mode
Every Cursor adapter install (fresh or update) risks producing .mdc files that Cursor cannot parse, requiring human intervention to catch and correct the ordering. This defeats the purpose of an automated installer.
Candidate approach
Add a "Cursor rule files (.mdc)" section to Install/managed-header.md (parallel to the existing "Skill files" section) that specifies: for .mdc files, YAML frontmatter goes first; the managed header lines go immediately after the closing ---. Include a short example.
Affected files
Install/managed-header.md
Verification
Future Cursor adapter installs produce .mdc files with YAML frontmatter first without human correction.
Friction
The managed-header spec (
Install/managed-header.md) instructs installers to place the managed header "at the very top of the file." Cursor.mdcrule files require YAML frontmatter (---delimited block withdescriptionandglobs) at the top for Cursor to parse them. The spec has a carve-out for skill files (managed marker after YAML frontmatter) but no equivalent carve-out for.mdcrule files, causing installers to produce incorrectly ordered files.Evidence/example
During a Cursor adapter install, the agent placed the managed header above the YAML frontmatter in all 7
.mdcrule files. The human caught the error and the files had to be corrected. The legacy install (from a prior system) had the correct ordering, which served as the reference for the fix.Failure mode
Every Cursor adapter install (fresh or update) risks producing
.mdcfiles that Cursor cannot parse, requiring human intervention to catch and correct the ordering. This defeats the purpose of an automated installer.Candidate approach
Add a "Cursor rule files (
.mdc)" section toInstall/managed-header.md(parallel to the existing "Skill files" section) that specifies: for.mdcfiles, YAML frontmatter goes first; the managed header lines go immediately after the closing---. Include a short example.Affected files
Install/managed-header.mdVerification
Future Cursor adapter installs produce
.mdcfiles with YAML frontmatter first without human correction.