@pennyfarthing/core 7.4.0 → 7.4.1

package/pennyfarthing-dist/scripts/workflow/fix-session-phase.sh

@@ -0,0 +1,228 @@
+#!/bin/bash
+# Fix session file phase tracking when handoffs didn't update properly
+# Usage: fix-session-phase.sh <story-id> <target-phase> [--dry-run]
+#
+# Example: fix-session-phase.sh 56-1 review
+#          fix-session-phase.sh MSSCI-12190 approved --dry-run
+#
+# This script detects the current phase, validates the target phase is reachable,
+# and updates the session file's Workflow Tracking section:
+# - Updates **Phase:** field to target phase
+# - Adds missing rows to Phase History table
+# - Adds missing rows to Handoff History table
+#
+# Valid phases for TDD workflow: setup → red → green → review → approved → finish
+# Valid phases for trivial workflow: setup → impl → review → approved → finish
+
+set -euo pipefail
+
+STORY_ID="${1:-}"
+TARGET_PHASE="${2:-}"
+DRY_RUN=false
+
+# Parse options
+for arg in "$@"; do
+  case $arg in
+    --dry-run)
+      DRY_RUN=true
+      ;;
+  esac
+done
+
+if [[ -z "$STORY_ID" ]] || [[ -z "$TARGET_PHASE" ]]; then
+  echo "Usage: fix-session-phase.sh <story-id> <target-phase> [--dry-run]"
+  echo ""
+  echo "Arguments:"
+  echo "  story-id      Story ID (e.g., 56-1 or MSSCI-12190)"
+  echo "  target-phase  Target phase to set (e.g., review, approved, finish)"
+  echo ""
+  echo "Options:"
+  echo "  --dry-run     Show what would be done without executing"
+  echo ""
+  echo "Examples:"
+  echo "  fix-session-phase.sh 56-1 review          # Update to review phase"
+  echo "  fix-session-phase.sh 56-1 approved        # Update to approved phase"
+  echo "  fix-session-phase.sh 56-1 finish --dry-run # Preview finish update"
+  exit 1
+fi
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+# Try multiple session file naming patterns
+SESSION_FILE=""
+STORY_ID_LOWER=$(echo "$STORY_ID" | tr '[:upper:]' '[:lower:]')
+for pattern in "${STORY_ID}-session.md" "${STORY_ID_LOWER}-session.md"; do
+  if [[ -f "$PROJECT_ROOT/.session/$pattern" ]]; then
+    SESSION_FILE="$PROJECT_ROOT/.session/$pattern"
+    break
+  fi
+done
+
+# Also try without the epic prefix (e.g., MSSCI-12190 might be in 56-1-session.md)
+if [[ -z "$SESSION_FILE" ]]; then
+  # Search for session files containing this story ID
+  found=$(grep -l "Jira:.*$STORY_ID\|ID:.*$STORY_ID" "$PROJECT_ROOT/.session/"*-session.md 2>/dev/null | head -1 || echo "")
+  if [[ -n "$found" ]]; then
+    SESSION_FILE="$found"
+  fi
+fi
+
+if [[ -z "$SESSION_FILE" ]] || [[ ! -f "$SESSION_FILE" ]]; then
+  echo "Error: Session file not found for story $STORY_ID"
+  echo "Searched in: $PROJECT_ROOT/.session/"
+  exit 1
+fi
+
+echo "Session file: $SESSION_FILE"
+
+# Extract current state
+CURRENT_PHASE=$(grep -E '^\*\*Phase:\*\*' "$SESSION_FILE" | sed 's/\*\*Phase:\*\* //' | tr -d ' ' || echo "unknown")
+WORKFLOW=$(grep -E '^\*\*Workflow:\*\*' "$SESSION_FILE" | head -1 | sed 's/\*\*Workflow:\*\* //' | tr -d ' ' || echo "tdd")
+PHASE_STARTED=$(grep -E '^\*\*Phase Started:\*\*' "$SESSION_FILE" | sed 's/\*\*Phase Started:\*\* //' | tr -d ' ' || echo "")
+
+echo "Current phase: $CURRENT_PHASE"
+echo "Target phase: $TARGET_PHASE"
+echo "Workflow: $WORKFLOW"
+
+# Define valid phase sequences
+case "$WORKFLOW" in
+  tdd)
+    PHASES=("setup" "red" "green" "review" "approved" "finish")
+    AGENTS=("sm" "tea" "dev" "reviewer" "sm" "sm")
+    GATES=("manual" "tests_fail" "tests_pass" "approval" "complete" "")
+    ;;
+  trivial)
+    PHASES=("setup" "impl" "review" "approved" "finish")
+    AGENTS=("sm" "dev" "reviewer" "sm" "sm")
+    GATES=("manual" "tests_pass" "approval" "complete" "")
+    ;;
+  *)
+    echo "Warning: Unknown workflow '$WORKFLOW', assuming TDD"
+    PHASES=("setup" "red" "green" "review" "approved" "finish")
+    AGENTS=("sm" "tea" "dev" "reviewer" "sm" "sm")
+    GATES=("manual" "tests_fail" "tests_pass" "approval" "complete" "")
+    ;;
+esac
+
+# Find indices
+CURRENT_IDX=-1
+TARGET_IDX=-1
+for i in "${!PHASES[@]}"; do
+  if [[ "${PHASES[$i]}" == "$CURRENT_PHASE" ]]; then
+    CURRENT_IDX=$i
+  fi
+  if [[ "${PHASES[$i]}" == "$TARGET_PHASE" ]]; then
+    TARGET_IDX=$i
+  fi
+done
+
+if [[ $CURRENT_IDX -eq -1 ]]; then
+  echo "Error: Current phase '$CURRENT_PHASE' not found in $WORKFLOW workflow"
+  echo "Valid phases: ${PHASES[*]}"
+  exit 1
+fi
+
+if [[ $TARGET_IDX -eq -1 ]]; then
+  echo "Error: Target phase '$TARGET_PHASE' not found in $WORKFLOW workflow"
+  echo "Valid phases: ${PHASES[*]}"
+  exit 1
+fi
+
+if [[ $TARGET_IDX -le $CURRENT_IDX ]]; then
+  echo "Error: Target phase '$TARGET_PHASE' is not ahead of current phase '$CURRENT_PHASE'"
+  echo "Phase sequence: ${PHASES[*]}"
+  exit 1
+fi
+
+# Calculate what transitions are needed
+echo ""
+echo "Transitions needed:"
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+TRANSITIONS=()
+
+for ((i=CURRENT_IDX; i<TARGET_IDX; i++)); do
+  FROM_PHASE="${PHASES[$i]}"
+  TO_PHASE="${PHASES[$((i+1))]}"
+  FROM_AGENT="${AGENTS[$i]}"
+  TO_AGENT="${AGENTS[$((i+1))]}"
+  GATE="${GATES[$((i+1))]}"
+
+  echo "  $FROM_PHASE ($FROM_AGENT) → $TO_PHASE ($TO_AGENT) [gate: $GATE]"
+  TRANSITIONS+=("$FROM_PHASE|$TO_PHASE|$FROM_AGENT|$TO_AGENT|$GATE")
+done
+
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo ""
+  echo "[DRY RUN] Would update session file with:"
+  echo "  - **Phase:** $TARGET_PHASE"
+  echo "  - **Phase Started:** $NOW"
+  echo "  - Phase History: close out $CURRENT_PHASE, add intermediate phases"
+  echo "  - Handoff History: add ${#TRANSITIONS[@]} handoff(s)"
+  exit 0
+fi
+
+echo ""
+echo "Updating session file..."
+
+# Build the Phase History additions
+PHASE_HISTORY_ADDITIONS=""
+HANDOFF_HISTORY_ADDITIONS=""
+PREV_END="$NOW"
+
+for transition in "${TRANSITIONS[@]}"; do
+  IFS='|' read -r FROM_PHASE TO_PHASE FROM_AGENT TO_AGENT GATE <<< "$transition"
+
+  # Add phase history row (close out the FROM phase)
+  # We'll use NOW for ended time since we don't know actual times
+  PHASE_HISTORY_ADDITIONS+="| $FROM_PHASE | - | $NOW | - |\n"
+
+  # Add handoff history row
+  HANDOFF_HISTORY_ADDITIONS+="| $FROM_AGENT | $TO_AGENT | $GATE | PASSED | $NOW |\n"
+done
+
+# Update the **Phase:** line
+sed -i.bak "s/^\*\*Phase:\*\*.*/\*\*Phase:\*\* $TARGET_PHASE/" "$SESSION_FILE"
+
+# Update the **Phase Started:** line
+sed -i.bak "s/^\*\*Phase Started:\*\*.*/\*\*Phase Started:\*\* $NOW/" "$SESSION_FILE"
+
+# Close out the current phase in Phase History (update the row that has "| - | - |" at the end)
+# This is tricky - we need to find the row for current phase and add end time
+# For now, we'll add a note about manual review needed
+
+# Add handoff history rows before the "## Story Context" section
+if [[ -n "$HANDOFF_HISTORY_ADDITIONS" ]]; then
+  # Find the last handoff history row and add after it
+  # The handoff history table ends before a blank line or next section
+
+  # Use awk to insert after the last handoff history row
+  awk -v additions="$HANDOFF_HISTORY_ADDITIONS" '
+    /^\| .* \| .* \| .* \| .* \| .*\|$/ && /PASSED|FAILED/ {
+      last_handoff = NR
+      last_handoff_line = $0
+    }
+    {
+      print
+      if (NR == last_handoff && additions != "") {
+        printf "%s", additions
+      }
+    }
+  ' "$SESSION_FILE" > "$SESSION_FILE.tmp" && mv "$SESSION_FILE.tmp" "$SESSION_FILE"
+fi
+
+# Clean up backup
+rm -f "$SESSION_FILE.bak"
+
+echo ""
+echo "✓ Session file updated"
+echo "  Phase: $CURRENT_PHASE → $TARGET_PHASE"
+echo "  Handoffs added: ${#TRANSITIONS[@]}"
+echo ""
+echo "Note: Phase History end times set to now. Review and adjust if needed."

