Smart Detection

Smart Detection is AgileFlow's Contextual Feature Router - a system that automatically analyzes your project state and recommends relevant features at the right moment in your workflow. Instead of memorizing 90+ commands, you work naturally and AgileFlow surfaces what you need.

Smart Detection is built into the /agileflow:babysit command and runs automatically as part of the context gathering pipeline.

Overview

AgileFlow has 155 commands and 149 agents. Most users only know about a handful. Smart Detection solves this discovery problem by:

1. Analyzing project signals - Git status, story state, test results, file changes
2. Detecting your workflow phase - Are you picking a story? Writing code? Ready for PR?
3. Running 42 feature detectors - Each checks if a specific feature is relevant right now
4. Recommending only what matters - Surfacing 2-5 contextual suggestions, not all 155 commands

The result: you get the right tool at the right time, without needing to know it exists.

How It Works

Architecture

Smart Detection runs as part of the obtain-context.js pipeline that powers /babysit:

Smart Detection pipeline: obtain-context.js gathers project data, smart-detect.js orchestrates signal extraction and lifecycle phase detection, 42 feature detectors run against signals filtered by phase, and recommendations are written to smart-detect.json for /babysit to act on.

All detection is deterministic and script-based - not LLM guesswork. The scripts analyze concrete signals (file existence, git status, story counts) and output structured recommendations.

The Three Steps

Step 1: Signal Extraction

The system gathers signals from your project:

Step 2: Lifecycle Phase Detection

Based on signals, the system determines which workflow phase you're in:

Phase detection uses a priority cascade - the most specific matching phase wins.

Step 3: Feature Detection

42 detectors run against your signals, filtered by lifecycle phase. Each detector either triggers (returning a recommendation) or stays silent (returning null). Only phase-relevant detectors run, keeping recommendations focused.

Lifecycle Phases

Pre-Story Phase

When you haven't selected a story yet, Smart Detection helps you choose:

Planning Phase

When you're designing your approach:

Implementation Phase

When you're actively writing code:

Post-Implementation Phase

When code is done and you're reviewing:

Pre-PR Phase

When you're ready to ship:

Recommendation Categories

Smart Detection categorizes recommendations into three groups:

Immediate (High Priority)

Features that need attention now. Presented via AskUserQuestion with the recommended action as the default option.

Examples:

• Tests are failing - run /agileflow:verify
• Blocked stories exist - run /agileflow:blockers
• 200 lines changed - run /agileflow:review

Available (Medium/Low Priority)

Features available but not urgent. Included as additional options in the next interaction prompt.

Examples:

• Dependency graph available - /agileflow:deps
• Sprint planning available - /agileflow:sprint
• Changelog entry recommended - /agileflow:changelog

Auto-Enabled Modes

Existing babysit modes that activate silently based on signals:

Example Output

When /babysit runs, the context output includes a Smart Recommendations section:

Smart Recommendations
Phase: implementation (5 files changed)

Immediate:
  ! verify: Tests are failing (/agileflow:verify)
  ! review: 250 lines changed - code review recommended (/agileflow:review)

Available:
  > docs: 2 API files changed - docs sync recommended (/agileflow:docs)
  > code-logic: 4 source files modified (/agileflow:code:logic)

Auto-enabled: loop mode, coverage mode

The babysit mentor then acts on these recommendations - presenting immediate items as suggested actions and including available items as options.

Configuration

Enabling/Disabling

Smart Detection is enabled by default. Configure it in docs/00-meta/agileflow-metadata.json:

Copy{
  "features": {
    "smartDetect": {
      "enabled": true,
      "disabled_features": [],
      "priority_overrides": {},
      "thresholds": {
        "impact_min_files": 3,
        "review_min_lines": 100,
        "compress_min_stories": 100
      }
    }
  }
}

Disabling Specific Features

If a detector is noisy for your project, disable it:

Copy{
  "smartDetect": {
    "disabled_features": ["ci", "deps", "changelog"]
  }
}

Adjusting Thresholds

Customize when detectors trigger:

Copy{
  "smartDetect": {
    "thresholds": {
      "impact_min_files": 5,
      "review_min_lines": 200,
      "compress_min_stories": 50
    }
  }
}

Priority Overrides

Change the priority of any feature:

Copy{
  "smartDetect": {
    "priority_overrides": {
      "docs": "high",
      "changelog": "medium"
    }
  }
}

Session State Tracking

Smart Detection tracks which features have been offered, used, and skipped during a session to avoid being repetitive:

Copy{
  "smart_detect": {
    "last_run": "2026-02-12T10:00:00Z",
    "current_phase": "implementation",
    "features_offered": ["impact", "tests"],
    "features_used": ["impact"],
    "features_skipped": ["tests"]
  }
}

• features_offered: Features presented to the user
• features_used: Features the user actually invoked
• features_skipped: Features the user declined (won't be re-offered)

User Overrides

Users can always override Smart Detection:

• Skip a feature: Say "skip tests" or "no review" - the feature won't be offered again this session
• Force a mode: /babysit MODE=once overrides auto-detected loop mode
• Disable visual: /babysit VISUAL=false overrides auto-detected visual mode
• Disable coverage: /babysit COVERAGE=0 overrides auto-detected coverage mode

Running Standalone

Smart Detection can be run independently for debugging:

Copynode .agileflow/scripts/smart-detect.js

This outputs a summary to stderr and writes the full results to docs/09-agents/smart-detect.json.

Architecture Details

Files

Detector Pattern

Each detector follows the same pattern:

Copy'feature-name': (signals) => {
  // Check if conditions are met
  if (!signals.story || signals.story.status !== 'in-progress') return null;
 
  // Return recommendation or null
  return {
    feature: 'feature-name',
    priority: 'high',        // high, medium, low
    trigger: 'Why this triggered',
    action: 'suggest',       // auto, suggest, offer
    command: '/agileflow:feature-name',
    phase: 'implementation',
  };
}

Detectors are pure functions: they take signals in, return a recommendation or null. No side effects, no I/O.

Phase Adjacency

To handle smooth transitions between phases, each phase also includes detectors from adjacent phases:

This ensures features aren't missed at phase boundaries.

Related Features

• Loop Mode - Autonomous story processing (auto-enabled by Smart Detection)
• Visual Mode - UI screenshot verification (auto-enabled by Smart Detection)
• Compact Context - Context preservation during long sessions
• Configuration - Configure Smart Detection thresholds
• Hooks System - The event system that Smart Detection integrates with