# Repository AGENTS.md Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Create a comprehensive root `AGENTS.md` with repository-specific development, safety, workflow, and verification instructions for the water backend.

**Architecture:** Use one root instruction file as the default policy for all Maven modules. Keep operational rules and commands in that file, while linking to the existing detailed review standard and deferring workflow phase details to the selected Comet skill.

**Tech Stack:** Markdown, Java 17, Spring Boot 3.5.12, Maven, JUnit 5, Mockito, AssertJ, OpenSpec/Comet

## Global Constraints

- Create only the root `AGENTS.md`; do not modify application code, POM files, configuration, or existing workflow assets.
- Preserve all unrelated tracked and untracked working-tree changes.
- Keep Java 17 and Spring Boot 3.5.12 as the documented baseline.
- State explicitly that the root POM defaults `skipTests` to `true`.
- Default human-facing communication to Simplified Chinese while preserving code, commands, paths, API names, and errors verbatim.
- Link to `docs/code-review-standards.md` rather than duplicating its full checklist.
- Do not add credentials, tokens, personal data, production endpoints, or other secrets.

---

### Task 1: Create And Validate Root Repository Instructions

**Files:**
- Create: `AGENTS.md`
- Reference: `pom.xml`
- Reference: `docs/code-review-standards.md`
- Reference: `docs/superpowers/specs/2026-07-20-repository-agents-init-design.md`

**Interfaces:**
- Consumes: Maven module names, root test defaults, existing CodeGraph rule, and installed OpenSpec/Comet workflows.
- Produces: Root-scoped natural-language instructions consumed by Codex for every file in the repository unless a future nested `AGENTS.md` overrides them.

- [ ] **Step 1: Confirm the expected precondition and referenced paths**

Run:

```powershell
if (Test-Path 'AGENTS.md') { throw 'AGENTS.md already exists; inspect it before continuing.' }
$requiredPaths = @(
    'pom.xml',
    'water-admin',
    'water-common',
    'water-common/water-common-mqtt',
    'water-modules/water-app',
    'water-modules/water-system',
    'water-extend',
    'docs/code-review-standards.md',
    'openspec',
    '.codex/skills/comet/SKILL.md'
)
$missingPaths = $requiredPaths | Where-Object { -not (Test-Path $_) }
if ($missingPaths) { throw "Missing required paths: $($missingPaths -join ', ')" }
'Preconditions: PASS'
```

Expected: `Preconditions: PASS`.

- [ ] **Step 2: Create the complete root instruction file**

Create `AGENTS.md` with exactly this content:

