@orchestrator-claude/cli 3.0.1 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +5 -0
  2. package/dist/index.d.ts +1 -1
  3. package/dist/index.js +1 -1
  4. package/dist/templates/base/CLAUDE.md.hbs +23 -17
  5. package/dist/templates/base/claude/agents/api-extractor.md +5 -25
  6. package/dist/templates/base/claude/agents/business-rule-miner.md +5 -33
  7. package/dist/templates/base/claude/agents/code-archaeologist.md +5 -46
  8. package/dist/templates/base/claude/agents/implementer.md +16 -69
  9. package/dist/templates/base/claude/agents/legacy-discoverer.md +9 -43
  10. package/dist/templates/base/claude/agents/legacy-synthesizer.md +7 -54
  11. package/dist/templates/base/claude/agents/orchestrator.md +4 -4
  12. package/dist/templates/base/claude/agents/planner.md +9 -38
  13. package/dist/templates/base/claude/agents/researcher.md +8 -37
  14. package/dist/templates/base/claude/agents/reviewer.md +15 -54
  15. package/dist/templates/base/claude/agents/schema-extractor.md +5 -26
  16. package/dist/templates/base/claude/agents/specifier.md +9 -38
  17. package/dist/templates/base/claude/agents/task-generator.md +12 -50
  18. package/package.json +3 -2
  19. package/templates/base/CLAUDE.md.hbs +23 -17
  20. package/templates/base/claude/agents/api-extractor.md +5 -25
  21. package/templates/base/claude/agents/business-rule-miner.md +5 -33
  22. package/templates/base/claude/agents/code-archaeologist.md +5 -46
  23. package/templates/base/claude/agents/implementer.md +16 -69
  24. package/templates/base/claude/agents/legacy-discoverer.md +9 -43
  25. package/templates/base/claude/agents/legacy-synthesizer.md +7 -54
  26. package/templates/base/claude/agents/orchestrator.md +4 -4
  27. package/templates/base/claude/agents/planner.md +9 -38
  28. package/templates/base/claude/agents/researcher.md +8 -37
  29. package/templates/base/claude/agents/reviewer.md +15 -54
  30. package/templates/base/claude/agents/schema-extractor.md +5 -26
  31. package/templates/base/claude/agents/specifier.md +9 -38
  32. package/templates/base/claude/agents/task-generator.md +12 -50
@@ -496,7 +496,7 @@ Se ferramenta nao instalada: SKIP (nao e blocker)
496
496
  4. MUST sanitize ALL secrets in outputs (replace with `***REDACTED***`)
497
497
  5. MUST classify findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
498
498
  6. MUST generate all 3 artifacts (analysis-report, dead-code-report, tech-debt)
499
- 7. MUST update orchestrator-index.json after completion
499
+ 7. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
500
500
  8. MUST create checkpoint after analysis complete
501
501
 
502
502
  ### MUST NOT (Forbidden)
@@ -561,50 +561,9 @@ After completing ANALYZE phase:
561
561
  - `.orchestrator/artifacts/legacy-analysis/{workflowId}/dead-code-report.md`
562
562
  - `.orchestrator/artifacts/legacy-analysis/{workflowId}/tech-debt.md`
563
563
 
564
- 2. Update orchestrator-index.json:
565
- ```json
566
- {
567
- "activeWorkflow": {
568
- "currentPhase": "analyze",
569
- "status": "completed"
570
- },
571
- "artifacts": [
572
- {
573
- "id": "art-analyze-001",
574
- "type": "analysis-report",
575
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/analysis-report.md",
576
- "status": "completed",
577
- "createdAt": "{timestamp}",
578
- "phase": "analyze",
579
- "findingsCount": {
580
- "critical": 2,
581
- "high": 8,
582
- "medium": 15,
583
- "low": 23
584
- }
585
- },
586
- {
587
- "id": "art-analyze-002",
588
- "type": "dead-code-report",
589
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/dead-code-report.md",
590
- "status": "completed",
591
- "createdAt": "{timestamp}",
592
- "phase": "analyze",
593
- "deadCodeLOC": 12450,
594
- "percentageOfCodebase": 23
595
- },
596
- {
597
- "id": "art-analyze-003",
598
- "type": "tech-debt",
599
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/tech-debt.md",
600
- "status": "completed",
601
- "createdAt": "{timestamp}",
602
- "phase": "analyze",
603
- "estimatedEffort": "320h"
604
- }
605
- ]
606
- }
607
- ```
564
+ 2. Return structured output to CLI for state update:
565
+
566
+ Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
608
567
 
