Agent skill

workflow-detection

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/workflow-detection

SKILL.md

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
# 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:

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

Fields

Field Values Description
type epic, feature, unknown Workflow type
base_dir epics, specs, unknown Base directory for artifacts
slug string Feature/epic identifier (e.g., 001-auth-system)
branch string Current git branch
source files, branch, state, none How type was detected
is_worktree boolean Whether in a git worktree

Worktree Fields (when is_worktree: true)

Field Description
worktree_path Absolute path to worktree
worktree_type epic, feature, or unknown
worktree_slug Extracted slug from worktree path

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)

yaml
# 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:

bash
$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:

markdown
**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:

bash
# Standard workflow
FEATURE_DIR="specs/$SLUG"

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

Exit Codes

Code Meaning
0 Detection successful
1 Detection failed (use fallback)

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

markdown
**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:

markdown
### 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

Before After
40+ lines inline in each command 10 lines referencing skill
Duplicated across 9 commands Single source of truth
Changes require 9 file edits Changes require 1 skill edit
360+ total lines ~90 total lines

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results