docs: design repository agent instructions

docs/superpowers/specs/2026-07-20-repository-agents-init-design.md

@@ -0,0 +1,101 @@
+# Repository AGENTS.md Initialization Design
+
+## Goal
+
+Create one root-level `AGENTS.md` that gives Codex durable, repository-specific instructions for safely changing and verifying the water backend. The file must be useful on its own while linking to detailed review guidance instead of duplicating it.
+
+## Scope
+
+The change adds only the root `AGENTS.md`. It does not change application code, Maven configuration, module-specific instructions, or existing OpenSpec/Comet assets.
+
+The instructions apply to the entire repository. A future nested `AGENTS.md` may add narrower module rules, but none are needed for this initialization.
+
+## Repository Facts
+
+- The project is an intelligent irrigation backend based on Java 17, Spring Boot 3.5, and Maven.
+- The root reactor contains `water-admin`, `water-common`, `water-modules`, and `water-extend`.
+- `water-admin` is the executable web application.
+- `water-common` contains shared infrastructure, including MQTT support in `water-common-mqtt`.
+- `water-modules` contains business modules; `water-app` handles app/device workflows and `water-system` handles system and user capabilities.
+- `water-extend` contains auxiliary services such as monitoring and job scheduling.
+- The root POM sets `skipTests=true`, so verification commands must explicitly use `-DskipTests=false`.
+- The repository already contains OpenSpec/Comet workflows and detailed review guidance in `docs/code-review-standards.md`.
+
+## AGENTS.md Structure
+
+The root instructions will contain these sections in order:
+
+1. Project overview and technology baseline.
+2. Module map and ownership boundaries.
+3. Code discovery and change preparation.
+4. Architecture and implementation constraints.
+5. Security-sensitive areas.
+6. MQTT and device-command constraints.
+7. Testing and verification commands.
+8. OpenSpec/Comet workflow selection.
+9. Definition of done and review reference.
+
+## Instruction Design
+
+### Code Discovery
+
+When `.codegraph/` exists, agents must use CodeGraph before text search or broad file reads. Otherwise they should use `rg` or `rg --files`. Before changing shared behavior, agents should identify callers, configuration bindings, persistence or Redis state, and relevant tests.
+
+Agents must preserve unrelated working-tree changes and avoid broad cleanup or refactoring unless required by the task.
+
+### Architecture and Code Quality
+
+Changes should follow the existing controller/service/mapper/domain layering and established package patterns. Shared behavior belongs in the owning common module rather than being copied into business modules. Cross-module APIs should remain backward compatible unless the task explicitly authorizes a breaking change.
+
+The instructions will prohibit swallowed exceptions, raw collection types in new code, hidden N+1 queries, unsafe shared formatters, unexplained magic status values, and sensitive values in source or logs. Detailed review criteria remain in `docs/code-review-standards.md`.
+
+### Security Boundaries
+
+Changes involving authentication, captcha, password recovery, account cancellation, or public route exclusions must preserve rate limiting, input validation, tenant and data-permission behavior, and sensitive-data handling. Public-route changes require focused tests and inspection of the effective security exclusion configuration.
+
+Configuration files must not receive real credentials, tokens, personal data, or production endpoints. Existing placeholders and environment-driven configuration patterns should be retained.
+
+### MQTT Boundaries
+
+MQTT and device-command changes must consider protocol compatibility, ACK matching, retry timing and limits, startup cleanup, Redis key and TTL behavior, duplicate delivery, and concurrent state transitions. Relevant unit tests must cover changed behavior, especially timing gates and cleanup failure paths.
+
+### Build and Test Commands
+
+The file will document these commands:
+
+```powershell
+mvn clean package
+mvn -DskipTests=false test
+mvn -pl <module> -am -DskipTests=false test
+mvn -pl <module> -am -DskipTests=false -Dtest=<TestClass> -Dsurefire.failIfNoSpecifiedTests=false test
+```
+
+`mvn clean package` reflects the repository's default package behavior and skips tests because of the root property. Any claim that tests pass must come from a command containing `-DskipTests=false`.
+
+Behavior changes should add or update focused tests before implementation. Shared or cross-module changes require broader reactor testing. High-risk security, concurrency, Redis, or MQTT changes require focused failure-path and compatibility coverage.
+
+### Workflow Selection
+
+- Use `/comet` for new capabilities or substantial behavior changes.
+- Use `/comet-hotfix` for defect corrections that do not introduce a new capability.
+- Use `/comet-tweak` for documentation, copy, prompt, or narrowly scoped configuration changes.
+
+The root instructions will not duplicate each workflow's phase rules; the selected skill remains authoritative.
+
+### Definition of Done
+
+Before reporting completion, agents must inspect `git diff`, run tests proportional to the change, confirm compilation or packaging when relevant, and check configuration compatibility. They must report commands actually run and any verification that could not be performed.
+
+## Error Handling
+
+If a required build or test depends on unavailable infrastructure, the agent should run the narrowest isolated verification available, preserve the original error output, and clearly report the remaining gap. It must not weaken production behavior or tests merely to obtain a passing command.
+
+## Validation
+
+The implementation will be validated by:
+
+1. Confirming the root `AGENTS.md` exists and is readable Markdown.
+2. Checking every documented path against the repository.
+3. Checking Maven commands against the root reactor and explicit test override.
+4. Scanning for placeholders, contradictions, duplicated rules, and accidental secrets.
+5. Reviewing the final diff to ensure no unrelated files were changed.