/nav-workflow

name: nav-workflow
description: Unified workflow orchestration for substantial tasks. Auto-detects complexity, defers to matching skills, or provides phase-based execution. Solves workflow conflicts between skills, loop mode, and CLAUDE.md.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
version: 1.0.0

Navigator Task Mode Skill

Unified workflow orchestration that coordinates between skills, loop mode, and direct execution based on task complexity and type.

Why This Exists

Navigator had three disconnected workflow systems: 1. **Skills** (frontend-component, etc.) - have mini-workflows (Step 1 → Step 7) 2. **Loop Mode** - separate phase system (INIT → COMPLETE) 3. **CLAUDE.md** - documents workflow nobody enforces

**Result**: Conflicts when multiple systems try to run.

**Solution**: Task Mode acts as a coordinator - detecting when skills should handle workflow vs when to provide standalone phase guidance.

How It Works

User Request
    ↓
TASK MODE (this skill)
    ├─ Simple task? → Direct execution (no overhead)
    ├─ Skill matches? → Let skill run (it has workflow)
    └─ Substantial, no skill? → Task Mode phases

When to Invoke

**Auto-invoke when**:

• User starts substantial work (3+ steps expected)
• No obvious skill match (not "create component", "add endpoint", etc.)
• Request involves planning, refactoring, or multi-file changes
• Loop mode is disabled but structured execution needed

**DO NOT invoke if**:

• Trivial task (typo fix, single line change)
• Skill will clearly handle it (component creation, endpoint, migration, etc.)
• User says "quick", "just do", "simple fix"
• Already in Task Mode or Loop Mode

Configuration

Task Mode settings in `.agent/.nav-config.json`:

{
  "task_mode": {
    "enabled": true,
    "auto_detect": true,
    "defer_to_skills": true,
    "complexity_threshold": 0.5,
    "show_phase_indicator": true
  }
}

**Options**:

• `enabled`: Master switch for Task Mode
• `auto_detect`: Auto-detect complexity (vs explicit invocation only)
• `defer_to_skills`: Let matching skills handle their own workflow
• `complexity_threshold`: Score (0-1) required to activate
• `show_phase_indicator`: Show phase banners during execution

Execution Steps

Step 1: Analyze Request

**Run complexity detection**:

python3 functions/complexity_detector.py \
  --request "{USER_REQUEST}" \
  --context "{RECENT_CONTEXT}"

**Complexity signals**:

• Multi-file changes expected (+0.3)
• Planning language ("implement", "refactor", "add feature") (+0.2)
• Vague requirements needing research (+0.2)
• Cross-system changes (frontend+backend) (+0.3)
• Testing requirements mentioned (+0.1)

**Simple task signals**:

• Single file mentioned (-0.3)
• Fix/typo/update language (-0.2)
• Specific location given (-0.2)
• "Quick" or "simple" mentioned (-0.3)

**Decision**:

IF complexity_score < threshold:
  → Direct execution (exit Task Mode)

Step 2: Check Skill Match

**Run skill detection**:

python3 functions/skill_detector.py \
  --request "{USER_REQUEST}" \
  --available-skills "{SKILLS_LIST}"

**Skill matching rules**:

• "create component" → frontend-component
• "add endpoint" → backend-endpoint
• "database migration" → database-migration
• "write test" → backend-test/frontend-test
• etc.

**Decision**:

IF matching_skill AND defer_to_skills:
  → Show: "Detected: {SKILL_NAME} skill will handle this"
  → Exit Task Mode (skill has workflow)

Step 3: Initialize Task Mode

**If substantial task, no skill match**:

**Display activation**:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TASK MODE ACTIVATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task: {TASK_SUMMARY}
Complexity: {SCORE} (threshold: {THRESHOLD})
Skills matched: None (Task Mode will orchestrate)

Phases:
  ○ RESEARCH - Understand requirements
  ○ PLAN - Create implementation strategy
  ○ IMPL - Execute changes
  ○ VERIFY - Test and validate
  ○ COMPLETE - Commit and document

Starting RESEARCH phase...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 4: Execute Phases

**RESEARCH Phase**:

• Use Task agent for codebase exploration
• Identify affected files
• Find existing patterns
• Document unknowns

**Show phase transition**:

python3 functions/phase_indicator.py \
  --phase "RESEARCH" \
  --status "complete" \
  --next "PLAN"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE: RESEARCH → PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Research completed:
  ✓ Found {N} related files
  ✓ Identified patterns in {LOCATION}
  ✓ Dependencies mapped

Moving to PLAN phase...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**PLAN Phase**:

• Create TodoWrite items
• Identify order of changes
• Document approach

**IMPL Phase**:

• Execute planned changes
• Follow project patterns
• Write tests as appropriate

**VERIFY Phase**:

• Run tests
• Type check
• Build validation
• **Run nav-simplify** (if enabled)

**COMPLETE Phase**:

• Commit changes
• Update documentation
• Close tickets (if PM configured)
• Suggest compact

Step 5: Complete Task Mode

**Display completion**:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TASK MODE COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task: {TASK_SUMMARY}
Phases:
  ✓ RESEARCH - {DURATION}
  ✓ PLAN - {DURATION}
  ✓ IMPL - {DURATION}
  ✓ VERIFY - {DURATION}
  ✓ COMPLETE

Summary:
- {FILES_CHANGED} files changed
- {TESTS_ADDED} tests added
- Committed: {COMMIT_SHA}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Predefined Functions

functions/complexity_detector.py

Analyzes request to determine complexity score.

**Usage**:

python3 functions/complexity_detector.py \
  --request "Refactor the auth system to use JWT" \
  --context "Working on user management"

**Returns**:

{
  "complexity_score": 0.7,
  "signals": {
    "multi_file": true,