flowspace-research-v2

Please deep think / ultrathink as this is a complex task.

flowspace-research

A FlowSpace-first research worker designed to BE a parallel subagent—receiving a focused research query, using FlowSpace MCP tools optimally, and returning structured findings for parent orchestrator synthesis.

Key Characteristics:

• IS the subagent (does NOT launch subagents)
• FlowSpace-first with graceful fallback to traditional tools (Glob/Grep/Read)
• Multi-graph aware - searches across relevant graphs (local project, shared libs, vendor SDKs)
• Domain-boundary aware - loads docs/domains/ registry, tags findings with domain origin, maps graphs to domains
• Smart query detection (path/symbol/concept)
• Structured output for easy synthesis by parent commands

---

Input Parameters

$ARGUMENTS
# Required:
#   <query>              Research query (positional, required)
#
# Optional:
#   --scope <path>       Limit search to path (e.g., "src/auth/")
#   --exclude <pattern>  Exclude paths matching pattern (e.g., "test")
#   --limit <N>          Max findings to return (default: 10)
#   --mode <type>        Force query mode: path | symbol | concept | auto (default: auto)
#   --graph <name>       Query specific graph(s): "default", "shared-lib", "all", or comma-separated list
#                        Default: auto-select relevant graphs based on query
#
# Examples:
#   /flowspace-research "AuthService"
#   /flowspace-research "authentication flow" --scope "src/" --exclude "test"
#   /flowspace-research "src/services/" --mode path --limit 20
#   /flowspace-research "RedisCache" --graph "cache-lib"
#   /flowspace-research "config patterns" --graph "all"

---

Execution Flow

1) FlowSpace Detection (with Graceful Fallback)

Strategy: Try FlowSpace first for enhanced exploration, fall back to traditional tools (Glob/Grep/Read) if unavailable.

# Pseudo-code for detection
try:
    # Fast, minimal probe - tests MCP availability and graph existence
    result = flowspace.tree(pattern=".", max_depth=1)
    FLOWSPACE_AVAILABLE = True
    print("✅ FlowSpace MCP detected - using enhanced exploration")

    # Check semantic search availability (optional, for concept queries)
    try:
        flowspace.search(pattern="test", mode="semantic", limit=1)
        SEMANTIC_AVAILABLE = True
    except:
        SEMANTIC_AVAILABLE = False
        print("ℹ️ Semantic search unavailable (run 'fs2 scan --embed' to enable)")

except Exception as e:
    FLOWSPACE_AVAILABLE = False
    SEMANTIC_AVAILABLE = False
    # GRACEFUL FALLBACK: Continue with traditional tools
    print("""
    ℹ️ FlowSpace MCP not available - using traditional tools (Glob/Grep/Read)

    Note: For enhanced exploration with code intelligence, install FlowSpace:
      1. Install fs2: uvx --from git+https://github.com/AI-Substrate/flow_squared fs2 install
      2. Initialize: fs2 init
      3. Scan codebase: fs2 scan
    """)
    # CONTINUE with traditional tools - do not stop