mirror of
https://github.com/4gray/iptvnator.git
synced 2026-10-08 09:01:03 -08:00
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
68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# 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.
|