rrce-workflow 0.2.91 → 0.2.92

package/README.md

@@ -5,13 +5,14 @@
 [![npm version](https://badge.fury.io/js/rrce-workflow.svg)](https://www.npmjs.com/package/rrce-workflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-RRCE-Workflow is a tool that turns your AI coding assistant (GitHub Copilot, Claude Desktop, Antigravity IDE, etc.) into a **context-aware agent**. 
+RRCE-Workflow transforms your AI coding assistant (GitHub Copilot, OpenCode, Claude Desktop, Antigravity IDE) into a **context-aware agent** with persistent project knowledge.
 
-It standardizes how AI agents understand your project through:
-1.  **Global Knowledge Base**: Centralized context management across all your projects.
-2.  **MCP Hub**: A Model Context Protocol server that exposes your code and knowledge to any MCP-compatible client.
-3.  **Semantic Search (RAG)**: Local, privacy-first vector indexing for deep codebase understanding.
-4.  **Structured Agent Pipelines**: Reusable prompts for Research, Planning, Execution, and Documentation.
+**Key Features:**
+- **Global Knowledge Base**: Centralized context management across all your projects (`~/.rrce-workflow/`).
+- **MCP Hub**: A Model Context Protocol server exposing tools, resources, and prompts to any MCP-compatible client.
+- **Semantic Search (RAG)**: Local, privacy-first vector indexing powered by `@xenova/transformers` for deep codebase understanding.
+- **Structured Agent Pipelines**: 7 specialized agents (Init, Research, Planning, Executor, Docs, Sync, Doctor) for end-to-end development workflows.
+- **Task Management**: Built-in CRUD operations for tracking high-level tasks via MCP tools.
 
 ---
 
@@ -58,7 +59,24 @@ RRCE-Workflow uses the [Model Context Protocol](https://modelcontextprotocol.io/
 ### Features
 *   **Universal Context**: Access your project's `project-context.md`, architecture docs, and task history from *any* MCP-enabled tool.
 *   **Cross-Project References**: Your AI can read documentation from Project A while working on Project B (perfect for monorepos or microservices).
-*   **Tools & Resources**: Exposes tools like `search_knowledge` and `get_project_context` directly to the model.
+*   **12 MCP Tools**: Including `search_knowledge`, `get_project_context`, `resolve_path`, task CRUD operations, and more.
+
+### MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `resolve_path` | Resolve RRCE configuration paths (RRCE_DATA, WORKSPACE_ROOT, etc.) for a project |
+| `list_projects` | List all projects exposed via MCP |
+| `get_project_context` | Get the project-context.md for a specific project |
+| `search_knowledge` | Semantic search (RAG) across project knowledge bases |
+| `index_knowledge` | Update the semantic search index for a project |
+| `list_agents` | List available RRCE agents and their arguments |
+| `get_agent_prompt` | Get the system prompt for a specific agent with context injection |
+| `list_tasks` | List all tasks for a project |
+| `get_task` | Get details of a specific task |
+| `create_task` | Create a new task in the project |
+| `update_task` | Update an existing task's meta.json |
+| `delete_task` | Delete a task from the project |
 
 ### Connecting Your IDE
 
@@ -149,36 +167,40 @@ Stores everything in a `.rrce-workflow` folder inside your project root.
 
 ---
 
-## 🤖 The Agent Pipeline
+## The Agent Pipeline
 
-Once installed, you gain access to powerful agent workflows. Invoke them using your AI assistant's chat interface (if supported) or by pasting the prompts.
+Once installed, you gain access to 7 specialized agent workflows. Invoke them via your AI assistant's chat interface or through MCP tools.
 
-| Agent | Purpose | Recommended Use |
-|-------|---------|-----------------|
-| **Init** | **Context Establishment** | Run once at project start to analyze tech stack & architecture. |
-| **Research** | **Scope Definition** | Use when starting a complex feature to clarify requirements & risks. |
-| **Planning** | **Execution Strategy** | Generates a step-by-step implementation plan (checklist). |
-| **Execute** | **Implementation** | The "coding" phase. Implements the plan created by the Planning agent. |
-| **Docs** | **Documentation** | Generates tailored docs (API refs, guides) from code. |
-| **Sync** | **Knowledge Maintenance** | Scans code changes to update the `knowledge/` folder. |
-| **Doctor** | **Health Analysis** | Analyzes codebase for issues, tech debt, and improvement opportunities. |
+| 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` |
 
 ### Recommended Workflow
-1.  **`/init`**: "Analyze this codebase." -> Creates `project-context.md`.
-2.  **`/research`**: "I need to add user auth." -> Generates a Research Brief.
-3.  **`/plan`**: "Create a plan for user auth." -> Generates an Implementation Plan.
-4.  **`/execute`**: "Implement the auth plan." -> Writes code across files.
-5.  **`/sync`**: "Update knowledge." -> Refreshes context for the next task.
+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.
 
 ---
 
-## 🔍 Semantic Search (RAG)
+## Semantic Search (RAG)
 
-RRCE-Workflow includes a local, embedding-based search engine.
--   **Privacy First**: All embeddings are calculated locally on your CPU/GPU. No code leaves your machine.
--   **Smart Context**: Allows the agent to find relevant code snippets via natural language queries (e.g., "Find the authentication middleware logic") even if keywords don't match exactly.
+RRCE-Workflow includes a local, embedding-based search engine powered by `@xenova/transformers`.
 
-RAG is enabled by default in Express Setup. You can toggle it per-project in the MCP Dashboard.
+-   **Privacy First**: All embeddings are calculated locally. No code leaves your machine.
+-   **Full Codebase Indexing**: The `index_knowledge` tool scans your entire source tree (respecting skip lists like `node_modules`, `.git`).
+-   **Smart Fallback**: If RAG fails or isn't enabled, `search_knowledge` performs line-by-line text matching.
+-   **Model**: Uses `Xenova/all-MiniLM-L6-v2` by default (configurable per-project).
+
+RAG is enabled by default in Express Setup. You can toggle it per-project in the MCP Dashboard or via `config.yaml`.
 
 ---
 
@@ -187,6 +209,16 @@ RAG is enabled by default in Express Setup. You can toggle it per-project in the
 -   **Node.js 18+**
 -   **Git**
 
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| TUI Framework | Ink ^6.6.0 (React-based) |
+| MCP Server | @modelcontextprotocol/sdk ^1.25.1 |
+| Embeddings | @xenova/transformers ^2.17.2 |
+| Build | esbuild |
+| Runtime | Node.js >= 18 |
+
 ## License
 
 MIT © RRCE Team

package/dist/index.js

@@ -1,11 +1,5 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -1725,6 +1719,7 @@ var init_rag = __esm({
 // src/mcp/resources.ts
 import * as fs14 from "fs";
 import * as path16 from "path";
+import * as os2 from "os";
 import * as crypto from "crypto";
 function resolveProjectPaths(project, pathInput) {
   const config = loadMCPConfig();
@@ -2053,7 +2048,7 @@ function getContextPreamble() {
   const activeProject = detectActiveProject();
   let contextPreamble = "";
   if (activeProject) {
-    const rrceHome = process.env.RRCE_HOME || path16.join(__require("os").homedir(), ".rrce-workflow");
+    const rrceHome = process.env.RRCE_HOME || path16.join(os2.homedir(), ".rrce-workflow");
     const workspaceRoot = activeProject.sourcePath || activeProject.path || activeProject.dataPath;
     const rrceData = activeProject.dataPath;
     contextPreamble += `
@@ -2123,7 +2118,7 @@ async function createTask(projectName, taskSlug, taskData) {
   fs14.mkdirSync(path16.join(taskDir, "planning"), { recursive: true });
   fs14.mkdirSync(path16.join(taskDir, "execution"), { recursive: true });
   fs14.mkdirSync(path16.join(taskDir, "docs"), { recursive: true });
-  const rrceHome = process.env.RRCE_HOME || path16.join(__require("os").homedir(), ".rrce-workflow");
+  const rrceHome = process.env.RRCE_HOME || path16.join(os2.homedir(), ".rrce-workflow");
   const templatePath = path16.join(rrceHome, "templates", "meta.template.json");
   let meta = {
     task_id: crypto.randomUUID(),

package/docs/architecture.md

@@ -1,17 +1,19 @@
 # RRCE-Workflow Architecture
 
 > RR Context Engineering Workflow - A selection-agnostic agentic workflow system
+> 
+> **Version**: 0.2.91 | **Last Updated**: 2025-12-31
 
 ## Overview
 
 RRCE-Workflow is a TUI-based agentic code workflow generator designed to work seamlessly across:
-- **GitHub Copilot CLI**
+- **OpenCode** (Native agentic TUI environment with custom Primary Agents)
+- **GitHub Copilot** (VSCode with MCP extension)
 - **Antigravity IDE** (Google's agentic coding environment)
-- **OpenCode** (Native agentic TUI environment)
-- **VS Code** (with Copilot and other AI extensions)
-- **Claude Desktop**
+- **Claude Desktop** (MCP Server integration)
+- **Any MCP-compatible client**
 
-The system provides a structured multi-agent pipeline for software development tasks, with persistent knowledge caching and workspace-aware context management.
+The system provides a structured multi-agent pipeline (7 agents) for software development tasks, with persistent knowledge caching, semantic search (RAG), and workspace-aware context management.
 
 ## Core Principles
 
@@ -24,38 +26,79 @@ The system provides a structured multi-agent pipeline for software development t
 
 ## Directory Structure
 
+### Source Code Organization
+
+```
+rrce-workflow/
+├── agent-core/           # Agent prompts and templates (Source of Truth)
+│   ├── prompts/          # 7 agent system prompts (doctor, executor, init, etc.)
+│   ├── templates/        # Output templates for agents
+│   │   └── docs/         # Doc-type specific templates
+│   └── docs/             # Internal documentation (path-resolution.md)
+├── bin/                  # Executable entry points
+│   └── rrce-workflow.js  # NPM binary wrapper
+├── docs/                 # High-level architecture docs (this file)
+├── scripts/              # Maintenance and verification scripts
+├── src/                  # Source code
+│   ├── commands/         # CLI/TUI command implementations
+│   │   └── wizard/       # Interactive setup wizard (setup-flow, link-flow, etc.)
+│   ├── lib/              # Core utilities
+│   │   ├── detection.ts  # Project scanning and detection (DetectedProject)
+│   │   ├── detection-service.ts  # Singleton project service
+│   │   ├── git.ts        # Git utilities
+│   │   ├── paths.ts      # Path resolution (RRCE_HOME, RRCE_DATA, etc.)
+│   │   └── preferences.ts # User preference storage
+│   ├── mcp/              # MCP Server implementation
+│   │   ├── handlers/     # Decomposed request handlers
+│   │   │   ├── prompts.ts   # Prompt/agent handlers
+│   │   │   ├── resources.ts # Resource handlers
+│   │   │   └── tools.ts     # 12 MCP tools (search, index, tasks, etc.)
+│   │   ├── services/     # Backend services
+│   │   │   └── rag.ts    # Semantic search with @xenova/transformers
+│   │   ├── ui/           # TUI components (Ink/React)
+│   │   │   └── components/ # Reusable UI components
+│   │   ├── config.ts     # MCP configuration management
+│   │   ├── resources.ts  # Project data access utilities
+│   │   └── server.ts     # MCP Server entry point (Stdio transport)
+│   └── types/            # Global TypeScript definitions
+└── temp_rag_test/        # RAG testing environment
+```
+
 ### Global Installation (`~/.rrce-workflow/`)
 
 ```
 ~/.rrce-workflow/
-├── config.yaml                              # User global configuration
-├── templates/                               # Default template store
-│   ├── meta.template.json                   # Task metadata template
-│   ├── research_output.md                   # Research brief template
-│   ├── planning_output.md                   # Execution plan template
-│   ├── executor_output.md                   # Implementation log template
-│   ├── documentation_output.md              # Handover note template
-│   └── docs/                                # Doc-type specific templates
-│       └── <doc-type>.md
-└── workspaces/                              # Project-scoped cache
-    └── <workspace-hash>/                    # SHA256 of workspace path
-        ├── workspace.json                   # Workspace metadata
-        ├── knowledge/                       # Project domain knowledge
-        │   └── <domain>.md
-        └── tasks/                           # Task state and artifacts
+├── mcp.yaml                             # MCP server configuration (projects, permissions)
+├── preferences.json                     # User preferences (global path overrides)
+├── templates/                           # Default template store
+│   ├── meta.template.json               # Task metadata template
+│   └── docs/                            # Doc-type specific templates
+└── workspaces/                          # Project-scoped data (Global Mode)
+    └── <workspace-name>/                # Named by project, not hash
+        ├── config.yaml                  # Project configuration
+        ├── knowledge/                   # Project domain knowledge
+        │   ├── project-context.md       # Main context file
+        │   ├── embeddings.json          # RAG vector index
+        │   └── <topic>.md               # Additional knowledge files
+        ├── refs/                        # Reference documents
+        └── tasks/                       # Task state and artifacts
             └── <task-slug>/
-                ├── meta.json                # Task metadata and status
-                ├── research/                # Research artifacts
-                ├── planning/                # Planning artifacts
-                ├── execution/               # Execution logs
-                └── docs/                    # Generated documentation
+                ├── meta.json            # Task metadata, checklist, agent status
+                ├── research/            # Research artifacts
+                ├── planning/            # Planning artifacts
+                ├── execution/           # Execution logs
+                └── docs/                # Generated documentation
 ```
 
-### Workspace Configuration (Optional)
+### Workspace Mode (`.rrce-workflow/`)
 
 ```
 <workspace>/
-└── .rrce-workflow.yaml                      # Project-specific config
+└── .rrce-workflow/
+    ├── config.yaml                      # Project-specific config
+    ├── knowledge/                       # Project knowledge (same structure as global)
+    ├── refs/
+    └── tasks/
 ```
 
 ---
@@ -69,19 +112,28 @@ The system provides a structured multi-agent pipeline for software development t
 | `global` (default) | `~/.rrce-workflow/workspaces/<workspace-name>/` | Non-intrusive, survives repo deletion |
 | `workspace` | `<workspace>/.rrce-workflow/` | Portable, team-shareable |
 
-Configure via `.rrce-workflow.yaml`:
+Configure via `config.yaml`:
 ```yaml
-storage:
-  mode: global  # or: workspace
+mode: global  # or: workspace
+name: my-project
+sourcePath: /path/to/source  # For global mode: links data back to source
 ```
 
+### Key Path Functions (`src/lib/paths.ts`)
+
+| Function | Purpose |
+|----------|---------|
+| `getEffectiveGlobalPath()` | Returns RRCE_HOME respecting user preferences |
+| `getConfigPath(workspaceRoot)` | Finds config.yaml (local or global) |
+| `resolveDataPath(mode, name, root)` | Resolves RRCE_DATA based on storage mode |
+| `detectWorkspaceRoot()` | Walks up from CWD to find project root |
+
 ### Environment Variables
 
 | Variable | Purpose | Default |
 |----------|---------|---------|
 | `RRCE_HOME` | Global installation path | `~/.rrce-workflow` |
 | `RRCE_WORKSPACE` | Explicit workspace root | Auto-detected |
-| `RRCE_AUTHOR` | Default author name | From `config.yaml` |
 
 ### Template Variables
 
@@ -89,7 +141,7 @@ storage:
 |----------|-------------|
 | `{{RRCE_HOME}}` | Global installation path |
 | `{{RRCE_DATA}}` | Data path (based on storage mode) |
-| `{{WORKSPACE_ROOT}}` | Workspace directory |
+| `{{WORKSPACE_ROOT}}` | Workspace directory (source code location) |
 | `{{WORKSPACE_NAME}}` | Project name (from config or directory) |
 
 ### Workspace Detection Algorithm
@@ -98,10 +150,32 @@ storage:
 1. If $RRCE_WORKSPACE is set → use it
 2. Walk up from CWD, find first directory containing:
    - .git/
-   - .rrce-workflow.yaml
+   - .rrce-workflow/config.yaml (new)
+   - .rrce-workflow.yaml (legacy)
 3. Fall back to CWD
 ```
 
+### Project Detection (`src/lib/detection.ts`)
+
+The `DetectedProject` interface captures:
+```typescript
+interface DetectedProject {
+  name: string;
+  path: string;           // Absolute path to project root
+  dataPath: string;       // Path to .rrce-workflow data directory
+  source: 'global' | 'local';
+  sourcePath?: string;    // For global mode: actual source code location
+  knowledgePath?: string;
+  tasksPath?: string;
+  semanticSearchEnabled?: boolean;
+}
+```
+
+Scanning priority:
+1. Known projects from MCP config (name + path)
+2. Global storage (`~/.rrce-workflow/workspaces/`)
+3. Home directory recursive scan (up to depth 5)
+
 ### Cross-Project References
 
 Reference another project's context when needed:
@@ -125,13 +199,13 @@ Reference another project's context when needed:
                                     └────────┬────────┘
                                              │
                                              ▼
-                                  project-context.md
+                                  project-context.md + embeddings.json
                                              │
         ┌────────────────────────────────────┴────────────────────────────────────┐
         ▼                                                                          │
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
 │    Research     │────▶│    Planning     │────▶│    Executor     │────▶│  Documentation  │
-│   & Discussion  │     │  Orchestrator   │     │                 │     │                 │
+│   Discussion    │     │   Discussion    │     │ (Code Changes)  │     │                 │
 └─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │                       │
         ▼                       ▼                       ▼                       ▼
@@ -139,43 +213,74 @@ Reference another project's context when needed:
         │                       │                       │                       │
         └───────────────────────┴───────────────────────┴───────────────────────┘
                                         │
-                                        ▼
-                            {{RRCE_CACHE}}/knowledge/
-                              (Persistent Context)
+                               ┌────────┴────────┐
+                               ▼                 ▼
+                       {{RRCE_DATA}}/      ┌─────────────────┐
+                         knowledge/        │      Sync       │
+                                           │ (Reconciliation)│
+                                           └────────┬────────┘
+                                                    │
+                                           ┌────────┴────────┐
+                                           ▼                 ▼
+                                       Doctor           (Next Task)
+                                    (Health Check)
 ```
 
 ### Agent Responsibilities
 
-| Agent | Role | Input | Output |
-|-------|------|-------|--------|
-| **Init** | Analyze codebase, establish project context | Workspace files | `project-context.md` |
-| **Research & Discussion** | Clarify requirements, surface risks | User request + context | Requirements brief |
-| **Planning Orchestrator** | Create actionable execution plan | Research brief | Prioritized task breakdown |
-| **Executor** | Implement and verify | Plan + skill scope | Code + execution log |
-| **Documentation** | Synthesize and handover | All artifacts | Release-ready docs |
-| **Sync** | Reconcile knowledge | Codebase state | Updated knowledge files |
+| Agent | ID | Role | Input | Output |
+|-------|-----|------|-------|--------|
+| **Init** | `init` | Analyze codebase, establish project context, build RAG index | Workspace files | `project-context.md`, `embeddings.json` |
+| **Research** | `research_discussion` | Interactive requirements clarification, surface risks | User request + context | Research brief |
+| **Planning** | `planning_discussion` | Create actionable execution plan with checklist | Research brief | Prioritized task breakdown |
+| **Executor** | `executor` | Implement and verify - ONLY agent that modifies code | Plan + skill scope | Code + execution log |
+| **Documentation** | `documentation` | Synthesize and handover | All artifacts | Release-ready docs |
+| **Sync** | `sync` | Reconcile knowledge with codebase state | Codebase state | Updated knowledge files |
+| **Doctor** | `doctor` | Analyze codebase health using semantic search | Project + focus area | Health report, improvement tasks |
 
 ---
 
 ## Configuration
 
-### Global Config (`~/.rrce-workflow/config.yaml`)
+### MCP Configuration (`~/.rrce-workflow/mcp.yaml`)
 
 ```yaml
-version: 1
+# Projects exposed to MCP clients
+projects:
+  - name: my-project
+    path: /path/to/my-project
+    permissions:
+      knowledge: true
+      tasks: true
+      prompts: true
+    semanticSearch:
+      enabled: true
+      model: Xenova/all-MiniLM-L6-v2
+```
 
-# User identity
-author: "your-name"
-email: "your@email.com"
+### Project Config (`<workspace>/.rrce-workflow/config.yaml` or global)
 
-# Default behaviors
-defaults:
-  auto_create_workspace_cache: true
-  sync_after_execution: false
-  
-# Editor integration hints (informational)
-editor:
-  preferred: "vscode"  # vscode | antigravity | vim | etc.
+```yaml
+name: my-project
+mode: global  # or: workspace
+sourcePath: /path/to/source  # For global mode
+
+# Semantic search configuration
+semantic_search:
+  enabled: true
+
+# Cross-project linking
+linked_projects:
+  - other-project
+```
+
+### User Preferences (`~/.rrce-workflow/preferences.json`)
+
+```json
+{
+  "defaultGlobalPath": "/custom/path/.rrce-workflow",
+  "useCustomGlobalPath": true
+}
 ```
 
 ### Project Config (`<workspace>/.rrce-workflow.yaml`)
@@ -205,89 +310,78 @@ author: "maintainer-name"    # Overrides global config for this project
 
 ## Prompt Frontmatter Schema
 
-All agent prompts use YAML frontmatter for metadata and tool compatibility:
+All agent prompts in `agent-core/prompts/` use YAML frontmatter for metadata:
 
 ```yaml
 ---
-description: Brief description of the agent's purpose
-argument-hint: CLI-style argument hint for display
-agent: agent | ask | edit              # Copilot mode
-tools: ['search/codebase', ...]        # Available Copilot tools
-required-args:
-  - name: ARG_NAME
-    prompt: "Interactive prompt if arg is missing"
-optional-args:
-  - name: ARG_NAME
-    default: "default value"
-auto-identity:
-  user: "$GIT_USER"      # Auto-detect from `git config user.name`
-  model: "$AGENT_MODEL"  # Auto-detect from runtime (gemini-2.0, claude-sonnet, etc.)
+name: RRCE Executor
+description: Execute the planned tasks to deliver working code and tests.
+tools:
+  - read
+  - write
+  - edit
+  - bash
+  - glob
+  - grep
+  - search_knowledge        # MCP tool (becomes rrce_search_knowledge in OpenCode)
+  - get_project_context     # MCP tool
+  - update_task             # MCP tool
+arguments:
+  - name: TASK_SLUG
+    description: Enter the task slug to execute
+    required: true
+  - name: BRANCH
+    description: Git branch for the work
+    required: false
 ---
-```
 
-### Auto-Identity
+# Agent System Prompt Content...
+```
 
-Identity is automatically detected - no user input required:
+### Tool Categories
 
-| Variable | Source | Example |
-|----------|--------|---------|
-| `$GIT_USER` | `git config user.name` | "John Doe" |
-| `$AGENT_MODEL` | Runtime environment | "gemini-2.0-flash", "claude-sonnet-4" |
+| Category | Tools | Notes |
+|----------|-------|-------|
+| **Host Tools** | `read`, `write`, `edit`, `bash`, `grep`, `glob`, `webfetch` | Native to host environment |
+| **MCP Tools** | `search_knowledge`, `get_project_context`, `list_tasks`, etc. | Prefixed with `rrce_` in OpenCode |
 
 ---
 
 ## Multi-Tool Integration
 
-RRCE-Workflow prompts are designed to work across multiple AI coding tools:
+RRCE-Workflow prompts are designed to work across multiple AI coding tools via MCP and IDE-specific agent generation.
 
 ### Tool Support Matrix
 
-| Tool | Prompt Location | Extension | Notes |
-|------|----------------|-----------|-------|
-| **Antigravity IDE** | `.agent/workflows/` | `.md` | Native workflow support |
-| **OpenCode** | `.opencode/agent/` | `.md` | Custom Primary Agents |
-| **GitHub Copilot (VSCode)** | `.github/agents/` | `.agent.md` | Custom agents format |
-| **Copilot CLI** | Any location | `.md` | Reference via file path |
-
-### Wizard Command
+| Tool | MCP Config Location | Agent Location | Notes |
+|------|---------------------|----------------|-------|
+| **OpenCode** | `~/.config/opencode/opencode.json` | `.opencode/agent/rrce-*.md` | Custom Primary Agents (Tab to switch) |
+| **Antigravity IDE** | `~/.gemini/antigravity/mcp_config.json` | `.agent/workflows/*.md` | Native workflow support |
+| **GitHub Copilot (VSCode)** | `.vscode/mcp.json` or global settings | `.github/prompts/*.prompt.md` | Custom agents format |
+| **Claude Desktop** | `~/.config/claude/claude_desktop_config.json` | N/A | MCP Server only |
 
-The TUI provides an interactive wizard to set up prompts for your preferred tools:
+### OpenCode Agent Transformation
 
-```
-$ rrce-workflow wizard
-
-┌─────────────────────────────────────────────────────────┐
-│  RRCE-Workflow Project Setup                            │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│  Which AI tools do you use?                             │
-│                                                         │
-│  [x] GitHub Copilot (VSCode)                            │
-│  [x] Antigravity IDE                                    │
-│  [ ] Copilot CLI only                                   │
-│                                                         │
-│  ─────────────────────────────────────────────────────  │
-│                                                         │
-│  ✓ Created .github/prompts/*.prompt.md                  │
-│  ✓ Created .agent/workflows/*.md                        │
-│  ✓ Initialized project context                          │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
+When generating agents for OpenCode (`src/commands/wizard/utils.ts`):
+- **Mode**: Set to `primary` (enables Tab cycling in TUI)
+- **Tools**: 
+  - Host tools (`read`, `write`, `edit`, `bash`, `grep`, `glob`, `webfetch`) pass through as-is
+  - MCP tools are prefixed with `rrce_` (e.g., `rrce_search_knowledge`)
+  - Tool list respects per-agent frontmatter restrictions
+- **Naming**: Agents prefixed with `rrce-` to avoid collisions
 
 ### Generated Files
 
-When you run `rrce-workflow wizard`, it creates:
-
-**For GitHub Copilot (VSCode):**
+**For OpenCode:**
 ```
-.github/prompts/
-├── init.prompt.md
-├── research.prompt.md
-├── planning.prompt.md
-├── executor.prompt.md
-├── documentation.prompt.md
-└── sync.prompt.md
+.opencode/agent/
+├── rrce-init.md
+├── rrce-research.md
+├── rrce-planning.md
+├── rrce-executor.md
+├── rrce-documentation.md
+├── rrce-sync.md
+└── rrce-doctor.md
 ```
 
 **For Antigravity IDE:**
@@ -298,55 +392,81 @@ When you run `rrce-workflow wizard`, it creates:
 ├── planning.md
 ├── executor.md
 ├── documentation.md
-└── sync.md
+├── sync.md
+└── doctor.md
 ```
 
-**For OpenCode:**
+**For GitHub Copilot (VSCode):**
 ```
-.opencode/agent/
-├── rrce-init.md
-├── rrce-research.md
-├── rrce-planning.md
-├── rrce-executor.md
-├── rrce-documentation.md
-└── rrce-sync.md
+.github/prompts/
+├── init.prompt.md
+├── research.prompt.md
+├── planning.prompt.md
+├── executor.prompt.md
+├── documentation.prompt.md
+├── sync.prompt.md
+└── doctor.prompt.md
 ```
 
-### Copilot-Specific Features
+---
+
+## MCP Server Architecture
+
+The MCP Server (`src/mcp/`) provides the bridge between project knowledge and AI agents.
+
+### Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| **Server Entry** | `src/mcp/server.ts` | Initializes server, registers handlers, manages Stdio transport |
+| **Tool Handlers** | `src/mcp/handlers/tools.ts` | 12 MCP tools (search, index, tasks, resolve_path, etc.) |
+| **Prompt Handlers** | `src/mcp/handlers/prompts.ts` | Agent system prompts with context injection |
+| **Resource Handlers** | `src/mcp/handlers/resources.ts` | Knowledge files and project context as readable resources |
+| **RAG Service** | `src/mcp/services/rag.ts` | Semantic search with @xenova/transformers |
+| **Resources Utilities** | `src/mcp/resources.ts` | Project data access, task CRUD, context preamble generation |
+
+### Context Injection
 
-Our prompts include Copilot-compatible frontmatter:
+When an agent requests a prompt via `get_agent_prompt`, the server injects a **Context Preamble** containing:
+- **System Resolved Paths**: Pre-resolved `RRCE_DATA`, `WORKSPACE_ROOT`, `RRCE_HOME`
+- **Available Projects**: List of exposed projects with active project marked
+- **Active Workspace**: Current project context for file operations
 
-| Field | Purpose | Values |
-|-------|---------|--------|
-| `agent` | Execution mode | `agent` (full), `ask` (read-only), `edit` (code changes) |
-| `tools` | Available tools | `search/codebase`, `search/web`, `terminalLastCommand`, etc. |
+### Semantic Search (RAG)
+
+| Feature | Implementation |
+|---------|----------------|
+| **Embedding Model** | `Xenova/all-MiniLM-L6-v2` (configurable) |
+| **Index Location** | `<knowledge>/embeddings.json` |
+| **Similarity** | Cosine similarity |
+| **Indexable Extensions** | `.ts`, `.tsx`, `.js`, `.py`, `.go`, `.rs`, `.md`, etc. |
+| **Skip Directories** | `node_modules`, `.git`, `dist`, `build`, etc. |
 
 ---
 
-## Installation Flow (TUI First Run)
+## Installation Flow
 
+```bash
+# Option 1: MCP Dashboard (recommended)
+npx rrce-workflow mcp
+
+# Option 2: Project Setup Wizard
+cd your-project
+npx rrce-workflow
+
+# Option 3: Start MCP Server directly (for IDE config)
+npx rrce-workflow mcp start
 ```
-$ npx rrce-workflow
-
-┌─────────────────────────────────────────────────────────┐
-│  RRCE-Workflow Setup Wizard                             │
-├─────────────────────────────────────────────────────────┤
-│                                                         │
-│  Welcome! Let's configure your workflow environment.    │
-│                                                         │
-│  Your name: [_________________]                         │
-│  Email (optional): [_________________]                  │
-│                                                         │
-│  ─────────────────────────────────────────────────────  │
-│                                                         │
-│  ✓ Created ~/.rrce-workflow/config.yaml                │
-│  ✓ Installed default templates                          │
-│  ✓ Ready to use!                                        │
-│                                                         │
-│  Run `rrce-workflow help` for available commands.       │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
+
+---
+
+## Key Design Patterns
+
+1. **MCP Decoupling**: Handlers separated from server instance for maintainability
+2. **TUI/MCP Separation**: MCP runs in "interactive" mode to avoid stdio conflicts with TUI
+3. **Prompt Parsing**: Frontmatter-based prompts with variable injection
+4. **Hybrid Storage**: Global mode (clean repos) vs Workspace mode (portable)
+5. **DetectedProject.sourcePath**: For global mode, links data back to actual source location
 
 ---
 
@@ -355,5 +475,7 @@ $ npx rrce-workflow
 - [ ] Web UI for knowledge browsing
 - [ ] Cross-project knowledge sharing (opt-in)
 - [ ] Plugin system for custom agents
-- [ ] LLM-agnostic (support OpenAI, Anthropic, Gemini, local models)
+- [ ] Comprehensive test suite (Jest/Vitest)
+- [ ] CI/CD with GitHub Actions
+- [ ] Cross-platform parity (Windows/macOS)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rrce-workflow",
-  "version": "0.2.91",
+  "version": "0.2.92",
   "description": "RRCE-Workflow TUI - Agentic code workflow generator for AI-assisted development",
   "author": "RRCE Team",
   "license": "MIT",
@@ -39,7 +39,10 @@
     "wizard": "npx tsx src/index.ts wizard",
     "start": "npx tsx src/index.ts",
     "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "engines": {
     "node": ">=18"
@@ -62,8 +65,10 @@
   "devDependencies": {
     "@types/node": "^25.0.3",
     "@types/react": "^19.2.7",
+    "@vitest/coverage-v8": "^4.0.16",
     "esbuild": "^0.27.2",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   }
 }