@aksp/opencrew 1.9.0 → 1.11.0

package/templates/_opencrew/core/best-practices/documento-oficial.md

@@ -0,0 +1,144 @@
+---
+name: "Documento oficial"
+platform: "documento"
+content_type: "official-document"
+description: "Text that becomes a Word document to print, sign or file: minutes, official letters, statements, contracts and reports, written so the conversion keeps every word"
+whenToUse: |
+  Creating agents that produce a document to print, sign or file — minutes (ata), official letter (ofício), statement, contract, formal report — which the project turns into a Word file (.docx).
+version: "1.0.0"
+---
+
+## Compact Rules
+
+1. One paragraph per line. Never break a paragraph in the middle: each line of the file becomes one paragraph of the document, and lines that follow each other are not joined.
+2. Start with `::: titulo` and, when there is one, `::: subtitulo`, as the first lines of the text (one line each).
+3. Use `#`, `##` and `###` for the sections, and no deeper level.
+4. Write every number by hand — "I.", "1.", "6.1.", "a)", "§ 1º" — in sections and in items. Nothing is numbered automatically: the number you write is the official text.
+5. Use a simple table (header line, separator line, rows) for figures and lists of names. No merged cells, no table inside a table.
+6. Put `::: quebra-de-pagina` alone on a line before each annex (anexo), so the annex starts on a new page.
+7. Put the `::: assinaturas` block at the end of the document (and at the end of an annex that is signed): one line `Nome | Cargo` per person, closed by a line with only `:::`.
+8. No image, no HTML, no labels such as `=== … ===`, no notes section and no comments to the reader: everything in the file goes to the document.
+9. Write the full, final text. Missing real data is marked `[PREENCHER: o que falta]`; never invent a name, a date, a number or a registration.
+10. Use bold (`**texto**`) and italic (`*texto*`) sparingly; a list of plain items uses `- `.
+
+## What the conversion does
+
+The project turns this text into a Word file with one script, with the same words and the same
+numbers, in the same order. Knowing what it does tells you how to write:
+
+| You write | The document gets |
+|---|---|
+| `::: titulo Texto` · `::: subtitulo Texto` | A centered title · a centered subtitle, in italic. Valid anywhere, as many times as needed (an annex has its own) |
+| `# Texto` · `## Texto` · `### Texto` | Section headings of level 1 (shown in capitals), 2 and 3 |
+| A line of text | One justified paragraph |
+| A line that starts with a number or a letter of item (`1.`, `a)`) | A common paragraph, with the number as you wrote it; two spaces at the start of the line indent it |
+| `- item` | A bulleted item (two spaces before it: second level) |
+| A table | A table with equal columns and the first line in bold |
+| `---` alone on a line | A horizontal line |
+| `::: quebra-de-pagina` | The next block starts on a new page |
+| `::: assinaturas` … `:::` | Signature lines, two per row, with the name above the role |
+| `[texto](https://endereco)` | `texto (https://endereco)`, as plain text |
+
+The header with the logo, the footer with "Página X de Y", the margins and the font come from
+the profile of the project, not from the text: never write a header, a footer or a page number.
+
+## The three markings
+
+A marking is a line that starts with `:::` in the first column.
+
+- **Title and subtitle** — `::: titulo ATA DA REUNIÃO` and `::: subtitulo Realizada em 5 de maio de 2026`. One line each. They are not sections: the sections are the `#` lines.
+- **Page break** — `::: quebra-de-pagina`, alone on the line, with nothing after it.
+- **Signatures** — open with `::: assinaturas`, write one person per line as `Nome | Cargo` (the role is optional) and close with `:::`. Inside the block nothing else is read: bold and italic signs would be printed as typed. The order you write is the order on the page, left to right and top to bottom.
+
+Any other word after `:::` is not a marking: the line goes to the document as text, and the
+conversion warns about it. A signature block without the closing `:::` also stays as text.
+
+## What does not go in the text
+
+- **Images** (`![…](…)`) — the document carries no image in the body; the line would stay as text. The logo belongs to the profile of the project.
+- **HTML** (`<br>`, `<center>`, `<table>`) and HTML comments — they would be printed as they are.
+- **Labels and service blocks** (`=== TÍTULO ===`, `NOTES:`, checklists for the writer) — they are not removed.
+- **A notes section** ("Notas", "Observações do redator", "Fontes consultadas" that are not part of the document) — say it to the user in the conversation, not in the file.
+- **Frontmatter is the only exception**: a `---` block of `chave: valor` lines at the very top stays out of the document.
+
+## Structure of a document
+
+1. **Title and subtitle** — what the document is; when and where, in the subtitle.
+2. **Opening** — who, when, where, under which rule or call.
+3. **Body in numbered sections** — one subject per section, in the order of the agenda or of the request. Decisions are written as decisions ("Aprovado por unanimidade."), with the numbers that support them.
+4. **Closing** — what happens next, and who wrote the document.
+5. **Signatures** — everyone who signs, with the role.
+6. **Annexes** — each one after a page break, with its own title.
+
+## Output Example
+
+```markdown
+::: titulo ATA DA REUNIÃO DA DIRETORIA
+::: subtitulo Realizada em 5 de maio de 2026, na sede da Associação Exemplo de Moradores
+
+# I. Abertura
+Aos 5 dias do mês de maio de 2026, às 19h, reuniu-se a diretoria da Associação Exemplo de Moradores, na Rua das Acácias, 100, com a presença dos três diretores.
+A presidente, Ana Lima, abriu a reunião e convidou Rui Sá para secretariar os trabalhos.
+
+# II. Ordem do dia
+A presidente leu a ordem do dia:
+1. Reforma do salão de festas;
+2. Calendário de eventos do segundo semestre.
+
+# III. Reforma do salão de festas
+## 3.1. Orçamentos recebidos
+A tesoureira, Bia Reis, apresentou os três orçamentos recebidos:
+
+| Empresa | Prazo | Valor |
+|---|---|---|
+| Construtora Exemplo | 30 dias | R$ 18.400,00 |
+| Reformas Modelo | 45 dias | R$ 16.900,00 |
+| Obras Amostra | 25 dias | R$ 21.000,00 |
+
+## 3.2. Deliberação
+Por unanimidade, a diretoria aprovou o orçamento da **Reformas Modelo**, com as seguintes condições:
+- pagamento em três parcelas iguais;
+- início da obra depois da festa junina.
+
+# IV. Calendário de eventos
+Ficou aprovado o calendário do segundo semestre, que segue no Anexo I.
+
+# V. Encerramento
+Nada mais havendo a tratar, a presidente encerrou a reunião às 20h15. Eu, Rui Sá, secretário, lavrei esta ata, que vai assinada por todos.
+
+::: assinaturas
+Ana Lima | Presidente
+Rui Sá | Secretário
+Bia Reis | Tesoureira
+:::
+
+::: quebra-de-pagina
+::: titulo ANEXO I — CALENDÁRIO DE EVENTOS
+::: subtitulo Segundo semestre de 2026
+
+| Data | Evento | Responsável |
+|---|---|---|
+| 12 de julho | Festa julina | Bia Reis |
+| 20 de setembro | Mutirão de limpeza | Rui Sá |
+| 6 de dezembro | Confraternização | Ana Lima |
+```
+
+## Anti-Patterns
+
+- A paragraph broken into several lines "to fit the screen": it becomes several paragraphs.
+- `1.` typed for every item, counting on automatic numbering: the document shows exactly what is typed.
+- The title of the document as `# Título`: it becomes a section heading, not the centered title.
+- A signature drawn with underscores (`______`): use the `::: assinaturas` block.
+- "Página 1 de 3", the name of the organization or the date of printing written in the text: the header and the footer come from the profile.
+- A closing note such as "Posso ajustar o que precisar": it would be printed in the document.
+
+## Quality Criteria
+
+- [ ] Each paragraph is on one line; no line is a continuation of the previous one
+- [ ] `::: titulo` is the first line of the text (after the frontmatter, if there is one)
+- [ ] Every section and item number is written by hand, in sequence, with no gap
+- [ ] Every table has a header line and a separator line, and the same number of columns in each row
+- [ ] Each annex comes after `::: quebra-de-pagina` and has its own `::: titulo`
+- [ ] The `::: assinaturas` block is closed by `:::` and lists everyone who signs
+- [ ] No image, HTML, label, notes section or message to the reader
+- [ ] No invented data: what is missing is `[PREENCHER: …]`

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 checker measures the text as a blog post. A text to print, sign or file is `documento-oficial`. 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.

