@orchestrator-claude/cli 1.4.0

package/templates/base/claude/hooks/track-agent-invocation.sh

@@ -0,0 +1,230 @@
+#!/bin/bash
+# Track Agent Invocation Hook
+# Registers agent invocations in orchestrator-index.json
+#
+# Usage (called by Claude Code hooks):
+#   track-agent-invocation.sh start    (reads stdin JSON)
+#   track-agent-invocation.sh complete (reads stdin JSON)
+#
+# Claude Code passes JSON via stdin with structure:
+#   { "tool_name": "Task", "tool_input": { "subagent_type": "...", ... } }
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+INDEX_FILE="$PROJECT_ROOT/.orchestrator/orchestrator-index.json"
+STATE_DIR="$PROJECT_ROOT/.orchestrator/.state"
+INVOCATION_FILE="$STATE_DIR/current-invocation"
+DEBUG_LOG="$STATE_DIR/hook-debug.log"
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+ACTION="${1:-}"
+
+# Read stdin into variable (Claude Code passes JSON via stdin)
+STDIN_DATA=""
+if [ ! -t 0 ]; then
+  STDIN_DATA=$(cat)
+fi
+
+case "$ACTION" in
+  start)
+    # Extract agent info from stdin JSON
+    # Structure: { "tool_name": "Task", "tool_input": { "subagent_type": "...", ... } }
+    if [ -n "$STDIN_DATA" ]; then
+      # Debug: log received data
+      echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] START stdin: $STDIN_DATA" >> "$DEBUG_LOG"
+
+      AGENT_NAME=$(echo "$STDIN_DATA" | node -e "
+        let data = '';
+        process.stdin.on('data', chunk => data += chunk);
+        process.stdin.on('end', () => {
+          try {
+            const json = JSON.parse(data);
+            // Try different structures
+            const type = json.tool_input?.subagent_type
+                      || json.subagent_type
+                      || json.tool_input?.type
+                      || 'unknown';
+            console.log(type);
+          } catch { console.log('unknown'); }
+        });
+      ")
+      PHASE=$(echo "$STDIN_DATA" | node -e "
+        let data = '';
+        process.stdin.on('data', chunk => data += chunk);
+        process.stdin.on('end', () => {
+          try {
+            const json = JSON.parse(data);
+            const type = json.tool_input?.subagent_type
+                      || json.subagent_type
+                      || json.tool_input?.type
+                      || 'unknown';
+            const phaseMap = {
+              'specifier': 'specify',
+              'planner': 'plan',
+              'task-generator': 'tasks',
+              'implementer': 'implement',
+              'researcher': 'research',
+              'reviewer': 'review',
+              'orchestrator': 'orchestrate'
+            };
+            console.log(phaseMap[type] || type);
+          } catch { console.log('unknown'); }
+        });
+      ")
+    elif [ -n "$CLAUDE_TOOL_INPUT" ]; then
+      # Fallback to environment variable
+      echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] START env: $CLAUDE_TOOL_INPUT" >> "$DEBUG_LOG"
+
+      AGENT_NAME=$(echo "$CLAUDE_TOOL_INPUT" | node -e "
+        let data = '';
+        process.stdin.on('data', chunk => data += chunk);
+        process.stdin.on('end', () => {
+          try {
+            const json = JSON.parse(data);
+            const type = json.subagent_type || json.tool_input?.subagent_type || 'unknown';
+            console.log(type);
+          } catch { console.log('unknown'); }
+        });
+      ")
+      PHASE="unknown"
+    else
+      echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] START no input received" >> "$DEBUG_LOG"
+      AGENT_NAME="unknown"
+      PHASE="unknown"
+    fi
+
+    # Generate invocation ID
+    INVOCATION_ID="inv-$(date +%s)-$(head -c 4 /dev/urandom | xxd -p)"
+    STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Get workflow ID from index
+    WORKFLOW_ID=""
+    if [ -f "$INDEX_FILE" ]; then
+      WORKFLOW_ID=$(node -e "
+        const fs = require('fs');
+        try {
+          const idx = JSON.parse(fs.readFileSync('$INDEX_FILE', 'utf8'));
+          console.log(idx.activeWorkflow?.id || 'wf-standalone-' + Date.now());
+        } catch { console.log('wf-standalone-' + Date.now()); }
+      ")
+    fi
+
+    # Save invocation state
+    echo "$INVOCATION_ID" > "$INVOCATION_FILE"
+
+    # Update orchestrator-index.json
+    if [ -f "$INDEX_FILE" ]; then
+      node -e "
+        const fs = require('fs');
+        const indexPath = '$INDEX_FILE';
+        const idx = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+
+        if (!idx.agentInvocations) idx.agentInvocations = [];
+
+        idx.agentInvocations.push({
+          id: '$INVOCATION_ID',
+          agentName: '$AGENT_NAME',
+          phase: '$PHASE',
+          workflowId: '$WORKFLOW_ID',
+          startedAt: '$STARTED_AT',
+          completedAt: null,
+          status: 'running',
+          durationMs: 0
+        });
+
+        fs.writeFileSync(indexPath, JSON.stringify(idx, null, 2));
+        console.log(JSON.stringify({ invocationId: '$INVOCATION_ID', startedAt: '$STARTED_AT' }));
+      "
+    else
+      echo '{"invocationId": "'$INVOCATION_ID'", "startedAt": "'$STARTED_AT'", "warning": "No index file found"}'
+    fi
+    ;;
+
+  complete)
+    # Get invocation ID from state file
+    INVOCATION_ID=""
+    if [ -f "$INVOCATION_FILE" ]; then
+      INVOCATION_ID=$(cat "$INVOCATION_FILE")
+    fi
+
+    if [ -z "$INVOCATION_ID" ]; then
+      echo '{"success": false, "error": "No invocation ID found"}'
+      exit 0  # Don't fail the hook
+    fi
+
+    # Debug log
+    if [ -n "$STDIN_DATA" ]; then
+      echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] COMPLETE stdin: $STDIN_DATA" >> "$DEBUG_LOG"
+    fi
+
+    # Determine status - default to success
+    STATUS="success"
+    SUMMARY="Completed"
+
+    COMPLETED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Update orchestrator-index.json
+    if [ -f "$INDEX_FILE" ]; then
+      node -e "
+        const fs = require('fs');
+        const indexPath = '$INDEX_FILE';
+        const idx = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+
+        const invocations = idx.agentInvocations || [];
+        const invIdx = invocations.findIndex(i => i.id === '$INVOCATION_ID');
+
+        if (invIdx === -1) {
+          console.log(JSON.stringify({ success: false, error: 'Invocation not found' }));
+          process.exit(0);
+        }
+
+        const inv = invocations[invIdx];
+        const startTime = new Date(inv.startedAt).getTime();
+        const endTime = new Date('$COMPLETED_AT').getTime();
+        const durationMs = endTime - startTime;
+
+        invocations[invIdx] = {
+          ...inv,
+          completedAt: '$COMPLETED_AT',
+          status: '$STATUS' === 'success' ? 'completed' : 'failed',
+          durationMs,
+          result: {
+            status: '$STATUS',
+            summary: '$SUMMARY'
+          }
+        };
+
+        idx.agentInvocations = invocations;
+
+        // Update statistics
+        if (idx.statistics) {
+          idx.statistics.totalInvocations = invocations.length;
+          idx.statistics.lastActivity = '$COMPLETED_AT';
+        }
+
+        fs.writeFileSync(indexPath, JSON.stringify(idx, null, 2));
+        console.log(JSON.stringify({ success: true, durationMs }));
+      "
+    else
+      echo '{"success": false, "error": "No index file found"}'
+    fi
+
+    # Clean up state file
+    rm -f "$INVOCATION_FILE"
+    ;;
+
+  *)
+    echo "Usage: $0 {start|complete}"
+    echo ""
+    echo "This script is called by Claude Code hooks."
+    echo "It reads JSON from stdin with structure:"
+    echo '  { "tool_name": "Task", "tool_input": { "subagent_type": "...", ... } }'
+    echo ""
+    echo "Debug log: $DEBUG_LOG"
+    exit 0
+    ;;
+esac

