@orchestrator-claude/cli 1.4.0

package/templates/base/claude/skills/phase-gate-evaluator/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: phase-gate-evaluator
+description: Avalia gates entre fases do workflow para verificar se criterios de qualidade foram atendidos. Use antes de avancar fase ou para diagnosticar bloqueios.
+allowed-tools: Read, Grep, Glob
+---
+
+# Phase Gate Evaluator Skill
+
+## Descricao
+
+Esta skill avalia se um workflow pode avancar de uma fase para a proxima,
+verificando criterios de qualidade (gates) definidos para cada transicao.
+
+## Quando Usar
+
+Use esta skill quando:
+- Apos validacao bem-sucedida de um artefato
+- Para verificar se pode avancar para proxima fase
+- Para diagnosticar por que um gate nao passou
+- Para listar criterios pendentes de uma fase
+
+## Invocacao
+
+Exemplos de como invocar esta skill:
+
+```
+"Avalie o gate da fase specify para o workflow wf-123"
+
+"Verifique se posso avancar de plan para tasks"
+
+"Liste os criterios pendentes do gate de implementacao"
+
+"Por que o gate da fase tasks nao passou?"
+```
+
+## Parametros
+
+| Parametro | Tipo | Obrigatorio | Descricao |
+|-----------|------|-------------|-----------|
+| `workflow_id` | string | Sim | ID do workflow sendo avaliado |
+| `phase` | enum | Sim | research, specify, plan, tasks, implement |
+| `evaluation_mode` | enum | Nao | evaluate (default), diagnose, list_criteria |
+
+### Valores de evaluation_mode
+
+- **evaluate**: Avalia gate e retorna passed/failed
+- **diagnose**: Explica em detalhes por que gate falhou
+- **list_criteria**: Lista todos os criterios do gate sem avaliar
+
+## Gates por Fase
+
+### RESEARCH → SPECIFY
+```yaml
+gate_id: research-complete
+criteria:
+  - research_context_exists: true
+  - research_context_validated: true
+  - minimum_sources: 3
+  - has_patterns_identified: true
+  - has_risks_documented: true
+```
+
+### SPECIFY → PLAN
+```yaml
+gate_id: specification-complete
+criteria:
+  - spec_artifact_exists: true
+  - spec_artifact_validated: true
+  - all_rf_have_acceptance_criteria: true
+  - all_rnf_have_metrics: true
+  - scope_clearly_defined: true
+  - dependencies_identified: true
+  - risks_documented: true
+```
+
+### PLAN → TASKS
+```yaml
+gate_id: plan-complete
+criteria:
+  - plan_artifact_exists: true
+  - plan_artifact_validated: true
+  - architecture_decisions_documented: true
+  - phases_defined: true
+  - deliverables_per_phase: true
+  - technical_risks_mitigated: true
+```
+
+### TASKS → IMPLEMENT
+```yaml
+gate_id: tasks-complete
+criteria:
+  - tasks_artifact_exists: true
+  - tasks_artifact_validated: true
+  - all_tasks_have_acceptance_criteria: true
+  - dependencies_form_dag: true
+  - no_orphan_tasks: true
+  - estimates_provided: true
+```
+
+### IMPLEMENT → DONE
+```yaml
+gate_id: implementation-complete
+criteria:
+  - all_tasks_completed: true
+  - all_tests_passing: true
+  - code_review_approved: true
+  - documentation_updated: true
+  - checkpoint_created: true
+```
+
+## Output
+
+### Modo: evaluate
+```json
+{
+  "gateId": "specification-complete",
+  "workflowId": "wf-123",
+  "phase": "specify",
+  "nextPhase": "plan",
+  "evaluatedAt": "2025-12-09T10:30:00Z",
+
+  "passed": false,
+
+  "criteria": [
+    {
+      "id": "spec_artifact_exists",
+      "description": "Artefato de especificacao existe",
+      "passed": true,
+      "evidence": ".orchestrator/artifacts/specify/spec.md"
+    },
+    {
+      "id": "spec_artifact_validated",
+      "description": "Artefato validado sem erros",
+      "passed": true,
+      "evidence": "Validation passed at 2025-12-09T10:25:00Z"
+    },
+    {
+      "id": "all_rf_have_acceptance_criteria",
+      "description": "Todos RFs tem criterios de aceite",
+      "passed": false,
+      "evidence": "RF-003 e RF-005 sem criterios de aceite",
+      "blockers": ["RF-003", "RF-005"]
+    }
+  ],
+
+  "summary": {
+    "totalCriteria": 7,
+    "passedCriteria": 5,
+    "failedCriteria": 2,
+    "passRate": 71
+  },
+
+  "recommendation": "Adicione criterios de aceite para RF-003 e RF-005 antes de avancar"
+}
+```
+
+### Modo: diagnose
+```json
+{
+  "gateId": "specification-complete",
+  "diagnosis": {
+    "failedCriteria": [
+      {
+        "id": "all_rf_have_acceptance_criteria",
+        "reason": "2 requisitos funcionais nao tem criterios de aceite verificaveis",
+        "affectedItems": ["RF-003", "RF-005"],
+        "howToFix": "Para cada RF, adicione uma secao 'Criterio de Aceite' com items verificaveis",
+        "example": "RF-003:\n  Criterio de Aceite:\n  - [ ] Usuario consegue fazer login em < 3 segundos\n  - [ ] Mensagem de erro clara se credenciais invalidas"
+      }
+    ],
+    "rootCause": "Especificacao incompleta - requisitos sem verificabilidade",
+    "estimatedEffort": "30 minutos para adicionar criterios faltantes",
+    "priority": "Alta - bloqueia avanco do workflow"
+  }
+}
+```
+
+### Modo: list_criteria
+```json
+{
+  "gateId": "specification-complete",
+  "phase": "specify",
+  "criteria": [
+    {
+      "id": "spec_artifact_exists",
+      "description": "Artefato de especificacao existe em .orchestrator/artifacts/specify/",
+      "type": "existence",
+      "required": true
+    },
+    {
+      "id": "spec_artifact_validated",
+      "description": "Artefato passou validacao completa (schema + business)",
+      "type": "validation",
+      "required": true
+    },
+    {
+      "id": "all_rf_have_acceptance_criteria",
+      "description": "Cada requisito funcional deve ter pelo menos 1 criterio de aceite",
+      "type": "completeness",
+      "required": true
+    },
+    {
+      "id": "all_rnf_have_metrics",
+      "description": "Cada requisito nao-funcional deve ter metrica e target",
+      "type": "completeness",
+      "required": true
+    },
+    {
+      "id": "scope_clearly_defined",
+      "description": "In scope e out of scope claramente definidos",
+      "type": "quality",
+      "required": true
+    },
+    {
+      "id": "dependencies_identified",
+      "description": "Dependencias externas e internas documentadas",
+      "type": "completeness",
+      "required": true
+    },
+    {
+      "id": "risks_documented",
+      "description": "Riscos identificados com mitigacoes",
+      "type": "quality",
+      "required": false
+    }
+  ]
+}
+```
+
+## Integracao com TypeScript
+
+Esta skill invoca o handler TypeScript:
+
+```typescript
+// src/presentation/skills/PhaseGateSkillHandler.ts
+
+export class PhaseGateSkillHandler {
+  async handle(params: GateParams): Promise<GateResult> {
+    // 1. Carrega definicao do gate para a fase
+    // 2. Carrega estado do workflow
+    // 3. Avalia cada criterio
+    // 4. Agrega resultados
+    // 5. Retorna GateResult
+  }
+}
+```
+
+## Comportamento Especial
+
+### Gate Parcial
+Se alguns criterios passam mas outros nao:
+- Retorna `passed: false`
+- Lista criterios que passaram como evidencia de progresso
+- Fornece guidance especifico para resolver blockers
+
+### Gate com Warnings
+Se gate passa mas tem warnings:
+- Retorna `passed: true`
+- Inclui warnings no resultado
+- Recomenda enderecamento antes de continuar
+
+### Re-avaliacao
+Apos correcao de problemas:
+- Pode re-avaliar mesmo gate
+- Historico de avaliacoes mantido
+- Mostra delta desde ultima avaliacao
+
+## Notas Importantes
+
+1. Gate **NAO** avanca fase automaticamente - apenas avalia
+2. Use MCP `advancePhase` apos gate passar
+3. Gates podem ser customizados por projeto via CONSTITUTION
+4. Criterios `required: false` geram warnings, nao bloqueiam
+5. Evidencias sao importantes para auditoria e rastreabilidade

