🚀 Quick Start & Core Workflow

Using rooroo involves these main steps:

1. Setup: Install Roo Code VS Code extension.
   • Load your .roomodes file.
     • For Roo Code v3.18.0 and later: You can use the YAML format for .roomodes.
     • For Roo Code versions earlier than v3.18.0: You must use the JSON format for .roomodes (e.g., .roomodes.json).
   • Reload VS Code.
   • (Optional: For advanced customization, create a .roo/rules/ directory and add custom instruction files to tailor agent behavior across your workspace.)
2. Initiate: Select 🧭 Rooroo Navigator and state your goal.
3. Navigator Triage: The Navigator assesses your request:
   • For complex/uncertain tasks, it engages the 🗓️ Rooroo Planner to break it down into sub-tasks with context.md briefings. These go into the .rooroo/queue.jsonl.
   • For simple, clear single-expert tasks (Developer, Analyzer, Documenter only), it prepares context.md and may execute directly or queue the task.
   • If ambiguous, it asks you for clarification.
4. Execution: The Navigator dispatches tasks from the queue to the assigned Rooroo expert. The expert uses its context.md and stores outputs in .rooroo/tasks/TASK_ID/.
5. Reporting: The expert returns a JSON Output Envelope (status, message, artifacts) to the Navigator.
6. Processing & Iteration: The Navigator parses the envelope:
   • NeedsClarification: Relays question to you.
   • Done/Failed: Logs event, updates queue, informs you. Auto-proceeds with plans if applicable.
7. Monitor: Track progress via .rooroo/queue.jsonl and .rooroo/logs/activity.jsonl.

(Refer to the Workflow Diagram below for a visual representation.)

🤖 The Agent Team at a Glance

Each Rooroo agent adheres to core principles like the Principle of Least Assumption and Concise Context File Preparation (linking over embedding).

• 🧭 Rooroo Navigator (⚡ Cheap/Fast Recommended): Your primary interface. Manages interactions, triages tasks, dispatches from the queue, processes expert reports, and logs events. Prioritizes concise communication.
• 🗓️ Rooroo Planner (🧠 Smart/Expensive Recommended): Decomposes complex goals into sub-tasks for the Developer, Analyzer, or Documenter. Creates their context.md briefings and can flag ambiguous expert choices for the Navigator to resolve.
• 🧑‍💻 Rooroo Developer (Custom / Varies): Executes coding tasks based on context.md. Stores outputs in its task folder or modifies project files.
• 📊 Rooroo Analyzer (⚡ Cheap/Fast Recommended): Performs analysis based on context.md. Generates reports in its task folder.
• ✍️ Rooroo Documenter (⚡ Cheap/Fast Recommended): Creates/updates documentation based on context.md. Stores outputs in its task folder.
• 💡 Rooroo Idea Sparker (🧠 Smart/Expensive Recommended): Acts as a Strategic Foresight Facilitator, guiding users through a structured process to explore problems, evaluate solutions, and produce a detailed Handoff Document. This document serves as a comprehensive blueprint, ready for delegation to execution agents. Its outputs are stored in .rooroo/brainstorming/.

Balance LLM tiers per agent for optimal cost and capability.

📁 Directory Structure at a Glance

rooroo uses a clear, workspace-relative structure under the .rooroo/ directory for all its operations and artifacts.

<Project Root>/
├── .rooroo/                  # Core rooroo operational directory
│   ├── queue.jsonl           # Pending Tasks (JSON objects, one per line, ROO# IDs, strictly parsable)
│   ├── logs/
│   │   └── activity.jsonl    # Activity Log (JSON objects, one per line, written by Navigator with escaped JSON)
│   ├── rules/                # Optional: Workspace-wide custom instruction files (e.g., 01-general.md)
│   ├── tasks/                # Directory for all task-specific data
│   │   ├── ROO#PLAN_20240101120000_initial_project/ # Example Planner Task Directory
│   │   │   └── context.md      # Briefing FOR the Planner (concise, uses links)
│   │   ├── ROO#SUB_initial_project_S001/ # Example Sub-Task Directory (ROO#SUB_... ID from Planner)
│   │   │   ├── context.md      # Task briefing FOR the expert (Created by Planner, concise, uses links)
│   │   │   ├── feature_component.py # Example artifact directly in task folder
│   │   │   └── data_analysis_report.md # Another example artifact
│   │   ├── ROO#TASK_20240101130000_fix_login/ # Example Direct Task Directory (ROO#TASK_... ID from Navigator)
│   │   │   ├── context.md      # Task briefing FOR the expert (Created by Navigator, concise, uses links)
│   │   │   └── login_fix.diff    # Example artifact directly in task folder
│   │   └── ...
│   ├── plans/                # Optional: High-level plan overview documents from Rooroo Planner
│   │   └── ROO#PLAN_20240101120000_initial_project_plan_overview.md
│   └── brainstorming/        # Optional: Summaries from Rooroo Idea Sparker sessions
│       └── brainstorm_summary_ROO#IDEA_20240101140000.md
│
└── src/                      # Example source code directory (Potentially modified by Rooroo Developer)
    └── ...

📊 Core Data Files Explained

Key files driving rooroo operations:

• .rooroo/queue.jsonl: Ordered list of tasks (JSON objects per line).
  • Defines: What needs to be done, by which expert, with what goal and context.
  • Example Task: {"taskId": "ROO#SUB_...", "suggested_mode": "rooroo-developer", "context_file_path": ".rooroo/tasks/ROO#SUB_.../context.md", "goal_for_expert": "Build feature X..."}
• .rooroo/logs/activity.jsonl: Append-only log of key events with severity (INFO, ERROR, etc.).
  • Tracks: What actions agents take and their outcomes.
  • Example Log: {"timestamp": "...", "agent_slug": "rooroo-navigator", "severity": "INFO", "task_id": "ROO#...", "event_type": "EXPERT_REPORT", "details": {"status": "Done"}}
• .rooroo/tasks/TASK_ID/context.md: The comprehensive Markdown briefing for an assigned agent.
  • Provides: Detailed goals, requirements, and links to relevant files/artifacts (prioritizing links over embedding content).
• Output Artifacts: Generated by experts (code, reports, docs) are stored directly in their respective task folders: .rooroo/tasks/TASK_ID/ (e.g., output.py, analysis_report.md).

Workflow Diagram (Visual)

+----------------------------------------------------------------------+ Phase 0: Optional Brainstorming +----------------------------------------------------------------------+

[User Initiates Brainstorming with 💡 Rooroo Idea Sparker]

+----------------------------------------------------------------------+ Phase 1: User Interaction & Task Triage (Navigator) +------------------------------------------------