inits

AGENTS.md

@@ -0,0 +1,45 @@
+# Repository Instructions
+
+## Scope and source layout
+
+- These instructions apply to the whole repository.
+- Treat root PHP files, `includes/`, `assets/`, `languages/`, and `readme.txt` as source. Never edit `build/` or release ZIP files directly; `./build.sh build` recreates them.
+- Read [README.md](README.md) for installation, shortcode, feed, cache, build, and layout details. Keep [README_zh.md](README_zh.md) synchronized when changing shared documentation.
+- The plugin supports WordPress 6.4+ and PHP 7.4+. Do not introduce syntax requiring a newer PHP version.
+- Preserve the existing WordPress naming and security conventions: `OICS_` classes/constants, `oics_` hooks/handles/keys/functions, direct-access guards, safe remote requests, sanitization, and context-appropriate escaping.
+
+## Architecture
+
+- `oi-contest-schedule.php` owns plugin metadata, constants, loading, and startup hooks.
+- `includes/class-plugin.php` owns WordPress integration, widgets, shortcode registration, and asset enqueueing.
+- `includes/class-contest-client.php` owns remote fetching, transient caching, validation, normalization, and sorting.
+- `includes/class-schedule-renderer.php` owns escaped server-rendered markup.
+- `assets/js/schedule.js` formats Unix timestamps in the visitor's locale/time zone and updates countdowns; `assets/css/schedule.css` owns presentation.
+- Keep the transient key synchronized between the contest client and `uninstall.php`.
+
+## Localization and text changes
+
+- Whenever modifying a file that contains text, explicitly check whether the change adds, removes, or changes user-facing/translatable strings and whether `languages/oi-contest-schedule.pot` and `languages/oi-contest-schedule-zh_CN.po` must also change.
+- PHP gettext calls use the `oi-contest-schedule` text domain. JavaScript-facing translated strings are localized from PHP.
+- Treat POT and PO files as editable localization sources. MO files are generated by the build and must not be committed from the source tree.
+- After PO changes, run `./build.sh build`; it validates gettext syntax and format placeholders with `msgfmt`.
+
+## Validation
+
+- Run `./build.sh build` after code, metadata, readme, asset, or translation changes. This is the repository's packaging and automated validation command.
+- Use `./build.sh clean` only to remove generated `build/` and ZIP artifacts.
+- There is no separate test, lint, Composer, or npm command. Do not invent one; add focused manual checks when behavior cannot be covered by the build.
+
+## Release requests
+
+When the user's message is exactly `release X.Y.Z` or `release vX.Y.Z` (allowing surrounding whitespace), perform the release preparation workflow below. Normalize the requested version to `X.Y.Z` and the tag to `vX.Y.Z`.
+
+1. Confirm the version is valid SemVer and inspect the worktree before editing. Do not overwrite unrelated user changes.
+2. Find the previous release tag from Git history, preferring the nearest reachable version tag: `git describe --tags --abbrev=0 --match 'v*'`. If none exists, state that the release notes cover the full repository history.
+3. Search tracked source files for the current version and release metadata. Update every applicable version occurrence, including the plugin header and `OICS_VERSION` in `oi-contest-schedule.php`, `Stable tag` plus changelog/upgrade-notice headings in `readme.txt`, and `Project-Id-Version` in both PO and POT files. Review other search results rather than assuming this list is exhaustive. Do not edit generated copies under `build/`.
+4. Review `git diff <previous-tag>..HEAD` and the commit log over the same range. Derive release notes only from that evidence; group user-visible changes, fixes, compatibility changes, and developer-facing changes as appropriate. Do not include uncommitted release-preparation edits as previously completed work unless clearly labeled.
+5. Add concise release entries to the repository changelog/upgrade notice where appropriate, keeping WordPress.org formatting valid. Check whether English and Chinese documentation or translations need corresponding updates.
+6. Run `./build.sh build` and report any validation failures. Confirm the produced ZIP version and the requested tag agree with the plugin header and `Stable tag`.
+7. Return release notes in both English and Simplified Chinese. The notes must be Markdown wrapped in a fenced code block, with clear `English` and `简体中文` sections. Include the version and comparison range (`<previous-tag>...vX.Y.Z`, or full history when no tag exists). Do not create a commit, tag, GitHub Release, or push unless the user explicitly requests it.
+
+The release tag must equal `v<plugin-header-version>` because the packaging workflow enforces that relationship. WordPress.org version tags are immutable; never attempt to overwrite an existing release tag.