proagents 1.6.18 → 1.6.20

package/lib/commands/ai.js

@@ -8,8 +8,50 @@ import yaml from 'js-yaml';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// Load platforms from YAML (single source of truth)
+// Priority: 1) User's project .proagents/platforms.yaml, 2) npm package's platforms.yaml
+function loadPlatformsFromYaml() {
+  // First, try user's project directory
+  const userYamlPath = join(process.cwd(), '.proagents', 'platforms.yaml');
+  if (existsSync(userYamlPath)) {
+    try {
+      const content = readFileSync(userYamlPath, 'utf-8');
+      return yaml.load(content);
+    } catch (error) {
+      // Fall through to npm package
+    }
+  }
+
+  // Fallback to npm package's platforms.yaml
+  const packageYamlPath = join(__dirname, '..', '..', '.proagents', 'platforms.yaml');
+  if (existsSync(packageYamlPath)) {
+    try {
+      const content = readFileSync(packageYamlPath, 'utf-8');
+      return yaml.load(content);
+    } catch (error) {
+      console.warn('Warning: Could not load platforms.yaml, using defaults');
+    }
+  }
+
+  // Fallback to defaults if YAML doesn't exist
+  return null;
+}
+
+// Load from YAML or use defaults
+const platformsConfig = loadPlatformsFromYaml();
+
 // AI Platform definitions grouped by type