package/templates/_opencrew/core/modelos/documento-oficial.md

@@ -0,0 +1,42 @@
+# Perfil de documento oficial
+
+Este arquivo guarda o papel timbrado do projeto: o logotipo, o cabeçalho, o rodapé, as margens e
+a letra dos documentos Word. Preencha depois dos dois-pontos; o que ficar vazio não aparece no
+documento. Só as linhas `chave: valor` são lidas: o resto é comentário.
+
+Para gerar um documento: node _opencrew/core/scripts/documento.mjs "caminho/do/texto.md"
+
+## Cabeçalho
+
+# Logotipo: arquivo PNG de até 2 MB, com o caminho a partir da pasta do projeto (exemplo: Ativos/Marca/logo.png).
+logotipo:
+# Largura do logotipo no papel, em centímetros (de 1 a 6); a altura acompanha a proporção da imagem.
+logotipo_largura_cm: 2,5
+# Primeira linha do cabeçalho, em negrito: o nome da organização (exemplo: ASSOCIAÇÃO EXEMPLO DE MORADORES).
+cabecalho_1:
+# Segunda linha do cabeçalho (exemplo: CNPJ 00.000.000/0001-00 · Fundada em 1990).
+cabecalho_2:
+# Terceira linha do cabeçalho, em cinza (exemplo: www.exemplo.org · contato@exemplo.org).
+cabecalho_3:
+
+## Rodapé
+
+# Texto do rodapé, à esquerda, em todas as páginas (exemplo: Associação Exemplo de Moradores — documento oficial).
+rodape:
+# "Página X de Y" à direita do rodapé: sim ou nao.
+numero_pagina: sim
+
+## Página e letra
+
+# Margem esquerda, em centímetros (de 1 a 6).
+margem_esquerda_cm: 3,0
+# Margem direita, em centímetros (de 1 a 6).
+margem_direita_cm: 2,0
+# Margem superior, em centímetros (de 1 a 6).
+margem_superior_cm: 2,5
+# Margem inferior, em centímetros (de 1 a 6).
+margem_inferior_cm: 2,5
+# Fonte do texto: o nome como aparece no Word (até 40 letras, dígitos e espaços).
+fonte: Arial
+# Tamanho da letra do texto, em pontos (de 8 a 14; aceita meio ponto, como 10,5).
+tamanho_corpo_pt: 11

