# Analisi tecnica per nuovi agenti `code_reviewer` e `test_writer`

Repository verificato in sola lettura: `sophiadeveloper/mcp-servers`
Data analisi: 2026-05-15
Perimetro richiesto: agenti portabili Codex + Copilot Pro+, skill in `skills/`, compatibilita' con regole e configurazioni esistenti.

---

## 1. Sintesi esecutiva

L'implementazione dei due nuovi agenti e' consigliata, ma deve seguire la pipeline gia' presente nel repository:

1. non editare direttamente `.codex/agents/*.toml`;
2. non editare direttamente `.copilot/agents/*.agent.md`;
3. aggiungere i ruoli nella fonte canonica `docs/agents/canonical-subagents.yaml`;
4. aggiornare `scripts/portable-agents-lib.js`;
5. rigenerare i target runtime con `node scripts/sync-portable-agents.js`;
6. verificare assenza di drift con `node scripts/check-agents-doc.js`;
7. correggere solo in modo mirato `skills/mcp-code-reviewer`, senza duplicare la skill.

La proposta consigliata e':

| Agente | Stato | Nome consigliato | Tipo | Write access |
| --- | --- | --- | --- | --- |
| Code reviewer | Da aggiungere | `code_reviewer` | review read-only | No |
| Test checklist writer | Da aggiungere | `test_writer` | checklist test e copertura regressione | No nella v1 |

Nota: il nome `test_writer` resta compatibile con la proposta precedente, ma nella v1 il ruolo deve essere esplicitamente "checklist/planning", non scrittura automatica dei test. In futuro potra' evolvere verso generazione template esportabile per Mantis.

---

## 2. Evidenze osservate nel repository

### 2.1 Governance principale

`AGENTS.md` dichiara regole permanenti concise:

- applicare prima `AGENTS.md`, poi guida tecnica viva e skill rilevanti;
- mantenere compatibilita' legacy;
- preferire cambi incrementali;
- evitare refactor estesi fuori scope;
- aggiornare coerentemente codice, test/smoke e documentazione;
- preservare pattern consolidati `action`, `project_path`, `save_path`;
- mantenere compatibilita' con client MCP severi come Codex e Copilot VS Code;
- eseguire smoke test, schema check e aggiornamento documentazione quando si modificano MCP/skill.

Fonte verificata: `AGENTS.md`.

### 2.2 Runtime agenti derivati

Entrambi i runtime agenti dichiarano esplicitamente una fonte canonica:

- fonte canonica: `docs/agents/canonical-subagents.yaml`;
- target Codex: `.codex/agents/*.toml`;
- target Copilot/VS Code: `.copilot/agents/*.agent.md`.

I README di `.codex/agents` e `.copilot/agents` indicano di non editare i runtime direttamente, salvo emergenze, e di usare:

```bash
node scripts/sync-portable-agents.js
node scripts/check-agents-doc.js
```

Fonti verificate:

- `.codex/agents/README.md`
- `.copilot/agents/README.md`

### 2.3 Ruoli canonici attuali

`docs/agents/canonical-subagents.yaml` contiene tre ruoli:

- `explorer`
- `implementer`
- `technical_analyst`

Profili modello attuali:

| Ruolo | Modello | Reasoning |
| --- | --- | --- |
| `explorer` | `gpt-5.4-mini` | `medium` |
| `implementer` | `gpt-5.3-codex` | `medium` |
| `technical_analyst` | `gpt-5.4` | `high` |

Fonte verificata: `docs/agents/canonical-subagents.yaml`.

### 2.4 Generazione runtime

`scripts/sync-portable-agents.js` legge il canonico, valida i ruoli e genera entrambi i target runtime.

`scripts/portable-agents-lib.js` contiene oggi:

```js
const ROLE_IDS = ['explorer', 'implementer', 'technical_analyst'];
```

Quindi, se si aggiungono ruoli solo nel YAML, non verranno generati finche' `ROLE_IDS` non viene esteso.

