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:

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:

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:

Public signature/semantic compatibility.
Layer ownership and dependency direction.
Descriptor/View/Composition/HTTP contract consistency.
Sensitive/write/query authorization boundaries.
Managed synchronization and transaction behavior.
Adapter parity, especially httplib versus Drogon.
Independent public-header compilation, install consumer, package contents, frontend build, and E2E coverage.

Dependency and release policy

Source-tree builds may use the pinned nlohmann/json, magic_enum, and cpp-httplib copies under backend/service/third_party/include; installed Adminive adapter targets must resolve those dependencies through their external CMake packages instead of installing bundled headers into the consumer's generic include namespace.
Keep THIRD_PARTY_NOTICES.md, third_party/licenses/, RELEASE.md, install-consumer checks, and package ZIP checks synchronized with dependency version changes.
The repository does not declare an outbound license for Adminive/Structive project-owned code. Do not invent or infer one.
Release verification against Drogon must include the opt-in real dependency gate: python scripts/verify.py --real-drogon. Fake Drogon tests remain fast contract tests, not a substitute for that release gate.

6.6 KiB Raw Blame History