claude-comms 2.0.5 → 2.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-comms",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "NPX installer for Claude Code workflow engine client setup",
   "main": "src/index.js",
   "bin": {

package/src/cli/interfaces.js

@@ -9,6 +9,8 @@
  * These interfaces serve as the integration points between CLI and core modules.
  */
 
+const { ROOT_FILES } = require('../utils/constants');
+
 /**
  * GitHub Fetcher Interface
  * Will be implemented in WP03 - GitHub API Integration
@@ -279,14 +281,14 @@ class MockGitHubFetcher extends GitHubFetcherInterface {
           encoding: 'utf-8',
           sha: 'mock-sha-1'
         },
-        {
-          path: 'CLAUDE.md',
-          content: '# Claude Setup\n\nProject configured for Claude.',
+        ...ROOT_FILES.map((name, i) => ({
+          path: name,
+          content: `# ${name}\n\nProject configured for Claude.`,
           mode: 0o644,
           size: 45,
           encoding: 'utf-8',
-          sha: 'mock-sha-2'
-        }
+          sha: `mock-sha-${i + 2}`
+        }))
       ],
       directories: ['.claude', '.claude/hooks', '.claude/agents'],
       metadata: {

package/src/cli/prompts.js

@@ -12,6 +12,7 @@ const prompts = require('prompts');
 const path = require('path');
 const fs = require('fs').promises;
 const chalk = require('chalk');
+const { ROOT_FILES } = require('../utils/constants');
 
 /**
  * Main prompt orchestrator for installation flow
@@ -124,7 +125,7 @@ async function checkExistingFiles(targetDir) {
   const conflictFiles = [];
   const checkFiles = [
     '.claude',
-    'CLAUDE.md',
+    ...ROOT_FILES,
     '.claude/settings.json',
     '.claude/hooks',
     '.claude/agents'

package/src/cli/runner.js

@@ -17,6 +17,7 @@ const fs = require('fs').promises;
 
 const { parseArguments, displayHelp } = require('./parser');
 const { runInstallationPrompts, setupInterruptHandler } = require('./prompts');
+const { ROOT_FILES } = require('../utils/constants');
 
 /**
  * Main CLI entry point
@@ -321,11 +322,11 @@ function generateMockFileStructure(_tag) {
       content: '# Architect Agent\n\nSystem design and architecture specialist.\n',
       mode: 0o644
     },
-    {
-      path: 'CLAUDE.md',
-      content: '# Claude Code Setup\n\nThis project has been configured for Claude multi-agent orchestration.\n',
+    ...ROOT_FILES.map(name => ({
+      path: name,
+      content: `# ${name}\n\nThis project has been configured for Claude multi-agent orchestration.\n`,
       mode: 0o644
-    }
+    }))
   ];
 }
 
@@ -402,7 +403,7 @@ async function setExecutablePermissions(targetDir) {
 async function validateInstallation(targetDir) {
   const requiredFiles = [
     '.claude/settings.json',
-    'CLAUDE.md'
+    ...ROOT_FILES
   ];
 
   for (const file of requiredFiles) {

package/src/fetcher/github.js

@@ -7,6 +7,7 @@ const fetch = require('node-fetch');
 const tar = require('tar');
 const { EventEmitter } = require('events');
 const { GitHubAPIError } = require('../utils/errors');
+const { ROOT_FILES } = require('../utils/constants');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -336,8 +337,8 @@ class GitHubFetcher extends EventEmitter {
       '.agents/AGENTS.md',
       '.agents/repo.md',
 
-      // Root CLAUDE.md
-      'CLAUDE.md'
+      // Root files (single source of truth: ROOT_FILES)
+      ...ROOT_FILES
     ];
 
     const files = [];
@@ -346,7 +347,7 @@ class GitHubFetcher extends EventEmitter {
       if (filePath.startsWith(path) ||
           (path === '.claude' && filePath.startsWith('.claude')) ||
           (path === '.agents' && filePath.startsWith('.agents')) ||
-          (path === 'CLAUDE.md' && filePath === 'CLAUDE.md')) {
+          (ROOT_FILES.includes(path) && filePath === path)) {
         try {
           const content = await this._fetchSingleFileRaw(filePath, options);
           files.push(content);
@@ -913,11 +914,11 @@ class GitHubFetcher extends EventEmitter {
           // Only extract files we care about
           const isClaudeFile = actualPath.startsWith('.claude/') || actualPath === '.claude';
           const isAgentsFile = actualPath.startsWith('.agents/') || actualPath === '.agents';
-          const isClaudeMd = actualPath === 'CLAUDE.md';
+          const isRootFile = ROOT_FILES.includes(actualPath);
 
-          console.log(`DEBUG: ${actualPath} -> claude: ${isClaudeFile}, agents: ${isAgentsFile}, md: ${isClaudeMd}, type: ${entry.type}`);
+          console.log(`DEBUG: ${actualPath} -> claude: ${isClaudeFile}, agents: ${isAgentsFile}, root: ${isRootFile}, type: ${entry.type}`);
 
-          if ((isClaudeFile || isAgentsFile || isClaudeMd) && entry.type === 'File') {
+          if ((isClaudeFile || isAgentsFile || isRootFile) && entry.type === 'File') {
             wantedFiles.set(filePath, actualPath);
             console.log(`DEBUG: Will extract: ${filePath} -> ${actualPath}`);
             return true;
@@ -954,15 +955,15 @@ class GitHubFetcher extends EventEmitter {
                 const content = await fs.promises.readFile(fullPath, 'utf-8');
                 console.log(`DEBUG: Read ${actualPath} (${content.length} bytes)`);
 
-                if (actualPath === 'CLAUDE.md') {
-                  const claudeMdFileObj = {
-                    path: 'CLAUDE.md',
+                if (ROOT_FILES.includes(actualPath)) {
+                  const rootFileObj = {
+                    path: actualPath,
                     content: content,
                     encoding: 'utf-8',
                     type: 'file'
                   };
-                  extractedFiles['CLAUDE.md'] = claudeMdFileObj;
-                  console.log('DEBUG: Added CLAUDE.md to result');
+                  extractedFiles[actualPath] = rootFileObj;
+                  console.log(`DEBUG: Added ${actualPath} to result`);
                 } else if (actualPath.startsWith('.claude/')) {
                   // Add to .claude files
                   const fileObj = {
@@ -1001,7 +1002,10 @@ class GitHubFetcher extends EventEmitter {
             }
           }
 
-          console.log(`DEBUG: Final result - .claude has ${extractedFiles['.claude'].files.length} files, .agents has ${extractedFiles['.agents'].files.length} files, CLAUDE.md: ${extractedFiles['CLAUDE.md'] ? 'present' : 'missing'}`);
+          const rootFilesSummary = ROOT_FILES
+            .map(name => `${name}: ${extractedFiles[name] ? 'present' : 'missing'}`)
+            .join(', ');
+          console.log(`DEBUG: Final result - .claude has ${extractedFiles['.claude'].files.length} files, .agents has ${extractedFiles['.agents'].files.length} files, ${rootFilesSummary}`);
 
           // Clean up temp directory
           try {
@@ -1086,14 +1090,18 @@ async function fetchRepository(gitRef = 'main', options = {}) {
     console.log('Attempting tarball fetch strategy...');
     const tarballFiles = await fetcher.fetchAsTarball({ version: gitRef });
 
+    const rootFiles = ROOT_FILES.map(name => tarballFiles[name]);
+
     return {
       claudeDirectory: tarballFiles['.claude'],
       agentsDirectory: tarballFiles['.agents'],
+      // Per-filename root file keys remain top-level siblings on the result.
       claudeFile: tarballFiles['CLAUDE.md'],
+      ...Object.fromEntries(ROOT_FILES.map(name => [name, tarballFiles[name]])),
       files: [
         ...(tarballFiles['.claude'].files || []),
         ...(tarballFiles['.agents'].files || []),
-        tarballFiles['CLAUDE.md']
+        ...rootFiles
       ]
     };
 
@@ -1103,17 +1111,19 @@ async function fetchRepository(gitRef = 'main', options = {}) {
 
     try {
       // Strategy 2: Individual file fetch (fallback)
-      const [claudeDir, agentsDir, claudeMd] = await Promise.all([
+      const [claudeDir, agentsDir, ...rootFiles] = await Promise.all([
         fetcher.fetchDirectory('.claude', { version: gitRef }),
         fetcher.fetchDirectory('.agents', { version: gitRef }),
-        fetcher.fetchFile('CLAUDE.md', { version: gitRef })
+        ...ROOT_FILES.map(name => fetcher.fetchFile(name, { version: gitRef }))
       ]);
 
       return {
         claudeDirectory: claudeDir,
         agentsDirectory: agentsDir,
-        claudeFile: claudeMd,
-        files: [...(claudeDir.files || []), ...(agentsDir.files || []), claudeMd]
+        // Per-filename root file keys remain top-level siblings on the result.
+        claudeFile: rootFiles[ROOT_FILES.indexOf('CLAUDE.md')],
+        ...Object.fromEntries(ROOT_FILES.map((name, i) => [name, rootFiles[i]])),
+        files: [...(claudeDir.files || []), ...(agentsDir.files || []), ...rootFiles]
       };
 
     } catch (fallbackError) {

package/src/orchestrator/installer.js

@@ -15,6 +15,7 @@
 const EventEmitter = require('events');
 const path = require('path');
 const { InstallerError } = require('../utils/errors');
+const { ROOT_FILES } = require('../utils/constants');
 
 // Error codes enum - matches interface contracts
 const ErrorCode = {
@@ -281,18 +282,19 @@ class Installer extends EventEmitter {
         retryCount: 3
       });
 
-      // Fetch CLAUDE.md file
-      const claudeMd = await this.fetcher.fetchFile('CLAUDE.md', {
-        version: this.options.version,
-        useCache: this.options.cache
-      });
-
+      // Fetch root files (single source of truth: ROOT_FILES) as sibling keys
       const fetchedFiles = {
         '.claude': claudeFiles,
-        '.agents': agentsFiles,
-        'CLAUDE.md': claudeMd
+        '.agents': agentsFiles
       };
 
+      for (const rootFile of ROOT_FILES) {
+        fetchedFiles[rootFile] = await this.fetcher.fetchFile(rootFile, {
+          version: this.options.version,
+          useCache: this.options.cache
+        });
+      }
+
       // Calculate total files for progress tracking
       this.progress.total = this._countFiles(fetchedFiles);
 
@@ -419,7 +421,7 @@ class Installer extends EventEmitter {
     const requiredPaths = [
       path.join(this.options.targetDir, '.claude'),
       path.join(this.options.targetDir, '.agents'),
-      path.join(this.options.targetDir, 'CLAUDE.md')
+      ...ROOT_FILES.map(name => path.join(this.options.targetDir, name))
     ];
 
     const missingPaths = [];
@@ -434,7 +436,7 @@ class Installer extends EventEmitter {
     if (this.writer.validateInstallationCompleteness) {
       const completenessResult = await this.writer.validateInstallationCompleteness(
         this.options.targetDir,
-        ['CLAUDE.md']
+        [...ROOT_FILES]
       );
 
       if (!completenessResult.complete) {
@@ -677,7 +679,6 @@ class Installer extends EventEmitter {
     // Check for existing directories and files that will be overwritten
     const claudeDir = path.join(this.options.targetDir, '.claude');
     const agentsDir = path.join(this.options.targetDir, '.agents');
-    const claudeMd = path.join(this.options.targetDir, 'CLAUDE.md');
 
     const existingPaths = [];
     if (await this.validator.pathExists(claudeDir)) {
@@ -686,8 +687,10 @@ class Installer extends EventEmitter {
     if (await this.validator.pathExists(agentsDir)) {
       existingPaths.push('.agents/');
     }
-    if (await this.validator.pathExists(claudeMd)) {
-      existingPaths.push('CLAUDE.md');
+    for (const rootFile of ROOT_FILES) {
+      if (await this.validator.pathExists(path.join(this.options.targetDir, rootFile))) {
+        existingPaths.push(rootFile);
+      }
     }
 
     if (existingPaths.length > 0) {
@@ -718,12 +721,16 @@ class Installer extends EventEmitter {
       });
     }
 
-    if (!fetchedFiles['CLAUDE.md']) {
-      issues.push({
-        type: 'missing_component',
-        component: 'CLAUDE.md',
-        message: 'Missing CLAUDE.md file'
-      });
+    // Root files are required (same semantics as CLAUDE.md): if any ROOT_FILES
+    // entry is missing after fetch, validation reports it incomplete.
+    for (const rootFile of ROOT_FILES) {
+      if (!fetchedFiles[rootFile]) {
+        issues.push({
+          type: 'missing_component',
+          component: rootFile,
+          message: `Missing ${rootFile} file`
+        });
+      }
     }
 
     // Check .claude structure if present

package/src/orchestrator/main.js

@@ -16,6 +16,7 @@ const ora = require('ora');
 // Import core modules (these will be implemented in WP02-06)
 const logger = require('./utils/logger');
 const { InstallationError } = require('./utils/errors');
+const { ROOT_FILES } = require('../utils/constants');
 const fetcher = require('./fetcher/github');
 const fileWriter = require('./installer/file-writer');
 const dependencyChecker = require('./installer/dependency-check');
@@ -104,11 +105,12 @@ async function validateEnvironment(targetDir, checkPython) {
  */
 async function handleExistingFiles(targetDir, force, verify, dryRun) {
   const claudeDir = path.join(targetDir, '.claude');
-  const claudeMd = path.join(targetDir, 'CLAUDE.md');
 
   const existingFiles = [];
   if (await fs.pathExists(claudeDir)) existingFiles.push('.claude/');
-  if (await fs.pathExists(claudeMd)) existingFiles.push('CLAUDE.md');
+  for (const rootFile of ROOT_FILES) {
+    if (await fs.pathExists(path.join(targetDir, rootFile))) existingFiles.push(rootFile);
+  }
 
   if (existingFiles.length === 0) {
     logger.info('No existing files found - proceeding with fresh installation');
@@ -232,13 +234,12 @@ async function verifyInstallation(targetDir) {
 
   try {
     const claudeDir = path.join(targetDir, '.claude');
-    const claudeMd = path.join(targetDir, 'CLAUDE.md');
     const settingsPath = path.join(claudeDir, 'settings.local.json');
 
     // Check required files exist
     const checks = [
       { path: claudeDir, name: '.claude directory' },
-      { path: claudeMd, name: 'CLAUDE.md' },
+      ...ROOT_FILES.map(name => ({ path: path.join(targetDir, name), name })),
       { path: settingsPath, name: 'settings.local.json' }
     ];
 

package/src/orchestrator/mocks/index.js

@@ -133,6 +133,12 @@ class MockFetcher {
           content: '# Claude Code Multi-Agent Setup\n\nThis project is configured for Claude multi-agent orchestration.\n\n## Features\n- Multi-agent team coordination\n- Observability and monitoring\n- Hook-based extensibility\n\n## Getting Started\nReview .claude/settings.local.json for configuration.',
           encoding: 'utf-8',
           sha: 'mock-claude-md-sha'
+        },
+        'GEMINI.md': {
+          path: 'GEMINI.md',
+          content: '# Gemini Multi-Agent Setup\n\nThis project is configured for Gemini multi-agent orchestration.\n\n## Features\n- Multi-agent team coordination\n- Observability and monitoring\n- Hook-based extensibility\n\n## Getting Started\nReview .claude/settings.local.json for configuration.',
+          encoding: 'utf-8',
+          sha: 'mock-gemini-md-sha'
         }
       }
     };

package/src/utils/config.js

@@ -7,6 +7,7 @@ const path = require('path');
 const fs = require('fs').promises;
 const { ErrorFactory } = require('./errors');
 const platform = require('./platform');
+const { ROOT_FILES } = require('./constants');
 
 /**
  * Configuration manager with defaults, validation, and persistence
@@ -55,7 +56,7 @@ class Config {
       // File operations
       files: {
         excludePatterns: ['.git', 'node_modules', '.DS_Store'],
-        includePatterns: ['.claude/**/*', 'CLAUDE.md'],
+        includePatterns: ['.claude/**/*', ...ROOT_FILES],
         encoding: 'utf8',
         lineEnding: 'auto', // auto, lf, crlf
         maxFileSize: 10 * 1024 * 1024 // 10MB

package/src/utils/constants.js

@@ -44,6 +44,15 @@ const GITHUB_API = {
   }
 };
 
+/**
+ * Root-level files fetched/installed/validated as siblings.
+ *
+ * SINGLE SOURCE OF TRUTH for root filenames: adding the next root file is a
+ * one-line change to this array. Every fetch strategy (tarball, raw-URL,
+ * individual), every validation, and every verify step derives from this list.
+ */
+const ROOT_FILES = ['CLAUDE.md', 'GEMINI.md'];
+
 /**
  * File paths and patterns
  */
@@ -52,6 +61,9 @@ const FILE_PATHS = {
   CLAUDE_DIR: '.claude',
   CLAUDE_MD: 'CLAUDE.md',
 
+  // Root-level files (single source of truth)
+  ROOT_FILES,
+
   // Claude directory structure
   CLAUDE_SUBDIRS: [
     '.claude/agents',
@@ -60,12 +72,12 @@ const FILE_PATHS = {
     '.claude/hooks/comms'
   ],
 
-  // Key files to install
+  // Key files to install (root files derived from ROOT_FILES)
   REQUIRED_FILES: [
     '.claude/settings.json',
     '.claude/hooks/comms/get_unread_messages.py',
     '.claude/hooks/comms/send_message.py',
-    'CLAUDE.md'
+    ...ROOT_FILES
   ],
 
   // Configuration files
@@ -382,6 +394,7 @@ module.exports = {
   GITHUB_API,
   GITHUB_URLS,
   FILE_PATHS,
+  ROOT_FILES,
   ERROR_CODES,
   HTTP_STATUS,
   RETRY_CONFIG,