@mrpatronz/nexusflow 0.2.13 → 0.2.18

package/src/core/ports/storage.ts

@@ -0,0 +1,71 @@
+/**
+ * @module core/ports/storage
+ * Storage Port defining the interface for workspace document persistence.
+ *
+ * Adapters implement this interface to provide different storage backends.
+ * Each adapter is self-describing via the `meta` property, which enables
+ * automatic discovery in CLI, GUI, and plugin systems.
+ */
+
+/** Describes a single configurable field for an adapter. */
+export interface AdapterConfigField {
+  /** Machine-readable key, stored in config.json. */
+  key: string;
+  /** Human-readable label for CLI prompts and GUI forms. */
+  label: string;
+  /** Value type — 'path' renders a file picker in the GUI. */
+  type: 'string' | 'boolean' | 'number' | 'path';
+  /** Whether the field must be set before the adapter can be used. */
+  required?: boolean;
+  /** Default value when not explicitly configured. */
+  default?: unknown;
+  /** Help text shown in CLI prompts and GUI tooltips. */
+  description?: string;
+}
+
+/** Metadata that makes an adapter self-describing and discoverable. */
+export interface StorageAdapterMeta {
+  /** Unique machine-readable identifier (e.g. 'obsidian'). */
+  name: string;
+  /** Human-readable name for CLI tables and GUI dropdowns (e.g. 'Obsidian Vault'). */
+  displayName: string;
+  /** One-line description of what this adapter does. */
+  description: string;
+  /** Configuration fields this adapter accepts. Empty array = no config needed. */
+  configFields: AdapterConfigField[];
+}
+
+export interface StoragePort {
+  /** Adapter metadata — who am I, what do I need? */
+  readonly meta: StorageAdapterMeta;
+
+  /** Called once after registration with the user's per-adapter settings. */
+  configure?(settings: Record<string, unknown>): void;
+
+  /** Writes a workspace context/metadata document. */
+  writeWorkspaceFile(workspacePath: string, featureId: string, filename: string, content: string): Promise<void>;
+
+  /** Reads a workspace context/metadata document. */
+  readWorkspaceFile(workspacePath: string, featureId: string, filename: string): Promise<string>;
+
+  /** Checks if a workspace context/metadata document exists. */
+  workspaceFileExists(workspacePath: string, featureId: string, filename: string): Promise<boolean>;
+
+  /** Resolves the human-readable path or link to the workspace document for the AI assistant. */
+  resolveWorkspaceFileUrl(workspacePath: string, featureId: string, filename: string): string;
+
+  /** Writes a base-layer context document (stable maps/conventions across workspaces). */
+  writeBaseFile(workspacePath: string, repoName: string, filename: string, content: string): Promise<void>;
+
+  /** Reads a base-layer context document. */
+  readBaseFile(workspacePath: string, repoName: string, filename: string): Promise<string>;
+
+  /** Checks if a base-layer context document exists. */
+  baseFileExists(workspacePath: string, repoName: string, filename: string): Promise<boolean>;
+
+  /** Resolves the human-readable path or link to the base document. */
+  resolveBaseFileUrl(workspacePath: string, repoName: string, filename: string): string;
+
+  /** Cleanly deletes all workspace-specific documents from the storage backend. */
+  deleteWorkspace(workspacePath: string, featureId: string): Promise<void>;
+}

package/src/core/storage.ts

