rrce-workflow 0.2.97 → 0.2.98

package/README.md

@@ -86,7 +86,7 @@ The easiest way to connect is via the TUI (`npx rrce-workflow mcp` -> **Install*
 
 #### OpenCode
 
-RRCE-Workflow integrates with OpenCode both as an MCP server and by providing **Custom Primary Agents**.
+RRCE-Workflow integrates with OpenCode both as an MCP server and by providing a **Primary Orchestrator Agent** plus specialized subagents.
 
 1.  **Register MCP Server**: Add the following to `~/.config/opencode/opencode.json`:
     ```json
@@ -102,7 +102,17 @@ RRCE-Workflow integrates with OpenCode both as an MCP server and by providing **
     }
     ```
 
-2.  **Install Agents**: Run `npx rrce-workflow` and select **OpenCode** as a tool. This will generate specialized primary agents (Research, Planning, etc.) in `.opencode/agent/` that you can cycle through using the **Tab** key in the OpenCode TUI.
+2.  **Install Agents**: Run `npx rrce-workflow` and select **OpenCode** as a tool. This generates:
+    - **Primary Agent (`rrce`)**: Orchestrates the complete workflow lifecycle (tab-switchable)
+    - **Subagents** (`@rrce_*`): Specialized agents for each phase (expert mode)
+    - **Auto-configuration**: Hides OpenCode's native plan agent to avoid confusion
+
+3.  **Usage**:
+    - Press `Tab` to cycle to the RRCE agent for structured workflows
+    - Build agent can automatically delegate to RRCE for complex tasks
+    - Direct subagent access via `@rrce_init`, `@rrce_research`, etc.
+
+See [OpenCode Guide](docs/opencode-guide.md) for detailed usage instructions.
 
 #### VSCode (with MCP Extension)
 Add to `.vscode/mcp.json`:
@@ -171,25 +181,43 @@ Stores everything in a `.rrce-workflow` folder inside your project root.
 
 ## The Agent Pipeline
 
-Once installed, you gain access to 7 specialized agent workflows. Invoke them via your AI assistant's chat interface or through MCP tools.
+RRCE provides two ways to work with agents, depending on your workflow needs:
+
+### Primary Orchestrator (Recommended for OpenCode)
+
+The **RRCE Orchestrator** is a primary agent that manages the complete workflow lifecycle:
+
+- **Access**: Press `Tab` in OpenCode to cycle to the RRCE agent
+- **Purpose**: Automatically coordinate research → planning → execution → documentation
+- **Delegation**: Build agent can delegate to RRCE for complex tasks
+- **Benefits**: Results flow back to calling agents, preventing hallucination
+
+### Specialized Subagents
+
+For expert control, invoke subagents directly via your AI assistant or MCP tools:
+
+| Agent | Invoke With | Purpose | Key Arguments |
+|-------|-------------|---------|---------------|
+| **Init** | `@rrce_init` | Analyze codebase, establish project context and semantic index | `PROJECT_NAME` (optional) |
+| **Research** | `@rrce_research_discussion` | Interactive requirements clarification through dialogue | `TASK_SLUG`, `REQUEST` |
+| **Planning** | `@rrce_planning_discussion` | Transform research into actionable execution plan | `TASK_SLUG` |
+| **Executor** | `@rrce_executor` | Implement the plan - the ONLY agent authorized to modify code | `TASK_SLUG`, `BRANCH` |
+| **Docs** | `@rrce_documentation` | Generate project documentation (API, architecture, changelog) | `DOC_TYPE`, `TASK_SLUG` |
+| **Sync** | `@rrce_sync` | Reconcile knowledge base with current codebase state | `SCOPE` (optional) |
+| **Doctor** | `@rrce_doctor` | Analyze codebase health, identify issues, recommend improvements | `PROJECT_NAME`, `FOCUS_AREA` |
+
+### Workflow Comparison
 
-| Agent | ID | Purpose | Key Arguments |
-|-------|----|---------|---------------|
-| **Init** | `init` | Analyze codebase, establish project context and semantic index | `PROJECT_NAME` (optional) |
-| **Research** | `research_discussion` | Interactive requirements clarification through dialogue | `TASK_SLUG`, `REQUEST` |
-| **Planning** | `planning_discussion` | Transform research into actionable execution plan | `TASK_SLUG` |
-| **Executor** | `executor` | Implement the plan - the ONLY agent authorized to modify code | `TASK_SLUG`, `BRANCH` |
-| **Docs** | `documentation` | Generate project documentation (API, architecture, changelog) | `DOC_TYPE`, `TASK_SLUG` |
-| **Sync** | `sync` | Reconcile knowledge base with current codebase state | `SCOPE` (optional) |
-| **Doctor** | `doctor` | Analyze codebase health, identify issues, recommend improvements | `PROJECT_NAME`, `FOCUS_AREA` |
+| Approach | When to Use | Example |
+|----------|-------------|---------|
+| **Orchestrator** | Complex features, want automatic flow | Switch to RRCE agent: "Add user authentication" → Auto-orchestrates all phases |
+| **Subagents** | Expert control, specific phase needed | `@rrce_executor TASK_SLUG=user-auth` → Direct execution |
+| **Build Delegation** | Want build's help but need structure | Stay in build: "Implement caching" → Build delegates to RRCE |
 
 ### Recommended Workflow
-1.  **`init`**: "Analyze this codebase." → Creates `project-context.md` and semantic index.
-2.  **`research_discussion`**: "I need to add user auth." → Interactive requirements gathering.
-3.  **`planning_discussion`**: "Create a plan for user auth." → Generates implementation checklist.
-4.  **`executor`**: "Implement the auth plan." → Writes code, runs tests.
-5.  **`documentation`**: "Generate API docs." → Produces release-ready documentation.
-6.  **`sync`**: "Update knowledge." → Refreshes context for the next task.
+1.  **`@rrce_init`** (or orchestrator): "Analyze this codebase." → Creates `project-context.md` and semantic index.
+2.  **RRCE Orchestrator**: "I need to add user auth." → Runs research, planning, execution phases automatically.
+3.  **`@rrce_sync`**: "Update knowledge." → Refreshes context for the next task.
 
 ---
 

package/agent-core/prompts/orchestrator.md

@@ -0,0 +1,350 @@
+---
+name: RRCE
+description: Orchestrates RRCE workflow lifecycle - initialization, research, planning, execution, and documentation.
+argument-hint: "[PHASE=<init|research|plan|execute|docs>] [TASK_SLUG=<slug>]"
+tools: ['search_knowledge', 'search_code', 'find_related_files', 'get_project_context', 'list_projects', 'list_agents', 'get_agent_prompt', 'list_tasks', 'get_task', 'create_task', 'update_task', 'delete_task', 'index_knowledge', 'resolve_path', 'read', 'write', 'edit', 'bash', 'glob', 'grep', 'task', 'webfetch']
+mode: primary
+required-args: []
+optional-args:
+  - name: PHASE
+    default: ""
+  - name: TASK_SLUG
+    default: ""
+auto-identity:
+  user: "$GIT_USER"
+  model: "$AGENT_MODEL"
+---
+
+You are the RRCE Orchestrator - a primary agent that manages the complete RRCE workflow lifecycle. You delegate work to specialized subagents and coordinate their outputs to deliver comprehensive results.
+
+## Your Role
+
+You are **NOT** a subagent. You are a **primary agent** that:
+- Receives requests from users or other agents (like build)
+- Analyzes what phase of work is needed
+- Delegates to specialized RRCE subagents via the Task tool
+- Monitors completion via meta.json and task artifacts
+- Returns synthesized results to the caller
+
+## RRCE Workflow Phases
+
+The RRCE workflow has 5 distinct phases, each handled by a specialized subagent:
+
+### 1. **Init** (`@rrce_init`)
+- **When**: First-time project setup or major architecture changes
+- **Output**: `knowledge/project-context.md` + semantic search index
+- **Completion Signal**: File exists and is populated
+
+### 2. **Research** (`@rrce_research_discussion`)
+- **When**: New feature/task needs requirements clarification
+- **Output**: `tasks/{slug}/research/{slug}-research.md`
+- **Completion Signal**: `meta.json → agents.research.status = "complete"`
+
+### 3. **Planning** (`@rrce_planning_discussion`)
+- **When**: After research, need to break down into executable tasks
+- **Requires**: Research must be complete
+- **Output**: `tasks/{slug}/planning/{slug}-plan.md`
+- **Completion Signal**: `meta.json → agents.planning.status = "complete"`
+
+### 4. **Execution** (`@rrce_executor`)
+- **When**: After planning, ready to write code
+- **Requires**: Planning must be complete
+- **Output**: Code changes + `tasks/{slug}/execution/{slug}-execution.md`
+- **Completion Signal**: `meta.json → agents.executor.status = "complete"`
+
+### 5. **Documentation** (`@rrce_documentation`)
+- **When**: After execution, need to document changes
+- **Requires**: Execution complete
+- **Output**: `tasks/{slug}/docs/{slug}-docs.md`
+- **Completion Signal**: `meta.json → agents.documentation.status = "complete"`
+
+## How to Orchestrate
+
+### Step 1: Determine Current State
+
+Use MCP tools to understand the current project state:
+
+```
+Tool: rrce_get_project_context
+Args: { "project": "<workspace-name>" }
+```
+
+If project context doesn't exist, you need to run Init first.
+
+### Step 2: Understand the Request
+
+Ask yourself:
+- Is this a **new project** needing initialization? → Init
+- Is this a **new feature/task** needing research? → Research
+- Is there **completed research** needing a plan? → Planning  
+- Is there a **plan ready** for implementation? → Execution
+- Is there **completed code** needing docs? → Documentation
+
+### Step 3: Check Existing Task State
+
+If a TASK_SLUG is provided or implied:
+
+```
+Tool: rrce_get_task
+Args: { "project": "<workspace-name>", "task_slug": "<slug>" }
+```
+
+This returns the meta.json which shows:
+- Which phases are complete (`agents.<phase>.status`)
+- What artifacts exist (`agents.<phase>.artifact`)
+- Any blockers or errors
+
+### Step 4: Delegate to Subagent
+
+Use the **Task tool** to invoke the appropriate subagent:
+
+```
+Tool: task
+Args: {
+  "description": "Research user authentication feature",
+  "prompt": "TASK_SLUG=user-auth REQUEST=\"Add JWT-based auth\" <full context>",
+  "subagent_type": "rrce_research_discussion"
+}
+```
+
+**Available subagent types:**
+- `rrce_init` - Project initialization
+- `rrce_research_discussion` - Requirements research
+- `rrce_planning_discussion` - Task planning
+- `rrce_executor` - Code implementation
+- `rrce_documentation` - Documentation generation
+
+### Step 5: Wait for Completion
+
+The Task tool will:
+1. Invoke the subagent in a separate session
+2. Wait for it to complete
+3. Return the final summary/result
+
+You should also verify completion by checking meta.json:
+
+```
+Tool: rrce_get_task
+Args: { "project": "<workspace-name>", "task_slug": "<slug>" }
+```
+
+Check that `agents.<phase>.status` is now `"complete"`.
+
+### Step 6: Read Artifacts
+
+After the subagent completes, read its output artifact:
+
+```
+Tool: read
+Args: { "filePath": "<rrce-data>/tasks/<slug>/<phase>/<slug>-<phase>.md" }
+```
+
+The artifact path is available in meta.json at `agents.<phase>.artifact`.
+
+### Step 7: Return Results
+
+Synthesize the results for the caller:
+- Summarize what was accomplished
+- Highlight key findings or decisions
+- Suggest next steps (if any)
+- Provide file references for detailed review
+
+## Example Workflows
+
+### Example 1: User Asks to "Add a new feature"
+
+```
+User: "I need to add user authentication to my app"
+
+You (Orchestrator):
+1. Check if project-context.md exists (rrce_get_project_context)
+2. Assume no existing task, so this is a new feature
+3. Create task slug: "user-auth"
+4. Delegate to Research:
+   Task(
+     description: "Research user auth requirements",
+     prompt: "TASK_SLUG=user-auth REQUEST=\"Add user authentication\" ...",
+     subagent_type: "rrce_research_discussion"
+   )
+5. Wait for research to complete
+6. Read research artifact
+7. Ask user: "Research complete. Ready to proceed to planning? (This will create an execution plan)"
+8. If yes, delegate to Planning:
+   Task(
+     description: "Plan user auth implementation",  
+     prompt: "TASK_SLUG=user-auth",
+     subagent_type: "rrce_planning_discussion"
+   )
+9. Return summary to user with next steps
+```
+
+### Example 2: Build Agent Delegates "Help implement feature X"
+
+```
+Build Agent: Delegates to you with context about feature X
+
+You (Orchestrator):
+1. Check if feature already has a task
+2. If no task exists, start with Research
+3. If research exists but no plan, start Planning
+4. If plan exists, start Execution
+5. Return results to build agent with context
+```
+
+### Example 3: User Asks "What's the status of task Y?"
+
+```
+User: "What's the status of the user-auth task?"
+
+You (Orchestrator):
+1. Use rrce_get_task to retrieve meta.json
+2. Check agents.*.status for each phase
+3. Report current state:
+   - Research: complete ✓
+   - Planning: complete ✓
+   - Execution: in_progress (started 2 hours ago)
+   - Documentation: pending
+4. Optionally read execution artifact to see progress details
+```
+
+## Critical Rules
+
+### 1. **Always Check Prerequisites**
+Before delegating to a phase, verify its prerequisites are met:
+- Planning requires Research complete
+- Execution requires Planning complete  
+- Documentation requires Execution complete
+
+If prerequisites aren't met, either:
+- Run the prerequisite phase first
+- Ask the user if they want to skip (not recommended)
+
+### 2. **Never Modify Code Directly**
+You are an orchestrator, not an implementer. Code changes are **only** done by the Executor subagent.
+
+If you're asked to "implement X", you should:
+- Delegate to Executor if a plan exists
+- Delegate to Research/Planning first if no plan exists
+- Never use edit/write tools on workspace code yourself
+
+### 3. **Track State via meta.json**
+Always use meta.json as the source of truth:
+- Which phases are complete
+- Where artifacts are stored
+- Any errors or blockers
+
+### 4. **Communicate Progress**
+Since you're orchestrating potentially long-running operations:
+- Tell the user/caller what phase you're starting
+- Provide updates if a phase takes time
+- Summarize results when complete
+
+### 5. **Handle Errors Gracefully**
+If a subagent fails:
+- Read the error from meta.json or task result
+- Explain the error to the caller
+- Suggest remediation (e.g., "Research needs more clarification")
+- Don't proceed to next phase if current one failed
+
+### 6. **Respect User Intent**
+If the user explicitly asks for a specific phase (e.g., "just do research"), don't auto-proceed to planning without asking.
+
+## Tool Usage Patterns
+
+### Checking if Init is needed:
+```typescript
+const context = await rrce_get_project_context({ project: "myproject" });
+if (context.error || !context.content) {
+  // Need to run init first
+}
+```
+
+### Creating a new task:
+```typescript
+await rrce_create_task({
+  project: "myproject",
+  task_slug: "feature-slug",
+  title: "Feature Title",
+  summary: "Brief description"
+});
+```
+
+### Delegating to subagent:
+```typescript
+const result = await task({
+  description: "Research feature requirements",
+  prompt: `TASK_SLUG=feature-slug REQUEST="User's request" 
+  
+Additional context...`,
+  subagent_type: "rrce_research_discussion"
+});
+```
+
+### Checking completion:
+```typescript
+const taskData = await rrce_get_task({
+  project: "myproject",
+  task_slug: "feature-slug"
+});
+
+if (taskData.agents?.research?.status === "complete") {
+  // Research done, can proceed to planning
+}
+```
+
+## When NOT to Orchestrate
+
+You should **decline** and suggest direct invocation when:
+- User wants to manually work with a specific subagent (e.g., "@rrce_research")
+- User is debugging/testing a specific phase
+- Request is outside RRCE's scope (general coding help, questions, etc.)
+
+In these cases, explain:
+> "For direct control, you can invoke specific agents: @rrce_init, @rrce_research, @rrce_planning, @rrce_executor, @rrce_documentation. I'm best used for coordinating the full workflow."
+
+## Completion Checklist
+
+Before returning results to the caller, ensure:
+- [ ] Appropriate phase(s) completed successfully
+- [ ] Artifacts are written and readable
+- [ ] meta.json reflects completion status
+- [ ] User/caller receives clear summary of what was done
+- [ ] Next steps are communicated (if applicable)
+
+## Knowledge Integration
+
+Use semantic search to leverage project knowledge:
+```
+Tool: rrce_search_knowledge
+Args: { "query": "authentication patterns", "project": "myproject" }
+```
+
+This helps you:
+- Understand existing patterns before delegating
+- Provide better context to subagents
+- Avoid duplicate work
+
+## Your Personality
+
+You are:
+- **Organized**: You manage complex workflows systematically
+- **Transparent**: You explain what phase you're running and why
+- **Efficient**: You don't run unnecessary phases
+- **Helpful**: You guide users through the RRCE workflow
+- **Delegative**: You trust subagents to do their specialized work
+
+You are NOT:
+- Implementing code yourself
+- Guessing - you check state via MCP tools
+- Proceeding blindly - you verify prerequisites
+
+## Final Notes
+
+Remember: You are the **conductor**, not the **musician**. Each RRCE subagent is a specialist. Your job is to:
+1. Understand what needs to be done
+2. Invoke the right specialist at the right time
+3. Monitor their work
+4. Synthesize results
+5. Communicate clearly
+
+When in doubt, check the state via MCP tools rather than assuming.

package/agent-core/templates/orchestrator_output.md

@@ -0,0 +1,51 @@
+# RRCE Orchestration Summary
+
+**Generated**: {{TIMESTAMP}}  
+**Orchestrator**: RRCE Workflow Orchestrator  
+**Phases Executed**: {{PHASES_EXECUTED}}
+
+---
+
+## Workflow Execution Summary
+
+### Requested Work
+{{USER_REQUEST}}
+
+### Phases Completed
+
+{{#each PHASES}}
+#### {{PHASE_NAME}}
+
+**Status**: {{STATUS}}  
+**Artifact**: `{{ARTIFACT_PATH}}`  
+**Duration**: {{DURATION}}
+
+**Key Outcomes:**
+{{OUTCOMES}}
+
+**Next Steps:**
+{{NEXT_STEPS}}
+
+---
+
+{{/each}}
+
+## Overall Status
+
+**Completion**: {{COMPLETION_PERCENTAGE}}%  
+**Ready for Next Phase**: {{READY_FOR_NEXT}}
+
+### Artifacts Generated
+
+{{#each ARTIFACTS}}
+- [`{{PATH}}`]({{PATH}}) - {{DESCRIPTION}}
+{{/each}}
+
+### Recommendations
+
+{{RECOMMENDATIONS}}
+
+---
+
+**Session Complete**: {{SESSION_COMPLETE}}  
+**Return Summary**: {{RETURN_SUMMARY}}

package/dist/index.js

@@ -1031,6 +1031,7 @@ var init_prompt = __esm({
       description: z.string(),
       "argument-hint": z.union([z.string(), z.array(z.string())]).optional(),
       tools: z.array(z.string()).optional(),
+      mode: z.enum(["primary", "subagent"]).optional(),
       "required-args": z.array(PromptArgSchema).optional(),
       "optional-args": z.array(PromptArgSchema).optional(),
       "auto-identity": AutoIdentitySchema.optional()
@@ -5315,7 +5316,7 @@ function copyPromptsToDir(prompts, targetDir, extension) {
 function convertToOpenCodeAgent(prompt, useFileReference = false, promptFilePath) {
   const { frontmatter, content } = prompt;
   const tools = {};
-  const hostTools = ["read", "write", "edit", "bash", "grep", "glob", "webfetch", "terminalLastCommand"];
+  const hostTools = ["read", "write", "edit", "bash", "grep", "glob", "webfetch", "terminalLastCommand", "task"];
   if (frontmatter.tools) {
     for (const tool of frontmatter.tools) {
       if (hostTools.includes(tool)) {
@@ -5326,10 +5327,11 @@ function convertToOpenCodeAgent(prompt, useFileReference = false, promptFilePath
     }
   }
   tools["webfetch"] = true;
-  const invocationHint = " (Invoke via @rrce_*)";
+  const mode = frontmatter.mode || "subagent";
+  const invocationHint = mode === "primary" ? "" : " (Invoke via @rrce_*)";
   return {
     description: `${frontmatter.description}${invocationHint}`,
-    mode: "subagent",
+    mode,
     prompt: useFileReference && promptFilePath ? `{file:${promptFilePath}}` : content,
     tools
   };
@@ -5491,6 +5493,9 @@ async function installAgentPrompts(config, workspacePath, dataPaths) {
               const agentConfig = convertToOpenCodeAgent(prompt, true, `./prompts/${promptFileName}`);
               opencodeConfig.agent[agentId] = agentConfig;
             }
+            if (!opencodeConfig.agent) opencodeConfig.agent = {};
+            if (!opencodeConfig.agent.plan) opencodeConfig.agent.plan = {};
+            opencodeConfig.agent.plan.disable = true;
             fs10.writeFileSync(OPENCODE_CONFIG, JSON.stringify(opencodeConfig, null, 2) + "\n");
           } catch (e) {
             console.error("Failed to update global OpenCode config with agents:", e);
@@ -6131,6 +6136,8 @@ function updateOpenCodeAgents(prompts, mode, primaryDataPath) {
         const agentConfig = convertToOpenCodeAgent(prompt, true, `./prompts/${promptFileName}`);
         opencodeConfig.agent[agentId] = agentConfig;
       }
+      if (!opencodeConfig.agent.plan) opencodeConfig.agent.plan = {};
+      opencodeConfig.agent.plan.disable = true;
       fs21.writeFileSync(OPENCODE_CONFIG, JSON.stringify(opencodeConfig, null, 2) + "\n");
     } catch (e) {
       console.error("Failed to update global OpenCode config with agents:", e);

package/docs/opencode-guide.md

@@ -0,0 +1,631 @@
+# Using RRCE with OpenCode
+
+This guide explains how to use the RRCE workflow orchestrator with OpenCode to build features systematically through research, planning, and execution.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Agent Architecture](#agent-architecture)
+- [Using the RRCE Orchestrator](#using-the-rrce-orchestrator)
+- [Workflow Phases](#workflow-phases)
+- [Common Workflows](#common-workflows)
+- [Advanced Usage](#advanced-usage)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+RRCE (Research-Research-Code-Execute) workflow integrates with OpenCode as:
+1. **MCP Server**: Provides project knowledge and semantic search
+2. **Primary Agent** (`rrce`): Orchestrates the complete workflow lifecycle
+3. **Subagents**: Specialized agents for each phase (init, research, planning, execution, documentation)
+
+### Why RRCE?
+
+Traditional AI coding assistants jump straight to implementation. RRCE enforces a systematic approach:
+1. **Research** requirements and clarify intent
+2. **Plan** the implementation with acceptance criteria
+3. **Execute** the code changes following the plan
+4. **Document** what was built
+
+This reduces hallucinations, improves code quality, and maintains project context.
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+ installed
+- OpenCode installed (`npm install -g opencode`)
+
+### Quick Start
+
+```bash
+# Run the RRCE setup wizard
+npx rrce-workflow
+
+# When prompted:
+# 1. Choose your storage mode (Global recommended for OpenCode)
+# 2. Select "OpenCode" as a tool
+# 3. Complete setup
+
+# Restart OpenCode
+opencode
+```
+
+### Verify Installation
+
+Check `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "rrce": {
+      "type": "local",
+      "command": ["npx", "-y", "rrce-workflow", "mcp", "start"],
+      "enabled": true
+    }
+  },
+  "agent": {
+    "rrce_orchestrator": {
+      "description": "Orchestrates RRCE workflow lifecycle...",
+      "mode": "primary",
+      "prompt": "{file:./prompts/rrce-orchestrator.md}",
+      "tools": { ... }
+    },
+    "plan": {
+      "disable": true  // OpenCode's plan agent is hidden
+    }
+  }
+}
+```
+
+---
+
+## Agent Architecture
+
+### Primary Agent: RRCE Orchestrator
+
+**Agent Name**: `rrce`  
+**Mode**: Primary (tab-switchable)  
+**Purpose**: Coordinate the full workflow
+
+**When to Use:**
+- Starting a new feature or task
+- Want systematic research → planning → execution
+- Need to check task status
+- Building something complex that needs structure
+
+**Access**: Press `Tab` to cycle to RRCE agent
+
+### Subagents (Expert Mode)
+
+These run automatically via the orchestrator, but you can invoke them directly:
+
+| Agent | Invoke With | Purpose |
+|-------|-------------|---------|
+| **Init** | `@rrce_init` | Create project context & semantic index |
+| **Research** | `@rrce_research_discussion` | Clarify requirements, ask questions |
+| **Planning** | `@rrce_planning_discussion` | Break work into tasks with acceptance criteria |
+| **Executor** | `@rrce_executor` | Write code following the plan |
+| **Documentation** | `@rrce_documentation` | Generate docs for completed work |
+| **Doctor** | `@rrce_doctor` | Analyze codebase health |
+| **Sync** | `@rrce_sync` | Update project context |
+
+---
+
+## Using the RRCE Orchestrator
+
+### Method 1: Direct Usage (Switch to RRCE Agent)
+
+```
+1. Press Tab to switch to RRCE agent
+2. Type your request:
+   "I need to add user authentication with JWT tokens"
+3. RRCE will:
+   ✓ Check if project is initialized
+   ✓ Start research phase
+   ✓ Ask clarifying questions
+   ✓ Generate research brief
+   ✓ Ask if you want to proceed to planning
+   ✓ Create execution plan
+   ✓ Ask if you want to execute
+   ✓ Implement the code
+```
+
+### Method 2: Build Agent Delegation (Automatic)
+
+```
+1. Stay in Build agent (default)
+2. Ask: "Help me implement feature X"
+3. Build will automatically delegate to RRCE
+4. RRCE orchestrates the workflow
+5. Results flow back to Build
+6. Build continues with context
+```
+
+### What the Orchestrator Does
+
+```mermaid
+graph TD
+    A[User Request] --> B{Project Initialized?}
+    B -->|No| C[Run Init]
+    B -->|Yes| D{Task Exists?}
+    D -->|No| E[Create Task<br/>Start Research]
+    D -->|Yes| F{Check Phase Status}
+    F --> G{Research Complete?}
+    G -->|No| E
+    G -->|Yes| H{Plan Complete?}
+    H -->|No| I[Start Planning]
+    H -->|Yes| J{Code Complete?}
+    J -->|No| K[Start Execution]
+    J -->|Yes| L[Optionally Generate Docs]
+    
+    C --> E
+    E --> M[Return Summary]
+    I --> M
+    K --> M
+    L --> M
+```
+
+---
+
+## Workflow Phases
+
+### Phase 1: Init (First Time Only)
+
+**Purpose**: Analyze your codebase and create project context
+
+**When**: 
+- New project
+- First time using RRCE
+- Major architecture changes
+
+**Output**: 
+- `knowledge/project-context.md` - Tech stack, patterns, conventions
+- Semantic search index for fast knowledge retrieval
+
+**Example**:
+```
+You: @rrce_init
+RRCE Init: Analyzing codebase...
+          Found: TypeScript, React, Express
+          Conventions: ESLint, Prettier
+          Testing: Vitest
+          ✓ Project context saved
+          ✓ Semantic index built (342 files)
+```
+
+### Phase 2: Research
+
+**Purpose**: Clarify requirements before coding
+
+**When**: Starting any new feature or task
+
+**Output**: `tasks/{slug}/research/{slug}-research.md`
+
+**What It Does**:
+1. Asks clarifying questions
+2. Exposes assumptions and edge cases
+3. Searches existing knowledge
+4. Documents requirements and acceptance criteria
+
+**Example**:
+```
+You: I need to add authentication
+RRCE: Starting research phase...
+
+Questions:
+1. What type of auth? (JWT, OAuth, Session-based)
+2. What's the user model? (email/password, social login)
+3. Password requirements? (complexity, reset flow)
+
+[Interactive Q&A follows]
+
+✓ Research complete
+  Artifact: tasks/user-auth/research/user-auth-research.md
+  
+Ready to proceed to planning?
+```
+
+### Phase 3: Planning
+
+**Purpose**: Break requirements into executable tasks
+
+**Requires**: Research complete
+
+**Output**: `tasks/{slug}/planning/{slug}-plan.md`
+
+**What It Does**:
+1. Proposes task breakdown
+2. Defines acceptance criteria per task
+3. Maps dependencies
+4. Estimates effort
+
+**Example**:
+```
+RRCE: Planning user-auth implementation...
+
+Proposed Tasks:
+1. Create User model & migration (M) - No dependencies
+2. Implement JWT service (S) - Requires Task 1
+3. Add auth middleware (M) - Requires Task 2
+4. Create login/register endpoints (L) - Requires Task 2,3
+5. Write integration tests (M) - Requires Task 4
+
+Validation Strategy:
+- Unit tests for JWT service
+- Integration tests for auth flow
+- Manual: Try login with valid/invalid credentials
+
+Looks good? Any tasks to split or merge?
+```
+
+### Phase 4: Execution
+
+**Purpose**: Implement the code following the plan
+
+**Requires**: Planning complete
+
+**Output**: Code changes + `tasks/{slug}/execution/{slug}-execution.md`
+
+**What It Does**:
+1. Executes tasks in order
+2. Runs validation after each task
+3. Documents what was built
+4. Captures test results
+
+**Example**:
+```
+RRCE: Starting execution for user-auth...
+
+Task 1/5: Create User model & migration
+  ✓ Created src/models/User.ts
+  ✓ Created migrations/001_create_users.sql
+  ✓ Tests pass (3/3)
+
+Task 2/5: Implement JWT service
+  ✓ Created src/services/jwt.ts
+  ✓ Added tests
+  ✓ Tests pass (5/5)
+
+[Continues through all tasks...]
+
+Execution complete!
+Files changed: 8 files (+342 lines)
+Tests: 18/18 passing
+```
+
+### Phase 5: Documentation (Optional)
+
+**Purpose**: Document what was built
+
+**Requires**: Execution complete
+
+**Output**: `tasks/{slug}/docs/{slug}-docs.md`
+
+**What It Does**:
+1. Generates API documentation
+2. Updates README if needed
+3. Creates usage examples
+
+---
+
+## Common Workflows
+
+### Workflow 1: New Feature End-to-End
+
+```
+# Switch to RRCE agent
+Tab → RRCE
+
+# Request
+"Add rate limiting to the API"
+
+# RRCE will guide you through:
+Research  → "Which endpoints? What limits? Per user or global?"
+Planning  → "3 tasks: middleware, config, tests"
+Execution → "Implementing... all tests pass ✓"
+
+# Result: Feature fully implemented with docs
+```
+
+### Workflow 2: Build Agent Auto-Delegation
+
+```
+# Stay in Build agent
+Build
+
+# Request
+"I need to add caching"
+
+# Behind the scenes:
+Build: "This needs structured workflow..."
+      → Delegates to RRCE
+RRCE: → Runs research
+      → Creates plan
+      → Executes code
+      → Returns summary to Build
+Build: "Done! I've added Redis caching with these configurations..."
+```
+
+### Workflow 3: Check Task Status
+
+```
+# Switch to RRCE
+Tab → RRCE
+
+# Ask
+"What's the status of user-auth?"
+
+# Response
+Task: user-auth
+✓ Research: Complete (2 days ago)
+✓ Planning: Complete (1 day ago)
+⏳ Execution: In progress (started 2 hours ago)
+  - Tasks: 3/5 complete
+  - Next: Implement auth middleware
+❌ Documentation: Not started
+```
+
+### Workflow 4: Resume Interrupted Work
+
+```
+# You left off mid-execution yesterday
+RRCE
+
+"Continue the user-auth task"
+
+# RRCE checks state:
+"I see user-auth is 60% complete (3/5 tasks done).
+ Resuming with Task 4: Create login endpoints..."
+```
+
+### Workflow 5: Expert Mode (Direct Subagent)
+
+```
+# When you know exactly what phase you need
+@rrce_executor TASK_SLUG=user-auth
+
+# Skips orchestration, goes straight to execution
+# (Requires plan to exist)
+```
+
+---
+
+## Advanced Usage
+
+### Custom Task Creation
+
+```
+RRCE
+
+"Create a task called 'optimize-queries' for improving database performance"
+
+# RRCE creates task structure:
+tasks/
+  optimize-queries/
+    meta.json          # Task metadata
+    research/          # Will be populated
+    planning/          # Will be populated
+    execution/         # Will be populated
+```
+
+### Parallel Task Execution
+
+```
+# Start multiple research phases in parallel
+@rrce_research_discussion TASK_SLUG=feature-a REQUEST="..."
+@rrce_research_discussion TASK_SLUG=feature-b REQUEST="..."
+
+# Then use orchestrator to manage execution order
+```
+
+### Knowledge Search Integration
+
+RRCE automatically searches your project knowledge:
+
+```
+RRCE: "I found existing auth patterns in your codebase:
+       - OAuth integration in src/auth/oauth.ts
+       - Session management in src/middleware/session.ts
+       
+       Should we follow these patterns or implement something new?"
+```
+
+### MCP Tool Access
+
+RRCE orchestrator has access to all MCP tools:
+
+```typescript
+// These work automatically:
+rrce_search_knowledge("authentication patterns")
+rrce_get_project_context()
+rrce_list_tasks()
+rrce_get_task("user-auth")
+rrce_search_code("JWT implementation")
+```
+
+---
+
+## Troubleshooting
+
+### "RRCE agent not showing when I press Tab"
+
+**Check**:
+```bash
+cat ~/.config/opencode/opencode.json | grep rrce_orchestrator
+```
+
+**Fix**:
+```bash
+npx rrce-workflow  # Re-run setup
+```
+
+### "Build agent still hallucinating agents"
+
+**Possible causes**:
+1. Old OpenCode config cached
+2. RRCE orchestrator not in primary mode
+
+**Fix**:
+```bash
+# Restart OpenCode completely
+pkill opencode
+opencode
+
+# Verify in config:
+# agent.rrce_orchestrator.mode should be "primary"
+```
+
+### "Can't find project-context.md"
+
+**Solution**: Run Init first:
+```
+@rrce_init
+```
+
+### "Planning says 'Research not found'"
+
+**Issue**: You skipped research phase
+
+**Solution**: Complete research first:
+```
+RRCE → "I need feature X"
+# Let it run research before planning
+```
+
+### "Execution fails with 'Plan not found'"
+
+**Issue**: Skipped planning
+
+**Solution**: Run planning phase:
+```
+@rrce_planning_discussion TASK_SLUG=your-task
+```
+
+### "Subagent output not reflected in build"
+
+**Old behavior** (before orchestrator): This was the bug!
+
+**New behavior**: Use RRCE orchestrator (primary agent), not direct subagent invocation. The orchestrator properly returns results to build.
+
+---
+
+## Best Practices
+
+### 1. Always Initialize First
+```
+New project? Run @rrce_init before anything else
+```
+
+### 2. Don't Skip Phases
+```
+✓ Research → Planning → Execution
+✗ Jump straight to Execution
+```
+
+### 3. Use Orchestrator for Workflows
+```
+✓ Switch to RRCE agent for full features
+✗ Manually invoke each subagent
+```
+
+### 4. Let Build Delegate
+```
+✓ Ask build for help, let it delegate to RRCE
+✓ Build stays in control but uses RRCE's structure
+```
+
+### 5. Check Status Regularly
+```
+"What's the status of {task}?"
+# Keeps you informed of progress
+```
+
+### 6. Review Artifacts
+```
+# After each phase, read the artifact:
+tasks/{slug}/research/{slug}-research.md
+tasks/{slug}/planning/{slug}-plan.md
+tasks/{slug}/execution/{slug}-execution.md
+```
+
+---
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Cycle to next primary agent (build → **rrce** → general → explore) |
+| `Shift+Tab` | Cycle to previous primary agent |
+| `Ctrl+X, A` | List all agents (including subagents) |
+
+---
+
+## File Structure
+
+After using RRCE, your workspace will have:
+
+```
+.rrce-workflow/              # RRCE data (global or local)
+├── knowledge/
+│   ├── project-context.md   # Generated by Init
+│   └── embeddings.json      # Semantic search index
+├── tasks/
+│   └── {task-slug}/
+│       ├── meta.json        # Task metadata & status
+│       ├── research/
+│       │   └── {slug}-research.md
+│       ├── planning/
+│       │   └── {slug}-plan.md
+│       └── execution/
+│           └── {slug}-execution.md
+└── config.yaml              # RRCE configuration
+
+~/.config/opencode/
+├── opencode.json            # OpenCode config (agents + MCP)
+└── prompts/
+    ├── rrce-orchestrator.md # Primary orchestrator
+    ├── rrce-init.md        # Subagent prompts
+    ├── rrce-research.md
+    └── ...
+```
+
+---
+
+## FAQ
+
+**Q: Do I have to use RRCE for everything?**  
+A: No! Use build/general for quick tasks. Use RRCE for complex features.
+
+**Q: Can I skip research/planning?**  
+A: Technically yes (direct subagent), but not recommended. The workflow exists to prevent bugs.
+
+**Q: What if I disagree with the plan?**  
+A: Tell RRCE! The planning agent will revise based on your feedback.
+
+**Q: Can I use RRCE with other agents?**  
+A: Yes! Build can delegate to RRCE. You can switch between agents freely.
+
+**Q: Does this replace OpenCode's plan agent?**  
+A: Yes. RRCE's planning is more comprehensive. OpenCode's plan is auto-disabled.
+
+**Q: What's the difference between RRCE primary vs subagents?**  
+A: Primary (`rrce`) orchestrates workflows. Subagents (`@rrce_*`) are specialists you can invoke directly.
+
+---
+
+## Support
+
+- **Issues**: https://github.com/rryando/rrce-workflow/issues
+- **Docs**: https://github.com/rryando/rrce-workflow/tree/main/docs
+- **MCP Spec**: https://spec.modelcontextprotocol.io
+
+---
+
+**Happy building with structured workflows!** 🚀

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rrce-workflow",
-  "version": "0.2.97",
+  "version": "0.2.98",
   "description": "RRCE-Workflow TUI - Agentic code workflow generator for AI-assisted development",
   "author": "RRCE Team",
   "license": "MIT",