rrce-workflow 0.2.95 → 0.2.97

package/README.md

@@ -18,65 +18,67 @@ RRCE-Workflow transforms your AI coding assistant (GitHub Copilot, OpenCode, Cla
 
 ## 🚀 Quick Start
 
-### 1. The MCP Dashboard (TUI)
+### 1. Run the Wizard (Project Setup)
 
-The central command center for RRCE-Workflow is the **MCP Dashboard**. It lets you manage your projects, server status, and IDE integrations.
+From the project you want to work on:
 
 ```bash
-npx rrce-workflow mcp
+cd your-project
+npx rrce-workflow
 ```
 
-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**, **Claude Desktop**, **Antigravity IDE**, or **OpenCode** to use the RRCE MCP server.
--   **View Logs**: Debug agent interactions in real-time.
+This launches the setup wizard and can:
+- Create the `.rrce-workflow/` structure (workspace mode) or initialize global storage (global mode)
+- Install IDE integrations (VSCode / Claude Desktop / OpenCode / Antigravity)
+- Optionally expose the project to MCP and enable semantic search indexing
 
-### 2. Setting Up a Project
+### 2. Launch the MCP Dashboard (TUI)
 
-To enable agent workflows for your current project, run the setup wizard:
+The **MCP Dashboard** lets you manage exposed projects, indexing jobs, IDE integrations, and view logs.
 
 ```bash
-cd your-project
-npx rrce-workflow
+npx rrce-workflow mcp
 ```
 
-You can choose between:
+### 3. Run the MCP Server (for IDE integrations)
+
+When an IDE connects via MCP, it launches the server in non-interactive mode:
+
+```bash
+npx rrce-workflow mcp start
+```
 
-*   **⚡ 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.
+Note: `mcp start` is intended for stdio-based MCP clients (it only auto-starts when `stdout` is not a TTY).
 
 ---
 
 ## 🧠 Model Context Protocol (MCP)
 
-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.
+RRCE-Workflow uses the [Model Context Protocol](https://modelcontextprotocol.io/) to bridge your codebase with AI models. This allows your AI assistant to access project context and knowledge without copy/paste.
 
 ### 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).
-*   **12 MCP Tools**: Including `search_knowledge`, `get_project_context`, `resolve_path`, task CRUD operations, and more.
+*   **MCP Tools**: Includes `search_knowledge`, `search_code`, `find_related_files`, `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 |
+| `resolve_path` | Resolve configuration paths (`RRCE_DATA`, `WORKSPACE_ROOT`, etc.) for a project |
+| `list_projects` | List projects exposed via MCP |
+| `get_project_context` | Get the project context/architecture for a specific project |
+| `search_knowledge` | Semantic search across project knowledge bases |
+| `search_code` | Semantic search across code files (snippets + line numbers + context) |
+| `find_related_files` | Find imports/imported-by relationships for a file |
+| `index_knowledge` | Start (or query) the semantic indexing job 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 |
+| `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 |
+| `get_task` | Get details of a task |
+| `create_task` | Create a task |
+| `update_task` | Update a task (`meta.json`) |
+| `delete_task` | Delete a task |
 
 ### Connecting Your IDE
 

package/dist/index.js

@@ -1718,6 +1718,14 @@ var init_rag = __esm({
           this.maybeSaveIndex(true);
         }
       }
+      /**
+       * Get current indexed file paths
+       */
+      getIndexedFiles() {
+        this.loadIndex();
+        if (!this.index || !this.index.fileMetadata) return [];
+        return Object.keys(this.index.fileMetadata);
+      }
       /**
        * Get index statistics
        */
@@ -2354,6 +2362,7 @@ import * as fs15 from "fs";
 import * as path17 from "path";
 import * as os2 from "os";
 import * as crypto from "crypto";
+import ignore from "ignore";
 function resolveProjectPaths(project, pathInput) {
   const config = loadMCPConfig();
   let workspaceRoot = pathInput;
@@ -2737,6 +2746,33 @@ async function indexKnowledge(projectName, force = false) {
     ".sql"
   ];
   const SKIP_DIRS = ["node_modules", ".git", "dist", "build", ".next", "__pycache__", "venv", ".venv", "target", "vendor"];
+  const gitignorePath = path17.join(scanRoot, ".gitignore");
+  const ig = fs15.existsSync(gitignorePath) ? ignore().add(fs15.readFileSync(gitignorePath, "utf-8")) : null;
+  const toPosixRelativePath = (absolutePath) => {
+    const rel = path17.relative(scanRoot, absolutePath);
+    return rel.split(path17.sep).join("/");
+  };
+  const isUnderGitDir = (absolutePath) => {
+    const rel = toPosixRelativePath(absolutePath);
+    return rel === ".git" || rel.startsWith(".git/");
+  };
+  const isIgnoredByGitignore = (absolutePath, isDir) => {
+    if (!ig) return false;
+    const rel = toPosixRelativePath(absolutePath);
+    return ig.ignores(isDir ? `${rel}/` : rel);
+  };
+  const shouldSkipEntryDir = (absolutePath) => {
+    const dirName = path17.basename(absolutePath);
+    if (dirName === ".git") return true;
+    if (SKIP_DIRS.includes(dirName)) return true;
+    if (isIgnoredByGitignore(absolutePath, true)) return true;
+    return false;
+  };
+  const shouldSkipEntryFile = (absolutePath) => {
+    if (isUnderGitDir(absolutePath)) return true;
+    if (isIgnoredByGitignore(absolutePath, false)) return true;
+    return false;
+  };
   const runIndexing = async () => {
     const indexPath = path17.join(project.knowledgePath || path17.join(scanRoot, ".rrce-workflow", "knowledge"), "embeddings.json");
     const codeIndexPath = path17.join(project.knowledgePath || path17.join(scanRoot, ".rrce-workflow", "knowledge"), "code-embeddings.json");
@@ -2748,29 +2784,45 @@ async function indexKnowledge(projectName, force = false) {
     let skipped = 0;
     let itemsTotal = 0;
     let itemsDone = 0;
-    const shouldSkipDir = (dirName) => SKIP_DIRS.includes(dirName) || dirName.startsWith(".");
     const preCount = (dir) => {
       const entries = fs15.readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
         const fullPath = path17.join(dir, entry.name);
         if (entry.isDirectory()) {
-          if (shouldSkipDir(entry.name)) continue;
+          if (shouldSkipEntryDir(fullPath)) continue;
           preCount(fullPath);
         } else if (entry.isFile()) {
           const ext = path17.extname(entry.name).toLowerCase();
           if (!INDEXABLE_EXTENSIONS.includes(ext)) continue;
+          if (shouldSkipEntryFile(fullPath)) continue;
           itemsTotal++;
         }
       }
     };
     preCount(scanRoot);
     indexingJobs.update(project.name, { itemsTotal });
+    const cleanupIgnoredFiles = async () => {
+      const indexedFiles = [...rag.getIndexedFiles(), ...codeRag.getIndexedFiles()];
+      const unique = Array.from(new Set(indexedFiles));
+      for (const filePath of unique) {
+        if (!path17.isAbsolute(filePath)) continue;
+        const relFilePath = filePath.split(path17.sep).join("/");
+        const relScanRoot = scanRoot.split(path17.sep).join("/");
+        const isInScanRoot = relFilePath === relScanRoot || relFilePath.startsWith(`${relScanRoot}/`);
+        if (!isInScanRoot) continue;
+        if (shouldSkipEntryFile(filePath)) {
+          await rag.removeFile(filePath);
+          await codeRag.removeFile(filePath);
+        }
+      }
+    };
+    await cleanupIgnoredFiles();
     const scanDir = async (dir) => {
       const entries = fs15.readdirSync(dir, { withFileTypes: true });
       for (const entry of entries) {
         const fullPath = path17.join(dir, entry.name);
         if (entry.isDirectory()) {
-          if (shouldSkipDir(entry.name)) {
+          if (shouldSkipEntryDir(fullPath)) {
             continue;
           }
           await scanDir(fullPath);
@@ -2779,6 +2831,9 @@ async function indexKnowledge(projectName, force = false) {
           if (!INDEXABLE_EXTENSIONS.includes(ext)) {
             continue;
           }
+          if (shouldSkipEntryFile(fullPath)) {
+            continue;
+          }
           try {
             indexingJobs.update(project.name, { currentItem: fullPath, itemsDone });
             const stat = fs15.statSync(fullPath);
@@ -5271,9 +5326,10 @@ function convertToOpenCodeAgent(prompt, useFileReference = false, promptFilePath
     }
   }
   tools["webfetch"] = true;
+  const invocationHint = " (Invoke via @rrce_*)";
   return {
-    description: frontmatter.description,
-    mode: "primary",
+    description: `${frontmatter.description}${invocationHint}`,
+    mode: "subagent",
     prompt: useFileReference && promptFilePath ? `{file:${promptFilePath}}` : content,
     tools
   };
@@ -5428,11 +5484,12 @@ async function installAgentPrompts(config, workspacePath, dataPaths) {
             if (!opencodeConfig.agent) opencodeConfig.agent = {};
             for (const prompt of prompts) {
               const baseName = path12.basename(prompt.filePath, ".md");
+              const agentId = `rrce_${baseName}`;
               const promptFileName = `rrce-${baseName}.md`;
               const promptFilePath = path12.join(promptsDir, promptFileName);
               fs10.writeFileSync(promptFilePath, prompt.content);
               const agentConfig = convertToOpenCodeAgent(prompt, true, `./prompts/${promptFileName}`);
-              opencodeConfig.agent[baseName] = agentConfig;
+              opencodeConfig.agent[agentId] = agentConfig;
             }
             fs10.writeFileSync(OPENCODE_CONFIG, JSON.stringify(opencodeConfig, null, 2) + "\n");
           } catch (e) {
@@ -5443,6 +5500,7 @@ async function installAgentPrompts(config, workspacePath, dataPaths) {
           ensureDir(opencodeBaseDir);
           for (const prompt of prompts) {
             const baseName = path12.basename(prompt.filePath, ".md");
+            const agentId = `rrce_${baseName}`;
             const agentConfig = convertToOpenCodeAgent(prompt);
             const content = `---
 ${stringify2({
@@ -5451,7 +5509,7 @@ ${stringify2({
               tools: agentConfig.tools
             })}---
 ${agentConfig.prompt}`;
-            fs10.writeFileSync(path12.join(opencodeBaseDir, `${baseName}.md`), content);
+            fs10.writeFileSync(path12.join(opencodeBaseDir, `${agentId}.md`), content);
           }
         }
       }
@@ -6048,15 +6106,17 @@ function updateOpenCodeAgents(prompts, mode, primaryDataPath) {
         opencodeConfig = JSON.parse(fs21.readFileSync(OPENCODE_CONFIG, "utf-8"));
       }
       if (!opencodeConfig.agent) opencodeConfig.agent = {};
-      const currentAgentNames = prompts.map((p) => path21.basename(p.filePath, ".md"));
+      const currentAgentBaseNames = prompts.map((p) => path21.basename(p.filePath, ".md"));
+      const currentAgentIds = new Set(currentAgentBaseNames.map((base) => `rrce_${base}`));
       const existingAgentNames = Object.keys(opencodeConfig.agent);
-      const rrceAgentPrefixes = ["init", "research", "planning", "executor", "doctor", "documentation", "sync"];
       for (const existingName of existingAgentNames) {
-        const isRrceAgent = rrceAgentPrefixes.some((prefix) => existingName.startsWith(prefix));
-        const stillExists = currentAgentNames.includes(existingName);
-        if (isRrceAgent && !stillExists) {
+        const isLegacyBaseName = currentAgentBaseNames.includes(existingName);
+        const isRrcePrefixed = existingName.startsWith("rrce_");
+        const isStaleRrcePrefixed = isRrcePrefixed && !currentAgentIds.has(existingName);
+        if (isLegacyBaseName || isStaleRrcePrefixed) {
           delete opencodeConfig.agent[existingName];
-          const oldPromptFile = path21.join(promptsDir, `rrce-${existingName}.md`);
+          const legacyBaseName = isLegacyBaseName ? existingName : existingName.replace(/^rrce_/, "");
+          const oldPromptFile = path21.join(promptsDir, `rrce-${legacyBaseName}.md`);
           if (fs21.existsSync(oldPromptFile)) {
             fs21.unlinkSync(oldPromptFile);
           }
@@ -6064,11 +6124,12 @@ function updateOpenCodeAgents(prompts, mode, primaryDataPath) {
       }
       for (const prompt of prompts) {
         const baseName = path21.basename(prompt.filePath, ".md");
+        const agentId = `rrce_${baseName}`;
         const promptFileName = `rrce-${baseName}.md`;
         const promptFilePath = path21.join(promptsDir, promptFileName);
         fs21.writeFileSync(promptFilePath, prompt.content);
         const agentConfig = convertToOpenCodeAgent(prompt, true, `./prompts/${promptFileName}`);
-        opencodeConfig.agent[baseName] = agentConfig;
+        opencodeConfig.agent[agentId] = agentConfig;
       }
       fs21.writeFileSync(OPENCODE_CONFIG, JSON.stringify(opencodeConfig, null, 2) + "\n");
     } catch (e) {
@@ -6080,6 +6141,7 @@ function updateOpenCodeAgents(prompts, mode, primaryDataPath) {
     clearDirectory(opencodeBaseDir);
     for (const prompt of prompts) {
       const baseName = path21.basename(prompt.filePath, ".md");
+      const agentId = `rrce_${baseName}`;
       const agentConfig = convertToOpenCodeAgent(prompt);
       const content = `---
 ${stringify3({
@@ -6088,7 +6150,7 @@ ${stringify3({
         tools: agentConfig.tools
       })}---
 ${agentConfig.prompt}`;
-      fs21.writeFileSync(path21.join(opencodeBaseDir, `${baseName}.md`), content);
+      fs21.writeFileSync(path21.join(opencodeBaseDir, `${agentId}.md`), content);
     }
   }
 }

package/docs/architecture.md

@@ -2,18 +2,18 @@
 
 > RR Context Engineering Workflow - A selection-agnostic agentic workflow system
 > 
-> **Version**: 0.2.91 | **Last Updated**: 2025-12-31
+> **Version**: 0.2.96 | **Last Updated**: 2026-01-02
 
 ## Overview
 
 RRCE-Workflow is a TUI-based agentic code workflow generator designed to work seamlessly across:
-- **OpenCode** (Native agentic TUI environment with custom Primary Agents)
+- **OpenCode** (Native agentic TUI environment; RRCE installs subagents invoked via `@rrce_<agent>`)
 - **GitHub Copilot** (VSCode with MCP extension)
 - **Antigravity IDE** (Google's agentic coding environment)
 - **Claude Desktop** (MCP Server integration)
 - **Any MCP-compatible client**
 
-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.
+The system provides a structured multi-agent pipeline (7 agents) for software development tasks, with persistent knowledge caching, semantic search (RAG) across knowledge and code, and workspace-aware context management.
 
 ## Core Principles
 
@@ -355,7 +355,7 @@ RRCE-Workflow prompts are designed to work across multiple AI coding tools via M
 
 | Tool | MCP Config Location | Agent Location | Notes |
 |------|---------------------|----------------|-------|
-| **OpenCode** | `~/.config/opencode/opencode.json` | `.opencode/agent/rrce-*.md` | Custom Primary Agents (Tab to switch) |
+| **OpenCode** | `~/.config/opencode/opencode.json` | `.opencode/agent/rrce_*.md` | Custom subagents (invoke via `@rrce_*`) |
 | **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 |
@@ -363,25 +363,26 @@ RRCE-Workflow prompts are designed to work across multiple AI coding tools via M
 ### OpenCode Agent Transformation
 
 When generating agents for OpenCode (`src/commands/wizard/utils.ts`):
-- **Mode**: Set to `primary` (enables Tab cycling in TUI)
-- **Tools**: 
+- **Mode**: Set to `subagent` (not tab-switchable; invoke via mention)
+- **Invoke**: Use `@rrce_<agent>` (e.g., `@rrce_init`)
+- **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
+- **Naming**: Agent IDs are prefixed with `rrce_` (underscore) to avoid collisions
 
 ### Generated Files
 
 **For OpenCode:**
 ```
 .opencode/agent/
-├── rrce-init.md
-├── rrce-research.md
-├── rrce-planning.md
-├── rrce-executor.md
-├── rrce-documentation.md
-├── rrce-sync.md
-└── rrce-doctor.md
+├── rrce_init.md
+├── rrce_research.md
+├── rrce_planning.md
+├── rrce_executor.md
+├── rrce_documentation.md
+├── rrce_sync.md
+└── rrce_doctor.md
 ```
 
 **For Antigravity IDE:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rrce-workflow",
-  "version": "0.2.95",
+  "version": "0.2.97",
   "description": "RRCE-Workflow TUI - Agentic code workflow generator for AI-assisted development",
   "author": "RRCE Team",
   "license": "MIT",
@@ -53,6 +53,7 @@
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@xenova/transformers": "^2.17.2",
     "gray-matter": "^4.0.3",
+    "ignore": "^5.3.2",
     "ink": "^6.6.0",
     "ink-link": "^5.0.0",
     "ink-spinner": "^5.0.0",