package/templates/base/claude/skills/workflow-status/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: workflow-status
+description: Consulta status detalhado do workflow atual incluindo fase, artefatos, gates e proximos passos. Use para verificar progresso ou diagnosticar problemas.
+allowed-tools: Read, Grep, Glob
+---
+
+# Workflow Status Skill
+
+## Descricao
+
+Esta skill fornece informacoes detalhadas sobre o status atual do workflow de orquestracao, incluindo fase atual, artefatos gerados, gates avaliados e proximos passos.
+
+## Quando Usar
+
+Use esta skill quando:
+- Precisar saber o status atual do workflow
+- Verificar quais artefatos foram gerados
+- Consultar progresso por fase
+- Identificar proximos passos
+- Verificar checkpoints disponiveis
+- Diagnosticar problemas no fluxo
+
+## Invocacao
+
+Exemplos de como invocar esta skill:
+
+```
+"Qual o status atual do workflow?"
+
+"Mostre o progresso da implementacao"
+
+"Quais artefatos ja foram gerados?"
+
+"Em qual fase estamos?"
+
+"Quais sao os proximos passos?"
+
+"Liste os checkpoints disponiveis"
+```
+
+## Parametros
+
+| Parametro | Tipo | Obrigatorio | Descricao |
+|-----------|------|-------------|-----------|
+| `workflowId` | string | Nao | ID do workflow (usa atual se omitido) |
+| `detail_level` | enum | Nao | summary, standard, detailed |
+| `include_artifacts` | boolean | Nao | Incluir lista de artefatos |
+| `include_checkpoints` | boolean | Nao | Incluir lista de checkpoints |
+| `include_gates` | boolean | Nao | Incluir status dos gates |
+
+### Valores de detail_level
+
+- **summary**: Apenas fase atual e status geral
+- **standard** (default): Fase, status, ultimos artefatos, proximo passo
+- **detailed**: Tudo incluindo historico completo
+
+## Output
+
+A skill retorna informacoes estruturadas:
+
+```json
+{
+  "success": true,
+  "workflow": {
+    "id": "wf-123",
+    "type": "feature_development",
+    "feature": "OAuth2 Authentication",
+    "status": "in_progress",
+    "startedAt": "2025-12-09T10:00:00Z",
+    "updatedAt": "2025-12-09T14:30:00Z"
+  },
+
+  "currentPhase": {
+    "name": "implement",
+    "status": "in_progress",
+    "startedAt": "2025-12-09T14:00:00Z",
+    "progress": {
+      "totalTasks": 10,
+      "completedTasks": 6,
+      "percentage": 60
+    }
+  },
+
+  "phases": [
+    {
+      "name": "research",
+      "status": "completed",
+      "duration": "45m",
+      "artifacts": ["research-context.md"]
+    },
+    {
+      "name": "specify",
+      "status": "completed",
+      "duration": "1h",
+      "artifacts": ["spec.md"]
+    },
+    {
+      "name": "plan",
+      "status": "completed",
+      "duration": "1h 30m",
+      "artifacts": ["plan.md"]
+    },
+    {
+      "name": "tasks",
+      "status": "completed",
+      "duration": "45m",
+      "artifacts": ["tasks.md"]
+    },
+    {
+      "name": "implement",
+      "status": "in_progress",
+      "duration": "2h (ongoing)",
+      "artifacts": ["impl-001.md", "impl-002.md"]
+    }
+  ],
+
+  "artifacts": [
+    {
+      "id": "art-001",
+      "type": "research",
+      "path": ".orchestrator/artifacts/research/research-context.md",
+      "status": "validated",
+      "createdAt": "2025-12-09T10:45:00Z"
+    },
+    {
+      "id": "art-002",
+      "type": "specification",
+      "path": ".orchestrator/artifacts/specify/spec.md",
+      "status": "validated",
+      "createdAt": "2025-12-09T11:45:00Z"
+    }
+  ],
+
+  "gates": {
+    "research": { "passed": true, "evaluatedAt": "2025-12-09T10:50:00Z" },
+    "specify": { "passed": true, "evaluatedAt": "2025-12-09T11:50:00Z" },
+    "plan": { "passed": true, "evaluatedAt": "2025-12-09T13:20:00Z" },
+    "tasks": { "passed": true, "evaluatedAt": "2025-12-09T14:00:00Z" },
+    "implement": { "passed": false, "pending": true }
+  },
+
+  "checkpoints": [
+    {
+      "id": "chk-001",
+      "phase": "specify",
+      "message": "[orchestrator] specify: specification validated",
+      "gitRef": "abc123",
+      "createdAt": "2025-12-09T11:50:00Z"
+    },
+    {
+      "id": "chk-002",
+      "phase": "plan",
+      "message": "[orchestrator] plan: technical plan approved",
+      "gitRef": "def456",
+      "createdAt": "2025-12-09T13:20:00Z"
+    }
+  ],
+
+  "nextSteps": [
+    "Completar TASK-007: Implementar middleware de autenticacao",
+    "Executar testes de integracao",
+    "Avaliar gate de implement para concluir workflow"
+  ],
+
+  "metrics": {
+    "totalDuration": "4h 30m",
+    "estimatedRemaining": "2h",
+    "artifactsGenerated": 6,
+    "gatesPassed": 4,
+    "checkpointsCreated": 4
+  }
+}
+```
+
+## Formato de Output para Usuario
+
+Quando invocada, a skill formata output amigavel:
+
+```markdown
+## Status do Workflow
+
+**ID**: wf-123
+**Tipo**: feature_development
+**Feature**: OAuth2 Authentication
+**Status**: 🟡 Em Progresso
+
+### Fase Atual: IMPLEMENT
+
+```
+[████████░░░░░░░░░░░░] 60% (6/10 tasks)
+```
+
+### Progresso por Fase
+
+| Fase | Status | Duracao | Artefatos |
+|------|--------|---------|-----------|
+| research | ✅ Completo | 45m | 1 |
+| specify | ✅ Completo | 1h | 1 |
+| plan | ✅ Completo | 1h 30m | 1 |
+| tasks | ✅ Completo | 45m | 1 |
+| implement | 🟡 Em Progresso | 2h | 2 |
+
+### Gates
+
+- [x] research-complete
+- [x] specification-complete
+- [x] plan-complete
+- [x] tasks-complete
+- [ ] implementation-complete (pendente)
+
+### Proximos Passos
+
+1. Completar TASK-007: Implementar middleware de autenticacao
+2. Executar testes de integracao
+3. Avaliar gate de implement para concluir workflow
+
+### Metricas
+
+- **Tempo Total**: 4h 30m
+- **Estimativa Restante**: 2h
+- **Artefatos**: 6
+- **Checkpoints**: 4
+```
+
+## Integracao com TypeScript
+
+Esta skill invoca o handler TypeScript:
+
+```typescript
+// src/presentation/skills/WorkflowStatusSkill.ts
+
+export class WorkflowStatusSkillHandler extends SkillHandler {
+  name = 'workflow-status';
+  description = 'Consulta status detalhado do workflow';
+
+  async execute(input: WorkflowStatusInput): Promise<SkillResult> {
+    // 1. Obtem workflow atual ou por ID
+    // 2. Carrega orchestrator-index.json
+    // 3. Coleta informacoes de fases
+    // 4. Coleta status de gates
+    // 5. Lista artefatos e checkpoints
+    // 6. Calcula metricas
+    // 7. Formata output
+  }
+}
+```
+
+## Casos de Uso
+
+### Verificar Status Rapido
+```
+User: "Status do workflow?"
+Skill: workflow-status com detail_level=summary
+Output: Fase atual, status, progresso percentual
+```
+
+### Relatorio Detalhado
+```
+User: "Me de um relatorio completo do progresso"
+Skill: workflow-status com detail_level=detailed, todos includes=true
+Output: Relatorio completo com historico
+```
+
+### Verificar Artefatos
+```
+User: "Quais artefatos ja temos?"
+Skill: workflow-status com include_artifacts=true
+Output: Lista de artefatos com status e paths
+```
+
+### Diagnostico de Problema
+```
+User: "Por que o workflow esta travado?"
+Skill: workflow-status com include_gates=true
+Output: Status detalhado mostrando gate pendente
+```
+
+## Comportamento em Casos Especiais
+
+### Nenhum Workflow Ativo
+```json
+{
+  "success": false,
+  "error": {
+    "code": "NO_ACTIVE_WORKFLOW",
+    "message": "Nenhum workflow ativo encontrado",
+    "suggestion": "Use 'orchestrate start' para iniciar um novo workflow"
+  }
+}
+```
+
+### Workflow Nao Encontrado
+```json
+{
+  "success": false,
+  "error": {
+    "code": "WORKFLOW_NOT_FOUND",
+    "message": "Workflow 'wf-xyz' nao encontrado",
+    "suggestion": "Verifique o ID ou use sem parametro para workflow atual"
+  }
+}
+```
+
+### Index Corrompido
+```json
+{
+  "success": false,
+  "error": {
+    "code": "INDEX_CORRUPTED",
+    "message": "orchestrator-index.json esta corrompido ou invalido",
+    "suggestion": "Execute 'orchestrator config validate' para diagnosticar"
+  }
+}
+```
+
+## Notas Importantes
+
+1. Esta skill e **read-only** - apenas consulta, nao modifica estado
+2. Dados vem de `orchestrator-index.json` e artefatos
+3. Metricas de tempo sao calculadas a partir de timestamps
+4. Progresso de tarefas requer leitura de tasks.md
+5. Cache de 30 segundos para evitar leituras repetidas

