nerviz-cockpit

<img alt="Nerviz — an agent harness for Spring Boot" src="brand/nerviz-banner-light.png" width="100%">

An agent harness for Spring Boot on Claude Code. It generates the project from an architecture declared as data, designs every feature as an approved spec before any code is written, and blocks at write time what that architecture forbids. Generated projects carry the whole harness with them and can update it later.

Documentation: docs/en/ (English) · docs/pt-br/ (português). How it compares with similar projects, with sources: docs/en/09-differentiators.md.

What one /init-project run produced is public: nerviz-ai/bank-app, a clean-architecture-single-module project with a green build. The run took 20 minutes, a figure read from the session transcripts into its GENESIS.md.

The generated project, opened as is: it starts against the compose Postgres, and mvn clean verify passes with tests, Spotless, Checkstyle and JaCoCo.

Then the first feature, inside the generated project. /new-feature takes a one-line request, asks only the questions that change the design (who may call it, duplicates, the age rule, data retention), and has one skill per layer write its part of the spec. The spec is approved, frozen, committed and pushed before a single line of code exists. The run took 10 minutes, about 2 of them waiting for answers.

Everything it wrote is public: the approved spec, its partials, and the run's audit report. That is the first of /new-feature's two flows. The second, /new-feature-implement UC-001-create-customer after /clear, hands the approved spec to the executor agent in a clean session.

At a glance

• Nine architectures as data, plus your own. A blueprint is a YAML file. Adding one changes no prompt.
• Spec before code. One use case per run, designed layer by layer by an owner skill for each layer, approved by you, then frozen.
• Blocked at write time. A forbidden import, a write outside a skill's territory, an edit to an approved spec, or a force push is refused by a hook. The model is not asked to remember the rule.
• Versions from Spring Initializr, never from the model's memory.
• Every run measured. Each skill and agent leaves a report with its time, tokens, questions asked and files touched.
• Self-contained projects. A generated project carries the whole harness and its own CI, and /arch-adopt updates it later.

What this is, and what it is not

The working definition in 2026 is agent = model + harness. Claude Code supplies the model and the tool loop. This repository supplies the rest of the harness for Spring Boot work, in two parts:

• Guides steer the model before it acts: norms (rules/), procedures and exemplars (skills/), architecture blueprints, and the use-case spec of the feature being built.
• Sensors check what the model did, deterministically: hooks that refuse a write outside a skill's territory or a forbidden import, the incremental build, ArchUnit, a compose health gate, and a CI that validates the harness itself.

It is not a coding assistant: it brings no model and no editor. It is not an agent framework like LangGraph or Spring AI: those build agents, and this repository constrains one. And it is not a project template: it generates through Spring Initializr at run time, and its job continues after generation, on every feature.

The problem

You start a Java project with a 30-line CLAUDE.md. Six months later it is 400 lines, the model ignores half of it, and the same rule lives in three skills that no longer agree. The AI "forgets" the architecture because nothing tells it cheaply and reliably what is true in this project, and nothing stops it when it gets it wrong.

Every new project also starts from zero. The same conventions get written again, and nothing learned on the previous project survives.

The approach

Treat the AI files as production code: an explicit architecture, dependencies in one direction, one owning file per rule, and enforcement by a program rather than by the model's memory. Concretely:

• Architecture is data. Nine blueprints (hexagonal, hexagonal-single-module, clean-architecture-multi-module, clean-architecture-single-module, layered, onion, onion-single-module, vertical-slice, modular-monolith) plus your own, each a YAML file. One forbidden_imports declaration feeds the module's CLAUDE.md, the hook that blocks the write, and the POM graph. A new architecture touches no prompt, and CI checks that.
• Versions are never written from memory. The base project comes from start.spring.io at run time. CI fails if a Spring or Java version appears as a fact.
• One use case per run, designed before it is built. /new-feature passes the request through one owner skill per layer and consolidates an UC-NNN-spec.md. Only after approval does a restricted executor agent write code under src/.
• Territory is enforced, not promised. Every skill and agent has a class in schemas/extensions.json. The class says which paths it may write, and the guard hook refuses everything else, through file tools and shell commands alike. An approved spec folder is frozen.
• Context stays cheap. The root CLAUDE.md stays under 200 lines. Norms load through paths only when a file in their territory is touched.
• Every run is measured. In a generated project, each skill or agent invocation leaves a report with tokens and the model per piece, the call chain, files touched, and failures.

