@orchestrator-claude/cli 1.4.0

package/templates/base/claude/hooks/post-artifact-generate.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Post-Artifact Generate Hook
+# Executado apos geracao de um artefato
+# Valida artefato, atualiza indice, cria checkpoint
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Recebe evento via stdin ou argumento
+if [ -n "$1" ]; then
+    EVENT="$1"
+else
+    EVENT=$(cat)
+fi
+
+# Verifica se temos o handler compilado
+HANDLER="$PROJECT_ROOT/dist/hook.js"
+
+if [ ! -f "$HANDLER" ]; then
+    echo '{"success": false, "error": "Hook handler not compiled. Run npm run build first."}' >&2
+    exit 1
+fi
+
+# Executa o handler TypeScript
+echo "$EVENT" | node "$HANDLER" post-artifact
+
+EXIT_CODE=$?
+
+# Log do resultado
+if [ $EXIT_CODE -eq 0 ]; then
+    echo "[post-artifact-generate] Artifact processed successfully" >&2
+else
+    echo "[post-artifact-generate] Warning: Artifact processing had issues" >&2
+fi
+
+# Este hook nao bloqueia, apenas avisa
+exit 0

package/templates/base/claude/hooks/post-implement-validate.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# Post-Implement Validation Hook
+# Validates orchestrator-index.json consistency after IMPLEMENT phase
+# Detects possible delegation bypass where code was written directly
+# instead of through the implementer subagent
+#
+# Exit codes:
+#   0 = Validation passed or skipped (jq not available)
+#   1 = Warning detected (possible delegation bypass)
+#
+# Author: Orchestrator System
+# Version: 1.0.0
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+INDEX_FILE="$PROJECT_ROOT/.orchestrator/orchestrator-index.json"
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${GREEN}[post-implement-validate]${NC} $1" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[post-implement-validate] WARNING:${NC} $1" >&2
+}
+
+log_error() {
+    echo -e "${RED}[post-implement-validate] ERROR:${NC} $1" >&2
+}
+
+log_debug() {
+    if [ "${DEBUG:-false}" = "true" ]; then
+        echo -e "${CYAN}[post-implement-validate] DEBUG:${NC} $1" >&2
+    fi
+}
+
+# Check if jq is available
+if ! command -v jq &> /dev/null; then
+    log_warn "jq not found, skipping validation (install jq for full validation)"
+    exit 0
+fi
+
+# Check if orchestrator-index.json exists
+if [ ! -f "$INDEX_FILE" ]; then
+    log_debug "orchestrator-index.json not found at $INDEX_FILE, skipping validation"
+    exit 0
+fi
+
+# Read statistics from orchestrator-index.json
+TASKS_COMPLETED=$(jq -r '.statistics.tasksCompleted // 0' "$INDEX_FILE" 2>/dev/null || echo "0")
+TASKS_PENDING=$(jq -r '.statistics.tasksPending // 0' "$INDEX_FILE" 2>/dev/null || echo "0")
+CURRENT_PHASE=$(jq -r '.activeWorkflow.currentPhase // "unknown"' "$INDEX_FILE" 2>/dev/null || echo "unknown")
+STATUS=$(jq -r '.activeWorkflow.status // "unknown"' "$INDEX_FILE" 2>/dev/null || echo "unknown")
+
+# Count TypeScript files in src/ (if directory exists)
+TS_FILES_COUNT=0
+if [ -d "$PROJECT_ROOT/src" ]; then
+    TS_FILES_COUNT=$(find "$PROJECT_ROOT/src" -name "*.ts" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+fi
+
+# Count test files
+TEST_FILES_COUNT=0
+if [ -d "$PROJECT_ROOT/tests" ]; then
+    TEST_FILES_COUNT=$(find "$PROJECT_ROOT/tests" -name "*.spec.ts" -o -name "*.test.ts" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+fi
+
+log_info "Validating IMPLEMENT phase consistency..."
+log_info "  Current Phase: $CURRENT_PHASE"
+log_info "  Status: $STATUS"
+log_info "  Tasks Completed: $TASKS_COMPLETED"
+log_info "  Tasks Pending: $TASKS_PENDING"
+log_info "  TypeScript Files: $TS_FILES_COUNT"
+log_info "  Test Files: $TEST_FILES_COUNT"
+
+# Detection logic
+WARNINGS=0
+MESSAGES=()
+
+# Check 1: Few tasks completed but many pending (primary indicator)
+if [ "$TASKS_COMPLETED" -le 1 ] && [ "$TASKS_PENDING" -gt 5 ]; then
+    MESSAGES+=("Only $TASKS_COMPLETED task(s) completed but $TASKS_PENDING pending.")
+    MESSAGES+=("This suggests the implementer agent may not have been properly invoked.")
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+# Check 2: Many source files but few tasks completed
+if [ "$TS_FILES_COUNT" -gt 10 ] && [ "$TASKS_COMPLETED" -lt 5 ]; then
+    MESSAGES+=("Found $TS_FILES_COUNT TypeScript files but only $TASKS_COMPLETED tasks completed.")
+    MESSAGES+=("Code may have been generated without proper task tracking.")
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+# Check 3: Status still "ready_for_implementation" after code exists
+if [ "$STATUS" = "ready_for_implementation" ] && [ "$TS_FILES_COUNT" -gt 5 ]; then
+    MESSAGES+=("Status is still 'ready_for_implementation' but $TS_FILES_COUNT code files exist.")
+    MESSAGES+=("Workflow state may not have been updated correctly.")
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+# Check 4: Source files exist but no test files (TDD violation)
+if [ "$TS_FILES_COUNT" -gt 5 ] && [ "$TEST_FILES_COUNT" -eq 0 ]; then
+    MESSAGES+=("Found $TS_FILES_COUNT source files but no test files.")
+    MESSAGES+=("TDD methodology may not have been followed.")
+    WARNINGS=$((WARNINGS + 1))
+fi
+
+# Summary
+if [ "$WARNINGS" -gt 0 ]; then
+    echo "" >&2
+    log_warn "============================================"
+    log_warn "Detected $WARNINGS potential issue(s):"
+    log_warn "============================================"
+    for msg in "${MESSAGES[@]}"; do
+        log_warn "  - $msg"
+    done
+    echo "" >&2
+    log_warn "Possible causes:"
+    log_warn "  1. Implementer agent was not invoked via Task tool"
+    log_warn "  2. Code was written directly instead of through delegation"
+    log_warn "  3. orchestrator-index.json was not updated during implementation"
+    echo "" >&2
+    log_warn "Recommended actions:"
+    log_warn "  1. Review CLAUDE.md section: MANDATORY: IMPLEMENT Phase Delegation"
+    log_warn "  2. Ensure Task tool is used with subagent_type='implementer'"
+    log_warn "  3. Update orchestrator-index.json with correct task progress"
+    echo "" >&2
+    exit 1
+else
+    log_info "Validation passed. No issues detected."
+    exit 0
+fi

package/templates/base/claude/hooks/post-phase-checkpoint.sh

@@ -0,0 +1,322 @@
+#!/bin/bash
+# Post-Phase Checkpoint Hook
+# Automatically creates git checkpoints when workflow phases complete
+#
+# Triggered by: PostToolUse on Task tool (after agent completes)
+# Behavior: Detects phase transitions and creates git commits
+#
+# Requirements:
+#   - jq (for JSON parsing)
+#   - git (for checkpoint commits)
+#
+# Debug mode: ORCH_CHECKPOINT_DEBUG=1 to enable verbose logging
+
+set -e
+
+# Configuration
+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"
+LOG_FILE="$STATE_DIR/checkpoint-hook.log"
+LAST_PHASE_FILE="$STATE_DIR/last-checkpointed-phase"
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+# Debug mode
+DEBUG="${ORCH_CHECKPOINT_DEBUG:-0}"
+
+# Logging functions
+log_debug() {
+  if [ "$DEBUG" = "1" ]; then
+    echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [DEBUG] $1" >> "$LOG_FILE"
+    echo "[DEBUG] $1" >&2
+  fi
+}
+
+log_info() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [INFO] $1" >> "$LOG_FILE"
+  if [ "$DEBUG" = "1" ]; then
+    echo "[INFO] $1" >&2
+  fi
+}
+
+log_warn() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [WARN] $1" >> "$LOG_FILE"
+  echo "[WARN] $1" >&2
+}
+
+log_error() {
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [ERROR] $1" >> "$LOG_FILE"
+  echo "[ERROR] $1" >&2
+}
+
+# Check prerequisites
+check_prerequisites() {
+  # Check jq
+  if ! command -v jq &> /dev/null; then
+    log_error "jq is not installed. Checkpoints disabled."
+    return 1
+  fi
+
+  # Check git
+  if ! command -v git &> /dev/null; then
+    log_error "git is not installed. Checkpoints disabled."
+    return 1
+  fi
+
+  # Check if we're in a git repo
+  if ! git -C "$PROJECT_ROOT" rev-parse --is-inside-work-tree &> /dev/null; then
+    log_warn "Not a git repository. Checkpoints disabled."
+    return 1
+  fi
+
+  # Check index file
+  if [ ! -f "$INDEX_FILE" ]; then
+    log_debug "No orchestrator-index.json found. Skipping."
+    return 1
+  fi
+
+  return 0
+}
+
+# Get current phase from orchestrator-index.json
+get_current_phase() {
+  local phase
+  phase=$(jq -r '.activeWorkflow.currentPhase // empty' "$INDEX_FILE" 2>/dev/null)
+  echo "$phase"
+}
+
+# Get workflow ID
+get_workflow_id() {
+  local wf_id
+  wf_id=$(jq -r '.activeWorkflow.id // empty' "$INDEX_FILE" 2>/dev/null)
+  echo "$wf_id"
+}
+
+# Get workflow status
+get_workflow_status() {
+  local status
+  status=$(jq -r '.activeWorkflow.status // empty' "$INDEX_FILE" 2>/dev/null)
+  echo "$status"
+}
+
+# Get last checkpointed phase from checkpoints array (one with commitHash)
+get_last_checkpointed_phase() {
+  local phase
+  # Find the most recent checkpoint that has a commitHash (indicating it was git-committed)
+  phase=$(jq -r '
+    [.checkpoints[] | select(.commitHash != null and .commitHash != "")]
+    | sort_by(.createdAt)
+    | last
+    | .phase // empty
+  ' "$INDEX_FILE" 2>/dev/null)
+  echo "$phase"
+}
+
+# Determine completed phase based on current phase
+# When we see currentPhase = PLAN, it means SPECIFY just completed
+get_completed_phase() {
+  local current_phase="$1"
+  local workflow_status="$2"
+
+  case "$workflow_status" in
+    "completed")
+      echo "IMPLEMENT"
+      return
+      ;;
+  esac
+
+  case "$current_phase" in
+    "PLAN")
+      echo "SPECIFY"
+      ;;
+    "TASKS")
+      echo "PLAN"
+      ;;
+    "IMPLEMENT")
+      echo "TASKS"
+      ;;
+    *)
+      echo ""
+      ;;
+  esac
+}
+
+# Create git checkpoint
+create_git_checkpoint() {
+  local phase="$1"
+  local commit_hash=""
+
+  log_info "Creating git checkpoint for phase: $phase"
+
+  # Stage all changes
+  git -C "$PROJECT_ROOT" add -A 2>/dev/null || {
+    log_warn "Failed to stage changes"
+    return 1
+  }
+
+  # Check if there are staged changes
+  if git -C "$PROJECT_ROOT" diff --cached --quiet 2>/dev/null; then
+    log_info "No changes to commit for phase: $phase"
+    echo ""
+    return 0
+  fi
+
+  # Create commit with standard message
+  local commit_msg="[orchestrator] ${phase}: Auto-checkpoint after ${phase} phase"
+
+  if git -C "$PROJECT_ROOT" commit -m "$commit_msg" --no-verify 2>/dev/null; then
+    commit_hash=$(git -C "$PROJECT_ROOT" rev-parse HEAD 2>/dev/null)
+    log_info "Checkpoint commit created: $commit_hash"
+    echo "$commit_hash"
+  else
+    log_warn "Failed to create commit"
+    echo ""
+    return 1
+  fi
+}
+
+# Update orchestrator-index.json with checkpoint
+update_orchestrator_index() {
+  local workflow_id="$1"
+  local phase="$2"
+  local commit_hash="$3"
+  local created_at
+
+  created_at=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  local checkpoint_id="cp_${workflow_id}_$(date +%s)"
+  local description="Auto-checkpoint after ${phase} phase"
+
+  log_debug "Updating index with checkpoint: $checkpoint_id"
+
+  # Create temp file for atomic update
+  local temp_file="${INDEX_FILE}.tmp.$$"
+
+  # Use jq to add checkpoint and update statistics
+  if jq --arg id "$checkpoint_id" \
+       --arg wfId "$workflow_id" \
+       --arg phase "$phase" \
+       --arg hash "$commit_hash" \
+       --arg date "$created_at" \
+       --arg desc "$description" '
+    # Add checkpoint to array
+    .checkpoints += [{
+      id: $id,
+      workflowId: $wfId,
+      phase: $phase,
+      commitHash: $hash,
+      createdAt: $date,
+      description: $desc
+    }] |
+    # Update statistics
+    .statistics.totalCheckpoints = (.checkpoints | length) |
+    .statistics.lastActivity = $date
+  ' "$INDEX_FILE" > "$temp_file" 2>/dev/null; then
+
+    # Validate JSON
+    if jq empty "$temp_file" 2>/dev/null; then
+      mv "$temp_file" "$INDEX_FILE"
+      log_info "Index updated with checkpoint: $checkpoint_id"
+      return 0
+    else
+      log_error "Generated invalid JSON"
+      rm -f "$temp_file"
+      return 1
+    fi
+  else
+    log_error "Failed to update index with jq"
+    rm -f "$temp_file"
+    return 1
+  fi
+}
+
+# Save last checkpointed phase
+save_last_phase() {
+  local phase="$1"
+  echo "$phase" > "$LAST_PHASE_FILE"
+}
+
+# Get saved last phase (from state file, not index)
+get_saved_last_phase() {
+  if [ -f "$LAST_PHASE_FILE" ]; then
+    cat "$LAST_PHASE_FILE"
+  else
+    echo ""
+  fi
+}
+
+# Main execution
+main() {
+  log_debug "Hook triggered"
+
+  # Check prerequisites
+  if ! check_prerequisites; then
+    log_debug "Prerequisites not met, exiting"
+    exit 0  # Don't fail the hook
+  fi
+
+  # Get current state
+  local current_phase
+  current_phase=$(get_current_phase)
+
+  if [ -z "$current_phase" ]; then
+    log_debug "No active workflow phase found"
+    exit 0
+  fi
+
+  local workflow_id
+  workflow_id=$(get_workflow_id)
+
+  local workflow_status
+  workflow_status=$(get_workflow_status)
+
+  log_debug "Current phase: $current_phase, Status: $workflow_status, Workflow: $workflow_id"
+
+  # Determine which phase just completed
+  local completed_phase
+  completed_phase=$(get_completed_phase "$current_phase" "$workflow_status")
+
+  if [ -z "$completed_phase" ]; then
+    log_debug "No completed phase detected from current phase: $current_phase"
+    exit 0
+  fi
+
+  # Check if we already checkpointed this phase
+  local last_checkpointed
+  last_checkpointed=$(get_last_checkpointed_phase)
+
+  local saved_last_phase
+  saved_last_phase=$(get_saved_last_phase)
+
+  log_debug "Completed phase: $completed_phase, Last checkpointed: $last_checkpointed, Saved: $saved_last_phase"
+
+  # Skip if already checkpointed
+  if [ "$completed_phase" = "$last_checkpointed" ] || [ "$completed_phase" = "$saved_last_phase" ]; then
+    log_debug "Phase $completed_phase already checkpointed, skipping"
+    exit 0
+  fi
+
+  # Create checkpoint
+  local commit_hash
+  commit_hash=$(create_git_checkpoint "$completed_phase")
+
+  # Update index (even if no commit, to track the checkpoint)
+  if [ -n "$commit_hash" ]; then
+    if update_orchestrator_index "$workflow_id" "$completed_phase" "$commit_hash"; then
+      save_last_phase "$completed_phase"
+      log_info "Checkpoint complete for phase: $completed_phase (commit: $commit_hash)"
+    else
+      log_error "Failed to update index for phase: $completed_phase"
+    fi
+  else
+    log_info "No changes to checkpoint for phase: $completed_phase"
+    save_last_phase "$completed_phase"
+  fi
+
+  exit 0
+}
+
+# Run main function
+main "$@"