@@ -0,0 +1,37 @@
+import { getActiveStorageProvider } from './adapters/registry.js';
+
+export async function writeWorkspaceFile(workspacePath: string, featureId: string, filename: string, content: string): Promise<void> {
+  await getActiveStorageProvider().writeWorkspaceFile(workspacePath, featureId, filename, content);
+}
+
+export async function readWorkspaceFile(workspacePath: string, featureId: string, filename: string): Promise<string> {
+  return await getActiveStorageProvider().readWorkspaceFile(workspacePath, featureId, filename);
+}
+
+export async function workspaceFileExists(workspacePath: string, featureId: string, filename: string): Promise<boolean> {
+  return await getActiveStorageProvider().workspaceFileExists(workspacePath, featureId, filename);
+}
+
+export function resolveWorkspaceFileUrl(workspacePath: string, featureId: string, filename: string): string {
+  return getActiveStorageProvider().resolveWorkspaceFileUrl(workspacePath, featureId, filename);
+}
+
+export async function writeBaseFile(workspacePath: string, repoName: string, filename: string, content: string): Promise<void> {
+  await getActiveStorageProvider().writeBaseFile(workspacePath, repoName, filename, content);
+}
+
+export async function readBaseFile(workspacePath: string, repoName: string, filename: string): Promise<string> {
+  return await getActiveStorageProvider().readBaseFile(workspacePath, repoName, filename);
+}
+
+export async function baseFileExists(workspacePath: string, repoName: string, filename: string): Promise<boolean> {
+  return await getActiveStorageProvider().baseFileExists(workspacePath, repoName, filename);
+}
+
+export function resolveBaseFileUrl(workspacePath: string, repoName: string, filename: string): string {
+  return getActiveStorageProvider().resolveBaseFileUrl(workspacePath, repoName, filename);
+}
+
+export async function deleteWorkspaceFiles(workspacePath: string, featureId: string): Promise<void> {
+  await getActiveStorageProvider().deleteWorkspace(workspacePath, featureId);
+}

package/src/core/workspace.ts

@@ -7,6 +7,7 @@
 
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import * as os from 'node:os';
 import { execa } from 'execa';
 
 import type { Feature, RepoInfo, WorkspaceContext } from '../types.js';
@@ -14,8 +15,9 @@ import { createWorktree, removeWorktree } from './worktree.js';
 import { detectDefaultBranch } from '../utils/git.js';
 import { analyzeAllRepos } from '../analyzers/index.js';
 import { generateContextFiles } from '../generators/index.js';
-import { packWorkspace } from './packer.js';
 import { loadConfig } from './config.js';
+import { getActiveStorageProvider } from './adapters/registry.js';
+import { deleteWorkspaceFiles } from './storage.js';
 
 /** Name of the per-workspace manifest file. */
 const MANIFEST_FILE = 'nexusflow.json';
@@ -66,17 +68,40 @@ export async function createWorkspace(
     console.warn('Warning: Failed to initialize git repository at workspace root:', error);
   }
 
