@aksp/opencrew 1.0.1 → 1.2.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.2.0] — 2026-08-02
+
+### Fixed
+- **Crews created without agent names**: some crews rendered their agents' functions
+  (e.g. "Pesquisador") but not their persona names (e.g. "Pedro Pesquisa"). Root cause:
+  `build.prompt.md` never specified the `crew-party.csv` schema, so the manifest could be
+  generated without a `displayName` column — the exact column the Pipeline Runner reads to
+  render agent names — even though the correct two-word names were present in each
+  `.agent.md`. Build now documents the full CSV schema (header + example) and enforces it
+  with a new blocking **Gate 0b: Crew-Party Manifest** that checks `displayName` exists and
+  matches each agent's `.agent.md` `name:`.
+
+### Added
+- **`/opencrew repair <crew>`**: repairs an already-created crew whose manifest is missing
+  agent names. It rebuilds `crew-party.csv` from the persona names already stored in each
+  `.agent.md` (no re-generation of agents, research, or pipeline). New prompt at
+  `_opencrew/core/prompts/repair.prompt.md`, routed via `AGENTS.md`.
+
+### Migration
+- To fix an existing crew that shows functions but no names:
+  1. `npx @aksp/opencrew update` — refreshes the framework and installs the repair command.
+  2. `/opencrew repair <crew>` — rewrites the crew's manifest with the correct names.
+  `update` intentionally never touches `crews/`, so the repair step is required in addition
+  to updating.
+
+## [1.1.0] — 2026-08-01
+
+### Fixed
+- **Skill catalog URLs**: `/opencrew install` now fetches skills from the correct fork
+  (`alberthpalhares/opencrew/templates/skills/`) instead of the upstream OpenSquad repo.
+- **Publish workflow**: restored `push: tags` as the sole trigger — the actual release
+  flow is `npm version` + `git push --tags`, not GitHub Releases. Documented in
+  `CONTRIBUTING.md`.
+- **Cross-platform test script**: replaced shell glob (`tests/*.test.js`) with an
+  explicit file list so `npm test` works on Windows PowerShell + Node 20.
+- **CI matrix**: test suite now runs on Ubuntu and Windows on every push/PR.
+
+### Added
+- **Test suite**: 30 tests (`node:test`) covering `fsx.js`, init, update, IDE bridge
+  validation, and documentation contracts.
+- **CI version-sync check**: `scripts/check-version-sync.js` fails the build if
+  `.opencrew-version` drifts from `package.json`.
+- **Playwright plugin warning**: `init` now warns Claude Code users to disable the
+  native Playwright extension (opencrew ships its own via `.mcp.json`).
+
+### Changed
+- **Dashboard opt-in**: Pipeline Runner `state.json` writes are now gated on
+  `Dashboard: enabled` in `preferences.md` (default: disabled). Removed the
+  unconditional 10-second sleep at the end of every pipeline run.
+- **Smaller fixes**: removed `AskUserQuestion` references from IDE-neutral files,
+  corrected `update.js` comment about overwrite behavior, pinned `@playwright/mcp`
+  version, removed stale root `skills/` directory (drifted duplicate of
+  `templates/skills/`).
+
 ## [1.0.1] — 2026-08-01
 
 ### Changed

package/README.md

