@aksp/opencrew 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -3,6 +3,106 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.12.0] — 2026-10-07
+
+Fase U5, fatia 1: "Polimento do uso" (`specs/fase-u5a-polimento-do-uso.md`). A U5 é a fase de
+fechamento do projeto, em quatro fatias (`specs/fase-u5-roteiro.md`). Chega a quem já usa com um
+`npx @aksp/opencrew@latest update`.
+
+Ainda não nesta versão: o runner dividido (1.13.0), o histórico confiável e o "retomar" (1.14.0)
+e o pedido avulso à crew (1.15.0).
+
+### Added
+- **Formato `texto-livre`** (o 24º guia): para o texto que não é post nem documento para
+  imprimir ou assinar — proposta, minuta que vira HTML ou PDF, plano, relatório interno. Não tem
+  limite de tamanho, não gera Word, e a entrega leva o arquivo inteiro para `outros/`. O
+  `/opencrew repair` passa a propô-lo para esse tipo de passo.
+- **O que o Word não vai converter aparece antes do revisor.** No passo com
+  `format: documento-oficial`, o verificador avisa de imagem, de marcação `:::` desconhecida e
+  de bloco de assinaturas sem fim. São alertas: quem decide é o revisor.
+- Aviso de conversão quando uma linha de tabela tem mais células que o cabeçalho.
+
+### Changed
+- **O nome da execução (`run_id`) vem do script**, com a data e a hora do computador
+  (`caminho.mjs <crew> pasta`, sem `--run`). Antes a IA montava a hora por conta própria.
+- **Conferência de fontes:** o resumo concorda em número ("1 fonte", "1 alerta"); quando há
+  caminho com sugestão, o relatório diz como corrigir; com `--corrigir`, cada arquivo alterado
+  aparece com o nome da cópia que ficou, e o relatório sai uma vez só.
+- Depois de um conserto por veto, o runner confere o arquivo de novo.
+- O runner não cita mais ferramenta de uma IDE só ("Task tool", `.claude/settings.local.json`).
+- **Perfil de documento oficial:** chave escrita quase certa (`Logotipo:`, `rodapé:`, com
+  espaço antes) agora é erro que diz a grafia certa; antes a linha era ignorada em silêncio.
+- O onboarding grava o `company.md` com seis cabeçalhos fixos e tira a marca
+  `NOT CONFIGURED` dos dois arquivos.
+- A linha "Não medido" some para formato que não declara limite (`documento-oficial`,
+  `texto-livre`).
+- Na entrega sem canal de rede, "O que não foi conferido" não cita imagens nem redes.
+- Prompts de criação: dez contradições que a execução real da 1.11.0 achou ganharam uma frase
+  cada (a pergunta de tier com modelo, `extends:` × "do zero", dependências de agente lidas
+  também do "Context Loading", skills nativas fora da conferência, exemplo de saída com 15
+  linhas, a pergunta 1 quando o comando já traz a descrição, entre outras).
+
+### Fixed
+- **Uma frase errada da 1.11.0.** O `/opencrew repair`, o README e este arquivo diziam que texto
+  sem formato "é medido como post de blog". Isso só acontece quando o arquivo tem `title:` no
+  frontmatter. O que acontece sempre, sem o formato: o redator não recebe o guia do tipo de
+  texto, e o verificador procura no arquivo peças de rede (legenda, post). A frase foi trocada
+  em todos os lugares.
+
+## [1.11.0] — 2026-10-07
+
+Fase U4, fatia 1: "Conserto de crews e caminho de criação" (`specs/fase-u4a-conserto-de-crews.md`).
+Chega a quem já usa com um `npx @aksp/opencrew@latest update`; as suas crews só mudam quando você
+pede o conserto e diz sim a cada ponto.
+
+Ainda não nesta versão: histórico confiável, retomar uma execução interrompida e pedido avulso à
+crew (`/opencrew pedir`), que ficaram para a fase U5 (`specs/fase-u5-roteiro.md`). O conserto não reordena passos: crew
+sem revisão, sem aprovação final ou que publica antes da revisão é apontada e resolvida com
+`/opencrew edit`.
+
+### Added
+- **`/opencrew repair <crew>` conserta crews antigas.** Ele lê a crew e mostra, em português, o
+  que falta para as melhorias das versões seguintes valerem nela: passo sem o formato do texto
+  (o redator ficava sem o guia do tipo de texto), crew sem os arquivos do projeto que deve ler,
+  proibição sem trecho entre aspas (que o verificador não consegue barrar), nomes dos agentes,
+  passo que publica sem a marca. Conserta um ponto por vez, com o seu sim; cada arquivo alterado
+  ganha uma cópia `.bak`. Quem grava é um script (`_opencrew/core/scripts/conserto.mjs`), não a
+  IA; sem `--aplicar` ele só lê.
+- **Proibição que é regra de conteúdo** ("nunca prever votação por aclamação") pode ser marcada
+  como `(revisão humana)`: fica para o revisor e deixa de aparecer como pendência do verificador.
+- **Crew de documento na criação.** Pedir uma crew de ata, ofício, contrato ou proposta leva a
+  perguntas próprias (quais documentos, quem assina e quem recebe, papel timbrado, quais arquivos
+  mandam no texto), sem a oferta de investigar perfis de referência, e os passos já saem com o
+  formato `documento-oficial`.
+- **Formato da crew escrito num lugar só** (`_opencrew/core/formato-da-crew.md`): `crew.yaml`,
+  `pipeline.yaml`, os campos de cada passo e o `id` do agente, com um exemplo completo. A criação,
+  o runner e o conserto seguem esse arquivo; as formas que versões antigas gravaram continuam
+  sendo lidas.
+- Depois do `update`, quando o projeto tem ao menos uma crew, o resumo lembra do
+  `/opencrew repair`.
+
+### Changed
+- **`max_review_cycles` no `crew.yaml` passa a valer.** O runner só lia o limite de ciclos de
+  revisão no passo de revisão; crews que o declaravam no `crew.yaml` recebiam sempre 3.
+- **Tier Express tem passo de revisão**, feito pelo próprio redator: o verificador automático roda
+  também nele. Antes o texto dizia "o redator se revisa" e, em outro ponto, "toda crew precisa de
+  revisor".
+- **Checkpoint que guarda a resposta em arquivo** deixa de usar sempre o formato de "foco de
+  pesquisa": fora do checkpoint do pesquisador, grava o título, a sua resposta e a data.
+- O Architect lista os prompts de cada fase da criação, e o ponto de entrada diz onde ele está;
+  antes um apontava para o outro.
+- Pasta de `crews/` sem `crew.yaml` (os modelos instalados) não aparece mais como crew nas
+  listas.
+
+### Fixed
+- `init --ide=<lista> --yes` (e `--all`) instalava as pontes das 9 IDEs; agora a lista vence.
+  `--yes` sem `--ide` continua instalando todas.
+- Uma frase cortada no meio nas instruções instaladas (`_opencrew/core/system.md`, desde a
+  1.10.0): a rota do documento Word e o pedido de entrega de uma execução encerrada não exigem o
+  onboarding.
+- O Build exigia um checkpoint imediatamente antes de cada passo que publica, o que era
+  impossível com dois passos de publicação seguidos.
+
 ## [1.10.0] — 2026-10-07
 
 Fase U3b "Documento Word, com perfil de documento oficial" (`specs/fase-u3b-documento-word.md`).

package/README.md

@@ -184,8 +184,9 @@ meu-projeto/
 │   │   ├── runner.pipeline.md    ← executor de pipeline
 │   │   ├── skills.engine.md      ← gerenciador de skills
 │   │   ├── architect.agent.yaml  ← definição do Arquiteto
-│   │   ├── best-practices/       ← 23 guias de melhores práticas + _catalog.yaml
-│   │   ├── scripts/              ← verificador, conferência de fontes, caminhos, entrega, documento Word e os scripts do Escritório
+│   │   ├── formato-da-crew.md    ← o formato dos arquivos de uma crew (crew.yaml, pipeline.yaml, passos)
+│   │   ├── best-practices/       ← 24 guias de melhores práticas + _catalog.yaml
+│   │   ├── scripts/              ← verificador, conferência de fontes, caminhos, entrega, documento Word, conserto de crews e os scripts do Escritório
 │   │   ├── modelos/              ← modelo do perfil de documento oficial (papel timbrado)
 │   │   ├── escritorio/           ← página do Escritório ao vivo (abre com /opencrew dashboard)
 │   │   └── prompts/              ← 15 prompts de fase (discovery, design, build, entrega, documento, etc.)
@@ -437,6 +438,16 @@ o que você fez:
   `# opencrew:end`)? Nenhuma linha sua é apagada: o `update` guarda o arquivo como estava e põe
   um bloco completo no fim. O bloco começa por um comentário que diz que ele é do OpenCrew: as
   suas linhas ficam fora dele.