609
568
  3. Create checkpoint (MANDATORY after ANALYZE):
610
569
  ```
@@ -701,7 +660,7 @@ Before claiming phase complete, MUST provide evidence:
701
660
  - [ ] tech-debt.md generated using template
702
661
  - [ ] All findings classified by severity
703
662
  - [ ] All artifacts saved to correct paths
704
- - [ ] orchestrator-index.json updated
663
+ - [ ] Structured output returned to CLI for state update
705
664
  - [ ] Checkpoint created
706
665
 
707
666
  **FORBIDDEN**: Claiming completion without generating all 3 artifacts.
@@ -303,23 +303,9 @@ npm run build # PASSOU
303
303
 
304
304
  **ATENCAO:** Alem de implementar codigo, voce DEVE manter a governanca do workflow.
305
305
 
306
- ### 1. Atualizar orchestrator-index.json
307
-
308
- Apos **CADA TAREFA** completada, atualize o arquivo `.orchestrator/orchestrator-index.json`:
309
-
310
- ```json
311
- {
312
- "activeWorkflow": {
313
- "currentPhase": "implement",
314
- "status": "in_progress"
315
- },
316
- "implementation": {
317
- "completedTasks": [/* IDs das tasks completas */],
318
- "currentTask": "TASK-XXX",
319
- "progress": "X/Y tasks"
320
- }
321
- }
322
- ```
306
+ ### 1. Return Structured Output for Task Progress
307
+
308
+ After **EACH TASK** completed, return structured output to the CLI with task completion status. The CLI will use MCP tools to update workflow state in PostgreSQL (workflow state managed via PostgreSQL).
323
309
 
324
310
  ### 2. Criar Checkpoints
325
311
 
@@ -334,8 +320,7 @@ Parametros:
334
320
 
335
321
  ### 3. Gerar implementation-report.md
336
322
 
337
- Ao **FINALIZAR TODAS AS TAREFAS**, crie o artefato em:
338
- `.orchestrator/artifacts/implement/implementation-report.md`
323
+ Ao **FINALIZAR TODAS AS TAREFAS**, crie o artefato e persista via MCP tool `artifactStore` (phase: implement).
339
324
 
340
325
  Formato obrigatorio:
341
326
  ```markdown
@@ -381,66 +366,28 @@ Validacao:
381
366
  - [ ] Build sem erros
382
367
  ```
383
368
 
384
- ### 4. Registrar Artefato em orchestrator-index.json
385
-
386
- Adicione o artefato ao array `artifacts`:
387
-
388
- ```json
389
- {
390
- "artifacts": [
391
- {
392
- "id": "art-XXX",
393
- "type": "implementation",
394
- "path": ".orchestrator/artifacts/implement/implementation-report.md",
395
- "status": "completed",
396
- "createdAt": "{timestamp}",
397
- "workflowId": "{workflowId}",
398
- "phase": "implement"
399
- }
400
- ]
401
- }
402
- ```
369
+ ### 4. Artifact Registration (automatic via MCP tools)
403
370
 
404
- ### 5. Atualizar Gates
371
+ **Note**: The artifact will be automatically registered in PostgreSQL by the domain layer when you use `artifactStore`. Sub-agents MUST NOT edit `.orchestrator/orchestrator-index.json` directly.
405
372
 
406
- Ao finalizar, atualize o gate da fase implement:
373
+ ### 5. Return Structured Output for Final State
407
374
 
408
- ```json
409
- {
410
- "gates": {
411
- "implement": {
412
- "passed": true,
413
- "evaluatedAt": "{timestamp}"
414
- }
415
- }
416
- }
417
- ```
418
-
419
- ### 6. Atualizar Status Final
420
-
421
- Ao completar TODAS as tarefas:
422
-
423
- ```json
424
- {
425
- "activeWorkflow": {
426
- "currentPhase": "completed",
427
- "status": "completed",
428
- "completedAt": "{timestamp}"
429
- }
430
- }
431
- ```
375
+ Ao finalizar todas as tarefas, return structured output to the CLI indicating completion. The CLI will use MCP tools to update workflow state in PostgreSQL:
376
+ - Phase gate: implement.passed = true
377
+ - Workflow status: "completed"
378
+ - Completion timestamp
432
379
 
433
380
  ### Checklist de Governanca (OBRIGATORIO)
434
381
 
435
382
  Antes de considerar a fase IMPLEMENT finalizada:
436
383
 
437
384
  - [ ] Todas as tarefas do tasks.md implementadas
438
- - [ ] orchestrator-index.json atualizado com progresso
385
+ - [ ] Structured output returned to CLI for state update
439
386
  - [ ] Checkpoints criados a cada grupo de tarefas
440
- - [ ] implementation-report.md criado
441
- - [ ] Artefato registrado em artifacts[]
442
- - [ ] Gate implement.passed = true
443
- - [ ] Status do workflow = "completed"
387
+ - [ ] implementation-report.md persistido via MCP tool `artifactStore`
388
+ - [ ] Artefato automaticamente registrado em PostgreSQL pelo domain layer
389
+ - [ ] Gate implement.passed = true (updated via CLI)
390
+ - [ ] Status do workflow = "completed" (updated via CLI)
444
391
  - [ ] Testes passando (npm run test)
445
392
  - [ ] Coverage >= 80% (npm run test:coverage)
446
393
  - [ ] Build sem erros (npm run build)
@@ -364,7 +364,7 @@ LOW:
364
364
  4. MUST generate inventory.json validated against schema
365
365
  5. MUST sanitize secrets in all outputs (replace with `***REDACTED***`)
366
366
  6. MUST catalog >= 95% of assets vs reality (if pattern set is good)
367
- 7. MUST update orchestrator-index.json after completion
367
+ 7. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
368
368
  8. MUST classify findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
369
369
 
370
370
  ### MUST NOT (Forbidden)
@@ -424,25 +424,9 @@ After completing DISCOVER phase:
424
424
  1. Save discovery-report.md to:
425
425
  `.orchestrator/artifacts/legacy-analysis/{workflowId}/discovery-report.md`
426
426
 
427
- 2. Update orchestrator-index.json:
428
- ```json
429
- {
430
- "activeWorkflow": {
431
- "currentPhase": "discover",
432
- "status": "completed"
433
- },
434
- "artifacts": [
435
- {
436
- "id": "art-discover-001",
437
- "type": "discovery-report",
438
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/discovery-report.md",
439
- "status": "completed",
440
- "createdAt": "{timestamp}",
441
- "phase": "discover"
442
- }
443
- ]
444
- }
445
- ```
427
+ 2. Return structured output to CLI for state update:
428
+
429
+ Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
446
430
 
447
431
  After completing INVENTORY phase:
448
432
 
@@ -452,27 +436,9 @@ After completing INVENTORY phase:
452
436
  2. Validate against schema:
453
437
  `.orchestrator/templates/legacy/inventory.json.schema`
454
438
 
455
- 3. Update orchestrator-index.json:
456
- ```json
457
- {
458
- "activeWorkflow": {
459
- "currentPhase": "inventory",
460
- "status": "completed"
461
- },
462
- "artifacts": [
463
- {
464
- "id": "art-inventory-001",
465
- "type": "inventory",
466
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/inventory.json",
467
- "status": "completed",
468
- "createdAt": "{timestamp}",
469
- "phase": "inventory",
470
- "validated": true,
471
- "schema": ".orchestrator/templates/legacy/inventory.json.schema"
472
- }
473
- ]
474
- }
475
- ```
439
+ 3. Return structured output to CLI for state update:
440
+
441
+ Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
476
442
 
477
443
  4. Create checkpoint (MANDATORY after INVENTORY):
478
444
  ```
@@ -554,7 +520,7 @@ Before claiming phase complete, MUST provide evidence:
554
520
  - [ ] Red flags classified by severity
555
521
  - [ ] Secrets sanitized (if any found)
556
522
  - [ ] Artifact saved to correct path
557
- - [ ] orchestrator-index.json updated
523
+ - [ ] Structured output returned to CLI for state update
558
524
 
559
525
  ### INVENTORY Phase Checklist
560
526
 
@@ -564,7 +530,7 @@ Before claiming phase complete, MUST provide evidence:
564
530
  - [ ] >= 95% asset coverage vs reality
565
531
  - [ ] JSON is valid and parseable
566
532
  - [ ] Artifact saved to correct path
567
- - [ ] orchestrator-index.json updated
533
+ - [ ] Structured output returned to CLI for state update
568
534
  - [ ] Checkpoint created
569
535
 
570
536
  **FORBIDDEN**: Claiming completion without evidence.
@@ -959,7 +959,7 @@ This analysis followed the **RFC-004 Legacy Analysis Workflow** with 6 phases:
959
959
  5. MUST identify quick wins (high impact, low effort)
960
960
  6. MUST document risks with probability, impact, and mitigations
961
961
  7. MUST generate all 3 final artifacts (migration-roadmap, architecture-proposal, final-report)
962
- 8. MUST update orchestrator-index.json after completion
962
+ 8. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
963
963
  9. MUST create final checkpoint after RECOMMEND phase complete
964
964
 
965
965
  ### MUST NOT (Forbidden)
@@ -1003,48 +1003,9 @@ After completing RECOMMEND phase:
1003
1003
  - `.orchestrator/artifacts/legacy-analysis/{workflowId}/architecture-proposal.md`
1004
1004
  - `.orchestrator/artifacts/legacy-analysis/{workflowId}/final-report.md`
1005
1005
 
1006
- 2. Update orchestrator-index.json:
1007
- ```json
1008
- {
1009
- "activeWorkflow": {
1010
- "currentPhase": "recommend",
1011
- "status": "completed",
1012
- "completedAt": "{timestamp}"
1013
- },
1014
- "artifacts": [
1015
- {
1016
- "id": "art-recommend-001",
1017
- "type": "migration-roadmap",
1018
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/migration-roadmap.md",
1019
- "status": "completed",
1020
- "createdAt": "{timestamp}",
1021
- "phase": "recommend",
1022
- "strategy": "strangler-fig",
1023
- "totalEffort": "1020-1530h",
1024
- "phases": 7
1025
- },
1026
- {
1027
- "id": "art-recommend-002",
1028
- "type": "architecture-proposal",
1029
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/architecture-proposal.md",
1030
- "status": "completed",
1031
- "createdAt": "{timestamp}",
1032
- "phase": "recommend",
1033
- "targetArchitecture": "modular-monolith"
1034
- },
1035
- {
1036
- "id": "art-recommend-003",
1037
- "type": "final-report",
1038
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/final-report.md",
1039
- "status": "completed",
1040
- "createdAt": "{timestamp}",
1041
- "phase": "recommend",
1042
- "totalArtifacts": 12,
1043
- "totalIssues": 48
1044
- }
1045
- ]
1046
- }
1047
- ```
1006
+ 2. Return structured output to CLI for state update:
1007
+
1008
+ Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
1048
1009
 
1049
1010
  3. Create final checkpoint (MANDATORY):
1050
1011
  ```
@@ -1054,15 +1015,7 @@ After completing RECOMMEND phase:
1054
1015
  - description: "Complete RECOMMEND phase - {strategy} strategy, {X} phases, {Y}h effort"
1055
1016
  ```
1056
1017
 
1057
- 4. Mark workflow as completed:
1058
- ```json
1059
- {
1060
- "activeWorkflow": {
1061
- "status": "completed",
1062
- "completedAt": "{timestamp}"
1063
- }
1064
- }
1065
- ```
1018
+ 4. CLI will mark workflow as completed via MCP tools → PostgreSQL
1066
1019
 
1067
1020
  ## Verification Before Completion
1068
1021
 
@@ -1082,9 +1035,9 @@ Before claiming phase complete, MUST provide evidence:
1082
1035
  - [ ] architecture-proposal.md generated
1083
1036
  - [ ] final-report.md generated using template
1084
1037
  - [ ] All 3 artifacts saved to correct paths
1085
- - [ ] orchestrator-index.json updated
1038
+ - [ ] Structured output returned to CLI for state update
1086
1039
  - [ ] Final checkpoint created
1087
- - [ ] Workflow marked as completed
1040
+ - [ ] Workflow marked as completed (via CLI)
1088
1041
 
1089
1042
  **FORBIDDEN**: Claiming completion without reading ALL artifacts or generating ALL 3 final artifacts.
1090
1043
 
@@ -83,12 +83,12 @@ The role: **Choose actions using MCP tools, delegate artifact creation to specia
83
83
  **CRITICAL: Violating these rules breaks checkpoints, metrics, and recovery.**
84
84
 
85
85
  You MUST NOT:
86
- - Use Edit/Write tools on `orchestrator-index.json` (MCP tools manage state)
86
+ - Use Edit/Write tools on `.orchestrator/orchestrator-index.json` (workflow state managed via PostgreSQL)
87
87
  - Use Edit/Write tools to create artifacts (subagents create them)
88
88
  - Spawn subagents internally via Task tool (use executeAction instead)
89
89
  - Execute multiple phases in a single invocation
90
90
  - Skip MCP tools for "efficiency"
91
- - Update `agentInvocations` or `checkpoints` arrays manually
91
+ - Attempt to manually update workflow state (MCP tools → REST API → PostgreSQL)
92
92
 
93
93
  **WHY:** The deterministic layer (MCP tools) triggers:
94
94
  - Auto-checkpoints after artifact approval
@@ -111,7 +111,7 @@ getContext() → executeAction("advance_to_specify") → RETURN
111
111
  getContext() → executeAction("advance_to_specify") → Task(specifier) ← WRONG!
112
112
  ```
113
113
 
114
- The CLI reads `pendingAction` from orchestrator-index.json and invokes the appropriate agent. Your job is to SET the pendingAction via executeAction(), not to execute it yourself.
114
+ The CLI reads `pendingAction` via MCP tools (PostgreSQL) and invokes the appropriate agent. Your job is to SET the pendingAction via executeAction(), not to execute it yourself.
115
115
 
116
116
  ## Example Flow
117
117
 
@@ -124,7 +124,7 @@ User: "Create OAuth2 API"
124
124
  5. **RETURN** ← You stop here! CLI handles the rest.
125
125
 
126
126
  **What happens next (NOT your responsibility):**
127
- - CLI reads pendingAction from orchestrator-index.json
127
+ - CLI reads pendingAction via MCP tools (PostgreSQL)
128
128
  - CLI invokes specifier agent
129
129
  - Specifier creates spec.md
130
130
  - CLI invokes orchestrator again for next phase
@@ -275,29 +275,11 @@ O artefato deve:
275
275
 
276
276
  **ATENCAO:** Alem de gerar o artefato, voce DEVE manter a governanca do workflow.
277
277
 
278
- ### 1. Registrar Artefato em orchestrator-index.json
279
-
280
- Apos criar o `plan.md`, atualize `.orchestrator/orchestrator-index.json`:
281
-
282
- ```json
283
- {
284
- "activeWorkflow": {
285
- "currentPhase": "plan",
286
- "status": "in_progress"
287
- },
288
- "artifacts": [
289
- {
290
- "id": "art-XXX",
291
- "type": "plan",
292
- "path": ".orchestrator/artifacts/plan/plan.md",
293
- "status": "draft",
294
- "createdAt": "{timestamp}",
295
- "workflowId": "{workflowId}",
296
- "phase": "plan"
297
- }
298
- ]
299
- }
300
- ```
278
+ ### 1. Artifact Registration (automatic via MCP tools)
279
+
280
+ Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. Sub-agents MUST NOT edit `.orchestrator/orchestrator-index.json` directly.
281
+
282
+ The CLI will use MCP tools to update workflow state in PostgreSQL after artifact storage.
301
283
 
302
284
  ### 2. Validar Artefato
303
285
 
@@ -321,28 +303,17 @@ Parametros:
321
303
  - description: "Complete PLAN phase - [nome da feature]"
322
304
  ```
323
305
 
324
- ### 4. Atualizar Gate
306
+ ### 4. Return Structured Output
325
307
 
326
- Atualize o gate da fase plan:
327
-
328
- ```json
329
- {
330
- "gates": {
331
- "plan": {
332
- "passed": true,
333
- "evaluatedAt": "{timestamp}"
334
- }
335
- }
336
- }
337
- ```
308
+ Return structured output to the CLI for state update. The CLI will use MCP tools to update the phase gate in PostgreSQL.
338
309
 
339
310
  ### Checklist de Governanca (OBRIGATORIO)
340
311
 
341
312
  Antes de considerar a fase PLAN finalizada:
342
313
 
343
314
  - [ ] plan.md criado em .orchestrator/artifacts/plan/
344
- - [ ] Artefato registrado em orchestrator-index.json
315
+ - [ ] Structured output returned to CLI for state update
345
316
  - [ ] Validacao executada via artifact-validator
346
317
  - [ ] Status do artefato = "validated"
347
318
  - [ ] Checkpoint criado via MCP
348
- - [ ] Gate plan.passed = true
319
+ - [ ] Gate plan.passed = true (updated via CLI)
@@ -301,29 +301,11 @@ Limites de uso:
301
301
 
302
302
  **ATENCAO:** Alem de gerar o artefato, voce DEVE manter a governanca do workflow.
303
303
 
304
- ### 1. Registrar Artefato em orchestrator-index.json
305
-
306
- Apos criar o `research-context.md`, atualize `.orchestrator/orchestrator-index.json`:
307
-
308
- ```json
309
- {
310
- "activeWorkflow": {
311
- "currentPhase": "research",
312
- "status": "in_progress"
313
- },
314
- "artifacts": [
315
- {
316
- "id": "art-XXX",
317
- "type": "research",
318
- "path": ".orchestrator/artifacts/research/research-context.md",
319
- "status": "completed",
320
- "createdAt": "{timestamp}",
321
- "workflowId": "{workflowId}",
322
- "phase": "research"
323
- }
324
- ]
325
- }
326
- ```
304
+ ### 1. Artifact Registration (automatic via MCP tools)
305
+
306
+ Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. Sub-agents MUST NOT edit `.orchestrator/orchestrator-index.json` directly.
307
+
308
+ The CLI will use MCP tools to update workflow state in PostgreSQL after artifact storage.
327
309
 
328
310
  ### 2. Criar Checkpoint (se pesquisa for significativa)
329
311
 
@@ -336,27 +318,16 @@ Parametros:
336
318
  - description: "Complete RESEARCH phase - [topico pesquisado]"
337
319
  ```
338
320
 
339
- ### 3. Atualizar Gate (se fase RESEARCH for usada)
321
+ ### 3. Return Structured Output
340
322
 
341
- Se o workflow incluir fase RESEARCH explicita:
342
-
343
- ```json
344
- {
345
- "gates": {
346
- "research": {
347
- "passed": true,
348
- "evaluatedAt": "{timestamp}"
349
- }
350
- }
351
- }
352
- ```
323
+ Return structured output to the CLI for state update. The CLI will use MCP tools to update the phase gate in PostgreSQL if RESEARCH is an explicit workflow phase.
353
324
 
354
325
  ### Checklist de Governanca (OBRIGATORIO)
355
326
 
356
327
  Antes de considerar a pesquisa finalizada:
357
328
 
358
329
  - [ ] research-context.md criado em .orchestrator/artifacts/research/
359
- - [ ] Artefato registrado em orchestrator-index.json
330
+ - [ ] Structured output returned to CLI for state update
360
331
  - [ ] Findings sao acionaveis e relevantes
361
332
  - [ ] Sources documentadas
362
333
  - [ ] Cache information registrada
@@ -361,62 +361,20 @@ Formato:
361
361
  }
362
362
  ```
363
363
 
364
- ### 2. Registrar em orchestrator-index.json
364
+ ### 2. Artifact Registration (automatic via MCP tools)
365
365
 
366
- Apos criar validation report, registre no index:
366
+ Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. Sub-agents MUST NOT edit `.orchestrator/orchestrator-index.json` directly.
367
367
 
368
- ```json
369
- {
370
- "artifacts": [
371
- {
372
- "id": "val-XXX",
373
- "type": "validation_report",
374
- "path": ".orchestrator/artifacts/{phase}/validation-report.json",
375
- "status": "completed",
376
- "createdAt": "{timestamp}",
377
- "workflowId": "{workflowId}",
378
- "phase": "{phase}"
379
- }
380
- ]
381
- }
382
- ```
383
-
384
- ### 3. Atualizar Status do Artefato Revisado
385
-
386
- Se aprovado, atualize o status do artefato original:
387
-
388
- ```json
389
- {
390
- "artifacts": [
391
- {
392
- "id": "art-XXX",
393
- "status": "validated", // era "draft"
394
- "validatedAt": "{timestamp}",
395
- "validationReport": "val-XXX"
396
- }
397
- ]
398
- }
399
- ```
368
+ ### 3. Return Structured Output for Validation Status
400
369
 
401
- ### 4. Avaliar Gate da Fase
370
+ Return structured output to the CLI indicating the validation result. The CLI will use MCP tools to:
371
+ - Update artifact status to "validated" in PostgreSQL
372
+ - Link validation report to original artifact
373
+ - Update phase gate if applicable
402
374
 
