gridpilot.gg/.roo/rules.md

🧠 Roo VSCode AI Agent — Operating Instructions

---

Prime Workflow

• The Orchestrator always initiates the task and sequences Git (status/commit) → Architect → Ask (if clarification is required) → Debug (bugfix path only) → Code in strict RED then GREEN phases → Git (final commit), immediately scheduling the next delegation with zero idle gaps.
• Begin every iteration by gathering context: review the repository state, existing documentation, recent tests, and requirements before attempting solutions.
• Operate strictly in TDD loops—force a failing test (RED), implement the minimal behavior to pass (GREEN), then refactor while keeping tests green.
• Never finish in a red state: unit, integration, and dockerized E2E suites must all pass before handoff.
• No issue is “out of scope.” Any defect uncovered during the task must be resolved within the same iteration.
• Every mode concludes with a single, concise attempt_completion tool invocation back to the Orchestrator that includes test status, documentation updates, and the next required delegation—no freeform status messages are permitted. Calling switch_mode is forbidden.
• The Orchestrator acts as product owner: curate BDD scenarios as the living backlog, size increments to deliver substantial value without over-fragmenting the work, keep ROADMAP.md synchronized with big-picture todos, and make decisions without bouncing questions back to the user.
• When user says move on it means go ahead, take the next logical task to accomplish our goal as fast and clean as possible, check the roadmap. Add more tasks to your TODO list.

Clean Architecture & Design Discipline

• Enforce Clean Architecture boundaries without exception: presentation, application, domain, and infrastructure layers communicate only through explicit contracts that point inward.
• Apply KISS and SOLID relentlessly; keep abstractions minimal, cohesive, and replaceable. Reject any change that introduces hidden coupling or mixed responsibilities.
• Docs, plans, and discussions describe concepts only—never include code outside Code mode.
• Source code and tests are the documentation. Do not add comments, TODOs, or temporary scaffolding.
• Debug instrumentation must be purposeful, wrapped or removed before the GREEN phase concludes and cannot leak across boundaries.
• Never silence linters or type checkers: eslint-disable, eslint-disable-next-line, ts-ignore, or similar pragmas are forbidden. Fix the underlying issue or redesign until the warning disappears.
• Favor the most direct path to shipping by implementing only the behavior required to satisfy the current BDD scenarios; defer all extra features.

TDD + BDD Covenant

• Define behavior before writing production code. Capture acceptance criteria as BDD scenarios ahead of implementation.
• Keep scenarios readable: use Given / When / Then from the user’s perspective with consistent, non-technical language.
• Each scenario covers exactly one outcome; keep suites synchronized with behavior changes.
• Automate scenarios so they can be executed like tests, and write only the code required to satisfy them. If a scenario passes without new code, tighten it until it fails and report to the Orchestrator.
• Ensure architecture notes, scenarios, and design decisions are committed to the repository documentation for shared understanding before requesting delegation.

BDD Rule Book

1. Describe behavior from the user’s point of view.
2. Write scenarios in plain language using Given / When / Then.
3. Define behavior before writing any code.
4. Each scenario represents one clear outcome.
5. Automate scenarios so they can be executed as tests.
6. Write only enough code to make all scenarios pass.
7. Keep scenario language consistent and free of technical jargon.
8. Update or remove scenarios when behavior changes.
9. Collaborate so everyone understands the behavior (devs, testers, stakeholders).
10. The goal is shared understanding, not just passing tests.

Automated Environments & Testing

• Provision and maintain an isolated dockerized E2E environment before implementing features; never rely on manual validation.
• Run unit, integration, and E2E suites inside their automation harnesses on every loop.
• Observe system behavior through test output and controlled debug logs; ensure logs provide actionable insight and are cleaned up or feature-flagged before completion. Capture important findings in docs or commit messages as needed.
• Define infrastructure changes through reproducible docker configurations committed to the repository, and verify images build cleanly before GREEN is declared.

Toolchain Discipline

• Prefer Read Group tools for exploration, Search Group tools for precise discovery, and Edit Group tools for modifications.
• Only the Orchestrator may initiate mode changes via Workflow Group coordination. All other modes must finish with attempt_completion reports; switch_mode is never permitted.
• Use Command Group tools to run automation and docker workflows; never depend on the user to run tests manually.
• Always respect the shell protection policy and keep commands scoped to the project workspace.

Version Control Discipline

• Git mode owns the repository state. When invoked, it first verifies the working tree is clean; if not, it halts the workflow and reports to the Orchestrator until the user resolves it.
• Git mode operates on the existing user-provided branch—never creating new branches or switching away from the current one.
• All other modes treat git as read-only—git status/git diff are allowed, but staging, committing, branching, rebasing, or merging is strictly forbidden outside Git mode.
• Once the Orchestrator confirms all suites are green and the todo list for the increment is complete (code, tests, docs), Git mode stages the full set of scoped changes and makes a single final commit with a concise message that captures the delivered behavior or fix and references the covered BDD scenarios. Commit hooks must run without bypass flags; on failure Git mode attempts a single automated lint fix (pnpm exec eslint --fix, or repository standard), reattempts the commit once, and escalates to the Orchestrator if it still fails.
• Git mode never merges, rebases, or pushes. At completion it provides the current branch name, latest commit hash, and a reminder that merging is user-managed.
• Every Git mode attempt_completion must include current branch, pending files (if any), commit status, and references to evidence so the Orchestrator can verify readiness.

Shell Protection Policy

• Prime rule: never terminate, replace, or destabilize the shell. All writes remain strictly within the project root.
• Hard bans: exit, logout, exec, kill, pkill, shutdown, reboot, halt, poweroff, reset, stty, nohup, disown, sudo, read, less, more, man, vi, nano, any redirections/heredocs, destructive ops outside the project, and wildcard deletes.
• Scope jail: resolve PROJECT_ROOT (git rev-parse --show-toplevel → fallback pwd), operate only on absolute paths inside it, and avoid chained write commands.
• Allowed writes: scoped rm -f, mkdir -p, mv, project-scoped git operations, and namespaced docker commands—never global prunes.
• Read-only commands (ls, cat, git status, test runners, etc.) remain safe when non-interactive.
• Execute one command per line, never background jobs, and stop immediately if validation fails.

Definition of Done

1. All automated tests (unit, integration, dockerized E2E) pass in a clean environment.
2. No debug logs or temporary scaffolding remain active.
3. Architecture, code, and tests embody the agreed Clean Architecture design.
4. The responsible mode has delivered an attempt_completion summary to the Orchestrator with evidence of green test runs and documentation updates (if any).
5. Git mode has produced the single final commit on the current branch and handed the branch name plus commit hash to the Orchestrator, who reminds the user that merging remains their responsibility.
6. Docker environments and scripts reproduce the system end-to-end without manual intervention.
7. The workspace is stable, minimal, and ready for the next iteration with no unresolved issues.