+- **E as crews que você já tinha?** O `update` não mexe nelas. Para levar a elas o que veio
+  depois — o formato de cada texto (sem ele o redator não recebe o guia do tipo de texto), os
+  arquivos do projeto que a crew deve ler, as proibições que o verificador consegue barrar —,
+  peça na sua IDE `/opencrew repair <nome>`. Ele mostra o que falta, pergunta antes de cada
+  mudança e deixa uma cópia `.bak` do arquivo que alterou. O que não dá para consertar assim
+  (crew sem passo de revisão, publicação antes da revisão) ele aponta e manda para
+  `/opencrew edit`.
+- **Texto que não é post nem documento para assinar?** Proposta, minuta que outro passo diagrama,
+  plano: o passo recebe o formato `texto-livre`. Não há limite de tamanho, nada vira Word, e a
+  entrega guarda o arquivo como está, em `outros/`.
 - **A instalação anterior parou no meio?** O `update` não altera nada e pede para você rodar
   `npx @aksp/opencrew init`, que conclui a instalação sem apagar o que já existe.
 - **Apagou um modelo de crew ou um skill do catálogo?** Ele volta no `update`, e a saída diz o
@@ -489,7 +500,7 @@ npx @aksp/opencrew update --check
 | `/opencrew run <nome>` | Executa o pipeline de uma crew |
 | `/opencrew list` | Lista todas as suas crews |
 | `/opencrew edit <nome>` | Modifica uma crew existente |
-| `/opencrew repair <nome>` | Conserta o manifesto de uma crew com nomes quebrados |
+| `/opencrew repair <nome>` | Mostra o que falta numa crew que você já tem (formato de cada texto, arquivos do projeto que ela deve ler, proibições que o verificador consegue barrar, nomes dos agentes) e conserta um ponto por vez, com o seu sim e uma cópia `.bak` |
 | `/opencrew delete <nome>` | Remove uma crew |
 | `/opencrew skills` | Navega, instala ou remove skills |
 | `/opencrew install <skill>` | Instala uma skill do catálogo |
@@ -509,7 +520,7 @@ npx @aksp/opencrew update --check
 | `npx @aksp/opencrew@latest update` | Atualiza o framework |
 | `npx @aksp/opencrew update --check` (ou `--dry-run`) | Verifica se há update disponível, sem alterar nada |
 | `npx @aksp/opencrew upgrade` | Atalho para `update` |
-| `npx @aksp/opencrew init --ide=claude-code,cursor` | Instala só as pontes das IDEs indicadas |
+| `npx @aksp/opencrew init --ide=claude-code,cursor` | Instala só as pontes das IDEs indicadas (também com `--yes`) |
 | `npx @aksp/opencrew init --all` (ou `-y`) | Instala as pontes de todas as IDEs |
 | `npx @aksp/opencrew@latest init --repair-bridges` | Regrava as pontes das IDEs já instaladas num workspace existente (`--ide=a,b`: só as indicadas; `--all`: as 9) |
 | `npx @aksp/opencrew version` | Mostra a versão instalada |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "publishConfig": {
     "access": "public"
   },

package/src/commands/init.js

