proagents 1.6.19 → 1.6.20

package/.proagents/prompts/ai-add.md

@@ -0,0 +1,80 @@
+# pa:ai-add - Add AI Platform
+
+Add a new AI platform configuration to this project.
+
+## Steps
+
+### 1. Read Available Platforms
+
+**IMPORTANT:** Always read the authoritative list first - do not hallucinate platforms.
+
+```bash
+cat .proagents/platforms.yaml
+```
+
+### 2. Show Options to User
+
+Display platforms grouped by category:
+
+```
+IDE-based AI Assistants:
+  1. claude    - Claude Code (CLAUDE.md)
+  2. cursor    - Cursor (.cursorrules)
+  3. windsurf  - Windsurf (.windsurfrules)
+  4. copilot   - GitHub Copilot (.github/copilot-instructions.md)
+  5. kiro      - AWS Kiro (KIRO.md)
+  6. gemini    - Gemini (GEMINI.md)
+
+Web-based AI Platforms:
+  7. replit    - Replit AI (REPLIT.md)
+  8. bolt      - Bolt.new (BOLT.md)
+  9. lovable   - Lovable (LOVABLE.md)
+
+Auto-handled (use AGENTS.md):
+  - ChatGPT, Groq, Antigravity, Codex CLI, OpenAI API
+
+Which platform to add?
+```
+
+### 3. Create the File
+
+After user selects platform:
+
+1. **Read source template** from `.proagents/{file}`
+2. **Check if target file exists** in project root:
+   - If exists: Merge using markers (append ProAgents section)
+   - If not exists: Create new file with markers
+
+3. **Wrap content with markers:**
+   ```
+   <!-- PROAGENTS_START -->
+   {content from template}
+   <!-- PROAGENTS_END -->
+   ```
+
+### 4. Update Config
+
+Add platform to `ai_platforms` array in `./proagents.config.yaml`:
+
+```yaml
+ai_platforms:
+  - claude
+  - cursor
+  - {new_platform}  # Add this
+```
+
+### 5. Confirm
+
+```
+Added {platform_name}!
+  File: {file_path}
+  Config updated: ./proagents.config.yaml
+```
+
+## Merge Rules
+
+When target file already exists:
+
+1. **Has PROAGENTS markers:** Update content between markers only
+2. **No markers:** Append ProAgents section at end with markers
+3. **Never overwrite** user's existing configuration

package/.proagents/prompts/ai-list.md

@@ -0,0 +1,41 @@
+# pa:ai-list - List AI Platforms
+
+Show which AI platforms are configured for this project.
+
+## Steps
+
+1. **Read config file:**
+   ```bash
+   cat ./proagents.config.yaml
+   ```
+
+2. **Extract `ai_platforms` array** from the config
+
+3. **Display installed platforms:**
+   ```
+   Installed AI Platforms:
+   - Claude Code (CLAUDE.md)
+   - Cursor (.cursorrules)
+   - ...
+   ```
+
+4. **Show available platforms** (not yet installed):
+   - Read `.proagents/platforms.yaml` for full list
+   - Compare with installed list
+   - Show what can be added
+
+## Output Format
+
+```
+Installed AI Platforms:
+  [x] claude - Claude Code
+  [x] cursor - Cursor
+
+Available to Add:
+  [ ] windsurf - Windsurf
+  [ ] copilot - GitHub Copilot
+  [ ] gemini - Gemini
+  ...
+
+Use pa:ai-add to add more platforms.
+```

package/.proagents/prompts/ai-remove.md