```markdown
# AGENTS.md

## 交流与适用范围

- 本文件适用于整个仓库；更深目录中的 `AGENTS.md` 可为其子树补充或覆盖规则。
- 默认使用简体中文交流。代码、命令、文件路径、API 名称和错误原文保持原样。
- 只修改当前任务需要的内容。保留并避开工作区中与任务无关的已跟踪或未跟踪改动。

## CodeGraph

- 如果仓库根目录存在 `.codegraph/`，在定位或理解代码时，先使用 CodeGraph，再使用文本搜索或直接读取大量文件。
- MCP 可用时优先使用 `codegraph_explore` 回答代码问题，使用 `codegraph_node` 查看符号、调用者或带行号的文件。
- MCP 不可用时使用 Shell 命令，例如 `codegraph explore "MqttCommandAckService callers and retry flow"` 和 `codegraph node MqttCommandAckService`。
- 如果不存在 `.codegraph/`，不要自行建立索引；使用 `rg` 和 `rg --files`。

## 项目概览

- 本项目是智能灌溉系统后端，基于 Java 17、Spring Boot 3.5.12 和 Maven 多模块构建。
- `water-admin`：可执行 Web 应用、入口控制器及应用配置。
- `water-common`：跨业务模块共享的基础设施；MQTT 位于 `water-common/water-common-mqtt`，安全基础设施位于 `water-common/water-common-security`。
- `water-modules/water-app`：App、设备、灌溉及设备消息业务。
- `water-modules/water-system`：用户、权限及系统管理能力。
- `water-extend`：监控、任务调度等独立辅助服务。

## 修改前准备

- 先检查 `git status --short`，识别用户已有改动；不得回退、覆盖或顺手格式化无关文件。
- 修改共享行为前，追踪调用方、配置绑定、数据库或 Redis 状态、MQTT 消息路径及相关测试。
- 优先复用现有分层、包结构、工具类和领域类型。没有明确收益时不引入新抽象或跨模块重构。
- 变更范围涉及多个模块时，先确认真正的所有者模块和依赖方向，避免复制共享逻辑。

## 架构与编码约束

- 遵循现有 controller、service、mapper、domain 分层和相邻代码风格。
- 共享基础能力放入其所属 `water-common-*` 模块；业务规则保留在对应业务模块。
- 除非任务明确允许破坏性变更，否则保持跨模块接口、配置键、消息字段和持久化格式向后兼容。
- 新代码不得吞掉异常；日志应包含排障上下文，但不得记录密码、验证码、令牌、密钥或完整个人信息。
- 新代码使用明确泛型，避免循环查询造成 N+1，避免共享非线程安全格式化器，并用枚举、常量或领域类型表达状态值。
- 不为通过测试而削弱生产行为、删除断言或扩大公开访问范围。

## 安全敏感区域

- 修改登录、验证码、找回密码、注销账号或公开路由时，必须检查限流、输入校验、租户隔离、数据权限和敏感信息处理。
- 修改安全排除路径时，同时检查配置绑定和拦截器的最终生效路径，并添加聚焦测试证明只开放目标端点。
- 配置文件不得写入真实凭据、令牌、个人数据或生产地址；沿用环境变量、占位符或既有外部配置方式。
- 涉及密码更新时，保持密码散列、验证码一次性消费和失败分支行为一致，避免泄露账号是否存在。

## MQTT 与设备命令

- MQTT 或设备命令变更必须同时考虑协议字段兼容、ACK 匹配、重试间隔与次数、启动清理、Redis 键与 TTL、重复投递和并发状态转换。
- 不得在未验证设备兼容性的情况下重命名消息字段、改变状态含义或调整 topic 结构。
- 对时序门控、ACK 缺失、清理失败、重复 ACK、达到重试上限和并发完成等边界添加或更新测试。
- 涉及 Redis 临时状态时，明确创建、读取、续期和删除时机，避免永久残留或提前删除。

## 构建与测试

- 所有 Maven 命令从仓库根目录运行。
- 根 POM 默认配置 `skipTests=true`；`mvn clean package` 会跳过测试，不能据此声称测试通过。
- 全量测试：`mvn -DskipTests=false test`
- 带测试完整验证：`mvn clean verify -DskipTests=false`
- App 模块测试：`mvn -pl water-modules/water-app -am -DskipTests=false test`
- MQTT 模块测试：`mvn -pl water-common/water-common-mqtt -am -DskipTests=false test`
- 单个测试示例：`mvn -pl water-admin -am -DskipTests=false -Dtest=CaptchaControllerUnitTest -Dsurefire.failIfNoSpecifiedTests=false test`
- 其他模块或测试类沿用上述命令结构，替换为 Maven reactor 中的真实模块路径和测试类名。
- 行为变更先添加或更新能够失败的聚焦测试，再修改实现。共享模块或跨模块变更应扩大到受影响 reactor 范围。
- 安全、并发、Redis 和 MQTT 变更必须覆盖失败路径及兼容性；不能运行依赖外部基础设施的验证时，执行最窄的隔离验证并报告缺口。

## OpenSpec 与 Comet

- 新能力或较大行为变更使用 `/comet`。
- 不引入新能力的缺陷修复使用 `/comet-hotfix`。
- 文档、文案、提示词或局部配置调整使用 `/comet-tweak`。
- 选定工作流后，以对应 skill 的阶段、确认点和归档规则为准，不在任务中绕过其门禁。

## 完成标准

- 完成前检查 `git diff` 和 `git status`，确认只包含任务范围内的改动。
- 运行与风险范围匹配的测试，并在相关时运行编译、打包或配置验证。
- 只有看到当前会话中的命令成功输出后，才能声称测试通过、构建成功或问题已修复。
- 最终说明实际运行的命令、结果以及未能执行的验证；保留关键错误原文。
- 代码审查遵循 `docs/code-review-standards.md`，重点检查正确性、安全、并发、性能、异常处理、测试和日志。
```

- [ ] **Step 3: Verify structure, required guidance, and referenced paths**

Run:

```powershell
$content = Get-Content -Raw 'AGENTS.md'
$requiredText = @(
    '## CodeGraph',
    'Java 17',
    'Spring Boot 3.5.12',
    'water-common/water-common-mqtt',
    'skipTests=true',
    'mvn -DskipTests=false test',
    '/comet-hotfix',
    'docs/code-review-standards.md'
)
$missingText = $requiredText | Where-Object { -not $content.Contains($_) }
if ($missingText) { throw "Missing required guidance: $($missingText -join ', ')" }
$references = @(
    'docs/code-review-standards.md',
    'water-common/water-common-mqtt',
    'water-common/water-common-security',
    'water-modules/water-app',
    'water-modules/water-system'
)
$missingReferences = $references | Where-Object { -not (Test-Path $_) }
if ($missingReferences) { throw "Broken references: $($missingReferences -join ', ')" }
'Content validation: PASS'
```

Expected: `Content validation: PASS`.

- [ ] **Step 4: Review the isolated diff and Markdown formatting**

Run:

```powershell
git diff --check -- AGENTS.md
git diff --stat -- AGENTS.md
git status --short -- AGENTS.md
```

Expected: `git diff --check` prints no errors; the stat reports one new file; status reports only `?? AGENTS.md` for this task.

- [ ] **Step 5: Commit the initialized repository instructions**

Run:

```powershell
git add -- AGENTS.md
git diff --cached --check
git diff --cached --name-only
git commit -m "docs: initialize repository agent guidance" -- AGENTS.md
```

Expected: the cached file list contains only `AGENTS.md`, and the commit succeeds.