@orchestrator-claude/definitions 3.5.0

package/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/skills/release/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: release
+description: Executa release oficial do Orchestrator via CI/CD. NUNCA faca bump manual de versao - sempre use esta skill.
+allowed-tools: Read, Bash, Grep, Glob
+---
+
+# Release Skill
+
+## REGRA CRITICA
+
+**NUNCA faca bump de versao manualmente!**
+
+- ❌ NUNCA edite `package.json` para alterar versao
+- ❌ NUNCA crie tags git manualmente
+- ❌ NUNCA faca `docker build` + `docker push` manual
+- ✅ SEMPRE use esta skill para releases
+
+Releases manuais causam dessincronizacao entre npm, Docker e package.json.
+
+## Descricao
+
+Esta skill automatiza o processo de release do Orchestrator:
+
+1. Valida pre-requisitos (git clean, branch main)
+2. Calcula nova versao (patch/minor/major)
+3. Atualiza TODOS os arquivos de versao
+4. Cria commit e tag
+5. Push dispara CI/CD (npm publish + Docker build)
+
+## Arquivos Atualizados pelo Script
+
+O script atualiza automaticamente:
+
+- `package.json` (root)
+- `packages/cli/package.json`
+- `packages/mcp-server/package.json`
+- `packages/sdk/package.json`
+- `packages/cli/src/index.ts` (CLI_VERSION constant)
+- `src/infrastructure/templates/base/package.json.hbs` (template versions)
+
+## Invocacao
+
+```
+/release patch     # 1.5.6 -> 1.5.7
+/release minor     # 1.5.6 -> 1.6.0
+/release major     # 1.5.6 -> 2.0.0
+/release 2.0.0     # Versao explicita
+```
+
+## Parametros
+
+| Parametro | Tipo | Obrigatorio | Descricao |
+|-----------|------|-------------|-----------|
+| `version` | string | Sim | patch, minor, major, ou x.y.z |
+| `--dry-run` | flag | Nao | Mostra o que seria feito sem executar |
+| `--force` | flag | Nao | Pula confirmacoes interativas |
+
+## Processo de Execucao
+
+### 1. Pre-verificacao
+
+Antes de executar o script, verifique:
+
+```bash
+# Working tree limpa?
+git status
+
+# Na branch main?
+git branch --show-current
+
+# Ultima tag?
+git describe --tags --abbrev=0
+```
+
+### 2. Dry Run (Recomendado)
+
+Sempre faca dry-run primeiro:
+
+```bash
+./scripts/release.sh --dry-run patch
+```
+
+### 3. Executar Release
+
+```bash
+./scripts/release.sh patch
+```
+
+### 4. Monitorar CI/CD
+
+Apos o push, monitore o pipeline:
+- GitHub Actions: https://github.com/orchestratorAII/orchestrator_claude/actions
+
+## Exemplos de Uso
+
+### Release de Patch (Bug Fix)
+
+```
+User: "Faca release do fix que acabamos de fazer"
+
+Claude:
+1. Verifico pre-requisitos
+2. Executo: ./scripts/release.sh --dry-run patch
+3. Confirmo com usuario
+4. Executo: ./scripts/release.sh patch
+5. Reporto URL do pipeline
+```
+
+### Release de Minor (Nova Feature)
+
+```
+User: "Release da nova feature de dashboard"
+
+Claude:
+1. Verifico CHANGELOG atualizado
+2. Executo: ./scripts/release.sh --dry-run minor
+3. Confirmo com usuario
+4. Executo: ./scripts/release.sh minor
+```
+
+### Release de Major (Breaking Change)
+
+```
+User: "Precisamos fazer release 2.0.0"
+
+Claude:
+1. Verifico CHANGELOG com breaking changes documentados
+2. Executo: ./scripts/release.sh --dry-run 2.0.0
+3. ALERTA sobre breaking changes
+4. Confirmo DUAS vezes com usuario
+5. Executo: ./scripts/release.sh 2.0.0
+```
+
+## Output Esperado
+
+```
+════════════════════════════════════════
+  Orchestrator Release Script
+════════════════════════════════════════
+
+🔍 Validating prerequisites...
+✅ All prerequisites satisfied
+🔍 Validating working tree...
+✅ Working tree is clean
+
+Release Plan:
+  Current version: 1.5.6
+  New version:     1.5.7
+  Git tag:         v1.5.7
+
+✅ Tag 'v1.5.7' is available
+
+Files to update:
+  - package.json (root)
+  - packages/cli/package.json
+  - packages/mcp-server/package.json
+  - packages/sdk/package.json
+  - packages/cli/src/index.ts (CLI_VERSION)
+  - src/infrastructure/templates/base/package.json.hbs (templates)
+
+Continue with release? (y/N): y
+
+📝 Updating versions to 1.5.7...
+✅ All versions updated to 1.5.7
+✅ Version bump committed
+✅ Tag created: v1.5.7
+⬆️  Pushing to remote...
+✅ Pushed main and tag v1.5.7
+
+════════════════════════════════════════
+  Release v1.5.7 initiated!
+════════════════════════════════════════
+
+🚀 CI/CD pipeline will now:
+   - Build and publish Docker image
+   - Publish npm packages
+
+📍 Monitor pipeline at:
+   https://github.com/orchestratorAII/orchestrator_claude/actions
+```
+
+## Troubleshooting
+
+### Working tree not clean
+
+```
+❌ Working tree is not clean
+Please commit or stash your changes
+```
+
+**Solucao:** Commit ou stash as mudancas pendentes antes do release.
+
+### Tag already exists
+
+```
+❌ Tag 'v1.5.7' already exists
+```
+
+**Solucao:** Use uma versao diferente ou delete a tag existente (se foi erro).
+
+### Not on main branch
+
+```
+⚠️ You are on branch 'feature-x', not main
+```
+
+**Solucao:** Merge para main primeiro, depois faca release.
+
+## Integracao com CI/CD
+
+O push da tag dispara automaticamente:
+
+1. **GitHub Actions** (`release.yml`)
+   - Build e teste
+   - Publish npm packages
+   - Build e push Docker image
+
+2. **Versoes Sincronizadas**
+   - npm: @orchestrator-claude/cli
+   - npm: @orchestrator-claude/mcp-server
+   - npm: @orchestrator-claude/sdk
+   - Docker: orchestrator-api:vX.Y.Z
+
+## Notas Importantes
+
+1. **Sempre faca dry-run primeiro** para verificar mudancas
+2. **CHANGELOG deve estar atualizado** antes do release
+3. **CI/CD faz o publish** - nunca publique manualmente
+4. **Uma tag = uma versao** em todos os lugares
+5. **Major releases** requerem confirmacao extra
+
+## Checklist Pre-Release
+
+- [ ] CHANGELOG.md atualizado com todas as mudancas
+- [ ] Todos os testes passando (`npm test`)
+- [ ] Build funcionando (`npm run build`)
+- [ ] Working tree limpa
+- [ ] Na branch main
+- [ ] Dry-run executado e revisado