package/templates/_opencrew/core/prompts/build.prompt.md

@@ -70,52 +70,24 @@ Generate these files. Use the Write tool for all file creation — never use Bas
 
 ### Files to generate:
 
-1. **`crews/{code}/crew.yaml`** — Crew definition with pipeline
-   - Include a `skills:` section listing all skills:
-     ```yaml
-     skills:
-       - web_search
-       - web_fetch
-       # Add any skills from design.yaml:
-       # - apify
-       # - canva
-     ```
-   - Include a `data:` section listing all reference materials:
-     ```yaml
-     data:
-       - pipeline/data/research-brief.md
-       - pipeline/data/domain-framework.md
-       - pipeline/data/quality-criteria.md
-       - pipeline/data/output-examples.md
-       - pipeline/data/anti-patterns.md
-       - pipeline/data/tone-of-voice.md  # for content crews
-      ```
-    - Include a `fontes:` section with the project sources from `discovery.yaml →
-      project_sources` (omit it only if that list is empty). The Pipeline Runner reads them at the
-      start of every run and checks they still exist:
-      ```yaml
-      fontes:
-        - caminho: Memoria/01_Decisoes.md      # relative to the project root
-          para_que: decisões de público e posicionamento
-      ```
+**Read `_opencrew/core/formato-da-crew.md` before writing any file.** It is the single definition
+of `crew.yaml`, `pipeline.yaml`, the step frontmatter and the agent id, with a complete example of
+each. Write every file in that format; what follows here only adds what is specific to the Build.
+
+1. **`crews/{code}/crew.yaml`** — the crew: the `crew:` block (`code`, `name`, `description`,
+   `icon` and `tier`, all from `design.yaml`), `pipeline:`, `skills:`, `data:`, `fontes:`,
+   `agent_dependencies:` (only when the format file says so) and `max_review_cycles:`.
+    - `skills:` lists every skill from `design.yaml`; `data:` lists every reference material you
+      wrote in `pipeline/data/`.
+    - `fontes:` carries the project sources from `discovery.yaml → project_sources` (`path` →
+      `caminho`, `purpose` → `para_que`); omit it only if that list is empty. The Pipeline Runner
+      reads them at the start of every run and checks they still exist.
     - **Paths to the user's project files** — in `crew.yaml`, step files and tasks — are always
