@aksp/opencrew 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [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 e pedido avulso à crew (`/opencrew pedir`), que vêm
+na 1.12.0; retomar uma execução interrompida, na 1.13.0. 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 verificador media como post de blog), 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
+│   │   ├── formato-da-crew.md    ← o formato dos arquivos de uma crew (crew.yaml, pipeline.yaml, passos)
 │   │   ├── 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
+│   │   ├── 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,13 @@ 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 verificador mede tudo como post de blog), 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`.
 - **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 +497,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 +517,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.11.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,7 +10,8 @@ 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 `
+   (except for `/opencrew documento` and the request to deliver a run that already ended: neither
+   uses the company context)
 4. Otherwise, display the MAIN MENU
 
 ## Onboarding Flow (first time only)
@@ -50,11 +51,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 +75,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.11.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/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/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: