Your customizable AI coding team that learns! Use it to create apps or make changes/additions to existing ones.
This set of instructions (markdown files) enhances and extends the modes/agents that come with many coding agents/assistants. The instructions are tailored to work with Roo Code (free highly customizable VS Code extension) but will work with many others, including Cursor, CLine, Kilo,Github Copilot, etc.
Using the built-in-to-Roo ability to use "rules" files, this archive is a set of custom instructions for the built-in modes/agents and some new ones, including:
- Architect Super Team: a 3-step "Planner" process (planner-a, planner-b, planner-c). Brainstorms with user. While planning and working, creates detailed files to keep track of its goals, progress, and lessons learned.
- Architect Quick: a 1-step "Planner" process; modified Roo's built-in Architect mode to be more detailed but for smaller tasks than full on 3-step "Planner" process.
- Coder on Crack: Juiced up "Code" mode to follow The Plan, whether created by the new superpowered Architect or hastily typed out by a user running 3 days on caffeine.
- Code Monkey (Junior coder): Supplemented "Code" with a tightly controlled budget-friendly "Code Monkey" created to work with the short, detailed tasks created for it by Planner.
- Other new modes: Added "Front-end", "Debugger", "Tester", "GitHubber", "Docs Writer", etc.
Notes:
- Smart but cheap: Designed both Architect and Planner modes to "front load" spend on high "intelligence" thinking models to create a plan that is so detailed, the "Workers" like "Coder", "Code Monkey", etc. can be faster/cheaper models. Overall, I'm finding this method burns far less tokens, has far less errors, and runs longer without a need for human intervention.
- Look how fast they grow up: This set of instructions is ever-evolving.
- Virtuous circle: The author, Scott Howard Swain, uses this "Team" every day, is constantly tinkering with it, and is always eager to hear ideas to improve this.
py -m pip install -r requirements.txt The browser-use skill requires a download of browser binaries:
playwright install chromiumUsing skills, the Team will:
- Consume far less tokens,
- Use up less of models' oh-so-precious context memory, and
- Follow instructions better!
I've added quite a few skills in the {base folder}/.roo/skills folder.
- Roo Code's docs: https://docs.roocode.com/features/skills
- They use the Agent Skills Open Format.
Skills libraries:
- A skill marketplace with over 230,000 skills! https://skillsmp.com
- https://agentskills.io/home
- https://skills.sh/jeffallan/claude-skills
If building a new app, Architect and Planner abc assume you already know specs for the project (stack, guidelines, etc). That's just one layer "higher" than these instructions are built for.
Possibly coming soon: a level above "Planner" where you brainstorm on a high level to get ideas for specs to feed planner. Until then, use "Ask" mode in Roo or query your favorite LLM chat to help you sculpt your specs. Save money by using the following in your browser for free until they reach their limits:
Scenario: Fixing a bug, modifying front-end, or adding a function.
- Use "code", "code monkey", "front-end", "debug", "tester", etc., as appropriate.
Scenario: Building a new dashboard screen. Planning
- Start with "planner-a" (for med/high size work) or "architect" (for low/med size work) mode.
- For this mode, I choose a model with high reasoning and large-as-possible context window. Why? Because AgentAutoFlow's planning modes do the "heavy lifting," creating a plan file that has atomic detail so that orchestrator and the other modes in the chain can be relatively "dumb".
- Mode choice examples (note - I change these often, your mileage may vary):
- Architect: Sonnet-4.5-Reasoning for intelligence and context window. I choose the large context window here because this modified architect mode does what Planners a/b/c all do, combined.
- Planner-a: This mode seeks to understand your goal, investigates relevant project files/functions, and creates a big picture. Brainstorms with user to determine high level plan. Creates "Phase(s)". Right now I use GPT-5x-Reasoning-High for intelligence. If you use it through OpenAI as a provider, you can choose "flex" Tier for lower pricing. If you don't care about cost, use Sonnet-4.5-Reasoning.
- Planner-b: Populates Phase(s) with detailed atomic Task(s). GPT-5x-Reasoning-High. Don't worry about planner-b receiving a large context window from planner-a. It will only receive the in-progress plan file from planner-a.
- Planner-c: Detailed task simulation and refinement. GPT-5x-Reasoning-High. Don't worry about planner-c receiving a large context window from planner-b. It will only receive the in-progress plan file from planner-b.
- Tell it what you want.
- It will brainstorm with you, asking questions, including:
- Complexity: How do you want the work plan to be structured in terms of size, phase(s), and task(s)? It will recommend one. It will automatically create tasks so they are "bite-size" chunks less smart/lower-cost LLM models can more easily do the actual work.
- Autonomy: What level of autonomy do you want it to have when it does the work?
- Testing: What type of testing (browser, unit tests, custom, none) do you want it to do as it completes tasks?
- It will create a plan and ask you if you want to modify it or approve.
- It will also create plan and log files.
Why are these files useful for the plan?
- Keep track of goals.
- Keep track of progress - if planning or execution is interrupted, you can easily get back on track.
- Catalog lessons learned during the process.
- Once you approve the plan, if using planner-a, it will pass on to the other planner modes to flesh out and add detail to the plan. If using architect mode, that mode will do what planners a/b/c all do but with a bit less "care" and cost in time.
- Eventually, once you approve, it will pass the plan (with detailed instructions, mode hints, etc.) on to the "orchestrator" mode.
Orchestration
- As you probably gathered, I've moved much more of the detail work (like making atomic tasks) into the planning phase so that orchestrator can be relatively dumb/cheap and merely follow orders to send out detailed tasks to whatever modes are part of each task description.
Mode budgeting
- Note: This workflow will sets the plan to choose between "code," "code monkey," and "task-simple" modes, depending on complexity. If "task-simple" or "code monkey" get confused because a task is too difficult or complex, they have instructions to pass the task up to "code" mode which I assign a "smarter" LLM to. Finally, "debug" mode is for more complex issues, so be sure to assign it a reasoning model, as well.
For me, in Windows with a preference for Powershell, I've found termminal commands work better with the following setting:
Setting -> Terminal -> Use Inline Terminal <- Unchecked.
Your mileage may vary.
These files go in your project root ("app" in this case). You'll see they coincide with where your current .roo folder is.
app/
├── agents.md (generate with `/init` command.)
├── .roomodes/
└── .roo/
├── docs/
│ ├── database_schema.md
│ ├── learning/
│ ├── old_versions/
│ ├── plans/
│ ├── plans_completed/
│ └── reports/
├── rules/
│ ├── 01-general.md
│ └── 02-database.md
├── rules-architect/
│ └── 01-architect.md
├── rules-ask/
│ ├── 01-ask.md
│ ├── 02-ask-health.md
│ └── 03-ask-flora-growing.md
├── rules-code/
│ └── 01-code.md
├── rules-code-monkey/
│ └── 01-code-monkey.md
├── rules-debug/
│ └── 01-debug.md
├── rules-docs-writer/
│ └── 01-docs-writer.md
├── rules-front-end/
│ └── 01-front-end.md
├── rules-githubber/
│ └── 01-githubber.md
├── rules-orchestrator/
│ └── 01-orchestrator.md
├── rules-planner-a/
│ └── 01-planner-a.md
├── rules-planner-b/
│ └── 01-planner-b.md
├── rules-planner-c/
│ └── 01-planner-c.md
├── rules-task-simple/
│ └── 01-task-simple.md
├── rules-tester/
│ └── 01-tester.md
└── skills/
├── api-use-external/
│ └── SKILL.md
├── app-knowledge/
│ └── SKILL.md
├── coding-css/
│ └── SKILL.md
├── coding-html/
│ └── SKILL.md
├── coding-javascript/
│ └── SKILL.md
├── coding-markdown/
│ └── SKILL.md
├── coding-python/
│ └── SKILL.md
├── database-use/
│ └── SKILL.md
├── error-handling/
│ └── SKILL.md
├── frontend-design/
│ └── SKILL.md
├── github-use/
│ └── SKILL.md
├── learning/
│ └── SKILL.md
├── log-file-use/
│ └── SKILL.md
├── mode-selection/
│ └── SKILL.md
├── planning-init/
│ └── SKILL.md
├── research/
│ ├── SKILL.md
│ └── resources/
├── simplification/
│ └── SKILL.md
└── testing/
└── SKILL.md
In Roo Code settings, under "Providers", when you set up a Configuration Profile: Like let's say you are adding "GPT-5x-R-M" as the profile name, with API provider "OpenAI". The new configuration one will have "Enable todo list tool" (in "Advanced settings") turned on by default.
The todo list tool burns extra tokens and - especially if you are using AgentAutoFlow - you don't need the todo list tool. I recommend going to the bottom of all the models you have set up and turning "Enable todo list tool" off.
Helpful utility included: A Python utility for synchronizing .roo directories across multiple project folders based on file modification times.
The AgentAutoFlow File Sync Utility scans .roo subdirectories in multiple project folders (you designate), identifies files that need updating based on modification times, and performs intelligent file synchronization with atomic operations and backup support.
Launch the graphical interface with:
python main_gui.pyUse the interface to:
- Select multiple folders containing
.roodirectories. - Configure sync settings via the Settings window and config.txt (dry-run mode, backup options).
- Monitor live progress during synchronization.
- Overwrite preview panel that shows planned overwrites before execution.
- Favorite folder sets (based on folders_faves in config) to quickly re-load common project combinations.
- Auto-creates .bak versions of all modified files.
- Button to remove all .bak files.
Run headless synchronization with:
python cli_sync.py <folder1> <folder2> ...Example:
python cli_sync.py /path/to/project1 /path/to/project2 /path/to/project3Settings are stored in config.txt See README-file-sync.MD for details.
Be sure to modify the content of files to fit your project. Especially:
- "agents.md" (In root, "above" .roo folder). Important file. See
/initin this document. - ".roo/docs/database_schema.md".
- ".roo/rules/01-general.md" <-- no longer necessary because skills!
- ".roo/rules/02-database.md" <-- no longer necessary because skills!
- ".roo/rules-front-end/02-design-patterns.md". Really, I'd look through all the rules files to modify to YOUR preferences.
- I've added "Orchestrator" to .roomodes local mode file so that I can give it read, edit, and command permissions. Without those permissions, it can sometimes have issues, depending on what LLM model you have it using. Example: I've seen it find an issue with The Plan and spend extra tokens to delegate minor textual changes to The Plan when it could have more quickly done the changes itself.
If your agentic assistant has an /init or other command that analyzes your codebase and creates tailored configuration files, use it. Roo Code uses /init.
Optimally, use a high reasoning, large context-window model. Type into chat: "/init". Note: If you type only "/init", the LLM may create agent.md files in other folders (like within the various rules subfolders in the .roo folder).
Some of the tips below are subject to change often, especially which models to use for which mode.
- Use free Roo Code.
- Use free AgentAutoFlow (just a bunch of .md files telling modes exactly how to act, delegate, and more).
- Pick the right models for each mode:
Front-loading the intelligence:
The following tips are based on the way AgentAutoFlow "front loads" the heavy-lifting (deep thought) in the architecting/planning, making plans so detailed and tasks so atomic, that when a "worker" mode gets its assignment, it knows exactly what to do. That allows you to use "dumber" models for "worker" tasks. That said, I still assign a pretty "smart" model to "Code" mode.
Modularity and low context usage:
When creating a plan based on user input, for larger projects, I divided "architect" up into "planner-a, b, c" so that, for example, "planner-a" will process user query and brainstorm with user to create a high level "plan" file. It will then pass that file on to "planner-b". This mode-switch provides a new fresh context window to do its work in. It will then create very detailed tasks that may include, per task:
- Either pseudo-code or code.
- Mode hints. Ex: "Use this mode: Code (Senior Coder)", "Code Monkey (Jr Coder)", "Task-Simple", "Tester", etc.
- Architect and Planner (team): GPT-5.1-R-H or M | Sonnet 4.5-R.
- Code (Senior Coder), Front-end, Debugger, Tester: Sonnet 4.5 | GPT-5.1-R-M. Note: On paper, GPT 5.1 seems far more expensive than it really is but I find it runs so efficiently that it ends up doing a lot for pennies! I use it through OpenRouter or through OpenAI, choosing "Flex" service tier because I'm fine with how slow it is for saving $.
- Code Monkey (Jr Coder): GPT-5.1-Low | GLM 4.6 | Kimi K2 | Gemini 2.5 Flash (through OpenRouter is least expensive) or any comparable model because "Architect" (AgentAutoFlow's version) and "Planner" team write a very detailed plan that even includes pseudocode or code so that when the plan gets delegated by Orchestrator, Code and Code Monkey know exactly what they are expected to do.
- Task-Simple and Githubber: GPT-5.1-non-reasoning or one of those dumb-and-cheap models mentioned above. The AgentAutoFlow's "Architect" and "Planner" subteam both know to delegate all file copying, and other simple tasks to this mode so your expensive models aren't wasting money on stuff like that.
For LLM instruction following, which should you choose?
Roo Code's native architecture employs Markdown files (.md or .txt) stored in {base folder}/.roo/rules/ directories for all custom instructions. After reviewing 171+ community-created custom modes, zero use XML formatting. Roo Coderoocode The platform concatenates these Markdown files directly into Claude's system prompt in alphabetical order. YAML or JSON handle mode configuration, while instruction content remains plain Markdown.
This universal adoption of Markdown isn't documented as a deliberate choice over XML—the official Roo Code documentation simply doesn't address XML at all. The format appears to be selected for developer experience and ecosystem compatibility rather than AI performance optimization. Markdown files integrate seamlessly with version control, text editors, and documentation workflows that developers already use.
2025-11-19: Talked with a Roo Code dev. He said he uses XML and - from within the Roo Code extension - download "Mode Writer" from the Marketplace. It's now part of this repo. I used it to make an XML version of my custom version of the Architect mode. So, according to him, you can use XML instead of MD for your custom mode instructions. Because I find XML to be so wordy and ugly, I'll stick with MD until I see a clear problem with models getting confused by or ignoring my instructions.
GPT-5.1, Sonnet 4.5, Gemini 3 all prefer XML and will score a few percentage points higher in prompt adherence when XML is used but understand MD.
Why I still use and prefer markdown:
- Ease of human read/write.
- Roo Code (my current favorite framework) prefers it.
- I find that no matter what model I'm using, they follow the rules I've created in markdown format.
Created in 2025 by Scott Howard Swain https://OceanMedia.net
Free to use, modify, and share.
You are responsible for any benefits or problems encountered as a result of using this archive.
Also, I'm looking for work.