-      written as a caminho relativo à raiz do projeto (relative to the project root), between
-      backticks, e.g. `` `Ativos/Identidade Visual/logo.png` ``. NEVER write absolute paths
+      written as a caminho relativo à raiz do projeto (relative to the project root); in the
+      prose of step files and tasks, between backticks, e.g. `` `Ativos/Identidade Visual/logo.png` ``. NEVER write absolute paths
       (`C:/…`, `J:/…`, `/Users/…`): they break as soon as the user moves or syncs the folder.
-    - Include an `agent_dependencies:` section (OPTIONAL — enables runtime
-      Pre-Execution Agent Selection):
-      ```yaml
-      agent_dependencies:      # OPTIONAL — enables Pre-Execution Agent Selection at runtime
-        copywriter: [researcher]   # copywriter consumes researcher's output
-        designer: [copywriter]     # designer consumes copywriter's output
-        reviewer: [copywriter]     # reviewer consumes copywriter's output
-      ```
-      - `agent_dependencies` is OPTIONAL. ALWAYS emit it for crews that should show the
-        runtime agent-selection step — even as an empty map `agent_dependencies: {}` (the
-        selection step triggers on field presence, so an empty map enables selection with
-        no dependency warnings). Derive entries from the pipeline step order: for each
-        agent step, list the agent(s) whose output it reads via `inputFile`. Omit the field
-        entirely to keep the legacy behavior (run all agents, no selection step).
+    - `agent_dependencies:` — derive the entries from the step order: for each agent step, list
+      the agent(s) whose output it reads via `inputFile`.
 
 2. **`crews/{code}/crew-party.csv`** — Agent manifest
    - The header row MUST be EXACTLY these columns, in this order:
@@ -134,7 +106,7 @@ Generate these files. Use the Write tool for all file creation — never use Bas
      render the agent's name in "🤖 {name} is working…" announcements, and the Escritório
      (the optional live view) shows the same column. If `displayName` is missing, empty, or set
      to the role/title instead of the persona name, the crew renders with functions but no names.
-   - `id` = the `path` basename with `./agents/` and `.agent.md` stripped
+   - `id` = the agent id: the agent file name without `.agent.md`
      (e.g. `./agents/researcher.agent.md` → `researcher`).
    - `title` = the agent's `title:` frontmatter (the role/function label). This is a
      SEPARATE column from `displayName` — never merge or swap them.
@@ -145,7 +117,8 @@ Generate these files. Use the Write tool for all file creation — never use Bas
    - For ALL agents that include `tasks:` in their frontmatter, ALSO generate the task files:
      `crews/{code}/agents/{agent-id}/tasks/{task}.md` — one per entry in the `tasks:` list
 
-4. **`crews/{code}/pipeline/pipeline.yaml`** — Pipeline entry point
+4. **`crews/{code}/pipeline/pipeline.yaml`** — the order of the steps: one `step` + `file` entry
+   per step file, as in the format file
 
 5. **Step files** — `crews/{code}/pipeline/steps/step-NN-{name}.md` — one per pipeline step
 
@@ -185,7 +158,7 @@ Every agent file MUST contain ALL of the following sections. Target 120-200 line
 
 ```markdown
 ---
-id: "crews/{code}/agents/{agent}"
+id: "{agent-id}"                    # the file name without `.agent.md`
 name: "{Agent Name}"
 title: "{Agent Title}"
 icon: "{emoji}"
@@ -392,10 +365,10 @@ Every step file begins with YAML frontmatter followed by the markdown body. The
 ```yaml
 ---
 execution: subagent   # subagent = runs in background via Task tool; inline = runs in the main conversation
-agent: {agent-id}     # the agent's id (matches the id field in their .agent.md frontmatter)
-format: {format-id}   # OPTIONAL — e.g., "instagram-feed". Pipeline Runner auto-injects from _opencrew/core/best-practices/
-                      # Use for content creation steps where platform-specific rules should guide the agent
-                      # Omit for non-content steps (research, analysis, review without platform context)
+agent: {agent-id}     # the agent id: the agent file name without `.agent.md`
+format: {format-id}   # e.g., "instagram-feed". Pipeline Runner auto-injects from _opencrew/core/best-practices/
+                      # REQUIRED on every step whose text the checker measures (from the `on_reject` step up to the review)
+                      # Omit for non-content steps (research, analysis, the review itself)
 inputFile: crews/{code}/output/{filename}.{ext}   # path to input file from previous step — MUST use output/ prefix
 outputFile: crews/{code}/output/{filename}.{ext}  # path where this step saves its output — MUST use output/ prefix
                                                     # NEVER use pipeline/data/ for outputFile — that folder is for static
