ai-architect
Projeta as portas de IA: modelo ou vector store, prompts, tipo da resposta, dados enviados e famílias de falha.
29-ia.md, bloco a bloco
O bank-app ainda não tem 29-ia.md. Estes são os blocos que o SKILL.md diz que o parcial contém.
## 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
O que lê, escreve e recusa
O contrato da própria skill, do SKILL.md, no texto original.
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/**.
Fonte: SKILL.md § Contract, no nerviz e4cae27.
O que o guard faz com ela
design é a classe da skill. O ArchHook abre uma fase quando a skill é chamada e confere cada escrita contra o território da classe. O texto à direita é o do próprio hook.
write_allow da classe design
- ✓
docs/use-cases/UC-*/** - ✓
docs/use-cases/BACKLOG.md src/**: migrations e classes são do executordocker-compose.yml: arquivo de outra classecaso de uso já aprovado: as specs ficam congeladas
A recusa sai com código 2 e a mensagem volta para o modelo.
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
PreToolUse Write(docs/use-cases/UC-005-record-kyc-verdict/29-ia.md) guard write exit 0 PostToolUse audit file exit 0
PreToolUse Write(docker-compose.yml) guard write exit 2 ❌ `ai-architect` is class `design` — docker-compose.yml is outside its territory. write_allow: docs/use-cases/UC-*/**, docs/use-cases/BACKLOG.md Put the content in the spec as a code block, or finish the run and invoke the skill that owns this path. If the path is legitimately this skill's, widen skill_classes.design in .claude/schemas/extensions.json — retrying will not help.
# UC-005-record-kyc-verdict-spec.md: status: approved PreToolUse Edit(docs/use-cases/UC-005-record-kyc-verdict/29-ia.md) guard write exit 2 ❌ UC-005-record-kyc-verdict is approved — its specs are immutable. Record the change in the new use case's "Impact on approved use cases" section, and the one-line entry in UC-005-record-kyc-verdict/CHANGELOG.md, which stays writable.
Onde ela fica no trilho
Cada cartão é um passo do /new-feature; a seta leva o parcial que um passo entrega ao seguinte. Passos tracejados só rodam quando o caso de uso precisa.
/new-feature orchestrator · opus/new-feature-implement Quem lê o parcial depoisDepois da aprovação, o /new-feature-implement faz o executor construir o código. A spec é consolidada por referência e vale onde ela e um parcial divergem; o parcial é lido, por seção, para o detalhe.