Skip to content
/

RooFlow

rooflow · GreatScottyMac/RooFlow · ★ 1.2k · last commit 2025-06-18

YAML-based system prompt replacement for Roo Code's Footgun feature with a persistent file-based Memory Bank for cross-session context continuity.

Best whenYAML encodes behavioral rules more compactly than markdown, enabling the same guidance with fewer tokens; memory should be event-triggered append-only files,…
Skip ifOverwriting Memory Bank entries (always append with timestamps), Using Flow-Ask to update memory (read-only by design)
vs seeds
agent-os(file-based state management) but uniquely uses Roo Code's Footgun system prompt override to inject YAML-encoded prompts…
Primitive shape 5 total
Subagents 5
00

Summary

RooFlow — Summary

RooFlow is an experimental alternative system prompt framework for the Roo Code VS Code extension that replaces Roo Code's standard markdown system prompts with compact YAML-based prompts, achieving reduced token consumption while providing persistent project context through a Memory Bank system. The framework ships five "Flow" modes (Flow-Code, Flow-Architect, Flow-Ask, Flow-Debug, Flow-Orchestrator) as drop-in replacements for Roo Code's built-in modes, with each mode's behavior defined by a YAML system prompt file (.roo/system-prompt-flow-*) and a corresponding memory bank strategy file. The Memory Bank consists of five markdown files (productContext.md, activeContext.md, systemPatterns.md, decisionLog.md, progress.md) that the agent reads at session start and updates throughout. An optional Context Portal MCP server variant enables database-backed context rather than file-based context.

differs_from_seeds: Most similar to agent-os (Archetype 4 — markdown scaffold managing state files) in its Memory Bank pattern (which RooFlow explicitly credits to roo-code-memory-bank), but with a critical architectural difference: the system prompts are YAML rather than markdown, targeting Roo Code's "Footgun" experimental feature that allows overriding default system prompts. This is the only framework in this batch that uses Roo Code's system-prompt-override capability directly. Compared to ccmemory (which uses Neo4j for persistent context), RooFlow uses plain markdown files as its memory backend, making it simpler to inspect and debug.

01

Overview

RooFlow — Overview

Origin

Created by GreatScottyMac (GitHub). Active development (last commit June 2025). Stars: 1,159. Licensed Apache-2.0. Evolved from the author's earlier roo-code-memory-bank project.

Philosophy

"RooFlow offers an experimental alternative approach to AI-assisted development within the Roo Code VS Code extension. It utilizes YAML-based system prompts for its specialized 'Flow' modes, potentially offering improved efficiency and reduced token consumption compared to standard modes."

"Uses Roo Code's experimental 'Footgun' feature for deep AI assistant customization while maintaining efficient token usage!"

Core improvements over Roo Code Memory Bank (predecessor):

  • Reduced Token Consumption: Optimized prompts minimize token usage
  • Five Integrated Modes: Flow-Architect, Flow-Code, Flow-Debug, Flow-Ask, Flow-Orchestrator work together
  • Simplified Setup: Easier installation and configuration
  • Streamlined Real-time Updates: More efficient Memory Bank updates
  • Clearer Instructions: YAML-based rule files for better readability

Memory Bank Philosophy

The Memory Bank is designed to solve context continuity across sessions:

"Persistent storage for project knowledge (automatically managed). Each mode reads the Memory Bank at session start and updates it throughout the session, ensuring context continuity."

Status prefix requirement:

"Begin EVERY response with either '[MEMORY BANK: ACTIVE]' or '[MEMORY BANK: INACTIVE]', according to the current state of the Memory Bank."

Footgun Feature

Roo Code's "Footgun" feature allows overriding the extension's default system prompts with custom YAML files. RooFlow uses this to replace standard prompts with token-optimized YAML alternatives. The README warns: "RooFlow is NOT officially endorsed or supported by the Roo Code project. Use with caution."

Key Design Choices

  1. YAML system prompts (not markdown) — more compact
  2. File-based Memory Bank (not database) — inspectable and git-trackable
  3. Five coordinated modes — specialized per task type
  4. Real-time memory updates — triggered by significant events, not just session end
02

Architecture

RooFlow — Architecture

Distribution

Standalone repository. Installation via OS-specific scripts (bash/PowerShell) that download and configure files.

Install