Lo stesso file contiene anche il mapping tool per Copilot:

```js
function toolsForRole(roleId) {
  if (roleId === 'implementer') return ['codebase', 'editFiles', 'search'];
  return ['codebase', 'search'];
}
```

Per i due nuovi agenti v1 e' corretto restare read-only, quindi non serve `editFiles`.

Fonti verificate:

- `scripts/sync-portable-agents.js`
- `scripts/portable-agents-lib.js`

### 2.5 Skill code review esistente

Esiste gia' `skills/mcp-code-reviewer/SKILL.md`.

La skill e' gia' ben allineata a:

- review di snippet, file, commit, diff, branch o PR;
- priorita' su regole locali, correttezza, robustezza, performance, test coverage e contesto funzionale disponibile;
- anti-trigger verso `mcp-technical-analyst` per intake multi-sorgente;
- anti-trigger verso `mcp-master-orchestrator` per flussi review + fix + test + handoff;
- separazione fatti osservati, inferenze, dubbi aperti e raccomandazioni;
- finding classificati per categoria.

Fonte verificata: `skills/mcp-code-reviewer/SKILL.md`.

### 2.6 Governance skill

`docs/skill-governance-matrix.md` classifica `mcp-code-reviewer` con:

- precisione trigger alta;
- separazione core/references alta;
- eval coverage alta;
- confini alti con analyst/orchestrator;
- script support basso, non bloccante.

La matrice conferma che non serve creare una skill duplicata per il code review.

Fonte verificata: `docs/skill-governance-matrix.md`.

---

## 3. Decisione tecnica consigliata

### 3.1 Aggiungere `code_reviewer`

`code_reviewer` deve essere un agente operativo read-only che applica il comportamento della skill `mcp-code-reviewer` quando il task e' una review di scope definito.

Non deve:

- editare file;
- fare fix;
- fare intake multi-sorgente;
- fare orchestrazione multi-step;
- inventare requisiti funzionali.

Deve:

- leggere diff/file/commit/branch/PR;
- applicare regole locali;
- produrre pochi finding ad alto valore;
- riportare evidenza, impatto, severita', confidenza e fix suggerito;
- suggerire test/checklist quando il rischio lo richiede.

### 3.2 Aggiungere `test_writer` come checklist writer v1

Dato il vincolo espresso, `test_writer` non deve essere inizialmente un agente che scrive o lancia test in autonomia.

Ruolo consigliato v1:

- analizzare una modifica, un diff, un bug, una issue o i finding del reviewer;
- proporre checklist di test manuali, smoke test, regressioni e casi limite;
- indicare dati, ambiente, precondizioni, passi e risultato atteso;
- produrre output copiabile in Mantis o PR;
- non modificare file.

Questo mantiene bassa la pericolosita' e prepara una futura evoluzione con template esportabile.

Nome alternativo piu' preciso: `test_planner`.
Tuttavia, per continuita' con la proposta iniziale, e' accettabile mantenere `test_writer` purche' la description chiarisca che in v1 scrive checklist, non codice test.

---

## 4. Modifiche consigliate

## 4.1 `docs/agents/canonical-subagents.yaml`

Aggiungere due ruoli dopo `technical_analyst`.

### Blocco YAML proposto: `code_reviewer`

```yaml
  - id: code_reviewer
    purpose: Read-only role for focused code review of snippets, files, commits, diffs, branches, or pull requests.
    prioritize:
      - Apply local project rules and conventions before generic best practices.
      - Review only the requested scope unless direct evidence requires a narrow dependency check.
      - Report high-value findings with severity, confidence, evidence, impact, and minimal fix guidance.
      - Call out test gaps and regression risks when they materially affect the change.
    avoid:
      - Editing files or preparing patches.
      - Expanding into broad multi-source analysis without explicit need.
      - Inventing functional requirements without tickets, docs, expected tests, or user-provided context.
      - Producing long cosmetic review lists with low operational value.
    output:
      - Short review outcome.
      - Findings ordered by severity.
      - Evidence, impact, and suggested fix for each finding.
      - Recommended validations or test checklist.
      - Limits of the review scope and any unverifiable assumptions.
    escalate_when:
      - The review depends on ticket, documents, attachments, commits, DB, or environment correlation before judgment.
      - The request includes review plus implementation, test execution, documentation, or handoff.
      - Security-sensitive changes require deeper application security review beyond normal code quality review.
    recommended_model_profile:
      default_model: gpt-5.4
      reasoning_effort: medium
```

### Blocco YAML proposto: `test_writer`

```yaml
  - id: test_writer
    purpose: Read-only role for producing targeted test checklists, smoke scenarios, and regression coverage plans for code changes or bugs.
    prioritize:
      - Derive test scenarios from the requested change, diff, bug report, or reviewer findings.
      - Prefer concrete manual and smoke-test steps with preconditions, data, actions, and expected results.
      - Cover happy path, relevant edge cases, failure modes, and regression risks.
      - Keep the checklist copyable into tickets, pull requests, or Mantis notes.
    avoid:
      - Editing application code or test files in the initial checklist-only version.
      - Running destructive commands or assuming access to environments.
      - Introducing new test frameworks or implementation details unless explicitly requested.
      - Producing generic QA advice not tied to the observed change.
    output:
      - Test objective and scope.
      - Preconditions and required data.
      - Manual checklist with steps and expected results.
      - Regression areas to recheck.
      - Automation candidates for future implementation.
      - Open questions or blocking assumptions.
    escalate_when:
      - Expected behavior is unclear or conflicts with available evidence.
      - Useful test design requires multi-source functional reconstruction.
      - The user explicitly asks to implement automated tests rather than produce a checklist.
    recommended_model_profile:
      default_model: gpt-5.4-mini
      reasoning_effort: medium
```

### Nota modello

- `code_reviewer`: `gpt-5.4`, `medium`, perche' richiede giudizio tecnico ma non implementazione.
- `test_writer`: `gpt-5.4-mini`, `medium`, perche' nella v1 produce checklist e non modifica codice.
- Se in futuro `test_writer` dovesse generare test automatici, rivalutare `gpt-5.3-codex` e concedere write access solo ai file test.

---

## 4.2 `scripts/portable-agents-lib.js`

### Aggiornare `ROLE_IDS`

Da:

```js
const ROLE_IDS = ['explorer', 'implementer', 'technical_analyst'];
```

A:

```js
const ROLE_IDS = [
  'explorer',
  'implementer',
  'technical_analyst',
  'code_reviewer',
  'test_writer',
];
```

### Aggiornare `toolsForRole`

Per la v1, mantenere `code_reviewer` e `test_writer` read-only.

Proposta esplicita:

```js
function toolsForRole(roleId) {
  if (roleId === 'implementer') return ['codebase', 'editFiles', 'search'];

  if (roleId === 'code_reviewer') return ['codebase', 'search'];
  if (roleId === 'test_writer') return ['codebase', 'search'];

  return ['codebase', 'search'];
}
```

### Eventuale miglioramento consigliato

Valutare una mappa esplicita per evitare `if` progressivi:

```js
const COPILOT_TOOLS_BY_ROLE = {
  explorer: ['codebase', 'search'],
  implementer: ['codebase', 'editFiles', 'search'],
  technical_analyst: ['codebase', 'search'],
  code_reviewer: ['codebase', 'search'],
  test_writer: ['codebase', 'search'],
};

function toolsForRole(roleId) {
  return COPILOT_TOOLS_BY_ROLE[roleId] || ['codebase', 'search'];
}
```

---

## 4.3 Runtime generati

Non creare manualmente questi file. Devono essere generati:

```text
.codex/agents/code_reviewer.toml
.codex/agents/test_writer.toml
.copilot/agents/code_reviewer.agent.md
.copilot/agents/test_writer.agent.md
```

Comando:

```bash
node scripts/sync-portable-agents.js
```

Verifica:

```bash
node scripts/check-agents-doc.js
```

---

## 4.4 Skill `mcp-code-reviewer`

Non creare una nuova skill code reviewer.

Correzione minima consigliata: aggiungere nel file `skills/mcp-code-reviewer/SKILL.md` una breve sezione `Agent integration`.

### Patch concettuale

Inserire dopo `## Quick Routing`:

```md
## Agent integration

Quando usata tramite `code_reviewer`, questa skill resta read-only:

- non modificare file;
- non preparare patch complete;
- produrre finding, fix suggeriti e test consigliati;
- demandare correzioni a `implementer`;
- demandare checklist test a `test_writer`;
- demandare intake multi-sorgente a `mcp-technical-analyst`;
- demandare flussi review + fix + test + handoff a `mcp-master-orchestrator`.
```

Motivo: chiarisce il rapporto agente/skill senza duplicare workflow e senza aumentare troppo il payload della skill.

---

## 4.5 Skill nuova per test

Non creare ora una skill `mcp-test-writer`.

Motivazione:

- il requisito attuale e' un agente che produce checklist;
- non esiste ancora un template stabile di output Mantis;
- la governance attuale privilegia skill snelle con trigger chiari e references solo quando servono;
- una skill test-specific avrebbe valore solo quando saranno consolidati template e standard.

Backlog consigliato fase 2:

```text
skills/mcp-test-checklist/
├── SKILL.md
├── references/
│   ├── mantis-test-template.md
│   ├── manual-test-checklist.md
│   ├── regression-risk-matrix.md
│   └── automation-candidates.md
└── evals/
    └── evals.json
```

Trigger futuro:

```yaml
name: mcp-test-checklist
description: Produce checklist di test manuali, smoke test, regression plan e template copiabili in Mantis o PR a partire da diff, ticket, bug report, finding di review o analisi tecnica.
```

---

## 5. Aggiornamenti documentazione consigliati

### 5.1 `.codex/agents/README.md` e `.copilot/agents/README.md`

Non e' obbligatorio modificarli. Sono gia' corretti.

Eventuale update minimo: indicare che i ruoli canonici possono crescere oltre i tre iniziali e che i runtime restano derivati.

### 5.2 `docs/agents/local-orchestration-playbook.md`

Aggiornare la sezione routing order.

Da:

```md
1. Use `explorer` for scoped read-first discovery when boundaries are unclear.
2. Use `technical_analyst` for multi-source technical analysis with explicit evidence and trade-offs.
3. Use `implementer` only when acceptance criteria and scope are clear enough for a reviewable patch.
```

A:

```md
1. Use `explorer` for scoped read-first discovery when boundaries are unclear.
2. Use `technical_analyst` for multi-source technical analysis with explicit evidence and trade-offs.
3. Use `implementer` only when acceptance criteria and scope are clear enough for a reviewable patch.
4. Use `code_reviewer` for focused read-only review of a defined snippet, diff, commit, branch, or PR.
5. Use `test_writer` for targeted manual test checklists, smoke scenarios, and regression coverage plans.
```

Aggiungere handoff:

```md
- Implementer -> Code Reviewer
  - after a patch is complete and the scope is reviewable.
- Code Reviewer -> Test Writer
  - when findings include test gaps, regression risks, or manual validation needs.
- Test Writer -> Implementer
  - only when the user explicitly asks to implement automated tests or fix code.
```

---

## 6. Prompt operativo da passare a Codex

Usare questo prompt per implementazione controllata.

