Workflow Detection

Workflow Detection Skill

Provides centralized workflow type detection for all phase and deployment commands.

Purpose

Eliminates 50+ lines of duplicated detection code across 44 commands by providing a single source of truth for workflow type detection.

Quick Reference

# Bash (Linux/Mac/Git Bash)
WORKFLOW_INFO=$(bash .spec-flow/scripts/utils/detect-workflow-paths.sh)

# PowerShell (Windows)
$workflowInfo = pwsh -File .spec-flow/scripts/utils/detect-workflow-paths.ps1

Output Format

Returns JSON with workflow information:

{
  "type": "epic",
  "base_dir": "epics",
  "slug": "001-auth-system",
  "branch": "epic/001-auth-system",
  "source": "files",
  "is_worktree": false
}

Fields

Worktree Fields (when is_worktree: true)

Detection Priority

1. Workspace Files (highest priority)

   • Checks for epics/*/epic-spec.md → Epic workflow
   • Checks for specs/*/spec.md → Feature workflow

2. Git Branch Pattern

   • Branch matches epic/* → Epic workflow
   • Branch matches feature/* → Feature workflow

3. Workflow State

   • Reads workflow_type from state.yaml

4. User Prompt (detection failed)

   • Returns type: unknown with exit code 1
   • Command should use AskUserQuestion as fallback

Usage in Commands

Standard Pattern (Recommended)

# In command's <process> section:

### Step 0: Workflow Type Detection

**Detect workflow type using centralized utility:**

<bash>
# Cross-platform detection
if command -v bash >/dev/null 2>&1; then
    WORKFLOW_INFO=$(bash .spec-flow/scripts/utils/detect-workflow-paths.sh 2>/dev/null)
elif command -v pwsh >/dev/null 2>&1; then
    WORKFLOW_INFO=$(pwsh -File .spec-flow/scripts/utils/detect-workflow-paths.ps1 2>/dev/null)
fi

if [ -n "$WORKFLOW_INFO" ]; then
    WORKFLOW_TYPE=$(echo "$WORKFLOW_INFO" | grep -o '"type":"[^"]*"' | cut -d'"' -f4)
    BASE_DIR=$(echo "$WORKFLOW_INFO" | grep -o '"base_dir":"[^"]*"' | cut -d'"' -f4)
    SLUG=$(echo "$WORKFLOW_INFO" | grep -o '"slug":"[^"]*"' | cut -d'"' -f4)
fi
</bash>

**If detection fails, prompt user:**

Use AskUserQuestion with options: "Epic workflow", "Feature workflow"

Path Variables

After detection, use these standardized variables:

$WORKFLOW_TYPE  # "epic" or "feature"
$BASE_DIR       # "epics" or "specs"
$SLUG           # "001-auth-system"
$SPEC_FILE      # "${BASE_DIR}/${SLUG}/epic-spec.md" or "spec.md"
$PLAN_FILE      # "${BASE_DIR}/${SLUG}/plan.md"
$TASKS_FILE     # "${BASE_DIR}/${SLUG}/tasks.md"
$STATE_FILE     # "${BASE_DIR}/${SLUG}/state.yaml"
$NOTES_FILE     # "${BASE_DIR}/${SLUG}/NOTES.md"

Commands Using This Skill

Phase Commands

• /clarify - Locates correct spec file
• /plan - Reads from correct workspace
• /tasks - Generates tasks in correct location
• /validate - Validates artifacts in correct directory
• /implement - Executes tasks from detected workspace
• /optimize - Determines gate count (6 for features, 10 for epics)
• /finalize - Archives to correct completed/ directory

Deployment Commands

• /ship - Routes to correct deployment workflow
• /ship-staging - Uses correct workspace for PR
• /ship-prod - Promotes correct branch
• /deploy-prod - Deploys from correct source

Epic Commands

• /epic continue - Detects and resumes epic workspace
• /implement-epic - Reads sprint plan from epics/ directory

Error Handling

Detection Failure

When detection returns type: unknown:

**Detection failed. Ask user:**

<AskUserQuestion>
question: "What type of workflow are you working on?"
options:
  - label: "Epic workflow"
    description: "Multi-sprint project in epics/ directory"
  - label: "Feature workflow"
    description: "Single feature in specs/ directory"
</AskUserQuestion>

Worktree Handling

When is_worktree: true, paths are relative to worktree root:

# Standard workflow
FEATURE_DIR="specs/$SLUG"

# Worktree workflow (same path structure, different root)
FEATURE_DIR="specs/$SLUG"  # Still works, relative to worktree

Exit Codes

Cross-Platform Notes

• Windows: Requires Git Bash or PowerShell with pwsh
• macOS/Linux: Uses bash directly
• CI/CD: Works in GitHub Actions, GitLab CI, etc.

Related Files

• .spec-flow/scripts/utils/detect-workflow-paths.sh - Bash implementation
• .spec-flow/scripts/utils/detect-workflow-paths.ps1 - PowerShell implementation
• .spec-flow/scripts/bash/shared-lib.sh - Contains detect_workflow_type() helper

Compact Detection Pattern (v11.2)

For phase commands to use instead of inline 40-line blocks:

In Command Context Section

**Workflow Detection**: !`bash .spec-flow/scripts/utils/detect-workflow-paths.sh 2>/dev/null || echo '{"type":"unknown"}'`

In Command Process Section (Step 0)

Replace 40+ lines of inline detection with this compact reference:

### Step 0: Workflow Detection

**Detect workflow using centralized skill** (see `.claude/skills/workflow-detection/SKILL.md`):

1. Run detection: `bash .spec-flow/scripts/utils/detect-workflow-paths.sh`
2. Parse JSON: Extract `type`, `base_dir`, `slug` from output
3. If detection fails (exit code != 0): Use AskUserQuestion fallback
4. Set paths:
   - Feature: `SPEC_FILE="${BASE_DIR}/${SLUG}/spec.md"`
   - Epic: `SPEC_FILE="${BASE_DIR}/${SLUG}/epic-spec.md"`

**Fallback prompt** (if detection fails):
- Question: "Which workflow are you working on?"
- Options: "Feature" (specs/), "Epic" (epics/)

Why This Pattern

Migration Guide

To convert existing commands:

1. Remove the inline bash block in Step 0
2. Add the compact reference pattern above
3. Update context section with dynamic detection
4. Verify detection still works with test runs