@aksp/opencrew 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.2.1] — 2026-08-02
+
+### Changed
+- **Menu discovery for repair**: the "My crews" menu entry now mentions `repair`, so the
+  command introduced in 1.2.0 is discoverable from the menu and not only from the command
+  routing table.
+- **README**: standardized the project name as "OpenCrew" in prose (commands and the npm
+  package name stay lowercase).
+
+## [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

package/README.md

@@ -1,4 +1,4 @@
-# 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)
@@ -10,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.
@@ -19,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.
@@ -45,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.
@@ -94,7 +94,7 @@ Cada integração é só um ponteiro enxuto para a fonte única de verdade, o **
 
 ## Dashboard (opcional)
 
-O opencrew inclui um dashboard visual auto-contido — `dashboard/index.html`, um arquivo
+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). 
@@ -122,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.1.0",
+  "version": "1.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -20,7 +20,7 @@
   "scripts": {
     "start": "node bin/opencrew.js",
     "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')\""
+    "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/templates/AGENTS.md

@@ -36,7 +36,7 @@ When the user types `/opencrew` or asks for the menu, present an interactive sel
 **Primary menu (first question):**
 - **Create a new crew** — Describe what you need and I'll build a crew for you
 - **Run an existing crew** — Execute a crew's pipeline
-- **My crews** — View, edit, or delete your crews
+- **My crews** — View, edit, repair, or delete your crews
 - **More options** — Skills, company profile, settings, and help
 
 If the user selects "More options", present a second selector the same way:
@@ -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 |

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-1.0.1
+1.2.1

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.