@@ -1,4 +1,8 @@
-# opencrew
+# OpenCrew
+
+[![CI](https://github.com/alberthpalhares/opencrew/actions/workflows/ci.yml/badge.svg)](https://github.com/alberthpalhares/opencrew/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40aksp%2Fopencrew)](https://www.npmjs.com/package/@aksp/opencrew)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 **Crie equipes de agentes de IA que trabalham juntos — direto na sua IDE.**
 
@@ -6,7 +10,7 @@
 > you don't read Portuguese, use your browser's translator (e.g. Google Translate) or ask
 > an AI assistant to translate this page.
 
-opencrew é um framework de orquestração multi-agente. Descreva o que você precisa em
+OpenCrew é um framework de orquestração multi-agente. Descreva o que você precisa em
 linguagem natural e ele monta um time de agentes especializados que rodam como um pipeline
 automatizado, com pontos de aprovação humana. Funciona no Claude Code, Cursor, Codex,
 Gemini CLI, OpenCode, Antigravity e mais.
@@ -15,7 +19,7 @@ Gemini CLI, OpenCode, Antigravity e mais.
 > O [OpenSquad](https://github.com/renatoasse/opensquad) foi criado por
 > [Renato Asse](https://github.com/renatoasse) ([Comunidade Sem Codar](https://semcodar.com.br)).
 > Eu ([aksp](https://www.npmjs.com/~aksp)) uso o OpenSquad no dia a dia e quis melhorar
-> algumas coisas para o meu próprio fluxo de trabalho — o `opencrew` é essa versão
+> algumas coisas para o meu próprio fluxo de trabalho — o `OpenCrew` é essa versão
 > reformulada, compartilhada caso ajude outras pessoas também. Todo o crédito pela ideia e
 > pelo framework original é do Renato Asse. Veja [Origem e créditos](#origem-e-créditos)
 > abaixo. Licenciado sob MIT, assim como o original.
@@ -41,7 +45,7 @@ extra ou chave de API é necessária para começar.
 
 Algumas **skills opcionais** dependem de serviços externos — por exemplo, publicar no
 Instagram, gerar imagens com IA, fazer web scraping (Apify) ou enviar e-mails (Resend). Você
-não precisa se preocupar com isso antes de começar: se, ao montar uma crew, o opencrew
+não precisa se preocupar com isso antes de começar: se, ao montar uma crew, o OpenCrew
 identificar que ela precisa de uma dessas skills, ele pede a chave direto na conversa
 (explicando o que é e onde consegui-la) e salva tudo por conta própria. Não é preciso abrir
 nem editar nenhum arquivo manualmente.
@@ -88,6 +92,18 @@ Cada integração é só um ponteiro enxuto para a fonte única de verdade, o **
 - **Skills Engine** carrega integrações (scraping, design, publicação, e-mail…) sob demanda,
   usando um esquema em duas camadas para manter o consumo de tokens baixo.
 
+## Dashboard (opcional)
+
+O opencrew inclui um dashboard visual auto-contido — `dashboard/index.html`, um arquivo
+HTML único sem dependências que mostra a execução de uma crew como um escritório virtual
+animado (com agentes trabalhando em suas mesas, handoffs entre etapas, e indicador de
+progresso). 
+
+Ele é **desligado por padrão** — o Pipeline Runner não escreve `state.json` a menos que
+você ligue o recurso (`Dashboard: enabled` em `_opencrew/_memory/preferences.md`, via
+`/opencrew settings`). Inclui modo demo embutido para visualização sem precisar rodar uma
+crew real.
+
 ## Comandos (dentro da sua IDE)
 
 | Comando | O que faz |
@@ -106,7 +122,7 @@ vivem as instruções do sistema; os arquivos por IDE são gerados a partir de `
 
 ## Origem e créditos
 
-`opencrew` é uma **distribuição reformulada do [OpenSquad](https://github.com/renatoasse/opensquad)**,
+`OpenCrew` é uma **distribuição reformulada do [OpenSquad](https://github.com/renatoasse/opensquad)**,
 o framework de orquestração multi-agente criado e mantido por
 **[Renato Asse](https://github.com/renatoasse)**, fundador da
 [Comunidade Sem Codar](https://semcodar.com.br). O projeto original, seu conceito, o modelo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,8 +19,8 @@
   ],
   "scripts": {
     "start": "node bin/opencrew.js",
-    "test": "node --test tests/*.test.js",
-    "version": "node -e \"require('fs').writeFileSync('templates/_opencrew/.opencrew-version', require('./package.json').version + '\\n')\""
+    "test": "node --test tests/cli.test.js tests/docs.test.js tests/fsx.test.js tests/ides.test.js tests/init.test.js tests/update.test.js",
+    "version": "node -e \"require('fs').writeFileSync('templates/_opencrew/.opencrew-version', require('./package.json').version + '\\n')\" && git add templates/_opencrew/.opencrew-version"
   },
   "keywords": [
     "ai-agents",

package/src/cli.js

@@ -3,7 +3,7 @@ import { packageJsonPath } from './lib/paths.js';
 import { allIdeIds } from './lib/ides.js';
 import { init } from './commands/init.js';
 import { update } from './commands/update.js';
-import { c, log, err } from './lib/ui.js';
+import { c, log, err, warn, info } from './lib/ui.js';
 
 function parseArgs(argv) {
   const opts = { _: [] };
@@ -36,18 +36,49 @@ ${c.bold('Options for init')}
   --all           Configure every supported IDE
   --yes           Non-interactive; accept defaults
 
+${c.bold('Options for update')}
+  --check         Dry-run: report whether an update is available without making changes
+
 ${c.bold('Examples')}
   npx @aksp/opencrew init
   npx @aksp/opencrew init --ide=claude-code,codex
   npx @aksp/opencrew init --all
   npx @aksp/opencrew update
+  npx @aksp/opencrew update --check
 `);
 }
 
 export async function run(argv) {
   const opts = parseArgs(argv);
-  const pkg = await readJson(packageJsonPath);
-  const version = pkg.version;
+
+  let version = 'unknown';
+  let engines = {};
+  try {
+    const pkg = await readJson(packageJsonPath);
+    version = pkg.version;
+    engines = pkg.engines || {};
+  } catch {
+    err('Could not read package.json. The installation may be corrupted.');
+    info('Try reinstalling: npm install @aksp/opencrew');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Validate Node version against engines.node requirement.
+  if (engines.node) {
+    const min = engines.node.replace(/[^0-9.]/g, '');
+    if (min) {
+      const major = Number(min.split('.')[0]);
+      const current = Number(process.versions.node.split('.')[0]);
+      if (current < major) {
+        warn(`opencrew requires Node.js ${engines.node}. You have v${process.versions.node}.`);
+        info(`Upgrade Node or use a compatible version.`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+
   const cmd = opts._[0] || (opts.help ? 'help' : 'init');
 
   switch (cmd) {

package/src/commands/init.js

@@ -75,6 +75,11 @@ export async function init(opts = {}) {
     ok(`${ide.label} → ${ide.files.map((f) => f.path).join(', ')}`);
   }
 
+  if (ids.includes('claude-code')) {
+    warn(`opencrew ships its own Playwright MCP server (.mcp.json) — disable Claude Code's`);
+    warn(`native Playwright plugin/extension to avoid the two conflicting.`);
+  }
+
   // 4. Version stamp.
   await fs.writeFile(path.join(target, '_opencrew', '.opencrew-version'), version + '\n');
 

package/src/commands/update.js

@@ -6,7 +6,11 @@ import { c, log, info, ok, warn, step } from '../lib/ui.js';
 
 // Update refreshes ONLY the framework. It never touches:
 //   crews/, _opencrew/_memory/, _opencrew/_browser_profile/, .env, IDE bridges.
-export async function update() {
+// Note: catalog skills (skills/<name>/ that ship with the package) ARE fully
+// overwritten below — user edits to a catalog skill's own files are not preserved.
+// Only skill directories that don't exist in the package's templates/skills/ at all
+// (i.e. custom/user-authored skills) are left untouched.
+export async function update(opts = {}) {
   const target = process.cwd();
   const pkg = await readJson(packageJsonPath);
   const version = pkg.version;
@@ -25,6 +29,17 @@ export async function update() {
   log(`\n${c.bold(c.cyan('opencrew update'))}`);
   log(c.dim(`Installed: ${current}  →  Package: ${version}\n`));
 
+  if (opts.check) {
+    if (current === version) {
+      ok(`Up to date (v${version}).`);
+    } else {
+      info(`Update available: v${current} → v${version}.`);
+      info(`Run ${c.cyan('npx @aksp/opencrew update')} to apply.`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (current === version) {
     ok('Already up to date. Refreshing framework files anyway.');
   }
@@ -38,8 +53,11 @@ export async function update() {
   });
   ok(`_opencrew/core refreshed (${n} files)`);
 
-  // Refresh catalog skills but preserve any user-modified/added ones:
-  // only overwrite skills that ship with the package; leave others untouched.
+  // Refresh catalog skills: every skill shipped in templates/skills/ is fully
+  // overwritten (edits to a catalog skill's files do not survive an update).
+  // Skill directories that only exist in the user's project — i.e. not part of
+  // the catalog — are never touched, since copyDir only visits paths that exist
+  // in the source (templates/skills/).
   step('Refreshing catalog skills');
   let s = 0;
   await copyDir(path.join(templatesDir, 'skills'), path.join(target, 'skills'), {

package/src/lib/fsx.js

@@ -50,6 +50,21 @@ export async function writeFileSafe(p, content, { overwrite = true } = {}) {
   return true;
 }
 
+/**
+ * Remove a directory and all its contents.
+ * Does nothing silently if the path does not exist.
+ * @param {string} p  Directory path to remove.
+ * @returns {Promise<boolean>} true if something was deleted, false if it didn't exist.
+ */
+export async function deleteDir(p) {
+  try {
+    await fs.rm(p, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function readJson(p) {
   return JSON.parse(await fs.readFile(p, 'utf8'));
 }

package/templates/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "playwright": {
       "command": "npx",
-      "args": ["@playwright/mcp@latest", "--config", "_opencrew/config/playwright.config.json"]
+      "args": ["@playwright/mcp@0.0.78", "--config", "_opencrew/config/playwright.config.json"]
     }
   }
 }

package/templates/AGENTS.md

@@ -31,7 +31,7 @@ If `company.md` is empty or contains `<!-- NOT CONFIGURED -->`:
 
 ## Main Menu
 
-When the user types `/opencrew` or asks for the menu, present an interactive selector using AskUserQuestion with these options (max 4 per question):
+When the user types `/opencrew` or asks for the menu, present an interactive selector with these options (max 4 per question). Use your IDE's native interactive-choice mechanism if it has one (e.g. Claude Code's `AskUserQuestion`); otherwise present the options as a numbered list and ask the user to reply with a number:
 
 **Primary menu (first question):**
 - **Create a new crew** — Describe what you need and I'll build a crew for you
@@ -39,7 +39,7 @@ When the user types `/opencrew` or asks for the menu, present an interactive sel
 - **My crews** — View, edit, or delete your crews
 - **More options** — Skills, company profile, settings, and help
 
-If the user selects "More options", present a second AskUserQuestion:
+If the user selects "More options", present a second selector the same way:
 - **Skills** — Browse, install, create, and manage skills for your crews
 - **Company profile** — View or update your company information
 - **Settings & Help** — Language, preferences, configuration, and help
@@ -56,6 +56,7 @@ Parse user input and route to the appropriate action:
 | `/opencrew list` | List all crews in `crews/` directory |
 | `/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 manifest |
 | `/opencrew skills` | Load Skills Engine → Show skills menu |
 | `/opencrew install <name>` | Install a skill from the catalog |
 | `/opencrew uninstall <name>` | Remove an installed skill |
@@ -84,8 +85,28 @@ When running a crew:
 3. For each agent in the party CSV, also read their full `.agent.md` file from agents/ directory
 4. Load company context from `_opencrew/_memory/company.md`
 5. Load crew memory from `crews/{name}/_memory/memories.md`
-6. Read the pipeline runner instructions from `_opencrew/core/runner.pipeline.md`
-7. Execute the pipeline step by step following runner instructions
+6. Load user preferences from `_opencrew/_memory/preferences.md` (used to check the Dashboard toggle — see below)
+7. Read the pipeline runner instructions from `_opencrew/core/runner.pipeline.md`
+8. Execute the pipeline step by step following runner instructions
+
+## Dashboard (Optional)
+
+opencrew ships an optional visual dashboard — a self-contained HTML file
+(`dashboard/index.html`) that shows a crew run in progress as an animated
+virtual office. It is **disabled by default** and most installs never use it,
+so the Pipeline Runner does not write `state.json` unless the user has turned
+it on.
+
+- To use: open `dashboard/index.html` in a browser and point it at the
+  `crews/{name}/state.json` written during a run.
+- Toggle: `Dashboard: enabled` (or `disabled`) in `_opencrew/_memory/preferences.md`,
+  editable via `/opencrew settings`.
+- When disabled (default): the runner never creates, writes, or deletes `state.json`.
+- When enabled: the runner writes `crews/{name}/state.json` before each step and at
+  every handoff, exactly as described in `_opencrew/core/runner.pipeline.md`.
+- The dashboard auto-polls `state.json` every 1.5 seconds when in live mode;
+  it also includes a built-in demo mode so you can see what it looks like
+  without running a real crew.
 
 ## Language Handling
 
@@ -93,6 +114,13 @@ When running a crew:
 - All user-facing output should be in the user's preferred language
 - Internal file names and code remain in English
 - Agent personas communicate in the user's language
+- **Exception — crew memory scaffolding stays in PT-BR regardless of Output Language.**
+  The section headers in `crews/{name}/_memory/memories.md` (e.g. `## Estilo de Escrita`)
+  and the table columns in `crews/{name}/_memory/runs.md` (e.g. `Data | Run ID | Tema`) are
+  fixed structural labels, not generated prose — see `_opencrew/core/runner.pipeline.md`.
+  opencrew's primary supported audience is PT-BR (see README), so these are intentionally
+  not localized per-user. Only the *content* written into those sections follows the
+  user's Output Language.
 
 ## Critical Rules
 

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-1.0.1
+1.2.0

package/templates/_opencrew/_memory/preferences.md

@@ -7,3 +7,4 @@
 - **Output Language:**
 - **IDEs:**
 - **Date Format:** YYYY-MM-DD
+- **Dashboard:** disabled

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

@@ -92,7 +92,28 @@ Generate these files. Use the Write tool for all file creation — never use Bas
      ```
 
 2. **`crews/{code}/crew-party.csv`** — Agent manifest
-   - Path column uses `.agent.md` extension (e.g., `./agents/researcher.agent.md`)
+   - The header row MUST be EXACTLY these columns, in this order:
+     ```
+     id,displayName,title,icon,path,execution
+     ```
+   - One row per agent. Example:
+     ```
+     id,displayName,title,icon,path,execution
+     researcher,"Pedro Pesquisa","Pesquisador de Tendências",🔎,./agents/researcher.agent.md,subagent
+     copywriter,"Guilherme Gancho","Redator Copywriter",✍️,./agents/copywriter.agent.md,inline
+     ```
+   - **`displayName` is REQUIRED and MUST be byte-for-byte identical to the agent's
+     `name:` frontmatter field in its `.agent.md`** (the mandatory two-word "FirstName
+     LastName" persona name). The Pipeline Runner reads `displayName` — NOT `title` — to
+     render the agent's name in `state.json`, in "🤖 {name} is working…" announcements, and
+     in the dashboard. 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
+     (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.
+   - `path` column uses `.agent.md` extension (e.g., `./agents/researcher.agent.md`).
+   - Quote any field containing a space or comma with double quotes (as shown above).
 
 3. **Agent files** — one per agent: `crews/{code}/agents/{agent-id}.agent.md`
    - For ALL agents that include `tasks:` in their frontmatter, ALSO generate the task files:
@@ -426,6 +447,23 @@ For EACH agent in `design.yaml`, verify:
 
 If ANY agent has a single-word name (missing last name), this is a critical bug. Fix it by generating an alliterative last name that references the agent's role, then update the name in `design.yaml` and all generated files.
 
+### Gate 0b: Crew-Party Manifest (BLOCKING)
+
+Read `crews/{code}/crew-party.csv` and verify:
+- [ ] The header row contains a `displayName` column (not just `title`/`role`/`name`)
+- [ ] For EACH agent row: `displayName` is non-empty and has EXACTLY two words
+- [ ] For EACH agent row: `displayName` matches, byte-for-byte, the `name:` frontmatter
+      of the `.agent.md` file referenced by that row's `path` column
+
+This gate exists because the Pipeline Runner renders agent identity from the CSV's
+`displayName` column. An agent can have a correct two-word `name:` in its `.agent.md`
+(passing Gate 0) yet still render as "function without a name" if the CSV omits
+`displayName` or fills it with the role/title. That is the exact failure this gate catches.
+
+If ANY check fails: rewrite `crew-party.csv` using the canonical header
+(`id,displayName,title,icon,path,execution`), pulling `displayName` from each agent's
+`.agent.md` `name:` field and `title` from its `title:` field. Re-validate. Max 2 fix attempts.
+
 ### Gate 1: Agent Completeness (BLOCKING)
 
 For EACH `.agent.md` file, verify:
@@ -504,6 +542,7 @@ If any check fails: warn in the summary but don't block.
 Additional programmatic checks — read the filesystem to verify:
 - [ ] `crew.yaml` exists and is valid YAML
 - [ ] All `.agent.md` files listed in `crew-party.csv` exist
+- [ ] `crew-party.csv` has a `displayName` column, populated for every row and matching each agent's `.agent.md` `name:` field
 - [ ] All task files referenced in agent frontmatter exist
 - [ ] All step files referenced in `pipeline.yaml` exist
 - [ ] Skills listed in `crew.yaml` are installed in `skills/`

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

@@ -0,0 +1,119 @@
+# Repair — Fix Crew Agent Names / Manifest
+
+You are the opencrew Repair agent. Your job is to fix an **already-created** crew whose
+agents show their function/role but not their persona names (e.g. the dashboard and the
+Pipeline Runner announce "Pesquisador" instead of "Pedro Pesquisa").
+
+This is a known defect in crews built by older versions: the `crew-party.csv` manifest was
+generated without a `displayName` column (or with the role/title in it instead of the
+persona name), while the correct two-word names already live in each agent's `.agent.md`
+`name:` frontmatter. This repair is **deterministic** — you pull names from the `.agent.md`
+files and rewrite the manifest. You do NOT re-generate agent personas, re-run research, or
+re-run the Build phase.
+
+## Scope
+
+You may ONLY touch files under `crews/{code}/`:
+- `crews/{code}/crew-party.csv`
+- `crews/{code}/agents/*.agent.md` (only in the fallback case — see Step 4)
+- `crews/{code}/state.json` (only if it exists)
+
+Never modify `_opencrew/`, `templates/`, or any other crew. Use the Write tool for all file
+writes (never Bash `mkdir`).
+
+---
+
+## Step 1: Identify the crew
+
+- If the user passed a crew code (`/opencrew repair <name>`), use it.
+- Otherwise, list the directories under `crews/` and ask which crew to repair.
+  - If exactly 1 crew exists, offer it plus a "Cancel" option.
+  - If 0 crews exist, tell the user there is nothing to repair and stop.
+
+Verify `crews/{code}/crew.yaml` and `crews/{code}/agents/` exist. If not, report and stop.
+
+## Step 2: Read the source of truth (the agent files)
+
+For EACH `crews/{code}/agents/*.agent.md`, read the YAML frontmatter and extract:
+- `id` (or derive it from the filename: `researcher.agent.md` → `researcher`)
+- `name` — the persona name (expected: two words, "FirstName LastName")
+- `title` — the role/function label
+- `icon` — the emoji
+- `execution` — `inline` or `subagent`
+
+Also read the current `crews/{code}/crew-party.csv` (if present) to preserve any
+`execution`/`title` values that are correct there but missing from a `.agent.md`.
+
+## Step 3: Rebuild `crew-party.csv`
+
+Write `crews/{code}/crew-party.csv` with the canonical header and one row per agent:
+
+```
+id,displayName,title,icon,path,execution
+```
+
+- `displayName` = the agent's `name:` from its `.agent.md` (the two-word persona name).
+- `title` = the agent's `title:`.
+- `icon` = the agent's `icon:`.
+- `path` = `./agents/{id}.agent.md`.
+- `execution` = the agent's `execution:` (default `inline` if absent).
+- Quote any field containing a space or comma with double quotes.
+- Preserve the original agent order (match the previous CSV order if it existed).
+
+## Step 4: Fallback — agent whose `.agent.md` name is itself broken
+
+If an agent's `.agent.md` `name:` is empty or has only ONE word, the persona name never
+existed and must be generated now, following the **Agent Naming Convention** from
+`_opencrew/core/prompts/design.prompt.md`:
+
+1. Read the user's Output Language from `_opencrew/_memory/preferences.md`.
+2. Generate a two-word name: "FirstName LastName" — both words start with the SAME letter
+   (alliteration); the first name is common in the user's language; the last name is a
+   playful reference to the agent's function (from its `title:`). Each agent in the crew
+   must use a DIFFERENT initial letter.
+3. Update BOTH the `.agent.md` `name:` frontmatter AND the `# {Name}` heading in that file.
+4. Use the new name as the `displayName` in the rebuilt CSV.
+
+Only do this for agents that are actually broken. Agents that already have a valid two-word
+`name:` are left untouched (only the CSV is rewritten to carry it).
+
+## Step 5: Refresh `state.json` (only if it exists)
+
+If `crews/{code}/state.json` exists, update each agent entry's `name` field to the repaired
+`displayName`. Do not change any other field. If the file does not exist, skip — the
+Pipeline Runner recreates it from the CSV on the next run.
+
+## Step 6: Report
+
+Present a summary table of what changed:
+
+```
+Crew "{name}" repaired.
+
+| Agent id    | Before        | After            | Source        |
+|-------------|---------------|------------------|---------------|
+| researcher  | (role only)   | 🔎 Pedro Pesquisa | .agent.md     |
+| copywriter  | Guilherme     | ✍️ Guilherme Gancho | generated   |
+
+crew-party.csv: rewritten with displayName column
+state.json: {updated | not present}
+
+Run it: /opencrew run {code}
+```
+
+If nothing was broken (CSV already had a valid `displayName` for every agent), say so
+plainly instead of inventing changes: "This crew's manifest is already correct — no repair
+needed."
+
+---
+
+## Rules
+
+- **DO** pull names from `.agent.md` `name:` — that is the source of truth.
+- **DO** rewrite the whole `crew-party.csv` with the canonical header.
+- **DO** limit persona generation to agents whose own `.agent.md` name is missing/one-word.
+- **DO NOT** re-run Discovery, Design, Build, research, or investigations.
+- **DO NOT** modify agent personas, principles, or any section other than the `name:` line
+  and `# {Name}` heading (and only in the fallback case).
+- **DO NOT** touch any file outside `crews/{code}/`.
+- **DO NOT** fabricate a summary — report only what you actually changed.

package/templates/_opencrew/core/runner.pipeline.md

@@ -14,6 +14,21 @@ Before starting execution:
    - The crew's `crew-party.csv` (all agent personas)
    - Company context from `_opencrew/_memory/company.md`
    - Crew memory from `crews/{name}/_memory/memories.md`
+   - User preferences from `_opencrew/_memory/preferences.md`
+
+1a. **Check the Dashboard toggle** — the visual dashboard (`state.json` writes) is an
+    optional, opt-in feature that most installs never use (it requires running the
+    separate dashboard app from source — see README). Scan the already-loaded
+    `preferences.md` for a `Dashboard:` field:
+    - If it reads `Dashboard: enabled` → set `dashboard_enabled = true` for this run.
+    - Otherwise (`disabled`, missing, or preferences.md not configured yet) →
+      set `dashboard_enabled = false`. This is the default.
+    Store `dashboard_enabled` in working memory for the rest of this run. Every
+    `state.json` read/write instruction in this document is conditional on it —
+    when `false`, skip ALL of them; never create, update, or delete
+    `crews/{name}/state.json`.
+
+> **Note on language**: the section headers below (`## Estilo de Escrita`, `## Design Visual`, etc.) and the `runs.md` table columns (`Data | Run ID | Tema | ...`) are fixed PT-BR structural labels, not translated per Output Language — opencrew's primary supported audience is PT-BR (see AGENTS.md → Language Handling). Only the *content* written under these headers follows the user's preferred language.
 
 1b. **Memory format migration** — After loading `memories.md`, check whether it uses the new format by scanning for the `## Estilo de Escrita` section header:
    ```bash
@@ -76,8 +91,8 @@ Before starting execution:
      - If it does (sub-second collision), append `-2`, `-3`, etc. until the folder does not exist
    - Create the folder using Bash: `mkdir -p crews/{name}/output/{run_id}`
    - Store `run_id` in working memory for this run — it will be used for ALL output paths
-6. **Initialize state.json**: Create `crews/{name}/state.json` from scratch (see below). State writes are always mandatory.
-   - **IMPORTANT**: You MUST write to `crews/{name}/state.json` before every step and after every handoff. This is non-negotiable. Never skip these writes.
+6. **Initialize state.json** (only if `dashboard_enabled` — see step 1a; otherwise skip this entire step, including all sub-steps below):
+   - **IMPORTANT**: When enabled, write to `crews/{name}/state.json` before every step and after every handoff, as described throughout this document. When `dashboard_enabled` is false, never create, write, or delete this file.
    - Create `state.json` from scratch:
      a. Read `crews/{name}/crew-party.csv` — for each agent row (skip header), extract:
         - `id`: take the `path` column, strip `./agents/` prefix and `.agent.md` suffix
@@ -270,7 +285,7 @@ Apply this transformation consistently for every write in this step.
 
 ### For each pipeline step:
 
-0. **Update dashboard** — MANDATORY. Write `crews/{name}/state.json` using the Write tool. Always write — it is never wrong to update the dashboard. Use this content:
+0. **Update dashboard** (only if `dashboard_enabled`; otherwise skip to step 1). Write `crews/{name}/state.json` using the Write tool. Use this content:
    ```json
    {
      "crew": "{crew code from crew.yaml}",
@@ -458,7 +473,8 @@ When a step has `on_reject: {step-id}`:
 
 ### Dashboard Handoff (between steps)
 
-After a step completes output and there IS a next step (MANDATORY):
+Only if `dashboard_enabled` (otherwise skip this entire section). After a step
+completes output and there IS a next step:
 
 1. **Write delivering state** — Write `crews/{name}/state.json` with:
    - Current step's agent: `"status": "delivering"`
@@ -489,13 +505,13 @@ After a step completes output and there IS a next step (MANDATORY):
 For reference, the complete execution order for each pipeline step is:
 
 ```
-0. Dashboard update (state.json)
+0. Dashboard update (state.json) — only if dashboard_enabled
 1. Pre-Step Input Validation (bash gate)
 2. Read step file
 3. Check execution mode and execute (subagent / inline / checkpoint)
 4. Post-Step Output Validation (bash gate)
 5. Veto Condition Enforcement
-6. Dashboard Handoff (to next step)
+6. Dashboard Handoff (to next step) — only if dashboard_enabled
 ```
 
 Steps 1 and 4 are binary bash gates. If either fails, the pipeline does NOT advance — the user is consulted.
@@ -504,7 +520,7 @@ Steps 1 and 4 are binary bash gates. If either fails, the pipeline does NOT adva
 
 1. Save final output to `crews/{name}/output/{run_id}/{filename}.md`
    (The run folder was created during initialization — no separate date subfolder needed)
-1b. **Update dashboard** — MANDATORY. Write `crews/{name}/state.json` with:
+1b. **Update dashboard** (only if `dashboard_enabled`; otherwise skip to step 2 below). Write `crews/{name}/state.json` with:
     - `"status": "completed"`
     - All agents: `"status": "done"`
     - `"updatedAt"`: now
@@ -512,7 +528,7 @@ Steps 1 and 4 are binary bash gates. If either fails, the pipeline does NOT adva
     - `"startedAt"`: preserve from existing `state.json`
     - Keep existing `"handoff"` object
 
-### Post-Completion Cleanup
+### Post-Completion Cleanup (only if `dashboard_enabled`)
 
 After writing the final "completed" state to `crews/{name}/state.json`:
 
@@ -521,13 +537,12 @@ After writing the final "completed" state to `crews/{name}/state.json`:
    ```bash
    cp crews/{name}/state.json crews/{name}/output/{run_id}/state.json
    ```
-3. Wait 10 seconds (so the dashboard can display the completed state)
-4. Delete the working copy:
-   ```bash
-   rm crews/{name}/state.json
-   ```
+3. Leave the working copy of `crews/{name}/state.json` in place — do not delete it and
+   do not add an artificial delay. A dashboard watching the file already sees the
+   "completed" status the moment it's written; the next run's initialization (step 6)
+   overwrites this file from scratch. There is nothing to clean up.
 
-This archives the run state for the `runs` command while keeping the crew root clean.
+This archives the run state for the `runs` command while keeping crew history available.
 
 2. **Update crew memory** — write to BOTH files (runs after Post-Completion Cleanup above):
 

package/templates/_opencrew/core/skills.engine.md

@@ -12,9 +12,19 @@ You are the Skills Engine. Your job is to manage skill integrations for opencrew
 ## File Locations
 
 - **Installed skills**: `skills/` — each skill in its own subdirectory with SKILL.md
-- **Skill catalog**: `https://github.com/renatoasse/opensquad/tree/main/skills`
+- **Skill catalog index**: `skills/catalog.json` (local) — structured skill metadata.
+  If missing, fall back to the catalog README:
+  `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/README.md`
 - **Skill format reference**: `skills/opencrew-skill-creator/references/skill-format.md`
 
+### Catalog URL Resolution
+
+When fetching skill files from the catalog, resolve the base URL in this order:
+1. Read `skills/catalog.json` (installed locally during init/update) → use its `baseUrl` field
+2. If not available, default to:
+   `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills`
+3. Append `/<name>/SKILL.md` (or other file paths) to the base URL
+
 ## How Skills Are Detected
 
 A skill is installed if and only if `skills/<name>/SKILL.md` exists.
@@ -96,9 +106,18 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
 
 1. User provides a skill name (or selects from the catalog).
 
-2. **Fetch SKILL.md from GitHub**:
+2. **Resolve the catalog base URL** (see Catalog URL Resolution above).
+
+3. **Validate minimum version** (if catalog.json available):
+   - Check `catalog.json` → `skills.<name>.minVersion`
+   - Compare against the installed opencrew version (from `_opencrew/.opencrew-version`)
+   - If installed version < minVersion → **ERROR**: "Skill '{name}' requires opencrew
+     v{minVersion} or newer. You have v{installed}. Run `npx @aksp/opencrew update`
+     to upgrade."
+
+4. **Fetch SKILL.md from catalog**:
    ```
-   https://raw.githubusercontent.com/renatoasse/opensquad/main/skills/<name>/SKILL.md
+   {baseUrl}/<name>/SKILL.md
    ```
    - If fetch fails (404 or network error) → **ERROR**: "Skill '<name>' not found in the skills catalog."
    - Do NOT proceed if the SKILL.md cannot be fetched.
@@ -112,7 +131,7 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
 
 5. **Fetch additional files** (if the skill requires them):
    - If the SKILL.md frontmatter has `script.path` → fetch the script file from:
-     `https://raw.githubusercontent.com/renatoasse/opensquad/main/skills/<name>/{script.path}`
+     `{baseUrl}/<name>/{script.path}`
      Create subdirectories (e.g., `scripts/`) as needed.
    - If the skill has a `references/` directory mentioned → fetch those files too.
    - If the skill has an `assets/` directory mentioned → fetch those files too.
@@ -345,11 +364,16 @@ When the Architect reaches Phase 3.5 during crew creation:
    to get name, description, type, and categories.
 
 2. **Fetch the catalog index**:
-   Fetch the catalog README from GitHub to see all available skills:
-   ```
-   https://raw.githubusercontent.com/renatoasse/opensquad/main/skills/README.md
-   ```
-   - If fetch fails → proceed with only installed skills (do not block crew creation).
+   a. First, try to read `skills/catalog.json` (installed locally). If it exists:
+      - Parse the JSON and extract the `skills` map and `baseUrl`
+      - Use this for discovery (skip the network fetch below)
+   b. If `skills/catalog.json` does NOT exist (pre-v1.1 install), fall back to fetching
+      the catalog README from GitHub:
+      ```
+      https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/README.md
+      ```
+      Parse the markdown table to extract skill names, types, and descriptions.
+   c. If both fail → proceed with only installed skills (do not block crew creation).
 
 3. **Analyze crew requirements**:
    From the discovery phase answers (Phase 1), identify what the crew needs:

package/templates/skills/README.md

@@ -0,0 +1,22 @@
+# Catálogo de Skills — opencrew
+
+Este é o índice de skills disponíveis no catálogo oficial do opencrew. O Skills Engine
+(`_opencrew/core/skills.engine.md`) lê este arquivo durante a descoberta de skills (Operação 7)
+e busca `SKILL.md` de cada uma via `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/<name>/SKILL.md`
+para instalação (Operação 2).
+
+| Skill | Tipo | Descrição |
+|-------|------|-----------|
+| `apify` | mcp | Plataforma de web scraping e automação. Extrai dados de qualquer site usando Actors prontos da Apify Store. |
+| `blotato` | mcp | Publicação e agendamento em redes sociais (Instagram, LinkedIn, Twitter/X, TikTok, YouTube). |
+| `canva` | mcp | Cria, busca, preenche e exporta designs do Canva (autenticação via OAuth). |
+| `image-ai-generator` | script | Gera imagens via API do OpenRouter (modo teste barato + modo produção de alta qualidade). |
+| `image-creator` | mcp | Renderiza HTML/CSS em imagens pixel-perfect via Playwright. Motor genérico para qualquer formato visual. |
+| `image-fetcher` | hybrid | Obtém assets visuais de múltiplas fontes: busca na web, screenshots via Playwright, arquivos do usuário. |
+| `instagram-publisher` | script | Publica carrosséis do Instagram a partir de imagens locais via imgBB + Graph API. |
+| `opencrew-best-practice-creator` | prompt | Guia a criação e manutenção de arquivos de best-practice na biblioteca do opencrew. |
+| `opencrew-skill-creator` | prompt | Cria, edita e avalia (evals/benchmark) skills do opencrew de qualquer tipo. |
+| `resend` | mcp | Envio de emails pelo servidor MCP oficial da Resend (individual, lote, anexos, agendamento). |
+| `template-designer` | prompt | Seleção de template visual para agentes de design — gera variações, renderiza e salva a identidade aprovada. |
+
+Para instalar qualquer uma delas dentro da sua IDE: `/opencrew install <nome>`.

package/templates/skills/catalog.json

@@ -0,0 +1,61 @@
+{
+  "version": "1",
+  "baseUrl": "https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills",
+  "skills": {
+    "apify": {
+      "type": "mcp",
+      "description": "Plataforma de web scraping e automação. Extrai dados de qualquer site usando Actors prontos da Apify Store.",
+      "minVersion": "1.0.0"
+    },
+    "blotato": {
+      "type": "mcp",
+      "description": "Publicação e agendamento em redes sociais (Instagram, LinkedIn, Twitter/X, TikTok, YouTube).",
+      "minVersion": "1.0.0"
+    },
+    "canva": {
+      "type": "mcp",
+      "description": "Cria, busca, preenche e exporta designs do Canva (autenticação via OAuth).",
+      "minVersion": "1.0.0"
+    },
+    "image-ai-generator": {
+      "type": "script",
+      "description": "Gera imagens via API do OpenRouter (modo teste barato + modo produção de alta qualidade).",
+      "minVersion": "1.0.0"
+    },
+    "image-creator": {
+      "type": "mcp",
+      "description": "Renderiza HTML/CSS em imagens pixel-perfect via Playwright. Motor genérico para qualquer formato visual.",
+      "minVersion": "1.0.0"
+    },
+    "image-fetcher": {
+      "type": "hybrid",
+      "description": "Obtém assets visuais de múltiplas fontes: busca na web, screenshots via Playwright, arquivos do usuário.",
+      "minVersion": "1.0.0"
+    },
+    "instagram-publisher": {
+      "type": "script",
+      "description": "Publica carrosséis do Instagram a partir de imagens locais via imgBB + Graph API.",
+      "minVersion": "1.0.0"
+    },
+    "opencrew-best-practice-creator": {
+      "type": "prompt",
+      "description": "Guia a criação e manutenção de arquivos de best-practice na biblioteca do opencrew.",
+      "minVersion": "1.0.0"
+    },
+    "opencrew-skill-creator": {
+      "type": "prompt",
+      "description": "Cria, edita e avalia (evals/benchmark) skills do opencrew de qualquer tipo.",
+      "minVersion": "1.0.0"
+    },
+    "resend": {
+      "type": "mcp",
+      "description": "Envio de emails pelo servidor MCP oficial da Resend (individual, lote, anexos, agendamento).",
+      "minVersion": "1.0.0"
+    },
+    "template-designer": {
+      "type": "prompt",
+      "description": "Seleção de template visual para agentes de design — gera variações, renderiza e salva a identidade aprovada.",
+      "minVersion": "1.0.0"
+    }
+  }
+}

package/templates/skills/instagram-publisher/SKILL.md

@@ -41,7 +41,7 @@ Use the Instagram Publisher when you need to publish carousel posts directly to
 
 1. List JPEG files in `crews/{crew}/output/images/` sorted by name.
    If no files found: stop and ask the user to add images before continuing.
-2. Present the image list to the user with AskUserQuestion to confirm order.
+2. Present the image list to the user to confirm order (use your IDE's native interactive-choice mechanism if it has one; otherwise a numbered list).
 3. Extract the caption from the content draft:
    - Use the hook slide text + CTA slide text
    - Max 2200 characters (Instagram limit)