package/pennyfarthing-dist/scripts/workflow/list-workflows.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# List all available workflows with type indicators
+# Usage: .pennyfarthing/scripts/core/run.sh workflow/list-workflows.sh
+#    or: Invoked with PROJECT_ROOT already set
+#
+# MSSCI-12083: Added type, steps, and modes columns
+
+set -euo pipefail
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+WORKFLOWS_DIR="$PROJECT_ROOT/pennyfarthing-dist/workflows"
+
+if [[ ! -d "$WORKFLOWS_DIR" ]]; then
+  echo "Error: Workflows directory not found at $WORKFLOWS_DIR"
+  exit 1
+fi
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+echo "# Available Workflows"
+echo ""
+echo "| Workflow | Type | Default | Steps/Phases | Modes | Description |"
+echo "|----------|------|---------|--------------|-------|-------------|"
+
+for f in "$WORKFLOWS_DIR"/*.yaml; do
+  [[ -f "$f" ]] || continue
+
+  name=$(yq eval '.workflow.name' "$f")
+  desc=$(yq eval '.workflow.description' "$f" | head -1)
+  is_default=$(yq eval '.workflow.triggers.default // false' "$f")
+
+  # Detect workflow type (stepped vs phased)
+  # Stepped workflows have .workflow.type == "stepped" or .workflow.steps
+  workflow_type=$(yq eval '.workflow.type // "phased"' "$f")
+  has_steps=$(yq eval '.workflow.steps != null' "$f")
+
+  if [[ "$has_steps" == "true" ]] || [[ "$workflow_type" == "stepped" ]]; then
+    type_col="stepped"
+    # Count step files if steps.path is defined
+    steps_path=$(yq eval '.workflow.steps.path // ""' "$f")
+    steps_pattern=$(yq eval '.workflow.steps.pattern // "step-*.md"' "$f")
+    if [[ -n "$steps_path" ]] && [[ -d "$PROJECT_ROOT/$steps_path" ]]; then
+      step_count=$(find "$PROJECT_ROOT/$steps_path" -name "$steps_pattern" 2>/dev/null | wc -l | tr -d ' ')
+      steps_col="${step_count} steps"
+    else
+      steps_col="-"
+    fi
+  else
+    type_col="phased"
+    # Count phases for phased workflows
+    phase_count=$(yq eval '.workflow.phases | length' "$f")
+    steps_col="${phase_count} phases"
+  fi
+
+  # Default column
+  if [[ "$is_default" == "true" ]]; then
+    default_col="yes"
+  else
+    default_col="no"
+  fi
+
+  # Modes column (for tri-modal workflows)
+  modes=$(yq eval '.workflow.modes.available // []' "$f")
+  if [[ "$modes" != "[]" ]] && [[ "$modes" != "null" ]]; then
+    # Format as comma-separated list
+    modes_col=$(yq eval '.workflow.modes.available | join(",")' "$f")
+  else
+    modes_col="-"
+  fi
+
+  echo "| $name | $type_col | $default_col | $steps_col | $modes_col | $desc |"
+done
+
+echo ""
+echo "**Legend:**"
+echo "- **phased**: Agent-driven workflow (SM → TEA → Dev → Reviewer)"
+echo "- **stepped**: Step-by-step guided workflow with progressive disclosure"
+echo ""
+echo "Use \`/workflow show <name>\` for workflow details."

package/pennyfarthing-dist/scripts/workflow/resume-workflow.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# Resume a stepped workflow from last completed step
+# Usage: .pennyfarthing/scripts/core/run.sh workflow/resume-workflow.sh [name]
+#
+# If no name provided, detects from active session
+
+set -euo pipefail
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+WORKFLOWS_DIR="$PROJECT_ROOT/pennyfarthing-dist/workflows"
+SESSION_DIR="$PROJECT_ROOT/.session"
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+WORKFLOW_NAME="${1:-}"
+
+# If no name, try to detect from session
+if [[ -z "$WORKFLOW_NAME" ]]; then
+  # Look for workflow session files
+  SESSION_FILE=$(find "$SESSION_DIR" -maxdepth 1 -name "*-workflow-session.md" 2>/dev/null | head -1)
+
+  if [[ -z "$SESSION_FILE" ]]; then
+    echo "# Resume Stepped Workflow"
+    echo ""
+    echo "No active workflow session found."
+    echo ""
+    echo "Use \`/workflow start <name>\` to begin a new workflow."
+    exit 1
+  fi
+
+  # Extract workflow name from session
+  WORKFLOW_NAME=$(grep -E "^\*\*Workflow:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/\*\*Workflow:\*\* //' | tr -d ' ')
+
+  if [[ -z "$WORKFLOW_NAME" ]]; then
+    # Try extracting from filename
+    WORKFLOW_NAME=$(basename "$SESSION_FILE" | sed 's/-workflow-session.md//')
+  fi
+else
+  SESSION_FILE="$SESSION_DIR/${WORKFLOW_NAME}-workflow-session.md"
+fi
+
+if [[ ! -f "$SESSION_FILE" ]]; then
+  echo "Error: No session found for workflow '$WORKFLOW_NAME'"
+  echo ""
+  echo "Use \`/workflow start $WORKFLOW_NAME\` to begin."
+  exit 1
+fi
+
+# Find workflow file
+WORKFLOW_FILE=""
+if [[ -f "$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml" ]]; then
+  WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml"
+elif [[ -f "$WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml" ]]; then
+  WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}/workflow.yaml"
+else
+  echo "Error: Workflow definition '$WORKFLOW_NAME' not found"
+  exit 1
+fi
+
+WORKFLOW_DIR=$(dirname "$WORKFLOW_FILE")
+
+# Parse session state
+CURRENT_STEP=$(grep -E "^\- \*\*Current Step:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "1")
+MODE=$(grep -E "^\- \*\*Mode:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "create")
+STATUS=$(grep -E "^\- \*\*Status:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "in_progress")
+STEPS_COMPLETED=$(grep -E "^\- \*\*Steps Completed:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' || echo "[]")
+
+# Check if workflow is complete
+if [[ "$STATUS" == "completed" ]]; then
+  echo "# Workflow Complete: $WORKFLOW_NAME"
+  echo ""
+  echo "This workflow has already been completed."
+  echo ""
+  echo "To start a new session, delete the session file:"
+  echo "\`\`\`bash"
+  echo "rm \"$SESSION_FILE\""
+  echo "\`\`\`"
+  echo ""
+  echo "Then run \`/workflow start $WORKFLOW_NAME\`"
+  exit 0
+fi
+
+# Resolve steps path based on mode
+MODE_PATH=$(yq eval ".workflow.modes.$MODE // \"\"" "$WORKFLOW_FILE")
+if [[ -n "$MODE_PATH" && "$MODE_PATH" != "null" ]]; then
+  STEPS_PATH="$MODE_PATH"
+else
+  STEPS_PATH=$(yq eval '.workflow.steps.path' "$WORKFLOW_FILE")
+fi
+
+# Resolve relative path
+if [[ "$STEPS_PATH" == ./* ]]; then
+  STEPS_PATH="$WORKFLOW_DIR/${STEPS_PATH#./}"
+elif [[ "$STEPS_PATH" != /* ]]; then
+  STEPS_PATH="$PROJECT_ROOT/$STEPS_PATH"
+fi
+
+# Count steps
+STEP_COUNT=$(find "$STEPS_PATH" -maxdepth 1 -name "step-0*.md" -o -name "step-1*.md" 2>/dev/null | wc -l | tr -d ' ')
+
+# Find the current step file
+# Handle various naming: step-01.md, step-01-name.md, step-1-name.md
+PADDED_STEP=$(printf "%02d" "$CURRENT_STEP")
+STEP_FILE=$(find "$STEPS_PATH" -maxdepth 1 \( -name "step-${PADDED_STEP}*.md" -o -name "step-${CURRENT_STEP}-*.md" \) 2>/dev/null | sort | head -1)
+
+if [[ -z "$STEP_FILE" ]]; then
+  echo "Error: Could not find step $CURRENT_STEP file in $STEPS_PATH"
+  exit 1
+fi
+
+# Update last updated timestamp
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+sed -i '' "s/^\- \*\*Last Updated:\*\*.*/- **Last Updated:** $NOW/" "$SESSION_FILE" 2>/dev/null || true
+
+# Calculate completion percentage
+COMPLETED_COUNT=$(echo "$STEPS_COMPLETED" | tr -cd ',' | wc -c | tr -d ' ')
+if [[ "$STEPS_COMPLETED" != "[]" ]]; then
+  COMPLETED_COUNT=$((COMPLETED_COUNT + 1))
+fi
+if [[ "$STEP_COUNT" -gt 0 ]]; then
+  COMPLETION_PCT=$((COMPLETED_COUNT * 100 / STEP_COUNT))
+else
+  COMPLETION_PCT=0
+fi
+
+# Output resume info
+echo "# Resuming Workflow: $WORKFLOW_NAME"
+echo ""
+echo "**Mode:** $MODE"
+echo "**Progress:** Step $CURRENT_STEP of $STEP_COUNT ($COMPLETION_PCT% complete)"
+echo "**Steps Completed:** $STEPS_COMPLETED"
+echo "**Session:** $SESSION_FILE"
+echo ""
+echo "---"
+echo ""
+echo "## Step $CURRENT_STEP of $STEP_COUNT"
+echo ""
+
+# Output step content (strip frontmatter if present)
+if head -1 "$STEP_FILE" | grep -q "^---$"; then
+  awk '/^---$/{if(++c==2){p=1;next}}p' "$STEP_FILE"
+else
+  cat "$STEP_FILE"
+fi
+
+echo ""
+echo "---"
+echo ""
+echo "**Controls:**"
+echo "- \`C\` - Continue to next step"
+echo "- \`/workflow status\` - Check progress"