package/templates/base/claude/orchestrator-config.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://orchestrator.ai/schemas/orchestrator-config.json",
+  "version": "1.0",
+  "_description": "Configuracoes customizadas do Orchestrator. NAO e lido pelo Claude Code CLI - usado pelo codigo TypeScript do Orchestrator.",
+
+  "project": {
+    "name": "orchestrator",
+    "description": "Sistema de Orquestracao Autonomo para Claude Code"
+  },
+
+  "agents": {
+    "orchestrator": {
+      "prompt": ".claude/agents/orchestrator.md",
+      "description": "Orchestrator v2 - Minimal decision agent using deterministic MCP tools (getContext, executeAction, canAdvance)",
+      "capabilities": ["invoke_subagents", "access_mcp"],
+      "version": "2.0"
+    },
+    "specifier": {
+      "prompt": ".claude/agents/specifier.md",
+      "description": "Gera especificacoes tecnicas de features",
+      "capabilities": ["access_research", "kb_lookup"]
+    },
+    "planner": {
+      "prompt": ".claude/agents/planner.md",
+      "description": "Elabora planos tecnicos de implementacao",
+      "capabilities": ["access_research", "kb_lookup"]
+    },
+    "task-generator": {
+      "prompt": ".claude/agents/task-generator.md",
+      "description": "Gera backlog de tarefas atomicas",
+      "capabilities": ["kb_lookup"]
+    },
+    "implementer": {
+      "prompt": ".claude/agents/implementer.md",
+      "description": "Executa implementacao de tarefas",
+      "capabilities": ["code_write", "run_tests"]
+    },
+    "researcher": {
+      "prompt": ".claude/agents/researcher.md",
+      "description": "Conduz pesquisas tecnicas via Perplexity",
+      "capabilities": ["access_perplexity"]
+    },
+    "reviewer": {
+      "prompt": ".claude/agents/reviewer.md",
+      "description": "Revisa e valida artefatos e codigo",
+      "capabilities": ["validate_artifacts", "code_review"]
+    }
+  },
+
+  "skills": {
+    "artifact-validator": {
+      "definition": ".claude/skills/artifact-validator/SKILL.md",
+      "description": "Valida artefatos contra schemas e regras de negocio",
+      "auto_invoke": true,
+      "triggers": ["after_artifact_generation", "before_phase_advance"]
+    },
+    "kb-lookup": {
+      "definition": ".claude/skills/kb-lookup/SKILL.md",
+      "description": "Busca informacoes na knowledge base do projeto",
+      "auto_invoke": true,
+      "triggers": ["when_context_needed", "when_rules_referenced"]
+    },
+    "phase-gate-evaluator": {
+      "definition": ".claude/skills/phase-gate-evaluator/SKILL.md",
+      "description": "Avalia gates entre fases do workflow",
+      "auto_invoke": true,
+      "triggers": ["before_phase_advance"]
+    },
+    "workflow-status": {
+      "definition": ".claude/skills/workflow-status/SKILL.md",
+      "description": "Consulta status detalhado do workflow atual",
+      "auto_invoke": false,
+      "triggers": ["on_demand"]
+    }
+  },
+
+  "workflows": {
+    "feature_development": {
+      "phases": ["research", "specify", "plan", "tasks", "implement"],
+      "gates": {
+        "research": "research-complete",
+        "specify": "specification-complete",
+        "plan": "plan-complete",
+        "tasks": "tasks-complete",
+        "implement": "implementation-complete"
+      }
+    },
+    "bug_fix": {
+      "phases": ["triage", "specify", "implement", "verify"],
+      "gates": {
+        "triage": "triage-complete",
+        "specify": "bugfix-spec-complete",
+        "implement": "fix-implemented",
+        "verify": "fix-verified"
+      }
+    },
+    "refactoring": {
+      "phases": ["analyze", "plan", "implement", "verify"],
+      "gates": {
+        "analyze": "analysis-complete",
+        "plan": "refactor-plan-complete",
+        "implement": "refactor-implemented",
+        "verify": "refactor-verified"
+      }
+    }
+  },
+
+  "knowledge_base": {
+    "root": ".orchestrator/memory/knowledge-base",
+    "tiers": {
+      "core": {
+        "path": "core",
+        "immutable": true,
+        "files": ["CONSTITUTION.md"]
+      },
+      "contextual": {
+        "path": "contextual",
+        "immutable": false,
+        "files": ["project-context.md", "tech-stack.md"]
+      },
+      "research": {
+        "path": "research",
+        "cache": true,
+        "ttl_hours": 24
+      }
+    }
+  },
+
+  "quality": {
+    "validation": {
+      "schema_validation": true,
+      "business_rules_validation": true,
+      "lint_on_write": true,
+      "test_on_write": true
+    },
+    "checkpoints": {
+      "auto_checkpoint_on_artifact": true,
+      "checkpoint_message_format": "[orchestrator] {phase}: {artifact_type} - {description}"
+    }
+  }
+}

