Nerviz

Meta-repository: generates Spring Boot projects already prepared for AI-assisted development. It is not a Java application — it has no pom.xml, does not compile, has no Maven tests. What gets edited here are instruction files, data, and a hook.

Purpose, features and status: @README.md.

Dependencies

java (JDK 21+) · git · curl. Nothing else. Zero Python, zero shell, zero mvn on PATH — the wrapper comes in the Initializr's starter.tgz. The mods under .claude/mods/ run inside Claude Code itself; only the mods CI workflow installs anything else (the Claude CLI, from npm, to test them). Node (from npm, pinned by the skill's lockfile) is needed only for /nerviz-diagrams's PNG/video export, in this repository only; everything else, including the CI gate, stays Java.

Commands

Architecture of the AI files

Clean Architecture applied to .claude/ itself. Dependencies point in one direction:

mods/                       interface — draws what hooks/ decide, only where it loads
        ↓ asks (java -jar ArchHook.jar), never restates
hooks/ + settings.json      infra/enforcement — deterministic
        ↓ verifies
skills/                     procedure + exemplars
        ↓ invokes                    ↑ delegates via context: fork
agents/                     isolated execution
        ↓ cites, never copies
rules/ + blueprints/ + .mcp.json   norms and data   ← LEAF

decisions/                  history — nobody reads it at runtime, outside the graph

claude-code-architect-designer writes upward into hooks/ + settings.json after approval — a design-time edge, like project-bootstrap writing src/; the runtime direction is unchanged.

Invariants (non-negotiable)

1. rules/ is a leaf. A norm never mentions a skill, an agent, or a command. If it needs to, it's a procedure and belongs in a skill.
2. Each norm has a single owning file. Others cite it by path (@.claude/rules/naming.md). A norm written in two places has diverged — that's a bug.
3. Code boilerplate lives in templates/ inside the skill that emits it, with the .example suffix. Never inside a norm, never pasted into the body of a SKILL.md.
4. No new commands/ are created. Slash commands were merged into skills: write skills/<name>/SKILL.md and control invocation with disable-model-invocation.
5. An agent exists only for one of three reasons: preserving context, restricting tools, or changing model. If none applies, it's a skill.
6. If a rule must always hold, it's a hook or permissions.deny — not prose in markdown. Owner: claude-code-architect-designer, forms 7 and 8, after approval and always with a record in decisions/. The mirror holds too — a hook against a failure nobody observed is a process per event confirming what was already true.
7. Architectures are data. Adding a blueprint must never require editing a skill, an agent, or a command.
8. Java and Spring Boot versions are never written from memory. They are resolved at runtime via Spring Initializr; without network access, ask.
9. The generated project is self-contained. Whoever clones it does not have Nerviz. Everything cited from inside the project must exist inside the project: norms, development skills, agents, ArchHook.java and schemas/extensions.json. ArchHook.java export writes all of it (step 6.6 of project-bootstrap), and what travels is data, in the export block of @.claude/schemas/extensions.json — creation skills excluded on purpose, and the blueprint catalog too, with one exception the manifest names: the active blueprint travels (export.blueprint_copy), because the stamp records its id, an update has to resolve it, and a blueprint written during adoption exists nowhere else. A new norm, skill or agent is complete once that block lists it: every skill and agent on disk in include or exclude, a derived_paths entry for a rule with a package territory, and ArchHook.java schema failing by name on either gap. An MCP server has the same obligation, per server, not per file: it is declared for this meta-repo (.mcp.json), for the generated project (project-bootstrap/templates/mcp.json.example, copied by export.optional_copy), or both — and the file it's written into is that declaration. A server useful to both is written in both files on purpose; that is not a duplication bug, see invariant 2. A hook, the same: the registration is per file (.claude/settings.json, project-bootstrap/templates/settings.json.example); a mode inside ArchHook.java needs nothing, the export mode copies that file whole. A skill has a second obligation on top of export: a class in skill_classes, which is what gives it a body shape and a write territory. A skill in no class has no territory — schema fails by name on it, in this repo and inside a generated project. An agent has the same second obligation, in agent_classes: its class fixes the sections its body carries, the frontmatter fields it must declare (model and tools always — two of the three reasons it is allowed to exist), whether it may write at all (executor), and the paths it may write. Territory there is keyed on agent_type, so it holds no matter which skill phase the caller left open.
10. Recognized frontmatter fields, .mcp.json's server fields, and settings.json's hook events and entry fields are data with a single owner. The list lives in .claude/schemas/extensions.json, ArchHook.java schema is what reads it, and any other file that displays it is derived and must match it exactly. A corollary of 2 and 7, written separately because its failure mode is silent: the runtime ignores an unknown field without any error — an unknown event too, and a matcher on an event that never reads one — and claude plugin validate lets it all through, looking at neither .mcp.json nor settings.json. Binds the Java too: a mode reads its lists from extensions.json, never from a constant in the source.
11. No literal secret in a versioned file. .mcp.json (this repo's or the copy inside a generated project) carries only ${VAR} / ${VAR:-default} expansion, oauth, or headersHelper — never a token, key, or password spelled out. Verified by ArchHook.java schema's secret scan over headers/env. A leaked token in git history is irreversible; that is why this is a hook and not a review checklist.

Routing — when X, read Y

Known pitfalls

Every silent trap — the runtime's and this repository's: write territories, frozen spec folders, who owns pom.xml and the outbox, what guard sweep and compose gate cover — lives in @docs/pt-br/11-pitfalls.md, read when a piece of .claude/ is designed or edited. Most of this repository's sit behind guard, schema or compose gate, whose block message names the rule and the fix. A new pitfall goes there, never here. What stays bites in any session with no hook behind it:

• The CLAUDE.md at the root of a generated project is not this file. It comes from .claude/skills/project-bootstrap/templates/root.CLAUDE.md.example.
• The hooks run .claude/hooks/ArchHook.jar, not ArchHook.java. Editing the source changes nothing a hook executes until java .claude/hooks/ArchHook.java build rewrites the jar — under the JDK major hook_build.javac_feature pins, or build refuses, since only the same javac reproduces the committed bytes that CI's build --verify compares. Here a PostToolUse entry rebuilds it on every edit of the source. The jar is committed: .gitignore ignores *.jar and un-ignores this one path — drop that line and CI fails on every OS with the jar "missing". Design: @.claude/decisions/0075-precompiled-hook-jar.md.
• This repository does not run ./mvnw. ArchHook exits 0 when it finds no wrapper; here that is expected, not a failure.