-  // Create .vscode/settings.json to allow VS Code search to query inside ignored sub-repos
+  // Generate a .code-workspace file so VS Code opens each repo as a top-level workspace
+  // folder with its own SCM provider. Without this, VS Code's git scanner respects the
+  // root .gitignore (which lists every repo dir) and never discovers the worktrees.
+  try {
+    const workspaceName = path.basename(workspacePath);
+    const codeWorkspace = {
+      folders: [
+        { path: '.', name: `${workspaceName} (workspace)` },
+        ...repos.map((repo) => ({ path: repo.name, name: repo.name })),
+      ],
+      settings: {
+        'search.useIgnoreFiles': false,
+      },
+    };
+    await fs.writeFile(
+      path.join(workspacePath, `${workspaceName}.code-workspace`),
+      JSON.stringify(codeWorkspace, null, 2) + '\n',
+      'utf-8',
+    );
+  } catch (error) {
+    console.warn('Warning: Failed to create .code-workspace file:', error);
+  }
+
+  // Create .vscode/settings.json for editors that don't use the .code-workspace file
   try {
     const vscodeDir = path.join(workspacePath, '.vscode');
     await fs.mkdir(vscodeDir, { recursive: true });
     const settings = {
-      "search.useIgnoreFiles": false
+      'search.useIgnoreFiles': false,
     };
     await fs.writeFile(
       path.join(vscodeDir, 'settings.json'),
       JSON.stringify(settings, null, 2) + '\n',
-      'utf-8'
+      'utf-8',
     );
   } catch (error) {
     console.warn('Warning: Failed to create .vscode/settings.json:', error);
@@ -90,7 +115,7 @@ export async function createWorkspace(
       "mcpServers": {
         "nexusflow": {
           "command": "npx",
-          "args": ["-y", "@mrpatronz/nexusflow", "mcp", "run", workspacePath]
+          "args": ["-y", "@mrpatronz/nexusflow", "mcp", "start"]
         }
       }
     };
@@ -117,6 +142,9 @@ export async function createWorkspace(
   // Persist the feature manifest.
   await saveFeatureConfig(workspacePath, feature);
 
+  // Exclude NexusFlow files from git
+  await excludeNexusFlowFiles(workspacePath, feature);
+
   return workspacePath;
 }
 
@@ -178,9 +206,9 @@ export async function saveFeatureConfig(
   workspacePath: string,
   feature: Feature,
 ): Promise<void> {
-  const manifestPath = path.join(workspacePath, MANIFEST_FILE);
   const data = JSON.stringify(feature, null, 2) + '\n';
-  await fs.writeFile(manifestPath, data, 'utf-8');
+  const adapter = getActiveStorageProvider();
+  await adapter.writeWorkspaceFile(workspacePath, feature.id, MANIFEST_FILE, data);
 }
 
 /**
@@ -194,16 +222,36 @@ export async function saveFeatureConfig(
 export async function loadFeatureConfig(
   workspacePath: string,
 ): Promise<Feature | null> {
-  const rootDir = await findWorkspaceRoot(workspacePath);
-  if (!rootDir) return null;
+  const featureId = path.basename(workspacePath);
+  const adapter = getActiveStorageProvider();
 
-  const manifestPath = path.join(rootDir, MANIFEST_FILE);
+  // 1. Try reading via the storage adapter first
+  try {
+    const raw = await adapter.readWorkspaceFile(workspacePath, featureId, MANIFEST_FILE);
+    return JSON.parse(raw) as Feature;
+  } catch {}
+
+  // 2. Try direct local check
+  const manifestPath = path.join(workspacePath, MANIFEST_FILE);
   try {
     const raw = await fs.readFile(manifestPath, 'utf-8');
     return JSON.parse(raw) as Feature;
-  } catch {
-    return null;
+  } catch {}
+
+  // 3. Try direct vault check
+  const vaultManifest = path.join(os.homedir(), '.nexusflow', 'vault', featureId, MANIFEST_FILE);
+  try {
+    const raw = await fs.readFile(vaultManifest, 'utf-8');
+    return JSON.parse(raw) as Feature;
+  } catch {}
+
+  // 4. Traverse parent directories
+  const rootDir = await findWorkspaceRoot(workspacePath);
+  if (rootDir && rootDir !== workspacePath) {
+    return loadFeatureConfig(rootDir);
   }
+
+  return null;
 }
 
 /**
@@ -255,6 +303,12 @@ export async function deleteWorkspace(
 ): Promise<void> {
   const feature = await loadFeatureConfig(workspacePath);
   if (feature) {
+    try {
+      await deleteWorkspaceFiles(workspacePath, feature.id);
+    } catch (error) {
+      console.warn(`Warning: failed to delete workspace context files from storage:`, error);
+    }
+
     const origRepos = feature.originalRepos || [];
     for (let i = 0; i < feature.repos.length; i++) {
       const worktreePath = feature.repos[i]!;
@@ -373,8 +427,61 @@ export async function addRepoToWorkspace(
   };
 
   await generateContextFiles(ctx, feature.assistants, workspacePath);
-  const config = await loadConfig();
-  if (config.packContextXml) {
-    await packWorkspace(workspacePath);
+  await excludeNexusFlowFiles(workspacePath, feature);
+}
+
+/**
+ * Automatically adds NexusFlow workspace context and config files to git's local
+ * exclude list for each repository so they never show up in `git status` or get committed.
+ */
+async function excludeNexusFlowFiles(workspacePath: string, feature: Feature): Promise<void> {
+  const excludeEntries = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    'WORKSPACE.md',
+    'nexusflow-knowledge.md',
+    'nexusflow-plan.md',
+    'nexusflow-conventions-*.md',
+    'nexusflow-map-*.md',
+    'nexusflow-diff-context.md',
+    '.cursor/rules/',
+    '.vscode/settings.json'
+  ];
+
+  for (const repoPath of feature.repos) {
+    try {
+      const gitDir = path.join(repoPath, '.git');
+      let worktreeGitDir = gitDir;
+      const stat = await fs.stat(gitDir);
+      if (stat.isFile()) {
+        const fileContent = await fs.readFile(gitDir, 'utf8');
+        const match = fileContent.match(/gitdir:\s*(.+)/);
+        if (match) {
+          worktreeGitDir = match[1].trim();
+        }
+      }
+      
+      const excludeFilePath = path.join(worktreeGitDir, 'info', 'exclude');
+      await fs.mkdir(path.dirname(excludeFilePath), { recursive: true });
+      
+      let excludeContent = '';
+      try {
+        excludeContent = await fs.readFile(excludeFilePath, 'utf8');
+      } catch {}
+
+      let updated = false;
+      for (const entry of excludeEntries) {
+        if (!excludeContent.includes(entry)) {
+          excludeContent = excludeContent.trim() + '\n' + entry + '\n';
+          updated = true;
+        }
+      }
+      
+      if (updated) {
+        await fs.writeFile(excludeFilePath, excludeContent.trim() + '\n', 'utf8');
+      }
+    } catch {
+      // Ignore if not a git repo or directory missing
+    }
   }
 }