@@ -410,8 +383,9 @@ side_effects: irreversible  # REQUIRED for any step that publishes, posts, sends
                             # distributes outside the project (it cannot be undone). The Pipeline
                             # Runner never retries these automatically, and Gate 2c places them last.
                             # Omit for every other step.
-max_review_cycles: {N}  # ONLY for the review step: write it next to its `on_reject`.
-                        # By crew tier (`crew.tier` in design.yaml): Express 1, Standard 2, Full 3.
+on_reject: {N}        # ONLY for the review step: the number of the step the pipeline goes back to
+                      # (the first writing step). `max_review_cycles` goes in `crew.yaml`, by crew
+                      # tier (`crew.tier` in design.yaml): Express 1, Standard 2, Full 3.
 ---
 ```
 
@@ -428,7 +402,8 @@ agent: {agent-id}   # OPTIONAL — ties this checkpoint to an agent; if that age
 ---
 ```
 
-For **research focus checkpoints** (where the user's response is saved to a file), use extended frontmatter with `outputFile`:
+For a **checkpoint whose answer the next step needs** (the research focus, the chosen angle, the
+request to be worked on), use extended frontmatter with `outputFile`:
 ```yaml
 ---
 type: checkpoint
@@ -437,7 +412,7 @@ agent: {agent-id}   # OPTIONAL — same semantics as above
 ---
 ```
 The Pipeline Runner writes the user's response to this file before proceeding.
-The next step (researcher) reads it as `inputFile: crews/{code}/output/research-focus.md`.
+The next step reads it as `inputFile: crews/{code}/output/research-focus.md`.
 Using `output/` ensures the path transformation applies and the file lands in the run_id folder.
 
 Every pipeline step file MUST contain ALL of the following sections. Target 60-120 lines per step.
@@ -593,7 +568,7 @@ For EACH agent step in the pipeline that produces visuals, renders images, or pu
 If ANY check fails:
 1. Insert a new `type: checkpoint` step immediately before the offending agent step
 2. Renumber all subsequent steps (e.g. step-05 becomes step-06, etc.)
-3. Add the new step to the `checkpoints:` list in pipeline.yaml
+3. Add the new step to `pipeline.yaml`
 4. Generate a step file for the new checkpoint that asks the user to review and approve the preceding agent's output before the visual/publish step runs
 5. Re-validate Gate 2b. Max 2 fix attempts — after that, present to user for manual decision.
 
@@ -602,7 +577,8 @@ If ANY check fails:
 For EACH step that publishes, posts, sends email or distributes outside the project:
 - [ ] Its frontmatter declares `side_effects: irreversible` and `execution: inline`
 - [ ] It comes AFTER the Review step (the reviewer has already approved the final content)
-- [ ] The IMMEDIATELY preceding step is a `type: checkpoint` (Final Approval) that itself comes after the Review
+- [ ] The IMMEDIATELY preceding step is a `type: checkpoint` (Final Approval) that itself comes
+      after the Review, or another irreversible step (two in a row share the same Final Approval)
 - [ ] Only other irreversible steps follow it (nothing is created, rendered or reviewed after publishing)
 
 If ANY check fails:

package/templates/_opencrew/core/prompts/design.prompt.md

@@ -107,10 +107,10 @@ Present the three tiers with concrete trade-offs:
 | Aspect | ⚡ Express | 🎯 Standard | 🔬 Full |
 |--------|-----------|-------------|---------|
 | Agent count | 2-3 | 3-5 | 5-7 |
-| Reviewer | Writer self-reviews | 1 dedicated reviewer | Reviewer + cross-review |
+| Reviewer | The writer does the review step (no reviewer agent) | 1 dedicated reviewer | Reviewer + cross-review |
 | Sherlock | Never | Only if user provided URLs | Always (social + web + trends) |
 | Checkpoints | Final approval only | Research focus + content approval + final | All checkpoints + angle selection |
-| model_tier per step | All `fast` | Mix (research=fast, create=powerful) | All `powerful` |
+| model_tier (subagent steps only) | `fast` | Mix (research=fast, create=powerful) | `powerful` |
 | Cross-review | None | None | Reviewer + second reviewer cross-check |
 | On-reject loops | 1 max | 2 max | 3 max |
 
@@ -219,7 +219,7 @@ Para {crew purpose}, sugiro este time:
   - Simple crews (1 format, 1 platform): 2-3 roles
   - Medium crews (content + review): 3-4 roles
   - Complex crews (multi-platform, multi-format): 4-6 roles
-- **Every crew needs a reviewer** — mandatory quality gate
+- **Every crew needs a review step** — mandatory quality gate (Express: done by the writer; Standard and Full: by a reviewer role)
 - **Allow editing** — after presenting roles, ask:
   > "Quer adicionar, remover ou modificar algum papel? Ou o time está bom?"
 
@@ -229,7 +229,7 @@ Never suggest fewer than 2 roles. The minimum viable crew has:
 - One creator/executor (the person who produces the output)
 - One reviewer (the person who checks quality before delivery)
 
-For very simple tasks, these two roles can be the same person with a self-review step — but the user must explicitly approve this simplification.
+In the Express tier these two roles are the same agent: the writer also does the review step. The step still exists (with `on_reject`), so the automatic checker runs before it.
 
 ---
 
@@ -365,7 +365,7 @@ execution: inline
 skills: []
 ---
 ```
-The Build phase copies the base agent from `_opencrew/agents/copywriter.agent.md` and the local file only needs to specify what's DIFFERENT — a different tone, specific output examples for this crew, or additional anti-patterns. The runner merges: base first, local overrides on top.
+The Build phase copies the base agent from `_opencrew/agents/copywriter.agent.md` and the local file only needs to specify what's DIFFERENT — a different tone, specific output examples for this crew, or additional anti-patterns. The Build phase does the merge (base first, local overrides on top) and writes a complete file; the Pipeline Runner never merges.
 
 ### Design Philosophy
 
@@ -382,7 +382,7 @@ Design the crew with appropriate agents:
 - Follow the deep `.agent.md` format with full sections: Persona (Role, Identity, Communication Style), Principles, Operational Framework, Voice Guidance, Output Examples, Anti-Patterns, Quality Criteria, Integration
 - Design each agent from scratch, informed by the relevant best-practices files read in Phase A
 - Each agent has exactly one clear responsibility
-- Every crew needs a reviewer agent for quality control
+- Every crew needs a review step for quality control (a reviewer agent in Standard and Full)
 - YAGNI — never create agents that aren't strictly necessary
 
 ### Agent Naming Convention (MANDATORY — never skip)
@@ -428,8 +428,7 @@ The name should make someone smile — it's a pun tying a common name to the pro
 
 ### Agent Composition Rules
 
-- One clear responsibility per agent; reviewer agent mandatory; YAGNI strictly applied
-- Research/data steps → `execution: subagent`; creative/writing steps → `execution: inline`
+- One clear responsibility per agent; review step mandatory (reviewer agent in Standard and Full); YAGNI strictly applied
 - Content crews must include `pipeline/data/tone-of-voice.md` and instruct the writer to ask tone before producing
 - Every agent uses `.agent.md` format with all sections: Persona, Principles, Operational Framework, Voice Guidance, Output Examples, Anti-Patterns, Quality Criteria, Integration
 
@@ -441,9 +440,10 @@ The name should make someone smile — it's a pun tying a common name to the pro
 
 - **Research/data-gathering steps** → `execution: subagent` (runs in background via Task tool)
 - **Creative/writing steps** → `execution: inline` (runs in the main conversation)
-- Always include reviewer agent before final output
 - Add checkpoints at every user decision point
-- Include `on_reject` loops from reviewer back to writer
+- The files the Build phase will write follow `_opencrew/core/formato-da-crew.md` (fields of `crew.yaml`, of `pipeline.yaml` and of each step): design nothing that format cannot hold
+- Always include a review step before final output (see the tier table for who does it), with `on_reject`: the number of the first writing step
+- A step whose result is a document to print, sign or file (minutes, official letter, statement, contract, formal report) gets `format: documento-oficial`, in any kind of crew: the writer follows that guide, and the text becomes a Word document in the delivery of the run (or with `/opencrew documento <arquivo>`)
 
 ### Research Focus Checkpoint (MANDATORY for crews with a researcher)
 
@@ -602,6 +602,7 @@ crew:
   code: "{code}"
   name: "{Crew Name}"
   description: "{one-line description}"
+  icon: "{emoji}"
   tier: "express" | "standard" | "full"
 
 agents:
@@ -655,7 +656,7 @@ pipeline:
   - step: 2
     name: "checkpoint-name"
     type: "checkpoint"
-    output_file: "{path}"        # optional, for research focus checkpoints
+    output_file: "{path}"        # optional, when the next step needs the user's answer
 
 investigation:                   # only if investigation ran
   enriched: true