4gray
faad8fd8fd
* docs(agents): compact root guidance and preserve task-specific knowledge * fix(agents): parse guidance navigation with Markdown tokens * fix(agents): validate generic literal repository paths * fix(agents): distinguish code symbols and shortcut images * fix(agents): recognize SCSS filename literals * fix(agents): handle fenced imports and encoded paths * fix(agents): parse prose and rendered HTML anchors * fix(agents): validate rendered HTML navigation * fix(agents): use GitHub-compatible heading slugs * fix(agents): require standalone top-level Claude import * fix(agents): exclude HTML-contained guidance imports * fix(agents): handle image fragments and quoted imports * fix(agents): validate visible HTML and image source sets * fix(agents): recognize package scopes and route source work * fix(agents): parse JSONC and constrain package exemptions * fix(agents): decode link entities and allow package subpaths * fix(agents): route source work and check extensionless files * fix(agents): support package versions and source fragments * fix(agents): accept qualified package prose * fix(agents): retain rendered context for Markdown references * fix(agents): validate visible headings and spaced paths * fix(agents): validate media and hyphenated literal paths * fix(agents): decode full HTML entities and media assets * fix(agents): recognize possessive package mentions * fix(agents): validate extensionless imports and version comparators * fix(agents): retain visible backticks and explicit path punctuation * fix(agents): validate image-map navigation targets * fix(agents): count all Markdown line endings in budgets * fix(agents): delimit package prose at Unicode punctuation * fix(agents): normalize punctuation for extensionless imports * fix(agents): preserve filenames across prose punctuation * fix(agents): validate iframe document references * fix(agents): inspect document suffix before URL fragments * fix(agents): unify Markdown suffix and encoded import guards * fix(agents): handle wildcard versions and alternate documents * fix(agents): validate document formats and trim HTML URLs * fix(agents): cover document families and guidance basenames * fix(agents): require files for media references * fix(agents): preserve block boundaries and validate embeds * fix(agents): normalize internal HTML URL whitespace * fix(agents): reject empty media and ignore URL at-signs * fix(agents): validate srcdoc references and empty srcset * fix(agents): honor HTML bases and preserve adjacent imports * fix(agents): convert base file URLs to native paths * fix(agents): preserve imports after bare URL punctuation * fix(agents): exclude opaque URI prose from import scans * fix(agents): keep import tokens outside URI scheme matches * fix(agents): restrict opaque URI exemptions to parsed links * fix(agents): handle opening prose delimiters * fix(agents): scan nested imports and share document suffixes * fix(agents): reject pathless media and direct file URLs * fix(agents): reject file bases and preserve quoted URL boundaries * fix(agents): distinguish URL quotes and cover guidance variants * fix(agents): validate SVG images and conventional guides * fix(agents): handle declared package names handles and SVG use * fix(agents): normalize closing punctuation on federated handles * fix(agents): normalize Unicode punctuation on handles * fix(agents): normalize possessive federated handles * fix(agents): separate parenthetical prose from handles * fix(agents): exclude www autolinks from import scanning * ci: allow manual CodeQL validation of PR branches * fix(agents): reject nonportable Windows drive links
3.5 KiB
Agent guidance reorganization — issue #1643
Approved implementation plan, 2026-09-20.
Outcome
One source of common instructions: AGENTS.md (at most 200 lines / 16 KiB). CLAUDE.md imports @AGENTS.md and contains only Claude-specific guidance (at most 30 lines / 2 KiB). Do not increase Codex loading limits. No runtime or public API changes.
Knowledge preservation
Inventory both original files at the starting commit in
docs/maintenance/agent-guidance-migration.md. Record source section and line
ranges, destination document and heading, and whether each contract was moved,
merged with an existing equivalent, or corrected with evidence. Split long
player sections into individual contracts. Preserve exceptions, commands,
rationale and platform constraints. Do not create a required monolithic archive.
Destinations
Use existing authoritative docs first: Nx boundaries for structure/dependencies; validation-map for tests/lint; release-pipeline and release skills for releases; sqlite-db-worker and the database README for IPC/migrations; m3u-playlist-module for M3U/XMLTV/startup/source health; Xtream/Stalker compatibility docs for portals; player-controls-contract for web controls/radio/sleep; embedded-mpv-native for native runtime/packaging; UI guidelines, detail navigation and remote control for navigation; PWA/host connectivity/security docs for networking; existing download, TMDB, multi-source, workspace and backup docs for their domains; website README for website policy.
Create docs/development/agent-workflow.md for documentation/skill maintenance and Angular conventions, and docs/development/electron-debugging.md for CDP/tracing. Add a developer navigation link in README.md.
Root guidance and navigation
Retain project purpose, essential commands, .nvmrc/frozen install/Nx bootstrap, scoped imports and boundaries, migration safety, credential redaction, regression coverage, release-note/doc requirements, protected Markdown formatting and plan storage. Preserve the Nx-managed block/markers, conditional on available tools. Replace mandatory root-file updates with updates to each subsystem's canonical doc. Root instructions hold only universal rules and a compact topic routing table. Create docs/maintenance/agent-context-map.md with topics, code paths, docs and skills. Read affected contracts only; cross-domain work reads each relevant one. Update existing skills rather than proliferating copies; preserve byte-identical release mirrors. No mass nested instructions in this change.
Tooling
Extend repository-skills (no new Nx project) with agents:validate and node:test coverage. Check UTF-8 bytes/line budgets, one standalone @AGENTS.md import in CLAUDE.md and no other root imports, local navigation/map/migration links and anchors, and literal repository paths without treating globs/commands as paths. Add an unconditional CI validation step and correct Nx test inputs/lint commands.
Acceptance
Tests cover exact/over budgets, UTF-8, LF/CRLF, missing/duplicate/extra imports, missing local files and anchors. Run frozen install, Nx discovery, repository-skills test/lint, agents:validate, skills:validate, release:notes:validate, git diff --check and workflow validation. Audit every source block to a destination, with no unresolved or lost unique contract. Walk navigation for XMLTV, Xtream, MPV, migrations and releases. App unit/E2E is unnecessary (no runtime changes); no release note for docs/tooling validation. Do not run whole-file Prettier on docs, AGENTS.md or CLAUDE.md.