@@ -0,0 +1,112 @@
+# pa:ai-remove - Remove AI Platform
+
+Remove an AI platform configuration from this project.
+
+## Steps
+
+### 1. Show Installed Platforms
+
+Read config and show what's installed:
+
+```bash
+cat ./proagents.config.yaml
+```
+
+Display:
+```
+Installed AI Platforms:
+  1. claude  - Claude Code (CLAUDE.md)
+  2. cursor  - Cursor (.cursorrules)
+
+Which platform to remove?
+```
+
+### 2. Locate the File
+
+Get file path from `.proagents/platforms.yaml`:
+- claude → `CLAUDE.md`
+- cursor → `.cursorrules`
+- copilot → `.github/copilot-instructions.md`
+- etc.
+
+### 3. Remove ProAgents Content
+
+**CRITICAL: Follow these rules carefully to avoid deleting user's config.**
+
+#### Step 3a: Check for Markers
+
+Look for these markers in the file:
+```
+<!-- PROAGENTS_START -->
+...content...
+<!-- PROAGENTS_END -->
+```
+
+#### Step 3b: If Markers Found
+
+1. Remove ONLY the content between markers (including the markers)
+2. Keep ALL other content in the file
+3. Clean up extra blank lines
+4. If file is empty after removal → delete the file
+5. If file has remaining content → keep the file
+
+**Example:**
+```
+# My Custom Rules        ← KEEP
+Some user config         ← KEEP
+
+<!-- PROAGENTS_START --> ← REMOVE
+ProAgents content...     ← REMOVE
+<!-- PROAGENTS_END -->   ← REMOVE
+
+# More user config       ← KEEP
+```
+
+#### Step 3c: If NO Markers Found
+
+**DO NOT DELETE THE FILE.**
+
+The file may contain user's own configuration that predates ProAgents or was manually edited.
+
+Action:
+1. Warn user: "No ProAgents markers found in {file}"
+2. Suggest: "Manual cleanup may be needed"
+3. Skip file removal
+4. Still update config (step 4)
+
+### 4. Update Config
+
+Remove platform from `ai_platforms` in `./proagents.config.yaml`:
+
+```yaml
+ai_platforms:
+  - claude
+  # - cursor  ← removed
+```
+
+### 5. Confirm
+
+Success cases:
+```
+Removed {platform}:
+  - Deleted: {file}  (file only had ProAgents content)
+  OR
+  - Cleaned: {file}  (kept your custom config)
+```
+
+Skip case:
+```
+Skipped {platform}:
+  - No ProAgents markers in {file}
+  - Manual cleanup may be needed
+  - Config updated anyway
+```
+
+## Safety Summary
+
+| Scenario | Action |
+|----------|--------|
+| File has markers, only ProAgents content | Delete file |
+| File has markers + user content | Remove markers section, keep rest |
+| File has no markers | **SKIP - don't delete** |
+| File doesn't exist | Skip silently |

package/.proagents/prompts/ai-sync.md

@@ -0,0 +1,96 @@
+# pa:ai-sync - Sync AI Platform Config
+
+Synchronize the config file with actual AI instruction files (fix mismatches).
+
+## When to Use
+
+- After manually adding/removing AI files
+- When config is out of sync with files
+- To detect and fix inconsistencies
+
+## Steps
+
+### 1. Read Current Config
+
+```bash
+cat ./proagents.config.yaml
+```
+
+Extract `ai_platforms` array.
+
+### 2. Read Platform Definitions
+
+```bash
+cat .proagents/platforms.yaml
+```
+
+### 3. Scan for Existing Files
+
+Check project root for each platform's file:
+
+| Platform | File to Check |
+|----------|---------------|
+| claude | `CLAUDE.md` |
+| cursor | `.cursorrules` |
+| windsurf | `.windsurfrules` |
+| copilot | `.github/copilot-instructions.md` |
+| kiro | `KIRO.md` |
+| gemini | `GEMINI.md` |
+| replit | `REPLIT.md` |
+| bolt | `BOLT.md` |
+| lovable | `LOVABLE.md` |
+
+### 4. Compare and Report
+
+```
+AI Platform Sync Status:
+
+In Config + File Exists:
+  [x] claude  - CLAUDE.md
+  [x] cursor  - .cursorrules
+
+In Config but File Missing:
+  [!] windsurf - .windsurfrules NOT FOUND
+
+File Exists but Not in Config:
+  [?] gemini - GEMINI.md exists
+
+Actions needed:
+  1. Add windsurf file OR remove from config
+  2. Add gemini to config OR delete file
+```
+
+### 5. Ask User for Action
+
+For each mismatch:
+
+**File missing:**
+```
+windsurf is in config but file doesn't exist.
+  1. Create the file (copy from .proagents/)
+  2. Remove from config
+```
+
+**File exists but not in config:**
+```
+GEMINI.md exists but gemini not in config.
+  1. Add to config
+  2. Delete the file
+```
+
+### 6. Apply Fixes
+
+Based on user choice:
+- Create missing files (use `pa:ai-add` logic)
+- Remove orphaned entries from config
+- Add discovered platforms to config
+- Delete orphaned files (use `pa:ai-remove` logic)
+
+### 7. Confirm
+
+```
+Sync complete!
+  - Added: gemini to config
+  - Created: .windsurfrules
+  - Removed: kiro from config (file was missing)
+```

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.19",
+  "version": "1.6.20",
   "description": "AI-agnostic development workflow framework that automates the full software development lifecycle",
   "type": "module",
   "main": "lib/index.js",