添加AGENTS SKILL

AGENTS.md

@@ -0,0 +1,89 @@
+# Adminive Codex Instructions
+
+## Mandatory skill usage
+
+- Use `$adminive-development` before editing Adminive runtime/API/protocol code, adapters, the Gallery frontend, tests, CMake, install/export, or packaging behavior.
+- If the task touches `third_party/Structive/`, also read `third_party/Structive/AGENTS.md` and use its `$structive-development` workflow. Structive rules override this file inside that subtree.
+- Do not use Git commands or modify repository history.
+
+## Project purpose
+
+Adminive projects ordinary C++ business objects into backend-admin capabilities. The backend definition is the source of truth for object descriptors, field presentation, form/collection views, page composition, JSON/HTTP contracts, AMIS schemas, managed mutation, status, and transactions. The React frontend consumes generated contracts and must not maintain a second business-field schema.
+
+Read `README.md` for usage and `backend/library/DESIGN.md` for architecture before changing public behavior.
+
+## Architecture boundaries
+
+- `third_party/Structive`: intrinsic property/schema/constraint/synchronization/runtime-structural capability. It must not learn Adminive UI, HTTP, AMIS, CRUD, or persistence semantics.
+- `backend/library`: Adminive Core protocol. Keep it independent of concrete JSON libraries, HTTP frameworks, enum libraries, PFR, and frontend frameworks.
+- `backend/service/include/adminive/adapters`: concrete bridges for nlohmann JSON, magic_enum, Boost.PFR, cpp-httplib, and Drogon.
+- `backend/service/src`: example runtime, Gallery, persistence sample, and server wiring. Do not move reusable protocol behavior here.
+- `frontend`: renderer/documentation client. It consumes descriptors/views/manifests/AMIS; do not duplicate C++ business fields in React.
+
+When deciding where a feature belongs, preserve this dependency direction:
+
+```text
+Structive -> Adminive Core -> Service adapters -> Example runtime/frontend
+```
+
+## Compatibility and implementation rules
+
+- Preserve the existing function signature and semantic contract whenever modifying an existing function.
+- If replacing an implementation, delete the old implementation. Do not add compatibility shims unless the design explicitly requires compatibility.
+- Do not introduce a second implementation path merely to support old behavior.
+- Add validation at the outer protocol/transport boundary when needed; do not repeat equivalent checks in every inner layer.
+- Static facts belong in C++20 `constexpr`, concepts, `requires`, or schema validation. Dynamic input belongs in runtime validation.
+- `managed writable` is not the same as frontend `editable`/`creatable`.
+- `sensitive` fields must not leak through frontend data or default-bearing descriptors.
+- Collection query capability is enforced by the backend View Schema. Transport adapters must not silently grant or silently ignore unsupported sort/search/filter fields.
+- `frontend` composition delegates final layout to the frontend; other composition kinds retain backend semantic positioning.
+- AMIS is an adapter target, not the business description language.
+- Synchronization is for in-process mutable consistency. `Resource_Transaction` is for external prepare/commit/rollback. Do not merge those concepts.
+
+## Coding style
+
+- C++ uses K&R brace style.
+- Do not add meaningless blank lines.
+- Keep comments adjacent to the code they explain; do not separate a comment from its code with a blank line.
+- Prefer small semantic functions over compatibility wrappers or defensive checks at every layer.
+- CMake paths must be relative to the `.cmake`/`CMakeLists.txt` that owns them, normally through `CMAKE_CURRENT_LIST_DIR`. Do not base project paths on `CMAKE_SOURCE_DIR`/`PROJECT_SOURCE_DIR` unless the existing design explicitly requires it.
+- Do not change build/output path patterns or add random path components.
+- If a PowerShell script is needed, write it for PowerShell 7 and run it with `pwsh`.
+
+## Tests and verification
+
+- Tests must use `ADMINIVE_CHECK`, not standard `assert()`, because Release defines `NDEBUG`.
+- Public headers must remain independently includable; keep header compile tests up to date when adding/removing public headers.
+- Protocol changes require focused unit/protocol tests and transport tests when the behavior is visible over HTTP.
+- Changes to install/export/package behavior require install-consumer and package ZIP tests.
+- Changes to frontend TypeScript/React require `npm run build`; renderer/protocol logic should also run `npm run test:unit`. Browser-visible behavior should run the Playwright E2E gate when dependencies are available.
+- Do not claim a verification step passed unless it was actually executed.
+
+Useful commands from the repository root:
+
+```text
+cmake -S . -B verification/debug -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON
+cmake --build verification/debug
+ctest --test-dir verification/debug --output-on-failure
+python scripts/verify.py
+```
+
+For a focused test, build and run the smallest affected target first, then run the broader gate before handoff.
+
+## Packaging
+
+- `package_zip` is part of the release contract. Keep `AGENTS.md`, `.agents/skills/`, and the nested Structive guidance in the source archive.
+- Generated source ZIP timestamps must use China Standard Time (`UTC+08:00`).
+- Do not package build directories, `node_modules`, frontend build output, test reports, temporary verification trees, or stale removed implementations.
+
+## Review priorities
+
+When reviewing a change, check in this order:
+
+1. Public signature/semantic compatibility.
+2. Layer ownership and dependency direction.
+3. Descriptor/View/Composition/HTTP contract consistency.
+4. Sensitive/write/query authorization boundaries.
+5. Managed synchronization and transaction behavior.
+6. Adapter parity, especially httplib versus Drogon.
+7. Independent public-header compilation, install consumer, package contents, frontend build, and E2E coverage.