package/templates/base/claude/hooks/pre-agent-invoke.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Pre-Agent Invoke Hook
+# Executado antes de invocar um subagent
+# Valida contexto e injeta informacoes da KB
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Recebe evento via stdin ou argumento
+if [ -n "$1" ]; then
+    EVENT="$1"
+else
+    EVENT=$(cat)
+fi
+
+# Verifica se temos o handler compilado
+HANDLER="$PROJECT_ROOT/dist/hook.js"
+
+if [ ! -f "$HANDLER" ]; then
+    echo '{"success": false, "error": "Hook handler not compiled. Run npm run build first."}' >&2
+    exit 1
+fi
+
+# Executa o handler TypeScript
+echo "$EVENT" | node "$HANDLER" pre-agent-invoke
+
+EXIT_CODE=$?
+
+# Exit code determina se agente pode prosseguir
+# 0 = permitido
+# 1 = bloqueado
+exit $EXIT_CODE

package/templates/base/claude/hooks/pre-phase-advance.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Pre-Phase Advance Hook
+# Executado antes de avancar para proxima fase
+# Avalia gate e cria checkpoint
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Recebe evento via stdin ou argumento
+if [ -n "$1" ]; then
+    EVENT="$1"
+else
+    EVENT=$(cat)
+fi
+
+# Verifica se temos o handler compilado
+HANDLER="$PROJECT_ROOT/dist/hook.js"
+
+if [ ! -f "$HANDLER" ]; then
+    echo '{"success": false, "error": "Hook handler not compiled. Run npm run build first."}' >&2
+    exit 1
+fi
+
+# Executa o handler TypeScript
+echo "$EVENT" | node "$HANDLER" pre-phase-advance
+
+EXIT_CODE=$?
+
+# Exit code determina se fase pode avancar
+# 0 = gate passou, pode avancar
+# 1 = gate falhou, bloqueado
+if [ $EXIT_CODE -eq 0 ]; then
+    echo "[pre-phase-advance] Gate passed, advancing phase" >&2
+else
+    echo "[pre-phase-advance] Gate failed, phase advance blocked" >&2
+fi
+
+exit $EXIT_CODE