package/src/generators/base.ts

@@ -8,6 +8,7 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import type { WorkspaceContext, ProjectAnalysis } from '../types.js';
+import { resolveBaseFileUrl, resolveWorkspaceFileUrl } from '../core/storage.js';
 
 /**
  * Formats a ProjectAnalysis into a readable markdown section.
@@ -17,9 +18,12 @@ function formatProjectSection(analysis: ProjectAnalysis, workspacePath: string):
 
   lines.push(`### ${analysis.name}`);
 
-  const mapPath = path.join(workspacePath, `nexusflow-map-${analysis.name}.md`).replace(/\\/g, '/');
+  const mapPath = resolveBaseFileUrl(workspacePath, analysis.name, `nexusflow-map-${analysis.name}.md`);
   lines.push(`- **Architecture Map**: [nexusflow-map-${analysis.name}.md](file:///${mapPath}) — **Instruction**: Before modifying this repository, read its architecture map. For exploration, consult the map's section index on demand.`);
 
+  const baseKnowledgePath = resolveBaseFileUrl(workspacePath, analysis.name, 'nexusflow-knowledge.md');
+  lines.push(`- **Base Knowledge & Decisions**: [nexusflow-knowledge.md](file:///${baseKnowledgePath}) — **Instruction**: Read this for persistent codebase learnings, decisions, and conventions.`);
+
   // Tech stack
   const { techStack } = analysis;
   if (techStack.languages.length > 0 && techStack.languages[0] !== 'other') {
@@ -151,19 +155,30 @@ ${parts.join('\n')}
     }
   }
 
-  const knowledgePath = path.join(workspacePath, 'nexusflow-knowledge.md').replace(/\\/g, '/');
+  const knowledgePath = resolveWorkspaceFileUrl(workspacePath, feature.id, 'nexusflow-knowledge.md').replace(/\\/g, '/');
 
   let setupDone = false;
   try {
-    const realKnowledgePath = path.join(workspacePath, 'nexusflow-knowledge.md');
-    if (fs.existsSync(realKnowledgePath)) {
-      const content = fs.readFileSync(realKnowledgePath, 'utf-8');
+    if (fs.existsSync(knowledgePath)) {
+      const content = fs.readFileSync(knowledgePath, 'utf-8');
       if (!content.includes('No assumptions recorded yet') && !content.includes('AI assistant to populate')) {
         setupDone = true;
       }
     }
   } catch {}
 
+  // Teamwork strategy section
+  let teamworkSection = '';
+  if (feature.teamworkInstructions) {
+    teamworkSection = `
+---
+
+## Team Collaboration Strategy
+
+${feature.teamworkInstructions}
+`;
+  }
+
   const taskSection = setupDone
     ? `## Setup Status\n\n✅ **Setup Completed**: Project assumptions and initial questions have been addressed. Refer to [nexusflow-knowledge.md](file:///${knowledgePath}) for persistent session details.`
     : `## First Steps\n\nYour very first task upon entering this workspace is to explore the codebase and align with the user:\n\n1. **Verify Assumptions**: Open [nexusflow-knowledge.md](file:///${knowledgePath}) and fill in the **Project Assumptions** section with a brief description of what each project does, its tech stack, and responsibilities.\n2. **Raise Questions**: Document any outstanding uncertainties or architectural questions in the **Clarifying Questions for the User** section.\n3. **Obtain Approval**: Ask the user to confirm your assumptions and answer your questions before writing any code.`;
@@ -189,6 +204,7 @@ ${resumptionSection}
 ---
 
 ${taskSection}
+${teamworkSection}
 ---
 
 ## Guidelines

package/src/generators/diff-context.ts

@@ -0,0 +1,75 @@
+import { execa } from 'execa';
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import type { WorkspaceContext } from '../types.js';
+import { getActiveStorageProvider } from '../core/adapters/registry.js';
+
+/**
+ * Generates an incremental task context file listing only changed files on the branch.
+ */
+export async function generateDiffContext(
+  ctx: WorkspaceContext,
+  workspacePath: string
+): Promise<void> {
+  let content = `# Incremental Task Context (Git Diff)\n\n`;
+  content += `This file lists the files modified or added on this feature branch compared to the base branch. Use this to focus the AI's attention.\n\n`;
+
+  let hasDiff = false;
+
+  for (const repo of ctx.repos) {
+    const repoPath = path.join(workspacePath, repo.name);
+    try {
+      await fs.access(repoPath);
+    } catch {
+      continue;
+    }
+
+    const defaultBranch = repo.defaultBranch || 'main';
+
+    let diffFiles: string[] = [];
+    try {
+      const { stdout } = await execa('git', ['diff', `origin/${defaultBranch}...HEAD`, '--name-only'], {
+        cwd: repoPath,
+        shell: process.platform === 'win32',
+      });
+      diffFiles = stdout.split('\n').map(f => f.trim()).filter(Boolean);
+    } catch {
+      try {
+        const { stdout } = await execa('git', ['diff', `${defaultBranch}...HEAD`, '--name-only'], {
+          cwd: repoPath,
+          shell: process.platform === 'win32',
+        });
+        diffFiles = stdout.split('\n').map(f => f.trim()).filter(Boolean);
+      } catch {
+        try {
+          const { stdout } = await execa('git', ['status', '--porcelain'], {
+            cwd: repoPath,
+            shell: process.platform === 'win32',
+          });
+          diffFiles = stdout.split('\n')
+            .map(line => line.slice(3).trim())
+            .filter(Boolean);
+        } catch {
+          // git command failed or not a repo
+        }
+      }
+    }
+
+    if (diffFiles.length > 0) {
+      hasDiff = true;
+      content += `## Repository: ${repo.name}\n\n`;
+      for (const file of diffFiles) {
+        const absoluteFilePath = path.join(repoPath, file).replace(/\\/g, '/');
+        content += `*   [${file}](file:///${absoluteFilePath})\n`;
+      }
+      content += `\n`;
+    }
+  }
+
+  if (!hasDiff) {
+    content += `*No changed files detected on this branch yet.*\n`;
+  }
+
+  const storage = getActiveStorageProvider();
+  await storage.writeWorkspaceFile(workspacePath, ctx.feature.id, 'nexusflow-diff-context.md', content);
+}

