@pennyfarthing/core 7.5.0 → 7.6.1

package/pennyfarthing-dist/skills/theme/skill.md

@@ -0,0 +1,129 @@
+---
+name: theme
+description: Manage persona themes - list available themes, show current/specific theme details, and set active theme. Use when switching persona themes, viewing available characters, or checking which theme is currently active.
+---
+
+# Theme Management Skill
+
+## Overview
+
+Pennyfarthing uses themed personas to give each agent a unique character. This skill provides commands to list, view, and change themes.
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| List all themes | `/list-themes` or see below |
+| Show current theme | `/show-theme` |
+| Show specific theme | `/show-theme <name>` |
+| Set active theme | `/set-theme <name>` |
+| Create new theme | `/theme-maker` (interactive) |
+
+## List Available Themes
+
+To see all available themes:
+
+```bash
+ls pennyfarthing-dist/personas/themes/*.yaml | xargs -I{} basename {} .yaml | sort
+```
+
+To show the current theme:
+
+```bash
+cat .pennyfarthing/config.local.yaml 2>/dev/null || echo "No theme configured"
+```
+
+## Show Theme Details
+
+To display a theme's agent mappings:
+
+```bash
+# Show current theme
+THEME=$(cat .pennyfarthing/config.local.yaml 2>/dev/null | grep "^theme:" | cut -d'"' -f2)
+cat pennyfarthing-dist/personas/themes/${THEME}.yaml
+```
+
+Or for a specific theme:
+
+```bash
+cat pennyfarthing-dist/personas/themes/<theme-name>.yaml
+```
+
+## Set Active Theme
+
+To change the active theme:
+
+1. Verify theme exists:
+   ```bash
+   ls pennyfarthing-dist/personas/themes/<name>.yaml
+   ```
+
+2. Read current config:
+   ```bash
+   cat .pennyfarthing/config.local.yaml 2>/dev/null || echo "FILE_NOT_FOUND"
+   ```
+
+3. Update `.pennyfarthing/config.local.yaml`:
+   - If file exists with `theme:` line: Use Edit tool to replace `theme: <old>` with `theme: <new>`
+   - If file missing or no theme line: Use Write tool to create:
+     ```yaml
+     # Pennyfarthing Local Configuration
+     theme: <name>
+     ```
+
+4. Verify the write succeeded:
+   ```bash
+   cat .pennyfarthing/config.local.yaml
+   ```
+
+5. Start a new agent session to use the new theme
+
+## Theme File Locations
+
+| Location | Purpose |
+|----------|---------|
+| `pennyfarthing-dist/personas/themes/` | Built-in themes (96+) |
+| `.claude/pennyfarthing/themes/` | User-created custom themes |
+| `.pennyfarthing/config.local.yaml` | Theme selection (agent-writable, gitignored) |
+
+## Theme Structure
+
+Each theme YAML defines agents with:
+
+```yaml
+theme:
+  name: theme-name
+  description: Brief description
+
+agents:
+  sm:
+    character: Character Name
+    style: Communication style description
+    quote: Signature quote
+    trait: Key personality trait
+    helper: Helper/assistant description
+  tea:
+    # ...same structure...
+  dev:
+    # ...
+```
+
+## Creating Custom Themes
+
+For creating new themes, use `/theme-maker` which provides:
+- **AI-Driven Mode**: Describe a concept, AI generates all personas
+- **Guided Mode**: Pick from AI-suggested characters
+- **Manual Mode**: Specify every detail yourself
+
+See the `theme-creation` skill for full documentation.
+
+## Common Theme Categories
+
+Themes are available across many categories:
+- **TV/Film**: star-trek-tos, star-trek-tng, breaking-bad, the-wire, firefly, etc.
+- **Literature**: shakespeare, jane-austen, dickens, discworld, dune, etc.
+- **Historical**: ancient-philosophers, military-commanders, renaissance-masters, etc.
+- **Mythology**: greek-mythology, norse-mythology, arthurian-mythos, etc.
+- **Animated**: futurama, the-simpsons, avatar-the-last-airbender, etc.
+
+Run the list command to see all 96+ available themes.