package/templates/base/claude/settings.json

@@ -0,0 +1,80 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(node:*)",
+      "Bash(git:*)",
+      "Bash(mkdir:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(tree:*)",
+      "Read(.orchestrator/**)",
+      "Read(project-guidelines/**)",
+      "Read(src/**)",
+      "Read(tests/**)",
+      "Read(docs/**)",
+      "Write(.orchestrator/**)",
+      "Write(src/**)",
+      "Write(tests/**)",
+      "Write(docs/**)",
+      "mcp__orchestrator-tools__*",
+      "mcp__perplexity__*",
+      "mcp__knowledge-base__*"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(rm -rf ~)",
+      "Write(.env)",
+      "Write(.env.*)",
+      "Read(.env)",
+      "Read(.env.*)"
+    ]
+  },
+  "env": {
+    "ORCHESTRATOR_ROOT": ".orchestrator",
+    "NODE_ENV": "development"
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/track-agent-invocation.sh start",
+            "timeout": 5000,
+            "on_failure": "ignore"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/track-agent-invocation.sh complete",
+            "timeout": 5000,
+            "on_failure": "ignore"
+          },
+          {
+            "type": "command",
+            "command": ".claude/hooks/post-implement-validate.sh",
+            "timeout": 10000,
+            "on_failure": "warn"
+          },
+          {
+            "type": "command",
+            "command": ".claude/hooks/post-phase-checkpoint.sh",
+            "timeout": 30000,
+            "on_failure": "ignore"
+          }
+        ]
+      }
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "alwaysThinkingEnabled": true
+}