package/src/generators/index.ts

@@ -10,6 +10,8 @@ import { generateCursorConfig } from './cursor.js';
 import { buildContextContent } from './base.js';
 import { generateImplementationPlan } from './plan-generator.js';
 import { generateSkills } from './skills-generator.js';
+import { writeWorkspaceFile, workspaceFileExists, writeBaseFile, readBaseFile, baseFileExists } from '../core/storage.js';
+import { generateDiffContext } from './diff-context.js';
 
 /** Maps each assistant to its generator function and the file it produces. */
 const GENERATORS: Record<
@@ -102,6 +104,34 @@ _(No gotchas recorded yet.)_
 `;
 }
 
+/**
+ * Builds the base codebase knowledge starter content.
+ */
+function buildBaseKnowledgeContent(repoName: string): string {
+  return `# Base Codebase Knowledge — ${repoName}
+
+> **This is a persistent cross-session memory file for ${repoName}.**
+> AI assistants should read this at the start of each session, and append new architectural learnings, conventions, decisions, and gotchas at the end.
+> This file persists across all features and tasks for this repository.
+
+## Architecture & Domain Concepts
+<!-- Document major design patterns, domain layers, and system concepts here. -->
+- None recorded yet.
+
+## Coding Conventions & Invariants
+<!-- Document coding styles, library rules, and invariants that must not be broken. -->
+- None recorded yet.
+
+## Discovered Gotchas & Watch-outs
+<!-- Document weird behaviors, workarounds, or bugs to avoid repeating them. -->
+- None recorded yet.
+
+## Architecture Decisions
+<!-- Document key architectural decisions made for this repository over time. -->
+- None recorded yet.
+`;
+}
+
 /**
  * Generates AI context files for each of the selected assistants.
  *
@@ -119,32 +149,70 @@ export async function generateContextFiles(
   assistants: AIAssistant[],
   workspacePath: string,
   onlyRepo?: string,
+  onlyBase?: boolean,
 ): Promise<void> {
   // Always generate a universal WORKSPACE.md at the workspace root
-  try {
-    const content = buildContextContent(ctx);
-    const filePath = path.join(workspacePath, 'WORKSPACE.md');
-    await fse.writeFile(filePath, content, 'utf-8');
-    console.log(
-      chalk.green('  ✔'),
-      `Generated universal ${chalk.bold('WORKSPACE.md')}`,
-    );
+  if (!onlyBase) {
+    try {
+      const content = buildContextContent(ctx);
+      await writeWorkspaceFile(workspacePath, ctx.feature.id, 'WORKSPACE.md', content);
+      console.log(
+        chalk.green('  ✔'),
+        `Generated universal ${chalk.bold('WORKSPACE.md')}`,
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(
+        chalk.red('  ✖'),
+        `Failed to generate universal WORKSPACE.md: ${message}`,
+      );
+    }
+  }
 
-    // Generate nexusflow-knowledge.md if it does not exist
-    const knowledgePath = path.join(workspacePath, 'nexusflow-knowledge.md');
-    if (!(await fse.pathExists(knowledgePath))) {
-      const knowledgeContent = buildKnowledgeContent(ctx);
-      await fse.writeFile(knowledgePath, knowledgeContent, 'utf-8');
-      console.log(chalk.green('  ✔'), `Generated ${chalk.bold('nexusflow-knowledge.md')} (persistent AI memory)`);
+  // Generate base knowledge for each repo if it does not exist (or force recreate if onlyBase is true)
+  for (const repo of ctx.repos) {
+    if (onlyRepo && repo.name !== onlyRepo) {
+      continue;
+    }
+    const baseExists = await baseFileExists(workspacePath, repo.name, 'nexusflow-knowledge.md');
+    if (!baseExists || onlyBase) {
+      const baseContent = buildBaseKnowledgeContent(repo.name);
+      await writeBaseFile(workspacePath, repo.name, 'nexusflow-knowledge.md', baseContent);
+      console.log(
+        chalk.green('  ✔'),
+        `Generated base knowledge for ${chalk.bold(repo.name)}`,
+      );
     } else {
-      console.log(chalk.gray('  ○'), `nexusflow-knowledge.md already exists — preserving existing content`);
+      console.log(
+        chalk.gray('  ○'),
+        `Base knowledge for ${repo.name} already exists — preserving`,
+      );
+    }
+  }
+
+  if (!onlyBase) {
+    try {
+      // Generate nexusflow-knowledge.md if it does not exist
+      const knowledgeExists = await workspaceFileExists(workspacePath, ctx.feature.id, 'nexusflow-knowledge.md');
+      if (!knowledgeExists) {
+        const knowledgeContent = buildKnowledgeContent(ctx);
+        await writeWorkspaceFile(workspacePath, ctx.feature.id, 'nexusflow-knowledge.md', knowledgeContent);
+        console.log(chalk.green('  ✔'), `Generated ${chalk.bold('nexusflow-knowledge.md')} (persistent AI memory)`);
+      } else {
+        console.log(chalk.gray('  ○'), `nexusflow-knowledge.md already exists — preserving existing content`);
+      }
+
+      // Generate Git branch diff context file
+      await generateDiffContext(ctx, workspacePath);
+      console.log(chalk.green('  ✔'), `Generated ${chalk.bold('nexusflow-diff-context.md')} (incremental git diff)`);
+
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(
+        chalk.red('  ✖'),
+        `Failed to generate workspace context files: ${message}`,
+      );
     }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(
-      chalk.red('  ✖'),
-      `Failed to generate universal context files: ${message}`,
-    );
   }
 
   // Generate per-repo architecture maps
@@ -178,6 +246,10 @@ export async function generateContextFiles(
     }
   }
 
+  if (onlyBase) {
+    return;
+  }
+
   // Generate configuration for each selected assistant
   for (const assistant of assistants) {
     const entry = GENERATORS[assistant];

package/src/generators/map-generator.ts

@@ -7,6 +7,7 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { globby } from 'globby';
+import { writeWorkspaceFile, readWorkspaceFile, workspaceFileExists, writeBaseFile, readBaseFile, baseFileExists } from '../core/storage.js';
 import type { ProjectAnalysis, RepoInfo } from '../types.js';
 
 interface PatternRule {
@@ -493,14 +494,11 @@ export async function generateRepoMap(
   md.push('## 📝 Discovered Conventions');
   md.push('');
   
-  const conventionsFile = path.join(workspacePath, `nexusflow-conventions-${repoName}.md`);
+  const featureId = path.basename(workspacePath);
+  const conventionsFilename = `nexusflow-conventions-${repoName}.md`;
   let customConventions = '';
   
-  let conventionsExist = false;
-  try {
-    await fs.access(conventionsFile);
-    conventionsExist = true;
-  } catch {}
+  const conventionsExist = await workspaceFileExists(workspacePath, featureId, conventionsFilename);
 
   if (!conventionsExist) {
     const starterContent = `# Repository Conventions — ${repoName}
@@ -519,12 +517,12 @@ Future AI assistant sessions will read these conventions from the repository map
 - None recorded yet.
 `;
     try {
-      await fs.writeFile(conventionsFile, starterContent, 'utf-8');
+      await writeBaseFile(workspacePath, repoName, conventionsFilename, starterContent);
       customConventions = starterContent.replace(/^#\s+.+\n?/, '').trim();
     } catch {}
   } else {
     try {
-      customConventions = await fs.readFile(conventionsFile, 'utf-8');
+      customConventions = await readBaseFile(workspacePath, repoName, conventionsFilename);
       customConventions = customConventions.replace(/^#\s+.+\n?/, '').trim();
     } catch {}
   }
@@ -537,6 +535,5 @@ Future AI assistant sessions will read these conventions from the repository map
     md.push('');
   }
 
-  const outPath = path.join(workspacePath, `nexusflow-map-${repoName}.md`);
-  await fs.writeFile(outPath, md.join('\n'), 'utf-8');
+  await writeBaseFile(workspacePath, repoName, `nexusflow-map-${repoName}.md`, md.join('\n'));
 }