nerviz

↑ ↓ to move · Enter to open · Esc to closeTap a result

Architecture
skill · class design · opus

ai-architect

Designs the AI ports: the model or vector store, prompts, the answer type, data sent and failure families.

skill · designopuswrites 29-ia.mdonly inside docs/use-cases/UC-*/**
§ the file it writes

29-ia.md, block by block

bank-app has no 29-ia.md yet. These are the blocks SKILL.md says the partial contains.

## 1 · AI ports

One row per port: kind, what it asks, what it returns, the "could not decide" value, the review state

## 2 · Provider and models

Provider, model and options per port, and whether inherited

## 3 · Prompts and output

Per LLM port: resources, variables, answer type, closed fields, every unusable answer. Per search: threshold and its basis, result ceiling

## 4 · Data sent

Per field: sent or not, in which form, why; the receiver and its agreement

## 5 · Vector store

Store, embedding model, dimensions, distance, item id, every writer and its re-index path — none without a store

## 6 · Failure and retry

Per port: timeout, retrying layer, attempts; the failure table; project-wide pieces NEW or REUSE

## 7 · Observability

Metric names and the alarm each exists for; content logging off

## 8 · Test cases

Every case, by level

## 9 · Requirements to other partials

Migration, re-index trigger, ingestion job, review state

## 10 · Declared dependencies

BOM and starters

## 11 · Configuration

Every property, its value, its owner

## 12 · Deferred

Same shape as every partial. none when nothing was deferred

## Compose services

The postgres image row for a store, or none

## Design patterns

The adapter over each port, with its classes — step 10b

§ behavior

What it reads, writes and refuses

The skill's own contract, from SKILL.md, in the original wording.

Class

design — the territory is skill_classes.design in @.claude/schemas/extensions.json, and ArchHook.java guard enforces it. Writes inside the use case folder and nothing else.

Reads

docs/use-cases/UC-NNN-<slug>/00-use-case.md (mandatory), 10-domain.md (mandatory), 30-rest.md, 25-messaging.md, 35-jobs.md, 32-security.md (when present), the Components tables and 29-ai.md of earlier cases, pom.xml, docker-compose.yml, the active blueprint's packages.map, the Initializr's metadata, @.claude/rules/ai.md, @.claude/rules/http-client.md, @.claude/rules/error-handling.md, @.claude/rules/personal-data.md, @.claude/rules/secrets.md, @.claude/rules/observability.md, @.claude/rules/architecture-ddd.md, @.claude/skills/docker-architect/references/compose-service-decision.md, and this skill's references/.

Writes

docs/use-cases/UC-NNN-<slug>/29-ai.md. Nothing else.

Owns

the provider and the model and options of each AI port, the prompt resources and their variables, the answer type and what each unusable answer becomes, the fields sent to the provider, the store, its embedding model and the list of writers that must re-index, the timeout and the retrying layer of each AI port, the translation of provider failures, AI metrics, AI dependencies and configuration, and the postgres image row a store needs.

Does not decide

the port, its domain types or the review state (10-domain.md), the trigger and its deadline (00-use-case.md, 30-rest.md), a re-index trigger or an ingestion job (25-messaging.md, 35-jobs.md), the migration's final form (20-persistence.md), or the tests (40-tests.md). Does not write Java, prompts, pom.xml, application.yml or docker-compose.yml — the executor and docker-architect do, from this partial. Doesn't touch .claude/rules/**.

Source: SKILL.md § Contract, at nerviz e4cae27.

§ guard and hook

What the guard does with it

design is the skill's class. ArchHook opens a phase when the skill is called and checks every write against the class's territory. The text on the right is the hook's own.

write_allow of class design

  • ✓docs/use-cases/UC-*/**
  • ✓docs/use-cases/BACKLOG.md
  • src/**: migrations and classes are the executor's
  • docker-compose.yml: another class's file
  • a use case already approved: its specs are frozen

A refusal exits with code 2 and the message goes back to the model.

PreToolUse  Skill(ai-architect)
  audit call                       exit 0
  guard call                       exit 0
# a skill of another class replaces the phase
# write_allow: docs/use-cases/UC-*/**, docs/use-cases/BACKLOG.md
§ orchestration

Where it sits on the rail

Each card is a step of /new-feature; the arrow carries the partial one step hands to the next. Dashed steps run only when the use case needs them.

/new-feature orchestrator · opus
/new-feature-implement Who reads the partial next

After approval, /new-feature-implement has the executor build the code. The spec is consolidated by reference and wins where it and a partial disagree; the partial is read, by section, for detail.

29-ia.mddocs/use-cases/UC-NNN-…/
read by section, for detail
java-spring-boot-developeragent · executor
writes the code
src/**designs one use case into a spec, writes no code
← back to the chains