rrce-workflow 0.2.61 → 0.2.63

package/README.md

@@ -1,197 +1,71 @@
 # RRCE-Workflow
 
-> Agentic code workflow generator for AI-assisted development
+> **Agentic code workflow generator for AI-assisted development**
 
 [![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 CLI wizard that sets up AI agent prompts and workflows for your codebase. It works with **GitHub Copilot**, **Antigravity IDE**, and other AI coding assistants.
+RRCE-Workflow is a tool that turns your AI coding assistant (GitHub Copilot, Claude Desktop, Antigravity IDE, etc.) into a **context-aware agent**. 
 
-## Installation
-
-```bash
-# Quick start (no install needed)
-npx rrce-workflow
-
-# Or install globally
-npm install -g rrce-workflow
-```
+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.
 
 ---
 
-## How to Use
+## 🚀 Quick Start
 
-### 1. Initial Setup
+### 1. The MCP Dashboard (TUI)
 
-Run the wizard in your project directory:
+The central command center for RRCE-Workflow is the **MCP Dashboard**. It lets you manage your projects, server status, and IDE integrations.
 
 ```bash
-cd your-project
-npx rrce-workflow
-```
-
-The wizard will:
-1. Ask where to store workflow data (global or workspace)
-2. Let you choose a custom global path if the default isn't writable
-3. Ask which AI tools you use (GitHub Copilot, Antigravity)
-4. Set up prompts and knowledge folders
-
-### 2. Using the Agent Prompts
-
-After setup, you'll have agent prompts in IDE-specific folders:
-
-- **GitHub Copilot**: `.github/agents/*.agent.md`
-- **Antigravity**: `.agent/workflows/*.md`
-
-In your AI assistant, invoke prompts using their names:
-
-| Agent | Invoke With | What It Does |
-|-------|-------------|--------------|
-| **Init** | `/init` | Analyze your codebase and create `project-context.md` |
-| **Research** | `/research REQUEST="..." TASK_SLUG=my-task` | Clarify requirements, create research brief |
-| **Planning** | `/plan TASK_SLUG=my-task` | Create actionable execution plan |
-| **Execute** | `/execute TASK_SLUG=my-task` | Implement the planned work |
-| **Docs** | `/docs DOC_TYPE=architecture` | Generate documentation |
-| **Sync** | `/sync` | Update knowledge base after code changes |
-
-### 3. Recommended Workflow (RRCE Pipeline)
-
-```
-1. /init       → Establish project context
-2. /research   → Clarify requirements for a new task
-3. /plan       → Create execution plan
-4. /execute    → Implement the plan
-5. /docs       → Generate documentation (optional)
-6. /sync       → Keep knowledge base current (periodic)
-```
-
-#### Pipeline Stages Explained
-
-**🔍 Init** — Scans your codebase to understand tech stack, architecture, coding conventions, and project structure. Creates `project-context.md` that all other agents rely on. Run once at project start, and again when major changes occur.
-
-**💬 Research** — Entry point for new tasks. Takes a user request and engages in clarifying discussion to refine scope, surface risks, and identify gaps. Produces a research brief for the Planning agent.
-
-**📋 Planning** — Transforms the research brief into an ordered, actionable execution plan. Breaks work into tasks with dependencies, acceptance criteria, and testing strategy. Ensures the Executor has clear guidance.
-
-**⚡ Execute** — Implements the planned work. Writes code, adds tests, runs verifications. Updates task metadata and logs execution notes for auditability.
-
-**📄 Docs** — Synthesizes the completed work into documentation. Can generate API docs, architecture overviews, runbooks, or changelogs based on `DOC_TYPE`.
-
-**🔄 Sync** — Maintenance agent that reconciles the knowledge base with actual code. Run periodically to catch drift and keep documentation accurate.
-
----
-
-## How It Works
-
-### Path Resolution
-
-All agents read `.rrce-workflow/config.yaml` to resolve paths:
-
-```yaml
-storage:
-  mode: workspace        # or: global
-  globalPath: "~/.rrce-workflow"  # optional custom path
-
-project:
-  name: "my-project"
-```
-
-Agents resolve `{{RRCE_DATA}}` based on storage mode:
-- `global` → `~/.rrce-workflow/workspaces/my-project/`
-
-### Cross-Project References
-
-When using `global` mode, you can reference other projects:
-
-```
-~/.rrce-workflow/workspaces/other-project/knowledge/project-context.md
+npx rrce-workflow mcp
 ```
 
-This enables a frontend app to reference its backend API's knowledge!
-
----
+From this dashboard, you can:
+-   **Manage Projects**: Toggle which projects are exposed to your AI agents.
+-   **Monitor Status**: See the health of the MCP server and RAG indexing.
+-   **Install to IDE**: Automatically configure **VSCode** or **Claude Desktop** to use the RRCE MCP server.
+-   **View Logs**: Debug agent interactions in real-time.
 
-## Folder Structure
+### 2. Setting Up a Project
 
-After setup, your project will have:
+To enable agent workflows for your current project, run the setup wizard:
 
+```bash
+cd your-project
+npx rrce-workflow
 ```
-your-project/
-├── .rrce-workflow/           # Data storage
-│   ├── config.yaml           # Configuration
-│   ├── knowledge/            # Project context
-│   ├── refs/                 # External references
-│   ├── tasks/                # Task artifacts by slug
-│   └── templates/            # Output templates
-├── .github/agents/           # GitHub Copilot prompts
-│   └── *.agent.md
-└── .agent/workflows/         # Antigravity prompts
-    └── *.md
-```
-
----
-
-## Wizard Options
-
-When you run the wizard on an already-configured project, you'll see:
-
-| Option | Description |
-|--------|-------------|
-| **Link other project knowledge** | Reference knowledge from other projects in global storage |
-| **Sync to global storage** | Copy workspace data to global (enables cross-project access) |
-| **Update from package** | Get latest prompts and templates |
-| **Reconfigure project** | Change storage mode, selected tools, or linked projects without resetting |
-
----
-
-## Storage Mode Comparison
-
-| Mode | Location | Best For |
-|------|----------|----------|
-| `global` | `~/.rrce-workflow/workspaces/<name>/` | Clean workspace, cross-project references |
-| `workspace` | `.rrce-workflow/` | Team sharing, portable with repo |
 
----
-
-## Custom Global Path
+You can choose between:
 
-If the default `~/.rrce-workflow` isn't writable (common with `npx` in enterprise environments), the wizard lets you choose a custom location:
-
-```yaml
-storage:
-  mode: global
-  globalPath: "/path/to/custom/rrce-workflow"
-```
+*   **⚡ Express Setup**: Configures the project using recommended defaults:
+    *   **Global Storage**: Keeps your project directory clean; config lives in `~/.rrce-workflow/`.
+    *   **MCP Enabled**: Exposes the project to your AI tools via the local server.
+    *   **RAG Enabled**: Indexes your code for semantic search.
+    
+*   **⚙️ Custom Setup**: Full control over storage location (Global vs Workspace), tool selection, and more.
 
 ---
 
-## MCP Hub (Cross-Project AI Access)
-
-RRCE-Workflow includes an **MCP (Model Context Protocol) Hub** that exposes your project knowledge to AI assistants like **VSCode Copilot** and **Claude Desktop**.
-
-### Quick Start
-
-```bash
-# Start the MCP Hub
-npx rrce-workflow mcp
-
-# Or run directly
-npx rrce-workflow mcp start
-```
+## 🧠 Model Context Protocol (MCP)
 
-### MCP Features
+RRCE-Workflow uses the [Model Context Protocol](https://modelcontextprotocol.io/) to bridge your codebase with AI models. This allows your AI assistant to "see" your project context without needing to manually copy-paste files.
 
-| Feature | Description |
-|---------|-------------|
-| **Cross-project knowledge** | AI can access context from multiple projects simultaneously |
-| **Agent prompts** | All 6 agents (init, research, plan, execute, docs, sync) exposed as MCP prompts |
-| **Search across projects** | Search knowledge bases across all exposed projects |
-| **Selective exposure** | Choose which projects to expose via interactive TUI |
+### 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.
 
-### VSCode Copilot Setup
+### Connecting Your IDE
 
-1. Create `.vscode/mcp.json` in your workspace:
+The easiest way to connect is via the TUI (`npx rrce-workflow mcp` -> **Install** tab), but you can also configure it manually.
 
+#### VSCode (with MCP Extension)
+Add to `.vscode/mcp.json`:
 ```json
 {
   "servers": {
@@ -204,13 +78,8 @@ npx rrce-workflow mcp start
 }
 ```
 
-2. In Copilot Chat, switch to **Agent** mode
-3. Click the 🔧 tools icon to see RRCE resources, tools, and prompts
-
-### Claude Desktop Setup
-
+#### Claude Desktop
 Add to `~/.config/claude/claude_desktop_config.json`:
-
 ```json
 {
   "mcpServers": {
@@ -222,133 +91,64 @@ Add to `~/.config/claude/claude_desktop_config.json`:
 }
 ```
 
-### MCP Resources & Tools
-
-**Resources:**
-- `rrce://projects` — List all exposed projects
-- `rrce://projects/{name}/context` — Get project context
-- `rrce://projects/{name}/tasks` — Get task list
-
-**Tools:**
-- `search_knowledge` — Search across all project knowledge bases
-- `list_projects` — List exposed projects
-- `get_project_context` — Get specific project context
-
-**Prompts:**
-- `init`, `research`, `plan`, `execute`, `docs`, `sync` — Full RRCE pipeline
-
-### Using Agent Prompts via MCP
-
-Once the MCP server is connected, you can invoke RRCE agent prompts directly:
-
-#### In VSCode Copilot (Agent Mode)
-
-```
-# Initialize project context
-@rrce Use the init prompt to analyze this codebase
-
-# Start a new task
-@rrce Use the research prompt with REQUEST="add user authentication" and TASK_SLUG="auth-feature"
-
-# Create execution plan
-@rrce Use the plan prompt for TASK_SLUG="auth-feature"
-
-# Execute the plan
-@rrce Use the execute prompt for TASK_SLUG="auth-feature"
-```
-
-#### In Claude Desktop
-
-```
-Use the RRCE init prompt to analyze the current project
-
-Search my RRCE projects for "authentication"
-
-Use the research prompt with these arguments:
-- REQUEST: "Add OAuth2 login"
-- TASK_SLUG: "oauth-login"
-```
-
-#### In Other MCP-Compatible Tools (Cursor, etc.)
-
-Most MCP clients follow similar patterns:
-1. Connect to the RRCE MCP server via stdio
-2. Use `list_prompts` to see available prompts
-3. Call prompts with required arguments
-
-**Example prompt arguments:**
+---
 
-| Prompt | Required Args | Optional Args |
-|--------|---------------|---------------|
-| `init` | — | `PROJECT_NAME` |
-| `research` | `REQUEST`, `TASK_SLUG` | `TITLE` |
-| `plan` | `TASK_SLUG` | — |
-| `execute` | `TASK_SLUG` | `BRANCH` |
-| `docs` | `DOC_TYPE` | `TASK_SLUG` |
-| `sync` | — | `SCOPE` |
+## 📂 Storage Modes
 
-### MCP Configuration
+RRCE-Workflow supports two ways to store your agent workflow data (`knowledge/`, `tasks/`, `refs/`).
 
-Configure which projects to expose:
+### 1. Global Mode (Default & Recommended)
+Stores configuration and knowledge outside your project directory in `~/.rrce-workflow/workspaces/<project-name>`.
 
-```bash
-npx rrce-workflow mcp           # Interactive TUI Dashboard
-npx rrce-workflow mcp status    # View current status
-```
+*   **✅ Pros**: Keeps your repo clean, easy cross-project linking, no `.gitignore` pollution.
+*   **❌ Cons**: Knowledge isn't checked into your project's git repo (unless you manually sync/backup).
 
-**Interactive Dashboard Controls:**
-- `p`: Open **Project Configuration** modal (Toggle exposed projects)
-- `i`: Open **IDE Installation** modal (Auto-configure VSCode/Claude)
-- `r`: Reload configuration
-- `c`: Clear logs
-- `?`: Toggle Help & Shortcuts
+### 2. Workspace Mode (Alternative)
+Stores everything in a `.rrce-workflow` folder inside your project root.
 
-**Unified Context:**
-Projects linked via the main wizard (`Link other project knowledge`) are automatically detected and exposed by the MCP server alongside globally configured projects.
+*   **✅ Pros**: Knowledge travels with the repo (great for teams sharing context).
+*   **❌ Cons**: Adds files to your project tree; requires `.gitignore` management.
 
-Config stored at `~/.rrce-workflow/mcp.yaml`
+**To use Workspace Mode**: Select "Custom Setup" -> "Workspace" when running `npx rrce-workflow`.
 
 ---
 
-## Requirements
-
-- **Node.js 18+**
-- **Git** (for user detection)
-
----
+## 🤖 The Agent Pipeline
 
-## Troubleshooting
+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.
 
-### "Permission denied" when setting up
+| 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. |
 
-If you can't write to `~/.rrce-workflow`, the wizard will prompt you to choose a custom path. You can also set it manually:
+### 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.
 
-```bash
-export RRCE_HOME=/path/to/writable/location
-npx rrce-workflow
-```
+---
 
-### Agents can't find data files
+## 🔍 Semantic Search (RAG)
 
-Make sure the agent reads `.rrce-workflow/config.yaml` first. All prompts include a mandatory first step to resolve paths from the config.
+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.
 
-### Updating prompts after package update
+RAG is enabled by default in Express Setup. You can toggle it per-project in the MCP Dashboard.
 
-```bash
-npx rrce-workflow
-# Select "Update from package"
-```
-
-### MCP server not connecting
-
-Ensure the server starts successfully:
-```bash
-npx rrce-workflow mcp start
-```
+---
 
-Check that your IDE is configured to use stdio transport.
+## requirements
 
----
+-   **Node.js 18+**
+-   **Git**
 
 ## License
 

package/dist/index.js

@@ -209,15 +209,20 @@ function scanGlobalStorage(excludeWorkspace) {
       const knowledgePath = path2.join(projectDataPath, "knowledge");
       const refsPath = path2.join(projectDataPath, "refs");
       const tasksPath = path2.join(projectDataPath, "tasks");
+      const configPath = path2.join(projectDataPath, "config.yaml");
+      const config = parseWorkspaceConfig(configPath);
       projects.push({
-        name: entry.name,
+        name: config?.name || entry.name,
         path: projectDataPath,
-        // For global projects, path is the data path
+        // Still use dataPath as defaults, BUT...
+        sourcePath: config?.sourcePath,
+        // ...expose sourcePath if available
         dataPath: projectDataPath,
         source: "global",
         knowledgePath: fs2.existsSync(knowledgePath) ? knowledgePath : void 0,
         refsPath: fs2.existsSync(refsPath) ? refsPath : void 0,
-        tasksPath: fs2.existsSync(tasksPath) ? tasksPath : void 0
+        tasksPath: fs2.existsSync(tasksPath) ? tasksPath : void 0,
+        semanticSearchEnabled: config?.semanticSearchEnabled
       });
     }
   } catch {
@@ -254,7 +259,8 @@ function scanHomeDirectory(excludePath) {
               storageMode: config?.storageMode,
               knowledgePath: fs2.existsSync(knowledgePath) ? knowledgePath : void 0,
               refsPath: fs2.existsSync(refsPath) ? refsPath : void 0,
-              tasksPath: fs2.existsSync(tasksPath) ? tasksPath : void 0
+              tasksPath: fs2.existsSync(tasksPath) ? tasksPath : void 0,
+              semanticSearchEnabled: config?.semanticSearchEnabled
             });
           }
           continue;
@@ -273,6 +279,7 @@ function parseWorkspaceConfig(configPath) {
   try {
     const content = fs2.readFileSync(configPath, "utf-8");
     const nameMatch = content.match(/name:\s*["']?([^"'\n]+)["']?/);
+    const sourcePathMatch = content.match(/sourcePath:\s*["']?([^"'\n]+)["']?/);
     const modeMatch = content.match(/mode:\s*(global|workspace)/);
     const linkedProjects = [];
     const linkedMatch = content.match(/linked_projects:\s*\n((?:\s+-\s+[^\n]+\n?)+)/);
@@ -285,10 +292,14 @@ function parseWorkspaceConfig(configPath) {
         }
       }
     }
+    const semanticSearchMatch = content.match(/semantic_search:\s*\n\s*enabled:\s*(true|false)/);
+    const semanticSearchEnabled = semanticSearchMatch ? semanticSearchMatch[1] === "true" : false;
     return {
       name: nameMatch?.[1]?.trim() || path2.basename(path2.dirname(path2.dirname(configPath))),
+      sourcePath: sourcePathMatch?.[1]?.trim(),
       storageMode: modeMatch?.[1] || "global",
-      linkedProjects: linkedProjects.length > 0 ? linkedProjects : void 0
+      linkedProjects: linkedProjects.length > 0 ? linkedProjects : void 0,
+      semanticSearchEnabled
     };
   } catch {
     return null;
@@ -1210,6 +1221,7 @@ storage:
 
 project:
   name: "${workspaceName}"
+  sourcePath: "${workspacePath}"
 
 tools:
   copilot: ${config.storageMode === "workspace" && config.tools.includes("copilot")}
@@ -1827,11 +1839,12 @@ async function indexKnowledge(projectName, force = false) {
   }
   const projConfig = config.projects.find(
     (p) => p.path && p.path === project.dataPath || !p.path && p.name === project.name
-  );
-  if (!projConfig?.semanticSearch?.enabled) {
+  ) || (project.source === "global" ? { semanticSearch: { enabled: true, model: "Xenova/all-MiniLM-L6-v2" } } : void 0);
+  const isEnabled = projConfig?.semanticSearch?.enabled || project.semanticSearchEnabled;
+  if (!isEnabled) {
     return { success: false, message: "Semantic Search is not enabled for this project", filesIndexed: 0, filesSkipped: 0 };
   }
-  const scanRoot = project.path || project.dataPath;
+  const scanRoot = project.sourcePath || project.path || project.dataPath;
   if (!fs13.existsSync(scanRoot)) {
     return { success: false, message: "Project root not found", filesIndexed: 0, filesSkipped: 0 };
   }
@@ -1876,7 +1889,8 @@ async function indexKnowledge(projectName, force = false) {
   const SKIP_DIRS = ["node_modules", ".git", "dist", "build", ".next", "__pycache__", "venv", ".venv", "target", "vendor"];
   try {
     const indexPath = path14.join(project.knowledgePath || path14.join(scanRoot, ".rrce-workflow", "knowledge"), "embeddings.json");
-    const rag = new RAGService(indexPath, projConfig.semanticSearch.model);
+    const model = projConfig?.semanticSearch?.model || "Xenova/all-MiniLM-L6-v2";
+    const rag = new RAGService(indexPath, model);
     let indexed = 0;
     let skipped = 0;
     const scanDir = async (dir) => {
@@ -3194,7 +3208,7 @@ var init_IndexingStatus = __esm({
             if (!projConfig && project.source === "global") {
               projConfig = config.projects.find((p) => p.name === project.name);
             }
-            const enabled = projConfig?.semanticSearch?.enabled ?? false;
+            const enabled = projConfig?.semanticSearch?.enabled || project.semanticSearchEnabled || false;
             if (!enabled) {
               newStats.push({
                 projectName: project.name,
@@ -3362,7 +3376,7 @@ var init_App = __esm({
       const isRAGEnabled = useMemo2(() => {
         return exposedProjects.some((p) => {
           const cfg = findProjectConfig(config, { name: p.name, path: p.path });
-          return cfg?.semanticSearch?.enabled;
+          return cfg?.semanticSearch?.enabled || p.semanticSearchEnabled;
         });
       }, [exposedProjects, config]);
       const tabs = useMemo2(() => {

package/package.json

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