flows

Flows

Prerequisites

This fork uses git stage-lines and git unstage-lines for granular staging control, which is essential for parallel agent workflows. These are custom git aliases that require setup.

Quick Setup (Recommended)

Run the automated setup script:

bash ~/tools/flows/setup.sh

This will install patchutils (if needed) and configure the git aliases automatically.

Manual Setup

If you prefer to set up manually:

1. Install patchutils

brew install patchutils

This provides the filterdiff command used by the git aliases.

2. Configure git aliases

Add these aliases to your global git configuration:

git config --global alias.stage-lines '!f() {
  # Handle parameter patterns
  if [ -z "$2" ]; then
    file="$1"
    lines=""
  else
    lines="$1"
    file="$2"
  fi

  # Check if file is tracked
  if git ls-files --error-unmatch "$file" 2>/dev/null; then
    # Tracked file: require line ranges
    if [ -z "$lines" ]; then
      echo "Error: Please specify line ranges (e.g., 1-5,8,10-12)" >&2
      echo "Usage: git stage-lines <lines> <file>" >&2
      echo "       git stage-lines <untracked-file>" >&2
      return 1
    fi
    # Use filterdiff for line-level staging
    git diff "$file" | filterdiff --lines="$lines" | git apply --cached --unidiff-zero
  else
    # Untracked file: stage entire file
    git add "$file"
  fi
}; f'

git config --global alias.unstage-lines '!f() {
  # Handle parameter patterns
  if [ -z "$2" ]; then
    file="$1"
    lines=""
  else
    lines="$1"
    file="$2"
  fi

  # Check if file is newly added
  if git diff --cached --diff-filter=A --name-only | grep -qx "$file"; then
    # Newly added file: remove from index, make untracked
    git rm --cached "$file"
  else
    # Partial staged changes: require line ranges
    if [ -z "$lines" ]; then
      echo "Error: Please specify line ranges (e.g., 1-5,8,10-12)" >&2
      echo "Usage: git unstage-lines <lines> <file>" >&2
      echo "       git unstage-lines <newly-added-file>" >&2
      return 1
    fi
    # Use filterdiff reverse for line-level unstaging
    git diff --cached "$file" | filterdiff --lines="$lines" | git apply --cached --unidiff-zero --reverse
  fi
}; f'

3. Verify setup

Check that aliases are configured:

git config --global --get-regexp "alias\.(stage-lines|unstage-lines)"

You should see output showing the configured aliases (formatting may vary).

Usage

The commands automatically detect file state and apply the appropriate staging behavior:

For tracked files with changes (requires line ranges):

# Stage specific lines from a tracked file
git stage-lines 10-25 path/to/file.py

# Unstage specific lines from staged changes
git unstage-lines 15-20 path/to/file.py

For untracked or newly-added files (line ranges optional):

# Stage an entire untracked file
git stage-lines new-file.js

# Unstage a newly-added file (makes it untracked again)
git unstage-lines new-file.js

The commands detect whether a file is tracked or untracked and automatically use the appropriate staging method. For tracked files, line ranges are required to enable granular control. For untracked files, the entire file is staged.

This allows multiple parallel agents to work on the same files and stage only their specific changes without conflicts.

Web-Researcher Agent

Flows includes an intelligent web research agent that automatically activates when you need current external information.

Automatic Triggering

The agent activates when you mention research keywords:

• "research online..."
• "web search for..."
• "search the web..."
• "look up online..."
• "find information about..."
• "@agent-web-researcher"

Manual Invocation

Explicitly invoke the agent in any context:

@agent-web-researcher find the latest Next.js 14 app router patterns

Research Capabilities

The web-researcher agent:

• Searches official documentation and authoritative sources
• Fetches and analyzes current API specifications
• Finds real-world examples and GitHub repositories
• Verifies version-specific information
• Provides sourced summaries with direct links

Use Cases

• Debugging: Research unfamiliar error messages and platform issues
• Design: Compare frameworks and find modern best practices
• Planning: Verify API syntax and integration patterns
• Reviews: Validate technical claims with authoritative sources
• Skills: Source current documentation for reference skills

The agent is integrated throughout flows skills with strategic invocation points in debugging, brainstorming, planning, and skill-creation workflows.

Concurrent-Safe Code Review

Flows includes a concurrent-safe code review system designed for environments where multiple agents or humans work simultaneously.

The Problem