commons-logging-installer
Installs the logging and masking annotations and aspects into the project's empty commons package, once.
commons-logging-installer.md, section by section
The sections of the agent's own file, excerpted. Hover or click one to see which project rules and templates it cites. The sections are also chips: click one to jump to it.
## 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
… cut here, the rest is in the file
## 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"
What it reads, writes and refuses
The skill's own contract, from SKILL.md, in the original wording.
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.
Source: the agent's § Contract, at nerviz e4cae27.
What the guard does with it
installer is the agent's class. ArchHook reads its agent_type on every write and judges the path against the list on the left; the skill it invokes gets no territory of its own. The text on the right is the hook's own.
write_allow of class commons-logging-installer
- ✓
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 any path outside this list: refused, exit 2
A refusal exits with code 2 and the message goes back to the model.
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
Where it sits on the rail
Each card is a step of /new-feature-implement. The executor runs three times, one block group each; between two groups the orchestrator carries the reports forward. Dashed steps run only when the spec needs them.
/new-feature-implement orchestrator · sonnet