Getting started

Requirements: JDK 21+, git, curl. Nothing else: no Python, no Node, no shell scripts, no mvn on the PATH (the wrapper comes inside the Initializr's starter.tgz).

New project

A project is generated from a copy of this repository, not by copying .claude/ into an empty directory. /init-project and the blueprint catalog stay in that copy; the project receives only what it needs to develop, written by the export mode. The copy is a clone, below, or the tree the plugin fetches without one:

claude plugin marketplace add nerviz-ai/marketplace
claude plugin install nerviz@nerviz
cd ~/dev && claude        # the directory that will hold the projects

Then /nerviz:new-project: it fetches the latest release into ~/dev/nerviz-<tag>, records which tag and commit it fetched, and prints the session to open there for /init-project. The generation is the same one a clone runs. With a clone instead:

# 1. clone next to where the projects will live
cd ~/dev
git clone --depth 1 https://github.com/nerviz-ai/nerviz

# 2. confirm the tools (nothing to install); gh is only for the optional push
java --version && git --version && curl --version | head -1
gh auth status

# 3. open the session in the clone
cd nerviz
claude

Inside that session:

/arch-doctor                 # confirms enforcement is active on this machine
/init-project --blueprint hexagonal --build maven --name my-api

Claude Code asks before writing outside the directory the session started in. To approve the generation once, run mkdir ../my-api and /add-dir ../my-api before /init-project; an empty directory is accepted.

The project is born next to the clone, at ../<name> (~/dev/my-api above). At the end, git-publish asks twice: once to run git init and make the first commit, once to create the GitHub repository and push. One clone generates as many projects as you want: /clear between them.

Then open a new session inside the generated project to develop:

cd ../my-api
claude

/new-feature <what the first use case should do>

Why this order:

• The generated project carries its own .claude/. The export mode writes the rules, the development skills, the executor agents, the hook, and the active blueprint. It leaves out init-project, project-bootstrap, and the blueprint catalog, so a project cannot regenerate itself on top of live code. It also refuses to write into this repository.
• .claude/settings.json is read once, at session startup. The session opened in the clone runs with this repository's hooks, not the project's. Developing in it means none of the project's hooks fire, and everything looks like it works.
• Accept the first git-publish gate. The tests hook uses git diff HEAD. In a repository without commits, HEAD does not exist and the hook exits without running a single test.

The project's own CLAUDE.md is generated during bootstrap, with the resolved versions and the real module list. This repository's root CLAUDE.md describes the meta-repository and does not travel. The full generation sequence is in docs/en/02-init-project.md.

Existing project

From inside a session in that project, /arch-adopt installs this .claude/ into a project that was never generated here, or pulls a newer version into one that is behind. It refuses a dirty worktree and writes through the deterministic export mode. It also stamps .claude/.arch-provenance.json, so the next update names every file you edited by hand before overwriting it. On an update, it prints the migrations notes for convention changes the project has not seen yet; it never runs them. See docs/en/10-arch-adopt.md.

Silent failures to know about

The hooks exit 0 when they cannot verify something. That is safe, but it can give false greens, which is why /arch-doctor exists. More traps, runtime and repository alike: docs/en/11-pitfalls.md.

Flows

/init-project — creating the project

/init-project
     │
     ├─ 1. INTERVIEW, in the main session — blueprint · coordinates · build · features · TLS · Sonar
     │
     ▼  agent: project-initializer (isolated context, model: sonnet, asks nothing)
     │
     ├─ 2. VALIDATES blueprint — 6-rule checklist            [fails fast]
     ├─ 3. BASE via Spring Initializr (curl)                 [GA versions, nothing hardcoded]
     ├─ 4. RESTRUCTURES into modules per the blueprint       [exemplars give the shape]
     ├─ 5. GENERATES forbidden-imports.txt + root and module CLAUDE.md/AGENTS.md, CI, Checkstyle,
     │      lombok.config, logback, Dockerfile + docker-compose
     ├─ 6. EXPORTS norms, development skills, executor agents — the project is self-contained
     ├─ 7. INSTALLS hooks (ArchHook.jar + extensions.json + settings.json), opens the audit trail
     ├─ 8. VERIFIES build + smoke + tested boundary block; writes README + GENESIS.md
     ├─ 9. REPORT in the fixed output contract
     ├─ 10. GENESIS.md figures from the session transcripts — Started, Finished, tokens
     └─ if the build is green: OFFERS git-publish — two independent confirmations

No business code is generated: no ExampleController to delete. The first feature comes from a real spec.

/new-feature — one use case, spec first, code in a clean session

One command, two flows. The argument decides which, and the two never share a session: the design leaves the main thread at 250–370k tokens of context, and implementing on top of it would pay for that on every turn.

Flow 1 — create the spec. /new-feature <feature description>

/new-feature <feature description>     (or UC-NNN-slug to resume a draft, or empty to list)
     │
     use-case-design → domain-modeling → rest-api-architect (unless GraphQL only)
        → graphql-api-architect (conditional)
        → security-architect (conditional) → http-client-architect (conditional)
        → ai-architect (conditional) → search-architect (conditional)
        → messaging-architect (conditional) → jobs-architect (conditional)
        → persistence-architect → cache-architect (conditional) → test-architect
     │  one use case per run; a split goes to docs/use-cases/BACKLOG.md
     │  design skills write only docs/ — never src/, never docker-compose.yml, never git
     │  a missing DB or broker is asked about and recorded: add it, runs elsewhere, or by hand
     │  each one decides the design patterns of its own layer, in its partial
     │
     ▼  consolidates into UC-NNN-spec.md (status: draft)
     ▼  asks approval → status: approved (the guard hook freezes the folder from here)
     ▼  git-publish (the approved spec only)
     ▼  prints the next two commands:  /clear  ·  /new-feature-implement UC-NNN-slug

Flow 2 — implement the spec. /new-feature-implement UC-NNN-slug over an approved spec, after /clear

/new-feature-implement UC-NNN-slug     (status: approved — the command is the request)
     │
     │  pre-flight, once per project (ArchUnit, logging/masking aspects)
     │  agent: java-spring-boot-developer, pattern catalog injected at start,
     │         in three chained groups, each starting again from the spec and the disk:
     │
     │    domain (blocks 1–2) → adapters (H, 3, S, M, J) → tests (block 4, ./mvnw verify)
     │
     │  each group ticks its checklist steps when it ends green;
     │  a failed group stops the chain, and the same command resumes there
     │
     ▼  status: implemented (or implemented-blocked)
     ▼  agent: compose-service-installer → docker-architect, for each service the spec
     │         marked materialize — the container lands in the same commit as the code
     ▼  git-publish (feature commit)

Each step's output contract is literally the next step's input contract. A free-prose handoff degrades by the third hop. Details: docs/en/03-new-feature.md.

What the consolidation produces: one UC-NNN-spec.md that keeps a single decision per fact, links back to the partial that owns each one, and ends in an implementation order the executor follows. An example is bank-app's UC-001-spec.md. Conditional layers the use case does not need, such as security, outbound HTTP, messaging and jobs, are recorded as not applicable instead of being left out silently.

Edit cycle — what runs on every write in a generated project

prompt (UserPromptSubmit)
     └─ guard prompt        baseline of the working tree for this turn's sweep

Write / Edit
     ├─ guard               path outside the active skill's or agent's territory → blocked
     │                      approved spec folder → blocked
     │                      Skill(build class) during a design run → blocked
     ├─ schema              frontmatter + body of .claude/**/*.md, .mcp.json   (blocks)
     ├─ format              spotless on the touched module                    (never blocks)
     ├─ check               forbidden imports + incremental test-compile      (blocks)
     └─ audit               file touched → appended to the run's log          (never blocks)

Bash
     └─ guard bash          force push → refused; a redirect, sed -i, tee… outside
                            the territory or into a frozen folder → blocked

SubagentStart
     └─ context subagent    design-pattern catalog → agents whose class asks for it

Stop
     ├─ guard sweep         what git sees changed this turn, re-checked       (blocks)
     ├─ compose gate        a service down, or published and unreachable      (blocks)
     ├─ audit flush         renders the run's report + ledger line            (never blocks)
     └─ tests               tests of the changed modules                      (blocks)

Audit trail — what every run spent

The report of the bank-app /new-feature run described above, as it lands in the project: 2026-10-07T08-52-11--new-feature.md. It shows the duration with the time spent waiting for the user taken out, the chain of skills with each one's share, tokens per piece, tool calls and peak context per piece, the most expensive turns, the files touched, and every question asked with the answer given.

The trail is a hook, not a skill. It survives the model forgetting and the session dying, and it costs zero tokens to produce. Prompts are redacted before they land in git. /audit-usage aggregates the ledgers across runs. Details: docs/en/08-audit-usage.md.

Issues — filed from a project, verified here

/report-issue, run inside a generated project, files an issue on this repository. It refuses a report with no evidence, warns when the project is behind the latest release, and strips the project's own code and names from the body. Here, /triage-issue <N> has a read-only agent check every claim against HEAD, including the reporter's diagnosis and proposed fix, before anything is commented or designed. Details: docs/en/12-issues.md.

What is in the box

Design skills of the /new-feature pipeline: use-case-design, domain-modeling, rest-api-architect, graphql-api-architect (the inbound GraphQL adapter, schema-first on the servlet stack: root fields, userErrors, connections, @BatchMapping, field-level access — only when the use case's trigger names it), security-architect (Spring Security on the servlet stack: who may call each endpoint, JWT, opaque token, API key, 401/403, CORS), http-client-architect (outbound HTTP client and engine, timeouts, retry, circuit breaker, outbound authentication), ai-architect (a language model or vector store behind a port — structured output, semantic search, prompts as resources, what the answer may change), search-architect (an Elasticsearch or OpenSearch index kept as a rebuildable projection of a source of truth: strict mapping, alias, indexer, rebuild, lag — only when the use case names a search index), messaging-architect (Kafka producer and consumer, retry, DLQ, the AsyncAPI contract), jobs-architect (@Scheduled, ShedLock, Quartz, Spring Batch, db-scheduler, JobRunr; the outbox relay), persistence-architect (relational with JPA or document with MongoDB, as the use case's Storage row states; stamps or an Envers history when its Audit row asks), cache-architect (Caffeine or Redis behind a decorator of the outbound port, keys, expiry, eviction on every write — only when the use case states how old an answer may be), test-architect.

Cross-cutting concerns that arrive solved: Idempotency-Key through AOP, logging with sensitive-data masking, an OTLP collector with Jaeger or Grafana + Tempo + Prometheus, transport security decided once per project through transport-security-setup (edge, direct, or mutual TLS, HSTS with exactly one writer), SonarQube or SonarCloud setup, compose port-collision and reachability checks, and permissions.deny on secrets files.

What travels into a generated project: the norms, the development skills, the executor agents, the hook and its schema, and the active blueprint. The manifest of what travels is data, the export block of schemas/extensions.json, and the schema hook fails if a skill or agent on disk is missing from it. Creation-only pieces stay here: project-bootstrap, init-project, new-project, claude-code-architect-designer, triage-issue, project-initializer, issue-verifier, and the blueprint catalog. arch-adopt is the one creation skill that travels, because it is how the project updates itself once this repository is out of the picture.

Blueprints

| vertical-slice | single-module | Loosely coupl