403
- Se revisao for a ultima da fase, avalie o gate:
375
+ ### 4. Comunicar Resultado ao Orchestrator
404
376
 
405
- ```json
406
- {
407
- "gates": {
408
- "{phase}": {
409
- "passed": true, // ou false se rejeitado
410
- "evaluatedAt": "{timestamp}",
411
- "evaluatedBy": "reviewer-agent"
412
- }
413
- }
414
- }
415
- ```
416
-
417
- ### 5. Comunicar Resultado ao Orchestrator
418
-
419
- Ao finalizar revisao, retorne status estruturado para o orchestrator:
377
+ Ao finalizar revisao, retorne status estruturado para o CLI:
420
378
 
421
379
  ```markdown
422
380
  ## Review Result
@@ -431,14 +389,17 @@ Ao finalizar revisao, retorne status estruturado para o orchestrator:
431
389
  - Se REJECTED: Escalar para usuario
432
390
  ```
433
391
 
392
+ The CLI will handle updating PostgreSQL via MCP tools.
393
+
434
394
  ### Checklist de Governanca (OBRIGATORIO)
435
395
 
436
396
  Antes de considerar a revisao finalizada:
437
397
 
438
398
  - [ ] Todos os criterios de qualidade verificados
439
- - [ ] Validation report criado e registrado
440
- - [ ] Status do artefato atualizado (validated/rejected)
441
- - [ ] Gate da fase avaliado
399
+ - [ ] Validation report criado
400
+ - [ ] Structured output returned to CLI for state update
401
+ - [ ] Status do artefato will be updated via CLI (validated/rejected)
402
+ - [ ] Gate da fase will be evaluated via CLI
442
403
  - [ ] Resultado comunicado ao orchestrator
443
404
  - [ ] Condicoes para aprovacao documentadas (se houver)
444
405
  ```
@@ -584,7 +584,7 @@ $posts = Post::with('user')->get();
584
584
  4. MUST document column types and nullability
585
585
  5. MUST generate database-schema.md using template
586
586
  6. MUST include table catalog with all columns
587
- 7. MUST update orchestrator-index.json after completion
587
+ 7. MUST return structured output to CLI for state update (workflow state managed via PostgreSQL)
588
588
  8. MUST create checkpoint after MAP phase fully complete (with api-extractor)
589
589
 
590
590
  ### MUST NOT (Forbidden)
@@ -650,30 +650,9 @@ After completing MAP phase (Database portion):
650
650
 
651
651
  2. Validate Mermaid syntax (paste in Mermaid Live Editor or use CLI if available)
652
652
 
653
- 3. Update orchestrator-index.json:
654
- ```json
655
- {
656
- "activeWorkflow": {
657
- "currentPhase": "map",
658
- "status": "completed"
659
- },
660
- "artifacts": [
661
- {
662
- "id": "art-map-002",
663
- "type": "database-schema",
664
- "path": ".orchestrator/artifacts/legacy-analysis/{workflowId}/database-schema.md",
665
- "status": "completed",
666
- "createdAt": "{timestamp}",
667
- "phase": "map",
668
- "format": "markdown-mermaid",
669
- "validated": true,
670
- "tableCount": 15,
671
- "relationshipCount": 22,
672
- "accuracyPercent": 95
673
- }
674
- ]
675
- }
676
- ```
653
+ 3. Return structured output to CLI for state update:
654
+
655
+ Artifacts are automatically registered in PostgreSQL when stored via MCP `artifactStore` tool. The CLI will use MCP tools to update workflow state after artifact storage.
677
656
 
678
657
  4. Create checkpoint (MANDATORY after MAP phase complete):
679
658
  ```
@@ -753,7 +732,7 @@ Before claiming phase complete, MUST provide evidence:
753
732
  - [ ] Junction tables identified for many-to-many
754
733
  - [ ] Query patterns analyzed (if applicable)
755
734
  - [ ] Artifact saved to correct path
756
- - [ ] orchestrator-index.json updated
735
+ - [ ] Structured output returned to CLI for state update
757
736
  - [ ] Checkpoint created (after MAP phase complete)
758
737
 
759
738
  **FORBIDDEN**: Claiming completion without valid Mermaid ER diagram.