@@ -148,14 +148,13 @@ async function workspaceState(target) {
 }
 
 /**
- * Decide which IDEs to configure. --all / --yes → every IDE; --ide → validated list;
- * nothing → `fallback()` (the interactive prompt; in repair mode, the detection). Throws
- * UsageError if --ide names no valid IDE.
+ * Decide which IDEs to configure. --ide → validated list, whatever comes with it; without it,
+ * --all / --yes → every IDE; nothing → `fallback()` (the interactive prompt; in repair mode, the
+ * detection). Throws UsageError if --ide names no valid IDE.
  */
 async function resolveIdes(opts, fallback) {
-  if (opts.all || opts.yes) return allIdeIds();
   const ids = normalizeIdes(opts.ide);
-  if (!ids) return fallback();
+  if (!ids) return opts.all || opts.yes ? allIdeIds() : fallback();
   const invalid = ids.filter((id) => !ideById(id));
   const valid = ids.filter((id) => ideById(id));
   if (!valid.length) {

package/src/commands/update.js

@@ -88,6 +88,7 @@ async function apply(target, version) {
   const done = { unreadable, ...(await refreshBridges(ctx)) };
   done.mcp = await updateMcp(ctx, await readFile(tpl('.mcp.json')));
   done.leftovers = await findLeftovers(target);
+  done.hasCrew = await hasCrew(target);
   say(updateSummary(ctx, done));
 
   await writeManifest(target, version, ctx.files);
@@ -97,6 +98,13 @@ async function apply(target, version) {
   log(c.dim(`${UNTOUCHED}\n`));
 }
 
+/** Is there a crew of the user's? A folder of `crews/` with `crew.yaml` (the templates have none). Only looks. */
+async function hasCrew(target) {
+  const dirs = await fs.readdir(path.join(target, 'crews'), { withFileTypes: true }).catch(() => []);
+  const found = await Promise.all(dirs.filter((d) => d.isDirectory()).map((d) => exists(path.join(target, 'crews', d.name, 'crew.yaml'))));
+  return found.includes(true);
+}
+
 /** @returns what `deliverTree` did to each crew template (only the missing ones are written). */
 async function refreshFramework(ctx) {
   const dest = (...p) => path.join(ctx.target, ...p);

package/src/lib/resumo.js

@@ -18,6 +18,9 @@ export const ALREADY_INSTALLED = 'Para atualizar, rode `npx @aksp/opencrew@lates
 /** `update` over `_opencrew/core` with no version stamp (spec U3a-2, rule 31). */
 export const INTERRUPTED = 'A instalação anterior não terminou. Rode `npx @aksp/opencrew init` para concluir.';
 
+/** After an `update`, when the project has at least one crew (spec U4-1, decision 7). */
+export const REPAIR_HINT = 'Para levar as melhorias novas às crews que você já tem, peça na sua IDE: /opencrew repair';
+
 const NO_BRIDGES = 'Nenhuma ponte de IDE encontrada: nada a atualizar. Para criar a ponte de uma IDE: `npx @aksp/opencrew@latest init --repair-bridges --ide=<id>`.';
 const LEAK_REMOVED = 'CLAUDE.md: removi a seção de STATUS.md que as versões 1.4.0 e 1.4.1 gravaram por engano.';
 const FIRST_PROTECTED = 'Primeira atualização com proteção: sem registro anterior, guardamos tudo o que diferia. Daqui em diante, só o que você editar.';
@@ -112,7 +115,7 @@ function copyLines(ctx, unreadable) {
  * @param {object} done what each step returned: `agents` and `gitignore` (deliverBlock; `agents`
  *   is null when a pre-1.3 AGENTS.md was migrated), `ides` (detected), `bridges` (deliverBridges),
  *   `leak` (the STATUS.md section left CLAUDE.md's block), `mcp` (updateMcp), `leftovers`
- *   (findLeftovers) and `unreadable` (manifest)
+ *   (findLeftovers), `unreadable` (manifest) and `hasCrew` (a folder of `crews/` with `crew.yaml`)
  * @returns {Array<[Function, string]>} lines for `say`
  */
 export function updateSummary(ctx, done) {
@@ -124,5 +127,6 @@ export function updateSummary(ctx, done) {
     ...mcpLines(ctx, done.mcp),
     ...leftoverLines(done.leftovers, done.mcp),
     ...copyLines(ctx, done.unreadable),
+    ...(done.hasCrew ? [[info, REPAIR_HINT]] : []),
   ];
 }

package/templates/AGENTS.md

@@ -10,8 +10,10 @@ On activation, perform these steps IN ORDER:
 1. Read the company context file: `{project-root}/_opencrew/_memory/company.md`
 2. Read the preferences file: `{project-root}/_opencrew/_memory/preferences.md`
 3. Check if company.md is empty or contains only the template — if so, trigger ONBOARDING
-   (except for `/opencrew documento` and the `
-4. Otherwise, display the MAIN MENU
+   (except for `/opencrew documento` and the request to deliver a run that already ended: neither
+   uses the company context)
+4. Otherwise: when the message carried a command or a request, route it (Command Routing);
+   display the MAIN MENU only when it carried none
 
 ## Onboarding Flow (first time only)
 
@@ -24,8 +26,12 @@ If `company.md` is empty or contains `<!-- NOT CONFIGURED -->`:
    description/sector, target audience, products/services, tone of voice,
    social media profiles
 4. Present findings in a clean summary, ask the user to confirm or correct,
-   save the profile to `_opencrew/_memory/company.md`
-5. Show the main menu
+   save the profile to `_opencrew/_memory/company.md` under these fixed headings, in this order:
+   `## Nome`, `## O que faz`, `## Público`, `## Produtos e serviços`, `## Tom de voz`,
+   `## Site e redes` (under it, the site goes on its own line, `- Site: https://…`). Then remove the line
+   `<!-- NOT CONFIGURED -->` from `company.md` and from `preferences.md`
+5. When the message that started this carried a command or a request, route it now (Command
+   Routing); show the main menu only when it carried none
 
 ## Main Menu
 
@@ -50,11 +56,11 @@ Route input to the matching action:
 |---------------|--------|
 | `/opencrew` or `/opencrew menu` | Show main menu |
 | `/opencrew help` | Show help text |
-| `/opencrew create <description>` | Load Architect → Create Crew flow |
-| `/opencrew list` | List all crews in `crews/` |
+| `/opencrew create <description>` | Load the Architect (`_opencrew/core/architect.agent.yaml`) → Create Crew flow: one prompt per phase, listed there |
+| `/opencrew list` | List all crews in `crews/` (a folder without `crew.yaml` is not a crew) |
 | `/opencrew run <name>` | Load Pipeline Runner → Execute crew |
-| `/opencrew edit <name> <changes>` | Load Architect → Edit Crew flow |
-| `/opencrew repair <name>` | Load `_opencrew/core/prompts/repair.prompt.md` → fix agent names / rebuild crew-party.csv |
+| `/opencrew edit <name> <changes>` | Load the Architect → Edit Crew flow |
+| `/opencrew repair <name>` | Load `_opencrew/core/prompts/repair.prompt.md` → show what an existing crew is missing and fix one point at a time, each with a `.bak` copy |
 | `/opencrew skills` | Load Skills Engine → Show skills menu |
 | `/opencrew install <name>` | Install a skill from the catalog |
 | `/opencrew uninstall <name>` | Remove an installed skill |
@@ -74,7 +80,8 @@ Route input to the matching action:
 
 When a specific agent needs to be activated:
 
-1. Read the agent's `.agent.md` file completely
+1. Read the agent's `.agent.md` file completely (the Architect is the exception: it lives in
+   `_opencrew/core/architect.agent.yaml`)
 2. Adopt the agent's persona (role, identity, communication_style, principles)
 3. Follow the agent's menu/workflow instructions
 4. When the agent's task is complete, return to the opencrew main context

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-1.10.0
+1.12.0

package/templates/_opencrew/core/architect.agent.yaml

@@ -57,24 +57,30 @@ agent:
     create-crew: |
       ## Create Crew
 
-      The create flow is now handled by the phased orchestration system.
-      See the SKILL.md entry point for the full phased flow:
-      Discovery → Investigation → Design → Template Selection (optional) → Build
-
-      Each phase is a separate prompt in `_opencrew/core/prompts/`:
-      - `discovery.prompt.md` — Phase 1: Intelligent wizard
-      - `sherlock-*.md` — Phase 2: Investigation (optional)
-      - `design.prompt.md` — Phase 3: Crew architecture (includes optional Phase H.5: Template Selection)
-      - `build.prompt.md` — Phase 4: File generation + validation
-
-      The SKILL.md orchestrator dispatches each phase as a subagent.
+      Creating a crew takes four phases, in this order. Each phase is one prompt: read it
+      completely when its turn comes, follow it to the end, and only then load the next one.
+
+      1. `_opencrew/core/prompts/discovery.prompt.md` — Discovery: the questions; ends by
+         writing `crews/{code}/_build/discovery.yaml`
+      2. `_opencrew/core/prompts/sherlock-shared.md` — Investigation: ONLY when the discovery
+         ended with the investigation enabled; it names the platform prompt to load with it
+      3. `_opencrew/core/prompts/design.prompt.md` — Design: agents and pipeline (includes the
+         optional template selection); ends by writing `crews/{code}/_build/design.yaml`
+      4. `_opencrew/core/prompts/build.prompt.md` — Build: writes the crew files, in the format
+         of `_opencrew/core/formato-da-crew.md`, and validates them
+
+      If your IDE can run a phase as a subagent, you may; otherwise run the phases one after
+      the other in this conversation. Never skip a phase and never write crew files before
+      the Build.
 
     edit-crew: |
       ## Edit Crew Workflow
 
-      1. Ask which crew to edit (list available crews if not specified).
+      1. Ask which crew to edit (list available crews if not specified; a folder without
+         crew.yaml is not a crew).
          If only 1 crew exists, add "Cancel" as a second option. If 0 crews, inform user directly.
-      2. Read the crew's crew.yaml to understand current structure
+      2. Read the crew's crew.yaml to understand current structure (the format of the crew
+         files is in `_opencrew/core/formato-da-crew.md`)
       3. Ask what changes the user wants
       4. **If the user asks to edit/define/change the visual template or identity of a design agent:**
          - Read and follow `skills/template-designer/SKILL.md`
@@ -86,8 +92,10 @@ agent:
     list-crews: |
       ## List Crews Workflow
 
-      1. Read all directories in crews/
-      2. For each, read crew.yaml to get name, description, icon, agent count
+      1. Read all directories in crews/. A folder without crew.yaml is not a crew (the
+         template folders installed with the product): leave it out
+      2. For each crew, read crew.yaml to get name, description and icon (inside `crew:` or,
+         in older crews, loose at the top level) and count the agents in crew-party.csv
       3. Present as a formatted list:
          ```
          Your Crews:
@@ -102,7 +110,8 @@ agent:
     delete-crew: |
       ## Delete Crew Workflow
 
-      1. Ask which crew to delete (list available if not specified).
+      1. Ask which crew to delete (list available if not specified; a folder without
+         crew.yaml is not a crew).
          If only 1 crew exists, add "Cancel" as a second option. If 0 crews, inform user directly.
       2. Show crew details (name, agents, output count)
       3. Confirm deletion with explicit "Are you sure?" presented as a numbered list (1. Yes, delete / 2. No, cancel)

package/templates/_opencrew/core/best-practices/_catalog.yaml

@@ -119,3 +119,8 @@ catalog:
     name: "Documento oficial (Word)"
     whenToUse: "Creating agents that produce a document to print, sign or file (minutes, official letter, statement, contract, formal report) that becomes a Word file."
     file: documento-oficial.md
+
+  - id: texto-livre
+    name: "Texto livre"
+    whenToUse: "Creating agents that write a text with no channel and no Word file: commercial proposal, draft that becomes HTML or PDF, work plan, internal report."
+    file: texto-livre.md

package/templates/_opencrew/core/best-practices/texto-livre.md

@@ -0,0 +1,23 @@
+---
+name: "Texto livre"
+content_type: "plain-text"
+description: "Text with no channel and no Word file: a proposal, a draft that becomes HTML or PDF, a plan, an internal report"
+whenToUse: |
+  Creating agents that write a text that is not a post for a network and is not a document to print or sign: commercial proposal, draft (minuta) that another step turns into HTML or PDF, work plan, internal report, briefing.
+version: "1.0.0"
+---
+
+## Compact Rules
+
+1. Write the full, final text: no outline, no notes to the reader, no "insert here".
+2. No YAML frontmatter and no labels such as `=== TITLE ===`: everything in the file is the text itself.
+3. Use `#`, `##` and `###` for the sections, simple tables for figures, `- ` for lists.
+4. Missing real data is marked `[PREENCHER: o que falta]`; never invent a name, a date, a price or a number.
+5. Copy figures exactly from the file they come from; when a total is shown, the parts add up to it.
+6. Follow the structure the step asks for (its "Output Format"): this guide adds no structure of its own.
+
+## What this format does not do
+
+There is no size limit here and nothing is converted: the delivery keeps the file as it is, in
+`outros/`. For a text to print, sign or file, use `documento-oficial`; for a post, an e-mail or a
+message, use the format of that channel.

package/templates/_opencrew/core/formato-da-crew.md

@@ -0,0 +1,162 @@
+# Crew file format (formato da crew)
+
+The single definition of the files that make a crew. The Build phase writes them, the Pipeline
+Runner and the scripts read them, `/opencrew repair` checks them. When another prompt and this
+file disagree, this file wins.
+
+```
+crews/{code}/
+├── crew.yaml               the crew: identity, sources, limits
+├── crew-party.csv          one row per agent (the names shown to the user)
+├── agents/{agent-id}.agent.md
+├── pipeline/
+│   ├── pipeline.yaml       the order of the steps
+│   ├── steps/step-NN-{name}.md
+│   └── data/               reference material (never an output)
+├── _memory/                memories.md, runs.md
+└── output/{run_id}/        what each run produces
+```
+
+A folder under `crews/` without a `crew.yaml` is not a crew (the template folders installed with
+the product only carry `discovery.template.yaml`).
+
+## crew.yaml
+
+```yaml
+crew:
+  code: "atas-do-conselho"          # the folder name
+  name: "Atas do Conselho"          # shown in lists
+  description: "Da pauta à ata pronta para assinar"
+  icon: "📄"
+  tier: "standard"                  # express | standard | full
+
+pipeline:
+  entry: "pipeline/pipeline.yaml"
+  steps_dir: "pipeline/steps"
+
+skills:                             # every skill the agents use
+  - web_search
+  - web_fetch
+
+data:                               # reference material the steps load
+  - pipeline/data/domain-framework.md
+  - pipeline/data/quality-criteria.md
+
+fontes:                             # files of the user's project the crew must read
+  - caminho: Regras/estatuto.md     # relative to the project root, never absolute
+    para_que: regras que mandam no texto
+
+agent_dependencies:                 # only when an agent can be left out (see below)
+  rita-redacao: []
+  vito-veredito: [rita-redacao]
+
+max_review_cycles: 2                # express 1 · standard 2 · full 3
+```
+
+| Field | Written by | Read by |
+|---|---|---|
+| `crew.code`, `name`, `description`, `icon` | Build, from `design.yaml` | crew lists (Architect) |
+| `crew.tier` | Build, from `design.yaml → crew.tier` | Runner (run header) |
+| `pipeline.entry`, `steps_dir` | Build, always these two values | a reference for people; the Runner reads these two paths directly |
+| `skills` | Build | Runner, Skills Engine |
+| `data` | Build; the template designer appends | Runner |
+| `fontes` (`caminho`, `para_que`) | Build, from `discovery.yaml → project_sources`; `/opencrew repair` | Runner (reads the sources at the start of the run), `conferir-fontes.mjs` |
+| `agent_dependencies` | Build | Runner (Pre-Execution Agent Selection) |
+| `max_review_cycles` | Build | Runner (Review Loops) |
+| `entrega.destino` | `entregar.mjs --lembrar-destino` only | `entregar.mjs` |
+
+- **`fontes`** is omitted only when the discovery found no project source.
+- **`agent_dependencies`** is written when at least one agent can be left out of a run without
+  breaking another (for example, one writer per channel). Each key is an agent `id`; its value
+  lists the agents whose output it reads. When every agent is needed in every run, omit the
+  field: the Runner then runs all agents and shows no selection step.
+- **`max_review_cycles`** — the Runner uses the value of the review step when the step declares
+  one, then this one, then 3.
+- Old crews carry `name`, `code`, `description` and `tier` loose at the top level, without the
+  `crew:` block. Readers accept both; new crews use the block.
+
+## pipeline.yaml
+
+```yaml
+steps:
+  - step: 1
+    file: "step-01-checkpoint-pauta.md"   # relative to pipeline/steps
+  - step: 2
+    file: "step-02-redigir-ata.md"
+  - step: 3
+    file: "step-03-revisar.md"
+  - step: 4
+    file: "step-04-checkpoint-final.md"
+```
+
+The steps run in the order of the list. `step` is the number other steps refer to (`on_reject`);
+without it, the number is the position in the list. Old crews write `file: steps/step-…md`;
+readers accept both. Nothing else is read from this file.
+
+## Step files
+
+The frontmatter of `pipeline/steps/step-NN-{name}.md` says how the Runner executes the step.
+
+**Creation step**
+```yaml
+---
+execution: inline            # inline | subagent
+agent: rita-redacao          # the agent id (see "Agent id")
+format: documento-oficial    # the kind of text this step produces (a best-practices id)
+inputFile: crews/atas-do-conselho/output/pauta.md
+outputFile: crews/atas-do-conselho/output/ata.md
+---
+```
+
+**Review step** — the one with `on_reject`
+```yaml
+---
+execution: inline
+agent: vito-veredito
+inputFile: crews/atas-do-conselho/output/ata.md
+outputFile: crews/atas-do-conselho/output/revisao.md
+on_reject: 2                 # the number of the step the pipeline goes back to on a rejection
+---
+```
+
+**Checkpoint**
+```yaml
+---
+type: checkpoint
+agent: rita-redacao          # optional: skipped together with that agent
+outputFile: crews/atas-do-conselho/output/pauta.md   # optional: the user's answer is saved here
+---
+```
+
+| Field | Rule |
+|---|---|
+| `execution` | `subagent` runs in the background; `inline` runs in the conversation. A step that publishes or sends is always `inline` |
+| `agent` | the agent id |
+| `format` | every step whose text is checked before the review (from the `on_reject` step up to the review) declares one; without it the writer does not get the guide of that kind of text and the checker looks in the file for pieces of a network (caption, post, blog title). A text to print, sign or file is `documento-oficial`; a text with no channel and no Word file (a proposal, a draft that becomes HTML or PDF, a plan) is `texto-livre`. Omit only for research, analysis and the review itself |
+| `inputFile`, `outputFile` | always under `crews/{code}/output/`; never `pipeline/data/` |
+| `model_tier` | `fast` or `powerful`, only on `subagent` steps. Express: `fast`. Standard: `fast` for research and data gathering, `powerful` for the rest. Full: `powerful`. Inline steps do not carry it |
+| `side_effects: irreversible` | every step that publishes, posts or sends outside the project; such steps come after the review and the final approval |
+| `on_reject` | marks the review step; its value is a step number |
+| `max_review_cycles` | optional on the review step, when it must differ from the crew's |
+| `skills_needed` | optional list of skills whose full instructions the step needs from the start |
+| `type: checkpoint` | a pause for the user; no `execution` |
+
+Every crew has a review step, followed by a final approval checkpoint. In the Express tier the
+review step is done by the writer agent itself; Standard and Full have a dedicated reviewer agent.
+
+## Agent id
+
+One definition: the agent `id` is the file name without `.agent.md`
+(`agents/rita-redacao.agent.md` → `rita-redacao`). The same text goes in the `id` column of
+`crew-party.csv`, in `agent:` of the steps and in `agent_dependencies`. Old agent files carry
+`id: "crews/{code}/agents/{id}"` in the frontmatter; readers use the last segment.
+
+## crew-party.csv
+
+```
+id,displayName,title,icon,path,execution
+rita-redacao,"Rita Redação","Redatora de Atas",📝,./agents/rita-redacao.agent.md,inline
+```
+
+`displayName` is the agent's `name:` (the two-word persona name), never the role. Quote any field
+with a space or a comma.