package/templates/base/docker-compose.yml.hbs

@@ -0,0 +1,20 @@
+version: '3.8'
+
+services:
+  orchestrator-api:
+    image: orchestrator/api:{{orchestratorVersion}}
+    container_name: {{projectName}}-orchestrator-api
+    ports:
+      - "3000:3000"
+    volumes:
+      - .:/app/project:rw
+    environment:
+      - ORCHESTRATOR_ROOT=/app/project
+      - NODE_ENV=development
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:3000/api/v1/health"]
+      interval: 30s
+      timeout: 3s
+      start_period: 10s
+      retries: 3
+    restart: unless-stopped

package/templates/base/mcp.json.hbs

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://modelcontextprotocol.io/schemas/mcp-config.json",
+  "mcpServers": {
+    "orchestrator-tools": {
+      "command": "node",
+      "args": [
+        "node_modules/@orchestrator/core/dist/infrastructure/mcp/bin/orchestrator-server.js"
+      ],
+      "env": {
+        "ORCHESTRATOR_ROOT": ".orchestrator",
+        "NODE_ENV": "production",
+        "MCP_DEBUG": "false"
+      }
+    },
+    "knowledge-base": {
+      "command": "node",
+      "args": [
+        "node_modules/@orchestrator/core/dist/infrastructure/mcp/bin/knowledge-base-server.js"
+      ],
+      "env": {
+        "ORCHESTRATOR_ROOT": ".orchestrator",
+        "CACHE_ENABLED": "true",
+        "MCP_DEBUG": "false"
+      }
+    },
+    "perplexity": {
+      "command": "node",
+      "args": [
+        "node_modules/@orchestrator/core/dist/infrastructure/mcp/bin/perplexity-server.js"
+      ],
+      "env": {
+        "CACHE_TTL_HOURS": "24",
+        "MCP_DEBUG": "false"
+      }
+    }
+  }
+}

package/templates/base/orchestrator-index.json.hbs

@@ -0,0 +1,37 @@
+{
+  "project": {
+    "name": "{{projectName}}",
+    "version": "1.0.0",
+    "created_at": "{{currentDate}}",
+    "orchestrator_version": "1.4.0"
+  },
+  "activeWorkflow": null,
+  "workflows": [],
+  "artifacts": [],
+  "checkpoints": [],
+  "taskToolInvocations": [],
+  "agentInvocations": [],
+  "gates": {},
+  "statistics": {
+    "totalWorkflows": 0,
+    "completedWorkflows": 0,
+    "failedWorkflows": 0,
+    "totalArtifacts": 0,
+    "totalCheckpoints": 0,
+    "totalInvocations": 0,
+    "lastActivity": "{{currentDate}}"
+  },
+  "metadata": {
+    "initialized_with": "orchestrator-cli",
+    "schema_version": "1.3"
+  },
+  "defaultHooks": {
+    "postImplement": {
+      "agent": "docs-guardian",
+      "mode": "auto",
+      "blocking": false,
+      "enabled": true,
+      "scope": "all"
+    }
+  }
+}