package/templates/base/claude/skills/artifact-validator/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: artifact-validator
+description: Valida artefatos do Orchestrator contra JSON schemas e regras de negocio da CONSTITUTION. Use apos geracao de artefatos (spec, plan, tasks) ou antes de avancar fase.
+allowed-tools: Read, Grep, Glob
+---
+
+# Artifact Validator Skill
+
+## Descricao
+
+Esta skill valida artefatos do sistema de orquestracao contra:
+1. **JSON Schemas**: Estrutura e tipos obrigatorios
+2. **Regras de Negocio**: Definidas na CONSTITUTION.md
+3. **Consistencia**: Referencias internas e dependencias
+
+## Quando Usar
+
+Use esta skill quando:
+- Apos geracao de qualquer artefato (spec, plan, tasks, implementation)
+- Antes de avancar para proxima fase do workflow
+- Quando solicitado revisao de artefato existente
+- Para verificar integridade de artefatos apos edicao
+
+## Invocacao
+
+Exemplos de como invocar esta skill:
+
+```
+"Valide o artefato specification em .orchestrator/artifacts/specify/spec.md"
+
+"Verifique se o plano esta conforme o schema de plan"
+
+"Valide tasks.md contra regras de negocio da CONSTITUTION"
+
+"Faca validacao completa do artefato de implementacao"
+```
+
+## Parametros
+
+| Parametro | Tipo | Obrigatorio | Descricao |
+|-----------|------|-------------|-----------|
+| `artifact_path` | string | Sim | Caminho do artefato a validar |
+| `artifact_type` | enum | Sim | specification, plan, tasks, implementation, research |
+| `validation_level` | enum | Nao | schema (apenas estrutura), business (apenas regras), full (ambos) |
+
+### Valores de validation_level
+
+- **schema**: Valida apenas estrutura JSON/Markdown e campos obrigatorios
+- **business**: Valida apenas regras de negocio da CONSTITUTION
+- **full** (default): Executa ambas validacoes
+
+## Output
+
+A skill retorna resultado estruturado:
+
+```json
+{
+  "isValid": true | false,
+  "validationLevel": "schema" | "business" | "full",
+  "artifactType": "specification",
+  "artifactPath": ".orchestrator/artifacts/specify/spec.md",
+  "timestamp": "2025-12-09T10:30:00Z",
+
+  "schemaValidation": {
+    "passed": true,
+    "errors": [],
+    "warnings": []
+  },
+
+  "businessValidation": {
+    "passed": true,
+    "errors": [],
+    "warnings": [],
+    "rulesChecked": [
+      "CONSTITUTION.rule.001",
+      "CONSTITUTION.rule.002"
+    ]
+  },
+
+  "errors": [
+    {
+      "code": "SCHEMA_001",
+      "field": "requisitos.RF-001.criterio_aceite",
+      "message": "Campo obrigatorio ausente",
+      "severity": "error",
+      "suggestion": "Adicione criterios de aceite verificaveis para RF-001"
+    }
+  ],
+
+  "warnings": [
+    {
+      "code": "BUSINESS_W001",
+      "field": "escopo.out_scope",
+      "message": "Out of scope sem justificativa",
+      "severity": "warning",
+      "suggestion": "Adicione justificativa para cada item out of scope"
+    }
+  ],
+
+  "suggestions": [
+    "Considere adicionar metricas de performance em RNF",
+    "Referencie o research-context se disponivel"
+  ],
+
+  "summary": {
+    "totalErrors": 1,
+    "totalWarnings": 1,
+    "canProceed": false
+  }
+}
+```
+
+## Regras de Validacao
+
+### Schema Validation
+
+#### Specification (spec.md)
+- Campos obrigatorios: metadata, sumario, escopo, requisitos_funcionais
+- Cada RF deve ter: id, descricao, ator, criterio_aceite
+- Cada RNF deve ter: id, metrica, target
+
+#### Plan (plan.md)
+- Campos obrigatorios: metadata, arquitetura, fases, dependencias
+- Cada fase deve ter: id, descricao, entregaveis, estimativa
+- Dependencias devem referenciar fases existentes
+
+#### Tasks (tasks.md)
+- Campos obrigatorios: metadata, backlog, dependencias
+- Cada task deve ter: id, titulo, descricao, criterio_aceite, estimativa
+- Dependencias devem formar DAG (sem ciclos)
+
+#### Implementation
+- Campos obrigatorios: metadata, task_id, arquivos_modificados
+- Cada arquivo deve ter: path, tipo_mudanca, descricao_mudanca
+- task_id deve existir em tasks.md
+
+### Business Validation
+
+Regras extraidas de CONSTITUTION.md:
+
+1. **CONST-001**: Todo requisito deve ter criterio de aceite mensuravel
+2. **CONST-002**: Out of scope deve ter justificativa explicita
+3. **CONST-003**: Estimativas devem estar em unidades padrao (horas/dias)
+4. **CONST-004**: Referencias a outros artefatos devem ser validas
+5. **CONST-005**: Nomes de arquivos devem seguir convencao do projeto
+
+## Integracao com TypeScript
+
+Esta skill invoca o handler TypeScript:
+
+```typescript
+// src/presentation/skills/ArtifactValidatorSkillHandler.ts
+
+export class ArtifactValidatorSkillHandler {
+  async handle(params: ValidationParams): Promise<ValidationResult> {
+    // 1. Carrega artefato do path
+    // 2. Executa SchemaValidator (infrastructure)
+    // 3. Executa ConstitutionValidator (domain)
+    // 4. Combina resultados
+    // 5. Retorna ValidationResult
+  }
+}
+```
+
+## Exemplos de Uso
+
+### Validacao Schema Only
+```
+User: "Valide a estrutura do spec.md"
+Skill: artifact-validator com validation_level=schema
+```
+
+### Validacao Business Only
+```
+User: "Verifique se o plano atende as regras da CONSTITUTION"
+Skill: artifact-validator com validation_level=business
+```
+
+### Validacao Completa (Default)
+```
+User: "Valide completamente o artefato tasks.md"
+Skill: artifact-validator com validation_level=full
+```
+
+## Comportamento em Caso de Erro
+
+### Artefato Nao Encontrado
+```json
+{
+  "isValid": false,
+  "errors": [{
+    "code": "ARTIFACT_NOT_FOUND",
+    "message": "Artefato nao encontrado: {path}"
+  }]
+}
+```
+
+### Tipo Desconhecido
+```json
+{
+  "isValid": false,
+  "errors": [{
+    "code": "UNKNOWN_TYPE",
+    "message": "Tipo de artefato desconhecido: {type}"
+  }]
+}
+```
+
+### Erro de Parse
+```json
+{
+  "isValid": false,
+  "errors": [{
+    "code": "PARSE_ERROR",
+    "message": "Erro ao parsear artefato: {details}"
+  }]
+}
+```
+
+## Notas Importantes
+
+1. Esta skill **NAO** modifica artefatos, apenas valida
+2. Validacao **full** e sempre recomendada antes de avancar fase
+3. Warnings **NAO** impedem avanco, mas devem ser revisados
+4. Errors **IMPEDEM** avanco e devem ser corrigidos
+5. Sugestoes sao opcionais mas melhoram qualidade