-export const AI_PLATFORMS = {
+export const AI_PLATFORMS = platformsConfig ? {
+  ide: {
+    label: platformsConfig.ide?.label || 'IDE-based AI Assistants',
+    platforms: platformsConfig.ide?.platforms || []
+  },
+  web: {
+    label: platformsConfig.web?.label || 'Web-based AI Platforms',
+    platforms: platformsConfig.web?.platforms || []
+  }
+} : {
+  // Fallback defaults (only used if platforms.yaml is missing)
   ide: {
     label: 'IDE-based AI Assistants',
     platforms: [
@@ -18,34 +60,28 @@ export const AI_PLATFORMS = {
       { id: 'windsurf', name: 'Windsurf', file: '.windsurfrules', desc: 'Codeium Windsurf IDE' },
       { id: 'copilot', name: 'GitHub Copilot', file: '.github/copilot-instructions.md', desc: 'GitHub Copilot' },
       { id: 'kiro', name: 'AWS Kiro', file: 'KIRO.md', desc: 'AWS Kiro IDE' },
-      { id: 'antigravity', name: 'Antigravity', file: 'ANTIGRAVITY.md', desc: 'Antigravity IDE (Gemini/Claude)' },
+      { id: 'gemini', name: 'Gemini', file: 'GEMINI.md', desc: 'Google Gemini / AI Studio' },
     ]
   },
   web: {
     label: 'Web-based AI Platforms',
     platforms: [
-      { id: 'chatgpt', name: 'ChatGPT', file: 'CHATGPT.md', desc: 'OpenAI ChatGPT' },
-      { id: 'gemini', name: 'Gemini', file: 'GEMINI.md', desc: 'Google Gemini' },
       { id: 'replit', name: 'Replit AI', file: 'REPLIT.md', desc: 'Replit Ghostwriter' },
       { id: 'bolt', name: 'Bolt.new', file: 'BOLT.md', desc: 'StackBlitz Bolt' },
       { id: 'lovable', name: 'Lovable', file: 'LOVABLE.md', desc: 'Lovable (GPT Engineer)' },
-      { id: 'groq', name: 'Groq', file: 'GROQ.md', desc: 'Groq fast inference' },
-    ]
-  },
-  cli: {
-    label: 'CLI-based AI Agents',
-    platforms: [
-      { id: 'codex', name: 'Codex CLI', file: 'AGENTS.md', desc: 'OpenAI Codex CLI' },
     ]
   }
 };
 
+// Auto-handled platforms (use AGENTS.md, no separate file needed)
+export const AUTO_HANDLED_PLATFORMS = platformsConfig?.auto_handled ||
+  ['ChatGPT', 'Groq', 'Antigravity', 'Codex CLI', 'OpenAI API'];
+
 // Get all platforms as flat array
 export function getAllPlatforms() {
   return [
     ...AI_PLATFORMS.ide.platforms,
     ...AI_PLATFORMS.web.platforms,
-    ...AI_PLATFORMS.cli.platforms,
   ];
 }
 
@@ -115,7 +151,12 @@ export async function selectPlatforms(previouslySelected = []) {
   const preselected = [...new Set([...autoSelected, ...(previouslySelected || [])])];
 
   console.log('\n' + chalk.bold('Which AI platform(s) do you use?'));
-  console.log(chalk.gray('(Enter numbers separated by commas, or "all" for all platforms)\n'));
+  console.log(chalk.gray('(Enter numbers separated by commas, or "all" for all platforms)'));
+
+  // Show auto-handled platforms info
+  console.log(chalk.cyan.bold('\n  Auto-handled (via AGENTS.md):'));
+  console.log(chalk.gray('    ' + AUTO_HANDLED_PLATFORMS.join(', ')));
+  console.log(chalk.gray('    → These work automatically, no installation needed\n'));
 
   let index = 1;
   const indexMap = {};
@@ -155,20 +196,6 @@ export async function selectPlatforms(previouslySelected = []) {
 
   console.log('');
 
-  // CLI-based platforms
-  console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.cli.label}:`));
-  for (const platform of AI_PLATFORMS.cli.platforms) {
-    const wasPreviouslySelected = previouslySelected && previouslySelected.includes(platform.id);
-    const isPreselected = preselected.includes(platform.id);
-    const marker = wasPreviouslySelected ? chalk.green(' ✓ (previously selected)') : '';
-    console.log(chalk.white(`    ${index}. ${platform.name}`) + chalk.gray(` - ${platform.desc}`) + marker);
-    indexMap[index] = platform.id;
-    if (isPreselected) preSelectedIndices.push(index);
-    index++;
-  }
-
-  console.log('');
-
   // Show default based on preselected (auto-detected + previously selected)
   const defaultHint = preSelectedIndices.length > 0
     ? `Enter for selected: ${preSelectedIndices.join(',')}`
@@ -253,12 +280,9 @@ function removeProagentsSectionFromFile(filePath) {
         return 'cleaned';
       }
     } else {
-      // No ProAgents markers - file was created by ProAgents (not merged)
-      // Check if it's a ProAgents-generated file by looking for ProAgents reference
-      if (content.includes('proagents') || content.includes('ProAgents') || content.includes('.proagents/')) {
-        rmSync(filePath, { force: true });
-        return 'deleted';
-      }
+      // No ProAgents markers found - we cannot safely determine what to remove
+      // Don't delete the file as it may contain user's own configuration
+      // User should manually clean up files without proper markers
       return 'skipped';
     }
   } catch (error) {
@@ -346,6 +370,24 @@ export function copyPlatformFiles(selectedIds, sourceDir, targetDir) {
   return results;
 }
 
+/**
+ * Copy universal AGENTS.md file (always present, not a selectable platform)
+ * @param {string} sourceDir - Source directory (.proagents folder in npm package)
+ * @param {string} targetDir - Target directory (project root)
+ * @returns {string} - 'created', 'updated', or 'skipped'
+ */
+export function copyUniversalAIFile(sourceDir, targetDir) {
+  const sourcePath = join(sourceDir, 'AGENTS.md');
+  const targetPath = join(targetDir, 'AGENTS.md');
+
+  if (!existsSync(sourcePath)) {
+    return 'skipped';
+  }
+
+  const result = mergeAIInstructions(sourcePath, targetPath);
+  return result;
+}
+
 /**
  * Save selected platforms to config
  */
@@ -431,6 +473,20 @@ export function getInstalledPlatforms(targetDir, configPath) {
  * Show available platforms that can be added
  */
 export function showAvailablePlatforms(currentIds) {
+  // Show auto-handled platforms info
+  console.log(chalk.cyan.bold('\n  Auto-handled (via AGENTS.md):'));
+  console.log(chalk.gray('    ' + AUTO_HANDLED_PLATFORMS.join(', ')));
+  console.log(chalk.gray('    → These work automatically, no installation needed'));
+  console.log(chalk.yellow('    ⚠️  Do not remove AGENTS.md - required for these platforms'));
+
+  // Show user's installed platforms
+  const installedNames = currentIds
+    .map(id => getPlatformById(id)?.name)
+    .filter(Boolean);
+  if (installedNames.length > 0) {
+    console.log(chalk.green('\n  Your platforms: ') + chalk.white(installedNames.join(', ')));
+  }
+
   console.log('\n' + chalk.bold('Available AI Platforms:\n'));
 
   let index = 1;
@@ -464,21 +520,6 @@ export function showAvailablePlatforms(currentIds) {
     index++;
   }
 
-  console.log('');
-
-  // CLI-based platforms
-  console.log(chalk.cyan.bold(`  ${AI_PLATFORMS.cli.label}:`));
-  for (const platform of AI_PLATFORMS.cli.platforms) {
-    const status = currentIds.includes(platform.id)
-      ? chalk.green(' ✓ (installed)')
-      : chalk.gray(' (not installed)');
-    console.log(chalk.white(`    ${index}. ${platform.name}`) + status);
-    if (!currentIds.includes(platform.id)) {
-      available.push({ index, platform });
-    }
-    index++;
-  }
-
   return available;
 }
 
@@ -540,6 +581,12 @@ export async function aiAddCommand() {
   // Copy files for new platforms
   const results = copyPlatformFiles(toAdd, sourceDir, targetDir);
 
+  // Ensure universal AGENTS.md exists (auto-handled platforms)
+  const agentsResult = copyUniversalAIFile(sourceDir, targetDir);
+  if (agentsResult === 'created') {
+    results.created.push('AGENTS.md (auto-handled)');
+  }
+
   // Update config
   const newIds = [...currentIds, ...toAdd];
   savePlatformConfig(newIds, configPath);
@@ -658,6 +705,8 @@ export async function aiRemoveCommand() {
         results.deleted.push(platform.name);
       } else if (result === 'cleaned') {
         results.cleaned.push(platform.name);
+      } else if (result === 'skipped') {
+        results.skipped.push(platform.name);
       }
     }
   }
@@ -670,6 +719,9 @@ export async function aiRemoveCommand() {
   if (results.cleaned.length > 0) {
     console.log(chalk.green(`✓ Cleaned ProAgents section from: ${results.cleaned.join(', ')} (kept your custom config)`));
   }
+  if (results.skipped.length > 0) {
+    console.log(chalk.yellow(`⚠ Skipped: ${results.skipped.join(', ')} (no ProAgents markers found - manual cleanup may be needed)`));
+  }
 
   console.log(chalk.gray('\nConfig updated in proagents.config.yaml\n'));
 }

package/lib/commands/init.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'url';
 import { createInterface } from 'readline';
 import chalk from 'chalk';
 import yaml from 'js-yaml';
-import { selectPlatforms, copyPlatformFiles, savePlatformConfig, loadPlatformConfig } from './ai.js';
+import { selectPlatforms, copyPlatformFiles, copyUniversalAIFile, savePlatformConfig, loadPlatformConfig } from './ai.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -213,9 +213,12 @@ const FRAMEWORK_FILES = [
   'GETTING-STARTED-STORY.md',
   'slash-commands.json',
   'AI_INSTRUCTIONS.md',  // Universal instructions kept for reference
-  'AGENTS.md',           // Universal AI instruction file (works with most AI platforms)
+  'platforms.yaml',      // Single source of truth for AI platforms
 ];
 
+// Universal AI file - always copied to project root (not selectable)
+const UNIVERSAL_AI_FILE = 'AGENTS.md';
+
 // Project type definitions for detection
 const PROJECT_TYPES = [
   {
@@ -1243,6 +1246,14 @@ For detailed commands, see \`./.proagents/PROAGENTS.md\`
     // Copy AI instruction files for selected platforms (merges with existing files)
     const aiResults = copyPlatformFiles(selectedPlatforms, sourceDir, targetDir);
 
+    // Always copy universal AGENTS.md
+    const agentsResult = copyUniversalAIFile(sourceDir, targetDir);
+    if (agentsResult === 'created') {
+      aiResults.created.push('AGENTS.md');
+    } else if (agentsResult === 'updated') {
+      aiResults.updated.push('AGENTS.md');
+    }
+
     if (aiResults.created.length > 0) {
       console.log(chalk.green(`✓ Created AI files: ${aiResults.created.join(', ')}`));
     }
@@ -1376,21 +1387,28 @@ async function smartUpdate(sourceDir, targetDir) {
 
   // Copy AI instruction files for configured platforms (merges with existing files)
   const projectRoot = join(targetDir, '..');
-  const configPath = join(targetDir, 'proagents.config.yaml');
+  const configPath = join(projectRoot, 'proagents.config.yaml');
   const selectedPlatforms = loadPlatformConfig(configPath);
 
-  if (selectedPlatforms.length > 0) {
-    const aiResults = copyPlatformFiles(selectedPlatforms, sourceDir, projectRoot);
+  // Copy AI instruction files for configured platforms
+  const aiResults = copyPlatformFiles(selectedPlatforms, sourceDir, projectRoot);
 
-    if (aiResults.created.length > 0) {
-      console.log(chalk.green(`✓ Created new AI files: ${aiResults.created.join(', ')}`));
-    }
-    if (aiResults.updated.length > 0) {
-      console.log(chalk.green(`✓ Updated AI files: ${aiResults.updated.join(', ')}`));
-    }
-    if (aiResults.merged.length > 0) {
-      console.log(chalk.green(`✓ Merged with existing: ${aiResults.merged.join(', ')}`));
-    }
+  // Always copy universal AGENTS.md
+  const agentsResult = copyUniversalAIFile(sourceDir, projectRoot);
+  if (agentsResult === 'created') {
+    aiResults.created.push('AGENTS.md');
+  } else if (agentsResult === 'updated') {
+    aiResults.updated.push('AGENTS.md');
+  }
+
+  if (aiResults.created.length > 0) {
+    console.log(chalk.green(`✓ Created new AI files: ${aiResults.created.join(', ')}`));
+  }
+  if (aiResults.updated.length > 0) {
+    console.log(chalk.green(`✓ Updated AI files: ${aiResults.updated.join(', ')}`));
+  }
+  if (aiResults.merged.length > 0) {
+    console.log(chalk.green(`✓ Merged with existing: ${aiResults.merged.join(', ')}`));
   }
 
   // Update framework files within preserved paths (templates, README, schemas)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proagents",
-  "version": "1.6.18",
+  "version": "1.6.20",
   "description": "AI-agnostic development workflow framework that automates the full software development lifecycle",
   "type": "module",
   "main": "lib/index.js",

package/.proagents/ANTIGRAVITY.md

@@ -1,59 +0,0 @@
-# ProAgents Commands for Antigravity IDE
-
-This project uses ProAgents - an AI-agnostic development workflow framework.
-
-## ⚠️ MANDATORY: Every pa: Command Flow
-
-### BEFORE Any pa: Command (Auto-Sync)
-
-**Read these files FIRST before doing anything:**
-
-```bash
-cat .proagents/worklog/_context.md      # Current state
-cat .proagents/changelog/_recent.md     # Recent changes
-tail -10 .proagents/activity.log        # Recent activity
-```
-
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
-
-### AFTER Any pa: Command (Auto-Log)
-
-**After EVERY file edit, IMMEDIATELY update these files:**
-
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
-
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
-
-## Essential Commands
-
-| Command | Action |
-|---------|--------|
-| `pa:feature "name"` | Start new feature workflow |
-| `pa:fix "bug"` | Quick bug fix mode |
-| `pa:doc` | Documentation options |
-| `pa:qa` | Quality assurance checks |
-| `pa:test` | Run test workflow |
-| `pa:deploy` | Deployment preparation |
-| `pa:status` | Show current progress |
-
-## Full Command Reference
-
-For complete command list, see: `./.proagents/AI_INSTRUCTIONS.md`
-
-## On `pa:` Command
-
-1. Read the corresponding file from `./.proagents/prompts/` or `./.proagents/workflow-modes/`
-2. Follow the workflow instructions
-3. Use project config from `./.proagents/proagents.config.yaml`
-
-## Key Files
-
-- `./.proagents/AI_INSTRUCTIONS.md` - Complete command reference
-- `./.proagents/WORKFLOW.md` - Full 10-phase workflow
-- `./.proagents/prompts/` - Phase-specific prompts
-
-## Note
-
-Works with both Gemini and Claude models in Antigravity.

package/.proagents/CHATGPT.md

@@ -1,55 +0,0 @@
-# ProAgents Commands for ChatGPT / Codex
-
-This project uses ProAgents - an AI-agnostic development workflow framework.
-
-## ⚠️ MANDATORY: Every pa: Command Flow
-
-### BEFORE Any pa: Command (Auto-Sync)
-
-**Read these files FIRST before doing anything:**
-
-```bash
-cat .proagents/worklog/_context.md      # Current state
-cat .proagents/changelog/_recent.md     # Recent changes
-tail -10 .proagents/activity.log        # Recent activity
-```
-
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
-
-### AFTER Any pa: Command (Auto-Log)
-
-**After EVERY file edit, IMMEDIATELY update these files:**
-
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
-
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
-
-## Essential Commands
-
-| Command | Action |
-|---------|--------|
-| `pa:feature "name"` | Start new feature workflow |
-| `pa:fix "bug"` | Quick bug fix mode |
-| `pa:doc` | Documentation options |
-| `pa:qa` | Quality assurance checks |
-| `pa:test` | Run test workflow |
-| `pa:deploy` | Deployment preparation |
-| `pa:status` | Show current progress |
-
-## Full Command Reference
-
-For complete command list, see: `./.proagents/AI_INSTRUCTIONS.md`
-
-## On `pa:` Command
-
-1. Read the corresponding file from `./.proagents/prompts/` or `./.proagents/workflow-modes/`
-2. Follow the workflow instructions
-3. Use project config from `./.proagents/proagents.config.yaml`
-
-## Key Files
-
-- `./.proagents/AI_INSTRUCTIONS.md` - Complete command reference
-- `./.proagents/WORKFLOW.md` - Full 10-phase workflow
-- `./.proagents/prompts/` - Phase-specific prompts

package/.proagents/GROQ.md

@@ -1,55 +0,0 @@
-# ProAgents Commands for Groq
-
-This project uses ProAgents - an AI-agnostic development workflow framework.
-
-## ⚠️ MANDATORY: Every pa: Command Flow
-
-### BEFORE Any pa: Command (Auto-Sync)
-
-**Read these files FIRST before doing anything:**
-
-```bash
-cat .proagents/worklog/_context.md      # Current state
-cat .proagents/changelog/_recent.md     # Recent changes
-tail -10 .proagents/activity.log        # Recent activity
-```
-
-**This applies to EVERY command:** `pa:fix`, `pa:feature`, `pa:test`, `pa:doc`, etc.
-
-### AFTER Any pa: Command (Auto-Log)
-
-**After EVERY file edit, IMMEDIATELY update these files:**
-
-1. `.proagents/changelog/_recent.md` - Prepend change summary
-2. `.proagents/changelog/modules/[module].md` - Based on file path
-3. `.proagents/worklog/_context.md` - Update current state
-
-Module detection: `src/api/*`→api, `src/auth/*`→auth, `src/components/*`→ui
-
-## Essential Commands
-
-| Command | Action |
-|---------|--------|
-| `pa:feature "name"` | Start new feature workflow |
-| `pa:fix "bug"` | Quick bug fix mode |
-| `pa:doc` | Documentation options |
-| `pa:qa` | Quality assurance checks |
-| `pa:test` | Run test workflow |
-| `pa:deploy` | Deployment preparation |
-| `pa:status` | Show current progress |
-
-## Full Command Reference
-
-For complete command list, see: `./.proagents/AI_INSTRUCTIONS.md`
-
-## On `pa:` Command
-
-1. Read the corresponding file from `./.proagents/prompts/` or `./.proagents/workflow-modes/`
-2. Follow the workflow instructions
-3. Use project config from `./.proagents/proagents.config.yaml`
-
-## Key Files
-
-- `./.proagents/AI_INSTRUCTIONS.md` - Complete command reference
-- `./.proagents/WORKFLOW.md` - Full 10-phase workflow
-- `./.proagents/prompts/` - Phase-specific prompts