Imported from wyattowalsh/awesome-iina (
AGENTS.md). Install upstream withnpx skills add wyattowalsh/awesome-iina. Copyright stays with the author.
Agent instructions
Repository purpose
Maintain a high-precision public catalog of the IINA ecosystem and a high-recall, auditable GitHub discovery pipeline. Discovery findings are leads. src/awesome_iina/catalog/catalog.yaml is the reviewed source of truth. The contributor layout map is docs/README.md.
Required workflow
- Read the nearest implementation, model, test, and documentation before changing behavior.
- Edit source data or templates, never generated catalog sections directly.
- Preserve evidence provenance and report incomplete search coverage honestly.
- Add or update tests for any non-trivial Python change.
- Run
just checkbefore finishing. - Regenerate
README.md,src/awesome_iina/catalog/exports/catalog.json, and every file undersrc/awesome_iina/catalog/schemas/after catalog, model, or template changes.
Data rules
- Use
owner/repo, not a mutable GitHub URL, for GitHub projects. - Do not mark a project official without an authoritative IINA source.
- Do not infer active maintenance from stars, a topic, or repository existence.
- Do not silently resolve duplicate plugin identifiers. Represent and explain collisions.
- Keep project descriptions original, factual, concise, and punctuated.
- Prefer
unknownover guessing a project's current status. - Preserve archived projects only with a documented historical or migration reason.
Discovery rules
- GitHub's search index and result caps prevent an absolute claim of global completeness.
- A full run is complete only when every configured
QueryOutcome.completeis true. - Never drop an incomplete query, inaccessible repository, or invalid manifest without recording the failure.
- Query overlap is intentional for recall. Scoring must cap inflation from redundant evidence.
- Manual overrides belong in
src/awesome_iina/discovery/overrides.yaml, not hard-coded repository conditionals. - Scheduled discovery must remain
contents: read, upload partial evidence on failure, and save a comparison baseline only after a successful source refresh and complete scan. - REST/GraphQL reconciliation must preserve conflicting stable identities and must not use a repository name alone when that name is ambiguous.
Python conventions
- Python 3.13, Pydantic v2, Typer, uv, Ruff, ty, and pytest.
- Use strict models and explicit enums for persisted data.
- Keep network and process boundaries injectable and testable.
- Use
pathlib.Path, timezone-aware datetimes, deterministic output, and atomic writes. - Avoid new dependencies when the standard library provides a clear, maintainable solution.
Safety
Never commit tokens, personal media metadata, service credentials, or raw private discovery data. Treat plugin network/filesystem permissions and externally downloaded binaries as security-relevant evidence, not implementation trivia.
Copier starter boundary
starter/ is a complete separate tooling project, not generated junk.
Preserve its files, license, tests, and documented runtime/ownership policy. Edit its
canonical questionnaire, not a duplicate at root. Root copier.yml may override only
_subdirectory. Run python starter/repo_wrapper.py verify for offline contracts, then the
starter's own tests. Fixture rendering is never a fallback for missing real Copier.
Run the required real-Copier and installed-toolchain matrix before certifying updates.
Keep source/answers/ref evidence; never initialize user Git history or add --trust silently.
Do not package Node tools, tests, agent files, docs build sources or fixture answers into a
native plugin. Do package the full nested source tree in this repository's source ZIP.
Portable Agent Plugins source is starter/plugins/iina-plugin-dev/ (closed plugin.json,
skills, no mcp.json). Sync with just starter-sync-agent-kit / --check. Nested
starter/.cursor/skills/ is allowed; catalog-root .cursor/ and catalog-root plugin.json
are not. Generated consumers get workspace .cursor/skills without iina-generate.
Copier hooks: is Lefthook, not an agent hook. just starter-agent-plugin-install is an
opt-in symlink and must never run from just check.
Learned User Preferences
- Keep the repository nested in named domain folders. Do not leave a flat root or a flat
docs//tests/dump. - Keep the catalog website grouped into exclusive provenance sections, with IINA's published
plugins.jsonindex split from other native plugins and from official plugins. - Treat the catalog site in
src/awesome_iina/site/as a designed UI surface (hierarchy, contrast, section navigation), not a single inventory list. - Treat
starter/plugins/iina-plugin-dev/as a portable Agent Plugins kit for downstream IINA plugin authors using their own harness, not as catalog-maintainer tooling in this checkout. - In Plannotator/goal flows, do not stall on unchecked out-of-scope boxes; encode them as rejectable facts and continue.
Learned Workspace Facts
- Root membership is the contract in
src/awesome_iina/repo/root-policy.tomland ADR 0002: entry points only; allowed directories are.github,docs,skills,src,starter, andtests. Do not add rootschemas/,artifacts/,data/,brand/, orgoals/directories. Nested goal packages live underdocs/maintain/goals/. - Package code lives in nested
src/awesome_iina/{catalog,discovery,github,site,media,repo}/. Catalog YAML, schemas, and the README template live incatalog/. Discovery config, overrides, queries, and snapshots live indiscovery/. Site templates,brand.json, and the identity kit live insite/. Generated output isdist/site/. - Identity lives in
src/awesome_iina/site/kit/. Built site URLs still useassets/brand/. - JSON Schemas generate under
src/awesome_iina/catalog/schemas/; local run evidence belongs in gitignoredoutput/;SOURCE-MANIFEST.jsonis written inside source ZIPs only. .cursorstays inignored_directories, notallowed_directories.- Listing in IINA's
plugins.jsonis not officialness and is not first-party ownership. - Package tests group by domain under
tests/{catalog,discovery,github,media,site,cli,repo}/. Do not usetests/awesome_iina/, which would shadow the installable package. - Design SSOT is
docs/maintain/design.md. The public catalog insrc/awesome_iina/site/(built todist/site/) is the awesome-* web app;docs/is the contributor handbook, not a site. Generated Copier plugins must not receive catalog hues (consumer_plugins_receive_catalog_identity: falseinsrc/awesome_iina/site/brand.json); maintainerstarter/site/may map kit tokens, Copier Starlight CSS must not. - Catalog-root
skills/is maintainer-only (awesome-iina-maintainer). Do not add a catalog-rootiina-plugin-starterrouter;iina-generatebelongs in the user-installed portable plugin. Nestedstarter/.cursor/skills/may expose the portable kit in this checkout. - Origin GitHub publish is operator-gated; never push silently.