# Linux/macOS (file-based Memory Bank)
bash <(curl -fsSL https://raw.githubusercontent.com/GreatScottyMac/RooFlow/main/config/install_rooflow.sh)

# Linux/macOS (with Context Portal MCP)
bash <(curl -fsSL https://raw.githubusercontent.com/GreatScottyMac/RooFlow/main/config/install_rooflow_conport.sh)

# Windows (PowerShell)
# Download install_rooflow.cmd and execute

Prerequisites:

  • Git
  • Python 3 + PyYAML (pip install pyyaml)
  • Roo Code VS Code extension

Directory Tree

RooFlow/
├── config/
│   ├── .roo/                      # Installed to project .roo/
│   │   └── system-prompt-flow-*/  # YAML system prompt files
│   ├── .roomodes                  # Mode definitions
│   ├── install_rooflow.sh/.cmd    # File-based install scripts
│   ├── install_rooflow_conport.sh/.cmd  # Context Portal variant
│   ├── update_roo_prompts.sh/.ps1 # Update scripts
│   └── generate_mcp_yaml.py       # MCP tool list generator
├── modules/
│   ├── rooflow_core_prompt.yaml   # Core YAML prompt template (tool definitions)
│   ├── modes.yml                  # Available modes definition
│   ├── memory_bank_strategy_code.yml    # Memory strategy for Code mode
│   ├── memory_bank_strategy_architect.yml
│   ├── memory_bank_strategy_ask.yml
│   ├── memory_bank_strategy_debug.yml
│   └── roo_code_conport_strategy/  # Context Portal variant strategies
└── README.md

Rule File Format

YAML system prompts (.roo/system-prompt-flow-*):

The core system prompt is a compact YAML structure defining:

  • mode — mode identifier
  • identity.name + identity.description — role definition
  • markdown_rules — formatting constraints
  • tool_use_protocol — tool invocation format (XML-style tags)
  • tools — full tool definitions (read_file, search_files, etc.)
  • memory_bank_strategy — initialization + update protocol
  • capabilities — mode-specific behaviors

Example structure:

mode: flow-code
identity:
  name: Flow-Code
  description: "Code creation, modification, and documentation"
memory_bank_strategy:
  initialization: |
    <thinking>CHECK FOR MEMORY BANK</thinking>
  if_memory_bank_exists: |
    READ ALL MEMORY BANK FILES sequentially

Memory Bank Files (Written to Project)

After initialization, five files in memory-bank/:

  • productContext.md — project description, goals, features
  • activeContext.md — current work focus, recent changes
  • systemPatterns.md — architectural patterns discovered
  • decisionLog.md — architectural decisions with timestamps
  • progress.md — task status and known issues

Target AI Tools

Primary: Roo Code VS Code extension (requires Footgun feature) Incompatible with standard Roo Code modes — Flow modes replace them.

Required Runtime

  • Python 3 + PyYAML
  • Roo Code with Footgun feature enabled
  • Git, bash (Linux/macOS) or PowerShell (Windows)
03

Components

RooFlow — Components

Flow Modes (5 total)

Mode Slug Memory Access Purpose
Flow-Orchestrator flow-orchestrator delegates Coordinates complex tasks by delegating to specialized modes
Flow-Code flow-code Read/Write Code creation, modification, and documentation
Flow-Architect flow-architect Read/Write System design, documentation structure, project organization
Flow-Debug flow-debug Read/Write Expert troubleshooting and debugging
Flow-Ask flow-ask Read-Only Answer questions, analyze code, explain concepts

Memory Bank Files (5 files, written to memory-bank/)

File Updated By Trigger
productContext.md Architect, Code, Debug High-level project description changes
activeContext.md Architect, Code, Debug Current work focus changes
systemPatterns.md Architect, Code, Debug New architectural patterns introduced
decisionLog.md Architect, Code, Debug Significant architectural decisions
progress.md Architect, Code, Debug Task begins, completes, or changes

Flow-Ask: Read-only access (never writes Memory Bank)

YAML System Prompts (5 files)

File Mode
.roo/system-prompt-flow-code Flow-Code
.roo/system-prompt-flow-architect Flow-Architect
.roo/system-prompt-flow-ask Flow-Ask
.roo/system-prompt-flow-debug Flow-Debug
.roo/system-prompt-flow-orchestrator Flow-Orchestrator

Memory Strategy Files (4, in modules/)

File Purpose
memory_bank_strategy_code.yml Memory init/update protocol for Code mode
memory_bank_strategy_architect.yml Memory init/update protocol for Architect mode
memory_bank_strategy_ask.yml Read-only memory protocol for Ask mode
memory_bank_strategy_debug.yml Memory init/update protocol for Debug mode

Config/Install Scripts (10 total)

Script Purpose
install_rooflow.sh Linux/macOS file-based install
install_rooflow.cmd Windows file-based install
install_rooflow_conport.sh Linux/macOS + Context Portal MCP install
install_rooflow_conport.cmd Windows + Context Portal MCP install
update_roo_prompts.sh/.ps1 Update system prompts to latest
generate_mcp_yaml.py Generate MCP tool YAML for connected servers

Optional: Context Portal MCP

An alternative memory backend using a database (Context Portal MCP server):

  • External database-backed context storage
  • More powerful querying than flat files
  • Optional — the file-based variant works without it
05

Prompts

RooFlow — Prompts

Prompt 1: Core YAML System Prompt Structure

From modules/rooflow_core_prompt.yaml:

Technique: YAML-encoded tool-use protocol replacing standard markdown system prompts.

mode: # [mode]

identity:
  name: # [Mode]
  description: "[Role Definition]"

# Markdown Formatting Rules
markdown_rules:
  file_and_code_references:
    rule: |
      ALL responses MUST show ANY `language construct` OR filename reference as clickable.
      The format MUST be exactly: [`filename OR language.declaration()`](relative/file/path.ext:line)

# Tool Use Protocol and Formatting
tool_use_protocol:
  description: |
    You have access to a set of tools that are executed upon the user's approval.
    You can use one tool per message.
    Use tools step-by-step to accomplish a given task.
  formatting:
    description: "Tool use requests MUST be formatted using XML-style tags."
    structure: |
      The tool name is enclosed in opening and closing tags, and each parameter 
      is similarly enclosed within its own set of tags.
    example_usage: |
      <read_file>
      <path>src/main.js</path>
      </read_file>

Technique: YAML as a more compact encoding of behavioral rules. The YAML format is machine-readable and more concise than equivalent markdown — the key innovation is encoding the same information that markdown prompts contain in a format that uses fewer tokens.


Prompt 2: Memory Bank Strategy (Code Mode)

From modules/memory_bank_strategy_code.yml:

Technique: State-machine-style memory initialization protocol with explicit conditional branching.

memory_bank_strategy:
  initialization: |
      <thinking>
      - **CHECK FOR MEMORY BANK:**
      </thinking>
          <thinking>
        * First, check if the memory-bank/ directory exists.
          </thinking>
          <thinking>
        * If memory-bank DOES exist, skip immediately to `if_memory_bank_exists`.
          </thinking>
  if_no_memory_bank: |
      1. **Inform the User:**  
          "No Memory Bank was found. I recommend creating one to maintain 
          project context. Would you like to switch to Flow-Architect mode?"
  if_memory_bank_exists: |
        **READ *ALL* MEMORY BANK FILES**
        Plan: Read all mandatory files sequentially.
        1. Read `productContext.md`
        2. Read `activeContext.md` 
        3. Read `systemPatterns.md` 
        4. Read `decisionLog.md` 
        5. Read `progress.md` 
        6. Set status to [MEMORY BANK: ACTIVE] and inform user.

general:
  status_prefix: "Begin EVERY response with either '[MEMORY BANK: ACTIVE]' 
    or '[MEMORY BANK: INACTIVE]'"

Technique: Explicit state machine encoded in YAML with two branches (no bank → ask user; bank exists → load all files). The <thinking> tags embedded in YAML values instruct the model to use chain-of-thought reasoning during memory initialization.


Prompt 3: Memory Update Protocol (Decision Log)

Technique: Event-triggered append-only log with timestamped entries.

memory_bank_updates:
  decisionLog.md:
    trigger: "When a significant architectural decision is made"
    action: |
      <thinking>
      I need to update decisionLog.md with a decision, the rationale, 
      and any implications. 
      </thinking>
      Use insert_content to *append* new information. Never overwrite 
      existing entries. Always include a timestamp.  
    format: |
      "[YYYY-MM-DD HH:MM:SS] - [Summary of Change/Focus/Issue]"

Technique: Append-only audit log with explicit never-overwrite constraint. The combination of timestamped entries and immutable history creates a lightweight decision provenance system.

09

Uniqueness

RooFlow — Uniqueness

differs_from_seeds

RooFlow is closest to agent-os (Archetype 4 — markdown scaffold managing state files) in its Memory Bank pattern, but uses a fundamentally different implementation mechanism: YAML system prompt overrides via Roo Code's Footgun feature. No seed framework overrides the AI IDE's default system prompts — all seeds either add files (agent-os, superpowers) or wrap the AI tool (claude-flow). RooFlow's YAML prompt format achieves token efficiency by encoding behavioral rules in a more compact syntax than markdown. The [MEMORY BANK: ACTIVE] status prefix on every response is a unique observability signal — a mandatory per-response state indicator not seen in any seed. Compared to ccmemory (which uses Neo4j for persistent context), RooFlow's Memory Bank is deliberately simpler: five human-readable markdown files rather than a graph database. The event-triggered append-only decisionLog.md pattern is the closest thing in this framework to an audit log, and it matches the format of kiro's decision tracking concept.

Positioning

  • Niche: Roo Code users who want Memory Bank persistence + token efficiency
  • Experimental status: Explicitly not endorsed by Roo Code — "use with caution"
  • 1,159 stars: Most popular Roo Code framework in this batch

Observable Failure Modes

  1. Footgun instability: The system prompt override feature ("Footgun") is experimental — Roo Code updates may break it.
  2. Memory file growth: The append-only Memory Bank files grow indefinitely. No compaction strategy means long-lived projects accumulate very large context files.
  3. All-files-at-start overhead: Reading all 5 Memory Bank files at every session start consumes tokens upfront, potentially negating the token efficiency gains of the YAML prompts.
  4. Not officially supported: If Roo Code removes the Footgun feature, RooFlow stops working entirely.
  5. Flow-Ask read-only constraint: Flow-Ask cannot update the Memory Bank, meaning informational sessions don't contribute to project memory — a potential information loss.
04

Workflow

RooFlow — Workflow

Session Startup Workflow (Every Mode)

Mode activated
    ↓
Check for memory-bank/ directory
    ↓
[EXISTS]: Read ALL 5 memory bank files sequentially
    → Set status: [MEMORY BANK: ACTIVE]
    → Proceed with task
[NOT EXISTS]:
    → Inform user: "No Memory Bank found. Create one?"
    → If yes: switch to Flow-Architect mode to create it
    → If no: proceed without memory bank ([MEMORY BANK: INACTIVE])

Memory Update Triggers (During Session)

File Update Trigger
decisionLog.md Significant architectural decision made
productContext.md High-level project description/goals change significantly
systemPatterns.md New architectural patterns introduced
activeContext.md Current work focus changes, significant progress made
progress.md Task begins, completes, or changes

Update format: append with timestamp [YYYY-MM-DD HH:MM:SS] - [Summary]

Flow-Orchestrator Delegation

For complex tasks:

  1. User activates Flow-Orchestrator
  2. Orchestrator analyzes request
  3. Decomposes into subtasks
  4. Delegates to appropriate Flow mode (Code/Architect/Debug)
  5. Reports completion

Approval Gates

No explicit approval gates. The Memory Bank status prefix ([MEMORY BANK: ACTIVE] or [MEMORY BANK: INACTIVE]) on every response serves as an implicit observability signal.

Phase-to-Artifact Map

Phase Artifact
Architecture/Planning updates to memory-bank/systemPatterns.md, productContext.md
Coding modified source files + updates to activeContext.md, progress.md
Decision-making appended entries in memory-bank/decisionLog.md

Memory Bank Creation Workflow (Architect Mode)

When no memory bank exists:

  1. Flow-Architect mode creates memory-bank/ directory
  2. Creates and populates 5 files with initial project context
  3. Sets status to [MEMORY BANK: ACTIVE]
06

Memory Context

RooFlow — Memory & Context

Memory Architecture

File-based, project-scoped. Five append-updated markdown files.

Memory Bank Files

All stored in memory-bank/ at project root:

File Contents Access
productContext.md Project description, goals, features, overall architecture Read/Write (Architect, Code, Debug)
activeContext.md Current work focus, active decisions, recent changes, next steps Read/Write (Architect, Code, Debug)
systemPatterns.md Architectural patterns, component relationships, dependencies Read/Write (Architect, Code, Debug)
decisionLog.md Timestamped architectural decision log Read/Write (Architect, Code, Debug)
progress.md Task status, what works, what's left, known issues Read/Write (Architect, Code, Debug)

Flow-Ask: Read-only access (never writes to Memory Bank)

Initialization Protocol

At start of every session:

  1. Check for memory-bank/ directory
  2. If exists: read all 5 files sequentially
  3. Set status to [MEMORY BANK: ACTIVE]
  4. Every response begins with status prefix

If not exists: offer to create via Flow-Architect mode.

Update Triggers (Event-Based)

Updates are triggered by significant events during the session, not just at session end:

  • Architectural decisions → append to decisionLog.md
  • Project goals change → update productContext.md
  • New patterns discovered → append to systemPatterns.md
  • Work focus shifts → update activeContext.md
  • Task completes → update progress.md

Format: [YYYY-MM-DD HH:MM:SS] - [Summary] (always appended, never overwritten)

Compaction

No explicit compaction. Memory files grow over time with appended entries.

Cross-Session Handoff

Yes. The Memory Bank is the explicit cross-session handoff mechanism — each session reads all 5 files at startup, providing complete project context continuity.

Optional: Context Portal MCP

Alternative backend where Memory Bank files are replaced by a database-backed context store. Uses the context-portal MCP server for querying and updating context.

Memory Type Summary

Dimension Value
Memory type file-based
Persistence scope project
State files memory-bank/productContext.md, memory-bank/activeContext.md, memory-bank/systemPatterns.md, memory-bank/decisionLog.md, memory-bank/progress.md
Search mechanism none (linear file read)
Compaction none
07

Orchestration

RooFlow — Orchestration

Multi-Agent

Yes — in the same soft sense as Roo Commander. Flow-Orchestrator delegates to Code/Architect/Debug modes. These are Roo Code mode-switches, not separate process-isolated agents.

Orchestration Pattern

Hierarchical. Flow-Orchestrator coordinates; specialized modes execute.

Flow-Orchestrator
    ├── → Flow-Code (implementation)
    ├── → Flow-Architect (design)
    └── → Flow-Debug (troubleshooting)
    (Flow-Ask is informational, not delegated to for execution)

Memory Bank Access Pattern

Different modes have different memory access rights:

Mode Memory Access
Flow-Orchestrator delegates
Flow-Code Read/Write
Flow-Architect Read/Write
Flow-Debug Read/Write
Flow-Ask Read-Only

Isolation Mechanism

None. All edits in-place.

Multi-Model

No. Single model (user-configured in Roo Code).

Execution Mode

Interactive loop. Each mode session is user-initiated.

Prompt Chaining

Yes (via Memory Bank). Each session reads prior session outputs (Memory Bank files), creating implicit cross-session chaining.

Crash Recovery

Partial. Memory Bank files persist across crashes — if a session crashes, the next session reads the last updated Memory Bank state.

Summary Table

Dimension Value
Multi-agent yes (mode-based delegation)
Orchestration pattern hierarchical
Max concurrent agents 1 active mode at a time
Isolation none
Consensus none
Prompt chaining yes (via Memory Bank)
Multi-model no
Execution mode interactive-loop
Crash recovery yes (Memory Bank persists)
08

Ui Cli Surface

RooFlow — UI / CLI Surface

Dedicated CLI Binary

None.

Local UI / Dashboard

None. Uses Roo Code's built-in VS Code extension interface.

IDE Integration

Primary: Roo Code VS Code extension (requires Footgun feature)

The five Flow modes appear in Roo Code's mode selector after installation. Users select the appropriate mode for their task.

Roo Code Footgun Feature

RooFlow uses Roo Code's experimental "Footgun" system prompt override capability:

  • Standard Roo Code modes use built-in prompts
  • With Footgun enabled, .roo/system-prompt-<mode> files override the built-in prompts
  • RooFlow's YAML system prompt files are installed at these paths

"RooFlow is NOT officially endorsed or supported by the Roo Code project. Use with caution."

Install Scripts

Script Platform Purpose
install_rooflow.sh Linux/macOS Install file-based Memory Bank variant
install_rooflow.cmd Windows Same for Windows
install_rooflow_conport.sh Linux/macOS Install with Context Portal MCP
install_rooflow_conport.cmd Windows Same for Windows
update_roo_prompts.sh/.ps1 Linux/macOS/Windows Update prompts to latest

Observability

  • Memory Bank status prefix on every response: [MEMORY BANK: ACTIVE] or [MEMORY BANK: INACTIVE]
  • decisionLog.md serves as an append-only audit trail with timestamps
  • No structured logging beyond Memory Bank files

Cross-Tool Portability

Low. The Footgun system prompt override is Roo Code-specific. The Memory Bank concept could be adapted for other tools, but the YAML prompt format and Footgun integration are Roo Code-only.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

deepagents (LangChain) ★ 23k

Opinionated Python agent harness on top of LangGraph with sub-agents, filesystem, memory, and context compaction bundled in

agentmemory ★ 18k

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Basic Memory ★ 3.1k

Gives AI agents a persistent, human-readable knowledge graph of project decisions, observations, and relations stored as plain…