commons-logging-installer.md，逐节说明
agent 自己文件的各节，为节选。把鼠标移到某一节上或点击它，可以看到它引用了哪些项目规则和模板。各节也是标签：点击即可跳转。
## Why this is an agent (Form 3)
Preserves context. Same shape as archunit-installer: translate exemplar packages to the project's own, write a fixed set of files, edit a POM, run ./mvnw up to twice, iterate until green. None of it needs the conversation that triggered it — the /new-feature-implement run that detected the gap doesn't need eleven file writes and a build log landing in its own context and getting re-paid on every later turn.
No tool or model reason applies on its own — reads and writes stay inside the project, same complexity class as archunit-installer, which already uses sonnet. Invariant 6 requires only one of the three reasons; this is the one that applies.
omitClaudeMd: true: the root CLAUDE.md is a declared input, Read explicitly at step 2; auto-loading it too paid for the same file twice (@.claude/decisions/0083-unused-ecosystem-fields-and-real-allow-list.md).
## Procedure
- Locate the
commonsshell. Discover it the same wayjava-spring-boot-developer
- Resolve the real package. Read the project's root
CLAUDE.md(and thecommons
… 此处截断，其余见文件
## Failure mode
No commons shell found: `` ❌ commons-logging-installer stopped — no commons package/module found project-bootstrap didn't create one for this blueprint, or step 4.7 wasn't run. Nothing installed. ``
Compilation breaks after translation: `` ❌ GlobalHttpMethodLogAspect.java:14: cannot find symbol GlobalProperties Translation bug — the package rewrite in step 3 missed a reference. Fix before continuing. ``
No rollback. The caller decides whether to retry after a fix.
---
## Summary format returned to the caller
✅ commons-logging-installer complete
- Package: com.example.demoapp.commons.logging (12 classes translated across its annotations/aspect/enums/interfaces/properties sub-packages)
- Tests: 3 classes in src/test/java under the same package — green
- AutoConfiguration.imports: 3 aspects registered
- Dependencies: spring-boot-starter-aspectj (or -aop, pre-Boot-4), spring-boot-configuration-processor (no <version> — parent-managed)
- <module> test-compile: greenOn failure, same shape with ❌ and the one line that matters (the real compiler error), not the full build log.
---
## References
- Invariant 6 — agent only for one of three reasons (context, tools, model)
@.claude/agents/archunit-installer.md— same shape, same "installed once, not at@.claude/rules/logging.md— the masking mechanism these classes implement@.claude/skills/project-bootstrap/SKILL.md— the "no.javabeyondpackage-info.java"
它读什么、写什么、拒绝什么
skill 自己的契约，取自 SKILL.md，保留原文。
Class
installer — the territory is agent_classes.installer.overrides.commons-logging-installer in @.claude/schemas/extensions.json: the POMs, /src/main/java//logging/, its mirror /src/test/java//logging/ for the three unit tests, and the META-INF/spring/*.imports file. The glob matches the leaf segment on purpose — the package is commons.logging under most blueprints and shared.logging under modular-monolith, and no blueprint guarantees either name. ArchHook.java guard reads this agent's agent_type on every write and refuses a path outside the list with exit 2.
Executor
yes — writes under src/ while a design phase may still be open. The class grants it (executor: true), and ArchHook.java schema cross-checks this marker against that flag in both directions.
Pattern catalog
not injected — copies fixed templates, designs no code (agent_classes.installer.pattern_catalog: false; schema cross-checks this line).
Input (required)
project root. Precondition — the commons package/module already exists, empty, with its package-info.java (written by project-bootstrap step 4.7, per the active blueprint's packages.map entry commons.logging) — is the caller's (/new-feature-implement's pre-flight check) to verify before invoking; this agent doesn't re-derive it, only fails loudly if it isn't there.
Reads
root POM, module POMs (multi-module only), the active blueprint's packages.map (for the real commons.logging package — modular-monolith names it shared.logging instead, see its own blueprint comment), .claude/rules/logging.md, .claude/skills/new-feature-implement/templates/commons/*.example (the sixteen exemplars: twelve production .java.example, three *Test.java.example, plus AutoConfiguration.imports.example).
Writes
one .java file per exemplar in templates/commons/, translated into the real commons.logging package, under the module/package project-bootstrap already created; the three *Test exemplars under the same package in src/test/java — installed code arrives tested, so no later run improvises its tests (lessons-learned-017 § 7); src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports (new file, or a merge if test-architect/another feature already wrote one — append, never overwrite existing lines) in the module with contains_main: true; the spring-boot-starter-aspectj (spring-boot-starter-aop pre-Boot-4 — see dependency-catalog.md) and spring-boot-configuration-processor (optional, same scope Lombok already uses) dependency declarations — no <version>, spring-boot-starter-parent manages both, same rule project-bootstrap step 4.8 applies to Lombok — in whichever module's POM commons corresponds to (multi-module) or the root POM (single-module).
Does not write
docker-compose.yml, anything outside commons's own package (main or test), application.yml (the app.logging.* properties ship with sensible defaults in the exemplars themselves — matchIfMissing = true — nothing to configure to get a working install).
Does not invoke other agents or skills — no `Agent` tool
If the commons shell doesn't exist, report that and stop; the caller decides whether to re-run project-bootstrap or fix the blueprint by hand.
Returns
one structured summary (shape at the bottom), not the raw ./mvnw output.
来源：agent 的 § Contract（nerviz e4cae27）。
guard 如何处理它
installer 是这个 agent 的类。ArchHook 在每次写入时读取它的 agent_type，并按左侧的列表判断路径；它调用的 skill 没有自己的领地。右侧文字是 hook 自己的输出。
commons-logging-installer 类的 write_allow
- ✓
pom.xml - ✓
**/pom.xml - ✓
src/main/java/**/logging/** - ✓
**/src/main/java/**/logging/** - ✓
src/test/java/**/logging/** - ✓
**/src/test/java/**/logging/** - ✓
src/main/resources/META-INF/spring/*.imports - ✓
**/src/main/resources/META-INF/spring/*.imports 列表之外的任何路径：拒绝，退出码 2
拒绝以退出码 2 结束，消息回到模型。
PreToolUse Agent(commons-logging-installer) audit call exit 0 guard call exit 0 SubagentStart context subagent exit 0 tests agent-start exit 0 # installer · sonnet · write_allow: pom.xml, **/pom.xml, src/main/java/**/logging/**, **/src/main/java/**/logging/**, src/test/java/**/logging/**, **/src/test/java/**/logging/**, src/main/resources/META-INF/spring/*.imports, **/src/main/resources/META-INF/spring/*.imports
SubagentStop audit agent exit 0 tests agent-end exit 0 Stop audit flush Recording the execution trail... exit 0 schema Validating frontmatter... exit 0 guard sweep Sweeping what this turn wrote... exit 0 compose gate Checking compose services... exit 0 tests Running the verify gate on changed modules... exit 0
它在轨道上的位置
每张卡片是 /new-feature-implement 的一步。执行器运行三次，每次一组块；两组之间由编排器带着上一组的报告继续。虚线的步骤仅在 spec 需要时运行。
/new-feature-implement orchestrator · sonnet