Task Mode (task_mode)

Task Mode is unified workflow orchestration for substantial work. It auto-detects complexity, defers to a matching skill when one applies, and otherwise drives a lightweight phase sequence — resolving conflicts between skills, Loop Mode, and the CLAUDE.md workflow that previously competed to run.

Config block

In .agent/.nav-config.json:


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

Keys

enabled (default true) — master switch for Task Mode.
auto_detect (default true) — score complexity automatically; when false, Task Mode only runs on explicit invocation.
defer_to_skills (default true) — let a matching skill run its own workflow instead of layering Task Mode phases on top. Set false to always use phases.
complexity_threshold (default 0.5) — score from 0–1 a request must reach to activate. Multi-file changes, planning language, and cross-system work push it up; “quick”, “fix typo”, and single-file mentions push it down.
show_phase_indicator (default true) — render the phase banners during execution.

As of v7.0.0, activation scoring runs at prompt-submit time via the prompt_gate op of the hook runtime (off-switch: workflow_enforcer_hook.enabled) — not via a WORKFLOW CHECK prose mandate, which is retired.

Phases

When Task Mode activates, it runs five phases:


RESEARCH → PLAN → IMPL → VERIFY → COMPLETE

RESEARCH — explore the codebase (via the research agent), map affected files and patterns.
PLAN — build the change list, order the work, capture the approach.
IMPL — execute changes following project conventions.
VERIFY — run tests and type checks; run nav-simplify if enabled.
COMPLETE — commit, document, close tickets, suggest compact (autonomous protocol).

Activate vs defer vs direct


User Request
    ├─ Below threshold?         → Direct execution (no overhead)
    ├─ Matching skill found?    → Skill runs its own workflow
    └─ Substantial, no skill?   → Task Mode phases

Task Mode vs Loop Mode

Task Mode is lighter weight. Loop Mode adds strict iteration control, stagnation detection, and an explicit EXIT_SIGNAL gate; Task Mode just provides phase structure and skill coordination. They can coexist — Loop Mode wraps Task Mode phases when both are active. Use Loop Mode for “run until done” autonomous work, Task Mode for a substantial feature that needs structure but not strict gating.

Phase timing and progress are instrumented with OpenTelemetry — run /nav:stats to see your own session metrics.

Example


User: "Refactor auth to use JWT instead of sessions"

→ Complexity: 0.8, no skill match → Task Mode activates
→ RESEARCH: explore current auth implementation
→ PLAN: document JWT migration steps
→ IMPL: execute changes across files
→ VERIFY: run tests, simplify code
→ COMPLETE: commit, document