package/pennyfarthing-dist/skills/theme-creation/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: theme-creation
+description: Create custom persona themes for Pennyfarthing. Use when users want to create, generate, or customize agent personas/themes, especially with AI-driven generation.
+---
+
+# Theme Creation Skill
+
+## Overview
+
+This skill covers creating custom persona themes for Pennyfarthing agents. Themes define how each agent (SM, TEA, Dev, Reviewer, etc.) presents themselves with character names, styles, quotes, and personality traits.
+
+## When to Use This Skill
+
+**Invoke `/theme-maker` when the user:**
+- Asks to "create a theme" or "make a theme"
+- Wants "AI-driven theme generation"
+- Says "generate personas" or "generate characters"
+- Mentions a fictional universe and wants agents based on it
+- Asks for "custom personas" or "themed agents"
+- Wants to "customize agent characters"
+- Mentions any fictional universe + "theme" (e.g., "Star Wars theme", "pirates theme")
+
+**Trigger phrases:**
+- "create a [X] theme"
+- "make a theme based on [X]"
+- "generate [X] personas"
+- "I want [X] themed agents"
+- "AI-driven theme generation"
+- "custom theme for [universe]"
+
+## Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/theme-maker` | Interactive wizard with AI-driven, Guided, or Manual modes |
+| `/create-theme <name>` | Quick CLI-based theme creation (copies from base) |
+| `/set-theme <name>` | Activate an existing theme |
+| `/list-themes` | Show available themes |
+| `/show-theme <name>` | Display theme details |
+
+## Theme Creation Modes
+
+### AI-Driven Mode (Recommended)
+
+Best for: Users who describe a concept and want the AI to generate everything.
+
+**Flow:**
+1. User provides universe/concept (e.g., "Gilligan's Island, humorous")
+2. AI generates all 10 agent personas automatically
+3. User previews and confirms or regenerates
+4. Theme file written to `.claude/pennyfarthing/themes/`
+
+**What gets generated:**
+- Character names fitting the universe
+- OCEAN personality profiles (O/C/E/A/N scores 1-5)
+- Communication styles
+- Signature quotes
+- Emojis and visual descriptions
+- Helper assistants for each agent
+
+### Guided Mode
+
+Best for: Users who want to pick characters from suggestions.
+
+**Flow:**
+1. User provides universe/concept
+2. AI suggests 3-4 character options per agent
+3. User picks (or enters custom) for each
+4. AI fills in remaining details (style, quote, OCEAN)
+
+### Manual Mode
+
+Best for: Users who know exactly what they want.
+
+**Flow:**
+1. User provides theme description
+2. User enters character, style, quote for each agent
+3. Optional: Specify OCEAN scores or let AI generate
+4. Theme file created with user's exact specifications
+
+## Agent Roles Reference
+
+When generating or suggesting characters, match to these roles:
+
+| Agent | Role | Character Should Be |
+|-------|------|---------------------|
+| orchestrator | Meta-coordinator | Pattern-seer, guide, overseer |
+| sm | Scrum Master | Leader, coordinator, keeps team together |
+| tea | Test Engineer | Analyst, detail-oriented, finds flaws |
+| dev | Developer | Builder, practical, gets things done |
+| reviewer | Code Reviewer | Critical, honest, high standards |
+| architect | System Architect | Big-picture thinker, systems designer |
+| pm | Product Manager | Strategic, stakeholder manager |
+| tech-writer | Documentation | Clear communicator, precise |
+| ux-designer | UX Design | User advocate, feels the experience |
+| devops | Infrastructure | Reliable, keeps systems running |
+
+## Theme File Location
+
+- **User themes:** `.claude/pennyfarthing/themes/{name}.yaml`
+- **Built-in themes:** `pennyfarthing-dist/personas/themes/`
+
+## OCEAN Personality Profiles
+
+Each agent gets an OCEAN profile (Big Five personality traits):
+
+| Dimension | Low (1-2) | High (4-5) |
+|-----------|-----------|------------|
+| **O**penness | Traditional, practical | Creative, curious |
+| **C**onscientiousness | Flexible, spontaneous | Organized, disciplined |
+| **E**xtraversion | Reserved, reflective | Outgoing, energetic |
+| **A**greeableness | Competitive, skeptical | Cooperative, trusting |
+| **N**euroticism | Calm, stable | Emotional, reactive |
+
+## Examples
+
+### Example 1: AI-Driven Theme Creation
+
+**User:** "Create a Gilligan's Island theme, make it humorous"
+
+**Action:** Invoke `/theme-maker`, select AI-Driven mode, generate 10 agents based on the show's characters.
+
+### Example 2: Quick Theme from Base
+
+**User:** "Create a theme called my-team based on discworld"
+
+**Action:** Run `/create-theme my-team --base discworld`
+
+### Example 3: List and Switch Themes
+
+**User:** "What themes are available? Switch to star-trek."
+
+**Action:** Run `/list-themes`, then `/set-theme star-trek`
+
+## Validation Rules for Theme Names
+
+- Lowercase letters only
+- Must start with a letter
+- Hyphens allowed (no underscores or spaces)
+- No conflicts with existing themes
+
+## Portrait Generation
+
+Each agent can have a `visual` field that describes their appearance for portrait generation.
+
+**Generate all portraits for a theme:**
+```bash
+./scripts/generate-portraits.sh --theme {name}
+```
+
+**Generate a single agent's portrait:**
+```bash
+./scripts/generate-portraits.sh --theme {name} --role {role}
+```
+
+**Dry run (preview):**
+```bash
+./scripts/generate-portraits.sh --theme {name} --dry-run
+```
+
+**Requirements:**
+- Python 3 venv at `.venv/` with: `pip install diffusers transformers accelerate torch pillow pyyaml tqdm`
+- Apple Silicon Mac (MPS) or NVIDIA GPU (CUDA)
+- ~6.5GB model download on first run
+
+**Output:** `pennyfarthing-dist/personas/portraits/{theme}/{shortName}-{OCEAN}.png`
+
+## Post-Creation Steps
+
+After creating a theme:
+1. Theme file at `.claude/pennyfarthing/themes/{name}.yaml`
+2. Activate with `/set-theme {name}`
+3. Generate portraits with `./scripts/generate-portraits.sh --theme {name}`
+4. Edit YAML directly for fine-tuning

package/pennyfarthing-dist/skills/workflow/scripts/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/skills/workflow/scripts/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/skills/workflow/scripts/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