package/pennyfarthing-dist/scripts/workflow/show-workflow.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+# Show workflow details
+# Usage: .pennyfarthing/scripts/core/run.sh workflow/show-workflow.sh [name]
+#    or: Invoked with PROJECT_ROOT already set
+#
+# If no name provided, shows current session's workflow
+# If name provided, shows that workflow's details
+
+set -euo pipefail
+
+# PROJECT_ROOT should be set by run.sh, but find it if not
+if [[ -z "${PROJECT_ROOT:-}" ]]; then
+  d="$PWD"
+  while [[ ! -d "$d/.claude" ]] && [[ "$d" != "/" ]]; do
+    d="$(dirname "$d")"
+  done
+  PROJECT_ROOT="$d"
+fi
+
+WORKFLOWS_DIR="$PROJECT_ROOT/pennyfarthing-dist/workflows"
+SESSION_DIR="$PROJECT_ROOT/.session"
+
+if ! command -v yq &> /dev/null; then
+  echo "Error: yq is required but not installed"
+  echo "Install with: brew install yq"
+  exit 1
+fi
+
+# Get workflow name from argument or session
+WORKFLOW_NAME="${1:-}"
+
+if [[ -z "$WORKFLOW_NAME" ]]; then
+  # Try to get from current session (exclude archive directory)
+  SESSION_FILE=$(find "$SESSION_DIR" -maxdepth 1 -name "*-session.md" 2>/dev/null | head -1)
+  if [[ -n "$SESSION_FILE" ]]; then
+    # Extract workflow from session file (look for **Workflow:** line)
+    WORKFLOW_NAME=$(grep -E "^\*\*Workflow:\*\*" "$SESSION_FILE" 2>/dev/null | sed 's/.*\*\* //' | tr -d ' ' || echo "")
+    if [[ -z "$WORKFLOW_NAME" ]]; then
+      # Try alternate format (Workflow: value in tracking section)
+      WORKFLOW_NAME=$(grep -E "^Workflow:" "$SESSION_FILE" 2>/dev/null | head -1 | cut -d: -f2 | tr -d ' ' || echo "")
+    fi
+  fi
+
+  if [[ -z "$WORKFLOW_NAME" ]]; then
+    echo "# Current Workflow"
+    echo ""
+    echo "No active session found. Showing default workflow (tdd)."
+    echo ""
+    WORKFLOW_NAME="tdd"
+  else
+    echo "# Current Session Workflow: $WORKFLOW_NAME"
+    echo ""
+  fi
+else
+  echo "# Workflow: $WORKFLOW_NAME"
+  echo ""
+fi
+
+WORKFLOW_FILE="$WORKFLOWS_DIR/${WORKFLOW_NAME}.yaml"
+
+if [[ ! -f "$WORKFLOW_FILE" ]]; then
+  echo "Error: Workflow '$WORKFLOW_NAME' not found"
+  echo ""
+  echo "Available workflows:"
+  for f in "$WORKFLOWS_DIR"/*.yaml; do
+    [[ -f "$f" ]] || continue
+    basename "$f" .yaml
+  done
+  exit 1
+fi
+
+# Extract workflow details
+DESC=$(yq eval '.workflow.description' "$WORKFLOW_FILE")
+VERSION=$(yq eval '.workflow.version' "$WORKFLOW_FILE")
+
+echo "**Description:** $DESC"
+echo "**Version:** $VERSION"
+echo ""
+
+# Show phases as a flow diagram
+echo "## Phase Flow"
+echo ""
+echo -n "\`\`\`"
+echo ""
+
+# Build phase flow string
+PHASES=""
+yq eval '.workflow.phases[].name' "$WORKFLOW_FILE" | while read -r phase; do
+  if [[ -n "$PHASES" ]]; then
+    echo -n " -> "
+  fi
+  echo -n "$phase"
+  PHASES="$phase"
+done
+echo ""
+echo "\`\`\`"
+echo ""
+
+# Show phases table
+echo "## Phases"
+echo ""
+echo "| Phase | Agent | Gate |"
+echo "|-------|-------|------|"
+
+yq eval '.workflow.phases[] | .name + "|" + .agent + "|" + (.gate.type // "none")' "$WORKFLOW_FILE" | while IFS='|' read -r phase agent gate; do
+  echo "| $phase | $agent | $gate |"
+done
+
+echo ""
+
+# Show triggers
+echo "## Triggers"
+echo ""
+
+TYPES=$(yq eval '.workflow.triggers.types // []' "$WORKFLOW_FILE")
+if [[ "$TYPES" != "[]" && "$TYPES" != "null" ]]; then
+  echo "**Types:** $(yq eval '.workflow.triggers.types | join(", ")' "$WORKFLOW_FILE")"
+fi
+
+POINTS_MIN=$(yq eval '.workflow.triggers.points.min // ""' "$WORKFLOW_FILE")
+POINTS_MAX=$(yq eval '.workflow.triggers.points.max // ""' "$WORKFLOW_FILE")
+
+if [[ -n "$POINTS_MIN" && "$POINTS_MIN" != "null" ]]; then
+  echo "**Points Min:** $POINTS_MIN"
+fi
+if [[ -n "$POINTS_MAX" && "$POINTS_MAX" != "null" ]]; then
+  echo "**Points Max:** $POINTS_MAX"
+fi
+
+IS_DEFAULT=$(yq eval '.workflow.triggers.default // false' "$WORKFLOW_FILE")
+if [[ "$IS_DEFAULT" == "true" ]]; then
+  echo "**Default:** yes (used when no other workflow matches)"
+fi
+
+TAGS=$(yq eval '.workflow.triggers.tags // []' "$WORKFLOW_FILE")
+if [[ "$TAGS" != "[]" && "$TAGS" != "null" ]]; then
+  echo "**Tags:** $(yq eval '.workflow.triggers.tags | join(", ")' "$WORKFLOW_FILE")"
+fi