rrce-workflow 0.2.8 → 0.2.10

package/README.md

@@ -5,89 +5,198 @@
 [![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 TUI that helps you set up and manage AI agent workflows for your codebase. It works with GitHub Copilot, Antigravity IDE, and other AI coding tools.
+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.
 
 ## Installation
 
 ```bash
-# Using npm
+# Quick start (no install needed)
 npx rrce-workflow
 
-# Using bun (recommended)
-bunx rrce-workflow
-
-# Global install
+# Or install globally
 npm install -g rrce-workflow
 ```
 
-## Quick Start
+---
+
+## How to Use
+
+### 1. Initial Setup
+
+Run the wizard in your project directory:
 
 ```bash
-# Run setup wizard
-rrce-workflow wizard
+cd your-project
+npx rrce-workflow
+```
+
+The wizard will:
+1. Ask where to store workflow data (global, workspace, or both)
+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
 
-# Or just run to see available agents
-rrce-workflow
+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)
 ```
 
-## Features
+#### Pipeline Stages Explained
 
-- **Setup Wizard** - Interactive configuration for storage mode and AI tools
-- **Agent Prompts** - Pre-built prompts for init, research, planning, execution, documentation, and sync
-- **Multi-Tool Support** - Works with GitHub Copilot (`.agent.md`) and Antigravity IDE
-- **Cross-Project References** - Reference context from related projects
+**🔍 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.
 
-## Agents
+**💬 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.
 
-| Agent | Command | Description |
-|-------|---------|-------------|
-| **Init** | `/init` | Initialize or update project context |
-| **Research** | `/research` | Clarify requirements and create research brief |
-| **Planning** | `/plan` | Transform requirements into execution plan |
-| **Executor** | `/execute` | Implement the planned tasks |
-| **Documentation** | `/docs` | Generate project documentation |
-| **Sync** | `/sync` | Reconcile codebase with knowledge base |
+**📋 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.
 
-## Configuration
+**⚡ Execute** — Implements the planned work. Writes code, adds tests, runs verifications. Updates task metadata and logs execution notes for auditability.
 
-After running the wizard, a `.rrce-workflow.yaml` is created in your project:
+**📄 Docs** — Synthesizes the completed work into documentation. Can generate API docs, architecture overviews, runbooks, or changelogs based on `DOC_TYPE`.
 
-```yaml
-version: 1
+**🔄 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: global  # or: workspace, both
+  mode: workspace        # or: global, both
+  globalPath: "~/.rrce-workflow"  # optional custom path
 
 project:
   name: "my-project"
 ```
 
-### Storage Modes
+Agents resolve `{{RRCE_DATA}}` based on storage mode:
+- `workspace` → `.rrce-workflow/`
+- `global` → `~/.rrce-workflow/workspaces/my-project/`
+- `both` → `.rrce-workflow/` (primary, synced to global)
 
-| Mode | Location | Use Case |
-|------|----------|----------|
-| `global` | `~/.rrce-workflow/workspaces/<name>/` | Non-intrusive, cross-project access |
-| `workspace` | `.rrce-workflow/` | Portable with repo, team sharing |
-| `both` | Both locations (synced) | Redundancy + cross-project access |
+### Cross-Project References
 
-When `both` is selected, data is stored in **both** locations simultaneously:
-- Primary (for reads): `<workspace>/.rrce-workflow/`
-- Secondary (auto-synced): `~/.rrce-workflow/workspaces/<name>/`
+When using `global` or `both` mode, you can reference other projects:
 
-Each storage location contains:
 ```
-<storage-path>/
-├── knowledge/      # Project context and domain knowledge
-├── prompts/        # Agent prompt files
-├── refs/           # External references
-├── tasks/          # Task artifacts and metadata
-└── templates/      # Output templates
+~/.rrce-workflow/workspaces/other-project/knowledge/project-context.md
+```
+
+This enables a frontend app to reference its backend API's knowledge!
+
+---
+
+## Folder Structure
+
+After setup, your project will have:
+
+```
+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 |
+
+---
+
+## 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 |
+| `both` | Both locations (synced) | Full redundancy + cross-project access |
+
+---
+
+## Custom Global Path
+
+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"
 ```
 
+---
+
 ## Requirements
 
-- Node.js 18+ or Bun 1.0+
-- Git (for user detection)
+- **Node.js 18+**
+- **Git** (for user detection)
+
+---
+
+## Troubleshooting
+
+### "Permission denied" when setting up
+
+If you can't write to `~/.rrce-workflow`, the wizard will prompt you to choose a custom path. You can also set it manually:
+
+```bash
+export RRCE_HOME=/path/to/writable/location
+npx rrce-workflow
+```
+
+### Agents can't find data files
+
+Make sure the agent reads `.rrce-workflow/config.yaml` first. All prompts include a mandatory first step to resolve paths from the config.
+
+### Updating prompts after package update
+
+```bash
+npx rrce-workflow
+# Select "Update from package"
+```
+
+---
 
 ## License
 

package/agent-core/prompts/documentation.md

@@ -20,6 +20,14 @@ auto-identity:
 
 You are the Documentation Lead for the project. Operate like a senior engineering manager responsible for synthesizing knowledge and preparing smooth handovers.
 
+**⚠️ FIRST STEP (MANDATORY)**
+Before doing ANY work, read `.rrce-workflow/config.yaml` and resolve these variables:
+```
+RRCE_HOME = config.storage.globalPath OR "~/.rrce-workflow"
+RRCE_DATA = (config.storage.mode == "workspace" or "both") ? ".rrce-workflow/" : "${RRCE_HOME}/workspaces/${config.project.name}/"
+```
+Use these resolved paths for ALL subsequent file operations.
+
 Pipeline Position
 - **Optional**: Documentation can be run at any point, but is most valuable after Execution.
 - **Best After**: Executor phase complete (if documenting a specific task).

package/agent-core/prompts/executor.md

@@ -16,6 +16,14 @@ auto-identity:
 
 You are the Executor for the project. Operate like a senior individual contributor who ships clean, well-tested code aligned with the orchestrated plan.
 
+**⚠️ FIRST STEP (MANDATORY)**
+Before doing ANY work, read `.rrce-workflow/config.yaml` and resolve these variables:
+```
+RRCE_HOME = config.storage.globalPath OR "~/.rrce-workflow"
+RRCE_DATA = (config.storage.mode == "workspace" or "both") ? ".rrce-workflow/" : "${RRCE_HOME}/workspaces/${config.project.name}/"
+```
+Use these resolved paths for ALL subsequent file operations.
+
 Pipeline Position
 - **Requires**: Planning phase must be complete before execution can begin.
 - **Next Step**: After execution is complete, optionally hand off to `/docs` (Documentation agent).

package/agent-core/prompts/init.md

@@ -15,6 +15,14 @@ auto-identity:
 
 You are the Project Initializer for RRCE-Workflow. Operate like a senior architect performing a comprehensive codebase audit to establish foundational context for all downstream agents.
 
+**⚠️ FIRST STEP (MANDATORY)**
+Before doing ANY work, read `.rrce-workflow/config.yaml` (if it exists) and resolve these variables:
+```
+RRCE_HOME = config.storage.globalPath OR "~/.rrce-workflow"
+RRCE_DATA = (config.storage.mode == "workspace" or "both") ? ".rrce-workflow/" : "${RRCE_HOME}/workspaces/${config.project.name}/"
+```
+If config doesn't exist yet (new project), use defaults: `RRCE_HOME=~/.rrce-workflow`, `RRCE_DATA=.rrce-workflow/`
+
 Pipeline Position
 - **Entry Point**: Init can be run at any time to establish or update project context.
 - **Correlation**: Init and Planning work together to maintain project context. Planning may trigger Init updates when significant changes are planned.

package/agent-core/prompts/planning_orchestrator.md

@@ -13,6 +13,14 @@ auto-identity:
 
 You are the Planning & Task Orchestrator for the project. Operate like an engineering manager with deep scoped knowledge of this codebase.
 
+**⚠️ FIRST STEP (MANDATORY)**
+Before doing ANY work, read `.rrce-workflow/config.yaml` and resolve these variables:
+```
+RRCE_HOME = config.storage.globalPath OR "~/.rrce-workflow"
+RRCE_DATA = (config.storage.mode == "workspace" or "both") ? ".rrce-workflow/" : "${RRCE_HOME}/workspaces/${config.project.name}/"
+```
+Use these resolved paths for ALL subsequent file operations.
+
 Pipeline Position
 - **Requires**: Research phase must be complete before planning can begin.
 - **Correlation**: Planning works with Init to maintain project context. If planning reveals significant architectural changes, recommend running `/init` to update project context.

package/agent-core/prompts/research_discussion.md

@@ -20,6 +20,14 @@ auto-identity:
 
 You are the Research & Discussion Lead for the project. Operate like a staff-level tech lead who owns broad project awareness.
 
+**⚠️ FIRST STEP (MANDATORY)**
+Before doing ANY work, read `.rrce-workflow/config.yaml` and resolve these variables:
+```
+RRCE_HOME = config.storage.globalPath OR "~/.rrce-workflow"
+RRCE_DATA = (config.storage.mode == "workspace" or "both") ? ".rrce-workflow/" : "${RRCE_HOME}/workspaces/${config.project.name}/"
+```
+Use these resolved paths for ALL subsequent file operations.
+
 Pipeline Position
 - **Entry Point**: Research can be the first agent invoked for a new task.
 - **Recommendation**: If `{{RRCE_DATA}}/knowledge/project-context.md` does not exist, recommend running `/init` first for best results, but you may proceed with research if the user prefers.

package/agent-core/prompts/sync.md

@@ -14,6 +14,14 @@ auto-identity:
 
 You are the Knowledge Sync Lead. Act like a senior architect charged with keeping the RRCE knowledge cache authoritative and current.
 
+**⚠️ FIRST STEP (MANDATORY)**
+Before doing ANY work, read `.rrce-workflow/config.yaml` and resolve these variables:
+```
+RRCE_HOME = config.storage.globalPath OR "~/.rrce-workflow"
+RRCE_DATA = (config.storage.mode == "workspace" or "both") ? ".rrce-workflow/" : "${RRCE_HOME}/workspaces/${config.project.name}/"
+```
+Use these resolved paths for ALL subsequent file operations.
+
 Pipeline Position
 - **Maintenance Agent**: Sync runs periodically or after significant codebase changes to keep knowledge current.
 - **Requires**: Init must have been run at least once (project-context.md must exist).

package/bin/rrce-workflow.js

@@ -1,2 +1,9 @@
-#!/usr/bin/env bun
-import "../src/index.ts";
+#!/usr/bin/env node
+import { register } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+// Register tsx for TypeScript support
+register('tsx/esm', pathToFileURL('./'));
+
+// Import and run the main module
+import('../src/index.ts');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rrce-workflow",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "RRCE-Workflow TUI - Agentic code workflow generator for AI-assisted development",
   "author": "RRCE Team",
   "license": "MIT",
@@ -35,22 +35,24 @@
     "bin"
   ],
   "scripts": {
-    "dev": "bun run src/index.ts",
-    "wizard": "bun run src/index.ts wizard",
-    "select": "bun run src/index.ts select",
-    "start": "bun run src/index.ts"
+    "dev": "npx tsx src/index.ts",
+    "wizard": "npx tsx src/index.ts wizard",
+    "select": "npx tsx src/index.ts select",
+    "start": "npx tsx src/index.ts"
   },
   "engines": {
-    "node": ">=18",
-    "bun": ">=1.0"
+    "node": ">=18"
   },
   "dependencies": {
+    "@clack/core": "^0.5.0",
     "@clack/prompts": "^0.11.0",
     "gray-matter": "^4.0.3",
     "picocolors": "^1.1.1",
+    "tsx": "^4.21.0",
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
   }
 }

package/src/commands/wizard/link-flow.ts

@@ -1,33 +1,45 @@
 import { multiselect, spinner, note, outro, cancel, isCancel } from '@clack/prompts';
 import pc from 'picocolors';
 import * as fs from 'fs';
-import { listGlobalProjects, getEffectiveRRCEHome, getConfigPath } from '../../lib/paths';
+import { getEffectiveRRCEHome, getConfigPath } from '../../lib/paths';
 import { generateVSCodeWorkspace } from './vscode';
+import { scanForProjects, getProjectDisplayLabel, type DetectedProject } from '../../lib/detection';
 
 /**
  * Run the link-only flow for adding other project knowledge to an existing workspace
+ * Now supports detecting workspace-scoped sibling projects, not just global storage
  */
 export async function runLinkProjectsFlow(
   workspacePath: string, 
   workspaceName: string, 
   existingProjects?: string[]
 ) {
-  // Get projects if not provided
-  const projects = existingProjects ?? listGlobalProjects(workspaceName);
+  // Scan for projects using the new detection system
+  const detectedProjects = scanForProjects({
+    excludeWorkspace: workspaceName,
+    workspacePath: workspacePath,
+    scanSiblings: true,
+  });
+  
+  // If legacy string array is passed, use that instead (for backwards compat)
+  const projects = existingProjects 
+    ? existingProjects.map(name => ({ name, source: 'global' as const } as DetectedProject))
+    : detectedProjects;
   
   if (projects.length === 0) {
-    outro(pc.yellow('No other projects found in global storage.'));
+    outro(pc.yellow('No other projects found. Try setting up another project first.'));
     return;
   }
 
   const customGlobalPath = getEffectiveRRCEHome(workspacePath);
   
+  // Build options with source labels
   const linkedProjects = await multiselect({
     message: 'Select projects to link:',
-    options: projects.map(name => ({
-      value: name,
-      label: name,
-      hint: `${customGlobalPath}/workspaces/${name}/knowledge`
+    options: projects.map(project => ({
+      value: project.name,
+      label: project.name,
+      hint: pc.dim(getProjectDisplayLabel(project)),
     })),
     required: true,
   });
@@ -37,13 +49,16 @@ export async function runLinkProjectsFlow(
     process.exit(0);
   }
 
-  const selectedProjects = linkedProjects as string[];
+  const selectedProjectNames = linkedProjects as string[];
 
-  if (selectedProjects.length === 0) {
+  if (selectedProjectNames.length === 0) {
     outro('No projects selected.');
     return;
   }
 
+  // Get the full DetectedProject objects for selected projects
+  const selectedProjects = projects.filter(p => selectedProjectNames.includes(p.name));
+
   const s = spinner();
   s.start('Linking projects');
 
@@ -63,7 +78,7 @@ export async function runLinkProjectsFlow(
         insertIndex++;
       }
       // Add new projects that aren't already there
-      for (const name of selectedProjects) {
+      for (const name of selectedProjectNames) {
         if (!configContent.includes(`  - ${name}`)) {
           lines.splice(insertIndex, 0, `  - ${name}`);
           insertIndex++;
@@ -74,25 +89,27 @@ export async function runLinkProjectsFlow(
   } else {
     // Add new linked_projects section
     configContent += `\nlinked_projects:\n`;
-    selectedProjects.forEach(name => {
+    selectedProjectNames.forEach(name => {
       configContent += `  - ${name}\n`;
     });
   }
 
   fs.writeFileSync(configFilePath, configContent);
 
-  // Update VSCode workspace file
+  // Update VSCode workspace file with full project info (includes refs, tasks)
   generateVSCodeWorkspace(workspacePath, workspaceName, selectedProjects, customGlobalPath);
 
   s.stop('Projects linked');
 
-  // Show summary
+  // Show summary with project sources
   const workspaceFile = `${workspaceName}.code-workspace`;
   const summary = [
     `Linked projects:`,
-    ...selectedProjects.map(p => `  ✓ ${p}`),
+    ...selectedProjects.map(p => `  ✓ ${p.name} ${pc.dim(`(${p.source})`)}`),
     ``,
     `Workspace file: ${pc.cyan(workspaceFile)}`,
+    ``,
+    pc.dim('Includes: knowledge, refs, tasks folders'),
   ];
 
   note(summary.join('\n'), 'Link Summary');

package/src/commands/wizard/setup-flow.ts

@@ -14,6 +14,7 @@ import {
 import { loadPromptsFromDir, getAgentCorePromptsDir, getAgentCoreDir } from '../../lib/prompts';
 import { copyPromptsToDir } from './utils';
 import { generateVSCodeWorkspace } from './vscode';
+import { directoryAutocomplete, isCancel as isAutocompleteCancel } from '../../lib/autocomplete-prompt';
 
 interface SetupConfig {
   storageMode: StorageMode;
@@ -206,10 +207,12 @@ async function resolveGlobalPath(): Promise<string | undefined> {
     return defaultPath;
   }
 
-  // Custom path input
-  const customPath = await text({
+  // Custom path input with Tab autocomplete
+  const suggestedPath = path.join(process.env.HOME || '~', '.local', 'share', 'rrce-workflow');
+  const customPath = await directoryAutocomplete({
     message: 'Enter custom global path:',
-    placeholder: path.join(process.env.HOME || '~', '.local', 'share', 'rrce-workflow'),
+    initialValue: suggestedPath,
+    hint: 'Tab to autocomplete',
     validate: (value) => {
       if (!value.trim()) {
         return 'Path cannot be empty';
@@ -226,16 +229,12 @@ async function resolveGlobalPath(): Promise<string | undefined> {
     },
   });
 
-  if (isCancel(customPath)) {
+  if (isAutocompleteCancel(customPath)) {
     return undefined;
   }
 
-  // Expand ~ if present
-  const expandedPath = (customPath as string).startsWith('~')
-    ? (customPath as string).replace('~', process.env.HOME || '')
-    : customPath as string;
-  
-  return expandedPath;
+  // Path is already expanded by directoryAutocomplete
+  return customPath as string;
 }
 
 /**

package/src/commands/wizard/vscode.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getRRCEHome } from '../../lib/paths';
+import { type DetectedProject, getProjectFolders } from '../../lib/detection';
 
 interface VSCodeWorkspaceFolder {
   path: string;
@@ -12,13 +13,22 @@ interface VSCodeWorkspace {
   settings?: Record<string, unknown>;
 }
 
+// Reference folder group prefix - used to visually group linked folders
+const REFERENCE_GROUP_PREFIX = '📁 References';
+
 /**
- * Generate or update VSCode workspace file with linked project knowledge folders
+ * Generate or update VSCode workspace file with linked project folders
+ * 
+ * Features:
+ * - Main workspace is clearly marked as the primary project
+ * - Linked folders are grouped under a "References" section (via naming)
+ * - Folders are organized by project with icons for type (📚 📎 📋)
+ * - Reference folders are marked as readonly in workspace settings
  */
 export function generateVSCodeWorkspace(
   workspacePath: string, 
   workspaceName: string, 
-  linkedProjects: string[],
+  linkedProjects: string[] | DetectedProject[],
   customGlobalPath?: string
 ) {
   const workspaceFilePath = path.join(workspacePath, `${workspaceName}.code-workspace`);
@@ -32,35 +42,156 @@ export function generateVSCodeWorkspace(
       workspace = JSON.parse(content);
     } catch {
       // If parse fails, create new
-      workspace = { folders: [] };
+      workspace = { folders: [], settings: {} };
     }
   } else {
-    workspace = { folders: [] };
+    workspace = { folders: [], settings: {} };
   }
 
-  // Ensure main workspace folder is first
-  const mainFolder: VSCodeWorkspaceFolder = { path: '.' };
-  const existingMainIndex = workspace.folders.findIndex(f => f.path === '.');
-  if (existingMainIndex === -1) {
-    workspace.folders.unshift(mainFolder);
+  // Initialize settings if not present
+  if (!workspace.settings) {
+    workspace.settings = {};
   }
 
-  // Add linked project knowledge folders
-  const rrceHome = customGlobalPath || getRRCEHome();
-  for (const projectName of linkedProjects) {
-    const knowledgePath = path.join(rrceHome, 'workspaces', projectName, 'knowledge');
-    const folderEntry: VSCodeWorkspaceFolder = {
-      path: knowledgePath,
-      name: `📚 ${projectName} (knowledge)`
-    };
+  // Clear existing folders and rebuild (to ensure proper ordering)
+  const existingNonReferencesFolders = workspace.folders.filter(f => 
+    f.path === '.' || (!f.name?.includes(REFERENCE_GROUP_PREFIX) && !f.name?.startsWith('📚') && !f.name?.startsWith('📎') && !f.name?.startsWith('📋'))
+  );
+  
+  workspace.folders = [];
+
+  // 1. Add main workspace folder first with clear label
+  const mainFolder: VSCodeWorkspaceFolder = { 
+    path: '.', 
+    name: `🏠 ${workspaceName} (workspace)` 
+  };
+  workspace.folders.push(mainFolder);
+
+  // 2. Add any other existing non-references folders
+  for (const folder of existingNonReferencesFolders) {
+    if (folder.path !== '.') {
+      workspace.folders.push(folder);
+    }
+  }
 
-    // Check if already exists
-    const existingIndex = workspace.folders.findIndex(f => f.path === knowledgePath);
-    if (existingIndex === -1) {
-      workspace.folders.push(folderEntry);
+  // 3. Add reference folders grouped by project
+  const referenceFolderPaths: string[] = [];
+  
+  // Determine if we're working with DetectedProject[] or string[]
+  const isDetectedProjects = linkedProjects.length > 0 && typeof linkedProjects[0] === 'object';
+
+  if (isDetectedProjects) {
+    // New behavior: use DetectedProject[] with knowledge, refs, tasks folders
+    const projects = linkedProjects as DetectedProject[];
+    
+    for (const project of projects) {
+      const folders = getProjectFolders(project);
+      const sourceLabel = project.source === 'global' ? 'global' : 'local';
+      
+      for (const folder of folders) {
+        referenceFolderPaths.push(folder.path);
+        
+        // Check if already exists
+        const existingIndex = workspace.folders.findIndex(f => f.path === folder.path);
+        if (existingIndex === -1) {
+          workspace.folders.push({
+            path: folder.path,
+            name: `${folder.displayName} [${sourceLabel}]`,
+          });
+        }
+      }
+    }
+  } else {
+    // Legacy behavior: string[] of project names (global storage only)
+    const projectNames = linkedProjects as string[];
+    const rrceHome = customGlobalPath || getRRCEHome();
+    
+    for (const projectName of projectNames) {
+      const projectDataPath = path.join(rrceHome, 'workspaces', projectName);
+      
+      const folderTypes = [
+        { subpath: 'knowledge', icon: '📚', type: 'knowledge' },
+        { subpath: 'refs', icon: '📎', type: 'refs' },
+        { subpath: 'tasks', icon: '📋', type: 'tasks' },
+      ];
+      
+      for (const { subpath, icon, type } of folderTypes) {
+        const folderPath = path.join(projectDataPath, subpath);
+        if (fs.existsSync(folderPath)) {
+          referenceFolderPaths.push(folderPath);
+          
+          const existingIndex = workspace.folders.findIndex(f => f.path === folderPath);
+          if (existingIndex === -1) {
+            workspace.folders.push({
+              path: folderPath,
+              name: `${icon} ${projectName} (${type}) [global]`,
+            });
+          }
+        }
+      }
     }
   }
 
-  // Write workspace file
+  // 4. Add workspace settings to mark reference folders as readonly
+  // This uses files.readonlyInclude to make imported folders read-only
+  if (referenceFolderPaths.length > 0) {
+    const readonlyPatterns: Record<string, boolean> = {};
+    
+    for (const folderPath of referenceFolderPaths) {
+      // Create a pattern that matches all files in this folder
+      readonlyPatterns[`${folderPath}/**`] = true;
+    }
+    
+    // Merge with existing readonly patterns
+    const existingReadonly = (workspace.settings['files.readonlyInclude'] as Record<string, boolean>) || {};
+    workspace.settings['files.readonlyInclude'] = {
+      ...existingReadonly,
+      ...readonlyPatterns,
+    };
+  }
+
+  // 5. Add helpful workspace settings for multi-root experience
+  workspace.settings['explorer.sortOrder'] = workspace.settings['explorer.sortOrder'] || 'default';
+  
+  // Write workspace file with nice formatting
   fs.writeFileSync(workspaceFilePath, JSON.stringify(workspace, null, 2));
 }
+
+/**
+ * Remove a project's folders from the workspace file
+ */
+export function removeProjectFromWorkspace(
+  workspacePath: string,
+  workspaceName: string,
+  projectName: string
+) {
+  const workspaceFilePath = path.join(workspacePath, `${workspaceName}.code-workspace`);
+  
+  if (!fs.existsSync(workspaceFilePath)) {
+    return;
+  }
+
+  try {
+    const content = fs.readFileSync(workspaceFilePath, 'utf-8');
+    const workspace: VSCodeWorkspace = JSON.parse(content);
+    
+    // Filter out folders that match the project name
+    workspace.folders = workspace.folders.filter(f => 
+      !f.name?.includes(projectName)
+    );
+    
+    // Also remove readonly patterns for this project
+    if (workspace.settings?.['files.readonlyInclude']) {
+      const readonly = workspace.settings['files.readonlyInclude'] as Record<string, boolean>;
+      for (const pattern of Object.keys(readonly)) {
+        if (pattern.includes(projectName)) {
+          delete readonly[pattern];
+        }
+      }
+    }
+    
+    fs.writeFileSync(workspaceFilePath, JSON.stringify(workspace, null, 2));
+  } catch {
+    // Ignore errors
+  }
+}

package/src/lib/autocomplete-prompt.ts

@@ -0,0 +1,190 @@
+import { TextPrompt, isCancel, type Prompt } from '@clack/core';
+import * as fs from 'fs';
+import * as path from 'path';
+import pc from 'picocolors';
+
+interface DirectoryAutocompleteOptions {
+  message: string;
+  placeholder?: string;
+  initialValue?: string;
+  validate?: (value: string) => string | undefined;
+  hint?: string;
+}
+
+/**
+ * Custom text input with Tab-completion for directory paths
+ * Uses @clack/core TextPrompt with custom key handling
+ */
+export async function directoryAutocomplete(opts: DirectoryAutocompleteOptions): Promise<string | symbol> {
+  let completions: string[] = [];
+  let completionIndex = 0;
+  let lastTabValue = '';
+
+  const prompt = new TextPrompt({
+    initialValue: opts.initialValue,
+    validate: opts.validate,
+    render() {
+      const title = `${pc.cyan('◆')}  ${opts.message}`;
+      const hintText = opts.hint ? pc.dim(` (${opts.hint})`) : '';
+      
+      let inputLine: string;
+      if (this.state === 'error') {
+        inputLine = `${pc.yellow('▲')}  ${this.valueWithCursor}`;
+      } else if (this.state === 'submit') {
+        inputLine = `${pc.green('✓')}  ${pc.dim(String(this.value || ''))}`;
+      } else {
+        inputLine = `${pc.cyan('│')}  ${this.valueWithCursor || pc.dim(opts.placeholder || '')}`;
+      }
+      
+      let result = `${title}${hintText}\n${inputLine}`;
+      
+      if (this.state === 'error' && this.error) {
+        result += `\n${pc.yellow('│')}  ${pc.yellow(this.error)}`;
+      }
+      
+      // Show completion hint if multiple options
+      if (completions.length > 1 && this.state === 'active') {
+        const remaining = completions.length - 1;
+        result += `\n${pc.dim('│')}  ${pc.dim(`+${remaining} more, press Tab again to cycle`)}`;
+      }
+      
+      return result;
+    },
+  });
+
+  // Listen for key events - Tab key handling
+  prompt.on('key', (key) => {
+    if (key === '\t' || key === 'tab') {
+      handleTabCompletion(prompt);
+    } else {
+      // Reset completion state on any other key
+      completions = [];
+      completionIndex = 0;
+      lastTabValue = '';
+    }
+  });
+
+  function handleTabCompletion(p: TextPrompt) {
+    const input = String(p.value || '');
+    
+    // Expand ~ to home directory
+    const expanded = input.startsWith('~')
+      ? input.replace(/^~/, process.env.HOME || '')
+      : input;
+
+    // If user hasn't changed input since last tab, cycle through completions
+    if (lastTabValue === input && completions.length > 1) {
+      completionIndex = (completionIndex + 1) % completions.length;
+      const completion = completions[completionIndex] || '';
+      setPromptValue(p, completion);
+      return;
+    }
+
+    // Get new completions
+    completions = getDirectoryCompletions(expanded);
+    completionIndex = 0;
+    lastTabValue = input;
+
+    if (completions.length === 1) {
+      // Single match - auto-complete with trailing slash if directory
+      const completion = completions[0] || '';
+      setPromptValue(p, completion.endsWith('/') ? completion : completion + '/');
+      completions = []; // Clear so next Tab gets fresh completions
+      lastTabValue = '';
+    } else if (completions.length > 1) {
+      // Multiple matches - complete common prefix and show first
+      const commonPrefix = getCommonPrefix(completions);
+      if (commonPrefix.length > expanded.length) {
+        setPromptValue(p, commonPrefix);
+        lastTabValue = formatForDisplay(commonPrefix);
+      } else {
+        // Show first completion
+        setPromptValue(p, completions[0] || '');
+      }
+    }
+  }
+
+  function setPromptValue(p: TextPrompt, value: string) {
+    // Convert back to ~ format if in home directory for display
+    const displayValue = formatForDisplay(value);
+    
+    // Update the prompt's value by emitting a value event
+    // This is a workaround since TextPrompt doesn't expose a direct setValue method
+    (p as any).value = displayValue;
+  }
+
+  function formatForDisplay(value: string): string {
+    const home = process.env.HOME || '';
+    return value.startsWith(home)
+      ? value.replace(home, '~')
+      : value;
+  }
+
+  function getDirectoryCompletions(inputPath: string): string[] {
+    try {
+      let dirToScan: string;
+      let prefix: string;
+
+      if (inputPath === '' || inputPath === '/') {
+        dirToScan = inputPath || '/';
+        prefix = '';
+      } else if (inputPath.endsWith('/')) {
+        // User typed a complete directory path
+        dirToScan = inputPath;
+        prefix = '';
+      } else {
+        // User is typing a partial name
+        dirToScan = path.dirname(inputPath);
+        prefix = path.basename(inputPath).toLowerCase();
+      }
+
+      if (!fs.existsSync(dirToScan)) {
+        return [];
+      }
+
+      const entries = fs.readdirSync(dirToScan, { withFileTypes: true })
+        .filter(entry => {
+          // Only directories
+          if (!entry.isDirectory()) return false;
+          // Skip hidden directories unless explicitly typing them
+          if (entry.name.startsWith('.') && !prefix.startsWith('.')) return false;
+          // Match prefix
+          return prefix === '' || entry.name.toLowerCase().startsWith(prefix);
+        })
+        .map(entry => path.join(dirToScan, entry.name))
+        .sort();
+
+      return entries;
+    } catch {
+      return [];
+    }
+  }
+
+  function getCommonPrefix(strings: string[]): string {
+    if (strings.length === 0) return '';
+    if (strings.length === 1) return strings[0] || '';
+
+    let prefix = strings[0] || '';
+    for (let i = 1; i < strings.length; i++) {
+      const str = strings[i] || '';
+      while (prefix.length > 0 && !str.startsWith(prefix)) {
+        prefix = prefix.slice(0, -1);
+      }
+    }
+    return prefix;
+  }
+
+  const result = await prompt.prompt();
+  
+  if (isCancel(result)) {
+    return result;
+  }
+  
+  // Expand ~ in final result
+  const value = String(result || '');
+  return value.startsWith('~')
+    ? value.replace(/^~/, process.env.HOME || '')
+    : value;
+}
+
+export { isCancel };

package/src/lib/detection.ts

@@ -0,0 +1,235 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { StorageMode } from '../types/prompt';
+import { getDefaultRRCEHome } from './paths';
+
+/**
+ * Detected rrce-workflow project information
+ */
+export interface DetectedProject {
+  name: string;
+  path: string;           // Absolute path to project root
+  dataPath: string;       // Path to .rrce-workflow data directory
+  source: 'global' | 'sibling' | 'parent';
+  storageMode?: StorageMode;
+  knowledgePath?: string;
+  refsPath?: string;
+  tasksPath?: string;
+}
+
+interface ScanOptions {
+  excludeWorkspace?: string;  // Current workspace name to exclude
+  workspacePath?: string;     // Current workspace path for sibling detection
+  scanSiblings?: boolean;     // Whether to scan sibling directories (default: true)
+}
+
+/**
+ * Scan for rrce-workflow projects in various locations
+ */
+export function scanForProjects(options: ScanOptions = {}): DetectedProject[] {
+  const { excludeWorkspace, workspacePath, scanSiblings = true } = options;
+  const projects: DetectedProject[] = [];
+  const seenPaths = new Set<string>();
+
+  // 1. Scan global storage (~/.rrce-workflow/workspaces/)
+  const globalProjects = scanGlobalStorage(excludeWorkspace);
+  for (const project of globalProjects) {
+    if (!seenPaths.has(project.path)) {
+      seenPaths.add(project.path);
+      projects.push(project);
+    }
+  }
+
+  // 2. Scan sibling directories (same parent as current workspace)
+  if (scanSiblings && workspacePath) {
+    const siblingProjects = scanSiblingDirectories(workspacePath, excludeWorkspace);
+    for (const project of siblingProjects) {
+      if (!seenPaths.has(project.path)) {
+        seenPaths.add(project.path);
+        projects.push(project);
+      }
+    }
+  }
+
+  return projects;
+}
+
+/**
+ * Scan global storage for projects
+ */
+function scanGlobalStorage(excludeWorkspace?: string): DetectedProject[] {
+  const rrceHome = getDefaultRRCEHome();
+  const workspacesDir = path.join(rrceHome, 'workspaces');
+  const projects: DetectedProject[] = [];
+
+  if (!fs.existsSync(workspacesDir)) {
+    return projects;
+  }
+
+  try {
+    const entries = fs.readdirSync(workspacesDir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === excludeWorkspace) continue;
+
+      const projectDataPath = path.join(workspacesDir, entry.name);
+      const knowledgePath = path.join(projectDataPath, 'knowledge');
+      const refsPath = path.join(projectDataPath, 'refs');
+      const tasksPath = path.join(projectDataPath, 'tasks');
+
+      projects.push({
+        name: entry.name,
+        path: projectDataPath,  // For global projects, path is the data path
+        dataPath: projectDataPath,
+        source: 'global',
+        knowledgePath: fs.existsSync(knowledgePath) ? knowledgePath : undefined,
+        refsPath: fs.existsSync(refsPath) ? refsPath : undefined,
+        tasksPath: fs.existsSync(tasksPath) ? tasksPath : undefined,
+      });
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  return projects;
+}
+
+/**
+ * Scan sibling directories for workspace-scoped projects
+ */
+function scanSiblingDirectories(workspacePath: string, excludeWorkspace?: string): DetectedProject[] {
+  const parentDir = path.dirname(workspacePath);
+  const projects: DetectedProject[] = [];
+
+  try {
+    const entries = fs.readdirSync(parentDir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      
+      const projectPath = path.join(parentDir, entry.name);
+      
+      // Skip current workspace
+      if (projectPath === workspacePath) continue;
+      if (entry.name === excludeWorkspace) continue;
+
+      // Check for .rrce-workflow/config.yaml
+      const configPath = path.join(projectPath, '.rrce-workflow', 'config.yaml');
+      if (!fs.existsSync(configPath)) continue;
+
+      // Parse config to get project details
+      const config = parseWorkspaceConfig(configPath);
+      if (!config) continue;
+
+      const dataPath = path.join(projectPath, '.rrce-workflow');
+      const knowledgePath = path.join(dataPath, 'knowledge');
+      const refsPath = path.join(dataPath, 'refs');
+      const tasksPath = path.join(dataPath, 'tasks');
+
+      projects.push({
+        name: config.name || entry.name,
+        path: projectPath,
+        dataPath,
+        source: 'sibling',
+        storageMode: config.storageMode,
+        knowledgePath: fs.existsSync(knowledgePath) ? knowledgePath : undefined,
+        refsPath: fs.existsSync(refsPath) ? refsPath : undefined,
+        tasksPath: fs.existsSync(tasksPath) ? tasksPath : undefined,
+      });
+    }
+  } catch {
+    // Ignore errors
+  }
+
+  return projects;
+}
+
+/**
+ * Parse a workspace config file
+ */
+export function parseWorkspaceConfig(configPath: string): {
+  name: string;
+  storageMode: StorageMode;
+  linkedProjects?: string[];
+} | null {
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    
+    // Simple YAML parsing (we don't want to add a full YAML library)
+    const nameMatch = content.match(/name:\s*["']?([^"'\n]+)["']?/);
+    const modeMatch = content.match(/mode:\s*(global|workspace|both)/);
+    
+    // Parse linked projects
+    const linkedProjects: string[] = [];
+    const linkedMatch = content.match(/linked_projects:\s*\n((?:\s+-\s+[^\n]+\n?)+)/);
+    if (linkedMatch && linkedMatch[1]) {
+      const lines = linkedMatch[1].split('\n');
+      for (const line of lines) {
+        const projectMatch = line.match(/^\s+-\s+(.+)$/);
+        if (projectMatch && projectMatch[1]) {
+          linkedProjects.push(projectMatch[1].trim());
+        }
+      }
+    }
+
+    return {
+      name: nameMatch?.[1]?.trim() || path.basename(path.dirname(path.dirname(configPath))),
+      storageMode: (modeMatch?.[1] as StorageMode) || 'global',
+      linkedProjects: linkedProjects.length > 0 ? linkedProjects : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get display label for a detected project
+ */
+export function getProjectDisplayLabel(project: DetectedProject): string {
+  switch (project.source) {
+    case 'global':
+      return `global: ~/.rrce-workflow/workspaces/${project.name}`;
+    case 'sibling':
+      return `sibling: ${project.path}/.rrce-workflow`;
+    default:
+      return project.dataPath;
+  }
+}
+
+/**
+ * Get all linkable folders from a detected project
+ */
+export function getProjectFolders(project: DetectedProject): Array<{
+  path: string;
+  type: 'knowledge' | 'refs' | 'tasks';
+  displayName: string;
+}> {
+  const folders: Array<{ path: string; type: 'knowledge' | 'refs' | 'tasks'; displayName: string }> = [];
+
+  if (project.knowledgePath) {
+    folders.push({
+      path: project.knowledgePath,
+      type: 'knowledge',
+      displayName: `📚 ${project.name} (knowledge)`,
+    });
+  }
+
+  if (project.refsPath) {
+    folders.push({
+      path: project.refsPath,
+      type: 'refs',
+      displayName: `📎 ${project.name} (refs)`,
+    });
+  }
+
+  if (project.tasksPath) {
+    folders.push({
+      path: project.tasksPath,
+      type: 'tasks',
+      displayName: `📋 ${project.name} (tasks)`,
+    });
+  }
+
+  return folders;
+}

package/src/lib/prompts.ts

@@ -1,8 +1,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { fileURLToPath } from 'url';
 import matter from 'gray-matter';
 import { PromptFrontmatterSchema, type ParsedPrompt } from '../types/prompt';
 
+// Get __dirname equivalent for ESM (works with both npm/tsx and Bun)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
 /**
  * Parse a prompt file and extract frontmatter + content
  */
@@ -52,10 +57,11 @@ export function loadPromptsFromDir(dirPath: string): ParsedPrompt[] {
 
 /**
  * Get the agent-core root directory
+ * Works with both npm/tsx and Bun
  */
 export function getAgentCoreDir(): string {
-  // Relative to the package root
-  return path.join(import.meta.dir, '..', '..', 'agent-core');
+  // Relative to this file: src/lib/prompts.ts -> ../../agent-core
+  return path.join(__dirname, '..', '..', 'agent-core');
 }
 
 /**
@@ -64,3 +70,4 @@ export function getAgentCoreDir(): string {
 export function getAgentCorePromptsDir(): string {
   return path.join(getAgentCoreDir(), 'prompts');
 }
+