// Collaboration protocol for Ralph loop (Plan → Act → Reflect → Refine). Use when working from spec files in specs/<name>/ (goal.md/spec.md, plan.md, state.json, decisions.md); when executing tasks in a shared plan; or when the user mentions Ralph, multi-agent, or file-based collaboration.
Maintain WCAG-focused accessibility in stream-chat-react. Use when changing interactive components, dialogs, menus, forms, media controls, notifications, focus behavior, keyboard flows, aria attributes, or screen-reader announcements.
Structures plan.md files for parallel, non-overlapping agent work. Use when creating or editing execution plans, task lists for multiple agents, or when the user asks how to structure plans or split work into tasks.
Creates and manages git worktrees for isolated plan execution. Use when setting up a worktree for a plan, syncing with base branch, rebasing, or cleaning up worktrees. Never modify the main repo for plan work—all work happens in the worktree.
Styling and structure conventions for stream-chat-react. Use when adding or editing components, SCSS, or icons in this repo—file layout, styling folder structure, SCSS imports, and icon placement.
Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.
| name | ralph-protocol |
| description | Collaboration protocol for Ralph loop (Plan → Act → Reflect → Refine). Use when working from spec files in specs/<name>/ (goal.md/spec.md, plan.md, state.json, decisions.md); when executing tasks in a shared plan; or when the user mentions Ralph, multi-agent, or file-based collaboration. |
Files are the source of truth. All agents share memory via files. No silent decisions. Always update state after acting. Prefer small, explicit updates.
Location: Generate and keep spec files in a dedicated folder inside the specs folder at the root of the repo: specs/<feature-or-component-name>/. Example: specs/resizable-container/goal.md, specs/resizable-container/plan.md, specs/resizable-container/state.json, specs/resizable-container/decisions.md. One folder per feature or component; do not put spec files next to source (e.g. not under src/components/...).
| File | Purpose |
|---|---|
| spec.md or goal.md | What we achieve; success criteria; constraints; non-goals. Read first. Only change if goal actually changes. No implementation details. |
| plan.md | How we achieve it. Ordered tasks, ownership, dependencies, status (pending | in-progress | done | blocked). Propose changes before big deviations; don't rewrite completed sections. |
| state.json | Current memory. Task statuses, flags (blocked, needs-review, etc.). Update immediately after acting. Read before assuming anything. |
| decisions.md | Log of non-trivial decisions (what + why). Append only; never delete. Prevents reopening or contradicting past choices. |
Before acting: Read the spec files in specs/<name>/: spec.md (or goal.md) → plan.md → state.json → decisions.md.
During: Follow the plan; no overlapping work unless coordinated; no undocumented decisions.
After: Update specs/<name>/state.json → record decisions in specs/<name>/decisions.md → update task status in specs/<name>/plan.md. Optionally add learnings to observations.md in the same folder.
Prohibited: Decisions without recording; using chat as memory; re-solving done problems; changing goals implicitly; overwriting files without explanation.
specs/<name>/plan.md), marked in-progress and assigned to you.Only commit files that were changed for the current task. Use git add <file> — never git add -A or git add .. Leave unrelated changes unstaged.
When acceptance criteria involve UI: use Playwright (MCP or project config). Take screenshots for success and failure. Save to a clear location (e.g. __tests__/screenshots/).
Each iteration: Plan (update specs/<name>/plan.md if needed) → Act (scoped work) → Reflect (learnings) → Refine (plan or decisions).
For decision log format and state.json example, see reference.md. Plan structure and worktrees: use make-plans and worktrees skills.