```text
Lavora in sola modalita implementativa controllata sul repository corrente.

Obiettivo:
aggiungere due nuovi agenti portabili compatibili con Codex e Copilot Pro+:
- code_reviewer
- test_writer

Vincoli:
- Non editare direttamente .codex/agents/*.toml o .copilot/agents/*.agent.md salvo output generato dagli script.
- La fonte canonica e' docs/agents/canonical-subagents.yaml.
- Mantenere compatibility legacy e pattern esistenti.
- Non creare nuova skill code reviewer.
- Non creare ora una skill test writer.
- test_writer v1 deve essere read-only e produrre checklist di test, non scrivere/eseguire test.
- code_reviewer deve essere read-only.
- Runtime Copilot per entrambi senza editFiles.
- Mantenere AGENTS.md sintetico.

Modifiche richieste:
1. Aggiorna docs/agents/canonical-subagents.yaml aggiungendo code_reviewer e test_writer.
2. Aggiorna scripts/portable-agents-lib.js:
   - estendi ROLE_IDS con code_reviewer e test_writer;
   - assicurati che toolsForRole assegni editFiles solo a implementer.
3. Rigenera runtime:
   node scripts/sync-portable-agents.js
4. Verifica drift:
   node scripts/check-agents-doc.js
5. Aggiorna docs/agents/local-orchestration-playbook.md con routing e handoff dei due nuovi agenti.
6. Aggiorna skills/mcp-code-reviewer/SKILL.md con sezione Agent integration read-only.
7. Se serve, aggiorna docs/skill-governance-matrix.md solo con nota breve sul fatto che mcp-code-reviewer e' skill di policy usata dal nuovo code_reviewer.
8. Non introdurre refactor non richiesti.

Validazioni obbligatorie:
- node scripts/sync-portable-agents.js
- node scripts/check-agents-doc.js
- git diff -- . ':(exclude)node_modules'

Output finale richiesto:
- files changed;
- riepilogo modifiche;
- comandi eseguiti e risultato;
- eventuali rischi residui;
- nota esplicita che test_writer v1 e' checklist-only.
```

---

## 7. Checklist di review post-Codex

Dopo la patch, verificare:

```bash
git diff -- docs/agents/canonical-subagents.yaml
git diff -- scripts/portable-agents-lib.js
git diff -- .codex/agents
git diff -- .copilot/agents
git diff -- skills/mcp-code-reviewer/SKILL.md
git diff -- docs/agents/local-orchestration-playbook.md
```

Controlli funzionali:

| Check | Atteso |
| --- | --- |
| `ROLE_IDS` contiene 5 ruoli | si' |
| `.codex/agents/code_reviewer.toml` generato | si' |
| `.codex/agents/test_writer.toml` generato | si' |
| `.copilot/agents/code_reviewer.agent.md` generato | si' |
| `.copilot/agents/test_writer.agent.md` generato | si' |
| `code_reviewer` non ha edit capability | si' |
| `test_writer` non ha edit capability | si' |
| `implementer` mantiene edit capability | si' |
| `node scripts/check-agents-doc.js` passa | si' |
| `mcp-code-reviewer` non viene duplicata | si' |

---

## 8. Rischi e mitigazioni

| Rischio | Impatto | Mitigazione |
| --- | --- | --- |
| Edit manuale dei runtime | Drift tra canonico, Codex e Copilot | Modificare solo YAML + generatore, poi sync |
| `test_writer` interpretato come agente che scrive test | Possibili modifiche indesiderate | Purpose e avoid devono dire chiaramente checklist-only |
| `code_reviewer` duplica la skill | Bloat e divergenza | Skill resta policy, agente resta worker read-only |
| Tool Copilot troppo permissivi | Modifiche non richieste | `editFiles` solo per `implementer` |
| Skill troppo verbose | Aumento token e trigger meno precisi | Patch minima `Agent integration` |

---

## 9. Raccomandazione finale

Implementare ora:

```text
code_reviewer
test_writer checklist-only
```

Non implementare ora:

```text
mcp-test-writer skill
test_writer con scrittura automatica file test
security_reviewer
pr_author
```

Sequenza consigliata di uso:

```text
explorer
  -> technical_analyst se serve analisi multi-sorgente
  -> implementer per patch piccola
  -> code_reviewer per review read-only
  -> test_writer per checklist manuale/regressione
```

Questa soluzione e' coerente con la governance esistente, preserva compatibilita' Codex/Copilot Pro+, evita bloat di skill e mantiene separati ruoli operativi, policy e workflow locali.