🚀 ReOpenSpec

Stop your AI agents from hallucinating architecture.

ReOpenSpec is an IDE-native Multi-Agent Orchestration Framework designed for modern AI coding assistants (like Cursor, Windsurf, Roo, and Cline). It provides strict, traceable workflows that enforce architectural boundaries, ensuring that AI agents execute tasks predictably without messing up your codebase.

🤯 How It Works

• Fact #1: Multi-Agent Handoffs. No single AI model is perfect at everything. ReOpenSpec orchestrates a strict pipeline: a Planner Agent (e.g., Claude 3.5 Sonnet) writes the architectural spec, a Plan Reviewer Agent catches logic gaps, a Coder Agent (e.g., Cursor Small) implements the code, and a Code Reviewer Agent validates the implementation.
• Fact #2: Solving "Context Pollution". If you dump your entire project history into an AI's prompt, it gets confused. ReOpenSpec solves this by strictly archiving completed work and only feeding the agent the active specs it needs right now.
• Fact #3: IDE-Native Slash Commands. The entire workflow happens directly in your IDE's chat interface. Run reo init once, and ReOpenSpec injects all the necessary / commands into your environment.

🏗️ The 3-Tier Architecture Philosophy

ReOpenSpec forces a heavily structured, traceable workflow on your repository:

| Where it lives | What it is | Agent's Relationship | |------|------|------| | reopenspec/docs/ | Agent guidelines, ADRs, runbooks. | Configures the Agents. Defines which LLM model does what. | | reopenspec/specs/ | Domain behaviors and scenarios. | Source of Truth. The AI must rigorously adhere to this. | | reopenspec/changes/ | In-flight work (active/) and archived work (completed/). | The AI's scratchpad. Completed work is archived to keep main memory clean! |

(See reopenspec/docs/reopenspec-model.md for the deep dive).

⚡ Quick Start

1. Install

Require Node.js 20+.

npm install -g reopenspec

2. Bootstrapping Magic

In your project root, run:

reo init

What just happened? ReOpenSpec auto-detected your frameworks and your IDE. It created the 3-tier folder structure, scaffolded your agent-guidelines.md, and injected targeted semantic agent slash-commands (.cursor/commands/) into your workspace.

3. The 4-Stage Traceable Workflow

Run these commands in your IDE's AI Chat (e.g., Cursor Chat):

1. /reo-plan: The Planner Agent connects via MCPs (Jira/Azure/Figma), pulls a story, parses dependencies, and provisions a strict plan.md under the active/ folder.
2. /reo-review-plan: The Plan Reviewer Agent critiques the plan, catching edge cases and architectural drift before any code is written.
3. /reo-proceed-plan: The Coder Agent executes the implementation in isolated, traceable steps based strictly on the approved plan.
4. /reo-review: The Reviewer Agent runs automated checks (linting, testing) and validates the code against the architecture before PR creation.
5. /reo-completed: You review, the AI proposes updates to reopenspec/specs/, and safely archives the work into changes/completed/YYYY-MM-DD/ to lock the spec and erase short-term memory pollution.

🛠️ CLI Command Reference

The reo CLI is used purely for environment setup and project scaffolding. Do not use the CLI to run the workflow.

| Command | Purpose | | :--- | :--- | | reo init | First-time boilerplate: directories, config, dynamic IDE profile detection, and contextual rule injection. | | reo init --skip-workflow | Core initialization only. Creates config without injecting .mdc rules or templates. | | reo doctor | Validate workspace health (checks config, directories, and spec contract references). | | reo inject | Hard force re-apply of the latest dynamic categorized IDE rules. |

(Run reo <command> --help for flags).

📄 License

MIT — see LICENSE. Go build smarter things.