A fix upstream
reaches every project.

A defect in a template, a norm or a hook shows up in a generated project first. Fixing it there fixes one project; fixing its owner in Nerviz fixes every project generated afterwards. So the most useful report is one a maintainer can verify.

/report-issue files it for you

Type it in the generated project, with a description or a lessons-learned file. It picks the repository's own issue form, asks once for the evidence that is missing, strips everything that identifies your project, searches open duplicates, and publishes only after you say yes.

# inside the generated project
› /report-issue <description of the problem>
› /report-issue docs/lessons-learned/sonar-001.md

• Only you fileNothing chains /report-issue. It is manual-only, so the model cannot publish on its own.
• No evidence, no issueEvery claim is checked against the code at HEAD before anything changes. A claim with no file, no output and no way to reproduce it could only be closed as needs evidence, so it is not written.
• The trace, never the projectThe repository is public and your project may not be. The issue names Sonar rule keys, counts, paths inside .claude/, commands and hook output. Never a path under src/, a package, a class, an excerpt, a project key or a server URL.

Behind the latest release is a warning, not a stop: the newer release may already carry the fix, and /arch-adopt pulls it.

Four forms, one per kind of report

Blank issues are disabled. /report-issue reads the same form files the web uses, so both produce the same issue.

• bug_report.yml

  Bug report

  Title bug: Label bug

  Something in .claude/ behaves differently from what its own file says it does.

  It asks for
  • Where it happened: in Nerviz, in a generated project, or both
  • The component and the exact entry point
  • The file and line that promise the behavior, quoted
  • The literal output, steps to reproduce, and /arch-doctor's output
  • java, git and claude versions, and the OS

  Filed by /report-issue or the web form

• feature_request.yml

  Feature request

  Title feat: Label enhancement

  Something is hard, repetitive or silently wrong today, and no file promises otherwise.

  It asks for
  • The problem, not the solution
  • Which file type should carry it: norm, skill, agent, hook, CLAUDE.md section, MCP server or docs
  • How it would be verified
  • The invariants it respects, and whether generated projects need it too
  • Alternatives considered

  Filed by /report-issue or the web form

• new_blueprint.yml

  New blueprint

  Title blueprint: Label blueprint

  An architecture declared as data in .claude/blueprints/, with no change to any skill, agent or command.

  It asks for
  • Id, readable name and a one-sentence description
  • when_to_choose and honest trade_offs
  • build.layout, modules and dependency direction
  • packages.map and architecture_paths
  • The 6-rule checklist of _schema.md

  Filed by The web form

• sonar-lessons.yml

  Sonar lessons

  Title sonar-lessons: Label sonar-lessons

  SonarQube findings in a generated project, traced to the .claude/ piece that produced them.

  It asks for
  • The source version, from .arch-provenance.json
  • A snapshot: the quality gate and counts only
  • Findings by owner: rule key, count, owner in .claude/, origin
  • Proposed changes, and the structural lesson
  • A privacy check: nothing that names the analyzed project

  Filed by /sonar-lessons, then /report-issue

Open the forms on GitHub →

Not an issue

• A vulnerabilityReport it privately, as a security advisory. Never as an issue and never with /report-issue: both publish it.
• A questionAsk in Discussions how something works before opening an issue.
• A design you disagree withRead .claude/decisions/ first. The bug form asks you to confirm it is a defect, not a decision.

Generated code should not become technical debt

Everything the harness generates aims at code that works and has quality, not at code someone pays for later. When SonarQube finds an issue, it is almost never a one-off: the code came from a template, a norm allowed it, or nothing in .claude/ said anything and the model decided alone. /sonar-lessons finds that owner, so the fix lands where every next project gets it.

1. /sonarqube-setupPuts the scanner in the root build file, and a local SonarQube container when there is no server yet. Runs once.
2. /sonar-lessonsRuns the analysis and reads the quality gate, bugs, vulnerabilities, code smells, duplication and coverage through the Web API. Needs a server answering and SONAR_TOKEN; it never sets them up.
3. sonar-NNN.mdThe full lesson in docs/lessons-learned/, kept in your project: paths, lines and excerpts, and the fix at the owner of each group.
4. /report-issueYou type it. It files the lesson on the Sonar lessons form, with the project stripped out.

# once: scanner in the build file, a server, a token
› /sonarqube-setup

# after a feature: analyze, trace, write the lesson
› /sonar-lessons

# then file it where the fix belongs
› /report-issue docs/lessons-learned/sonar-001.md

Every group of findings gets an owner

Each run compares itself with the previous one: the snapshot gets Previous and Δ columns, and every group is marked new, recurring or gone. The goal is fewer issues each round, and this is the place that says whether it is happening.

Every claim is checked before anything changes

The maintainer runs /triage-issue on your issue. An agent with no write tools checks each claim against the code at HEAD and judges the proposed fix apart. The verdict comes back as a comment and a label.

The whole flow, in the docs →

Changing the harness itself

Blueprints and norms are the most useful contributions. The repository is not a Java application: what gets edited is instruction files, data and one hook. Read CLAUDE.md before the first PR; its Invariants are what review checks against.

# JDK 21+, git and curl. Nothing else
git clone https://github.com/nerviz-ai/nerviz.git
cd nerviz
java .claude/hooks/ArchHook.java doctor

# before you open a PR
java .claude/hooks/ArchHook.java schema
claude plugin validate .claude/skills

Not sure whether it is a norm, a skill, an agent or a hook? Picking the wrong one is the most common review finding, and /claude-code-architect-designer exists for that question.

CONTRIBUTING.md, with the rules per file type →