Workflow & Agent Governance

These rules come from AGENTS.md, fireskills/SKILL.md and fireskills/skills/Spec.md. They apply to every agent that works in the repository, and they explain what you will see in the chat.

What an agent reads first

AGENTS.md (the root file that CLAUDE.md imports) sends every agent through the same path:

1. fireskills/SKILL.md: which flow skill and which specialist fit the request.
2. .fireskills/RULES.md, plus PROJECT.md, STACK.md, DATABASE.md, INTERFACE.md or DESIGNSYSTEM.MD for the subject at hand.
3. The specialist of the area (fireskills/specialists/), before reading or writing code there.

A change of behavior (feature, rule, data, screen) goes through the flow. A trivial adjustment may go straight to the code, but with the rules read and the specialist loaded.

Principles

Code wins over documentation

Every statement about the project needs a file as evidence. When a document and the code disagree, the code is right and the document gets fixed.

Specialists say what exists and what does not

Each specialist has a references/nuxfire-*.md with what actually exists in this repository and a "what does NOT exist" list. The agent does not introduce anything from that second list.

One normative file per slice

All requirements, Gherkin scenarios, tasks, gates and evidence live in specs/<state>/<NNNN>-<slug>/spec.md. The agent does not create plan.md, tasks.md, research.md or data-model.md. Only research/ is allowed beside the spec, for consulted evidence.

sst deploy is the real gate

tsc, vitest and nuxt build passing do not prove that sst deploy works. For changes that touch apps/functions or layers, the deploy is the real check, and only you can authorize it.

The conversation: numbered questions

When a decision is yours, the agent follows the numbered-question contract of Spec.md:

• exactly one question per round, labeled Pergunta 1, and the agent waits for your answer;
• at least three specific numbered options, then the three fixed ones: Escrever outra resposta, Gere outras opções, Avançar;
• you can answer 2, 1.2, or 1. Escrever: <texto>; the agent records the full text of the option, not the number;
• at most eight questions per area; at the limit it summarizes, records what is still open and stops.

Pergunta 1. Como você prefere receber as orientações deste setup?
1. Iniciante: explique os termos técnicos e o efeito de cada escolha antes de prosseguir.
2. Intermediário: conheço os fundamentos e prefiro explicações curtas junto das escolhas.
3. Experiente: posso responder com detalhes de stack, arquitetura, comandos e integrações.
4. Escrever outra resposta
5. Gere outras opções
6. Avançar

This is the real first question of $fireskill-setup (from fireskills/skills/fireskill-setup/SKILL.md). Questions, options and generated files are in Brazilian Portuguese.

What Avançar does

Choosing Avançar does not fill anything in for you. On the next round the agent asks one thing: close this area for good, answer later, or answer now. Closing records Área encerrada pelo usuário: <área>; postponing records Área adiada pelo usuário: <área>. If applicable points remain open, the spec stays Status: Draft with Definition Gate: Pending.

Automatic hand-offs

You do not retype commands between steps. When a skill finds work that belongs to another one, it announces and switches in the same conversation:

Transição automática: $fireskill-02-backlog → $fireskill-03-specify — motivo: <motivo> — resultado esperado: <resultado>

• A pendência that fits the current skill is solved right there (Pendência detectada: … — ação: resolvendo nesta etapa).
• After the other skill fixes the prerequisite, the original one resumes (Retomada automática: …).
• If origin, destination and pendência repeat with no observable change, the agent stops and reports the impasse.
• A hand-off never authorizes deploy, deleting data, publishing or other external changes.

Late changes

Changing a spec after it was defined goes through $fireskill-update-spec, which reopens only what is affected:

See Late changes.

What agents never do on their own

• Deploy (bun run deploy -- --stage <stage>), delete data, or run any irreversible action without your explicit authorization.
• Run a test that touches the development database. The guard check_database_safety.mjs classifies commands, and destructive ones (drizzle-kit push --force, drizzle-kit drop, db:wipe, migrate:fresh, DROP, TRUNCATE…) are refused even with your approval. See Governance scripts.
• Mark a gate Passed without the evidence that gate requires.